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
|
Date
|
Summary
|
| 1.13 |
26 January 2012 | In the Platforms section, removed a line that erroneously stated AIX 5.2 as a supported operating system version. |
|
1.12 |
27 November 2009 |
Reworked section "Database Compatibility for GT.M V5.3-004A" for clarity and renamed it to "Upgrading to GT.M V5.3-004A"; Added the guidelines for using MUPIP REORG -UPGRADE; Moved the instructions for compiling ICU on HP PA-RISC HP-UX to a separate section; Added the instructions for compiling ICU on HP Integrity IA64 HP-UX. |
| 1.11 | 13 August 2009 | Corrected AIX information to reflect AIX 5.3 as lowest supported operating system level |
|
1.1
|
10 August 2009
|
Updated to reflect V5.3-004A; corrected description of S9A11-001722; added entry for S9F04-002544, previously fixed in V5.3-003
|
|
1.0
|
16 July 2009
|
First published version
|
|
GT.M Group Fidelity National 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 / gtmsupport@fisglobal.com
Switchboard: +1 (610) 296-8877 Website: http://fis-gtm.com
|
UNIX: The term UNIX is used here in the general sense of all platforms for which GT.M uses a POSIX API. As of this date, this includes: AIX; HP-UX on IA64 and PA-RISC; GNU/Linux on IA64, x86 and x86_64; Solaris on SPARC; z/OS.
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 "/".
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 [].
GT.M V5.3-004A addresses a few issues with V5.3-004 (highlighted as V5.3-004A).
GT.M V5.3-004 adds significant new functionality to GT.M:
Alias variables. Intended to provide an underlying technology for implementing an object layer, alias variables provide a layer of abstraction between the name of a local variable and an array analogous to that provided by M pass by reference in subroutine invocations. Multiple local variables can be aliases, and a SET or KILL to one acts as a SET or KILL to all. Alias container variables provide a way of storing a reference to a data-space in an M sparse array, which protects the associated array even when it’s not accessible through any current name. Refer to the GT.M Alias Variables technical bulletin for details.
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.
|
Platform |
Supported Versions |
Notes |
|
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 |
11.11 |
GT.M supports UTF-8 mode and M mode on this platform subject to the following:
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.
|
|
Hewlett-Packard Alpha/AXP Tru64 UNIX |
5.1B |
GT.M supports M mode but not UTF-8 mode on this platform. GT.M does not support database encryption on this platform. |
|
Hewlett-Packard Alpha/AXP OpenVMS |
7.3-1/7.3-2/8.2/8.3 |
GT.M supports M mode but not UTF-8 mode on this platform. GT.M does not support database encryption on this platform.
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.
|
|
IBM eServer pSeries AIX |
5.3 |
Since GT.M processes are 64-bit, FIS expects 64-bit AIX configurations to be preferable.
|
|
Sun SPARC Solaris |
9 (Update 3 and above) and 10 |
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.3; Ubuntu 8.04 LTS (Hardy Heron), 8.10 (Intrepid Ibex) & 9.04 (Jaunty Jackalope) |
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.3, 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 <minor-ver>.<major-ver>):
|
|
x86 GNU/Linux |
Red Hat Enterprise Linux 4 |
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.3.4-2 or later) and ncurses (version 5.4-1 or later). The minimum CPU must have the instruction set of a 686 (Pentium Pro) or equivalent. Contact FIS for support of older CPUs.
Although RHEL 5.x is officially not supported for the 32-bit x86 GNU/Linux GT.M, we are aware of no reason why GT.M will not run on it.
This is the last GT.M release for RHEL 4.x. Future GT.M releases will require RHEL V5.x. |
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.
|
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, except on Tru64 UNIX, where GT.M remains a 32-bit application. |
|
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 |
|
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. |
|
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. |
Recompile all M and C source files.
Rebuild all Shared Libraries (UNIX) or Shareable Executable Images (OpenVMS) after recompiling all M and C source files.
To install GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide.
Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.
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 kill pid_of_gtmsecshr.
GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. Before installing GT.M on IBM pSeries AIX, 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 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)
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 to exceed 2GB, 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.
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.
Read the upgrade instructions of each stage carefully. Your upgrade procedure for GT.M V5.3-004A depends on your GT.M upgrade history and your current version.
To upgrade from any prior GT.M version:
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.
You need to upgrade your database files only when there is a block format upgrade (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:
To upgrade from GT.M V5.0*/V5.1*/V5.2*/V5.3*:
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. GT.M version upgrades on 32-bit Linux do not need to recreate instance files. After recreating replication instance files for a replication secondary (or tertiary in a multi-site replication environment) 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 primary) to abnormally terminate with errors ranging from REPLINSTSECMTCH to a SIG-11 (which would create a corefile).
In these three scenarios, your source server process terminates abnormally if you do not recreate the replication instance file. 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: The UPDATERESYNC qualifier unconditionally synchronizes this secondary instance with the primary.
To upgrade from any prior GT.M version:
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 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 /opt/lsb-gtm/gtm_V5.3-004_i686, then gtmprofile and gtmcshrc set $gtm_dist to /opt/lsb-gtm/gtm_V5.3-004_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.
Version: 11.31 (11iv3)
Compiler: cc HP C/aC++ B3910B A.06.12, aCC HP C/aC++ B3910B A.06.15, GNU Make 3.81
Instructions:
Ensure that system environment variable $PATH includes the location of all the compilers mentioned above.
Download the source code of ICU (in this example, version 3.6 for C from http://icu.sourceforge.net/download/3.6.html#ICU4C)
At the shell prompt, execute the following commands:
Set the environment variable $LD_LIBRARY_PATH to point to the location of ICU. HP-UX uses the environment variable $LD_LIBRARY_PATH to search for dynamically linked libraries to be loaded.
ICU is now installed in /usr/local.
By default, ICU is installed in /usr/local. If you install ICU in a different directory, type:
Then execute the gmake commands, and set the environment variable $LD_LIBRARY_PATH to point to the appropriate location.
Note: All GT.M versions prior to V5.3-004 require exactly ICU 3.6, however, V5.3-004 (or above) accept ICU 3.6 or later.
As of this writing (November, 2009), ICU version 3.6 can be compiled on HP Integrity IA64 HP-UX with the following configuration:
Version: HP-UX 11.31
Compilers: HP C/aC++ B3910B A.06.15, GNU make (3.81)
Instructions:
gunzip -d< icu4c-3_6-src.tgz | tar -xf -
cd icu/source/
chmod +x runConfigureICU configure install-sh
runConfigureICU HP-UX/ACC --disable-threads
gmake
gmake check
gmake install
ICU is now installed in the /usr/local directory.
By default, ICU is installed in /usr/local. If you install ICU in a different directory, type:
runConfigureICU HP-UX/ACC --prefix=<install_path> --disable-threads
Note: Although GT.M uses ICU, ICU is not FIS software and FIS does not support ICU. The instructions for installing and configuring ICU are merely provided as a convenience to you.
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 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.
Solaris/cc compiler from Sun Studio:
HP-UX(IA64)/HP C compiler:
AIX/XL compiler:
Linux/gcc:
z/OS:
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 (libz.sl 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) and $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.
Transaction Processing (TP) logic now enables a caching optimization for global references that previously only worked for non-TP (so called mini-transactions). This can provide a performance increase for applications using TP. (C9905-001119)
GT.M now supports database file encryption using a plug-in architecture. This enhances GT.M’s ability to protect data stored in the database and assists with compliance, such as HIPAA and PCI DSS. The GT.M Database Encryption Technical Bulletin provides details. [AIX, HP-UX on IA64, Linux, Solaris, z/OS] (C9A05-001476)
The KILL in progress (KIP) handling now deals correctly with the very rare case where a process terminates (perhaps because of a MUPIP STOP) in the middle of a non-TP (mini-transaction) multi-block Kill, and termination processing encounters a secondary error. In previous versions there was a very small chance the process could inappropriately clear the KIP indicator for the wrong region and/or leave behind an incorrect KIP indicator. DSE DUMP -FILE displays the current value of KIP as "KILLs in Progress". (C9E02-002510)
Transaction processing performance has been improved in the case where a only a small subset of the global variables accessed by a process in its lifetime are accessed within any given transaction. (C9I09-003042)
Fewer disk write operations are used to keep the database file, and journal file if any, on disk up-to-date with shared memory when the database has had no updates for a while. In previous versions, it was possible for more than one process to (redundantly) write file headers and EPOCH records. [UNIX] (C9J01-003076)
GT.M now manages any signals arriving during database startup and rundown and (BG) buffer allocation more robustly. In previous versions, there were very narrow windows where a signal such as a MUPIP STOP could disrupt lock management and cause a deadlock. [UNIX] (C9J01-003078)
GT.M now sends a JNLFLUSH error message to the operator facility if a process has trouble completing its journal writes. Prior versions issued a GTMASSERT in this case. [OpenVMS] (C9J03-003096)
GT.M now handles high contention at database startup and shutdown more gracefully. In prior versions, a large number of processes opening and closing a database file at the same time could cause one of them to get an inappropriate CRITSEMFAIL error. Such an error had no associated database damage. [UNIX] (C9J04-003120)
When possible, in a core file, GT.M now appropriately includes the file header for a database region using the MM access method. In prior versions if a memory related problem triggered the core it could cause an indefinite recursion. [UNIX] (C9J05-003121)
Databases created with V5.3-004 can grow to a maximum size of 224M (234,881,024) blocks. This means, for example, that with an 8KB block size, the maximum single database file size is 1,792GB (8KB*224M). In prior V5 versions, the maximum was 128M (134,217,728) blocks. Note that this is the size of a single database file - a logical database (an M global variable name space) can consist of an arbitrary number of database files. (C9I09-003122)
GT.M now handles the situation where a process has insufficient timer queue entries (TQELM) by skipping a free (idle) journal epoch, potentially repeatedly. In previous versions, the epoch logic could live-lock and produce indefinite looping when the process timer queue entries were exhausted. The workaround and recommended practice is to ensure that processes running GT.M have sufficient TQE limits (three per database file added to any other needs). You can adjust this limit for all users with the SYSGEN PQL_MTQELM parameter. Note that deferred epochs can lengthen journal recovery times. [OpenVMS] (C9J05-003123)
GT.M now generates %GTM-E-VERMISMATCH errors correctly during database initialization. Previous versions could inappropriately return an %GTM-E-REQRUNDOWN error. (C9J05-003132)
GT.M now limits the number of EPOCH and PBLK records it writes in journal files that have before image journaling turned on. In previous versions of GT.M, depending on database update patterns, more records than needed could be written resulting in journal file size bloat. [UNIX] (C9J06-003139)
GT.M now maintains the integrity of the database even in rare cases of TP updates to globals that have NOISOLATION optimization turned on and non-TP updates to globals using the $INCREMENT() function. In GT.M V5.3-004, the NOISOLATION case could under very rare circumstances result in a damaged database. In all previous GT.M versions since V5.0-000 which implemented $INCREMENT(), its use could in very rare circumstances result in a damaged database. The symptoms of the damage could be either a DBKEYORD integrity error report from MUPIP INTEG or a false GVUNDEF reported by GT.M. (C9J07-003162)
The new environment variable $gtm_nocenable controls whether <CTRL-C> is enabled at process startup. If $gtm_nocenable has a value of 1, "TRUE" or "YES" (case-insensitive), and the process principal device is a terminal, $PRINCIPAL is initialized to a NOCENABLE state where the process does not recognize <CTRL-C> as a signal to enter direct mode. No value, or other values of $gtm_nocenable initialize $PRINCIPAL with the CENABLE state. The [NO]CENABLE deviceparameter on a USE command can still control this characteristic from within the process. In prior versions, there was theoretically a minuscule window where GT.M might recognize a <CTRL-C> and enter direct mode even if a USE $PRINCIPAL:NOCENABLE was the very first command executed. In Open VMS, GTM$DEFAULTS provides a way to address this same issue. [UNIX] (S9902-001105)
The GT.CM GNP or OMI server process no longer suffers from inappropriate memory consumption (due to unnecessary string pool growth). This addresses a problem introduced in V5.0-000, which could cause the server to exhaust available memory and fail, particularly when the server had been running for a long time and the data rates were high. In theory, DSE, MUPIP or compilation could also trigger this issue, but in practice none of them are likely to generate enough temporary storage to expose the problem. Increasing the OS managed memory limits on processes and restarting the server frequently could ameliorate or workaround the issue. (S9I10-002704)
The $ZSYSTEM Intrinsic Special Variable (ISV) now returns the exit status modulo 256 of the shell invoked by the last ZSYSTEM command. The 256 limitation is external to GT.M. Previously $ZSYSTEM was not always reliable - it reported the actual exit status, but potentially OR'd with extraneous data multiplied by 256 modulo 65536. [UNIX] (S9J01-002718)
The SET command correctly handles the case where local variables used as subscripts of glvns outside of parentheses on the left hand side of the SET are also modified as part of a $$ or $& or $INCREMENT invocation on the right hand side of the SET; for example: SET X(I)=$$FUNC() where $$FUNC() modifies the value of I. As a consequence of a regression introduced in V5.2-000A, SET evaluated the right hand side first and used the modified value of the variable as the subscript for the SET. A workaround for such prior versions is to use a parenthesized set instead; for example: SET (X(I))=$$FUNC(). (S9J05-002724)
When using NOUNDEF, $NAME() now returns an empty string where appropriate for undefined variables. Starting with V5.3-001, $NAME() would return nothing at all for such undefined variables. (S9J06-002725)
GT.M now appropriately handles the situation when ZCOMPILE finds an error in the routine being compiled. Versions after V5.3-001 and through V5.3-004 create the object file, but do not close it - resulting in the possibility that other users trying to access the same object file, for example, through ZPRINT or $TEXT(), wait indefinitely for the object file to be closed. [Unix] (S9J07-002728)
GT.M now correctly handles the situation when a command line qualifier requests a source program listing file and the file being compiled has syntax errors. In previous versions certain types of syntax errors (for example LABELMISSING or FMLLSTPRESENT) could cause abnormal termination (SIG-11). [Unix] (S9J07-002729)
KILL of a variable joined by pass-by-reference to a formallist variable now always KILLs the formalist variable when the actuallist variable is KILL'd even if the formallist variable is specified as protected by an exclusive KILL. In prior releases, both variables were protected by the exclusive KILL. The new behavior conforms to the M standard. (C9B09-001754)
GT.M now correctly reports 0 for $ZEOF prior to a READ from a NULL device $PRINCIPAL. Previously $ZEOF would inappropriately be set to 1 prior to attempting a READ from a NULL device $PRINCIPAL. [UNIX] (C9E02-002527)
Alias variables provide a layer of abstraction between the name of a local variable and its value analogous to that provided by M pass by reference in routine calls. Multiple local variables can be aliases, and a SET or KILL to one acts as a SET or KILL to all. Alias container variables provide a way of storing a reference to a data-space in an M sparse array, which protects the associated data-space even when it is not accessible through any current name. The Alias Variables Technic
al Bulletin covers the details. (C9I02-002957)
GT.M now handles $ZEOF for disk files correctly by setting it to 1 only after a read to the end of file. Previously $ZEOF would inappropriately be set to 1 when opening a zero length file READONLY or when opening a file for APPEND - in both cases prior to any read operation. Note: $ETRAP and $ZTRAP occur on the READ after $ZEOF is set by a prior READ, while EXCEPTION is triggered on the same read that sets $ZEOF. [UNIX] (C9I04-002984)
Certain inappropriate terminations during ZLINK or ZPRINT commands, $TEXT() functions or $ETRAP/$ZTRAP invocations no longer occur. Previously, GT.M could get a signal 11 (UNIX) or ACCVIO (VMS) in these situations if a routine had been replaced by one or more ZLINK commands and the process referenced its source text with ZPRINT, $TEXT, $ETRAP, or $ZTRAP. (C9I08-003017)
z/OS on zSeries is now a supported platform using a 64-bit POSIX API. The GT.M on IBM eServer zSeries z/OS Technical Bulletin provides details. [z/OS] (C9I09-003031)
In UTF-8 mode, GT.M now also uses ICU versions later than 3.6 (previous versions of GT.M required ICU 3.6). By default, GT.M now uses the most current installed version of ICU. GT.M expects ICU to have been built with symbol renaming disabled and will issue an error at startup if the currently installed version of ICU has been built with symbol renaming enabled. To use a different version of ICU (not the currently installed) or a version of ICU built with symbol renaming enabled, use the new $gtm_icu_version environment variable to indicate the MAJOR VERSION and MINOR VERSION numbers of the desired ICU formatted as MajorVersion.MinorVersion (for example "3.6" to denote ICU-3.6). When $gtm_icu_version is so defined, GT.M attempts to open the specific version of ICU. In this case, GT.M works regardless of whether or not symbols in this ICU have been renamed. A missing or ill-formed value for this environment variable causes GT.M to only look for non-renamed ICU symbols. Note that display widths for a few characters are different starting in ICU 4.0. [UNIX] (C9I09-003033)
PIPE and FIFO ISV after a READ
Operation | Result | $DEVICE | $ZA | $TEST | X | $ZEOF |
READ X:n | Normal Termination | 0 | 0 | 1 | Data Read | 0 |
READ X:n | Timeout with no data read | 0 | 0 | 0 | empty string | 0 |
READ X:n | Timeout with partial data read | 0 | 0 | 0 | Partial data | 0 |
READ X:n | End of File | 1,Device detected EOF | 9 | 1 | empty string | 1 |
READ X:0 | Normal Termination | 0 | 0 | 1 | Data Read | 0 |
READ X:0 | No data available | 0 | 0 | 0 | empty string | 0 |
READ X:0 | Timeout with partial data read | 0 | 0 | 0 | Partial data | 0 |
READ X:0 | End of File | 1,Device detected EOF | 9 | 1 | empty string | 1 |
READ X | Error | 1,<error signature> | 9 | n/c | empty string | 0 |
GT.M now more efficiently handles large numbers of M routines within a single process, reducing memory usage for processes that link a large number of routines. (C9I12-003068)
GT.M now frees memory created when processing a pattern match operator containing alternations. In previous versions of GT.M, this same usage caused a small memory leak. (C9J01-003080)
64-bit implementations now handle deeply nested indirection in a more wholesome way. In previous releases, indirection nesting of more than 16 levels could trigger a buffer overflow, causing the process to terminate abnormally. [AIX, HP-UX IA64, Linux IA64 & x86_64, Solaris] (C9J01-003081)
GT.M now handles the case where an error occurs during the creation of a file or FIFO device, for example resulting from incorrect parameters, by ensuring neither the external device or file, nor the GT.M internal information on it persist. In previous versions an empty file would exist after the unsuccessful OPEN and a ZSHOW “D” included a CLOSED device. Additionally, the descriptors associated with the empty file would accumulate leading to a possible depletion of available descriptors. [UNIX] (C9J03-003097)
If $ZCHSET is "M", GT.M now accepts string literals containing characters in the range $CHAR(128) to $CHAR(255) on the right side of the pattern match operator. Previously GT.M issued a PATLIT error in such cases. Note that this is an unhealthy programming practice because string literals containing such characters are different between "M" and "UTF-8" modes and may cause subtle application bugs that are not immediately obvious. [UNIX] (C9J03-003102)
GTM now ignores trailing white space and/or comments in a string compiled for use in indirection or the Xecute command. Previously GTM would generate an INDEXTRACHARS error in this situation. (C9J03-003104)
GT.M now protects an EXCEPTION handler for an OPEN on a Sequential Disk, FIFO, or PIPE device when the OPEN fails. Previously there was a small chance the EXCEPTION could be corrupted during such an error resulting in inappropriate failure of the exception handler. (C9J04-003106)
If the UNIX environment variable or VMS logical name $gtm_prompt is defined, it is used to initialize the $ZPROMPT Intrinsic Special Variable (ISV), which specifies the direct mode prompt. If $gtm_prompt is not defined, the default remains "GTM>". (C9J04-003109)
GT.M now issues an appropriate error if an attempt is made to compile an M program that contains binary data. Previous versions of GT.M could terminate abnormally. (C9J04-003115)
GT.M now manages branches (DO, Extrinsic, GOTO, ZGOTO) to previous labels in the same routine properly. Previous 64-bit versions (V5.3-002 or later) could branch incorrectly, when the offset to the branch exceeded 1MB, typically causing a SEGV (Signal-11) error. Note that a 1MB offset is extremely large for an object module, requiring a substantially larger source module to generate it. [Solaris] (C9J04-003119)
GTM now reports the correct location (entryref) in errors, $STACK, $ZPOSITION and other places where it displays location. In prior versions large routines could trigger an internal overflow and cause GT.M to report incorrect locations. (C9J05-003129)
The call-out ($&) interface now correctly manages the registers on return from the call. In previous AIX releases stating with V5.3-001 external call logic that used many registers – typically programs with instances of significant logic complexity - could fail with a SEG-V (signal 11). The workaround was to rework called routines to lower their register usage high-water mark. [AIX] (C9J06-003135)
GT.M now compiles programs with many literals faster and manages compiler memory requirements to a low rather than high-water mark. This change also increases how many names (labels, routines and variables) the 32-bit x86 Linux edition can handle in a compilation. Previous versions took longer to compile some routines and could acquire a large memory footprint when compiling large routines. The memory size was typically an issue only when doing dynamic compilation from a running process. [UNIX] (C9J06-003136)
The gtmprofile and gtmcshrc scripts now recognize utf-8 as a valid setting of the gtm_chset environment variable. Previously, only UTF-8 was recognized by these scripts. [UNIX] (C9J06-003141)
GT.M now sets $TEST to 1 in case of a timed lock release operation (e.g. LOCK -^GBLREF:TIMEOUT). Previous versions of GT.M left $TEST untouched in this case which was not in compliance with the M-standard. (C9J06-003144)
Cursor addressing for terminal devices now works correctly using the X, Y, UP, or DOWN parameters of the USE statement. [z/OS] (C9J07-003146)
GT.M now avoids a case where multiple processes attempting to exit at the same time might cause one process to deadlock trying to get information about one of the other processes which is not available. [OpenVMS](C9J07-003147)
GT.M now reports more descriptive error messages for two cases dealing with ICU (for UTF-8) - ICUVERLT36, when it finds an ICU library with version less than 3.6 or when the $gtm_icu_version environment variable defines a value less than 3.6; and ICUSYMNOTFOUND when $gtm_icu_version is not defined and it encounters an ICU library built with symbol renaming. Previously, GT.M did not immediately report the error when $gtm_icu_version specified a version less than 3.6 and the error message did not include the library path and the ICU version in question. [Unix] (C9J07-003152)
GTM now compiles routines with many thousands of literals correctly and without error. Previously a routine with a large number or literals could occasionally cause a memory access violation (SEG-V, Sig-11 or ACCVIO) or, at least in theory, some corruption of a literal string. (C9J07-003161)
For enhanced troubleshooting, the source server now creates a core dump as part of issuing a JNLBADRECFMT error, in case one is encountered. The core file will help with determining the cause of the error. [UNIX] (S9J05-002723)
After one retry (to rule out the unlikley case of a TCP error in transmission), the Update Server on a replicating instance now appropriately issues GVSUBOFLOW or REC2BIG errors and then shuts down. GVSUBOFLOW indicates the incoming key length is greater than the maximum key size for a region. REC2BIG indicates the incoming global variable record length exceeds the maximum for a region. Previous versions ignored the GVSUBOFLOW error, causing database structural damage, and indefinitely retried a REC2BIG error, logging a stream of “Bad trans” messages. If the database key and record sizes on replicating instance are properly matched with those on the initiating instance, replication never encounters this issue. (C9G09-002804)
MUPIP FREEZE, DSE ALL -FREEZE/-NOFREEZE and DSE CHANGE -FILEHEADER -FREEZE=TRUE/FALSE now print informational messages to indicate the action on each region and the overall outcome. These commands used to be silent unless they encountered an error. (C9J01-003086)
MUPIP LOAD in UTF-8 mode runs faster and should now more closely approximate MUPIP Load in M mode. [UNIX] (C9J04-003117)
C9J05-003128 is described below, under Utilities other than MUPIP.
MUPIP BACKUP -DATABASE now issues an appropriate error message in case it encounters a failure while creating the backup database. Previous versions would issue a misleading error message in this case. (C9J07-003159)
DSE CHANGE -BLOCK -TN and DSE MAPS -RESTORE now write before-image journal records (which show up as PBLK records in a mupip journal -extract -detail output) as appropriate. DSE CHANGE -BLOCK -TN also writes after-image journal records (which show up as a AIMG records in the detailed journal extract) in case of local bitmap blocks. Previous versions did not write these records which could prevent a backward recovery/rollback from restoring the database to a valid past state. Please note that these are low-level DSE operations intended only to be performed under the guidance of FIS support. (C9B11-001789)
The installation script for GT.M on Solaris now works with /bin/sh. Previously, it required /usr/xpg4/bin/sh or Korn shell (ksh). Also, the script now correctly checks for 64-bit ICU libraries. Previously it checked for 32-bit ICU libraries, despite the fact that GT.M is a 64-bit application, and would fail to build GT.M's utf8 subdirectory if the 32-bit ICU libraries were not found. [Solaris] (C9J01-003071)
The release tar file may now be unpacked by any user. The install script must still be run as root to set permissions properly. Previous releases required root permissions to unpack the archive. [UNIX] (C9J01-003079)
C9J01-003086 is described above under Utilities, MUPIP.
The installation script for GT.M now creates any required parent directories for either an absolute or relative path installation. In addition, the installation creates a soft link from the utf8 installation directory to gtmsecshr and copies all include files in the distribution to the installation directory. Previously, the installation failed if any parent directories did not exist or if the installation directory was a relative path; also it did not provide the soft link and omitted some include files. [UNIX] (C9J02-003095)
DSE DUMP BLOCK now outputs certain printable UTF-8 character representations that it incorrectly suppressed in previous versions. Also, MUPIP LOAD now produces proper terminal output while loading binary format extract files created by GT.M versions before V5.2-000. Previous versions incorrectly displayed a <CTRL-D> character at the end of the first line of the header report, even though the actual database load worked correctly. [UNIX] (C9J05-003128)
GDE now issues an error if it encounters any problem opening a command file. In previous versions, it reported only file not found, but suppressed other errors, for example insufficient authorization. (C9J06-003134)
DSE CACHE -VERIFY now works correctly. In previous versions, it could fail with a DBBMMSTR error (reported in the operator log) even though the database was clean. [OpenVMS] (C9J06-003138)
Compile time or Run Time Error: This indicates the argument for a SET * or KILL * command used a non-alias local variable where the syntax requires an alias or alias container variable.
Action: Correct the code in or investigate the logic to determine why the local variable in question is not in the expected state.
Action: Change the [i/o]chset to match the device or file or use iconv to convert the file to an appropriate character set, or possibly use chtag to [re]tag the file.
MUPIP Error: MUPIP or DSE (uuuu) could not flush the buffers for database file dddd completely. In the case of MUPIP, this typically means that some process is not releasing the critical section. In the case of DSE, this typically means there is some error in the global buffer cache which needs to be fixed.
Action: In the case of MUPIP, wait approximately 20 seconds and retry. In the case of DSE, try DSE CACHE RECOVER to fix the cache. If the error persists, report it to the group responsible for database integrity at your operation as soon as possible
Run Time Error: GT.M failed to load the gtmcrypt plug-in or one of its related libraries.
Action: Refer to the accompanying detail (xxxx) and verify that the gtmcrypt plug-in and related libraries are properly installed and that $LD_LIBRARY_PATH / $LIBPATH are properly set.
Run Time Error: gtmcrypt plug-in reports there is problem with the hash function.
Action: Examine the message (xxxx) from the plug-in and take the needed action.
Run Time Error: The gtmcrypt plug-in reports it is unable to initialize one or more of its related libraries.
Action: Examine the detailed message (xxxx) from the plug-in and take appropriate action.
Run Time Error: gtmcrypt plug-in reports the hash of the key in the header of database file dddd does not match the hash stored in the header of journal file jjjj. This is most likely caused by inappropriate operator action such as replacing the current journal file with an older journal file.
Action: Correct the error that caused the incorrect journal file to be pointed to by the database file. If the correct journal file has been inadvertently deleted, create new journal files with the -noprevjnl switch. Take a backup as soon as possible thereafter. Depending on your situation, you may need to refresh secondary instances.
Run Time Error: gtmcrypt plug-in reports it was unable to obtain an encryption key for file ffff.
Action: Examine the message (xxxx) from the plug-in and take the needed action: for example, verify encryption key for this file is pointed to by the database key file, verify proper permissions on the directory path and the file, etc.
Run Time Error: gtmcrypt plug-in reports it was unable to obtain an encryption key based upon matching the hash of an encryption key.
Action: Examine the message (xxxx) from the plug-in and take the needed action: for example, verify encryption keys for all database files are pointed to by the database key file. For extracts and backups, verify all the keys from the databases that provided records are in the database key file.
MUPIP or GDE error: This error is triggered by an attempt to mark an MM database as encrypted with GDE or to switch an encrypted database from BG to MM with MUPIP SET. The MM access method is not supported for encrypted databases.
Action: Use the BG access method for encrypted files.
Run-time error: This error occurs if an external call was used to set the gtm_passwd environment variable to the null string after GT.M has been started and the first time an encrypted database file is accessed is within a TP transaction.
Action: If possible, set the gtm_passwd environment variable to the obfuscated password. Otherwise, ensure that any TP transactions have been closed before setting the gtm_passwd environment variable to the null string. Once that is done, immediately touch a global from an encrypted database, e.g., $DATA(myglobal), to ensure the prompting happens before entering another TP transaction.MUPIP error: An attempt to downgrade ffff which is an encrypted database to the V4 (GT.M version 4) format failed because the V4 format does not support encrypted database files.
Action: Use the database in the current format. If a V4 format is required, extract the data in unencrypted ZWRite format with MUPIP EXTRACT and load it into a newly created V4 database.
Run Time Error: gtmcrypt plug-in reports there is problem with encryption or decryption.
Action: Examine the message (xxxx) from the plug-in and take appropriate action.
Action: Correct the code in question - the $ZWRTAC* is only useful in restoring context from ZSHOW or ZWRITE output and has very narrow capabilities.
Action: Correct the code in question - the $ZWRTAC* is only useful in restoring context from ZSHOW or ZWRITE output and has very narrow capabilities.
Action: Look for accompanying text that explains the cause of the error and take appropriate action.
Action: Correct the code in question to avoid the parenthesized list.
Run Time Error: This error is reported by GT.M when it recognizes that the LC_CTYPE locale category cccc (as shown by the UNIX locale command) does not use UTF-8 character encoding when gtm_chset is "UTF-8".
Action: Set the environment variable LC_CTYPE to a Unicode locale name with UTF-8 character encoding. Note that LC_ALL, if defined, overrides LC_CTYPE. The name of the locale varies between different UNIX platforms, but mostly in the form of <lang>_<country>.<charset>, where each element (without the angular brackets) has the form shown below:
<lang> is the language code in lower case (such as en, or de).
<country> is the country name in upper case (such as US, GB)
<charset> is the character set encoding (such as UTF-8, ISO8859-1)
Refer to the operating system manuals for the specific details of available locale names on the system.
Run Time Error: This indicates that a transaction updated more blocks than the global buffer could hold for a particular region rrrr or accessed more than the single transaction limit of 64K blocks.
Action: Look for missing TCOMMIT commands; modify the code to reduce the total content or change content of the transaction. If the transaction is as intended and the issue is the number of updates, increase the GLOBAL_BUFFERS for the region using MUPIP SET, or modify the Global Directory to redistribute the relevant globals to more regions.
Action: Correct the code in or investigate the logic to determine why the local variable in question is not in the expected state.