Technical Bulletin - GT.M V5.4-001 Release Notes

Copyright © 2010 Fidelity Information Services, Inc.  All Rights Reserved. 

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.


GT.M™ is a trademark of Fidelity Information Services, Inc.  Other trademarks are the property of their respective owners.  


This document contains a description of GT.M and the operating instructions pertaining to the various functions that comprise the system. This document does not contain any commitment of FIS.  FIS believes the information in this publication is accurate as of its publication date; such information is subject to change without notice.  FIS is not responsible for any errors or defects. 

Revision History

Version Date               
1.8 July 1, 2011 Improved the writeup of C9K06-003286.
1.7 February 18, 2011 In Compiling ICU, corrected the link to Appendix C: Compiling ICU on GT.M supported platforms of the UNIX GT.M Administration and Operations Guide.
1.6 February 8, 2011 Added an entry for S9K05-002770.
1.5 November 15, 2010 In Table of Contents, fixed a broken link to the Change History section.
1.4 August 16, 2010 In the Platforms section, added a note about the unsupported NFS mounted database and journal files.
1.3 August 10, 2010 In the Platforms section, corrected the minimum supported library versions of glibc and ncurses for RHEL 5.5.
1.2 July 30, 2010 In the Platforms section, changed the SuSE supported version for IBM System z Linux and added an accompanying note.
July 12, 2010
Miscellaneous cleanup of vocabulary and grammar.

Improved the writeup of C9K03-003248.

Removed the following gtmprofile fix in C9K06-003276 that did not make it to the build of GT.M V5.4-001 due to a packaging error. It will now be made available in the next GT.M release.
The environment variable $LC_CTYPE is not specified when the $gtm_chset environment variable specifies that GT.M is to run in UTF-8 mode, the gtmprofile script now defaults $LC_CTYPE to the first UTF-8 locale.  Previously, any upper case U, T, and F characters in that first UTF-8 locale name were incorrectly converted to lower case.

This fix has no impact on M mode operations of the gtmprofile script. If you are an FIS GT.M support customer and use gtmprofile in UTF-8 mode, please contact your GT.M support channel to obtain this fix.

1.0 July 6, 2010 First published version.


GT.M Group

Fidelity Information Services, Inc.

2 West Liberty Boulevard, Suite 300

Malvern, Pennsylvania 19355

United States of America


GT.M Support for customers: +1 (610) 578-4226 /


Switchboard: +1 (610) 296-8877



Table of Contents

Click here to go directly to the Change History section.




Command Syntax: UNIX syntax (that is, lowercase text and "-" for flags/qualifiers) is used throughout this document.  OpenVMS accepts both lowercase and uppercase text; flags/qualifiers on OpenVMS should be preceded with "/".

Program Names: When referring to a GT.M program or function, the reference is in upper case, e.g, MUPIP BACKUP.  When a specific example is provided, the lower case UNIX command names are used, e.g., mupip backup -database ACN,HIST /backup

Reference Number: Reference numbers used to track software enhancements and customer support requests appear in parentheses ().

Platform Identifier: If a new feature or software enhancement does not apply to all platforms, the relevant platform or platforms appear in brackets [].

In GT.M documentation, we're adopting the terms "originating instance" where we previously used "primary instance" or "originating primary instance," and the term "replicating instance" where we previously used "secondary instance" and "originating secondary instance."  Since it is easier to change documentation than it is to change software, and given our tradition of maintaining compatibility especially for existing programs and scripts, the former terms will remain in the software for a long time to come, even as they are supplemented with the new terms in the code, and replaced in the documentation.

Return to Table of Contents

Bulletin Overview

GT.M V5.4-001 introduces support for Linux on the IBM System z platform.

With this release, the GT.M trigger facility is suitable for production use. For trigger-related changes, see C9K02 Trigger Fixes.


There are of course numerous bug fixes, remedied mis-features and smaller enhancements.  For a comprehensive list, see Changes.   


As of the publication date, FIS supports this release on the following hardware and operating system versions.  Contact FIS for a current list of supported platforms.




Supported Versions


Hewlett-Packard Integrity IA64 HP-UX

11V3 (11.31)


IA64 GNU/Linux - Red Hat Enterprise Linux

Red Hat Enterprise Linux 5.3

GT.M should also run on recent releases of other major Linux distributions with a contemporary 2.6 Linux kernel, glibc (version 2.5-24 or later) and ncurses (version 5.5-24 or later).  We have verified that GT.M passes comprehensive testing on RHEL 5.x on machines that have single cells (no more than 8 CPUs).  Multi-cell machines are not considered suitable for production use until they are certified.

Hewlett-Packard PA-RISC HP-UX


GT.M supports UTF-8 mode and M mode on this platform subject to the following:

  • Problems with HP-UX 11.11 prevent FIS from testing 4 byte UTF-8 characters.  FIS understands that the issue is resolved in HP-UX 11.31.  At this time, HP-UX 11.31 is still untested and not formally supported for GT.M; however, we are aware of nothing that would prevent this GT.M release from working correctly on that newer version.

Running GT.M on HP-UX 11i requires that patch PHKL_28475 be applied to the system.  This patch fixes a problem with the lseek64() C library call that GT.M uses.  A system without this patch gives fairly consistent database errors of varying types, structural damage, and in general does not work correctly for any but the most simplistic usage.  The swlist -p command (executed as root) can be used to determine if this patch has been applied.  Since recent "BATCH" and "GOLDEN" patches may contain this patch, your system may already have this patch applied but may not list it separately. Contact your HP support channel for more information.

