V7.0-000 supports database files with up to 16Gi blocks, For example, the maximum size of a V7 database file having 8KiB block size is 128 TiB (8KiB * 16Gi) which means, using multiple regions, it is easier to manage petabyte storage capacity. V7.0-000 includes support for operation with V6 database file format used by recent GT.M versions.

V7.0-000 also includes other fixes and enhancements including changes aimed a making management of replication more straightforward. For more information, refer to the Change History section.

Items marked with document new or different capabilities.

Please pay special attention to the items marked with the symbols as those document items that have a possible impact on existing code, practice or process. Please be sure to recompile all objects to ensure all the updates are in place.

	Note
	Messages are not part of the GT.M API whose stability we strive to maintain. Make sure that you review any automated scripting that parses GT.M messages.

This document uses the following conventions:

	Note
	The term UNIX refers to the general sense of all platforms on which GT.M uses a POSIX API. As of this date, this includes: AIX and GNU/Linux on x86 (32- and 64-bits).

The following table summarizes the new and revised replication terminology and qualifiers.

Effective V6.0-000, GT.M documentation adopted IEC standard Prefixes for binary multiples. This document therefore uses prefixes Ki, Mi and Ti (e.g., 1MiB for 1,048,576 bytes). Over time, we'll update all GT.M documentation to this standard.

denotes a new feature that requires updating the manuals.

denotes a new feature or an enhancement that may not be upward compatible and may affect an existing application.

denotes deprecated messages.

denotes revised messages.

denotes added messages.

Over time, computing platforms evolve. Vendors obsolete hardware architectures. New versions of operating systems replace old ones. We at FIS continually evaluate platforms and versions of platforms that should be Supported for GT.M. In the table below, we document not only the ones that are currently Supported for this release, but also alert you to our future plans given the evolution of computing platforms. If you are an FIS customer, and these plans would cause you hardship, please contact your FIS account executive promptly to discuss your needs.

Each GT.M release is extensively tested by FIS on a set of specific versions of operating systems on specific hardware architectures (the combination of operating system and hardware architecture is referred to as a platform). This set of specific versions is considered Supported. There may be other versions of the same operating systems on which a GT.M release may not have been tested, but on which the FIS GT.M Group knows of no reason why GT.M would not work. This larger set of versions is considered Supportable. There is an even larger set of platforms on which GT.M may well run satisfactorily, but where the FIS GT.M team lacks the knowledge to determine whether GT.M is Supportable. These are considered Unsupported. Contact FIS GT.M Support with inquiries about your preferred platform.

As of the publication date, FIS supports this release on the hardware and operating system versions below. Contact FIS for a current list of Supported platforms. The reference implementation of the encryption plugin has its own additional requirements, should you opt to use it as included with GT.M.

Note

Debian 10 (buster) x86 GNU/Linux is Supportable but not Supported. The 32-bit version of GT.M runs on either 32- or 64-bit x86 platforms; we expect the x86_64 GNU/Linux version of GT.M to be preferable on 64-bit hardware. Running a 32-bit GT.M on a 64-bit GNU/Linux requires 32-bit libraries to be installed. The CPU must have an instruction set equivalent to 586 (Pentium) or better. If you are using the 32-bit GT.M, please also refer to the notes above on x86_64 GNU/Linux.

The same application code runs on both 32-bit and 64-bit platforms; however there are operational differences between them (for example, auto-relink and the ability to use GT.M object code from shared libraries exist only on 64-bit platforms). Please note that:

Call-ins and External Calls

Parameter type	32-Bit	64-bit	Remarks
gtm_long_t	4-byte (32-bit)	8-byte (64-bit)	gtm_long_t is much the same as the C language long type.
gtm_ulong_t	4-byte	8-byte	gtm_ulong_t is much the same as the C language unsigned long type.
gtm_int_t	4-byte	4-byte	gtm_int_t has 32-bit length on all platforms.
gtm_uint_t	4-byte	4-byte	gtm_uint_t has 32-bit length on all platforms

	Caution
	If your interface uses gtm_long_t or gtm_ulong_t types but your interface code uses int or signed int types, failure to revise the types so they match on a 64-bit platform will cause the code to fail in unpleasant, potentially dangerous, and hard to diagnose ways.

Internationalization (Collation)

Parameter type	32-Bit	64-bit	Remarks
gtm_descriptor in gtm_descript.h	4-byte	8-byte	Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

	Important
	Assuming other aspects of code are 64-bit capable, collation routines should require only recompilation.

Environment Translation

