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.
| Version |
Date |
Summary |
| 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. |
|
1.1 |
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 / gtmsupport@fnis.com
Switchboard: +1 (610) 296-8877 Website: http://fis-gtm.com
|
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 [].
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.
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.
|
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.
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 |
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.
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 |
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 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.
|
|
IBM System z Linux |
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.
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 a MUPIP STOP <pid_of_gtmsecshr>.
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)
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.
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.4-000A 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 (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:
To upgrade from GT.M V5.0*/V5.1*/V5.2*/V5.3*/V5.4*:
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.
To upgrade from any prior GT.M version:
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.
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:
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) 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.
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 |
| C9K06-003276 |
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 |
| C9K06-003279 |
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 |
| C9K06-003283 |
UNIX gtmsecshr displays more detailed error messages |
| C9K06-003284 | GT.M prevents possible deadlocks when using MUPIP STOP on source and receiver servers |
| C9K06-003286 |
GT.M now accepts only ASCII characters where the standard (or GT.M) specify ASCII characters for language elements, such as global variable names. |
|
C9K06-003290 |
MUPIP RESTORE and MUPIP BACKUP using TCP handle errors more robustly. |
| Journal Characteristic | New | Old |
| Journal format | V20 | V19 |
| Allocation minimum | 200 | 10 |
| Allocation default | 2048 | 100 |
| Extension default | 2048 | 100 |
| Alignsize minimum | 256 /* i.e. 16KB -> 128KB */ | 32 |
| Alignsize default | 2048 /* i.e. 64KB -> 1MB */ | 128 |
| Autoswitchlimit minimum | 16*128KB /* new autoswitchlimit minimum = 16 * alignsize-minimum */ | 128*16KB |
GT.M now supports the $gtm_lvscale UNIX environment variable or GTM_LVSCALE VMS logical name which cause GT.M to "scale up" performance when local variables have large numbers of subscripts. Previously, GT.M used a fixed set of of algorithms/structures to implement local variables. While scaling increases the sizes of internal structures, resulting in increased memory usage, it may also significantly increase the performance of arrays with more than a few hundred nodes at a subscript level. FIS suggests testing applications with large local variable useage first with $gtm_lvscale set to two (2), then increase by one (1) until performance levels off or until the memory requirements become problematic. (C9K03-003248).
MUPIP RUNDOWN now returns a status indicating not all regions or shared memory were run down. In prior versions some cases returned a success status even when there were issues with rundown actions on some regions. (S9J07-002730)
GT.M now supports the $gtm_snaptmpdir environment variable to specify where to place the temporary "snapshot" file created by online mupip integ. If $gtm_snaptmpdir is not defined, GT.M reverts to its previous behavior of using the $GTM_BAKTMPDIR environment variable if defined, and otherwise using the current working directory. In addition, for MUPIP BACKUP, the $GTM_BAKTMPDIR environment variable is considered deprecated in favor of the new $gtm_baktmpdir environment variable and at a future date FIS may opt to remove support for $GTM_BAKTMPDIR. Please plan to edit your scripts accordingly within a convenient timeframe. [UNIX] (S9K03-002762)
During this operation, MUPIP SET –JOURNAL=ON also sends the PREJNLLINKCUT message for the region to the application and the operator log.
Note: 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)
MUPIP INTEG now correctly calculates the total number of blocks at the time it initiates a snapshot. In V5.4-000 and V5.4-000A, in rare cases, the number of blocks and the size of shared memory created by MUPIP INTEG could be less than what the database actually held at the time of snapshot initiation and could cause false integrity errors. [UNIX] (C9K04-003259)
MUPIP JOURNAL ROLLBACK or RECOVER BACKWARD now work even in the case where they are interrupted and reissued. Prior versions could, in rare cases, terminate abnormally with a GTMASSERT error if more than one previous recovery was interrupted. This issue was reported as fixed by C9D07-002357 in GT.M V5.3-000 but the fix did not handle one case. (C9K04-003260)
MUPIP RESTORE and MUPIP BACKUP using TCP handle errors more robustly. Previously, invalid TCP address specifications could cause memory access violations (SEG-V/SIG-11 or ACCVIOs) and error messages for other conditions were cryptic and sometimes incorrect. (C9K06-003290)
V5CBSU on Open VMS now has two additional options. The FIX512 option takes in a DBCERTSCAN file from OpenVMS 7.3-1, which incorrectly pads a record type used by DBCERTIFY SCAN and produces a corrected file. The DUMP option produces a more diagnostic interpretation of the scan file. In addition, the distribution provides a LINK command for V5CBSU (in GTMDCBUILD.COM) that does not need editing before use. Versions since V5.3-003 required you to add GTM$DIST:_DH and GTM$DIST:_EXP to the V5CBSU LINK.
To remove the extra padding, define the logical GTM_V5CBSU with the value "FIX512" (that is, DEFINE GTM_V5CBSU FIX512.) This causes V5CBSU to create an output file with the same name as the input file but with "_FIX512" appended to the file extension (e.g. MUMPS.DBCERTSCAN as input will produce MUMPS.DBCERTSCAN_FIX512 as output.) This output file should be used as the input to V5CBSU (after DEASSIGNing GTM_V5CBSU) or to DBCERTIFY CERTIFY. It does not modify or require the database.
To invoke the dump feature of V5CBSU on OpenVMS, define the logical GTM_V5CBSU with the value "DUMP" before using V5CBSU. If the value of the logical GTM_V5CBSU contains both "DUMP" and "FIX512", V5CBSU performs both functions. [OpenVMS] (S9K04-002765)
DSE appropriately releases the database critical section (crit) returning to the DSE prompt in case of errors during the execution of the current command. In previous versions, DSE could inappropriately retain a hold on crit after errors in some commands. In addition, DSE CRIT SEIZE and CRIT RELEASE now work as documented. Any sequence of DSE commands run in the -seize window, whether they cause errors or complete successfully, leaves the database critical section (crit) untouched. In previous versions, a few DSE commands (DSE CHANGE -BLOCK -TN, DSE BUFF on an MM db, DSE WCINIT) unconditionally released crit even when it had previously been acquired with a CRIT -SEIZE. (C9K04-003261)
GT.M now displays an accurate error message in case it encountered an error while trying to start the gtmsecshr server. In previous versions, in cases where the gtmsecshr wrapper detected a situation that made it infeasible to start the real gtmsecshr server, GT.M used to display a GTMSECSHRSTART message followed by a misleading GTM-I-TEXT message [UNIX] (C9K06-003283).
Example old output:
-------------------
%GTM-E-GTMSECSHRSTART, Client - 8079 : gtmsecshr failed to startup
%GTM-I-TEXT, ess_id
Example new output:
-------------------
%GTM-E-GTMSECSHRSTART, Client - 8079 : gtmsecshr failed to startup
%GTM-I-TEXT, See syslog for cause of failure
| 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. |
The new error message(s) introduced in V5.4-001 are as follows:
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().
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.