GT.M does not support database encryption on this platform.


GT.M does not support the Memory Mapped (MM) Access Method on this platform.

Although this platform remains at present fully supported with respect to bug fixes, owing to its looming sunset by the vendor, new functionality is supported on this platform only for FIS' convenience.  Please contact your FIS account manager regarding future support.

Hewlett-Packard Alpha/AXP Tru64 UNIX


GT.M supports M mode but not UTF-8 mode on this platform.  GT.M does not support database encryption on this platform.

Although this platform remains at present fully supported with respect to bug fixes, owing to its looming sunset by the vendor, new functionality is supported on this platform only for FIS' convenience.  Please contact your FIS account manager regarding future support.

Hewlett-Packard Alpha/AXP OpenVMS


GT.M supports M mode but not UTF-8 mode on this platform.  GT.M does not support several recent enhancements on this platform, including but not limited to database encryption, on-line backup, multi-site replication, PIPE devices and triggers.

If you need to work with external calls written in C with Version 6.x of the Compaq C compiler on Alpha OpenVMS, then you must carefully review all the provided kits for that product and apply them appropriately.

Although this platform remains at present fully supported with respect to bug fixes, owing to its looming sunset by the vendor, new functionality is supported on this platform only for FIS' convenience.  Please contact your FIS account manager regarding future support.

IBM System p AIX

5.3, 6.1

Since GT.M processes are 64-bit, FIS expects 64-bit AIX configurations to be preferable.

  • While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.  
IBM System z
SuSE Linux Enterprise Server 10.3 and 11 or later
GT.M supports starts at SuSE Linux Enterprise Server 10 Service Pack 3. On SuSE Linux Enterprise Server 11 or later, we require the installation of the SuSE provided libelf0-0.8.10-37.10, or later, package.
IBM System z z/OS V1R10 At this time, FIS is not providing a general distribution of GT.M for this platform.  Contact your FIS account executive if you need such a distribution.

Sun SPARC Solaris

9 (Update 3 and above) and 10 (Update 6 and above)

GT.M supports the deprecated DAL calls in M mode but not in UTF-8 mode.  Please refer to the Integrating External Routines chapter in the Programmer’s Guide for appropriate alternative solutions.

x86_64 GNU/Linux

Red Hat Enterprise Linux 5.4; Ubuntu 8.04 LTS through 10.04 LTS; SuSE Linux Enterprise Server 11

To run 64-bit GT.M processes requires both a 64-bit kernel as well as 64-bit hardware.


GT.M should also run on recent releases of other major Linux distributions with a contemporary 2.6 Linux kernel, glibc (version 2.5-24 or later) and ncurses (version 5.5 or later).


To install GT.M with Unicode (UTF-8) support on RHEL 5.4, in response to the installation question Should an ICU version other than the default be used? (y or n) please respond y and then specify the ICU version (e.g., respond 3.6) to the subsequent prompt Enter ICU version (at least ICU version 3.6 is required. Enter as <major-ver>.<minor-ver>):

x86 GNU/Linux

Red Hat Enterprise Linux 5.5

This 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.


GT.M should also run on recent releases of other major Linux distributions with a contemporary 2.6 Linux kernel, glibc (version 2.5-49 or later) and ncurses (version 5.5-24 or later).  The minimum CPU must have the instruction set of a 686 (Pentium Pro) or equivalent. Contact FIS for support of older CPUs.

Note: GT.M does not support database and journal files which reside on an NFS mounted filesystem. However, you can use an NFS mounted filesystem for keeping source and object code modules and performing sequential file IO.


Return to Table of Contents

Migrating to 64-bit platforms

The same application code runs on both 32-bit and 64-bit platforms. Please note that:

  • You must compile the application code separately for each platform.  Even though the M source code is exactly the same, the generated object modules are different even on the same hardware architecture - the object code for x86 and x86_64 is different.

  • Parameter-types that interface GT.M with non-M code using C calling conventions must match the data-types on their target platforms.  Mostly, these parameters are for call-ins, external calls, internationalization (collation), and environment translation and are listed in the tables below.  Note that most addresses on 64-bit platforms are 8 bytes long and require 8 byte alignment in structures whereas all addresses on 32-bit platforms are 4 bytes long and require 4-byte alignment in structures.

Call-ins and External Calls

Parameter type





4-byte (32-bit)

8-byte (64-bit)

gtm_long_t is much the same as the C language long type, except on Tru64 UNIX, where GT.M remains a 32-bit application.




gtm_ulong_t is much the same as the C language unsigned long type.




gtm_int_t has 32-bit length on all platforms.




gtm_uint_t has 32-bit length on all platforms

  • 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




gtm_descriptor in gtm_descript.h



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.

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

Environment Translation 

Parameter type




gtm_string_t type in gtmxc_types.h



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.

  • Any environment translation routines require only a recompile, assuming other aspects of their code are 64-bit capable.


Return to Table of Contents


  • Recompile all M and C source files.


Return to Table of Contents

Rebuild Shared Libraries or Images

  • Rebuild all Shared Libraries (UNIX) or Shareable Executable Images (OpenVMS) after recompiling all M and C source files.


Return to Table of Contents

Additional Installation Instructions 