Parameter type	32-Bit	64-bit	Remarks
gtm_string_t type in gtmxc_types.h	4-byte	8-byte	Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

	Important
	Assuming other aspects of code are 64-bit capable, environment translation routines should require only recompilation.

To install GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide. For minimal down time, upgrade a current replicating instance and restart replication. Once that replicating instance is current, switch it to become the originating instance. Upgrade the prior originating instance to become a replicating instance, and perform a switchover when you want it to resume an originating primary role.

	Caution
	Never replace the binary image on disk of any executable file while it is in use by an active process. It may lead to unpredictable results. Depending on the operating system, these results include but are not limited to denial of service (that is, system lockup) and damage to files that these processes have open (that is, database structural damage).

There are two upgrade paths available when you upgrade to GT.M V7.0-000:

Choose V7 Upgrade Path 1 if you anticipate a database file to grow up to 16Gi blocks. Note that the maximum size of a V7 database file having 8KiB block size is 114688GiB (8KiB*16Gi).

Choose V7 Upgrade Path 2 if you do not anticipate a database file to grow beyond the V6 database limit of 994Mi blocks. Note that the maximum size of a V6 database file having 8KiB block size is 7936GiB (8KiB*992Mi).

Other that the new maximum database file size that comes with V7 Upgrade Path 1, there is no difference between V7 Upgrade Path 1 and V7 Upgrade Path 2. You can choose V7 Upgrade Path 2 first and then later choose V7 Upgrade Path 1 if a need arises.

	Note
	To upgrade your database from V5 to V7, you need to first upgrade your database from V5 to a V6 database and then choose an appropriate V7 upgrade path. Refer to the appropriate V6 release notes for the database upgrade instructions or consult your GT.M support channel.

	Important
	In an upcoming release, the FIS GT.M team plans to provide in-place database upgrade with minimal downtime.

With International Components for Unicode (ICU) version 3.6 or later installed, GT.M's UTF-8 mode provides support for Unicode® (ISO/IEC-10646) character strings. On a system that does not have ICU 3.6 or later installed, GT.M only supports M mode.

On a system that has ICU installed, GT.M optionally installs support for both M mode and UTF-8 mode, including a utf8 subdirectory of the directory where GT.M is installed. From the same source file, depending upon the value of the environment variable gtm_chset, the GT.M compiler generates an object file either for M mode or UTF-8 mode. GT.M generates a new object file when it finds both a source and an object file, and the object predates the source file and was generated with the same setting of $gtm_chset/$ZCHset. A GT.M process generates an error if it encounters an object file generated with a different setting of $gtm_chset/$ZCHset than that processes' current value.

Always generate an M object module with a value of $gtm_chset/$ZCHset matching the value processes executing that module will have. As the GT.M installation itself contains utility programs written in M, their object files also conform to this rule. In order to use utility programs in both M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 versions of object modules exist, the latter in the utf8 subdirectory. This technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use. If your installation uses both modes, consider a similar pattern for structuring application object code repositories.

GT.M is installed in a parent directory and a utf8 subdirectory as follows:

For more information on gtmprofile, refer to the Basic Operations chapter of GT.M Administration and Operations Guide.

Although GT.M uses ICU for UTF-8 operation, ICU is not FIS software and FIS does not support ICU.

The environment variable TERM must specify a terminfo entry that accurately matches the terminal (or terminal emulator) settings. Refer to the terminfo man pages for more information on the terminal settings of the platform where GT.M needs to run.

GT.M sends keypad_xmit before terminal reads for direct mode and READs (other than READ *) if EDITING is enabled. GT.M sends keypad_local after these terminal reads.

If you plan to use the optional compression facility for replication, you must provide the compression library. The GT.M interface for compression libraries accepts the zlib compression libraries without any need for adaptation. These libraries are included in many UNIX distributions and are downloadable from the zlib home page. If you prefer to use other compression libraries, you need to configure or adapt them to provide the same API as that provided by zlib.

If a package for zlib is available with your operating system, FIS suggests that you use it rather than building your own.

By default, GT.M searches for the libz.so shared library in the standard system library directories (for example, /usr/lib, /usr/local/lib, /usr/local/lib64). If the shared library is installed in a non-standard location, before starting replication, you must ensure that the environment variable LIBPATH (AIX) or LD_LIBRARY_PATH (GNU/Linux) includes the directory containing the library. The Source and Receiver Server link the shared library at runtime. If this fails for any reason (such as file not found, or insufficient authorization), the replication logic logs a DLLNOOPEN error and continues with no compression.

Although GT.M uses a library such as zlib for compression, such libraries are not FIS software and FIS does not support any compression libraries.

Fixes and enhancements specific to V7.0-000:

Here are some examples of the new gtmsource_local_struct.heartbeat_jnl_seqno ^%PEEKBYNAME field.

This routine returns the replication speed, that is the number of seqno updates per second acknowledged by the replicating instance during heartbeat intervals.

Example:

replspeed
  ; This routine returns the replication speed, that is the number of seqno updates per second acknowledged by the replicating instance during the heartbeat intervals.
  ; Usage: $gtm_exe/mumps -r ^replspeed INSTANCE3 20
  ; The second parameter is the sampling size
  set $etrap="write ""REPLSPEED-E-ACKSMPL : unable to fetch sampling data due to "",$zstatus  halt  "
  set $ztimeout="300:write ""Timeout occurred out after 5 minutes"",! zwrite  halt"
  new hrtbtperiod,instance,samplingsize,hrtbts,slot,i,hrtbtdiffs,diff,dump
  set instance=$piece($zcmdline," ",1),slot=0
  set samplingsize=$piece($zcmdline," ",2),hrtbtdiffs=0
  set:$length(samplingsize)=0 samplingsize=10
  if '($length(instance)) write "REPLSPEED-E-ARGS : ",$zcmdline," was specified. This routine requires specifying an instance name.",! halt
  for i=0:1:15 set instname=$$^%PEEKBYNAME("gtmsource_local_struct.secondary_instname",i),instname=$piece(instname,$char(0),1) set:(instname=instance) slot=i
  ; capture heartbeat_jnl_seqno samplingsize times. Wait for hrtbtperiod after every capture of heartbeat_jnl_seqno
  set hrtbtperiod=$piece($$^%PEEKBYNAME("gtmsource_local_struct.connect_parms",slot),",",5)
  for j=1:1:samplingsize do
  . set hrtbts(j)=$$^%PEEKBYNAME("gtmsource_local_struct.heartbeat_jnl_seqno",slot,"I")
  . do:(j>1)
  . . set diff=hrtbts(j)-hrtbts(j-1)
  . . do:(diff<0)
  . . . write "REPLSPEED-E-ACKSEQNO : acknowledgement sequence number received is lower than previous acknowledgement seqno."
  . . . set dump="replspeed.dump" open dump use dump zwrite hrtbts  close dump
  . . . halt
  . . set hrtbtdiffs=hrtbtdiffs+diff
  . hang hrtbtperiod
  set hrtbtdiffs=hrtbtdiffs/samplingsize
  write $justify(hrtbtdiffs/hrtbtperiod,0,0)
  quit

Use the following example confirm that an update corresponding to a Source Server sequence number has reached the Receiver Pool. This can be used as a tool to help confirm that there are no in-flight updates.

Example:

waitforhrtbt
  ; This routine returns 0 when the acknowledged seqno from the specified instance matches or exceeds the specified seqno
  ; If there is no confirmation (network issues etc) from the Receiver Server for 300 seconds, this routines returns 1.
  ; Usage: $gtm_exe/mumps -r ^waitforhrtbt <instname> <seqnocheckpoint>
  set $etrap="write ""WAITFORHRTBT-E-ERROR, Error occurred while waiting for ackseqno confirmation due to "",$zstatus  halt  "
  new heartbeatseqno,hangduration,instance,checkseqno,i,instname,slot
  ; set $ztimeout to align with the REPLALERT threshold for the test system
  set $ztimeout="900:write 1 halt"
  set hangduration=1,slot=""
  set instance=$piece($zcmdline," ",1)
  set checkseqno=$piece($zcmdline," ",2)
  if '($length(instance)&$length(checkseqno)) write "WAITFORHRTBT-E-ARGS : ",$zcmdline," was specified. This routine requires specifying instance name and seqno.",! halt
  for i=0:1:15 set instname=$$^%PEEKBYNAME("gtmsource_local_struct.secondary_instname",i),instname=$piece(instname,$char(0),1) set:(instname=instance) slot=i
  if '($length(slot)) write "WAITFORHRTBT-E-INSTNOMATCH : No matching instance name for ",instance,! halt
  for  do
  . set heartbeatseqno=$$^%PEEKBYNAME("gtmsource_local_struct.heartbeat_jnl_seqno",slot,"I")-1
  . if (heartbeatseqno>=checkseqno) write 0 halt
  . hang hangduration
  quit

Example:

waitforseqnosync
  ; This routine returns 0 when there the sequence numbers of the Source Server and the acknowledged sequence number from the Receiver Server is the same.
  ; It returns a non-zero value when there is no confirmation of the receipt of the latest seqno from the secondary even when there is no backlog.
  ; If there is no confirmation (network issues etc) from the Receiver Server for 150 seconds, this routines returns 1.
  ; Usage: $gtm_exe/mumps -r ^waitforseqnosync <instname>
  set $etrap="write ""WAITFORSEQNOSYNC-E-SRCBACKLOG : unable to get current Source Server backlog and seqno updates status due to "",$zstatus  halt  "
  new readseqno,heartbeatseqno,instance,i,instname,slot,hrtbtperiod
  set $ztimeout="150:write 1 halt"
  set slot=""
  ; hrtbtperiod: the heartbeat period (the fifth parameter of -CONNECTPARAMS)
  set instance=$zcmdline
  if '$length(instance) write "WAITFORSEQNOSYNC-E-ARGS : This routine requires specifying an instance name.",! halt
  for i=0:1:15 set instname=$$^%PEEKBYNAME("gtmsource_local_struct.secondary_instname",i),instname=$piece(instname,$char(0),1) set:(instname=instance) slot=i
  if '($length(slot)) write "WAITFORSEQNOSYNC-E-INSTNOMATCH : No matching instance name for ",instance halt
  set hrtbtperiod=$piece($$^%PEEKBYNAME("gtmsource_local_struct.connect_parms",slot),",",5)
  for  do
  . set seqno=$$^%PEEKBYNAME("jnlpool_ctl_struct.jnl_seqno","","I")
  . set readseqno=$$^%PEEKBYNAME("gtmsource_local_struct.read_jnl_seqno",i,"I")
  . set heartbeatseqno=$$^%PEEKBYNAME("gtmsource_local_struct.heartbeat_jnl_seqno",i,"I")
  . if (seqno=readseqno=heartbeatseqno) write 0 halt
  . hang hrtbtperiod
  quit

BOVTMGTEOVTM, Journal file xxxx has beginning timestamp aaaa greater than end timestamp bbbb

MUPIP Error: This indicates that the beginning time stamp aaaa of the journal file xxxx is greater than the ending timestamp bbbb. This could be due to something that changed the system time,such as a daylight savings time change or a testing time reset, while GT.M was journaling. FIS recommends against changing system time during GT.M Run-time as a matter of course, as this disruption is not heavily tested.

Action: Confirm the reason for the time shift and decide whether to continue processing the affected journal files.

DBADDRANGE, Database file rrrr element location aaaa: control vvvv was outside qqqq range bbbb to tttt

Run Time Information: This indicates a database control structure for database region rrrr at memory location aaaa contains a value vvvv outside range bbbb to tttt for quantity qqqq.

Action: This typically indicates a process terminated abnormally while updating the database. GT.M often fixes such an error unless there is a serious problem causing this error. If GT.M cannot correct the issue, the accompanying messages should expand on the situation; and you should report such database error to the group responsible for database integrity at your operation.

DBADDRANGE8, Database file rrrr element location aaaa: control vvvv was outside qqqq range bbbb to tttt

Run Time Error: This indicates a database control structure for database region rrrr at memory location aaaa contains a value vvvv outside range bbbb to tttt for quantity qqqq.This message is the same as a DBADDRANGE message except that vvvv, bbbb and tttt are 8-byte quantities (as opposed to 4-byte quantitites in DBADDRANGE).

Action: This typically indicates a process terminated abnormally while updating the database. GT.M often fixes such an error unless there is a serious problem causing this error. If GT.M cannot correct the issue, the accompanying messages should expand on the situation; and you should report such database error to the group responsible for database integrity at your operation.

GTMCURUNSUPP, The requested operation is unsupported in this version of GT.M

All GT.M Components Error: GT.M tried to perform an operation that is unsupported in the current version. Currently this is only thrown by GT.M when trying to perform an upgrade/downgrade operation.

Action: GT.M does not currently support upgrade/downgrade between V6 and V7 databases. This feature will be added in a future release.

HEX64ERR, Error: cannot convert VVVV value to 64 bit hexadecimal number

All GT.M Components Error: The entered value does not correspond to a valid hexadecimal number representable in no more than 64 binary digits.

Action: Enter an appropriate hexadecimal value starting with 0X, using decimal integers 0-9 and ASCII letters A-F.

HEXERR, Error: cannot convert VVVV value to hexadecimal number

All GT.M Components Error: The entered value does not correspond to a valid hexadecimal number.