To install GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide.


  1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version.  If you must overwrite an existing GT.M installation with a new version you must first shut down all processes using the old version.  FIS suggests installing GT.M V5.4-001 in a Filesystem Hierarchy Standard compliant location such as /usr/lib/fis-gtm/V5.4-001_arch (for example, /usr/lib/fis-gtm/V5.4-001_x86) on 32-bit Linux systems.  A location such as /opt/fis-gtm/V5.4-001_<arch> would also be appropriate.  Note that the arch suffix is especially important if you plan to install 32- and 64-bit versions of the same release of GT.M on the same system.
  2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

  3. In UNIX editions, make sure gtmsecshr is not running. If gtmsecshr is running, first stop all GT.M processes including the DSE, LKE and MUPIP utilities and then perform a MUPIP STOP <pid_of_gtmsecshr>.

  • 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 the denial of service (that is, system lockup) and damage to files that these processes open (that is, database structural damage).
Additional Information for AIX

GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. AIX 6 manages AIO dynamically (as requested). Before installing GT.M on IBM pSeries AIX of versions prior to AIX 6, run the following command to check the filesets of this facility: lslpp -l bos.rte.aio

If there are no filesets, then install them from AIX installation media.  Then, use SMIT to configure the Asynchronous IO facility.  Use SMIT as follows:

  • smit aio (for gui mode) or

  • smitty aio (for text mode)


For a system that has the "posixaio" option instead of "aio" (also called "legacy aio"), use SMIT as follows:

  • smit posixaio (for gui mode) or

  • smitty posixaio (for text mode)

Select "Configure AIO now".  If you see a message such as "aio0 has been created", it means that there is no further need of setup at this time.

In addition to configuring the aio0 device, select "Change/Show characteristics of Asynchronous I/O" change the value of "State to be configured at system restart" from "defined" to "available".  This ensures that the aio0 device will be available when you next reboot the system.

If you expect a database file or journal file to exceed 2GB with older versions of the JFS file system, then you must configure its file system to permit files larger than 2GB.  Furthermore, should you choose to place journal files on file systems with a 2GB limit, since GT.M journal files can grow to a maximum size of 4GB, you must then set the journal auto switch limit to less than 2 GB.


To upgrade from a GT.M version prior to V4.3-001, you must update any customized copy of GTM$DEFAULTS to include a definition for GTM$ZDATE_FORM.

You can ignore the following section if you choose the standard GT.M configuration or answer yes to the following question:

Do you want to define GT.M commands to the system

If you define GT.M commands locally with SET COMMAND GTM$DIST:GTMCOMMANDS.CLD in GTMLOGIN.COM or other command file for each process which uses GT.M, you must execute the same command after installing the new version of GT.M before using it.  If you define the GT.M commands to the system other than during the installation of GT.M, you must update the system DCLTABLES with the new GTMCOMMANDS.CLD provided with this version of GT.M.  See the OpenVMS "Command Definition, Librarian, and Message Utilities Manual" section on "Adding a system command."  In both cases, it is important for each process to match the proper GTMCOMMANDS.CLD with the version of GT.M it runs.

Return to Table of Contents

Upgrading to GT.M V5.4-001

The GT.M database consists of four types of components— database files, journal files, global directories, and replication instance files. The format of each database component may differ for each GT.M version and even for 32-bit/64-bit GT.M platforms on the same hardware architecture.

GT.M upgrade procedure for V5.4-001 consists of 4 stages:  


Read the upgrade instructions of each stage carefully. Your upgrade procedure for GT.M V5.4-000A depends on your GT.M upgrade history and your current version. 

Stage 1: Upgrading your Global Directory

FIS strongly recommends you make a copy of your Global Directory before upgrading it. There is no way to downgrade a Global Directory to an earlier format.  

To upgrade from any prior GT.M version:

  1. Open your Global Directory with the GDE utility program from GT.M V5.4-001.
  2. Run the EXIT command. This command automatically, even with no other intervening commands, upgrades the global directory.


If you inadvertently open a global directory in an earlier format, with no intention of upgrading it, execute the QUIT command rather than the EXIT command.


If you inadvertently upgrade a global directory, perform the following steps:
  1. Open the global directory with GDE from V5.4-001.
  2. Execute the SHOW ALL command.
Note: Create a GDE command script, or manually enter the GDE commands corresponding to the output, into GDE from the prior GT.M version.


Note: As global directories are binary files, analogous to object files, FIS recommends that you use a GDE command script to create your global directories.

Stage 2: Upgrading your Database Files  

You need to upgrade your database files only when there is a block format upgrade (such as V4->V5). However, some versions, for example, the ones which have been initially been created with V4 (and subsequently upgraded to a V5 format) may additionally need a MUPIP REORG -UPGRADE operation to upgrade previously used but free blocks that may have been missed by earlier upgrade tools. 


To upgrade from a GT.M version prior to V5.000:


  1. Upgrade your database files using in-place or traditional database upgrade procedure depending on your situation. For more information on in-place/traditional database upgrade, see Database Migration Technical Bulletin.
  1. Run the MUPIP REORG –UPGRADE command. This command upgrades all V4 block to V5 format.


Note: Databases created with GT.M releases prior to V5.0-000 and upgraded to a V5 format retain a maximum size limit of 64M (67,108,864) blocks.

To upgrade from GT.M V5.0*/V5.1*/V5.2*/V5.3*/V5.4*:

No database file upgrade procedure is necessary if you upgrade from GT.M V5.0-000 or later to V5.3-000 or later. However, you may need to run the MUPIP REORG –UPGRADE command to upgrade any previously used but free block that may have been missed during earlier upgrade cycles.  You do not need to run MUPIP REORG –UPGRADE in either of the following situations:
If you have already run the MUPIP REORG –UPGRADE command in a version prior to V5.3-003, subsequent versions cannot determine whether or not it was done correctly and will record warnings in the operator log for running MUPIP REORG -UPGRADE. Therefore, you must either:


For additional upgrade considerations, see "Database Compatibility Notes".  
Database Compatibility Notes

Stage 3: Upgrading your Replication Instance File

If you are running a logical multi-site (LMS) application configuration on a UNIX platform, then you need to recreate the replication instance file using the MUPIP REPLICATE -INSTANCE_CREATE command whenever your upgrade changes GT.M from a 32-bit implementation to a 64-bit implementation (or potentially vice versa on the x86 platform).  If your upgrade does not include a change between a 32- and 64-bit implementation then you do not need to recreate the replication instance file.  For example, on Linux systems, you do not have to recreate the replication instance file if you upgrade from 32-bit pre V5.3-001 to 32-bit V5.3-001 or later. You have to recreate the replication instance file only for the upgrade scenarios below.


Note: When upgrading from a 32-bit GT.M version to a 64-bit GT.M version you always need to recreate the replication instance files.  This includes upgrades from V5.3-000 or prior versions to GT.M V5.3-001 or later on AIX or 64-bit Linux and upgrades from V5.3-001 or prior versions to GT.M V5.3-002 or later on Solaris.  After creating new replication instance files, always start it with the -UPDATERESYNC qualifier.  Using pre-existing instance files (as opposed to creating new instance files) could cause any process that reads the instance file (which includes the Source Server, receiver server, update process and GT.M processes on an originating instance) to abnormally terminate with errors ranging from REPLINSTSECMTCH to a SIG-11 (which would create a corefile).

In the following three scenarios, your Source Server process terminates abnormally if you do not recreate the replication instance file:


In these cases, shut down all receiver servers on other instances looking for updates from this instance, shut down this instance, recreate the instance file and then restart the receiver server on this instance with the -UPDATERESYNC qualifier. 


Note: Without the UPDATERESYNC qualifier, the replicating instance synchronizes with the originating instance using state information from both instances and potentially rolling back information on the replicating instance. The UPDATERESYNC qualifier declares the replicating instance to be in a wholesome state matching some prior (or current) state of the originating instance; it causes MUPIP to update the information in the replication instance file of the originating instance and not modify information currently in the database on the replicating instance.  After this command, the replicating instance catches up to the originating instance starting from its own current state. Use UPDATERESYNC only when you are absolutely certain that the replicating instance database was shut down normally with no errors, or appropriately copied from another instance with no errors.


You must always follow the steps in the Multi-Site Replication technical bulletin when migrating from a logical dual site (LDS) configuration to an LMS configuration, even if you are not changing GT.M releases.

Stage 4: Upgrading your Journal Files

To upgrade from any prior GT.M version: 



Important: This is necessary because MUPIP cannot use journal files from a release other than its own for RECOVER or ROLLBACK. 

Return to Table of Contents

Managing M mode and UTF-8 mode

On selected platforms, 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 other platforms, or 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 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 an object file is older than the source file and was generated with the same setting of $gtm_chset/$ZCHset.  A GT.M process triggers 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:  

  • Actual files for GT.M executable programs (mumps, mupip, dse, lke, and so on) are in the parent directory, that is, the location specified for installation.

  • Object files for programs written in M (GDE, utilities) have two versions - one compiled with support for Unicode in the utf8 subdirectory, and one compiled without support for Unicode in the parent directory.  Installing GT.M generates both the versions of object files, as long as ICU 3.6 or greater is installed and visible to GT.M when GT.M is installed.

  • The utf8 subdirectory has files called mumps, mupip, dse, lke, and so on, which are relative symbolic links to the executables in the parent directory (for example, mumps is the symbolic link ../mumps).

  • When a shell process sources the shell scripts gtmprofile or gtmcshrc, the behavior is as follows:    

    • If $gtm_chset is "m", "M" or undefined, there is no change from the previous GT.M versions to the value of the environment variable $gtmroutines.

    • If $gtm_chset is "UTF-8" (the check is case-insensitive),

      • $gtm_dist is set to the utf8 subdirectory (that is, if GT.M is installed in /usr/lib/fis-gtm/gtm_V5.4-001_i686, then gtmprofile and gtmcshrc set $gtm_dist to /usr/lib/fis-gtm/gtm_V5.4-001_i686/utf8).

      • The last element of $gtmroutines is $gtm_dist($gtm_dist/..) so that the source files in the parent directory for utility programs are matched with object files in the utf8 subdirectory.


For more information on gtmprofile and gtmcshrc, refer to the "Basic Operations" chapter of UNIX Administration and Operations Guide.

Compiling ICU 

GT.M versions prior to V5.3-004 require exactly ICU 3.6, however, V5.3-004 (or later) accept ICU 3.6 or later. For sample instructions to download ICU, configure it not to use multi-threading, and compiling it for various platforms, refer to "Appendix C: Compiling ICU on GT.M supported platforms" of UNIX Administration and Operations Guide.

Although GT.M uses ICU, ICU is not FIS software and FIS does not support ICU. The sample instructions for installing and configuring ICU are merely provided as a convenience to you.

Also, note that download sites, versions of compilers, and milli and micro releases of ICU may have changed ICU since the embedded dates when these instructions were tested making them out-of-date. Therefore, these instructions must be considered examples, not a cookbook.


Return to Table of Contents

Setting the environment variable TERM

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.


Return to Table of Contents

Installing Compression Libraries

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 provided by zlib.  Simple instructions for compiling zlib on a number of platforms follow.  Although GT.M uses zlib, zlib is not FIS software and FIS does not support zlib.  These instructions are merely provided as a convenience to you.

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

Solaris/cc compiler from Sun Studio:

./configure --shared
make CFLAGS="-KPIC -m64"

HP-UX(IA64)/HP C compiler:

./configure --shared
make CFLAGS="+DD64"

AIX/XL compiler:

./configure --shared
Add -q64 to the LDFLAGS line of the Makefile
make CFLAGS="-q64"


./configure --shared
make CFLAGS="-m64"
Refer to the steps we used to install zlib on z/OS in the GT.M for z/OS technical bulletin.

By default, GT.M searches for the shared library ( on HPUX PA-RISC) 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 and z/OS) or $LD_LIBRARY_PATH (other UNIX platforms) includes the directory containung 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.

Change History 


Fixes and enhancements specific to V5.4-001 are:   

S9A09-001678 GT.M now supports the z/Linux platform
S9C05-002098 The JOB command accepts empty parameters
S9C10-002234 $QLENGTH() and $QSUBSCRIPT() now deal with $[Z]CHAR() representations
S9E12-002513 ZHELP is now more robust
S9J07-002730 Better status summary report from MUPIP RUNDOWN
S9F03-002532 The JOB command accepts  an empty actuallist
S9K03-002762 New environment variable gtm_snaptmpdir on UNIX
S9K04-002765 Two new options for V5CBSU on VMS
S9K04-002769 Improve M profiling resolution on UNIX
S9K05-002769 No SIG-11 on recovery of critical section lock on the journal pool after forcibly killing its UNIX holding process
S9K05-002770 The SOCKET device read is now better protected from SEGV (SIG-11 in UNIX or ACCVIO in OpenVMS) errors that may occur from INTRPT during READs.
S9K05-002772 Protect alias containers with multiple subscripts from inappropriate garbage collection
C9C08-002102 Improved handling of TCP connect() system calls for the source server and the GT.CM UNIX GNP server
C9E12-002681 GT.M call-in and call-out accepts names starting with percent (%)
C9I03-002965 Attempts to update a database which shares journals with another active database causes an error
C9J03-003105 On UNIX platforms, GT.M journal file header size is now 64K
C9J04-003116 MUPIP SET -JOURNAL=ON resumes journaling even if the current generation journal file is damaged or moved
C9K02-003237 On UNIX platforms, GT.M extends the gtm_procstuckexec facility to SEMWT2LONG and COMMITWAITPID errors
C9K02-003240 The UNIX trigger facility is now production grade
C9K03-003246 Improved snapshot error-handling and temporary file cleanup with MUPIP INTEG
C9K03-003247 No more "libgcrypt warning: Missing initialization" in UNIX operator log
C9K03-003248 New gtm_lvscale UNIX environment variable and GTM_LVSCALE VMS logical to enhance performance with large numbers of local variables
C9K04-003253 GETPASS (source and object files) stored in the distribution directories
C9K04-003254 GT.M handles VIEW "JNLFLUSH" more appropriately inside a TP transaction
C9K04-003258 Encryption plugin reference implementation scripts more robust than their predecessors
C9K04-003259 MUPIP INTEG correctly calculates the total number of blocks when it initiates a snapshot.
C9K04-003260 MUPIP JOURNAL ROLLBACK or RECOVER BACKWARD work even they are interrupted and reissued
C9K04-003261 DSE appropriately manages the database critical section and returns to the prompt under all known conditions
C9K04-003262 GT.M on AIX no longer causes process death when other sofware brings in threading 
C9K04-003263 On UNIX platforms in M mode, GT.M returns the correct value for $X for non-fixed READs from sequential disk, FIFO, and PIPE
C9K04-003264 Most UTF-8 compatible functions are now available in M-mode on OpenVMS
C9K04-003265 GT.M can concurrently update more than 64 databases
C9K03-003270 On UNIX platforms, MUPIP INTEG stops for a snapshot file error and reports snapshot file authorization issues
C9K05-003272 MUPIP REPLIC -SOURCE -SHOWBACKLOG -INST shows the backlog even if the Source Server is not alive
C9K05-003273 MUPIP JOURNAL RECOVER and ROLLBACK exit cleanly even if stopped prematurely by a MUPIP STOP

Corrections to the UNIX gtmprofile script

C9K06-003278 On UNIX platforms, issuing a MUPIP STOP on a Receiver Server now also shuts down the Update Process

Alias container appropriately maintained when a MERGE replaces it

C9K06-003281 UNIX MUPIP ENDIANCVT now normalizes some fields in files copied using a non-GT.M method

UNIX gtmsecshr displays more detailed error messages

C9K06-003284 GT.M prevents possible deadlocks when using MUPIP STOP on source and receiver servers

GT.M now accepts only ASCII characters where the standard (or GT.M) specify ASCII characters for language elements, such as global variable names.

MUPIP RESTORE and MUPIP BACKUP using TCP handle errors more robustly.

Return to Table of Contents

M-Database Access