Action: Enter an appropriate hexadecimal value starting with 0X, using decimal integers 0-9 and ASCII letters A-F.

INVSHUTDOWN, Shutdown timeout should be from 0 to 3600 seconds

MUPIP Error: This error appears when the -TIMEOUT specified with -SOURCE -SHUTDOWN exceeds 3600 seconds (1 hour).

Action: Specify -TIMEOUT between 0 to 3600 seconds

NUM64ERR, Error: cannot convert VVVV value to 64 bit decimal or hexadecimal number

All GT.M Components Error: The entered value does not correspond to a valid decimal number or hexadecimal number representable in no more than 64 binary digits.

Action: Enter an appropriate decimal value or hexadecimal value starting with 0X, and using decimal integers 0-9 and ASCII letters A-F.

NUMERR, Error: cannot convert VVVV value to 64 bit decimal or hexadecimal number

All GT.M Components Error: The entered value does not correspond to a valid decimal number or hexadecimal number.

Action: Enter an appropriate decimal value or hexadecimal value starting with 0X, and using decimal integers 0-9 and ASCII letters A-F.

REPL0BACKLOG, Total backlog for the specified replicating instance(s) is 0

MUPIP Success: This message indicates a successful -ZEROBACKLOG -SHUTDOWN. It means that was no backlog for the specified replicating instance(s), no inflight updates, and all updates were successfully acknowledged by the Receiver Server.

Action: None.

REPLBACKLOG, Timeout occurred while there was a backlog

MUPIP Error: This error occurs when the -TIMEOUT specified with -SOURCE -ZEROBACKLOG -SHUTDOWN expires and there is a either a backlog and/or there was a failure to receive an acknowledment of the latest sequence number on the Source Server by the Receiver Server. If REPLNORESP also accompanies this error, it means that the Source Server did not receive a response from the Receiver Server for acknowledgement sequence number confirmation.

Action: This error means that the -ZEROBACKLOG checks did not pass. Restart the Source Server to clear any backlog. The presence of REPL0BACKLOG success message for -ZEROBACKLOG -SHUTDOWN confirms that there are no inflight updates and all updates are acknowledged by the Receiver Server.

REPLNORESP, No sequence number confirmation from the replicating instance xxxx after waiting for nnnn second(s)

MUPIP Warning: This message appears when the Source Server fails to receive a response from the Receiver Server during a -ZEROBACKLOG -SHUTDOWN. The presence of a REPLNORESP indicates that a -ZEROBACKLOG -SHUTDOWN check failed. This warning is accompanied by the REPLBACKLOG error message.

Action: This warning means that the -ZEROBACKLOG checks did not pass. Restart the Source Server to clear any backlog. The presence of REPL0BACKLOG success message for -ZEROBACKLOG -SHUTDOWN confirms that there are no inflight updates and all updates are acknowledged by the Receiver Server.

SHUT2QUICK, Shutdown timeout ssss shorter than the heartbeat period SSSS; cannot confirm the backlog at the replicating instance iiii

MUPIP Warning: This warning appears when the -TIMEOUT=ssss specified with -ZEROBACKLOG is less than the heartbeat period SSSS (the fifth parameter of -CONNECTPARAMS). If -TIMEOUT is less than the heartbeat period, -ZEROBACKLOG cannot confirm that there is zero backlog as it cannot obtain the acknowledgement of the latest sequence number from the Receiver Server of instance iiii in such a short time.

Action: Specify -TIMEOUT that is larger or equal to the heartbeat period.

UNUM64ERR, Error: cannot convert VVVV value to 64 bit unsigned decimal or hexadecimal number

All GT.M Components Error: The entered value does not correspond to a valid unsigned decimal number or hexadecimal number representable in no more than 64 binary digits.

Action: Enter an appropriate decimal value or hexadecimal value starting with 0X, and using decimal integers 0-9 and ASCII letters A-F.

VIEWREGLIST, $VIEW() only handles the first region subparameter

Run Time Warning: $VIEW() with a region subparameter only operates on a single region. This differs from the VIEW command which has similar arguments and accepts region-lists for regions. This error is a warning and the function attempts to act on the first region.

Action: If the requirement is for multiple regions, use multiple $VIEW() invocations, perhaps in a loop.

WCSFLUFAIL, Error flushing buffers -- called from module MMMM at line LLLL

All GT.M Components Error: This indicates that an attempt to flush a buffer to disk failed.

Action: If the error persists, report this database error to the group responsible for database integrity at your operation.