The encryption reference plugin build script ( now uses a more optimized set of compiler and linker options for building plugin. Prior versions used minimal options required to build the plugin.[UNIX] (C9K04-003253, C9K04-003258)

Return to Table of Contents

M-Other Than Database Access


Return to Table of Contents


During this operation, MUPIP SET –JOURNAL=ON also sends the PREJNLLINKCUT message for the region to the application and the operator log.

: While this operation ensures that journaling continues even if the current generation journal file is damaged/missing, creating a new journal file with no back pointers creates a discontinuity with the previous journal files. Therefore, FIS recommends taking a database backup at the earliest convenience because a MUPIP RECOVER/ROLLBACK will not be able to go back past this discontinuity. Also, consider switching the journal files on all regions in the instance (with REGION "*") to ensure the RECOVER/ROLLBACK for other regions remains unaffected.
In prior versions, attempting MUPIP SET -JOURNAL=ON in such cases caused JNLOPNERR and JNLNOCREATE errors, requiring shutdown of the instance to restart journaling. (C9J04-003116)

Return to Table of Contents

Utilities-Other Than MUPIP


C9K02-003240 - Fixes for GT.M Triggers on UNIX 

In GT.M V5.4-000 (and V5.4-000A), the implementation of GT.M triggers was of field test grade, suitable for application development and testing but not for production use.  Triggers are now ready for production use.  Below are the changes to GT.M triggers in V5.4-001.

Revised behavior (V5.4-001) Old behavior (V5.4-000 and V5.4-000A)
GT.M invokes the correct set of triggers in case of a SET update to a node that either did not exist or was set to the null string.

Trigger definitions that specified a piece list (using -piece=) might be inappropriately invoked even if no specified piece changed as a result of the update.

GT.M wraps non-TP triggering updates in implicit TP transactions in such a way to avoid the possibility of "live lock" when some other process tries to concurrently update the trigger definition.

Non-TP triggering updates could enter in a "live lock" state when some other process tried to concurrently update the trigger definition. In the livelock state, a process consumes CPU without doing useful work.

Since GT.M implicitly wraps trigger updates as M transactions, any routines used to process journal extract files should deal with type 8 and 9 (TSTART/TCOMMIT) record types in addition to new record types introduced with triggers. If the application includes triggers that do no updates (i.e., effectively No-ops), the update that initiated the trigger appears inside TStart/TCommit brackets in the journal file. A trigger that conditionally does no updates (for example, a trigger that forces the value of a node to only take on permissible values, or initiates other corrective action, but makes no updates of its own for permissible values) produces similar journal records. In addition, GT.M may change a non-TP update  into a TP update if there are any trigger definitions associated with the named global.

GT.M did not wrap triggers that performed conditional updates or no updates (that is, effectively No-ops) inside Tstart/TCommit in the journal records.

GT.M handles $ZTRIGGER("item",<item>) more robustly.

Parsing of the item content in $ZTRIGGER("item",<item>) might cause erratic random damage with various symptoms.

GT.M now correctly unwinds the M stack when the unwind, from a ZGOTO or an error, includes a trigger base-frame.

From a ZGOTO or an error, GT.M did not properly count the frames to be unwound when a trigger base frame was included resulting in a partial unwind of the M stack which could cause various types of improper execution paths or fatal errors.

GT.M more robustly handles the use of triggers in environments operating in UTF-8 mode. In some cases, GT.M could generate a SIG-11 when using triggers in a UTF-8 environment, whether or not UTF-8 characters were used in the trigger.
GT.M now maintains the proper value for $REFERENCE during trigger operations.

$REFERENCE after $ZTRIGGER() operations incorrectly referred to a location in the internal global infrastructure associated with triggers.

GT.M properly handles the situation where there is a very large number of triggers for the same global with autogenerated trigger names. SELECT lists a trigger only once.

GT.M displayed no message or statistics when the auto-generated trigger names for the same global exceeded the maximum number of unique trigger name. Additionally, a SELECT could list the same trigger more than once.

GT.M now invokes the correct set of triggers for a given update.

For certain conditions when a global update invoked a trigger that updated the same global (potentially different nodes) that, in turn, invoked nested triggers, it was possible that the triggers defined for the initial global update might be skipped or invoked multiple times.

GT.M now properly handles the case when the first argument passed to $ztrigger() starts with a non-alphabetic character.

An initial non-alphabetic character in the first $ztrigger() argument caused a SIG-11.

$ZTWORMHOLE allows you to specify a string up to 128KB you want to make available during trigger execution.

$ZTWORMHOLE allowed you to specify a string up to 15KB to make available during trigger execution.

GT.M now correctly gives errors in cases where globals corresponding to trigger metadata are either missing or corrupted.

GT.M ignored trigger metadata corruption and silently skipped the corresponding triggers.

A MUPIP LOAD operation now issues a single warning on first encountering trigger metadata in GO/ZWR format files.

During a MUPIP LOAD operation with GO/ZWR format files, GT.M siltently ignored the trigger metadata.

GT.M reclaims memory more aggressively for both $ZTWORMHOLE information and incremental rollbacks during transaction processing. It is likely that only processes that set $ZTWORMHOLE inside transactions, or processes that perform a large number of incremental rollbacks inside transactions might show the difference.

Memory structures used for incremental rollbacks and $ZTWORMHOLE could become inflated by repeated use in a single transaction to sizes unlikely to be used efficiently by subsequent transactions.

$ZTRIGGER() now always opens a file or returns an error message if the second parameter  is missing.

Under certain conditions, $ZTRIGGER() did not recognize a valid trigger file name and returned a failure status. Additionally, a file name of length 0 or containing only the <NUL> character could cause a SIG-11.

GT.M trigger loading handles trigger definitions longer than 32K characters and also long values for the trigger qualifiers.

Long values for trigger qualifiers or trigger definitions longer than 32K characters could cause SIG-11 failures.

GT.M now properly handles the situation while assembling trigger status messages for a load operation and simultaneously printing operator messages.

During a load operation and while assembling trigger status message and printing operator message, GT.M trigger processing could lose the initial part of the trigger status message containing the file and line number and print only actual status part of the message.

GT.M properly prints trigger data (using select) when the data is longer than 2048 bytes.

GT.M truncated trigger data (using select) longer than 2048 bytes which resulted in an inaccurate representation of the trigger.

GT.M produces a "duplicate name" error when adding a trigger with both SET and KILL commands and an identical user-supplied name when the KILL components of the trigger match an existing trigger but the SET components of the added definition do not match an existing trigger.

GT.M did not produce an error and incorrectly added the SET components of the definition in the following condition under the described circumstances

GT.M properly adds a new SET trigger to the database when its pattern happens to match an existing KILL trigger.

If a new trigger definition had both SET and KILL commands with a user-defined trigger name and the matching trigger in the database had only a SET command and no name, GT.M could inappropriately merge the definition for the KILL command from the trigger definition file with the existing trigger's SET definition.

GT.M now only allows trigger names that follow the same syntax rules as M names: either % or a letter followed by letters and/or numeric digits, but limited to 28 characters.

Trying to use a trigger name that did not satisfy the M name syntax resulted in a GTMASSERT.

GT.M prints trigger parse error messages that contain non-printable characters using the $[Z]CHAR representation. For example, a trigger definition that had an embedded NULL character in the global name generates an error message like the following:

Invalid global name :

"^a"_$C(0)_"bc -commands=S -xecute=""write 123"""

where the NULL is plainly visible as $C(0). Note that the error message is now displayed in the form of an M string. As part of this change many of the trigger parse error messages are now printed as M strings.

As another example, the following trigger definition:

+^#t -command=SET -xecute="do ^twork"

Generates the following error message:

File t1.trg, Line 5: Invalid global name :

"^#t -command=SET -xecute=""do ^twork"""

Embedded non-printing characters in the trigger definition did not produce an error. GT.M would would either skip the invalid characters or print different characters.

GT.M properly handles maximum length trigger names.

In some cases, having a maximum length trigger name could cause corruption of the global reference in the trigger signature.

The Update process now detects discrepancies in the existence of trigger definitions for a global between the originating and replicating instances and puts a warning message in the operator log at the first detection for every global with that difference. Note that because trigger definitions are replicated, this should be an unusual situation.

During replcation, GT.M did not warn about the discrepencies in a global's trigger definition in an originating and its replicating instances.

GT.M rejects invalid UTF-8 characters in the global name in a trigger definition or in a trigger name used to delete a trigger by name.

Contrary to the M standard, GT.M accepted non-ASCII UTF-8 characters in the global name in a trigger definition or in a trigger name used to delete a trigger by name.

GT.M protects all calls to the print- and format-related service library routines against interrupts.

The interrupt of an unprotected call might on occasion cause faulty operation in a variety of ways that are not easily characterized. For example, a failure in a trigger compilation could be caused by a null routine name due to an interrupted formatting service. Note that these library functions are not used by core database logic, and data integrity was not in jeopardy.

$ZTOLDVAL correctly holds the empty string at trigger routine entry in case of KILL commands that reference a node whose $data is 10 (that is, node does not exist but has a subtree underneath).

Accessing $ZTOLDVAL in a trigger routine entry incorrectly issued an UNDEF error in case a KILL command that referenced a node whose $DATA was 10 (that is, node did not exist but had a subtree underneath).

GTM now allows the trigger related ISV $ZTWORMHOLE to be NEW’d. Note that NEWing this ISV is slightly different from NEWing most other ISVs or variables in that when $ZTWOrmhole is NEW’d it retains its original value (like $ZGBLDIR), but like other NEWs, this value is restored when that stack level pops.

GT.M did not allow ISV $ZTWORMHOLE to be NEW’d.

GT.M  introduces a new trigger ISV called $ZTSLATE. It allows you to specify a string that you want to make available in parallel or nested triggers invoked for an outermost  transaction (when a TSTART takes $TLEVEL from 0 to 1). You might use $ZTSLATE to accumulate transaction-related information, for example $ZTOLDVAL and $ZTVALUE,  available within trigger context for use in a subsequent trigger later in the same transaction. For example, you can use $ZTSLATE to build up an application history or journal record to be written when a transaction is about to commit.

You can SET $ZTSLATE only while a database trigger is active. GT.M clears $ZTSLATE for the outermost transaction or on a TRESTART. However, GT.M retains $ZTSLATE for all sub-transactions (where $TLEVEL>1).
GT.M did not provide the $ZTSLATE ISV.
If an originating instance does not support triggers, GT.M does not invoke triggers on a replicating instance even if the replicating instance has triggers defined for a replicated node.

If an originating instance did not support triggers, GT.M incorrectly invoked triggers on a replicating instance even if the replicating instance had triggers defined for a replicated node. This could cause duplicate updates that might induce application level errors.

GT.M maintains $REFERENCE correctly when a Non-TP update, having triggers defined, encounters a runtime error.

GT.M incorrectly set $REFERENCE to the empty string when a Non-TP update, having triggers defined, encountered a runtime error.

The Update Processes in the replicating instance now correctly set up structures needed for naked references to work on the replicating instance. The Update Process issued a GVNAKED error in the Update Process log if a global update invoked trigger code using a naked reference on the replicated global.
The Update Process in the replicating instance now correctly identifies empty-string ("null") subscripts in the global that is being replicated and issue a NULSUBSC error in the update process log if the region does not allow null subscripts.  The update Process continued with the update even though the global being replicated had empty subscripts.
GT.M writes the entire results of a $ZTRIGGER("SELECT") $ZTRIGGER("SELECT") truncated its output at 32K bytes.

Error Messages

The new error message(s) introduced in V5.4-001 are as follows:



SSATTACHSHM, Error while attaching to shared memory identifier iiii

Runtime Error: A GT.M process encountered error while trying to attach to shared memory created to manage a snapshot and reports the above error in the operator log.

Action: Examine the accompanying system error message and take appropriate action. 


TCOMMITDISALLOW, TROLLBACK required after an unhandled error in trigger context

Runtime Error: This transaction did an update that invoked a trigger which in turn encountered an error that was not handled by the application error trap inside the trigger context. Because of this, the exit from trigger context was abnormal. GT.M does not commit such transactions since they would not preserve the atomicity of trigger updates (triggering update + triggered updates).

Action: Such transactions can only be rolled back. If this is a nested TSTART (subtransaction), it can optionally be rolled back incrementally, that is, only the nested TSTART needs to be rolled back while the parent TSTART can still be committed.


TRIGDEFBAD, Trigger initialization failed for global ^gggg. Error while processing ^#t("xxxx",yyyy[,zzzz])

GT.M/MUPIP error: Missing or corrupted trigger metadata causes this error.

Action: Delete and replace defective triggers. If possible analyze the cause of the trigger damage and report the incident to your GT.M support channel.


TRIGDEFNOSYNC, Global ^gggg has triggers defined on the <originating/replicating> instance but none on the <replicating/originating> instance. Current journal sequence number is 0xjjjj

Update Process Warning : The Update Process detected that there is a mismatch in trigger definitions for global gggg between originating and replicating instances and sent this warning to the operator log.

Action : Differences in triggers between originating and replicating instances typically mean the replicating instance is not in a position to stand in as a system of record by becoming an originating instance. Unless the difference is intended because of a special use of the replicating instance, shutdown and resynchronize the replicating instance.


TRIGSUBSCRANGE, Trigger definition for global ^gggg has one or more invalid subscript range(s) : ssss

GT.M/MUPIP error : This error indicates one or more subscript range(s) of of order given the current collation subscript ordering - for global gggg in tthe trigger definition files.

Action: Verify the validity of subscript ranges in trigger definition file for the particular global, taking its collation into account, and redefine the trigger with correct subscript ranges for the collation of the global in question.


TRIGDATAIGNORE, Ignoring trigger data tttt. Use MUPIP TRIGGER to load trigger definitions

MUPIP informational message : MUPIP LOAD displays this warning when it encounters trigger metadata during extract file processing (GO/ZWR extracts).

Action: Identify and remove trigger metadata information from GO/ZWR extract files and, if appropriate, process it with MUPIP TRIGGER or $ZTRIGGER().

Due to V5.4-001 enhancements, the following error messages have changed:


The JNLVSIZE error message now displays the file system block size.
JNLVSIZE, Journal File xxxx has incorrect virtual_filesize aaaa Allocation is bbbb extension is cccc filesize is dddd file_system_block_size is eeee


PREVJNLLINKCUT, Previous journal file name link set to NULL in new journal file xxxx created for database file yyyy


Run Time/MUPIP Error: This indicates that GT.M or MUPIP has removed the link of previous journal file name and set it to NULL in the new xxxx journal files header. This could possibly be because journal state was ON for the database file yyyy and its corresponding journal file was inaccessible, this triggered MUPIP or GT.M to create new journal file xxxx clearing the previous generation journal file name(s).


Action: If the error is issued by GT.M review the accompanying message(s) in the operator log.

If a MUPIP SET –JOUNAL=ON command produces this message for the region in the operator log, it may indicate that one or more of the current generation journal files are damaged/missing and new journal files were created with no back pointers to the previous journal files. FIS recommends taking a database backup at the earliest convenience because a MUPIP RECOVER/ROLLBACK will not be able to go back past xxxx. If this message is for a specified region(s), consider switching the journal files for all regions (with REGION "*") that the process has opened (all journaled/replicated regions in the instance if replication is in use) to ensure that the RECOVER/ROLLBACK for other regions remains unaffected.

No action is required if the MUPIP BACKUP -NEWJNLFILES=NOPREVLINK issues the error. 


SRCSRVNOTEXIST, Source server for secondary instance xxxx is not alive

MUPIP Error: This error is issued by a mupip replic -source command that specifies any one of activate, changelog, checkhealth, deactivate, shutdown, showbacklog, statslog, stopsourcefilter if it finds no Source Server up and running for the replicating (secondary) instance name specified in the command.

Action: Make sure the Source Server for the specified replicating instance name is up and running to provide working replication.


REPLINSTSECNONE, No information found for secondary instance xxxx in instance file yyyy

MUPIP Error: This error is issued by any mupip replic source command that specifies a replicating (secondary) instance name (except for the one which specifies -start) if no information on this name can be found in the instance file. This is possible if no Source Server was ever started since the initialization of this instance file for such a replicating instance.

Action: Make sure the replicating instance name is correct. If it is, make sure a Source Server for that replicating instance has been started at least once in the life of the instance file even if it is currently not up and running.


REGSSFAIL, Process pppp encountered error contributing to the snapshot for region rrrr - the snapshot is no longer valid.

Mupip error: A GT.M process encountered failure while opening snapshot file or attaching to shared memory or writing a block to the snapshot file, any of which invalidate the snapshot file. The original error should be in the operator log.

Action: Examine the operator log for messages issued by process pppp to obtain details of the failure and take action, possibly by modifying file access characteristics or user roles, to address the problem.  


Starting with V5.4-001, the SSTMPFILOPEN message is deprecated in favor of SSFILOPERR
Return to Table of Contents

For more information, see the GT.M web site.