From 9654d8b8950e869a7bad1ec8f97948a922963a24 Mon Sep 17 00:00:00 2001 From: Marcin Szydelski Date: Sep 09 2019 22:15:33 +0000 Subject: 20190910-00:15 --- diff --git a/articles/GTM_Database_Encryption.html b/articles/GTM_Database_Encryption.html index 4f4666a..5a55acf 100644 --- a/articles/GTM_Database_Encryption.html +++ b/articles/GTM_Database_Encryption.html @@ -1495,7 +1495,7 @@ body {
 
- +
@@ -1650,7 +1650,7 @@ body { The following schematic illustrates acquisition of the password for the key ring on disk.  Note that an error (for example from the entry of an incorrect password) may not be triggered immediately a?? for example, DSE does not need an encryption key until you attempt to access data (since the file header is not encrypted, access to it does not require a key).
- +

@@ -1662,7 +1662,7 @@ body {
- +
@@ -1747,7 +1747,7 @@ body {  

- +

@@ -1844,7 +1844,7 @@ body {
- +
@@ -1856,7 +1856,7 @@ body {
- +

@@ -1877,7 +1877,7 @@ body {
- +


@@ -1893,7 +1893,7 @@ body {

-
+
 
@@ -2412,7 +2412,7 @@ body {
- +

diff --git a/articles/GTM_Database_Migration.html b/articles/GTM_Database_Migration.html index 01e7464..ee7beef 100644 --- a/articles/GTM_Database_Migration.html +++ b/articles/GTM_Database_Migration.html @@ -57,7 +57,7 @@

  • Bring down all V4 GT.M processes and execute mupip rundown -file on each database file to ensure that there are no processes accessing the database files.

  • Take a backup of all the database files. Alternatively, use mupip journal -recover -forward to apply journal files to backups of database files taken above. Note that this may involve multiple generations of journal files for each database file. Archive journal files, if the policy is to archive journal files.

  • Use dbcertify certify to certify all the database files as being ready to be upgraded to V5 format.

  • Use V5 mupip upgrade to upgrade the database file header from V4 format to V5 format.

  • Recompile routines and rebuild shared libraries (can be done in parallel with the above).

  • Make copies of all global directory files. Use V5 GDE to open and exit each global directory to update it to V5 format. (This step is not needed when upgrading from V5 field test releases.)

  • Run dse maps -restore_all on the upgraded database. This will rebuild all the maps and reflect the blocks used in the database file.

  • Resume normal GT.M applications with V5.

  • While GT.M V5 applications are in normal use, run V5 mupip reorg -upgrade to convert any V4 format blocks that may be read but may not be updated (e.g., history records) to V5 format.

    • Return to top

    Background

    At the heart of GT.M's transaction management capability is the "transaction number" (TN). Each index or data block has a "block transaction number" (BTN) field. At each database update, the BTN field of all the altered blocks has the "current transaction number" (CTN) recorded within it. When a process references a block, by comparing the BTN with the BTN the last time it referenced that block, the process can determine whether the block has changed or not. Having a monotonically increasing CTN for the database, and being able to compare this with the BTNs is therefore crucial to being able to maintain consistency and structural integrity of the database during normal operation with hundreds or thousands of concurrent processes simultaneously updating the database.

    For all GT.M releases through the V4 series[1], the TN was an unsigned 32-bit integer, which meant that the maximum transaction number was 4,294,967,295. Before the maximum transaction number was reached, a database had to have all of its BTNs reset with a mupip integ -tn_reset command (see Chapter 6 of the GT.M Administration and Operations manual), a procedure that requires stand-alone access to the database, and which can take several hours on a large production database. GT.M was not very user friendly in that while a MUPIP INTEG would generate a warning when the CTN was within approximately 300 million of the limit (i.e., more than 93% of the TN range was used), normal operation would not generate any warning. Causing the transaction number to wrap around could damage the database.

    Furthermore, as computer systems have become faster, production databases at large financial institutions would require a TN RESET every few months. Unless logical dual site operation of an application is implemented, a TN RESET requires that the GT.M based application not be available for those few hours.

    Effective GT.M V5.0-000, the TN becomes an unsigned 64-bit number with a maximum value of 18,446,744,073,709,551,615. This means that if a financial institution needs an annual TN reset with GT.M V4, it would need a TN reset every 4,294,967,295 years with GT.M V5. A transaction processing application that runs flat out at a non-stop rate of 1,000,000 updates per second would need a TN reset approximately every 584,554 years. Thus, a 64-bit TN simplifies the operational management of a GT.M application.

    Since V4 databases only reserve 32-bits of space for TNs, the GT.M V5 database format is different from the V4 format (hence the need to change the major software version number from V4 to V5, as in V4.4-004 to V5.0-000), and a database upgrade is required when migrating from GT.M V4 to GT.M V5. In V5.0-000, the block header requires 16 bytes, vs. 8 bytes in all prior releases, through V5.0-FT02. This means that any prior database file that has even a single block that contains a single record that is larger than sixteen bytes less than the block size will require a database file with larger block size in V5.0-000.

    The traditional way to migrate a database is to perform a MUPIP EXTRACT with GT.M V4, and a MUPIP LOAD of the extracted data with GT.M V5. However, this approach requires that the database file be unavailable for the time that it takes to extract and load - potentially several hours - during which the application is not available, unless the application is deployed in a logical dual site configuration.

    GT.M V5.0 therefore provides an alternative mechanism to upgrade the database, one that allows most operations to be performed while the database is in use, and reduces the required time that the database is unavailable to - in the typical case - seconds to minutes.

    Also, for those who wish to try GT.M V5 before they switch to it, GT.M V5.0-000 has the ability to run with a database format that can almost instantaneously be switched to a V4 format, albeit with some impact on performance when using this feature.

    In order to accommodate 64-bit TNs, there are changes to the database file header, as well as to each database index and data block. In order to facilitate a database migration approach that minimizes the amount of time that an application must be unavailable, there are additional fields to support an in-place upgrade.

    [Note]

    A further enhancement effective V5.0-000 is that the maximum database file size is 134,217,728 (128M) blocks, whereas in all prior releases, through GT.M V5.0-FT02, the maximum database file size is 67,108,864 (64M) blocks. V4 databases that are upgraded to V5 retain the maximum database file size limit of 64M blocks (which means that with the popular 4KB block size, a single database file can grow to a maximum size of 256GB).

    Database File Header Changes

    There are a number of changes to the database file header, and these are reflected in the output of the dse dump -fileheader command, as described below:

    1. All transaction number fields (including CTN) are increased in size from 32 bits to 64 bits.

    2. Master Bitmap Size - since the master bitmap size is different for databases created with V5, compared to those upgraded from V4, the master bitmap size is made explicit and visible.

    3. Blocks to Upgrade - in order to support an incremental upgrade, there is a count of the blocks in the database that are still in V4 format.

    4. Desired DB format - for an option to "try before you switch", as well as an incremental database downgrade for those wishing to migrate a database from V5 to V4, there is a field that specifies the format of database blocks that are written out to the database file.

    5. Certified for Upgrade to - in order to accomplish the incremental upgrade, a database must be "pre-certified" using a new dbcertify utility that certifies that a database is ready for an incremental upgrade.

    6. "Hard Stop" transaction number - even if a database is in V5 format with a maximum transaction number of 264 - 1, for users who wish to preserve the ability to downgrade to V4, where the maximum transaction number cannot exceed 232-1, there is a "hard stop" TN. In order to support journal recovery and rollback for databases in V4 format, this needs to be 232-1-128M, or 4,160,749,567 (0xF7FFffff). For a database in V5 format, this needs to be 264-1-256M or 18,446,744,073,441,116,159 (0xFFFFffffEFFFffff)

    7. "Warning" transaction number - when the transaction number crosses this limit, GT.M will generate a warning, and update the warning transaction number to a new value. The new warning TN will be 256M (128M for a database with a Desired db format of V4) greater than the current warning TN unless the current warning TN is within 256M (128M for a Desired db format of V4) of the Hard Stop TN, in which case the new Warning TN will be halfway between the old Warning TN and the Hard Stop TN (so that the frequency of warnings will increase as the Hard Stop TN is approached).

    -

    The layout of the database file header has also changed, but this is not of any consequence to users since the only way to interact with the database file header is via the dse change -fileheader and mupip set commands.

    Block Format Changes

    Every V5 format database and index block requires a 64-bit BTN. Furthermore, since a database can have both V4 and V5 format blocks within it, there is a need to distinguish between V4 format blocks and V5 format blocks.

    The V4 block header is 8 bytes on UNIX, 7 bytes on OpenVMS, and is laid out as follows:

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 4 bytes - BTN

    In V5, the block header is increased to 16 bytes, and is laid out as follows:

    • 2 bytes - block version number

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 8 bytes - BTN

    If the value in the first two bytes is 0 through 6, GT.M V5 knows that the block is a V5 block and the field is a block version number; if it is 7 or greater, GT.M V5 knows that it is a V4 block and the field is the number of bytes currently in use in the block. This feature - a true hack - permits a GT.M database to contain both V4 format blocks as well as V5 format blocks, and facilitates the incremental upgrading of V4 databases to V5 with minimal unavailability of applications.

    One result of the fact that GT.M V5 has a 16-byte block header, whereas GT.M V4 has a 7 or 8 byte block header is that it is possible to have a record in a V4 database that will not fit in a V5 database with the same block size. The largest record that can fit in a V4 GT.M database on x86 GNU/Linux with a 4KB block size is 4088 bytes, whereas the largest record that can fit in a V5 GT.M database on the same platform is 4080 bytes. If there are any records whose size exceeds blocksize-16, then a new V5 database will need to be created with a larger block size. [2]

    Approaches to Migration

    Common to all Approaches
    Global Directory

    Since GT.M V5 adds support for names longer than 8 characters (see GT.M Long Names Technical Bulletin), as well as optional changes to the collation of null subscripts (see GT.M Null Subscripts Technical Bulletin), the V5 global directory format is different from a V4 global directory format, and must be upgraded.

    Please refer to the V5.0-000D Release Notes to upgrade the global directory.

    [Note]

    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Journal files and backups

    Journal files are specific to each GT.M version, and a journal file generated by one GT.M version is not compatible with another GT.M version. In particular, GT.M V4.4-004 journal files can only be processed by V4.4-004 and cannot be processed by V5.0-000. This means that a successful database backup as of the point of conversion is strongly recommended.

    [Note]

    An online backup that allows the application to continue operating will not suffice for such a backup, since a GT.M mupip backup command creates a snapshot of the database as of the instant that the command is issued, and not as of the time that the command completes.

    [Tip]

    mupip backup for a large database, even with the -bytestream flag, can take a non-trivial amount of time to run, perhaps more time than one might desire that the application be unavailable. An alternative approach is to take the journal files when the application is brought down, immediately prior to a database upgrade, and to apply them to a database backup from an earlier time with a mupip journal -recover -forward command, which should be faster than a mupip backup command.

    Logical Dual Site Operation

    A GT.M application that is configured for logical dual site operation can be upgraded from V4 to V5 while maintaining continuity of application availability. Please follow the procedures in the Database Replication chapter of the GT.M Administration and Operations Guide. Note that V4 journal files and mupip backup -bytestream files are not compatible with V5.

    Traditional

    The traditional approach to upgrading a database file is to extract it on the lower GT.M version with a mupip extract and to load it on the higher GT.M version with mupip load. Both BINARY format (mupip extract -format=binary) as well as the default ZWR format will work; however, the former is likely to be faster.

    Since the V4 database files are not modified with this approach, they can simply be archived, and a separate backup is not needed. The mupip extract files can also serve as an alternative backup.

    The benefits of a traditional approach are its simplicity and the fact that a database created with GT.M V5.0-000 can grow to a maximum size of 134,217,728 (128M) blocks, whereas a database created with a GT.M V4 release and upgraded to V5 retains a maximum size of 67,108,864 (64M) blocks.

    In-place upgrade minimizing down time

    Since a database extract and reload can take hours for large database files, GT.M V5.0-000 provides a method to upgrade database files that, at least in the typical case, requires that the application be brought down for only seconds to minutes. The basic approach to the in-place upgrade is the ability of GT.M V5.0-000 to read database blocks in V4 or V5 format. Whenever a block is updated, it will be written in V5 format. Thus, over time, the blocks are converted from V4 format to V5 format. Conceptually, this is a three-step process:

    1. Test and Certify: Test whether a database qualifies for an in-place upgrade, and certify it if it is. Except for a small part at the end, which in the typical case is expected to take only seconds to minutes, this step can be performed while the application is operating normally.

    2. Upgrade Database File Header: Upgrade the database file header from V4 format to V5 format. This requires stand-alone access of at most a few seconds.

    3. Use Applications Normally: Use the application normally with GT.M V5: When a database block is read in from disk to the global buffer cache, it is converted from V4 format to V5 format. Any V4 format blocks that are updated are automatically converted to V5 format. Since some database blocks may never be updated under normal operation (e.g., history records), a mupip reorg -upgrade command can be executed in the background to update all V4 format blocks to V5 format blocks.

    Test and Certify

    The critical requirement for being able to upgrade a database from V4 format to V5 format, whether in place or traditional, is that there must be no blocks whose records occupy more than blocksize-16 bytes. This is because database blocks in the global buffer cache are always in V5 format - when GT.M V5 reads a V4 format block into the global buffer cache, it converts it to V5 format. When writing out blocks, they can be written out in V5 format or converted to V4 format. If a database has no blocks with records occupying more than blocksize-16 bytes, upgrading to V5 is a snap. If it does have such blocks, they will need to be dealt with.

    There are two types of blocks whose records occupy more than blocksize-16 bytes - those with one record and those with more than one record. The latter can be made suitable for upgrading to V5 format blocks simply by splitting the block, but the former cannot: if a database contains even one block with one record which is larger than blocksize-16 bytes, that database cannot be upgraded in place from V4 to V5. Such a database file will require a new database to be created in V5 with a larger block size, following which the data must be extracted in V4 and loaded in V5.

    The dbcertify program is used to scan a V4 database and identify blocks with more than blocksize-16 bytes occupied. The testing and certification process has several steps:

    1. Increase the Reserved Bytes parameter in the database file header by 8 (UNIX/Linux) or 9 (OpenVMS). Note that the Reserved Bytes field is typically zero, so the new values will typically be 8 (UNIX) or 9 (OpenVMS). However, your database files may not be typical, so always check the value of this field with dse dump -fileheader and increment the value accordingly. This will ensure that no new records are created with a record size greater than blocksize-16, even though existing records will remain unaltered. You can run a mupip reorg on the database after setting Reserved Bytes to the new value; this will reduce the number of blocks that dbcertify will need to deal with in the next step.

    2. Verify that the Maximum Record Size parameter is less than or equal to blocksize-16, which it must be in V5. If it is not, you must determine whether your application requires it to be greater than blocksize-16, in which case a database upgrade is not possible: you will need to create a new database in V5 with a larger block size, into which you can load data extracted from the V4 database. If the application permits the Maximum Record Size parameter to be reduced to be less than or equal to blocksize-16, then reduce it accordingly. Once the Maximum Record Size parameter is less than or equal to blocksize-16, dbcertify can be used.

    3. The dbcertify program has two phases, a scan phase and a certify phase. Fidelity strongly recommends a backup before the certify phase, refer to the Tip in the Journal Files and Backups section for a suggestion on how to obtain a fast backup. +

      The layout of the database file header has also changed, but this is not of any consequence to users since the only way to interact with the database file header is via the dse change -fileheader and mupip set commands.

    Block Format Changes

    Every V5 format database and index block requires a 64-bit BTN. Furthermore, since a database can have both V4 and V5 format blocks within it, there is a need to distinguish between V4 format blocks and V5 format blocks.

    The V4 block header is 8 bytes on UNIX, 7 bytes on OpenVMS, and is laid out as follows:

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 4 bytes - BTN

    In V5, the block header is increased to 16 bytes, and is laid out as follows:

    • 2 bytes - block version number

    • 2 bytes - bytes currently in use in the block

    • 1 byte - block level

    • 8 bytes - BTN

    If the value in the first two bytes is 0 through 6, GT.M V5 knows that the block is a V5 block and the field is a block version number; if it is 7 or greater, GT.M V5 knows that it is a V4 block and the field is the number of bytes currently in use in the block. This feature - a true hack - permits a GT.M database to contain both V4 format blocks as well as V5 format blocks, and facilitates the incremental upgrading of V4 databases to V5 with minimal unavailability of applications.

    One result of the fact that GT.M V5 has a 16-byte block header, whereas GT.M V4 has a 7 or 8 byte block header is that it is possible to have a record in a V4 database that will not fit in a V5 database with the same block size. The largest record that can fit in a V4 GT.M database on x86 GNU/Linux with a 4KB block size is 4088 bytes, whereas the largest record that can fit in a V5 GT.M database on the same platform is 4080 bytes. If there are any records whose size exceeds blocksize-16, then a new V5 database will need to be created with a larger block size. [2]

    Approaches to Migration

    Common to all Approaches
    Global Directory

    Since GT.M V5 adds support for names longer than 8 characters (see GT.M Long Names Technical Bulletin), as well as optional changes to the collation of null subscripts (see GT.M Null Subscripts Technical Bulletin), the V5 global directory format is different from a V4 global directory format, and must be upgraded.

    Please refer to the V5.0-000D Release Notes to upgrade the global directory.

    [Note]

    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Journal files and backups

    Journal files are specific to each GT.M version, and a journal file generated by one GT.M version is not compatible with another GT.M version. In particular, GT.M V4.4-004 journal files can only be processed by V4.4-004 and cannot be processed by V5.0-000. This means that a successful database backup as of the point of conversion is strongly recommended.

    [Note]

    An online backup that allows the application to continue operating will not suffice for such a backup, since a GT.M mupip backup command creates a snapshot of the database as of the instant that the command is issued, and not as of the time that the command completes.

    [Tip]

    mupip backup for a large database, even with the -bytestream flag, can take a non-trivial amount of time to run, perhaps more time than one might desire that the application be unavailable. An alternative approach is to take the journal files when the application is brought down, immediately prior to a database upgrade, and to apply them to a database backup from an earlier time with a mupip journal -recover -forward command, which should be faster than a mupip backup command.

    Logical Dual Site Operation

    A GT.M application that is configured for logical dual site operation can be upgraded from V4 to V5 while maintaining continuity of application availability. Please follow the procedures in the Database Replication chapter of the GT.M Administration and Operations Guide. Note that V4 journal files and mupip backup -bytestream files are not compatible with V5.

    Traditional

    The traditional approach to upgrading a database file is to extract it on the lower GT.M version with a mupip extract and to load it on the higher GT.M version with mupip load. Both BINARY format (mupip extract -format=binary) as well as the default ZWR format will work; however, the former is likely to be faster.

    Since the V4 database files are not modified with this approach, they can simply be archived, and a separate backup is not needed. The mupip extract files can also serve as an alternative backup.

    The benefits of a traditional approach are its simplicity and the fact that a database created with GT.M V5.0-000 can grow to a maximum size of 134,217,728 (128M) blocks, whereas a database created with a GT.M V4 release and upgraded to V5 retains a maximum size of 67,108,864 (64M) blocks.

    In-place upgrade minimizing down time

    Since a database extract and reload can take hours for large database files, GT.M V5.0-000 provides a method to upgrade database files that, at least in the typical case, requires that the application be brought down for only seconds to minutes. The basic approach to the in-place upgrade is the ability of GT.M V5.0-000 to read database blocks in V4 or V5 format. Whenever a block is updated, it will be written in V5 format. Thus, over time, the blocks are converted from V4 format to V5 format. Conceptually, this is a three-step process:

    1. Test and Certify: Test whether a database qualifies for an in-place upgrade, and certify it if it is. Except for a small part at the end, which in the typical case is expected to take only seconds to minutes, this step can be performed while the application is operating normally.

    2. Upgrade Database File Header: Upgrade the database file header from V4 format to V5 format. This requires stand-alone access of at most a few seconds.

    3. Use Applications Normally: Use the application normally with GT.M V5: When a database block is read in from disk to the global buffer cache, it is converted from V4 format to V5 format. Any V4 format blocks that are updated are automatically converted to V5 format. Since some database blocks may never be updated under normal operation (e.g., history records), a mupip reorg -upgrade command can be executed in the background to update all V4 format blocks to V5 format blocks.

    Test and Certify

    The critical requirement for being able to upgrade a database from V4 format to V5 format, whether in place or traditional, is that there must be no blocks whose records occupy more than blocksize-16 bytes. This is because database blocks in the global buffer cache are always in V5 format - when GT.M V5 reads a V4 format block into the global buffer cache, it converts it to V5 format. When writing out blocks, they can be written out in V5 format or converted to V4 format. If a database has no blocks with records occupying more than blocksize-16 bytes, upgrading to V5 is a snap. If it does have such blocks, they will need to be dealt with.

    There are two types of blocks whose records occupy more than blocksize-16 bytes - those with one record and those with more than one record. The latter can be made suitable for upgrading to V5 format blocks simply by splitting the block, but the former cannot: if a database contains even one block with one record which is larger than blocksize-16 bytes, that database cannot be upgraded in place from V4 to V5. Such a database file will require a new database to be created in V5 with a larger block size, following which the data must be extracted in V4 and loaded in V5.

    The dbcertify program is used to scan a V4 database and identify blocks with more than blocksize-16 bytes occupied. The testing and certification process has several steps:

    1. Increase the Reserved Bytes parameter in the database file header by 8 (UNIX/Linux) or 9 (OpenVMS). Note that the Reserved Bytes field is typically zero, so the new values will typically be 8 (UNIX) or 9 (OpenVMS). However, your database files may not be typical, so always check the value of this field with dse dump -fileheader and increment the value accordingly. This will ensure that no new records are created with a record size greater than blocksize-16, even though existing records will remain unaltered. You can run a mupip reorg on the database after setting Reserved Bytes to the new value; this will reduce the number of blocks that dbcertify will need to deal with in the next step.

    2. Verify that the Maximum Record Size parameter is less than or equal to blocksize-16, which it must be in V5. If it is not, you must determine whether your application requires it to be greater than blocksize-16, in which case a database upgrade is not possible: you will need to create a new database in V5 with a larger block size, into which you can load data extracted from the V4 database. If the application permits the Maximum Record Size parameter to be reduced to be less than or equal to blocksize-16, then reduce it accordingly. Once the Maximum Record Size parameter is less than or equal to blocksize-16, dbcertify can be used.

    3. The dbcertify program has two phases, a scan phase and a certify phase. Fidelity strongly recommends a backup before the certify phase, refer to the Tip in the Journal Files and Backups section for a suggestion on how to obtain a fast backup.

      1. The scan phase runs concurrently with normal operation of GT.M V4. It makes no modifications to the database, but instead produces a report of blocks that are too large to be used by GT.M V5.

      2. The certify phase requires stand-alone access to the database. An M program is provided with GT.M V5.0-000, V5CBSU, which can run concurrently with normal operation of GT.M V4 applications, and which can take the output of the dbcertify scan phase and help reduce the amount of work the certify phase must perform. This reduces the amount of time that dbcertify requires stand-alone access to the database.

    Once the certify phase of dbcertify completes, mupip upgrade can be used to upgrade the database file header.

    [Note]

    dbcertify assumes that there is no structural damage to the database. Therefore, Fidelity strongly recommends that a mupip integ (without the -fast switch) be performed on the database or a backup copy of the database as soon as possible prior to running dbcertify, and not to start dbcertify if there are any unusual events or unusual messages in the operator log after the mupip integ operation (or the backup operation that created the backup on which mupip integ was run).

    [Note]

    The dbcertify certify and mupip upgrade steps are not journaled and are not interruptible. In the event of a hardware or software malfunction in the dbcertify or mupip upgrade, the V4 database will need to be restored from a backup.

    [Note]

    Although dbcertify and V5CBSU are written to have minimal impact on running applications, the fact that they perform IO means that the impact will not be zero. Whether or not the impact is noticeable depends on the extent to which IO is limiting throughput on your system.

    Upgrade Database File Header

    Once the certify phase of dbcertify has completed, the database file header can be upgraded from V4 to V5 with mupip upgrade, an operation that should take a fraction of a second on even the largest databases, since it only affects the file header. Once the database file header has been upgraded, the database can be used by GT.M V5 processes.

    A GT.M V5 database has a switch in the file header that specifies whether blocks that are updated are written to the database in V4 format or V5 format. Mupip upgrade will set the switch to cause GT.M V5 processes to write updated blocks in V5 format. To cause GT.M V5 processes to write updated blocks in V4 format, an option which preserves the ability to revert to GT.M V4 on short notice, use a subsequent mupip set -version=v4 command.

    [Note]

    Using GT.M V4 blocks in GT.M V5 will incur a small performance penalty, which may or may not be noticeable depending on what is limiting the throughput of your system.

    [Note]

    Mupip upgrade will reduce the Reserved Bytes field in the database file header by 8 bytes (UNIX) or 9 bytes (OpenVMS).

    Use Applications Normally

    Once the database file header has been upgraded, the database can be used normally with GT.M V5 processes. With the default database file header upgrade, any database blocks that are updated are written in V5 format, so that over time an increasing percentage of the blocks will be in V5 format.

    Since there may be blocks in V4 format that are never updated (e.g., history records), and as long as they are in V4 format, every read will incur at least a slight performance penalty, mupip reorg -upgrade can be used in the background to convert these blocks to V5 format.

    Memory Mapped (MM) access method database files

    To upgrade a database file used with the MM access method (supported on OpenVMS only), it must either have its access mode changed to Buffered Global (BG) to use the upgrade method that minimizes access time, or the traditional upgrade method should be used.

    [Note]

    Changing the access method from MM to BG requires stand-alone access and is accomplished by the mupip set command.

    Reverting from V5 to V4

    It is feasible to revert from GT.M V5 to V4. The database must first be downgraded to V4 format before it can be accessed by a GT.M V4 release. This is accomplished with the steps below, assuming that the CTN of the database is less than 4,294,967,295 (0xFFFFFFFF). If the CTN exceeds this number, a mupip integ -tn_reset must first be performed, or the database must be extracted using V5 mupip extract (with the default ZWR format) and loaded with V4 mupip load into a database created with V4 mupip create.

    1. The following steps can take place during normal operation of GT.M V5 processes.

      1. Use mupip set -version=v4 so that any blocks that are updated are written in V4 format.

      2. Use mupip reorg -downgrade to convert all blocks from V5 format to V4 format.

      diff --git a/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html b/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html index 448952a..45d2c44 100644 --- a/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html +++ b/articles/GTM_Migrating_Off_Alpha_AXP_OpenVMS.html @@ -745,7 +745,7 @@ body {

      -
      +


      @@ -757,7 +757,7 @@ body {

      -
      +


      diff --git a/articles/GTM_Multi_Site_Replication.html b/articles/GTM_Multi_Site_Replication.html index 128384d..1813471 100644 --- a/articles/GTM_Multi_Site_Replication.html +++ b/articles/GTM_Multi_Site_Replication.html @@ -42,7 +42,7 @@ gtmsupport@fnf.com

    -

    Table of Contents

    Overview
    Summary
    User Interface
    Replication Instance File
    MUPIP REPLIC –INSTANCE_CREATE –NAME
    -INSTSEC[ONDARY] qualifier
    -ROOT[PRIMARY] and –PROPAGATE[PRIMARY] Qualifiers
    Obsolete –UPDATE Qualifier
    MUPIP REPLIC –SOURCE –START
    MUPIP REPLIC –RECEIVER –START
    MUPIP REPLIC –SOURCE –ACTIVATE
    MUPIP REPLIC –SOURCE –DEACTIVATE
    Starting up an instance
    Shutting down an instance
    Primary and Secondary transitions
    Refreshing secondary from backup of primary
    Lost transaction processing
    MUPIP REPLIC –SOURCE –NEEDREST[ART]
    MUPIP REPLIC –SOURCE –LOSTTN[COMPLETE]
    MUPIP REPLIC –EDIT[INSTANCE]
    MUPIP REPLIC -SOURCE –JNLPOOL
    DSE DUMP -FILE[HEADER]
    DSE CHANGE -FILE[HEADER]
    MUPIP JOURNAL -ROLLBACK
    MUPIP BACKUP
    Rolling Upgrade
    From a GT.M Dual-site version to a GT.M Multi-site version
    Error Messages
    Typographical Conventions

    Return to top

    Overview

    GT.M V5.1-000 provides the capability to deploy an application in a logical multi-site configuration with multiple secondary sites to a single primary site.

    Prior versions of GT.M featured the capability to deploy an application in a logical dual-site configuration with only one secondary site.

    A configuration having a primary and secondary in proximity for operational efficiency, however, would not provide protection against a disruption that affects both systems. A separate and distant "disaster recovery" (DR) third system can provide the operational convenience of proximal systems for routine operations, and a distant system for continuity of business in the face of catastrophic events. Prior GT.M versions did not make it possible to set up multiple secondary and/or tertiary systems. GT.M V5.1-000 enables such multi-site configurations. For migration to the new version with continuity of business, a dual-site configuration where one site runs on a GT.M version that has multi-site replication enabled and the other site runs on a GT.M version that does not, is supported.

    [Note]

    The terms site and instance are used interchangeably throughout this technical bulletin to refer to a primary or secondary system that participates in replication. Please also note that GT.M imposes no restrictions on the number of instances that can reside on a given machine.

    [Note]

    A configuration that uses GT.M replication between one primary and one secondary is henceforth termed a dual-site configuration while a configuration that uses GT.M replication between one primary and more than one secondary and/or tertiaries is henceforth termed a multi-site configuration. Likewise, replication between one primary and one secondary is termed dual-site replication. Replication between one primary and more than one secondary and/or tertiaries is termed multi-site replication.

    Return to top

    Summary

    GT.M V5.1-000 supports replication from one primary site to multiple secondary sites. As in prior versions of GT.M, at any given instant, only one primary instance performs updates. In GT.M V5.1-000, this primary can concurrently replicate to as many as sixteen (16) additional instances. Any of the secondary sites can become the new primary, in the event of an unplanned or planned outage of the primary.

    After recovering from the outage, the original primary becomes a secondary, potentially generating a lost transaction file to be sent to the new primary for (re)processing.

    The multi-site configuration capability permits a secondary instance to pass the transactions to a tertiary instance. The flow of transaction data is from the primary to the secondary to the tertiary. Herein, the secondary acts as a primary for the tertiary. Thus, if each of the 16 secondary instances were to feed 16 tertiary instances, there could be 273 instances (1 primary + 16 secondaries + 256 tertiaries). If the tertiary instances fed quaternary instances, there could be 4,369 instances (1 primary + 16 secondaries + 256 tertiaries + 4096 quaternaries). And so on.

    Any arbitrary reconfiguration of the instances would be feasible, as any instance in the tree of instances below the primary could potentially become a new primary, if the current primary comes down.

    [Note]

    A tree structure is required for replication and cycles are not supported.

    [Caution]

    Just because GT.M permits arbitrary reconfiguration of the instances, it does not mean that an application or a specific deployment of the application should permit such an arbitrary reconfiguration. Each application deployment should have a specific configuration and a strategy for dealing with unplanned and planned outages.

    To differentiate the real primary from the secondary that is also acting as a primary (for the tertiary), GT.M V5.1-000 introduces the notion of a root primary versus a propagating primary.

    The instance on which business logic is executed, and resulting database updates are computed & commited, is termed the root primary. The secondary that acts as a primary (to a tertiary) is termed a propagating primary. This can be further extended to allow the tertiary replicate to a quaternary and so on. In such a case, the tertiary also acts as a propagating primary. There can be any number of propagating primaries but only ONE root primary in GT.M V5.1-000.

    GT.M process updates to replicated regions are disabled on all instances except the root primary (note that mupip reorg and database repair in the unlikely event of structural database damage needing repair with DSE, are not considered logical updates, and are permitted on the secondary). To identify whether the current instance is a root primary or a propagating primary the source server startup command now has an optional qualifier, -rootprimary or -propagate primary.

    Central to multi-site replication support is the notion of an instance name. Each replication instance is uniquely identified by a name that can be from 1 to 15 alphanumeric characters. This name is stored in the replication instance file of that instance. The instance name uniquely identifies every site in the multi-site configuration, as each site has only one replication instance file.

    [Caution]

    The instance name should be unique and two instances should not have the same name.

    [Note]

    The instance name is not changeable once the instance has served the role of either a primary (root or propagating) or a secondary since the replication instance files of all the corresponding secondaries and/or primaries connected to the instance maintain a record of the instance name.

    Since there can be multiple source servers running (one per active secondary) on a primary instance, source server commands need to specify secondary instance names to identify specific source servers.

    As indicated previously, a secondary running on GT.M V5.1-000 is supported with a primary running a prior version of GT.M and vice versa, which will occur in a rolling upgrade. Multiple secondary instances are allowed only after both the primary and secondary have been upgraded to GT.M V5.1-000. Likewise, tertiaries are allowed from a secondary only after both the primary and secondary have been upgraded to GT.M V5.1-000.

    [Note]

    Additional features of multi-site replication are available only when both the sites in an existing dual-site configuration are upgraded to GT.M V5.1-000.

    Return to top

    User Interface

    The changes to the user interface in V5.1-000 apply in both multi-site and dual-site configurations (e.g., if an instance name is required by a command, it is required even when operating in a dual-site configuration.

    Return to top

    Replication Instance File

    In order to use replication in dual-site or multi-site mode on UNIX, new replication instance files need to be created. A REPLINSTFMT error occurrs if a replication instance file from a previous version of GT.M is used. A FILENOTFND error occurs if the instance file does not exist and replication is attempted.

    The name given at the time of creating the instance file uniquely identifies the instance and is stored in the replication instance file.

    The instance file serves as a repository of the history of the journal sequence numbers that are generated locally or received from other instances. The history is maintained as a set of records. Every record identifies a range of journal sequence numbers and the name of the root primary instance that generated those journal records. The first history record starts with the current journal sequence number of the instance. When a root primary and secondary communicate, the primary instance name is recorded in the replication instance file history of both the primary and the secondary as the instance that generated the transmitted journal sequence numbers. When a tertiary connects to a secondary, it is still the root primary instance name (not that of the secondary which serves as a propagating primary) that gets recorded in the tertiary instance file since that is the instance that actually generated the records. History records are always added to the tail of the instance file, the only exception being records removed from the tail of the instance file when updates are rolled back from the database as part of a mupip journal –rollback.

    This history is crucial to determining the journal sequence numbers through which both instances are synchronized when a primary and secondary (or secondary and tertiary) attempt to connect. This journal sequence number is determined by going back in the history of both the instance files and finding the earliest shared journal sequence number that was generated by the same root primary instance. The receiver server on the secondary continues with normal replication only if the shared journal sequence number determined above matches the current journal sequence number of the secondary instance. Otherwise, a mupip journal –rollback –fetchresync must be performed on the secondary to rollback the secondary to a common synchronization point from which the primary can transmit updates to allow it to catch up. To avoid a possible out-of-sync situation, it is advisable, and safe even if it is not strictly necessary, so it can be unconditionally scripted, to perform a mupip journal -rollback -fetchresync prior to starting any source servers on the secondary instance.

    Processes such as source servers, receiver server, and mupip rollback access this history. A REPLINSTNOHIST error message is generated if they attempt to look up a history record corresponding to a sequence number (for example, as part of a -rollback operation) that is less than the earliest sequence number recorded in the instance file.

    A replication instance file maintains the current state of the instance and it is necessary to take a backup of this file that is consistent with the snapshot of the database files in the backup. Mupip journal -backup allows for the backup of the instance files at the same time that it backs up the database files.

    The replication instance file on the primary stores the information pertaining to each secondary for which a source server is started and the journal sequence number that was last transmitted to that secondary. In prior versions of GT.M, this journal sequence number was maintained as Resync Seqno in the database file headers of all replicated regions and a dse dump -fileheader would display this information. With GT.M V5.1-000, this information is only available in the replication instance file and mupip replic –source –showbacklog command uses this information to display the backlogs for secondary instances.

    The instance file has 16 slots to store information pertaining to a maximum of 16 secondary instances. Initially, all the slots are unused. A source server replicating to a secondary for the first time utilizes an unused slot to store the information related to that secondary and any future source server process replicating to the same secondary will update this information.

    If an unused slot is not available, the first time the source server starts, the slot for the least recently started secondary is reused, assuming of course that the source server for the secondary is not alive, and the information that is previously stored in that slot is overwritten. Any subsequent mupip replic –source on the preempted secondary instance generates a REPLINSTSECNONE message.

    [Note]

    Preemption of slots is not an issue if the primary does not connect to more than 16 different secondaries throughout its lifetime.

    If the replication instance file is damaged or deleted, a new instance file must be created, and all secondaries downstream must be recreated from backups.

    Return to top

    MUPIP REPLIC –INSTANCE_CREATE –NAME

    An instance name must be specified when the replication instance file is being created using the –name qualifier in the command line.

    The name identifies the replication instance to other instances, and it is immutable.

    [Note]

    In this rare instance, a GT.M command from a prior version is not upward compatible in GT.M V5.1-000.

    If -name is not specified, mupip uses the environment variable gtm_repl_instname for the name. If that variable is not defined, the command issues a REPLINSTNMUNDEF error message. Using the environment variable allows pre-existing user replication scripts to run without any changes. Explicitly specifying the qualifier in the scripts improves clarity.

    The name can be from 1 to 15 characters. Specifying a name longer than 15 characters or an empty string will issue a REPLINSTNMLEN error message.

    If an instance file already exists, it is renamed with a timestamp suffix, and a new one is created. This behavior is similar to the manner in which GT.M renames existing journal files while creating new journal files.

    Creating an instance file requires standalone access. A REPLINSTSTNDALN message is issued if the instance file is being used (i.e. the journal pool for that instance exists), while attempting to (re)create that instance file.

    Return to top

    -INSTSEC[ONDARY] qualifier

    On a primary instance, a source server process runs for each secondary instance. The –instsecondary qualifier identifies the secondary instance to which a source server replicates the data. In GT.M V5.1-000, the following commands have been modified to include the –instsecondary qualifier. It is mandatory to specify the –instsecondary qualifier while issuing these commands.

    +

    Table of Contents

    Overview
    Summary
    User Interface
    Replication Instance File
    MUPIP REPLIC –INSTANCE_CREATE –NAME
    -INSTSEC[ONDARY] qualifier
    -ROOT[PRIMARY] and –PROPAGATE[PRIMARY] Qualifiers
    Obsolete –UPDATE Qualifier
    MUPIP REPLIC –SOURCE –START
    MUPIP REPLIC –RECEIVER –START
    MUPIP REPLIC –SOURCE –ACTIVATE
    MUPIP REPLIC –SOURCE –DEACTIVATE
    Starting up an instance
    Shutting down an instance
    Primary and Secondary transitions
    Refreshing secondary from backup of primary
    Lost transaction processing
    MUPIP REPLIC –SOURCE –NEEDREST[ART]
    MUPIP REPLIC –SOURCE –LOSTTN[COMPLETE]
    MUPIP REPLIC –EDIT[INSTANCE]
    MUPIP REPLIC -SOURCE –JNLPOOL
    DSE DUMP -FILE[HEADER]
    DSE CHANGE -FILE[HEADER]
    MUPIP JOURNAL -ROLLBACK
    MUPIP BACKUP
    Rolling Upgrade
    From a GT.M Dual-site version to a GT.M Multi-site version
    Error Messages
    Typographical Conventions

    Return to top

    Overview

    GT.M V5.1-000 provides the capability to deploy an application in a logical multi-site configuration with multiple secondary sites to a single primary site.

    Prior versions of GT.M featured the capability to deploy an application in a logical dual-site configuration with only one secondary site.

    A configuration having a primary and secondary in proximity for operational efficiency, however, would not provide protection against a disruption that affects both systems. A separate and distant "disaster recovery" (DR) third system can provide the operational convenience of proximal systems for routine operations, and a distant system for continuity of business in the face of catastrophic events. Prior GT.M versions did not make it possible to set up multiple secondary and/or tertiary systems. GT.M V5.1-000 enables such multi-site configurations. For migration to the new version with continuity of business, a dual-site configuration where one site runs on a GT.M version that has multi-site replication enabled and the other site runs on a GT.M version that does not, is supported.

    [Note]

    The terms site and instance are used interchangeably throughout this technical bulletin to refer to a primary or secondary system that participates in replication. Please also note that GT.M imposes no restrictions on the number of instances that can reside on a given machine.

    [Note]

    A configuration that uses GT.M replication between one primary and one secondary is henceforth termed a dual-site configuration while a configuration that uses GT.M replication between one primary and more than one secondary and/or tertiaries is henceforth termed a multi-site configuration. Likewise, replication between one primary and one secondary is termed dual-site replication. Replication between one primary and more than one secondary and/or tertiaries is termed multi-site replication.

    Return to top

    Summary

    GT.M V5.1-000 supports replication from one primary site to multiple secondary sites. As in prior versions of GT.M, at any given instant, only one primary instance performs updates. In GT.M V5.1-000, this primary can concurrently replicate to as many as sixteen (16) additional instances. Any of the secondary sites can become the new primary, in the event of an unplanned or planned outage of the primary.

    After recovering from the outage, the original primary becomes a secondary, potentially generating a lost transaction file to be sent to the new primary for (re)processing.

    The multi-site configuration capability permits a secondary instance to pass the transactions to a tertiary instance. The flow of transaction data is from the primary to the secondary to the tertiary. Herein, the secondary acts as a primary for the tertiary. Thus, if each of the 16 secondary instances were to feed 16 tertiary instances, there could be 273 instances (1 primary + 16 secondaries + 256 tertiaries). If the tertiary instances fed quaternary instances, there could be 4,369 instances (1 primary + 16 secondaries + 256 tertiaries + 4096 quaternaries). And so on.

    Any arbitrary reconfiguration of the instances would be feasible, as any instance in the tree of instances below the primary could potentially become a new primary, if the current primary comes down.

    [Note]

    A tree structure is required for replication and cycles are not supported.

    [Caution]

    Just because GT.M permits arbitrary reconfiguration of the instances, it does not mean that an application or a specific deployment of the application should permit such an arbitrary reconfiguration. Each application deployment should have a specific configuration and a strategy for dealing with unplanned and planned outages.

    To differentiate the real primary from the secondary that is also acting as a primary (for the tertiary), GT.M V5.1-000 introduces the notion of a root primary versus a propagating primary.

    The instance on which business logic is executed, and resulting database updates are computed & commited, is termed the root primary. The secondary that acts as a primary (to a tertiary) is termed a propagating primary. This can be further extended to allow the tertiary replicate to a quaternary and so on. In such a case, the tertiary also acts as a propagating primary. There can be any number of propagating primaries but only ONE root primary in GT.M V5.1-000.

    GT.M process updates to replicated regions are disabled on all instances except the root primary (note that mupip reorg and database repair in the unlikely event of structural database damage needing repair with DSE, are not considered logical updates, and are permitted on the secondary). To identify whether the current instance is a root primary or a propagating primary the source server startup command now has an optional qualifier, -rootprimary or -propagate primary.

    Central to multi-site replication support is the notion of an instance name. Each replication instance is uniquely identified by a name that can be from 1 to 15 alphanumeric characters. This name is stored in the replication instance file of that instance. The instance name uniquely identifies every site in the multi-site configuration, as each site has only one replication instance file.

    [Caution]

    The instance name should be unique and two instances should not have the same name.

    [Note]

    The instance name is not changeable once the instance has served the role of either a primary (root or propagating) or a secondary since the replication instance files of all the corresponding secondaries and/or primaries connected to the instance maintain a record of the instance name.

    Since there can be multiple source servers running (one per active secondary) on a primary instance, source server commands need to specify secondary instance names to identify specific source servers.

    As indicated previously, a secondary running on GT.M V5.1-000 is supported with a primary running a prior version of GT.M and vice versa, which will occur in a rolling upgrade. Multiple secondary instances are allowed only after both the primary and secondary have been upgraded to GT.M V5.1-000. Likewise, tertiaries are allowed from a secondary only after both the primary and secondary have been upgraded to GT.M V5.1-000.

    [Note]

    Additional features of multi-site replication are available only when both the sites in an existing dual-site configuration are upgraded to GT.M V5.1-000.

    Return to top

    User Interface

    The changes to the user interface in V5.1-000 apply in both multi-site and dual-site configurations (e.g., if an instance name is required by a command, it is required even when operating in a dual-site configuration.

    Return to top

    Replication Instance File

    In order to use replication in dual-site or multi-site mode on UNIX, new replication instance files need to be created. A REPLINSTFMT error occurrs if a replication instance file from a previous version of GT.M is used. A FILENOTFND error occurs if the instance file does not exist and replication is attempted.

    The name given at the time of creating the instance file uniquely identifies the instance and is stored in the replication instance file.

    The instance file serves as a repository of the history of the journal sequence numbers that are generated locally or received from other instances. The history is maintained as a set of records. Every record identifies a range of journal sequence numbers and the name of the root primary instance that generated those journal records. The first history record starts with the current journal sequence number of the instance. When a root primary and secondary communicate, the primary instance name is recorded in the replication instance file history of both the primary and the secondary as the instance that generated the transmitted journal sequence numbers. When a tertiary connects to a secondary, it is still the root primary instance name (not that of the secondary which serves as a propagating primary) that gets recorded in the tertiary instance file since that is the instance that actually generated the records. History records are always added to the tail of the instance file, the only exception being records removed from the tail of the instance file when updates are rolled back from the database as part of a mupip journal –rollback.

    This history is crucial to determining the journal sequence numbers through which both instances are synchronized when a primary and secondary (or secondary and tertiary) attempt to connect. This journal sequence number is determined by going back in the history of both the instance files and finding the earliest shared journal sequence number that was generated by the same root primary instance. The receiver server on the secondary continues with normal replication only if the shared journal sequence number determined above matches the current journal sequence number of the secondary instance. Otherwise, a mupip journal –rollback –fetchresync must be performed on the secondary to rollback the secondary to a common synchronization point from which the primary can transmit updates to allow it to catch up. To avoid a possible out-of-sync situation, it is advisable, and safe even if it is not strictly necessary, so it can be unconditionally scripted, to perform a mupip journal -rollback -fetchresync prior to starting any source servers on the secondary instance.

    Processes such as source servers, receiver server, and mupip rollback access this history. A REPLINSTNOHIST error message is generated if they attempt to look up a history record corresponding to a sequence number (for example, as part of a -rollback operation) that is less than the earliest sequence number recorded in the instance file.

    A replication instance file maintains the current state of the instance and it is necessary to take a backup of this file that is consistent with the snapshot of the database files in the backup. Mupip journal -backup allows for the backup of the instance files at the same time that it backs up the database files.

    The replication instance file on the primary stores the information pertaining to each secondary for which a source server is started and the journal sequence number that was last transmitted to that secondary. In prior versions of GT.M, this journal sequence number was maintained as Resync Seqno in the database file headers of all replicated regions and a dse dump -fileheader would display this information. With GT.M V5.1-000, this information is only available in the replication instance file and mupip replic –source –showbacklog command uses this information to display the backlogs for secondary instances.

    The instance file has 16 slots to store information pertaining to a maximum of 16 secondary instances. Initially, all the slots are unused. A source server replicating to a secondary for the first time utilizes an unused slot to store the information related to that secondary and any future source server process replicating to the same secondary will update this information.

    If an unused slot is not available, the first time the source server starts, the slot for the least recently started secondary is reused, assuming of course that the source server for the secondary is not alive, and the information that is previously stored in that slot is overwritten. Any subsequent mupip replic –source on the preempted secondary instance generates a REPLINSTSECNONE message.

    [Note]

    Preemption of slots is not an issue if the primary does not connect to more than 16 different secondaries throughout its lifetime.

    If the replication instance file is damaged or deleted, a new instance file must be created, and all secondaries downstream must be recreated from backups.

    Return to top

    MUPIP REPLIC –INSTANCE_CREATE –NAME

    An instance name must be specified when the replication instance file is being created using the –name qualifier in the command line.

    The name identifies the replication instance to other instances, and it is immutable.

    [Note]

    In this rare instance, a GT.M command from a prior version is not upward compatible in GT.M V5.1-000.

    If -name is not specified, mupip uses the environment variable gtm_repl_instname for the name. If that variable is not defined, the command issues a REPLINSTNMUNDEF error message. Using the environment variable allows pre-existing user replication scripts to run without any changes. Explicitly specifying the qualifier in the scripts improves clarity.

    The name can be from 1 to 15 characters. Specifying a name longer than 15 characters or an empty string will issue a REPLINSTNMLEN error message.

    If an instance file already exists, it is renamed with a timestamp suffix, and a new one is created. This behavior is similar to the manner in which GT.M renames existing journal files while creating new journal files.

    Creating an instance file requires standalone access. A REPLINSTSTNDALN message is issued if the instance file is being used (i.e. the journal pool for that instance exists), while attempting to (re)create that instance file.

    Return to top

    -INSTSEC[ONDARY] qualifier

    On a primary instance, a source server process runs for each secondary instance. The –instsecondary qualifier identifies the secondary instance to which a source server replicates the data. In GT.M V5.1-000, the following commands have been modified to include the –instsecondary qualifier. It is mandatory to specify the –instsecondary qualifier while issuing these commands.

        	mupip replic –source –start
    	mupip replic –source –deactivate
    	mupip replic –source –activate
diff --git a/articles/GTM_V5.2-000B_Release_Notes.html b/articles/GTM_V5.2-000B_Release_Notes.html
index 73fa4a1..493d1e4 100644
--- a/articles/GTM_V5.2-000B_Release_Notes.html
+++ b/articles/GTM_V5.2-000B_Release_Notes.html
@@ -116,9 +116,9 @@
 					SET COMMAND GTM$DIST:GTMCOMMANDS.CLD
 				
    in GTMLOGIN.COM or other command file for each process which uses GT.M, you must execute this 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 will need to 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 to match the proper GTMCOMMANDS.CLD with the version of GT.M being used.

    Managing M mode and UTF-8 mode

    From the same source file, the GT.M V5.2-000B mumps process generates an object file for M mode or UTF-8 mode depending on the value of the environment variable gtm_chset. GT.M V5.2-000B mumps process 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. GT.M V5.2-000B mumps process trigger an error if the object file was generated with a different setting of $gtm_chset/$ZCHset.

    M object modules must be generated with an environment that matches the run-time setting. As the GT.M product contains M utility programs, their object files must conform to this rule. In order to be able to use either, or both, M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 “flavors” of object modules exist and can be found in known locations (as described above). The technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use – the same pattern should be considered for structuring application object code repositories.

    The following changes are made to the way in which V5.2-000 (and above) is installed.

    1. Most GT.M product executables (mumps, mupip, dse, lke, etc.) are in the parent directory, that is, environment variable gtm_dist.
    2. The object files for programs written in M (GDE, utilities) have two versions-- one compiled for functionality related to Unicode™ in the utf8 subdirectory, and one compiled for functionality not related to Unicode™ in the parent directory. Installing V5.2-000B generates both the versions of object files if ICU 3.5 is installed; otherwise it generates only the M mode object files.
    3. Both the parent directory and the utf8 subdirectory have files called mumps, mupip, dse, etc. Those in the utf8 subdirectory are relative symbolic links to the executables in the parent directory (e.g., mumps is the symbolic link ../mumps).
    4. When the user sources the shell scripts gtmprofile or gtmcshrc, the behavior is as follows:
      1. If environment variable gtm_chset is m, M or undefined, there are no changes to the environment from the previous versions.
      2. If environment variable gtm_chset is UTF-8, -

        1. $gtm_dist is set to the utf8 subdirectory (i.e, if GT.M is installed in /usr/local/gtm_V5.2-000B, $gtm_dist will be set to /usr/local/gtm_V5.2-000B/utf8).

        2. The last element of $gtmroutines will not be $gtm_dist as it is today, but will instead be $gtm_dist($gtm_dist/..) so that the source directory for GDE and the utilities are matched with the appropriate executables.

    Note on setting the environment variable TERM

    Users must set the environment variable TERM to a terminfo entry that 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 is being run.

    [Important]
    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal functions. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) manufacturer may also be able to help.

    Return to top

    Change History

    Return to top

    V5.2-000B

    The only fix released in V5.2-000B is:

    +

    1. $gtm_dist is set to the utf8 subdirectory (i.e, if GT.M is installed in /usr/local/gtm_V5.2-000B, $gtm_dist will be set to /usr/local/gtm_V5.2-000B/utf8).

    2. The last element of $gtmroutines will not be $gtm_dist as it is today, but will instead be $gtm_dist($gtm_dist/..) so that the source directory for GDE and the utilities are matched with the appropriate executables.

    Note on setting the environment variable TERM

    Users must set the environment variable TERM to a terminfo entry that 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 is being run.

    [Important]
    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal functions. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) manufacturer may also be able to help.

    Return to top

    Change History

    Return to top

    V5.2-000B

    The only fix released in V5.2-000B is:

    C9H04-002843 -

    This fix is marked with [V5.2-000B] in the subsequent sections.

    Return to top

    V5.2-000A

    Fixes and enhancements released in V5.2-000A are:

    +

    This fix is marked with [V5.2-000B] in the subsequent sections.

    Return to top

    V5.2-000A

    Fixes and enhancements released in V5.2-000A are:

    S9C08-002197
    S9C10-002243 @@ -230,7 +230,7 @@

    • [V5.2-000A] SET of global variables within a parenthesized list of targets where the global references use extended syntax containing one or more local variables now occurs properly when the local variables are defined or gives an appropriate UNDEF error when a local variable is undefined. In previous versions, even when the local variables were all defined, it used to give a message that did not specify the variable name (HPUX/AIX) or a segmentation fault (SIG-11). [Linux/Tru64/Solaris/AlphaVMS] (S9C08-002197)

    • [V5.2-000A] Output-only parameters of type char * and string * without pre-allocation now trigger the ZCNOPREALLOUTPAR error. Also see C9F09-002753.[UNIX] (S9C10-002243)

      Note that this change makes V5.2-000A not backward compatible for programs that use this feature. Although GT.M is normally fastidious with respect to maintaining backward compatibility, improvements in performance and robustness were judged to warrant an exception in this case.

    • [V5.2-000A] The pattern match operator no longer causes a process to hang if the pattern following the question-mark (?) is a string literal more than 6 characters long and the repetition count consists of a period (.) with no leading and trailing integer literals. (S9F01-002526)

    • [V5.2-000A] Unrecognized Intrinsic Functions and Intrinsic Special Variables and unrecognized deviceparameter constructions that are bypassed due to FALSE postconditionals no longer cause run-time errors. The error messages affected by this change are INVFCN, INVSVN, FNOTONSYS, SVNOSET, SVNONEW, DEVPARINAP, DEVPARUNK, DEVPARVALREQ. These errors still trigger error reports at compile time—for example "SET:0 $ZZZZ=1" continues to generate a compilation error— but no longer generates a run-time error. (S9F10-002572)

    • [V5.2-000A] Extensive testing validates that two argument $STACK() and ZSHOW “S” work properly. If $ECODE is null then the two argument $STACK() returns the same result as ZSHOW "S". The result differs only when $ECODE contains error information. Fidelity recommends applications reset $ECODE in their error handlers before restoring the normal flow of control. (S9F12-002579)

    • READ X:0 now leaves $TEST set in case the only character READ is a terminator. (S9F12-002582)

    • Certain cases of an untimed OPEN of the TCP device that would cause the process to spin in a tight loop no longer do so.(S9G09-002625)

    • READ *X:<timeout>now properly times out when the timeout is greater than 8 seconds. [Linux] (S9G11-002628)

    • [V5.2-000A] $zgetjpi(“”,”INVALID ARG”) now produces the BADJPIPARAM error rather than a segmentation fault (SIG-11). (S9G12-002632) [UNIX]

    • [V5.2-000A] Pre-allocation of xc_string_t is now allowed and is required for output-only parameters on external calls. Also see S9C10-002243. (S9G12-002634, C9F09-002753) [UNIX]

    • [V5.2-000A] ZSHOW "V" or ZWR when variables with "long" content no longer give a segmentation fault (SIG-11). This was fixed in V5.2-000 but the fix was not documented. (S9G12-002635)

    • - [V5.2-000A] $ZB now contains the correct value after a READ *. In particular, $ZB holds the full escape sequence after entry of an escape sequence when ESCAPE processing enabled. This was broken in GT.M V5.2-000. [AIX/Solaris/HPUX] (S9H02-002642)

    • [V5.2-000A] Exponents greater than 18 digits no longer result in a numeric evaluation of 0; for example in previous versions, WRITE +"1E12234567890123456789" produced 0. (S9F11-002573)

    • [V5.2-000A]The GT.M utilities and the mumps commands now use a space-dash (“ –“)combination to delimit/introduce a qualifier, which is standard UNIX usage, where they used to require only a dash ("-", which was not standard).

      [Warning]
      This will cause existing shell scripts that use the idiosyncratic dash-only form to break – they can be fixed by adding one or more spaces in front of any dash.

      This change allows the use of dashes in argument and qualifier values. [UNIX] (C9B04-001681)

    • [V5.2-000A] $ORDER() now returns the correct value even if the optional second argument is specified and contains a global reference. In such cases, previous versions used to perform the $ORDER() operation on the global reference in the second argument instead of the first.

      $REFERENCE is now set properly after a $ORDER() operation involving a global reference in the first or second argument. Previous versions used to set this incorrectly. For example $ORDER(^x(1)) used to incorrectly set $REFERENCE to ^x(1.00) instead of ^x(1). (C9B10-001744)

    • [V5.2-000A] $ORDER() now returns the correct value where the second argument is an extrinsic function that manipulates the first argument. In such cases, previous versions could give an incorrect result. For example, $ORDER(V(2,-1),$$ABC) where the extrinsic $$ABC() sets the node V(2,2) to 1 and quits with a value of 1 now returns a result of 2 where it used to incorrectly return a null string (""). Substituting ^V for V in the example demonstrates the change for global references. (C9B10-001765)

    • [V5.2-000A] $GET() with two arguments where both the arguments contain global references now sets the naked indicator correctly to the last global reference in the second argument. In cases where the first argument had a value, previous versions used to incorrectly set the naked indicator to that first argument. (C9B10-001767)

    • [V5.2-000A] The processing of SET commands with multiple targets and $Piece() / $Extract() now complies better with the M standard.

      GT.M now allows the $PIECE() and $EXTRACT functions as targets in a SET command that has a parenthesized, comma-separated list of targets. Previous versions disallowed this usage.

      When SET arguments have multiple parenthesized (set-left) targets and a target is used as a subscript in more than one item in the list of targets that follow, ALL the targets now use the before-SET value (not the after-SET value) in conformance to the M-standard. Previous versions of GT.M used the before-SET value only for the last such subscripted target item in the list and incorrectly used the after-SET value for all prior subscripted target items. For example, set a=0,(a,array1(a),array2(a))=2 now sets both array1(0) and array2(0) to 2 whereas previous versions of GT.M would set array2(0) to 2 and array1(2) (instead of array1(0)) to 2.

      If a SET target is of the form $PIECE(glvn,d,m,n) or $EXTRACT(glvn,m,n) GT.M now evaluates the right hand side of the Set even when m > n or n < 1. Previous versions of GT.M would not evaluate the right-hand-side of the SET which could result in the naked indicator not being set correctly. For example, set ^x=1,$piece(^a,";",3,2)=^b now correctly sets the naked indicator to point to the global ^b. Previous versions of GT.M set the naked indicator to ^x in this example. (C9C05-002003)

    • GT.M socket devices now allow up to the number of clients specified in the environment variable gtm_max_sockets. The default limit is 64, and there is an absolute maximum which at this point in human history exceeds your wildest dreams. $VIEW("MAX_SOCKETS") returns the current value. (C9C10-002149)

    • [V5.2-000A] ZWRITE with a range (n:m) no longer no longer occasionally fails with a segmentation fault (SIG-11). [AIX; Solaris] (C9D01-002239)

    • The maximum length for the argument to the ZSYSTEM command has increased to 4K bytes.[UNIX] (C9E09-002637)

    • [V5.2-000A] Messages and Recovery Procedures Manual is now current up to V5.2-000A. See http://www.fidelityinfoservices.com/user_documentation/V52AMsgRecProc/index.htm. (C9F07-002745)

    • OPEN of TCP device with an invalid address specification now gives an appropriate error rather than terminating the process. (C9G12-002808)

    • [V5.2-000A] Pattern match with multiple unbounded patterns where a lower bound after the first unbounded pattern is 7 (9 for V5.2-000) or more now gives the correct result. For example, in GT.M V5.2 (1.1?.n1"."9.n), and, in prior versions, (1.1?.n1"."7.n) incorrectly returned 1. (C9G12-002813)

    • [V5.2-000A] GT.M now reports complete error messages where in V5.2-000 utf-8 mode they were terminated at the first non-ASCII character. [HP-UX] (C9G12-002815)

    • [V5.2-000A] GT.M no longer inappropriately issues a GTM-E-GTMSECSHRSOCKET when it finds a socket conflict (usually because of an abandoned socket) for use in activating GTMSECSHR actions.[UNIX] (C9H03-002828)

    • [V5.2-000A] GT.M introduces a new deviceparameter called MOREREADTIME that applies to OPEN and USE commands for a SOCKET device. Except when a READ has a zero (0) timeout, MOREREADTIME specifies the time (in milliseconds) that a READ waits for input. + [V5.2-000A] $ZB now contains the correct value after a READ *. In particular, $ZB holds the full escape sequence after entry of an escape sequence when ESCAPE processing enabled. This was broken in GT.M V5.2-000. [AIX/Solaris/HPUX] (S9H02-002642)

    • [V5.2-000A] Exponents greater than 18 digits no longer result in a numeric evaluation of 0; for example in previous versions, WRITE +"1E12234567890123456789" produced 0. (S9F11-002573)

    • [V5.2-000A]The GT.M utilities and the mumps commands now use a space-dash (“ –“)combination to delimit/introduce a qualifier, which is standard UNIX usage, where they used to require only a dash ("-", which was not standard).

      [Warning]
      This will cause existing shell scripts that use the idiosyncratic dash-only form to break – they can be fixed by adding one or more spaces in front of any dash.

      This change allows the use of dashes in argument and qualifier values. [UNIX] (C9B04-001681)

    • [V5.2-000A] $ORDER() now returns the correct value even if the optional second argument is specified and contains a global reference. In such cases, previous versions used to perform the $ORDER() operation on the global reference in the second argument instead of the first.

      $REFERENCE is now set properly after a $ORDER() operation involving a global reference in the first or second argument. Previous versions used to set this incorrectly. For example $ORDER(^x(1)) used to incorrectly set $REFERENCE to ^x(1.00) instead of ^x(1). (C9B10-001744)

    • [V5.2-000A] $ORDER() now returns the correct value where the second argument is an extrinsic function that manipulates the first argument. In such cases, previous versions could give an incorrect result. For example, $ORDER(V(2,-1),$$ABC) where the extrinsic $$ABC() sets the node V(2,2) to 1 and quits with a value of 1 now returns a result of 2 where it used to incorrectly return a null string (""). Substituting ^V for V in the example demonstrates the change for global references. (C9B10-001765)

    • [V5.2-000A] $GET() with two arguments where both the arguments contain global references now sets the naked indicator correctly to the last global reference in the second argument. In cases where the first argument had a value, previous versions used to incorrectly set the naked indicator to that first argument. (C9B10-001767)

    • [V5.2-000A] The processing of SET commands with multiple targets and $Piece() / $Extract() now complies better with the M standard.

      GT.M now allows the $PIECE() and $EXTRACT functions as targets in a SET command that has a parenthesized, comma-separated list of targets. Previous versions disallowed this usage.

      When SET arguments have multiple parenthesized (set-left) targets and a target is used as a subscript in more than one item in the list of targets that follow, ALL the targets now use the before-SET value (not the after-SET value) in conformance to the M-standard. Previous versions of GT.M used the before-SET value only for the last such subscripted target item in the list and incorrectly used the after-SET value for all prior subscripted target items. For example, set a=0,(a,array1(a),array2(a))=2 now sets both array1(0) and array2(0) to 2 whereas previous versions of GT.M would set array2(0) to 2 and array1(2) (instead of array1(0)) to 2.

      If a SET target is of the form $PIECE(glvn,d,m,n) or $EXTRACT(glvn,m,n) GT.M now evaluates the right hand side of the Set even when m > n or n < 1. Previous versions of GT.M would not evaluate the right-hand-side of the SET which could result in the naked indicator not being set correctly. For example, set ^x=1,$piece(^a,";",3,2)=^b now correctly sets the naked indicator to point to the global ^b. Previous versions of GT.M set the naked indicator to ^x in this example. (C9C05-002003)

    • GT.M socket devices now allow up to the number of clients specified in the environment variable gtm_max_sockets. The default limit is 64, and there is an absolute maximum which at this point in human history exceeds your wildest dreams. $VIEW("MAX_SOCKETS") returns the current value. (C9C10-002149)

    • [V5.2-000A] ZWRITE with a range (n:m) no longer no longer occasionally fails with a segmentation fault (SIG-11). [AIX; Solaris] (C9D01-002239)

    • The maximum length for the argument to the ZSYSTEM command has increased to 4K bytes.[UNIX] (C9E09-002637)

    • [V5.2-000A] Messages and Recovery Procedures Manual is now current up to V5.2-000A. See http://www.fidelityinfoservices.com/user_documentation/V52AMsgRecProc/index.htm. (C9F07-002745)

    • OPEN of TCP device with an invalid address specification now gives an appropriate error rather than terminating the process. (C9G12-002808)

    • [V5.2-000A] Pattern match with multiple unbounded patterns where a lower bound after the first unbounded pattern is 7 (9 for V5.2-000) or more now gives the correct result. For example, in GT.M V5.2 (1.1?.n1"."9.n), and, in prior versions, (1.1?.n1"."7.n) incorrectly returned 1. (C9G12-002813)

    • [V5.2-000A] GT.M now reports complete error messages where in V5.2-000 utf-8 mode they were terminated at the first non-ASCII character. [HP-UX] (C9G12-002815)

    • [V5.2-000A] GT.M no longer inappropriately issues a GTM-E-GTMSECSHRSOCKET when it finds a socket conflict (usually because of an abandoned socket) for use in activating GTMSECSHR actions.[UNIX] (C9H03-002828)

    • [V5.2-000A] GT.M introduces a new deviceparameter called MOREREADTIME that applies to OPEN and USE commands for a SOCKET device. Except when a READ has a zero (0) timeout, MOREREADTIME specifies the time (in milliseconds) that a READ waits for input.

      • By default, MOREREADTIME is 10.
      • When MOREREADTIME is set to -1, it takes the default value of 10.
      • The maximum value of MORETREADTIME is 999 (basically 1 second). GTM triggers the MRTMAXEXCEEDED error if MOREREADTIME exceeds the maximum value.
      • Previous versions of GT.M used a fixed value of 200ms.
      [Note]
      This change may affect the operational behavior of TCP/IP aspects of your application. If the impact is adverse, specify a value of 200 milliseconds to restore the previous behavior.

      @@ -241,13 +241,13 @@ To implement approach 1 in MUMPS, specify a delimiter in an OPEN or USE command

      To implement approach 2, use a pair of fixed-length READs (READ #). Specifying a large value of MOREREADTIME is appropriate for Approach 1 and 2, but it tends to make Approach 3 work sub-optimally (except when it is implemented with zero timeout READ).

      Specify a short value of MOREREADTIME for Approach 3. However, when used together with Approach 1 and 2, it uses CPU less efficiently than otherwise.

      -
      [Warning]
      Never set MOREREADTIME to 0 as it may cause a CPU to "spin". (C9H03-002835)
      -

    • [V5.2-000B] +

      [Warning]
      Never set MOREREADTIME to 0 as it may cause a CPU to "spin". (C9H03-002835)
      +

    • [V5.2-000B] READ * in M-mode on Sequential Disk file and Socket device of a character with encoding between 128 to 255 inclusive now returns the correct code value. This fixes a problem introduced in V5.2-000 that resulted in READ * on those devices returning an incorrect (negative) value. (C9H04-002843)

    Return to top

    Utilities-MUPIP

    • The CHECKHEALTH, SHOWBACKLOG and SHUTDOWN qualifiers in a MUPIP REPLIC -SOURCE command now honor the value (if any) specified in the environment variable gtm_repl_instsecondary. [UNIX] (S9G07-002618)

    • MUPIP RUNDOWN now correctly uses an INFO message severity at its termination which prevents its hanging. This problem was introduced in V5.1-000 and is now fixed. [OpenVMS] (S9G07-002619)

    • MUPIP ENDIANCVT no longer terminates with an error while trying to convert a V5.0 format database. (S9G08-002621)

    • [V5.2-000A] MUPIP INTRPT command no longer causes the loss of data in the input buffer on a terminal READ or direct mode.

      If an interrupt (sent by the MUPIP INTRPT command) triggers code that does not resume from where the process was interrupted while a terminal READ is in progress, GT.M discards all input that the terminal READ received up to the time of that interrupt. ZSHOW "D" in a $ZINTERRUPT routine now includes a "ZINTERRUPT" designation for a terminal device if MUPIP INTRPT interrupted input on a terminal READ. Fidelity recommends that applications declare $ZINTERRPT routine specific $ETRAP/$ZTRAP error handlers in the interrupt processing code. -

      MUPIP INTRPT no longer causes the loss of previously received input on a terminal READ or direct mode. While GT.M processes an interrupt through the MUPIP INTRPT command, the only operation that GT.M permits on the current device ($IO) is the USE command with no deviceparameters. All other actions (CLOSE, OPEN, READ, WRITE) to that device trigger the ZINTRECURSEIO error. GT.M also triggers the ZINTDIRECT error for all attempts to BREAK into direct mode while that interrupt is processed. This allows the interrupt processing code to use another device and then restore the original device in an undisturbed state so that the interrupted application can resume as if uninterrupted (at least as far as the device behavior is concerned).[UNIX] (S9G12-002636)

    • [V5.2-000A] Both socket /WAIT (server side) and socket READ now respond to MUPIP INTRPT. A socket device performing a client connect operation does not currently respond to an INTRPT until the connection is complete. (C9G04-002779, S9G03-002602)

      [Important]
      Note that the TCP device is not changed and still does not respond to INTRPT. FIS recommends replacing the deprecated TCP device usage with the standard SOCKET device.

    • MUPIP ENDIANCVT now ensures that buffers in shared memory are flushed to disk and completes close of its output file before printing success. (C9G06-002799)

    • If the environment variable gtm_quiet_halt is set to 1, then if the process is stopped via MUPIP STOP or by a SIGTERM signal (as is sent by some web servers), the FORCEDHALT message will be suppressed as it is assumed that this is the "normal" way this type of process will terminate. Full robust process termination, database flush, cleanup etc will be performed as is normally done. [UNIX] (C9G12-002812)

    • [V5.2-000A] A Journal file's name can now include characters in Unicode™.[HP-UX] (C9G12-002814)

    • In rare cases where processes accessing a GT.M database were terminated abnormally, MUPIP RUNDOWN on that database could terminate prematurely with a SIG-11. This is now fixed.[UNIX] (C9F09-002755)

    • [V5.2-000A] Users now have the option to install GT.M with or without Unicode-related functionality. GT.M now installs components related to the M-mode only on a computer which does not have ICU. GT.M continues to require ICU for functionality related to UTF-8 mode. (C9H02-002821)

    • [V5.2-000A] GT.M now produces correct process initiation (“pini”) records in a journal file created during a recovery from an event that happens to interrupt a database file extension, where in prior versions this rare occurrence could result in an incorrect record. Such an incorrect record would not generally be noticed in M mode, but could cause a BADCHAR error in UTF-8 mode. (C9H03-002832)

    • [V5.2-000A] In a backward rollback/recovery GT.M now avoids counting blocks requiring a V4 to V5 upgrade more than once when the action is interrupted and reissued more than once. In prior versions, a MUPIP INTEG of the recovered database could report a benign DBBTUWRNG integrity error, which it then automatically fixed. [UNIX] (C9H03-002836)

    +

    MUPIP INTRPT no longer causes the loss of previously received input on a terminal READ or direct mode. While GT.M processes an interrupt through the MUPIP INTRPT command, the only operation that GT.M permits on the current device ($IO) is the USE command with no deviceparameters. All other actions (CLOSE, OPEN, READ, WRITE) to that device trigger the ZINTRECURSEIO error. GT.M also triggers the ZINTDIRECT error for all attempts to BREAK into direct mode while that interrupt is processed. This allows the interrupt processing code to use another device and then restore the original device in an undisturbed state so that the interrupted application can resume as if uninterrupted (at least as far as the device behavior is concerned).[UNIX] (S9G12-002636)

  • [V5.2-000A] Both socket /WAIT (server side) and socket READ now respond to MUPIP INTRPT. A socket device performing a client connect operation does not currently respond to an INTRPT until the connection is complete. (C9G04-002779, S9G03-002602)

    [Important]
    Note that the TCP device is not changed and still does not respond to INTRPT. FIS recommends replacing the deprecated TCP device usage with the standard SOCKET device.

  • MUPIP ENDIANCVT now ensures that buffers in shared memory are flushed to disk and completes close of its output file before printing success. (C9G06-002799)

  • If the environment variable gtm_quiet_halt is set to 1, then if the process is stopped via MUPIP STOP or by a SIGTERM signal (as is sent by some web servers), the FORCEDHALT message will be suppressed as it is assumed that this is the "normal" way this type of process will terminate. Full robust process termination, database flush, cleanup etc will be performed as is normally done. [UNIX] (C9G12-002812)

  • [V5.2-000A] A Journal file's name can now include characters in Unicode™.[HP-UX] (C9G12-002814)

  • In rare cases where processes accessing a GT.M database were terminated abnormally, MUPIP RUNDOWN on that database could terminate prematurely with a SIG-11. This is now fixed.[UNIX] (C9F09-002755)

  • [V5.2-000A] Users now have the option to install GT.M with or without Unicode-related functionality. GT.M now installs components related to the M-mode only on a computer which does not have ICU. GT.M continues to require ICU for functionality related to UTF-8 mode. (C9H02-002821)

  • [V5.2-000A] GT.M now produces correct process initiation (“pini”) records in a journal file created during a recovery from an event that happens to interrupt a database file extension, where in prior versions this rare occurrence could result in an incorrect record. Such an incorrect record would not generally be noticed in M mode, but could cause a BADCHAR error in UTF-8 mode. (C9H03-002832)

  • [V5.2-000A] In a backward rollback/recovery GT.M now avoids counting blocks requiring a V4 to V5 upgrade more than once when the action is interrupted and reissued more than once. In prior versions, a MUPIP INTEG of the recovered database could report a benign DBBTUWRNG integrity error, which it then automatically fixed. [UNIX] (C9H03-002836)

    • Return to top

    Utilities-Other Than MUPIP

    • The INSTALL script no longer terminates prematurely on some HP-UX systems.[HP-UX] (S9G11-002627)

    • DSE ALL -DUMP [-ALL] now dumps the fileheader for all regions in the global directory. The -ALL qualifier selects the comprehensive format. The default is the briefer format. The -DUMP qualifier can only be intermixed with the -ALL qualifier. (C9G04-002784)

    • [V5.2-000A] DBCERTIFY CERTIFY now correctly handles all conditions that lead to a split in the root level of a global variable tree. Previously these (fortunately rare) conditions triggered occasional spurious DBCMODBLK2BIG errors and the only workaround was to revert to a V4 format database and then repeat the scan/upgrade process. DBCERTIFY now always operates in M mode, while in V5.2-000 it could inappropriately attempt to operate in UTF-8 mode.

      Also, the V5CBSU utility no longer triggers an occasional spurious INVFCN errors when it encounters a character with encoding in the range of 128-255. This problem was specific to V5.2-000 version only. [UNIX] (C9G04-002790)

    Return to top

    Error Messages

    Return to top

    BADCASECODE

    diff --git a/articles/GTM_V5.3-000_Release_Notes.html b/articles/GTM_V5.3-000_Release_Notes.html index f2ffc93..478ffbf 100644 --- a/articles/GTM_V5.3-000_Release_Notes.html +++ b/articles/GTM_V5.3-000_Release_Notes.html @@ -78,7 +78,7 @@

    11.11

    GT.M supports UTF-8 mode and M mode on this platform.

    -
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent Fidelity from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. Fidelity understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.
    +
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent Fidelity from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. Fidelity understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.

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

    @@ -100,7 +100,7 @@

    5.2/5.3

    		 -
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent Fidelity from testing 4-byte UTF-8 characters more comprehensively on this platform than on others.
    +
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent Fidelity from testing 4-byte UTF-8 characters more comprehensively on this platform than on others.

    Sun SPARC Solaris

    @@ -156,7 +156,7 @@

    4-byte (32 bit)

    gtm_uint_t has 32 bit length on all platforms

    -
    [Caution]
    If your interface uses gtm_long_t or gtm_ulong_t types but your interface code uses int or signed int types, failure to revise the types so they match on a 64 bit platform will cause the code to fail in unpleasant and potentially dangerous and hard to diagnose ways. In testing, GTMASSERT and SEGV (signal-11) errors were most common caused by storage chain (malloc) corruption failures.

    Internationalization (Collation)

    +
    [Caution]
    If your interface uses gtm_long_t or gtm_ulong_t types but your interface code uses int or signed int types, failure to revise the types so they match on a 64 bit platform will cause the code to fail in unpleasant and potentially dangerous and hard to diagnose ways. In testing, GTMASSERT and SEGV (signal-11) errors were most common caused by storage chain (malloc) corruption failures.

    Internationalization (Collation)

    Parameter type

    32-Bit

    @@ -172,7 +172,7 @@

    8-byte (64-bit)

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

    -
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    +
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    Parameter type

    32-Bit

    @@ -188,7 +188,7 @@

    8-byte (64-bit)

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

    -
    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled in the 64-bit environment, the source is identical to the 32-bit editions.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On the Linux platform, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    • Relink all object files after recompiling all M and C source files.

    Return to top

    Global Directory Upgrade

    Users who upgrade from GT.M V5.0-000 or later do not require a global directory upgrade.

    Users on the Integrity IA64 platforms must create new global directories as the format on 64 bit editions differs from 32 bit editions.

    Users who upgrade from a GT.M version prior to V5.0-000 require a global directory upgrade because the V5 global directory format is different from a V4 global directory format. When a user opens a V4 global directory with the V5 GDE utility program, even if they make no changes, an EXIT command automatically replaces the V4 format global directory file with a V5 format global directory file.

    [Note]
    Fidelity strongly recommends users make a copy of any global directory before upgrading it. There is no way to downgrade a global directory from V5 format to V4 format.

    If a user inadvertently opens V4 global directory with a V5 GDE with no intention of upgrading it, then execute the QUIT command rather than the EXIT command.

    If a user inadvertently upgrades a global directory, then perform the following steps:

    1. Open the global directory with V5 GDE.
    2. Execute the SHOW ALL command.
    3. Then, edit the output into a command file or manually enter the commands corresponding to the output into a V4 GDE invocation.

    Return to top

    Database Upgrade

    Users who upgrade from a GT.M version prior to V5.0-000 need to perform a database upgrade. See Database Migration Technical Bulletin (Database Migration Technical Bulletin) for more information on the database upgrade procedure. No database upgrade is necessary for users who upgrade from GT.M V5.0-000 or later.

    [Note]
    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Return to top

    Installation Instructions

    See the "Installing GT.M" section in the GT.M Administration and Operations Guide.

    UNIX

    1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version. Users who overwrite an existing GT.M installation with a new version must shut down all processes using the old version.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to bring down any open database files.

    3. In UNIX editions, make sure gtmsecshr is not running. If found running, perform kill <pid of gtmsecshr>.

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

    4. In UNIX editions, the GT.M configure script asks the following question:

      Enter the RC node ID of the GT.CM server, if desired (42).

    5. Respond by pressing ENTER.

    Additional Information for AIX

    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:

    • +

    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled in the 64-bit environment, the source is identical to the 32-bit editions.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On the Linux platform, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    Return to top

    Relink

    • Relink all object files after recompiling all M and C source files.

    Return to top

    Global Directory Upgrade

    Users who upgrade from GT.M V5.0-000 or later do not require a global directory upgrade.

    Users on the Integrity IA64 platforms must create new global directories as the format on 64 bit editions differs from 32 bit editions.

    Users who upgrade from a GT.M version prior to V5.0-000 require a global directory upgrade because the V5 global directory format is different from a V4 global directory format. When a user opens a V4 global directory with the V5 GDE utility program, even if they make no changes, an EXIT command automatically replaces the V4 format global directory file with a V5 format global directory file.

    [Note]
    Fidelity strongly recommends users make a copy of any global directory before upgrading it. There is no way to downgrade a global directory from V5 format to V4 format.

    If a user inadvertently opens V4 global directory with a V5 GDE with no intention of upgrading it, then execute the QUIT command rather than the EXIT command.

    If a user inadvertently upgrades a global directory, then perform the following steps:

    1. Open the global directory with V5 GDE.
    2. Execute the SHOW ALL command.
    3. Then, edit the output into a command file or manually enter the commands corresponding to the output into a V4 GDE invocation.

    Return to top

    Database Upgrade

    Users who upgrade from a GT.M version prior to V5.0-000 need to perform a database upgrade. See Database Migration Technical Bulletin (Database Migration Technical Bulletin) for more information on the database upgrade procedure. No database upgrade is necessary for users who upgrade from GT.M V5.0-000 or later.

    [Note]
    The global directory in use at the time of database upgrade MUST have a mapping of globals to databases that exactly matches the globals that are actually resident in those databases. Some sites have more than one global directory with some having reduced or changed mappings such that, for example, a database may have more than one global in it but the global directory mapping has only a single global in it. This situation can potentially cause the database upgrade procedure to fail because database certification was not correctly processed. A sign that this could be an issue is if MUPIP REORG UPGRADE or a GT.M process fails with the DYNUPGRDFAIL message (block has insufficient room for expansion) after the V5 upgrade.

    Return to top

    Installation Instructions

    See the "Installing GT.M" section in the GT.M Administration and Operations Guide.

    UNIX

    1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version. Users who overwrite an existing GT.M installation with a new version must shut down all processes using the old version.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to bring down any open database files.

    3. In UNIX editions, make sure gtmsecshr is not running. If found running, perform kill <pid of gtmsecshr>.

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

    4. In UNIX editions, the GT.M configure script asks the following question:

      Enter the RC node ID of the GT.CM server, if desired (42).

    5. Respond by pressing ENTER.

    Additional Information for AIX

    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 in one of the following modes:

    • smit aio (for gui mode) or @@ -199,7 +199,7 @@

      Users who 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 must execute the same command after installing the new version of GT.M before using it. Users who define the GT.M commands to the system other than during the installation of GT.M need to 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 to match the proper GTMCOMMANDS.CLD with the version of GT.M being used.

    Post Installation Instructions

    When you complete the installation of V5.3-000, run the MUPIP REORG -UPDATE command.

    If you have upgraded from a pre-V5 version to V5.3-000, then the MUPIP REORG -UPDATE command upgrades all the blocks.

    If you have upgraded from another V5 version to V5.3-000, the MUPIP REORG -UPDATE command cleans those recycled database blocks that escaped prior upgrade activities. This command also adjusts the file header to stop log message like the following:

     GTM[iiii]: %GTM-W-DBVERPERFWARN2, Peformance warning: Database /home/voet/EHR/g/mumps.dat is not fully upgraded. 
 Run MUPIP REORG UPGRADE for best overall performance -- generated from 0xaaaaaaaa
-

    where iiii is a process id and aaaaaaaa is a hexadecimal address that depends on your platform.

    Managing M mode and UTF-8 mode

    On a system that does not have ICU installed, GT.M assumes M mode operation and installs M mode components only.

    On a system that has ICU installed, GT.M installs both M mode and UTF-8 mode components and an additional utf8 subdirectory. The technique that GT.M uses to separate M mode and UTF-8 mode object files is as follows:

    From the same source file, the GT.M compiler generates an object file for M mode or UTF-8 mode depending on the value of the environment variable gtm_chset. 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. GT.M processes trigger an error if the object file was generated with a different setting of gtm_chset/$ZCHset than the current value.

    Always generate an M object module with a value of gtm_chset that matches the value that a process executing that module will have. As the GT.M product contains M utility programs, their object files must conform to this rule. In order for the users to be able to use both M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 "flavors" of object modules exist and can be found in known locations. The technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use. Users should consider a similar pattern for structuring application object code repositories.

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

    • Most GT.M (mumps, mupip, dse, lke, and so on) are in the parent directory, that is, the location specified by the environment variable gtm_dist.

    • Object files for programs written in M (GDE, utilities) have two versions-- one compiled for support of Unicode™ in the utf8 subdirectory, and one compiled without support of Unicode™ in the parent directory. Installing GT.M (V5.2-000 and above) generates both the versions of object files. Note that GT.M generates the object files for utf8 subdirectory only if ICU 3.6 is installed on the system.

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

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

      • If gtm_chset is "m", "M" or undefined, there is no change to the environment from the previous versions.

      • If gtm_chset is "UTF-8",

        • $gtm_dist is set to the utf8 subdirectory (that is, if GT.M is installed in /usr/local/gtm_V5.2-001, then $gtm_dist is set to /usr/local/gtm_V5.2-001/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.

    Setting the environment variable TERM

    Users must set the environment variable TERM to 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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

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

    Return to top

    V5.3-000 Change History

    Fixes and enhancements specific to V5.3-000 are:

    S9H05-002658
    S9H08-002667
    S9H08-002668
    C9B11-001813
    C9B11-001813A
    C9C11-002165
    C9D07-002357
    C9E05-002604
    C9F09-002753
    C9F10-002762
    C9H05-002863
    C9H07-002873
    C9H07-002876
    C9H07-002883
    C9H08-002888
    C9H08-002890
    C9H09-002901
    C9H09-002905

    Return to top

    M-Database Access

    +

    where iiii is a process id and aaaaaaaa is a hexadecimal address that depends on your platform.

    Managing M mode and UTF-8 mode

    On a system that does not have ICU installed, GT.M assumes M mode operation and installs M mode components only.

    On a system that has ICU installed, GT.M installs both M mode and UTF-8 mode components and an additional utf8 subdirectory. The technique that GT.M uses to separate M mode and UTF-8 mode object files is as follows:

    From the same source file, the GT.M compiler generates an object file for M mode or UTF-8 mode depending on the value of the environment variable gtm_chset. 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. GT.M processes trigger an error if the object file was generated with a different setting of gtm_chset/$ZCHset than the current value.

    Always generate an M object module with a value of gtm_chset that matches the value that a process executing that module will have. As the GT.M product contains M utility programs, their object files must conform to this rule. In order for the users to be able to use both M mode and UTF-8 mode, the GT.M installation ensures that both M and UTF-8 "flavors" of object modules exist and can be found in known locations. The technique of segregating the object modules by their compilation mode prevents both frequent recompiles and errors in installations where both modes are in use. Users should consider a similar pattern for structuring application object code repositories.

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

    • Most GT.M (mumps, mupip, dse, lke, and so on) are in the parent directory, that is, the location specified by the environment variable gtm_dist.

    • Object files for programs written in M (GDE, utilities) have two versions-- one compiled for support of Unicode™ in the utf8 subdirectory, and one compiled without support of Unicode™ in the parent directory. Installing GT.M (V5.2-000 and above) generates both the versions of object files. Note that GT.M generates the object files for utf8 subdirectory only if ICU 3.6 is installed on the system.

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

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

      • If gtm_chset is "m", "M" or undefined, there is no change to the environment from the previous versions.

      • If gtm_chset is "UTF-8",

        • $gtm_dist is set to the utf8 subdirectory (that is, if GT.M is installed in /usr/local/gtm_V5.2-001, then $gtm_dist is set to /usr/local/gtm_V5.2-001/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.

    Setting the environment variable TERM

    Users must set the environment variable TERM to 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.

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. Users may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

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

    Return to top

    V5.3-000 Change History

    Fixes and enhancements specific to V5.3-000 are:

    S9H05-002658
    S9H08-002667
    S9H08-002668
    C9B11-001813
    C9B11-001813A
    C9C11-002165
    C9D07-002357
    C9E05-002604
    C9F09-002753
    C9F10-002762
    C9H05-002863
    C9H07-002873
    C9H07-002876
    C9H07-002883
    C9H08-002888
    C9H08-002890
    C9H09-002901
    C9H09-002905

    Return to top

    M-Database Access

    • GT.M now handles name-level $ORDER(gvn,-1) and $ZPREVIOUS(gvn) operations which move between database regions appropriately. In prior versions, if the region holding global name specified in the argument had a smaller maximum key size than the region holding the result, it could cause process memory corruption and possible shared memory corruption, which could, in turn, cause database corruption. (S9H05-002658)

    • Before-image journaling now writes a correct checksum on journal records in a few cases where it formerly did not, which would cause MUPIP RECOVER/ROLLBACK to issue a "Checksum validation failed" error. This issue was reported as fixed in GT.M V5.0-000D as part of C9F10-002762 but this item addresses a few rare cases that remained. (C9F10-002762)

    • GT.M now timestamps journal records such that the times never decrease in the record sequence. Prior versions of GT.M could, in rare cases, write journal records with out-of-order timestamps when recording transactions that used ZTSTART/ZTCOMMIT semantics, which could cause problems with backward journal recovery. Note that FIS strongly recommends TSTART/TCOMMIT transaction processing over ZTSTART/ZTCOMMIT. (C9E05-002604)

    • diff --git a/articles/GTM_V5.3-001A_Release_Notes.html b/articles/GTM_V5.3-001A_Release_Notes.html index 823037d..0579d50 100644 --- a/articles/GTM_V5.3-001A_Release_Notes.html +++ b/articles/GTM_V5.3-001A_Release_Notes.html @@ -47,7 +47,7 @@

    -

    Table of Contents

    Typographical Conventions
    Bulletin Overview
    Platforms
    Migrating to 64-bit platforms
    Call-ins and External Calls
    Internationalization (Collation)
    Environment Translation
    Recompile
    Rebuild Shared Libraries or Images
    Global Directory Upgrade
    Additional Installation Instructions
    UNIX
    OpenVMS
    Database Upgrade Procedure
    Pre V5.0-000 to V5.3*
    V5.0*/V5.1*/V5.2* to V5.3*
    Managing M mode and UTF-8 mode
    Setting the environment variable TERM
    Change History
    V5.3-001A
    V5.3-001
    M-Database Access
    M-Other Than Database Access
    Utilities- MUPIP
    Utilities-Other Than MUPIP
    Error Messages
    GTMSECSHRTMPPATH
    OPCOMMISSED [V5.3-001A]

    Return to top

    Typographical Conventions

    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: The 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 [ ].

    Return to top

    Bulletin Overview

    +

    Table of Contents

    Typographical Conventions
    Bulletin Overview
    Platforms
    Migrating to 64-bit platforms
    Call-ins and External Calls
    Internationalization (Collation)
    Environment Translation
    Recompile
    Rebuild Shared Libraries or Images
    Global Directory Upgrade
    Additional Installation Instructions
    UNIX
    OpenVMS
    Database Upgrade Procedure
    Pre V5.0-000 to V5.3*
    V5.0*/V5.1*/V5.2* to V5.3*
    Managing M mode and UTF-8 mode
    Setting the environment variable TERM
    Change History
    V5.3-001A
    V5.3-001
    M-Database Access
    M-Other Than Database Access
    Utilities- MUPIP
    Utilities-Other Than MUPIP
    Error Messages
    GTMSECSHRTMPPATH
    OPCOMMISSED [V5.3-001A]

    Return to top

    Typographical Conventions

    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: The 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 [ ].

    Return to top

    Bulletin Overview

    V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to defects, including an issue with NOUNDEF handling, an issue with TP transactions that include multiple global directories, as well as some other issues.

    GT.M V5.3-001 introduced support for 64-bit GT.M processes to x86_64 GNU/Linux and IBM pSeries AIX.

    For a brief description of the fixes and enhancements in this release, see section Change History.

    [Note]
    Placing databases on raw partitions is no longer supported, and references thereto will be removed in the next update to the user documentation. Although the GT.M team is fastidious about maintaining upward compatibility, in this case, we are aware of no customer who is using GT.M on a raw partition. If you are a GT.M customer using raw partitions for GT.M databases, please contact GT.M Support (gtmsupport@fnis.com) as soon as possible.

    Return to top

    Platforms

    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.

    @@ -67,7 +67,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    11V2(11.23)

    Database performance may be unsatisfactory unless you apply patch PHKL_37279

    -
    [Warning]
    V5.3-0001A does not properly support the SOCKET devices when used with 11V3 (11.31); this will be addressed in the next release. We are aware of no other issues with 11.31, but consider it not formally Supported for V5.3-001A.
    +
    [Warning]
    V5.3-0001A does not properly support the SOCKET devices when used with 11V3 (11.31); this will be addressed in the next release. We are aware of no other issues with 11.31, but consider it not formally Supported for V5.3-001A.

    IA64 GNU/Linux - Red Hat Enterprise Linux

    @@ -84,7 +84,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    11.11

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

    -
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.
    +
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.

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

    @@ -112,7 +112,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    Although AIX 5.2 and 5.3 are the officially supported releases, we are not aware of any reason why GT.M V5.3-001A will not run on AIX 6.x.

    -
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.
    +
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.

    Sun SPARC Solaris

    @@ -178,7 +178,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    4-byte

    gtm_uint_t has 32 bit length on all platforms

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

    Internationalization (Collation)

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

    Internationalization (Collation)

    Parameter type

    32-Bit

    @@ -194,7 +194,7 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

    -
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    +
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    Parameter type

    32-Bit

    @@ -210,9 +210,9 @@ V5.3-001A is a minor release derived from V5.3-001, and provides timely fixes to

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

    -
    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    Return to top

    Rebuild Shared Libraries or Images

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

    Return to top

    Global Directory Upgrade

    Global directory formats differ for 32- and 64-bit GT.M platforms. This means that:

    • The global directory format differs between GT.M on x86 GNU/Linux and that of x86_64 GNU/Linux.
    • On AIX, the global directory format differs between GT.M on V5.3-001 and prior versions.

    +

    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. The GT.M team will address this in a future release. (C9H10-002924)

    Return to top

    Rebuild Shared Libraries or Images

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

    Return to top

    Global Directory Upgrade

    Global directory formats differ for 32- and 64-bit GT.M platforms. This means that:

    • The global directory format differs between GT.M on x86 GNU/Linux and that of x86_64 GNU/Linux.
    • On AIX, the global directory format differs between GT.M on V5.3-001 and prior versions.

    Furthermore, on Itanium platforms, there is a difference in global directory formats between V5.3-000 and V5.3-001. -

    Except for the above cases, you do not require a global directory upgrade when moving up from GT.M V5.0-000 or later.

    Moving up from a GT.M version prior to V5.0-000, from a 32-bit global directory to a 64-bit global directory, or on Itanium platforms migrating from V5.3-000 to V5.3-001 requires a global directory upgrade. Opening a global directory with the GDE utility program from the latest GT.M version (or the 64-bit x86_64 format for that platform), followed by an EXIT command automatically, even with no other intervening commands, upgrades the global directory.

    [Note]
    FIS strongly recommends you make a copy of any global directory before upgrading it. There is no way to downgrade a global directory to an earlier format.

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

    If you inadvertently upgrade a global directory, perform the following steps:

    1. Open the global directory with GDE from the current version.
    2. Execute the SHOW ALL command.
    3. Create a command file, or manually enter the commands corresponding to the output, into GDE from the prior GT.M version.

    Return to top

    Additional Installation Instructions

    For installing GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide.

    UNIX

    1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version. If you must overwrite an existing GT.M installation with a new version you must first shut down all processes using the old version. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-001A in /opt/lsb-gtm/V5.3-001A on Linux systems.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

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

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

    GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. Before installing GT.M on IBM pSeries AIX, run the following command to check the filesets of this facility:

    • +

      Except for the above cases, you do not require a global directory upgrade when moving up from GT.M V5.0-000 or later.

      Moving up from a GT.M version prior to V5.0-000, from a 32-bit global directory to a 64-bit global directory, or on Itanium platforms migrating from V5.3-000 to V5.3-001 requires a global directory upgrade. Opening a global directory with the GDE utility program from the latest GT.M version (or the 64-bit x86_64 format for that platform), followed by an EXIT command automatically, even with no other intervening commands, upgrades the global directory.

      [Note]
      FIS strongly recommends you make a copy of any global directory before upgrading it. There is no way to downgrade a global directory to an earlier format.

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

      If you inadvertently upgrade a global directory, perform the following steps:

      1. Open the global directory with GDE from the current version.
      2. Execute the SHOW ALL command.
      3. Create a command file, or manually enter the commands corresponding to the output, into GDE from the prior GT.M version.

    Return to top

    Additional Installation Instructions

    For installing GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide.

    UNIX

    1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version. If you must overwrite an existing GT.M installation with a new version you must first shut down all processes using the old version. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-001A in /opt/lsb-gtm/V5.3-001A on Linux systems.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

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

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

    GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. 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 in one of the following modes:

    • smit aio (for gui mode) or @@ -236,9 +236,9 @@ gmake gmake check gmake install

    • 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 the /usr/local directory.

    [Note]
    By default, ICU is installed in /usr/local. If you install ICU in a different directory, type: -
    • runConfigureICU HP-UX/ACC --prefix=<install_path> --enable-64bit-libs  --enable-rpath –disable-threads
    • Then execute the gmake commands, and set the environment variable LD_LIBRARY_PATH to point to the appropriate location.

    Return to top

    Setting the environment variable TERM

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

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

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

    Return to top

    Change History

    Return to top

    V5.3-001A

    Fixes and enhancements specific to V5.3-001A are:

    S9I03-002674
    S9I03-002675
    S9I03-002676
    C9C11-002181
    C9D01-002232
    C9D01-002234
    C9E04-002596
    C9E08-002617
    C9I02-002956
    C9I02-002959
    C9I02-002960
    C9I02-002963
    C9I03-002964
    C9I03-002967
    C9I03-002969
    C9I03-002971

    These fixes are marked with [V5.3-001A] in the subsequent sections.

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

    S9E08-002478
    S9G12-002633
    S9H11-002670
    C9B03-001664
    C9D10-002409
    C9G04-002788
    C9H07-002880
    C9H09-002899
    C9H09-002900
    C9H10-002916
    C9H10-002918
    C9H10-002923
    C9H11-002926
    C9H11-002927
    C9H11-002932
    C9H12-002934
    C9I01-002938
    C9I01-002939

    Return to top

    M-Database Access

    +

    • runConfigureICU HP-UX/ACC --prefix=<install_path> --enable-64bit-libs  --enable-rpath –disable-threads
    • Then execute the gmake commands, and set the environment variable LD_LIBRARY_PATH to point to the appropriate location.

    Return to top

    Setting the environment variable TERM

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

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation.The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

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

    Return to top

    Change History

    Return to top

    V5.3-001A

    Fixes and enhancements specific to V5.3-001A are:

    S9I03-002674
    S9I03-002675
    S9I03-002676
    C9C11-002181
    C9D01-002232
    C9D01-002234
    C9E04-002596
    C9E08-002617
    C9I02-002956
    C9I02-002959
    C9I02-002960
    C9I02-002963
    C9I03-002964
    C9I03-002967
    C9I03-002969
    C9I03-002971

    These fixes are marked with [V5.3-001A] in the subsequent sections.

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

    S9E08-002478
    S9G12-002633
    S9H11-002670
    C9B03-001664
    C9D10-002409
    C9G04-002788
    C9H07-002880
    C9H09-002899
    C9H09-002900
    C9H10-002916
    C9H10-002918
    C9H10-002923
    C9H11-002926
    C9H11-002927
    C9H11-002932
    C9H12-002934
    C9I01-002938
    C9I01-002939

    Return to top

    M-Database Access

    • The Linux version of GT.M can now utilize O_DIRECT support for journal files. The O_DIRECT option is made available by using the sync_io option to the MUPIP SET -JOURNAL command just as for the other platforms that support direct I/O. [Linux] (C9D10-002409) -

    • [V5.3-001A] GT.M now appropriately handles TP transactions that include multiple global directories (due to SET $ZGBLdir or extended references) having multiple regions that map to the same database file. Previous versions could, in rare cases, terminate the GT.M process abnormally with TPFAIL or SIG-11 errors (ACCVIO in VMS) and damage the database if TP transactions accessed global variables in such a database files via different global directories.

      [Note]
      If you use the VIEW "NOISOLATION" command to turn NOISOLATION characteristics ON for a global name in one global directory and turn it OFF for the same name in a different global directory and if the two global directories map the global name to the same database file, then GT.M leaves NOISOLATION OFF if any path specifies OFF, irrespective of the order of the specifying VIEW command. (C9E04-002596)

    • After changing $ZGBLDIR, $VIEW() now properly reflects the current value of $ZGBLDIR even with no intervening global variable access. Previously this sequence could give an incorrect answer, or a memory access violation with the workaround being to perform an intervening global variable access. (C9H09-002900)

    • The GT.M database critical section lock wakeup mechanism has been enhanced to use memory semaphores. Previous versions used a socket-based scheme for wakeup. In some cases this led to processes being blocked trying to wake other processes up. This is no longer an issue in the new scheme. Since memory semaphores were introduced in 2.6 kernels, running GT.M on 2.4 kernels now requires a kernel which has had memory semaphores back-ported from 2.6. Note that contemporary releases of major Linux distributions use 2.6 kernels. [Linux] (C9H10-002918).

    • GT.M now avoids restarting a TP transaction in some additional cases where the global variable it is planning on updating has NOISOLATION turned ON even though it has been concurrently updated thereby improving GT.M transaction throughput rates. (C9I01-002938)

    • TP transactions now do not sleep between TP restarts thereby improving GT.M transaction throughput rates. Previously they used to sleep for a short time between every restart potentially resulting in inefficient use of system resources. (C9I01-002939)

    • [V5.3-001A] Using TSTART with no prior global reference now works if you precede it with a SET $ZGBLDIR command and no intervening database references. In previous GT.M versions, such an unusual usage would terminate a GT.M process abnormally with SIG-11 (ACCVIO in VMS) errors. (C9I02-002963)

    • [V5.3-001A] +

    • [V5.3-001A] GT.M now appropriately handles TP transactions that include multiple global directories (due to SET $ZGBLdir or extended references) having multiple regions that map to the same database file. Previous versions could, in rare cases, terminate the GT.M process abnormally with TPFAIL or SIG-11 errors (ACCVIO in VMS) and damage the database if TP transactions accessed global variables in such a database files via different global directories.

      [Note]
      If you use the VIEW "NOISOLATION" command to turn NOISOLATION characteristics ON for a global name in one global directory and turn it OFF for the same name in a different global directory and if the two global directories map the global name to the same database file, then GT.M leaves NOISOLATION OFF if any path specifies OFF, irrespective of the order of the specifying VIEW command. (C9E04-002596)

    • After changing $ZGBLDIR, $VIEW() now properly reflects the current value of $ZGBLDIR even with no intervening global variable access. Previously this sequence could give an incorrect answer, or a memory access violation with the workaround being to perform an intervening global variable access. (C9H09-002900)

    • The GT.M database critical section lock wakeup mechanism has been enhanced to use memory semaphores. Previous versions used a socket-based scheme for wakeup. In some cases this led to processes being blocked trying to wake other processes up. This is no longer an issue in the new scheme. Since memory semaphores were introduced in 2.6 kernels, running GT.M on 2.4 kernels now requires a kernel which has had memory semaphores back-ported from 2.6. Note that contemporary releases of major Linux distributions use 2.6 kernels. [Linux] (C9H10-002918).

    • GT.M now avoids restarting a TP transaction in some additional cases where the global variable it is planning on updating has NOISOLATION turned ON even though it has been concurrently updated thereby improving GT.M transaction throughput rates. (C9I01-002938)

    • TP transactions now do not sleep between TP restarts thereby improving GT.M transaction throughput rates. Previously they used to sleep for a short time between every restart potentially resulting in inefficient use of system resources. (C9I01-002939)

    • [V5.3-001A] Using TSTART with no prior global reference now works if you precede it with a SET $ZGBLDIR command and no intervening database references. In previous GT.M versions, such an unusual usage would terminate a GT.M process abnormally with SIG-11 (ACCVIO in VMS) errors. (C9I02-002963)

    • [V5.3-001A] GT.M now closes journaling and continues with database updates even if:

      • it encounters errors (for example, insufficient disk space errors ) while writing to the journal file, and
      • it is holding the critical section lock on the database file. If GT.M does not hold the critical section lock on the database file, then it waits in a sleep loop until it successfully writes to the journal file.
      @@ -264,18 +264,18 @@ Jan 23 17:17:40 host1 GTM[18950]: %GTM-I-GTMSECSHRTMPPATH, gtmsecshr path is /se Jan 23 17:17:40 host1 GTM[18964]: %GTM-F-GTMSECSHRSTART, Server - 18964 : gtmsecshr failed to startup, %GTM-I-TEXT, server already running, %SYSTEM-E-ENO11, Resource temporarily unavailable -- generated from 0x0804D275. Jan 23 17:17:40 host1 GTM[18964]: %GTM-I-GTMSECSHRTMPPATH, gtmsecshr path is /secshrpath/two, %GTM-I-TEXT, (from $gtm_tmp) -- generated from 0x0804D2E4. -

    • [V5.3-001A] GT.M now handles name indirection and call-ins in an a wholesome way. In V5.3-001, an inconsistency in handling these operations in NOUNDEF mode could cause various misfortunes including out of memory conditions and segmentation faults (SIG-11/ACCVIO). (S9I03-002674)

    • [V5.3-001A] GT.M now suppresses STACKCRIT errors in the current frame at the time of the error. Previously, GT.M suppressed STACKCRIT errors in stack levels invoked because of an error, but this did not cover the GOTO implicit in $ETRAP processing or any explicit GOTO or ZGOTO in a $ZTRAP that placed control at the original stack level of the error. (S9I03-002676)

      GT.M now signals the STACKCRIT error when a process has 16K stack space left available. This gives processes more opportunity to recover and trim the stack using QUIT, ZGOTO, or HALT. Previous versions used to display the STACKCRIT message when there was 1K stack space left. [UNIX] (S9I03-002676)

    • GT.M introduces a new environment variable gtm_noundef. If it is defined, and evaluates to a non-zero integer, the string "TRUE", or the string "YES" (or any case independent leading substrings thereof), then GT.M, at process startup, treats undefined variables as having an implicit value of an empty string. Otherwise, GT.M triggers an error on an attempt to use the value of an undefined variable. Previously the only way to alter this behavior of undefined variables was to use the UNDEF or NOUNDEF arguments of the VIEW command.

      [Note]
      To establish the behavior of undefined variables on OpenVMS, set "GTM$UNDEF_INHIBIT == 1" in GTM$DEFAULTS.M64 to treat undefined variables as having a null value or set "GTM$UNDEF_INHIBIT == 0" to trigger an error on an attempt to use the value of an undefined variable.

      Running with VIEW "NOUNDEF" no longer has the disconcerting result of a test of a value implicitly creating (with a null value) previous undefined local unsubscripted variables. Now, while the variables still appear to have a null value in NOUNDEF mode, they remain undefined and will not show up in the output of ZWRITE, and functions such as $DATA() and $ORDER().

      When running in VIEW "UNDEF" mode, $STACK(X,Y) where the variable Y is undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a INVSTACODE error.

      When running in VIEW "UNDEF" mode, JOB @LABEL+OFFSET^@ROUTINE where any of the variables LABEL, OFFSET or ROUTINE are undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a JOBFAIL error. (C9B03-001664)

    • [V5.3-001A] GT.M now handles an error while $ZTRAP is active (a recursive error) in a similar fashion to an error while $ETRAP is active -- $ZTRAP now returns to the previous stack level and does not enter the direct mode. $ZTRAP creates an implicit additional frame, and therefore GT.M clears the current $ZTRAP to avoid indefinite recursion. GT.M invokes any $ETRAP or $ZTRAP handler that it encounters during unwinding the stack. If GT.M cannot locate any valid handler, it eventually terminates the process or, if invoked from direct mode, returns to direct mode. This behavior means that production environments should always start with a mumps -run. In prior versions, if GT.M could not locate a valid handler during $ZTRAP error processing, it would enter direct mode as a last resort. Although this behavior may be appropriate for some development environments, it did not match many production requirements.

      GT.M now handles an error in an EXCEPTION or ZBREAK action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M would enter direct mode in those circumstances.

      GT.M now handles a compilation error in the SET of a $ZSTEP action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M ignored such errors. Note -- Unlike ZBREAK actions, $ETRAP, $ZTRAP, and EXCEPTION strings, $ZSTEP is compiled when it's SET rather than when it's first used. This means that the prior $ZTEP action value (which defaults to "B" - BREAK) is not changed on a defective SET. We don't expect or recommend production code use ZSTEP commands. Nonetheless, if it should happen to, we recommend ensuring $ZSTEP is successfully assigned a value other than the default; for example, $ZSTEP="" causes a ZSTEP to have no effect (other than to slow execution if ZSTEP is used). (C9C11-002181)

    • [V5.3-001A] GT.M now reports the correct error location if it encounters errors during $ZTRAP error handling. In prior versions, in some cases, certain errors could cause GT.M to misreport the current location particularly in $ZSTATUS, but potentially in other location reports, such as $ZPOSITION. (C9D01-002232, S9I03-002676)

    • [V5.3-001A] GT.M no longer triggers a GTMASSERT error (causing a process termination) while trying to determine the error location under certain conditions. Previous versions occasionally issued the spurious GTMASSERT error. (C9D01-002234, C9E08-002617)

    • GT.M processes on IBM pSeries AIX are now 64-bit. See "Migrating to 64-bit platform" and "Additional Information on AIX" for more information on installing GT.M on IBM pSeries AIX. [AIX] (C9G04-002788)

    • GT.M processes on the x86_64 GNU/Linux platform are now 64-bit. GT.M for x86 Linux (32-bit) remains available as a separate build and continues to run on both x86 and x86_64 platforms. On x86_64 GNU/Linux, GT.M now has the ability to generate object modules that can be included in shared libraries using the standard system ld utility. See "Migrating to 64-bit platform" and "Additional Information on Linux" for more information on installing GT.M on x86_64 GNU/Linux. [Linux] (C9H07-002880)

    • The v5cbsu V4 to V5 upgrade utility component now operates with TRANSACTIONID="BATCH" which reduces its run-time by not waiting for journal hardening. It is safe to do this because the v5cbsu can be safely rerun or restarted should the original run stop before it is complete. (C9H09-002899)

    • If an application fails to detect and act on the loss of a SOCKET $PRINCIPAL device (using $DEVICE, $ZEOF, or EXCEPTION) and attempts additional READs or WRITEs, GT.M handles this condition by sending a NOPRINCIO message to the system log and terminating the process (as if performing a HALT). (C9H10-002916)

    • GT.M now prevents a module on the execution stack from being ZLINK'd in a pathological case. A pattern where an attempted ZLINK of a program on the stack (which would fail, as it should), followed by a ZLINK of a program with the same name when it was not on the stack (which would succeed), was followed by a ZLINK of the same module name when it was again on the stack would not fail with an error (whereas it should). Subsequent behavior could include memory access violations. (C9H11-002926)

    • The "execstack" command is no longer needed to permit GT.M processes to execute dynamically generated code. [Linux] (C9H11-002927)

    • GT.M is now able to explicitly ZLink object modules in shared libraries. In prior versions, doing an explicit ZLink on an object module in a shared library produced a ZLink error. The new behavior is now consistent between explicit and implicit ZLinks. If you have $ZROUTINES search lists that assume that explicit ZLINK would bypass your shared libraries, you should revise those in light of what you were trying to accomplish. (C9H11-002932)

    • [V5.3-001A] GT.M no longer generates unaligned access errors in the system log files. Previously, due to an incorrect size of a structure in 64-bit UNIX versions of GT.M, running the gtcm_gnp server could generate unaligned access messages. (C9I02-002959)

    • [V5.3-001A] An auto-ZLINKing process now holds control of a newly generated object file until it completes loading the fresh code from it. Previous versions used to close the newly created object file at the end of the compile and then reopen it to load the code - this left a small window where another process could delete that file and cause a somewhat mystifying file-not-found error. (C9I02-002960)

    • [V5.3-001A] GT.M now guards against signals interrupting time requests other than those for internal use. Previously limitations on reentrancy of UNIX services could occasionally cause time requests to hang if a signal resulted in another time request while one was already active. [UNIX] (C9I03-002967)

    • [V5.3-001A]GT.M now reports if it encounters errors or a full OPCOM mailbox while trying to send operator messages; it sends this report at the first non-failing attempt. It also retries sending an operator message for the mail box full condition. [OpenVMS] (C9I03-002969)

    • [V5.3-001A] GT.M now manages object files on some 64-bit platforms in a way that avoids a small memory leak that existed in prior versions. [Linux/IA64, Linux/x86_64, HPUX/IA64] (C9I03-002971)

    Return to top

    Utilities- MUPIP

    • [V5.3-001A] The source server now replicates data correctly whether it reads from journal files or the journal pool. In GT.M V5.3-001, if the source server needed to read from journal files and if the journal files had sync_io turned on and were using alignsize values greater than 64Kb, it read more data than its internal buffers could hold leading to memory corruption and mysterious abnormal termination. [UNIX] (S9I03-002675)

    • The GT.M utilities except GDE (DSE, LKE, MUPIP) now require arguments and values entered directly from the shell and containing single-quote (') or double-quotes (") to have the quotes "protected" by an escape mechanism. Each one must be preceded by a back-slash (\) or the entire string must be enclosed in a set of quotes (single or double) that do not also appear in the string. Previously GT.M attempted to implicitly escape quotes within some strings when it added quotes in preprocessing strings, but that prior approach led to inconsistent behavior in certain cases. The following are examples of appropriate usage:

      +

    • [V5.3-001A] GT.M now handles name indirection and call-ins in an a wholesome way. In V5.3-001, an inconsistency in handling these operations in NOUNDEF mode could cause various misfortunes including out of memory conditions and segmentation faults (SIG-11/ACCVIO). (S9I03-002674)

    • [V5.3-001A] GT.M now suppresses STACKCRIT errors in the current frame at the time of the error. Previously, GT.M suppressed STACKCRIT errors in stack levels invoked because of an error, but this did not cover the GOTO implicit in $ETRAP processing or any explicit GOTO or ZGOTO in a $ZTRAP that placed control at the original stack level of the error. (S9I03-002676)

      GT.M now signals the STACKCRIT error when a process has 16K stack space left available. This gives processes more opportunity to recover and trim the stack using QUIT, ZGOTO, or HALT. Previous versions used to display the STACKCRIT message when there was 1K stack space left. [UNIX] (S9I03-002676)

    • GT.M introduces a new environment variable gtm_noundef. If it is defined, and evaluates to a non-zero integer, the string "TRUE", or the string "YES" (or any case independent leading substrings thereof), then GT.M, at process startup, treats undefined variables as having an implicit value of an empty string. Otherwise, GT.M triggers an error on an attempt to use the value of an undefined variable. Previously the only way to alter this behavior of undefined variables was to use the UNDEF or NOUNDEF arguments of the VIEW command.

      [Note]
      To establish the behavior of undefined variables on OpenVMS, set "GTM$UNDEF_INHIBIT == 1" in GTM$DEFAULTS.M64 to treat undefined variables as having a null value or set "GTM$UNDEF_INHIBIT == 0" to trigger an error on an attempt to use the value of an undefined variable.

      Running with VIEW "NOUNDEF" no longer has the disconcerting result of a test of a value implicitly creating (with a null value) previous undefined local unsubscripted variables. Now, while the variables still appear to have a null value in NOUNDEF mode, they remain undefined and will not show up in the output of ZWRITE, and functions such as $DATA() and $ORDER().

      When running in VIEW "UNDEF" mode, $STACK(X,Y) where the variable Y is undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a INVSTACODE error.

      When running in VIEW "UNDEF" mode, JOB @LABEL+OFFSET^@ROUTINE where any of the variables LABEL, OFFSET or ROUTINE are undefined now causes an UNDEF error to be issued by GT.M at runtime. Previous versions used to incorrectly issue a JOBFAIL error. (C9B03-001664)

    • [V5.3-001A] GT.M now handles an error while $ZTRAP is active (a recursive error) in a similar fashion to an error while $ETRAP is active -- $ZTRAP now returns to the previous stack level and does not enter the direct mode. $ZTRAP creates an implicit additional frame, and therefore GT.M clears the current $ZTRAP to avoid indefinite recursion. GT.M invokes any $ETRAP or $ZTRAP handler that it encounters during unwinding the stack. If GT.M cannot locate any valid handler, it eventually terminates the process or, if invoked from direct mode, returns to direct mode. This behavior means that production environments should always start with a mumps -run. In prior versions, if GT.M could not locate a valid handler during $ZTRAP error processing, it would enter direct mode as a last resort. Although this behavior may be appropriate for some development environments, it did not match many production requirements.

      GT.M now handles an error in an EXCEPTION or ZBREAK action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M would enter direct mode in those circumstances.

      GT.M now handles a compilation error in the SET of a $ZSTEP action by triggering the current $ETRAP/$ZTRAP handler. In prior versions, GT.M ignored such errors. Note -- Unlike ZBREAK actions, $ETRAP, $ZTRAP, and EXCEPTION strings, $ZSTEP is compiled when it's SET rather than when it's first used. This means that the prior $ZTEP action value (which defaults to "B" - BREAK) is not changed on a defective SET. We don't expect or recommend production code use ZSTEP commands. Nonetheless, if it should happen to, we recommend ensuring $ZSTEP is successfully assigned a value other than the default; for example, $ZSTEP="" causes a ZSTEP to have no effect (other than to slow execution if ZSTEP is used). (C9C11-002181)

    • [V5.3-001A] GT.M now reports the correct error location if it encounters errors during $ZTRAP error handling. In prior versions, in some cases, certain errors could cause GT.M to misreport the current location particularly in $ZSTATUS, but potentially in other location reports, such as $ZPOSITION. (C9D01-002232, S9I03-002676)

    • [V5.3-001A] GT.M no longer triggers a GTMASSERT error (causing a process termination) while trying to determine the error location under certain conditions. Previous versions occasionally issued the spurious GTMASSERT error. (C9D01-002234, C9E08-002617)

    • GT.M processes on IBM pSeries AIX are now 64-bit. See "Migrating to 64-bit platform" and "Additional Information on AIX" for more information on installing GT.M on IBM pSeries AIX. [AIX] (C9G04-002788)

    • GT.M processes on the x86_64 GNU/Linux platform are now 64-bit. GT.M for x86 Linux (32-bit) remains available as a separate build and continues to run on both x86 and x86_64 platforms. On x86_64 GNU/Linux, GT.M now has the ability to generate object modules that can be included in shared libraries using the standard system ld utility. See "Migrating to 64-bit platform" and "Additional Information on Linux" for more information on installing GT.M on x86_64 GNU/Linux. [Linux] (C9H07-002880)

    • The v5cbsu V4 to V5 upgrade utility component now operates with TRANSACTIONID="BATCH" which reduces its run-time by not waiting for journal hardening. It is safe to do this because the v5cbsu can be safely rerun or restarted should the original run stop before it is complete. (C9H09-002899)

    • If an application fails to detect and act on the loss of a SOCKET $PRINCIPAL device (using $DEVICE, $ZEOF, or EXCEPTION) and attempts additional READs or WRITEs, GT.M handles this condition by sending a NOPRINCIO message to the system log and terminating the process (as if performing a HALT). (C9H10-002916)

    • GT.M now prevents a module on the execution stack from being ZLINK'd in a pathological case. A pattern where an attempted ZLINK of a program on the stack (which would fail, as it should), followed by a ZLINK of a program with the same name when it was not on the stack (which would succeed), was followed by a ZLINK of the same module name when it was again on the stack would not fail with an error (whereas it should). Subsequent behavior could include memory access violations. (C9H11-002926)

    • The "execstack" command is no longer needed to permit GT.M processes to execute dynamically generated code. [Linux] (C9H11-002927)

    • GT.M is now able to explicitly ZLink object modules in shared libraries. In prior versions, doing an explicit ZLink on an object module in a shared library produced a ZLink error. The new behavior is now consistent between explicit and implicit ZLinks. If you have $ZROUTINES search lists that assume that explicit ZLINK would bypass your shared libraries, you should revise those in light of what you were trying to accomplish. (C9H11-002932)

    • [V5.3-001A] GT.M no longer generates unaligned access errors in the system log files. Previously, due to an incorrect size of a structure in 64-bit UNIX versions of GT.M, running the gtcm_gnp server could generate unaligned access messages. (C9I02-002959)

    • [V5.3-001A] An auto-ZLINKing process now holds control of a newly generated object file until it completes loading the fresh code from it. Previous versions used to close the newly created object file at the end of the compile and then reopen it to load the code - this left a small window where another process could delete that file and cause a somewhat mystifying file-not-found error. (C9I02-002960)

    • [V5.3-001A] GT.M now guards against signals interrupting time requests other than those for internal use. Previously limitations on reentrancy of UNIX services could occasionally cause time requests to hang if a signal resulted in another time request while one was already active. [UNIX] (C9I03-002967)

    • [V5.3-001A]GT.M now reports if it encounters errors or a full OPCOM mailbox while trying to send operator messages; it sends this report at the first non-failing attempt. It also retries sending an operator message for the mail box full condition. [OpenVMS] (C9I03-002969)

    • [V5.3-001A] GT.M now manages object files on some 64-bit platforms in a way that avoids a small memory leak that existed in prior versions. [Linux/IA64, Linux/x86_64, HPUX/IA64] (C9I03-002971)

    Return to top

    Utilities- MUPIP

    • [V5.3-001A] The source server now replicates data correctly whether it reads from journal files or the journal pool. In GT.M V5.3-001, if the source server needed to read from journal files and if the journal files had sync_io turned on and were using alignsize values greater than 64Kb, it read more data than its internal buffers could hold leading to memory corruption and mysterious abnormal termination. [UNIX] (S9I03-002675)

    • The GT.M utilities except GDE (DSE, LKE, MUPIP) now require arguments and values entered directly from the shell and containing single-quote (') or double-quotes (") to have the quotes "protected" by an escape mechanism. Each one must be preceded by a back-slash (\) or the entire string must be enclosed in a set of quotes (single or double) that do not also appear in the string. Previously GT.M attempted to implicitly escape quotes within some strings when it added quotes in preprocessing strings, but that prior approach led to inconsistent behavior in certain cases. The following are examples of appropriate usage:

         lke show -lock='^global("embed=and""nospace")'
   lke show -lock="^global(\"embedded\"\" quote\")"
   lke show -lock='^a("two words",5)'
-
      [Caution]
      This change may cause some existing scripts to fail.

      The following is an example from our test system where the old usage required revision:

      $MUPIP backup -o -i -t=1 DEFAULT "| gzip -c > online5pipe.inc.gz"

      Now must be:

      $MUPIP backup -o -i -t=1 DEFAULT "\"| gzip -c > online5pipe.inc.gz"\"

      Behavior at the utility prompt is unchanged. [UNIX] (D9G12-002633)

    • Backward journal recovery (MUPIP JOURNAL ROLLBACK or MUPIP JOURNAL RECOVER BACKWARD) now maintains the integrity of the master bitmap when the total blocks in the database is a multiple of 512. In previous versions, these operations could, in that case coupled with other unusual conditions, result in a database with a DBMBPINCFL integrity error (Master bitmap incorrectly marks this local map full). Please note that although no database integrity error is desirable, DBMBINCFL is a "benign" error whose only effect is wasted space in the database. (C9H10-002923)

    • MUPIP REORG now preserves application data integrity even in case of concurrent GT.M updates. In previous versions, running MUPIP REORG concurrently with GT.M could result in data loss in certain extremely rare cases. In GT.M V5.3-000 one particular case of this issue was addressed by C9B11-001813. Additional cases are addressed by this change. (C9H12-002934) -

    • [V5.3-001A] MUPIP INTEG now correctly reports a DBINVGBL integrity error when it finds records with one global name in the Global Variable Tree (GVT) belonging to a different global name. Previous GT.M versions used to miss reporting an integrity error in case the incorrectly placed records were in the rightmost leaf block of the target GVT and the global name corresponding to the incorrectly placed records lexically sorted AFTER the global name corresponding to the target GVT. For example, if MUPIP INTEG encountered records of ^AA in the rightmost leaf block of the GVT of ^BB, it issued (and continues to issue) an integrity error but if there were records of ^CC incorrectly placed in the rightmost leaf block of the GVT of ^BB, then INTEG previously issued no error. (C9I02-002956)

    Return to top

    Utilities-Other Than MUPIP

    +

    [Caution]
    This change may cause some existing scripts to fail.

    The following is an example from our test system where the old usage required revision:

    $MUPIP backup -o -i -t=1 DEFAULT "| gzip -c > online5pipe.inc.gz"

    Now must be:

    $MUPIP backup -o -i -t=1 DEFAULT "\"| gzip -c > online5pipe.inc.gz"\"

    Behavior at the utility prompt is unchanged. [UNIX] (D9G12-002633)

  • Backward journal recovery (MUPIP JOURNAL ROLLBACK or MUPIP JOURNAL RECOVER BACKWARD) now maintains the integrity of the master bitmap when the total blocks in the database is a multiple of 512. In previous versions, these operations could, in that case coupled with other unusual conditions, result in a database with a DBMBPINCFL integrity error (Master bitmap incorrectly marks this local map full). Please note that although no database integrity error is desirable, DBMBINCFL is a "benign" error whose only effect is wasted space in the database. (C9H10-002923)

  • MUPIP REORG now preserves application data integrity even in case of concurrent GT.M updates. In previous versions, running MUPIP REORG concurrently with GT.M could result in data loss in certain extremely rare cases. In GT.M V5.3-000 one particular case of this issue was addressed by C9B11-001813. Additional cases are addressed by this change. (C9H12-002934) +

  • [V5.3-001A] MUPIP INTEG now correctly reports a DBINVGBL integrity error when it finds records with one global name in the Global Variable Tree (GVT) belonging to a different global name. Previous GT.M versions used to miss reporting an integrity error in case the incorrectly placed records were in the rightmost leaf block of the target GVT and the global name corresponding to the incorrectly placed records lexically sorted AFTER the global name corresponding to the target GVT. For example, if MUPIP INTEG encountered records of ^AA in the rightmost leaf block of the GVT of ^BB, it issued (and continues to issue) an integrity error but if there were records of ^CC incorrectly placed in the rightmost leaf block of the GVT of ^BB, then INTEG previously issued no error. (C9I02-002956)

    • Return to top

    Utilities-Other Than MUPIP

    • None.

    -

    Return to top

    Error Messages

    Return to top

    GTMSECSHRTMPPATH

    GTMSECSHRTMPPATH: gtmsecshr path is pppp

    Information Message: GT.M displays this message when different users of an instance of GT.M connect using a socket or a semaphore and when gtmsecshr is started and it detects an existing gtmsecshr. pppp indicates the gtm_tmp path set in the clients. Gtmsecshr inherits the path from the first GT.M process that uses its services.

    Action: If different clients of the same instance of GT.M are using different gtmsecshr paths, then set a common value for the environment variable gtm_tmp for all users of an instance of GT.M, then stop and restart the processes that were using incorrect paths. If gtmsecshr itself has the incorrect path, all processes that are using that incorrect path must be stopped first - then stop gtmsecshr with a kill command.

    Return to top

    OPCOMMISSED [V5.3-001A]

    OPCOMMISSED n errors and m MBFULLs sending prior operator messages

    Informational Message: GT.M issues this message to the operator log if any operator messages prior to the immediately preceding one had not been sent due to errors from $SNDOPR. m is the number of time a persistent MBFULL error prevented a messages from being sent and n is the number of other errors whose reports were bypassed.

    Action: None.

    +

    Return to top

    Error Messages

    Return to top

    GTMSECSHRTMPPATH

    GTMSECSHRTMPPATH: gtmsecshr path is pppp

    Information Message: GT.M displays this message when different users of an instance of GT.M connect using a socket or a semaphore and when gtmsecshr is started and it detects an existing gtmsecshr. pppp indicates the gtm_tmp path set in the clients. Gtmsecshr inherits the path from the first GT.M process that uses its services.

    Action: If different clients of the same instance of GT.M are using different gtmsecshr paths, then set a common value for the environment variable gtm_tmp for all users of an instance of GT.M, then stop and restart the processes that were using incorrect paths. If gtmsecshr itself has the incorrect path, all processes that are using that incorrect path must be stopped first - then stop gtmsecshr with a kill command.

    Return to top

    OPCOMMISSED [V5.3-001A]

    OPCOMMISSED n errors and m MBFULLs sending prior operator messages

    Informational Message: GT.M issues this message to the operator log if any operator messages prior to the immediately preceding one had not been sent due to errors from $SNDOPR. m is the number of time a persistent MBFULL error prevented a messages from being sent and n is the number of other errors whose reports were bypassed.

    Action: None.

    For more information, see the GT.M web site.
    diff --git a/articles/GTM_V5.3-002_Release_Notes.html b/articles/GTM_V5.3-002_Release_Notes.html index 93f6a58..27603c6 100644 --- a/articles/GTM_V5.3-002_Release_Notes.html +++ b/articles/GTM_V5.3-002_Release_Notes.html @@ -98,7 +98,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    11.11

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

    -
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.
    +
    [Tip]
    While GT.M should support both UTF-8 mode and M mode on this platform, there are problems with the version of HP-UX that we currently use for supporting HP-UX that prevent FIS from testing 4 byte UTF-8 characters in UTF-8 mode on the HP PA-RISC HP-UX platform. FIS understands that the issue is resolved in HP-UX 11.31. At this time, HP-UX 11.31 is not formally supported (as it is untested); however, there is no identified reason that would prevent GT.M V5.2-000 (and above) from working correctly on that newer version.

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

    @@ -126,7 +126,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    Although AIX 5.2 and 5.3 are the officially supported releases, we are not aware of any reason why GT.M V5.3-002 will not run on AIX 6.x.

    -
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.
    +
    [Tip]
    While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.

    Sun SPARC Solaris

    @@ -192,7 +192,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    4-byte

    gtm_uint_t has 32 bit length on all platforms

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

    Internationalization (Collation)

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

    Internationalization (Collation)

    Parameter type

    32-Bit

    @@ -208,7 +208,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

    -
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    +
    [Important]
    Any collation routines require only a recompile, assuming other aspects of their code are 64 bit capable.

    Environment Translation

    Parameter type

    32-Bit

    @@ -224,7 +224,7 @@ Note that 32- and 64-bits refers to GT.M processes. 64-bit operating system ker

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

    -
    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. FIS will address this in a future release. (C9H10-002924)

    Return to top

    Rebuild Shared Libraries or Images

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

    Return to top

    Additional Installation Instructions

    For installing GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide.

    UNIX

    1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version. If you must overwrite an existing GT.M installation with a new version you must first shut down all processes using the old version. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-002 in /opt/lsb-gtm/V5.3-002 on Linux systems.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

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

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

    GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. Before installing GT.M on IBM pSeries AIX, run the following command to check the filesets of this facility:

    • +

    [Important]
    Any environment translation routines require only a recompile, assuming other aspects of their code are 64 bit capable.
    [Note]
    Although any existing M code must be compiled for the 64-bit environment, the source is unchanged from 32-bit environments.

    Return to top

    Recompile

    • Recompile all M and C source files.

    [Warning]
    On all Linux platforms, the GT.M compiler fails with a GTM-E-OBJFILERR error when it attempts to place the object modules on an NFS-mounted file system. The workaround is to avoid compiling GT.M on NFS file systems; however you can move object modules to an NFS-mounted system after successful compilation. FIS will address this in a future release. (C9H10-002924)

    Return to top

    Rebuild Shared Libraries or Images

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

    Return to top

    Additional Installation Instructions

    For installing GT.M, see the "Installing GT.M" section in the GT.M Administration and Operations Guide.

    UNIX

    1. Fidelity strongly recommends installing each version of GT.M in a separate (new) directory, rather than overwriting a previously installed version. If you must overwrite an existing GT.M installation with a new version you must first shut down all processes using the old version. Since GT.M has now been assigned the package name lsb-gtm by the Linux Assigned Names and Numbers Authority (http://lanana.org), it would be appropriate to install GT.M V5.3-002 in /opt/lsb-gtm/V5.3-002 on Linux systems.

    2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

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

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

    GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. 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 in one of the following modes:

    • smit aio (for gui mode) or @@ -251,7 +251,7 @@ gmake gmake check gmake install

    • 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 the /usr/local directory.

    [Note]
    By default, ICU is installed in /usr/local. If you install ICU in a different directory, type: -
    • runConfigureICU HP-UX/ACC --prefix=<install_path> --enable-64bit-libs  --enable-rpath –disable-threads
    • Then execute the gmake commands, and set the environment variable LD_LIBRARY_PATH to point to the appropriate location.

    Return to top

    Setting the environment variable TERM

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

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

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

    Return to top

    Change History

    Fixes and enhancements specific to V5.3-002 are:

    S9D08-002359
    S9D11-002394
    S9F01-002523
    S9F06-002552
    S9H03-002644
    S9I03-002677
    S9I05-002681
    S9I05-002682
    S9I05-002686
    S9I06-002687
    S9I07-002688
    S9I07-002689
    S9I07-002690
    S9I07-002692
    C9C06-002064
    C9D07-002355
    C9D10-002413
    C9D12-002471
    C9E02-002525
    C9F03-002709
    C9F06-002736
    C9I01-002946
    C9I01-002947
    C9I01-002953
    C9I03-002972
    C9I04-002974
    C9I04-002975
    C9I04-002976
    C9I04-002977
    C9I05-002989
    C9I06-002998
    C9I06-003000
    C9I06-003002
    C9I06-003002
    C9I07-003006
    C9I07-003007
    C9I07-003009
    C9I08-003012

    Return to top

    M-Database Access

    • +

      • runConfigureICU HP-UX/ACC --prefix=<install_path> --enable-64bit-libs  --enable-rpath –disable-threads
      • Then execute the gmake commands, and set the environment variable LD_LIBRARY_PATH to point to the appropriate location.

    Return to top

    Setting the environment variable TERM

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

    [Important]

    Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M. GT.M itself does not have any knowledge of specific terminal control characteristics. Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal. You may need to add new terminfo entries depending on their specific platform and implementation. The terminal (emulator) vendor may also be able to help.

    GT.M uses the following terminfo capabilities. The full variable name is followed by the capname in parenthesis.

    auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

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

    Return to top

    Change History

    Fixes and enhancements specific to V5.3-002 are:

    S9D08-002359
    S9D11-002394
    S9F01-002523
    S9F06-002552
    S9H03-002644
    S9I03-002677
    S9I05-002681
    S9I05-002682
    S9I05-002686
    S9I06-002687
    S9I07-002688
    S9I07-002689
    S9I07-002690
    S9I07-002692
    C9C06-002064
    C9D07-002355
    C9D10-002413
    C9D12-002471
    C9E02-002525
    C9F03-002709
    C9F06-002736
    C9I01-002946
    C9I01-002947
    C9I01-002953
    C9I03-002972
    C9I04-002974
    C9I04-002975
    C9I04-002976
    C9I04-002977
    C9I05-002989
    C9I06-002998
    C9I06-003000
    C9I06-003002
    C9I06-003002
    C9I07-003006
    C9I07-003007
    C9I07-003009
    C9I08-003012

    Return to top

    M-Database Access

    • GT.M journaling logic now recovers from additional runtime errors. If the control structures in the journal buffer (in database shared memory) get set to invalid values (such as unanticipated, out-of-design condition), GT.M journal buffer flushing logic detects this situation, turns OFF journaling right away and sends appropriate messages to the syslog (operator log in VMS). Subsequent updates to the database continue to work without any issues. Previous versions of GT.M used to hang for minutes trying to recover from this situation and terminate unlucky processes abnormally with GTMASSERT errors. In addition, processes could try writing to non-allocated portions of the journal file, which in turn caused a flood of JNLACCESS messages in the operator log. (S9D11-002394, S9I07-002690)

    • This release includes a field test grade implementation of the MM (Mapped Memory) database access method for UNIX/Linux. The OpenVMS editions of GT.M previously supported MM and continue to do so unchanged. The MM access method maps database files (with the mmap() system call) to the address space of all processes accessing the corresponding MM region, thereby using the operating system to manage traffic between memory and disk rather than using the global buffer pool as in the Buffered Global (BG) access method. Note that before image journaling and backward recovery require that before-image journal records be committed to disk before the corresponding database updates are committed. Since this is not possible with MM, before-image journaling, and consequently mupip backward recovery/rollback to recover a database without a restore are not available with MM. Attempts to use MM with before image journaling produce an error. The MM access method supports nobefore_image journaling and mupip forward recovery, as well as mupip journal rollback with the -resync or -fetchresync qualifiers to generate lost and broken transaction files. The implementation of MM on UNIX/Linux allows databases to extend dynamically, as they do with BG; as before, the implementation of MM on OpenVMS does not permit dynamic database file extension. The MM access method may provide a performance advantage in situations where its restrictions are acceptable. Although we do not yet recommend this feature in production (the next GT.M release will make MM fully Supported), we encourage you to try it in appropriate development, testing and benchmarking environments and to tell us how it works for you – especially about any issues you encounter and any performance gain you experience. Note that the field test designation refers only to the new MM access method for UNIX/Linux. V5.3-002, including MM for OpenVMS, is a fully tested and qualified, production grade GT.M release that is at least as robust as, if not more robust than, any previous GT.M release. [UNIX] (C9904-001024)

    • The Linux version of GT.M can now utilize O_DIRECT support for journal files. The O_DIRECT option is made available by using the sync_io option to the MUPIP SET -JOURNAL command just as for the other platforms that support direct I/O. [Linux] (C9D10-002409)

    • The 'VIEW "FLUSH"' (originally introduced in V5.0-000), now always flushes all dirty buffers from the global buffer pool. Previous versions might only do a partial flush. (C9E02-002525)

    • diff --git a/articles/GTM_V5.4-002_Release_Notes.html b/articles/GTM_V5.4-002_Release_Notes.html index 64db7d1..0c01c40 100644 --- a/articles/GTM_V5.4-002_Release_Notes.html +++ b/articles/GTM_V5.4-002_Release_Notes.html @@ -42,7 +42,7 @@ gtmsupport@fisglobal.com
      JNLTPNEST

      REPLJNLCNFLCT
      REPLNOXENDIAN
      - REPLNOMULTILINETRG [V5.4-002A]
      + REPLNOMULTILINETRG [V5.4-002A]
      REPLXENDIANFAIL
      SECNODZTRIGINTP
      SETINSETTRIGONLY
      SHMREMOVED [V5.4-002B]
      @@ -53,7 +53,7 @@ gtmsupport@fisglobal.com
      TRIGNAMBAD
      TRIGNAMENF
      TRIGZBREAKREM
      - WRITEWAITPID
      ZCCLNUPRTNMISNG [V5.4-002B]
      ZCINVALIDKEYWORD [V5.4-002B]
      ZGOCALLOUTIN
      ZGOTOINVLVL2

    Conventions

    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 "/" rather than a "-".

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

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

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

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

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

    Release Overview

    GT.M V5.4-002B provides timely remediation of some additional issues with V5.4-002 and V5.4-002A (highlighted as [V5.4-002B]).

    GT.M V5.4-002A provides timely remediation of some issues with V5.4-002 (highlighted as [V5.4-002A]).

    GT.M V5.4-002 brings performance and scalability enhancements to GT.M:

    • The previous implementation of local variables has been replaced by one that scales well to large numbers of nodes at a given subscript level. FIS has internally validated its scalability to over one million nodes and also validated that it preserves or even slightly improves upon GT.M's traditional fast performance for local variables with smaller numbers of nodes.

    • On 64-bit editions of GT.M, the previous per-region limits of 65,536 global buffers and 2GB shared segment size are no longer limited by GT.M; of course, they remain limited by your actual computing platform.

    There are important enhancements to the trigger facility:

    • Trigger -xecute commands can span multiple lines.

    • The new ZTRIGGER command allows a trigger to be explicitly invoked under program control.

    • $ZTNAME replaces the deprecated $ZTCODE in the trigger signature.

    • The use of $ZTRIGGER() within a TP transaction allows trigger logic to be updated atomically within a transaction. Some restrictions apply.

    An "unlink all" capability for UNIX platforms allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref at the top of the stack; local variables and IO devices are preserved across the transition.

    A new option generates code to evaluate elements of Boolean expressions in an alternative order that ensures expresion components with side effects evluated before the Boolena evaluation as an alternative to GT.M's default behavior which stops the evaluation of Boolean expressions once the final outcome is determined.

    Please refer to the description of C9K09-003324 for changes to the configure script used to install GT.M.

    V5.4-002 contains numerous fixes, remedied mis-features, and smaller enhancements. For a comprehensive list, refer to Change History.

    Conventions

    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 "/" rather than a "-".

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

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

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

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

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

    Release Overview

    GT.M V5.4-002B provides timely remediation of some additional issues with V5.4-002 and V5.4-002A (highlighted as [V5.4-002B]).

    GT.M V5.4-002A provides timely remediation of some issues with V5.4-002 (highlighted as [V5.4-002A]).

    GT.M V5.4-002 brings performance and scalability enhancements to GT.M:

    • The previous implementation of local variables has been replaced by one that scales well to large numbers of nodes at a given subscript level. FIS has internally validated its scalability to over one million nodes and also validated that it preserves or even slightly improves upon GT.M's traditional fast performance for local variables with smaller numbers of nodes.

    • On 64-bit editions of GT.M, the previous per-region limits of 65,536 global buffers and 2GB shared segment size are no longer limited by GT.M; of course, they remain limited by your actual computing platform.

    There are important enhancements to the trigger facility:

    • Trigger -xecute commands can span multiple lines.

    • The new ZTRIGGER command allows a trigger to be explicitly invoked under program control.

    • $ZTNAME replaces the deprecated $ZTCODE in the trigger signature.

    • The use of $ZTRIGGER() within a TP transaction allows trigger logic to be updated atomically within a transaction. Some restrictions apply.

    An "unlink all" capability for UNIX platforms allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref at the top of the stack; local variables and IO devices are preserved across the transition.

    A new option generates code to evaluate elements of Boolean expressions in an alternative order that ensures expresion components with side effects evluated before the Boolena evaluation as an alternative to GT.M's default behavior which stops the evaluation of Boolean expressions once the final outcome is determined.

    Please refer to the description of C9K09-003324 for changes to the configure script used to install GT.M.

    V5.4-002 contains numerous fixes, remedied mis-features, and smaller enhancements. For a comprehensive list, refer to Change History.

    Platforms

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

    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

    		 @@ -478,7 +478,7 @@ key_insert(kich1), keypad_local(rmkx),keypad_xmit(smkx), lines(lines).

    MUMPS

    KILL * corrections

    -

    These fixes are marked with [V5.4-002A] in the subsequent sections.

    +

    These fixes are marked with [V5.4-002A] in the subsequent sections.

    V5.4-002

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

    CR#

    		 @@ -1171,10 +1171,10 @@ GTM>ztrigger ^C

    YES*

    YES*

    -

    RI means replicating instance and OI means originating instance;OpenVMS+ can act as RI only to same-endian instance in dual site mode.

    * ? means FIS does not test this configuration, but it might work because the conversion can occur on the replicating instance.

    * means if the replicating instance does not support triggers the originating instance sends updates performed by triggers, but no updates to triggers themselves.

    In a cross-endian environment, V5.4-000[A] and V5.4-001 do not work correctly when replicating updates from originating instances with higher GT.M versions (V5.4-002 and above) (C9K09-003326)

  • GT.CM GNP server honors MUPIP STOP (SIG-15), at the first opportunity, even if the signal arrives while GT.CM server is executing a non-interruptible code path. Previously in such cases, the server might lose track of MUPIP STOP, ignore the interrupt, and just continue waiting for client requests. [UNIX] (C9K09-003327)

  • GT.M appropriately defers timer interrupts (for example, database flush timers) to prevent an out-of-design state. Previously in a rare situation, an interrupt could cause a process to terminate with a fatal GTMASSERT (in module have_crit.c). [UNIX] (C9K10-003335)

  • GT.M appropriately handles an unusual situation where the rate of change in journal files exceeds the rate of journal file writes in some process. In prior versions, a such a process might not recognize it needed to change journal files when it should and could cause a database stall of up to two minutes. [UNIX] (C9K11-003339)

  • [V5.4-002A] GT.M ensures that journal records are never written with out-of-order timestamps. Previously, in rare cases where the system time went back by a second or two, GT.M wrote journal records with out-of-order timestamps which could cause MUPIP JOURNAL -RECOVER to fail. Note that even previously GT.M generally protected itself against the eventuality of the system clock going backwards; the fix remedied a rare code path where it did not. Note also that FIS recommends against stepping the system clock back when GT.M applications are active - slewing the clock is safe and is the preferred option when GT.M applications are active. (C9K12-003350)

  • GT.M includes the journal sequence number (token sequence number if replication is not enabled) field of all replicated records as part of computing the checksum of the journal record. Previously, this field was not a part of the checksum and in rare cases, after a crash, could cause ROLLBACK/RECOVERY to assume a bad journal record to be a good one resulting in GTM-F-MEMORY errors. [UNIX] (C9L01-003354)

  • [V5.4-002A] A database access during the "final" retry (third or higher) of a TP transaction from an error handler specified by $ETRAP works correctly. Previously, such a combination damaged internal data structures that would most likely result in process termination with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). As the damage produced incorrect addresses, its effect could not be guaranteed, and although unlikely, could in theory cause the affected process to produce incorrect results or database damage. (C9L03-003368)

  • During replication, the GT.M Source Server handles certain timeout related network stress as connection resets, that is: the Source Server breaks its connection with the Receiver Server and attempts to reconnect. Previously, these timeouts caused the Source Server to exit. While FIS was not able to recreate these network conditions in the GT.M development environment, GT.M includes changes that should make it more robust in the face of these not-yet-characterized network timeouts. (C9L03-003369)

  • [V5.4-002A] GT.M deals appropriately with an unusual set of circumstances where: the global directory contains a -KEY_SIZE less than the maximum key size in database file header and the application does a VIEW "NOISOLATION" on one or more globals in the region before the first reference to any global in the region. The global directory and the database file header might not match if the current global directory was not used to create the database file or if the file header was modified with DSE. Previously this caused a GTMASSERT. The workarounds were to avoid the mismatch between the global directory and the database or to access at least one global in the region before issuing the VIEW "NOISOLATION" command. (C9L03-003393)

  • [V5.4-002A] MERGE gvn=glvn sets $REFERENCE and the "naked indicator" to gvn even if the glvn has a $DATA() result of 0. Previously this unusual condition left $REFERENCE to either its prior value if the source was an lvn or to reflect the source gvn if it was a global. (C9L03-003394)

  • [V5.4-002B] GT.M correctly handles runtime errors for a SET or $INCREMENT() of a gvn. Previously, such errors in very rare cases could result in database damage. (C9L04-003407)

  • [V5.4-002B] GT.M follows a GVSUBOFLOW error message with a GVIS message with a * at the end of the global variable node to indicate incompleteness. For example, if a program attempts a SET^ZGBL(1,2) and the maximum key size for the region is 10, the GVIS message reports ^ZGBL(1* as the global variable to indicate that the reported value is incomplete and that the actual value could contain zero or more subscripts replacing the *. GT.M previously reported a GVIS message with ^ZGBL(1) as the global variable to indicate that the maximum key size was exceeded while processing the second subscript. In addition, a GVSUBOFLOW in a string subscript containing either $C(0) or $C(1) no longer reports garbled subscript values of arbitrary length. (C9L05-003412)

  • [V5.4-002B] NOBEFORE_IMAGE journaling avoids a potentially time consuming action that has no value to its successful operation. Although the change affects both BG and MM access methods, the impact is likely to be greater with MM. (C9L06-003429)

  • [V5.4-002B] GT.M now explicitly enforces ordering for a few additional shared memory operations used in the course of buffer management in the database logic. While we are not currently aware of any issues in production sites, our testing revealed that, at least on some IBM pSeries systems, aggressive instruction reordering could cause out-of-order store order conditions that violate the design and raise the possibility of database damage. Note that the x86 (both 32- and 64-bit) and zSeries do not create out-of-order store conditions, nor does the p6 (the p5 and p7 do); other platforms can generate such conditions with varying degrees of frequency. (C9L07-003437)

    • - M-Other Than Database Access

    • ZGOTO accepts a negative level and treats it as $zlevel-intexpr. In prior versions, negative arguments produced a ZGOTOLTZERO error. GT.M handles all identified ZGOTO cases correctly, including ZLINKFILE, INVOBJ, MEMORY (exhausted), GTMASSERT errors and various signals on UNIX and ACCVIOs on OpenVMS. (S9606-000216, C9D06-002318, C9H04-002845)

    • GT.M handles numeric strings which are not canonical within the implementation as strings unless the application specifically requests they be treated as numbers. Any use in a context defined as numeric elicits numeric treatment; this includes operands of numeric operators, numeric literals, and some intrinsic function arguments. When the code creates a large number out of range , GT.M gives a NUMOFLOW error. When the code creates a small fractional number out of range GT.M treats it as zero (0). The GT.M number range is (to the limit of accuracy) 1E-43 to 1E47. When the application creates an in-range number that exceeds the GT.M numeric accuracy of 18 significant digits, GT.M silently retains the most significant digits. With standard collation, GT.M collates canonic numeric strings used as subscripts numerically, while it collates non-canonic numbers as strings. Prior versions followed this pattern but had some edge case anomalies including:

      1. Sorts-after (]]) comparisons involving a number inappropriately treated some non-canonic strings as numbers

      2. $DATA() treated large out-of-range non-canonic numeric string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      3. $ORDER() of a local array containing a non-canonic decimal fraction with no integer part returned a numeric value which could cause indefinite looping

      4. $QUERY() with an argument specifying a local array treated large out-of-range non-canonic string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      5. In local arrays but not global arrays, MERGE treated non-canonic numeric string subscripts in as numbers, resulting in asymmetric merges

      6. ZWRITE treated non-canonic numeric string subscripts as numbers and, as a result, misrepresented such results

      7. GT.M did not treat calculations producing small out-of-range decimal values uniformly when they underflowed so tiny values that should have been the same could differ for example: (X+X) ‘= (2*X) for some very, very small values of X.

      8. Depending on context, GT.M reported numeric overflow at slightly differing values close to 1E47

      9. $NEXT(), which is deprecated, handles a constructed string that evaluates to -1 as a "starting value" and therefore picks up large negative subscripts (S9D06-002331, S9F05-002547, C9H02-002826)

    • [V5.4-002A] The new ZHALT command extends the HALT command to allow a GT.M process to provide a return code to the shell (or other process) from which it was invoked. The syntax of the command is ZHALT[:tvexpr] [intexpr]. GT.M returns the value of intexpr to the invoking program as the completion status. Since UNIX limits return codes to zero through 255, GT.M returns the return code modulo 256, unless the return code is non-zero but the value modulo 256 is zero, in which case GTM returns a (non-success) value of 255 so that the return code is non-zero. On OpenVMS, GT.M returns the standard success value (EXIT_SUCCESS or 1) if the ZHALT argument is zero and otherwise returns the standard failure value (EXIT_FAILURE or %X10000002). (S9J10-002744)

    • PIPE and FIFO devices respond to interrupts such as MUPIP INTRPT when waiting on a READ. Previously these devices ignored such interrupts while waiting on a READ. In direct mode, <CTRL-C> terminates a hung FIFO READ. Previously a FIFO device ignored a <CTRL-C> waiting on a READ. The direct mode behavior of the PIPE device remains the same, where a <CTRL-C> terminates PIPE subprocesses and the READ.

      The FIFO device correctly returns partial input for timed READs and sets status variables appropriately for fixed and UTF -8 mode READs. Previously a FIFO could hang and/or return partial data and/or not set status variables correctly for such READs.

      On z/OS, a readonly FIFO OPENs correctly and maintains $X properly. Previously on z/OS, readonly FIFO OPEN and $X misbehaved. [UNIX] (S9K02-002753)

    • READ from a SOCKET device provides improved protection against interrupts (for example, generated with MUPIP INTRPT). In prior releases, we had reports of segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Since FIS was unable to recreate these problems in the GT.M development environment, FIS cannot confirm whether they are entirely corrected. (S9K05-002770)

    • The jump optimizer in the GT.M compiler correctly optimizes the generated code in an obscure case. This issue started with V5.2-000 in certain 32-bit versions. While it is possible there are others, the only known condition to manifest symptoms is as follows: two nested argumentless DOs terminating on the same line where the inner DO preceded an argumentless FOR command on the same line containing no local variable references did not properly iterate. The only currently shipping version that showed this issue is x86 Linux, but 32-bit Solaris through V5.3-001A also might exhibit this problem. The workarounds for the identified symptom are to use an explicit QUIT or other code to avoid multiple argumentless DOs from terminating on the same line or ensure any line with a nested argumentless DO contains at least one local variable reference.[32-bit x86 Linux and 32-bit SPARC Solaris] (S9K07-002782).

    • GT.M local variable processing avoids occasional duplicate subscripts in local variable arrays. This addresses an interaction between GT.M and some versions of a C library (crtl) function. The code in question has been in GT.M for all versions and all platforms for a very long time (at least before V4.0-000). Even though this issue has only been reported on Linux x86 (32 bit) systems on V5.4-001, FIS believes that it is very hardware dependent and rare. It is also theoretically possible for this to manifest itself as a segmentation violation (SIG-11) on certain (usually older) x86 architecture CPUs, but FIS was was never able to replicate this in the GT.M development environment (S9K10-002786)

    • [V5.4-002A] M-profiling counts all types of FOR loops appropriately, and captures time consistently. When nesting levels exceed the facility's capacity to retain information, M-profiling stops detailed reporting and reports all subsequent time as a total. Previously FOR iterations were miscounted or not reported, and times could be very inaccurate; high levels of nesting could cause time capture to stop and restart with no accounting for the time between. M-profiling cannot and does not provide exact time information, but does provide a useful representation of where application code spends CPU cycles. Relative times reported by M-profiling should be meaningful. (S9L03-002804)

    • [V5.4-002A] The compiler gives FULLBOOLWARN warnings only in cases where the evaluation contains an AND (&) or an OR (!) with a $increment(), extrinsic function, or external call in other than the first element. In V5.4-002, it gave inappropriate warnings even in these cases where the side effect items are always evaluated. (S9L03-002807)

    • [V5.4-002B] $QLENGTH() and $QSUBSCRIPT() accept the non-standard (square-bracket) form of extended reference. Previously they only accepted the standard (up-bar) form. (S9L06-002813)

    • [V5.4-002B] GT.M handles job interrupts inside of a TP transaction more robustly. This fixes a regression introduced in V5.4-000, where a job interrupt that occurs inside a TP transaction that has not yet done any global reference but does some global reference inside the job interrupt code causing the first global reference after retunr from the job interrupt code to abnormally terminate with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) error. Note this abnormal termination could not affect database integrity. (S9L06-002816)

    • [V5.4-002B] $QSUBSCRIPT() returns a correct value when the selected subscript is exactly 0 (zero). Starting in V5.4-001, selecting a 0 subscript caused $QSUBSCRIPT() to return not only the 0 but all subsequent subscripts in the name. (S9L06-002820)

    • [V5.4-002B] $ZCONVERT() issues an ICUERROR error when ICU returns an inappropriate or unexpected error. Previously the process terminated with a GTMASSERT. [UNIX](S9L06-002821)

    • [V5.4-002B] VIEW "TRACE" works with triggers and call-ins. Previously, use of the VIEW "TRACE" facility with triggers or call-ins resulted in a GTMASSERT. [UNIX] (S9L06-002822)

    • ZWRITE accepts Intrinsic Special Variables (ISVs) as single arguments. This provides a way to easily expose non-graphic characters in individual ISVs. ISVs cannot be selected with the pattern matching and range syntax that ZWRITE accepts for global and local variables. As before, ZSHOW "I" provides a way to get all ISVs. In previous versions ZWRITE did not permit ISV arguments. (C9806-000511)

    • GT.M has a completely new implementation of local variables that scales much better for local variables with large numbers of nodes while preserving or even slightly improving upon the fast performance of local variables with small number of nodes that the previous implementation handled well. The new implementation outperforms global variables at all sizes tested, even local variables with hundreds of thousands of nodes. For local variables with more than a few thousand nodes, global variables outperformed the prior implementation. There is no functional difference.

      This refactoring effort also improved some other aspects of performance.

      The gtm_lvscale environment variable previously available to tune local variable structures is now ignored. You can safely let it remain in shell scripts that are designed to span GT.M versions with both local variable implementations.

      As part of the same effort, $QUERY() with standard NULL collation no longer skips descendants of an empty string subscript.

      Also as part of this effort, GT.M uniformly enforces the rule that a collation transform (or reverse transform) cannot modify an empty string ("NULL") subscript. In prior versions some, but not all operations enforced this rule, which applies to global variables as well as local variables. Note that transforms should not introduce empty string subscripts and GT.M does not currently protect against this. (C9905-001087)

    • An attempt to use a subscripted FOR control variable and calculate values assigned to it using expressions with side effects generates a FORCTRLINDX error. This construct presents some issues that can potentially cause incorrect results or segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Previous releases did not guard against this problem. Note GT.M does not detect the loss of a control variable specified by indirection and then destroyed within scope (by a KILL or NEW) and when it detects the loss of an unsubscripted indirect control variable does not report the name of that variable. FIS recommends against such usage as a source of program fragility; refer to C9L03-003392. (C9B03-001660)

    • GT.M provides an option to control evaluation of Boolean expressions (expressions evaluated as a logical TRUE or FALSE). By default, GT.M stops evaluating such expression as soon as it establishes a definitive result. For example, in this mode, neither 0&$$abc^def() or 1!$$abc^def() ever executes $$abc^def(). In the case of global references, such as 0&^a or 1!^a, GT.M correctly sets $Reference and the naked indicator without actually accessing the global variable.

      The settings may be altered with a VIEW command using an argument evaluating to (case-insensitive) "FULL_BOOLEAN" to select a evaluation order that evaluates expression atoms with short-circuit side effects prior to Boolean evaluation: "NOFULL_BOOLEAN" to select the traditional GT.M evaluation order which stops as soon as the result is known, and "FULL_BOOLWARN" which evaluates like "FULL_BOOLEAN" but also produces a BOOLSIDEFFECT warning when it encounters Boolean expressions that may induce side-effects; that is: expressions with side effects after the first Boolean operator - extrinsic functions, external calls and $INCREMENT(). The new gtm_boolean environment variable (UNIX) or GTM_BOOLEAN logical name (OpenVMS) provide initial values to control this behavior at process startup. If gtm_boolean is undefined or evaluates to an integer zero (0), the initial setting the default "NOFULL_BOOLEAN", if it evaluates to an integer one (1), the initial setting is "FULL_BOOLEAN" and if it evaluates to integer two (2) the initial setting is "FULL_BOOLWARN". Other numeric values are reserved for possible future controls - do not use them.

      These are compilation settings and the object code determines run-time execution independent of the current setting. As changing the compiler setting does not clear previously compiled and cached XECUTE arguments, changing the setting before an XECUTE may or may not produce a desired effect. "FULL_BOOLWARN" does not produce warnings on XECUTE arguments with potential side effects in Boolean evaluation.

      $VIEW("FULL_BOOLEAN") returns a string describing the current compiler setting.Note that while the FULL_BOOLEAN setting ensures that the side-effect expression atoms execute, it does not produce results that match full left-to-right evaluation in cases where the side-effect operation alters variables that appear before it in the Boolean expression. Therefore it's prudent to use the FULL_BOOLWARN setting to identify and evaluate and appropriately adjust the use of side-effect expression atoms in Boolean expressions.

      GT.M does not short-circuit evaluation if the first argument of a $INCREMENT() uses indirection. In prior releases, GT.M always compiled in "NOFULL_BOOLEAN" order, but exhibited inappropriate behavior when the first argument to $INCREMENT() used indirection, including spurious VAREXPECTED errors with no variable named by the error message, and incorrectly maintained $REFERENCE (and the naked indicator) when it skipped a $INCREMENT() both of whose arguments were global variables. If your application uses indirection for the first argument of $INCREMENT() in Boolean expressions, please analyze and test those instances thoroughly.

      Note that in the default short-circuit mode, global references within an extrinsic function are not reflected in the $REFERENCE of the caller, regardless of whether or not the extrinsic actually executes - this behavior is unchanged. (C9B04-001673)

    • Call ins offer a gtm_cip() interface, similar to gtm_ci() but using a handle, which improves performance on calls after the first one. gtm_cip() replaces the first argument of gtm_ci() with an argument of type struct ci_name_descriptor which contains the routine name and a handle to the call in function. GT.M populates the empty handle on the first call; the caller must not modify the handle (or bad things happen). Prior versions only offered the original gtm_ci() interface. This change also improved the performance of the original gtm_ci() interface. [UNIX] (C9D07-002340),

    • The gtm_exit call for GT.M call-ins cleans up any pending timers setup using the gt_timers interface and releases all associated memory. Previously, gtm_exit could leak a modest amount of memory used to track the timers. [UNIX](C9E12-002687)

    • $ZDATE() provides a date representation for day 0 (31-Dec-1840) and accepts two to six consecutive "Y" characters to indicate digits of year. Previously, $ZDATE() only accepted "YY" and "YEAR" to indicate two- and four-digit years respectively, and $ZDATE() of zero (0) produced an empty output. For example:

      GTM>write $zdate(123456789,"DAY MON DD, YYYYYY") 
+

    RI means replicating instance and OI means originating instance;OpenVMS+ can act as RI only to same-endian instance in dual site mode.

    * ? means FIS does not test this configuration, but it might work because the conversion can occur on the replicating instance.

    * means if the replicating instance does not support triggers the originating instance sends updates performed by triggers, but no updates to triggers themselves.

    In a cross-endian environment, V5.4-000[A] and V5.4-001 do not work correctly when replicating updates from originating instances with higher GT.M versions (V5.4-002 and above) (C9K09-003326)

  • GT.CM GNP server honors MUPIP STOP (SIG-15), at the first opportunity, even if the signal arrives while GT.CM server is executing a non-interruptible code path. Previously in such cases, the server might lose track of MUPIP STOP, ignore the interrupt, and just continue waiting for client requests. [UNIX] (C9K09-003327)

  • GT.M appropriately defers timer interrupts (for example, database flush timers) to prevent an out-of-design state. Previously in a rare situation, an interrupt could cause a process to terminate with a fatal GTMASSERT (in module have_crit.c). [UNIX] (C9K10-003335)

  • GT.M appropriately handles an unusual situation where the rate of change in journal files exceeds the rate of journal file writes in some process. In prior versions, a such a process might not recognize it needed to change journal files when it should and could cause a database stall of up to two minutes. [UNIX] (C9K11-003339)

  • [V5.4-002A] GT.M ensures that journal records are never written with out-of-order timestamps. Previously, in rare cases where the system time went back by a second or two, GT.M wrote journal records with out-of-order timestamps which could cause MUPIP JOURNAL -RECOVER to fail. Note that even previously GT.M generally protected itself against the eventuality of the system clock going backwards; the fix remedied a rare code path where it did not. Note also that FIS recommends against stepping the system clock back when GT.M applications are active - slewing the clock is safe and is the preferred option when GT.M applications are active. (C9K12-003350)

  • GT.M includes the journal sequence number (token sequence number if replication is not enabled) field of all replicated records as part of computing the checksum of the journal record. Previously, this field was not a part of the checksum and in rare cases, after a crash, could cause ROLLBACK/RECOVERY to assume a bad journal record to be a good one resulting in GTM-F-MEMORY errors. [UNIX] (C9L01-003354)

  • [V5.4-002A] A database access during the "final" retry (third or higher) of a TP transaction from an error handler specified by $ETRAP works correctly. Previously, such a combination damaged internal data structures that would most likely result in process termination with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). As the damage produced incorrect addresses, its effect could not be guaranteed, and although unlikely, could in theory cause the affected process to produce incorrect results or database damage. (C9L03-003368)

  • During replication, the GT.M Source Server handles certain timeout related network stress as connection resets, that is: the Source Server breaks its connection with the Receiver Server and attempts to reconnect. Previously, these timeouts caused the Source Server to exit. While FIS was not able to recreate these network conditions in the GT.M development environment, GT.M includes changes that should make it more robust in the face of these not-yet-characterized network timeouts. (C9L03-003369)

  • [V5.4-002A] GT.M deals appropriately with an unusual set of circumstances where: the global directory contains a -KEY_SIZE less than the maximum key size in database file header and the application does a VIEW "NOISOLATION" on one or more globals in the region before the first reference to any global in the region. The global directory and the database file header might not match if the current global directory was not used to create the database file or if the file header was modified with DSE. Previously this caused a GTMASSERT. The workarounds were to avoid the mismatch between the global directory and the database or to access at least one global in the region before issuing the VIEW "NOISOLATION" command. (C9L03-003393)

  • [V5.4-002A] MERGE gvn=glvn sets $REFERENCE and the "naked indicator" to gvn even if the glvn has a $DATA() result of 0. Previously this unusual condition left $REFERENCE to either its prior value if the source was an lvn or to reflect the source gvn if it was a global. (C9L03-003394)

  • [V5.4-002B] GT.M correctly handles runtime errors for a SET or $INCREMENT() of a gvn. Previously, such errors in very rare cases could result in database damage. (C9L04-003407)

  • [V5.4-002B] GT.M follows a GVSUBOFLOW error message with a GVIS message with a * at the end of the global variable node to indicate incompleteness. For example, if a program attempts a SET^ZGBL(1,2) and the maximum key size for the region is 10, the GVIS message reports ^ZGBL(1* as the global variable to indicate that the reported value is incomplete and that the actual value could contain zero or more subscripts replacing the *. GT.M previously reported a GVIS message with ^ZGBL(1) as the global variable to indicate that the maximum key size was exceeded while processing the second subscript. In addition, a GVSUBOFLOW in a string subscript containing either $C(0) or $C(1) no longer reports garbled subscript values of arbitrary length. (C9L05-003412)

  • [V5.4-002B] NOBEFORE_IMAGE journaling avoids a potentially time consuming action that has no value to its successful operation. Although the change affects both BG and MM access methods, the impact is likely to be greater with MM. (C9L06-003429)

  • [V5.4-002B] GT.M now explicitly enforces ordering for a few additional shared memory operations used in the course of buffer management in the database logic. While we are not currently aware of any issues in production sites, our testing revealed that, at least on some IBM pSeries systems, aggressive instruction reordering could cause out-of-order store order conditions that violate the design and raise the possibility of database damage. Note that the x86 (both 32- and 64-bit) and zSeries do not create out-of-order store conditions, nor does the p6 (the p5 and p7 do); other platforms can generate such conditions with varying degrees of frequency. (C9L07-003437)

    • + M-Other Than Database Access

    • ZGOTO accepts a negative level and treats it as $zlevel-intexpr. In prior versions, negative arguments produced a ZGOTOLTZERO error. GT.M handles all identified ZGOTO cases correctly, including ZLINKFILE, INVOBJ, MEMORY (exhausted), GTMASSERT errors and various signals on UNIX and ACCVIOs on OpenVMS. (S9606-000216, C9D06-002318, C9H04-002845)

    • GT.M handles numeric strings which are not canonical within the implementation as strings unless the application specifically requests they be treated as numbers. Any use in a context defined as numeric elicits numeric treatment; this includes operands of numeric operators, numeric literals, and some intrinsic function arguments. When the code creates a large number out of range , GT.M gives a NUMOFLOW error. When the code creates a small fractional number out of range GT.M treats it as zero (0). The GT.M number range is (to the limit of accuracy) 1E-43 to 1E47. When the application creates an in-range number that exceeds the GT.M numeric accuracy of 18 significant digits, GT.M silently retains the most significant digits. With standard collation, GT.M collates canonic numeric strings used as subscripts numerically, while it collates non-canonic numbers as strings. Prior versions followed this pattern but had some edge case anomalies including:

      1. Sorts-after (]]) comparisons involving a number inappropriately treated some non-canonic strings as numbers

      2. $DATA() treated large out-of-range non-canonic numeric string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      3. $ORDER() of a local array containing a non-canonic decimal fraction with no integer part returned a numeric value which could cause indefinite looping

      4. $QUERY() with an argument specifying a local array treated large out-of-range non-canonic string subscripts as numbers and, as a result, inappropriately gave a NUMOFLOW error

      5. In local arrays but not global arrays, MERGE treated non-canonic numeric string subscripts in as numbers, resulting in asymmetric merges

      6. ZWRITE treated non-canonic numeric string subscripts as numbers and, as a result, misrepresented such results

      7. GT.M did not treat calculations producing small out-of-range decimal values uniformly when they underflowed so tiny values that should have been the same could differ for example: (X+X) ‘= (2*X) for some very, very small values of X.

      8. Depending on context, GT.M reported numeric overflow at slightly differing values close to 1E47

      9. $NEXT(), which is deprecated, handles a constructed string that evaluates to -1 as a "starting value" and therefore picks up large negative subscripts (S9D06-002331, S9F05-002547, C9H02-002826)

    • [V5.4-002A] The new ZHALT command extends the HALT command to allow a GT.M process to provide a return code to the shell (or other process) from which it was invoked. The syntax of the command is ZHALT[:tvexpr] [intexpr]. GT.M returns the value of intexpr to the invoking program as the completion status. Since UNIX limits return codes to zero through 255, GT.M returns the return code modulo 256, unless the return code is non-zero but the value modulo 256 is zero, in which case GTM returns a (non-success) value of 255 so that the return code is non-zero. On OpenVMS, GT.M returns the standard success value (EXIT_SUCCESS or 1) if the ZHALT argument is zero and otherwise returns the standard failure value (EXIT_FAILURE or %X10000002). (S9J10-002744)

    • PIPE and FIFO devices respond to interrupts such as MUPIP INTRPT when waiting on a READ. Previously these devices ignored such interrupts while waiting on a READ. In direct mode, <CTRL-C> terminates a hung FIFO READ. Previously a FIFO device ignored a <CTRL-C> waiting on a READ. The direct mode behavior of the PIPE device remains the same, where a <CTRL-C> terminates PIPE subprocesses and the READ.

      The FIFO device correctly returns partial input for timed READs and sets status variables appropriately for fixed and UTF -8 mode READs. Previously a FIFO could hang and/or return partial data and/or not set status variables correctly for such READs.

      On z/OS, a readonly FIFO OPENs correctly and maintains $X properly. Previously on z/OS, readonly FIFO OPEN and $X misbehaved. [UNIX] (S9K02-002753)

    • READ from a SOCKET device provides improved protection against interrupts (for example, generated with MUPIP INTRPT). In prior releases, we had reports of segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Since FIS was unable to recreate these problems in the GT.M development environment, FIS cannot confirm whether they are entirely corrected. (S9K05-002770)

    • The jump optimizer in the GT.M compiler correctly optimizes the generated code in an obscure case. This issue started with V5.2-000 in certain 32-bit versions. While it is possible there are others, the only known condition to manifest symptoms is as follows: two nested argumentless DOs terminating on the same line where the inner DO preceded an argumentless FOR command on the same line containing no local variable references did not properly iterate. The only currently shipping version that showed this issue is x86 Linux, but 32-bit Solaris through V5.3-001A also might exhibit this problem. The workarounds for the identified symptom are to use an explicit QUIT or other code to avoid multiple argumentless DOs from terminating on the same line or ensure any line with a nested argumentless DO contains at least one local variable reference.[32-bit x86 Linux and 32-bit SPARC Solaris] (S9K07-002782).

    • GT.M local variable processing avoids occasional duplicate subscripts in local variable arrays. This addresses an interaction between GT.M and some versions of a C library (crtl) function. The code in question has been in GT.M for all versions and all platforms for a very long time (at least before V4.0-000). Even though this issue has only been reported on Linux x86 (32 bit) systems on V5.4-001, FIS believes that it is very hardware dependent and rare. It is also theoretically possible for this to manifest itself as a segmentation violation (SIG-11) on certain (usually older) x86 architecture CPUs, but FIS was was never able to replicate this in the GT.M development environment (S9K10-002786)

    • [V5.4-002A] M-profiling counts all types of FOR loops appropriately, and captures time consistently. When nesting levels exceed the facility's capacity to retain information, M-profiling stops detailed reporting and reports all subsequent time as a total. Previously FOR iterations were miscounted or not reported, and times could be very inaccurate; high levels of nesting could cause time capture to stop and restart with no accounting for the time between. M-profiling cannot and does not provide exact time information, but does provide a useful representation of where application code spends CPU cycles. Relative times reported by M-profiling should be meaningful. (S9L03-002804)

    • [V5.4-002A] The compiler gives FULLBOOLWARN warnings only in cases where the evaluation contains an AND (&) or an OR (!) with a $increment(), extrinsic function, or external call in other than the first element. In V5.4-002, it gave inappropriate warnings even in these cases where the side effect items are always evaluated. (S9L03-002807)

    • [V5.4-002B] $QLENGTH() and $QSUBSCRIPT() accept the non-standard (square-bracket) form of extended reference. Previously they only accepted the standard (up-bar) form. (S9L06-002813)

    • [V5.4-002B] GT.M handles job interrupts inside of a TP transaction more robustly. This fixes a regression introduced in V5.4-000, where a job interrupt that occurs inside a TP transaction that has not yet done any global reference but does some global reference inside the job interrupt code causing the first global reference after retunr from the job interrupt code to abnormally terminate with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) error. Note this abnormal termination could not affect database integrity. (S9L06-002816)

    • [V5.4-002B] $QSUBSCRIPT() returns a correct value when the selected subscript is exactly 0 (zero). Starting in V5.4-001, selecting a 0 subscript caused $QSUBSCRIPT() to return not only the 0 but all subsequent subscripts in the name. (S9L06-002820)

    • [V5.4-002B] $ZCONVERT() issues an ICUERROR error when ICU returns an inappropriate or unexpected error. Previously the process terminated with a GTMASSERT. [UNIX](S9L06-002821)

    • [V5.4-002B] VIEW "TRACE" works with triggers and call-ins. Previously, use of the VIEW "TRACE" facility with triggers or call-ins resulted in a GTMASSERT. [UNIX] (S9L06-002822)

    • ZWRITE accepts Intrinsic Special Variables (ISVs) as single arguments. This provides a way to easily expose non-graphic characters in individual ISVs. ISVs cannot be selected with the pattern matching and range syntax that ZWRITE accepts for global and local variables. As before, ZSHOW "I" provides a way to get all ISVs. In previous versions ZWRITE did not permit ISV arguments. (C9806-000511)

    • GT.M has a completely new implementation of local variables that scales much better for local variables with large numbers of nodes while preserving or even slightly improving upon the fast performance of local variables with small number of nodes that the previous implementation handled well. The new implementation outperforms global variables at all sizes tested, even local variables with hundreds of thousands of nodes. For local variables with more than a few thousand nodes, global variables outperformed the prior implementation. There is no functional difference.

      This refactoring effort also improved some other aspects of performance.

      The gtm_lvscale environment variable previously available to tune local variable structures is now ignored. You can safely let it remain in shell scripts that are designed to span GT.M versions with both local variable implementations.

      As part of the same effort, $QUERY() with standard NULL collation no longer skips descendants of an empty string subscript.

      Also as part of this effort, GT.M uniformly enforces the rule that a collation transform (or reverse transform) cannot modify an empty string ("NULL") subscript. In prior versions some, but not all operations enforced this rule, which applies to global variables as well as local variables. Note that transforms should not introduce empty string subscripts and GT.M does not currently protect against this. (C9905-001087)

    • An attempt to use a subscripted FOR control variable and calculate values assigned to it using expressions with side effects generates a FORCTRLINDX error. This construct presents some issues that can potentially cause incorrect results or segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). Previous releases did not guard against this problem. Note GT.M does not detect the loss of a control variable specified by indirection and then destroyed within scope (by a KILL or NEW) and when it detects the loss of an unsubscripted indirect control variable does not report the name of that variable. FIS recommends against such usage as a source of program fragility; refer to C9L03-003392. (C9B03-001660)

    • GT.M provides an option to control evaluation of Boolean expressions (expressions evaluated as a logical TRUE or FALSE). By default, GT.M stops evaluating such expression as soon as it establishes a definitive result. For example, in this mode, neither 0&$$abc^def() or 1!$$abc^def() ever executes $$abc^def(). In the case of global references, such as 0&^a or 1!^a, GT.M correctly sets $Reference and the naked indicator without actually accessing the global variable.

      The settings may be altered with a VIEW command using an argument evaluating to (case-insensitive) "FULL_BOOLEAN" to select a evaluation order that evaluates expression atoms with short-circuit side effects prior to Boolean evaluation: "NOFULL_BOOLEAN" to select the traditional GT.M evaluation order which stops as soon as the result is known, and "FULL_BOOLWARN" which evaluates like "FULL_BOOLEAN" but also produces a BOOLSIDEFFECT warning when it encounters Boolean expressions that may induce side-effects; that is: expressions with side effects after the first Boolean operator - extrinsic functions, external calls and $INCREMENT(). The new gtm_boolean environment variable (UNIX) or GTM_BOOLEAN logical name (OpenVMS) provide initial values to control this behavior at process startup. If gtm_boolean is undefined or evaluates to an integer zero (0), the initial setting the default "NOFULL_BOOLEAN", if it evaluates to an integer one (1), the initial setting is "FULL_BOOLEAN" and if it evaluates to integer two (2) the initial setting is "FULL_BOOLWARN". Other numeric values are reserved for possible future controls - do not use them.

      These are compilation settings and the object code determines run-time execution independent of the current setting. As changing the compiler setting does not clear previously compiled and cached XECUTE arguments, changing the setting before an XECUTE may or may not produce a desired effect. "FULL_BOOLWARN" does not produce warnings on XECUTE arguments with potential side effects in Boolean evaluation.

      $VIEW("FULL_BOOLEAN") returns a string describing the current compiler setting.Note that while the FULL_BOOLEAN setting ensures that the side-effect expression atoms execute, it does not produce results that match full left-to-right evaluation in cases where the side-effect operation alters variables that appear before it in the Boolean expression. Therefore it's prudent to use the FULL_BOOLWARN setting to identify and evaluate and appropriately adjust the use of side-effect expression atoms in Boolean expressions.

      GT.M does not short-circuit evaluation if the first argument of a $INCREMENT() uses indirection. In prior releases, GT.M always compiled in "NOFULL_BOOLEAN" order, but exhibited inappropriate behavior when the first argument to $INCREMENT() used indirection, including spurious VAREXPECTED errors with no variable named by the error message, and incorrectly maintained $REFERENCE (and the naked indicator) when it skipped a $INCREMENT() both of whose arguments were global variables. If your application uses indirection for the first argument of $INCREMENT() in Boolean expressions, please analyze and test those instances thoroughly.

      Note that in the default short-circuit mode, global references within an extrinsic function are not reflected in the $REFERENCE of the caller, regardless of whether or not the extrinsic actually executes - this behavior is unchanged. (C9B04-001673)

    • Call ins offer a gtm_cip() interface, similar to gtm_ci() but using a handle, which improves performance on calls after the first one. gtm_cip() replaces the first argument of gtm_ci() with an argument of type struct ci_name_descriptor which contains the routine name and a handle to the call in function. GT.M populates the empty handle on the first call; the caller must not modify the handle (or bad things happen). Prior versions only offered the original gtm_ci() interface. This change also improved the performance of the original gtm_ci() interface. [UNIX] (C9D07-002340),

    • The gtm_exit call for GT.M call-ins cleans up any pending timers setup using the gt_timers interface and releases all associated memory. Previously, gtm_exit could leak a modest amount of memory used to track the timers. [UNIX](C9E12-002687)

    • $ZDATE() provides a date representation for day 0 (31-Dec-1840) and accepts two to six consecutive "Y" characters to indicate digits of year. Previously, $ZDATE() only accepted "YY" and "YEAR" to indicate two- and four-digit years respectively, and $ZDATE() of zero (0) produced an empty output. For example:

      GTM>write $zdate(123456789,"DAY MON DD, YYYYYY") 
 FRI MAR 17, 339854 
-GTM>

      (C9H02-002824)

    • [V5.4-002B] M-profiling more accurately reports time for large M programs with extensive routine invocations and tracks nested invocations as long as GT.M has available stack. In V5.4-002A, M-profiling over-reported time and, upon exceeding 1024 levels of nesting, aggregated all further time in one special entry. Note that the M-profiling changes in V5.4-002A were still more representative of relative time spent than in earlier versions. (C9L04-003409)

    • An "unlink all" capability allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref as the only current entry in the M virtual stack; GT.M preserves local variables and IO devices across the transition. ZGOTO to level 0 with an entryref specified (for example, ZGOTO 0:entryref) invokes this facility, which behaves as follows:

      • If the current invocation is a call-in, raise a ZGOCALLOUTIN error.

      • Stop M-Profiling (if active).

      • Unwind all routines in the M stack.

      • Unlink all routines, release allocated memory, and close any shared libraries containing GT.M generated object code.

      • Purge all cached objects (code generated for XECUTE and indirection).

      • Reset $ECODE, $REFERENCE, and $TEST to their initial (empty) values. Values of other intrinsic special variables are not affected.

      Previously, such usage terminated the process. [UNIX] (C9I09-003043)

    • [V5.4-002B] GT.M uniformly reports REQRUNDOWN for attempts to access an improperly shutdown database from the same node that last used it. Previously it sometimes inappropriately reported CLSTCONFLICT; CLSTCONFLICT indicates that the database was last used on, or is still in use on another node. [UNIX] (C9J03-003100)

    • [V5.4-002A] GTM properly resumes after a MUPIP INTRPT recognized during a ZSHOW or some forms of the FOR command. Previously, GTM was likely to resume, not where it was interrupted but at a previously executed location usually causing a GTMASSERT or SEG-V (UNIX SIG-11 or OpenVMS ACCVIO). (C9J06-003137)

    • The first line of an external call table is a path to the shared library containing the entry points for the external calls; GT.M permits that path to include environment variables, which are parsed and expanded with the same logic used for file names in segments in global directories. The environment variable names only include the "$"sign, "_", and alphanumerics. Note that GT.M parsing for environment variables does not handle curly-brace ({}) usage. For example, use $mysharedlibpath not ${mysharedlibpath}. [UNIX] (C9J09-003200)

    • GT.M correctly handles short (less than 3-byte) FIFO and PIPE READs in UTF-8 mode when they are not preceded by a UTF-8 Byte Order Mark (BOM). Previously a such READ could block if less than 3 bytes were available. [UNIX] (C9K05-003275)

    • GT.M no longer writes a <LF> to a PIPE device with unprocessed characters when the previous operation was a WRITE. Prior versions, performed this unnecessary flush of the PIPE. GT.M handles read x#n:0 correctly for the PIPE device. Previously, $TEST indicated a timeout even when READ returned the requested number of characters; and in some situations READ returned fewer characters than were available. [UNIX] (C9K08-003312)

    • GT.M again generates a GTM_FATAL_ERROR* ZSHOW type dump when it receives a fatal signal as it used to do except, by default, for segmentation violation (SIG-11). In V5.4-001, this diagnostic feature was inadvertently removed. [UNIX] (C9K08-003318)

    • GT.M loads ICU version 4.4 correctly when run in UTF-8 mode. Prior versions reported DLLNOOPEN or ICUSYMNOTFOUND error when trying to load ICU version 4.4 [Linux, Solaris, AIX, HP-UX IA64] (C9K09-003322)

    • GT.M reports the correct value for $ZREALSTOR. Since V5.3-001 the value was under-reported on some platforms potentially to the point of going negative and thus appearing as a very large value. [Linux, Tru64] (C9K10-003336)

    • $QSUBSCRIPT() handles multiple quotes mixed with non-graphic characters. In prior versions, this combination in a $QSUBSCRIPT() argument could give an incorrect result or fail with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K10-003338)

    • GT.M gives an UNDEF error when attempting to return an alias container where a subscript value is undefined. Previously, GT.M gave segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K12-003347)

    • GT.M handles the setup of the JOB command STARTUP script correctly - including issuing an error message if script fails. In V5.4-000[A] and V5.4-001 the argument might not be properly terminated and thus cause unpredictable results; also, the command did not report STARTUP script errors. GT.M issues an ERROR_SYSCALL message to the system log file if the JOB command PRIORITY variable fails. Previously, it made no report. [UNIX] (C9L02-003364)

    • [V5.4-002B] Device changes primarily for, but not restricted to, z/OS FIFO devices:

      • On z/OS, incorrect tagging can result when an OPEN command creates a new (not previously existing) fifo with the READONLY deviceparameter, as a GT.M READONLY attachment to a the fifo does no tagging, and relies on the first writer to tag the device. To ensure proper tagging under these circumstances, create the underlying fifo with the proper tagging before executing the GT.M OPEN command. Creation/tagging is unnecessary when the first writer attaches to the device before the reader performs the OPEN. Previously, a GT.M writer process which created and tagged a fifo could still result in the reader process getting incorrect tagging, resulting in inappropriate data conversion. [z/OS]

      • On z/OS, when a process performs an unrestricted (read/write) OPEN on a FIFO, or one with the WRITEONLY deviceparameter, it protects against uninitialized memory. Previously such a process could terminate with a segmentation violation (SIG-11). [z/OS]

      • On z/OS, when a process encounters an IO exception while performing an OPEN on a FIFO (other than with the READONLY deviceparameter), it removes both the GT.M device descriptor and the underlying OS fifo. Previously, such a process abandoned the OS fifo rather than removing it. [z/OS]

      • On UNIX, if a process attempts to READ from a sequential file, FIFO, or PIPE device opened with the WRITEONLY deviceparameter, it issues a GTM-E-DEVICEWRITEONLY error. Previously, such a READ caused a Bad file descriptor error. [UNIX]

      • On any platform when a process attempts to WRITE to a sequential file, FIFO or PIPE opened READONLY, it issues a GTM-E-DEVICEREADONLY. Previously, such a WRITE caused a GTM-E-RMSRDONLY. (C9L03-003382)

    • [V5.4-002A] ZBREAK manages the caching action of code objects more appropriately. Previously, substantial numbers of ZBREAK actions slowly choked off the indirection cache which slowed down all XECUTE and indirect processing. The nature of this issue typically kept it confined to lengthy debugging sessions, although it was possible to have a program demonstrate the problem by introducing lots of ZBREAK actions. The workaround was to restart the process. (C9L03-003390)

    • [V5.4-002B] FOR accepts a subscripted control variable in all circumstances. In addition it provides better detection, handling and reporting of cases where the control variable is KILL’d within the scope of the FOR. Note that NOUNDEF, which treats undefined values as the empty string, does not apply to missing FOR control variables when they are incremented, as that would tend to create apparently unintended indefinite loops. For example FOR A=1:1:10 KILL A gives an UNDEF error on the increment from 1 to 2 even in NOUNDEF mode. In V5.4-002 the most troublesome constructs gave a FORCTRLINDX error; prior to that they could produce unreliable results including segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). In addition, when the control variable disappeared in the scope of the FOR, the UNDEF message sometimes did not contain the name of the variable. (C9L03-003392)

    • [V5.4-002A] KILL * (KILL alias) works correctly and alias operations deal appropriately with alias containers at subscript levels greater than one. Previously, KILL * incorrectly removed even alias associations that were out of scope at the time of the command, possibly resulting in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) under some conditions. ZWRITE correctly reports subscripts of alias containers. Previously large numbers of alias containers could cause ZWRITE to misreport some subscripts even though the variables were correct. In addition, alias processing no longer skips alias containers at subscript depths greater than one. In V5.4-002, some alias processing skipped alias containers unless all their subscripted ancestors were also alias containers, which could cause associated variables to inappropriately disappear or processes to leak storage and possibly result in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9L04-003400)

    +GTM>

    (C9H02-002824)

  • [V5.4-002B] M-profiling more accurately reports time for large M programs with extensive routine invocations and tracks nested invocations as long as GT.M has available stack. In V5.4-002A, M-profiling over-reported time and, upon exceeding 1024 levels of nesting, aggregated all further time in one special entry. Note that the M-profiling changes in V5.4-002A were still more representative of relative time spent than in earlier versions. (C9L04-003409)

  • An "unlink all" capability allows a process to disassociate itself from all routines that it has linked, release memory, and continue execution with a new entryref as the only current entry in the M virtual stack; GT.M preserves local variables and IO devices across the transition. ZGOTO to level 0 with an entryref specified (for example, ZGOTO 0:entryref) invokes this facility, which behaves as follows:

    • If the current invocation is a call-in, raise a ZGOCALLOUTIN error.

    • Stop M-Profiling (if active).

    • Unwind all routines in the M stack.

    • Unlink all routines, release allocated memory, and close any shared libraries containing GT.M generated object code.

    • Purge all cached objects (code generated for XECUTE and indirection).

    • Reset $ECODE, $REFERENCE, and $TEST to their initial (empty) values. Values of other intrinsic special variables are not affected.

    Previously, such usage terminated the process. [UNIX] (C9I09-003043)

  • [V5.4-002B] GT.M uniformly reports REQRUNDOWN for attempts to access an improperly shutdown database from the same node that last used it. Previously it sometimes inappropriately reported CLSTCONFLICT; CLSTCONFLICT indicates that the database was last used on, or is still in use on another node. [UNIX] (C9J03-003100)

  • [V5.4-002A] GTM properly resumes after a MUPIP INTRPT recognized during a ZSHOW or some forms of the FOR command. Previously, GTM was likely to resume, not where it was interrupted but at a previously executed location usually causing a GTMASSERT or SEG-V (UNIX SIG-11 or OpenVMS ACCVIO). (C9J06-003137)

  • The first line of an external call table is a path to the shared library containing the entry points for the external calls; GT.M permits that path to include environment variables, which are parsed and expanded with the same logic used for file names in segments in global directories. The environment variable names only include the "$"sign, "_", and alphanumerics. Note that GT.M parsing for environment variables does not handle curly-brace ({}) usage. For example, use $mysharedlibpath not ${mysharedlibpath}. [UNIX] (C9J09-003200)

  • GT.M correctly handles short (less than 3-byte) FIFO and PIPE READs in UTF-8 mode when they are not preceded by a UTF-8 Byte Order Mark (BOM). Previously a such READ could block if less than 3 bytes were available. [UNIX] (C9K05-003275)

  • GT.M no longer writes a <LF> to a PIPE device with unprocessed characters when the previous operation was a WRITE. Prior versions, performed this unnecessary flush of the PIPE. GT.M handles read x#n:0 correctly for the PIPE device. Previously, $TEST indicated a timeout even when READ returned the requested number of characters; and in some situations READ returned fewer characters than were available. [UNIX] (C9K08-003312)

  • GT.M again generates a GTM_FATAL_ERROR* ZSHOW type dump when it receives a fatal signal as it used to do except, by default, for segmentation violation (SIG-11). In V5.4-001, this diagnostic feature was inadvertently removed. [UNIX] (C9K08-003318)

  • GT.M loads ICU version 4.4 correctly when run in UTF-8 mode. Prior versions reported DLLNOOPEN or ICUSYMNOTFOUND error when trying to load ICU version 4.4 [Linux, Solaris, AIX, HP-UX IA64] (C9K09-003322)

  • GT.M reports the correct value for $ZREALSTOR. Since V5.3-001 the value was under-reported on some platforms potentially to the point of going negative and thus appearing as a very large value. [Linux, Tru64] (C9K10-003336)

  • $QSUBSCRIPT() handles multiple quotes mixed with non-graphic characters. In prior versions, this combination in a $QSUBSCRIPT() argument could give an incorrect result or fail with a segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K10-003338)

  • GT.M gives an UNDEF error when attempting to return an alias container where a subscript value is undefined. Previously, GT.M gave segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9K12-003347)

  • GT.M handles the setup of the JOB command STARTUP script correctly - including issuing an error message if script fails. In V5.4-000[A] and V5.4-001 the argument might not be properly terminated and thus cause unpredictable results; also, the command did not report STARTUP script errors. GT.M issues an ERROR_SYSCALL message to the system log file if the JOB command PRIORITY variable fails. Previously, it made no report. [UNIX] (C9L02-003364)

  • [V5.4-002B] Device changes primarily for, but not restricted to, z/OS FIFO devices:

    • On z/OS, incorrect tagging can result when an OPEN command creates a new (not previously existing) fifo with the READONLY deviceparameter, as a GT.M READONLY attachment to a the fifo does no tagging, and relies on the first writer to tag the device. To ensure proper tagging under these circumstances, create the underlying fifo with the proper tagging before executing the GT.M OPEN command. Creation/tagging is unnecessary when the first writer attaches to the device before the reader performs the OPEN. Previously, a GT.M writer process which created and tagged a fifo could still result in the reader process getting incorrect tagging, resulting in inappropriate data conversion. [z/OS]

    • On z/OS, when a process performs an unrestricted (read/write) OPEN on a FIFO, or one with the WRITEONLY deviceparameter, it protects against uninitialized memory. Previously such a process could terminate with a segmentation violation (SIG-11). [z/OS]

    • On z/OS, when a process encounters an IO exception while performing an OPEN on a FIFO (other than with the READONLY deviceparameter), it removes both the GT.M device descriptor and the underlying OS fifo. Previously, such a process abandoned the OS fifo rather than removing it. [z/OS]

    • On UNIX, if a process attempts to READ from a sequential file, FIFO, or PIPE device opened with the WRITEONLY deviceparameter, it issues a GTM-E-DEVICEWRITEONLY error. Previously, such a READ caused a Bad file descriptor error. [UNIX]

    • On any platform when a process attempts to WRITE to a sequential file, FIFO or PIPE opened READONLY, it issues a GTM-E-DEVICEREADONLY. Previously, such a WRITE caused a GTM-E-RMSRDONLY. (C9L03-003382)

  • [V5.4-002A] ZBREAK manages the caching action of code objects more appropriately. Previously, substantial numbers of ZBREAK actions slowly choked off the indirection cache which slowed down all XECUTE and indirect processing. The nature of this issue typically kept it confined to lengthy debugging sessions, although it was possible to have a program demonstrate the problem by introducing lots of ZBREAK actions. The workaround was to restart the process. (C9L03-003390)

  • [V5.4-002B] FOR accepts a subscripted control variable in all circumstances. In addition it provides better detection, handling and reporting of cases where the control variable is KILL’d within the scope of the FOR. Note that NOUNDEF, which treats undefined values as the empty string, does not apply to missing FOR control variables when they are incremented, as that would tend to create apparently unintended indefinite loops. For example FOR A=1:1:10 KILL A gives an UNDEF error on the increment from 1 to 2 even in NOUNDEF mode. In V5.4-002 the most troublesome constructs gave a FORCTRLINDX error; prior to that they could produce unreliable results including segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). In addition, when the control variable disappeared in the scope of the FOR, the UNDEF message sometimes did not contain the name of the variable. (C9L03-003392)

  • [V5.4-002A] KILL * (KILL alias) works correctly and alias operations deal appropriately with alias containers at subscript levels greater than one. Previously, KILL * incorrectly removed even alias associations that were out of scope at the time of the command, possibly resulting in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO) under some conditions. ZWRITE correctly reports subscripts of alias containers. Previously large numbers of alias containers could cause ZWRITE to misreport some subscripts even though the variables were correct. In addition, alias processing no longer skips alias containers at subscript depths greater than one. In V5.4-002, some alias processing skipped alias containers unless all their subscripted ancestors were also alias containers, which could cause associated variables to inappropriately disappear or processes to leak storage and possibly result in segmentation violation (UNIX SIG-11 and OpenVMS ACCVIO). (C9L04-003400)

    • Utilities-MUPIP

    • MUPIP BACKUP -REPLACE applies to both specified files and files in specified directories. A destination specification that causes the same backup command to reuse a destination file for more than one source generates an error regardless of whether or not you specify -REPLACE. Note that -REPLACE only applies to -DATABASE backups. In prior versions -REPLACE only applied when the command specified target directories, but not files. [UNIX] (S9E02-002420)

    • [V5.4-002B] MUPIP RUNDOWN ensures correct relationship among database ID, database Name and Shared Memory before running down database files. RUNDOWN sends the IDs of any removed IPC resource (shared memory and/or semaphore) to the operator log. Previously, under certain unusual operational circumstances, MUPIP RUNDOWN could take a suboptimal or unintended action and display any removed IPC resource IDs on only the terminal issuing the command. The table below summarizes the modified cases. [UNIX] (C9K06-003280) (S9C01-002024)

      Case

      		 @@ -1223,10 +1223,10 @@ GTM>

      (C9H02-002824)

      		•

      Oldest shared memory rundown"File is in use by another process" message for one or more other segments

      -

    • For performance reasons, MUPIP RECOVER and MUPIP ROLLBACK never use the synchronous / direct I/O option when opening journal files for recovery or rollback, whether or not the SYNC_IO option of MUPIP SET -JOURNAL was used to create them. In prior versions, RECOVER and ROLLBACK used the same options as the run-time system, even though synchronous / direct I/O is not optimal for these MUPIP operations. [UNIX] (S9E04-002445)

    • Source and Receiver Server processes include additional information (host error number and error string) in their respective log files when they encounter connection reset errors while sending or receiving messages. Prior versions did not include this information and hence made it difficult to determine the cause of the connection reset. (S9I04-002680)

    • [V5.4-002B] MUPIP RECOVER -BACKWARD checks the database transaction number against the journal file transaction number and if they don’t align, issues an error. Previously, RECOVER -BACKWARD, did not detect such a mismatch between database and journal file, which could have allowed an operator error to cause a flawed recovery leaving integrity errors. (S9I05-002683) (C9L01-003351)

    • [V5.4-002B] A new environment variable called gtm_jnl_release_timeout allows you to specify the number of seconds that a replicating Source Server waits when there is no activity on an open journal file before closing it. The default wait period is 300 seconds. If gtm_jnl_release_timeout specifies 0, the Source Server keeps the current journal files open until shutdown. The maximum value for gtm_jnl_release_timeout is 2147483 seconds. Previously, the Source Server kept the current journal files open until its shutdown. [UNIX] (S9I12-002716)

    • [V5.4-002A] The startup of a replicating instance deals appropriately with a sequence where the Receiver Server is killed and restarted with Helper Processes and then the Update Process is killed. Previously, the Receiver Server hung trying to ensure proper shutdown of the Update Process started before its own start. Note that such a condition is more likely to occur in a test environment simulating system crashes than in a real environment - in a real environment, if a system crashes, all processes and all resources go down, a condition from which GT.M recovers well. [UNIX] (S9L04-002809)

    • [V5.4-002A] When a MUPIP REPLICATE -INSTANCE_CREATE command renames an existing file due to a name conflict, it prints a FILERENAME message acknowledging the operation. Additionally, a -NOREPLACE qualifier on the command prevents the renaming of a potentially existing file. Previously, MUPIP REPLICATE did not offer the -NOREPLACE option and did the rename without a warning message. [UNIX] (S9I05-002990)

    • MUPIP JOURNAL issues the JNLTPNEST error message as a Warning because MUPIP processes the associated condition appropriately. In previous versions JNLTPNEST was an Error, which was slightly misleading. (C9D11-002456)

    • MUPIP REPLIC -SOURCE -SHOW -JNLPOOL displays a maximum of 16 printable characters for the "Instance File Created Nodename" field of the replication instance file header. Prior versions, displayed a maximum of 15 printable characters. [UNIX] (C9K03-003241)

    • MUPIP RUNDOWN removes orphaned semaphores even if no shared memory exists. In prior versions, RUNDOWN did not remove abandoned GT.M database semaphores when they had no corresponding shared memory. [UNIX] (C9K07-003297)

    • MUPIP INTEG -SUBSCRIPT and -BLOCK preserve the integrity of the database in case it has a mix of V4 and V5 format GDS blocks. In prior V5 versions, this used to silently introduce a DBBTUWRNG integ error in an otherwise clean database. (C9K07-003303)

    • MUPIP SET JOURNAL and MUPIP BACKUP, as part of turning journaling ON in a database, create journal files that are in sync with the database. In previous versions, it was possible in rare cases for these to create a journal file whose transaction number did not match with the database. This used to result in JNLFILOPN and JNLTRANSLSS errors when opening this journal file which caused GT.M to make one more (extra) journal switch to fix this situation. (C9K08-003304)

    • MUPIP JOURNAL RECOVER and ROLLBACK defer MUPIP STOP request-handling during several brief sections of the code to maintain the integrity of the database state after an interrupted RECOVER/ROLLBACK process. Previously, a MUPIP STOP command received by a MUPIP JOURNAL RECOVER/ROLLBACK process within a certain small window could leave journaling/replication disabled. (C9K08-003305)

    • [V5.4-002B] MUPIP JOURNAL -RECOVER -FORWARD and MUPIP JOURNAL -EXTRACT -FORWARD report a JNLFILEDUP error when the command specifies duplicate journal files in forward recovery. Previously, they incorrectly reported JNLTNOUTOFSEQ or JNLBADRECFMT errors while processing the journal files instead of detecting the duplicate input and refusing to proceed.MUPIP JOURNAL -INTERACTIVE requires a non-empty response but defaults to a NO on an EOF. Previously, it defaulted an empty response to YES and prompted again after an EOF. Because the -INTERACTIVE option seems seldom used, we felt it prudent to adopt a more conservative approach; you can always rerun the RECOVER and answer YES if you desire a different outcome. In addition, -INTERACTIVE only re-prints the continue prompt upon wrong user input and only waits for a single response. Previously, it re-printed the prompt at a fixed interval even if there was no user input and might have ignored a response, sometimes requiring the user to answer twice.Utility programs looking for an interactive YES/NO including LKE, MUPIP ENDIANCVT, and MUPIP JOURNAL report any error reading from user input and consider it as a NO. Previously, MUPIP JOURNAL would re-print the prompt and LKE and MUPIP ENDIANCVT would assume a default NO without reporting the issue. [UNIX] (C9K08-003315)

    • MUPIP REPLICATE -INSTANCE_CREATE defers renaming the current replication instance file until after it verifies that it has sufficient information to create a new one. In prior versions, if the replicating instance name was not provided (either in the command line or through the environment variable gtm_repl_instname), this command renamed the existing instance file and issued a REPLINSTNMUNDEF error without creating a new replacement instance file. [UNIX] (C9K09-003320)

    • MUPIP INTEG reports misaligned database file as DBMISALIGN. Previously, this error was not differentiated from DBTOTBLK. (C9K11-003341)

    • MUPIP JOURNAL ROLLBACK recovers the database correctly even if it has NULL records (a special type of journal record). These records are never written into the journal file when executing normal application logic, but are potentially inserted into the replication stream by schema change filters for rolling upgrades that involve changes to the application schema or internally by GT.M's replication mechanism when replicating between different GT.M versions (for example, from a version with trigger support to one without). Previously, the presence of such records could cause rollback to create more unreplicated (lost) transactions than necessary which also meant rolling the database further back in time than necessary. (C9L02-003362)

    • [V5.4-002A] MUPIP JOURNAL -ROLLBACK consumes less memory when checking transaction consistency. Previously, the memory consumption during ROLLBACK was nearly eight times higher. (C9L02-003366)

    • [V5.4-002A] MUPIP BACKUP allows an argument in the destination list to be as long as the maximum path the platform can support. Previously, MUPIP BACKUP silently truncated arguments longer than 255 characters to that length. [UNIX except z/OS] (C9L03-003386)

    • [V5.4-002A] The Source Server stops with a REPLNOMULTILINETRG error when it is replicating to an instance that does not support multi-line triggers and it needs to send a trigger definition update that includes a multi-line XECUTE code string too large to store in a single record. This fixes an issue resulting from the introduction of multi-line triggers in V5.4-002, in which the Source Server sent the trigger update, the replicating instance accepted the update, but would never XECUTE it because the XECUTE code string appeared empty. [UNIX] (C9L04-003399)

    • [V5.4-002B] The first database access after a MUPIP RESTORE of an encrypted data database leaves the encryption properly set up. Previously, that first database access after a RESTORE cleared the encryption state, even when the database was encrypted. The workaround was to correct the encryption setting with DSE. [UNIX] (C9L04-003406)

    • [V5.4-002B] The replication log files record information about orphaned semaphores (GT.M generated) and shared memory resulting from an error in the shutdown of the Receiver Server or Update Process. In prior versions, GT.M did not record this information in the replication log files. [UNIX] (C9L06-003434)

    - Utilities-Other Than MUPIP

    • GDE appropriately handles adjacent maximum length (31 character) names. In Previous versions, such names mapped correctly originally, but either gave an error when attempting to use GDE on the global directory or could disappear on reprocessing the directory. (C9E11-002658)

    • The GT.M configure installation script no longer creates arch.gtc in the parent of the installation directory. Previously, this script erroneously created this file. [UNIX] (S9K08-002783)

    • GDE provides a -COMMAND qualifier for the SHOW command with an optional -FILE= qualifier. This displays commands that recreate the current global directory state. -FILE= optionally specifies a file to hold the commands. In addition, SHOW -TEMPLATE gives an encryption indication for BG except on OpenVMS where it does not apply. Prior versions did not offer SHOW -COMMAND or display encryption status for BG templates. (C9H08-002889)

    • If the environment variable $LC_CTYPE is not specified when the $gtm_chset environment variable specifies that GT.M run in UTF-8 mode, the gtmprofile script 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. [UNIX] (C9K07-003299)

    • The automatic execution of GDE in the gtmprofile script to create a default global directory if one does not exist includes an stty sane command to turn on echoing of characters in the terminal session. Previously, it left the terminal in a state where it did not echo characters. Note that this provides a workaround to an issue in GDE/GT.M - in our judgment at the current time this is a better option than attacking the root cause, given the minor nature of the issue and the simplicity of the workaround. [UNIX] (C9K08-003310)

    • The GT.CM OMI server gives an appropriate error message for an over-sized value of gtm_dist and exits. This also changes the GT.CM log file destination to match that of the rest of GT.M. Previously such an operation error caused a stack overflow and core file, and error messages went to the user.error log while messages from other GT.M components go to user.info. [UNIX] (C9K08-003311)

    • GDE SHOW includes reserved bytes value (RES) for templates. In prior releases SHOW did not display this information. (C9K08-003317)

    • The configure installation script correctly modifies the gpgagent.tab file to point to the GT.M encryption library in the installation directory. Previously, it failed to do this on AIX and HP-UX Itanium. This may have resulted in the pinentry program not working correctly on AIX/HP-UX Itanium servers using GPG2 with the reference implementation encryption plugin. [AIX, HP-UX Itanium] (C9K09-003323)

    • The configure installation script is executable and explicitly executes /bin/sh. Previously, the execute bit was not set and a shell had to be explicitly specified. The revised script also supports changing the installation group without also having to restrict access to this group. Previously, the installation group could not be changed without restricting access to this group. The installation script correctly handles invalid ICU version entry lower than 3.6. Previously, this resulted in shell script errors. The installation script correctly handles restricted group for UTF-8 mode. Previously, it did not allow the owner of the installation to execute in UTF-8 mode if not a member of the restricted group. [UNIX] (C9K09-003324)

    • [V5.4-002A] GT.M utilities defer signal handling during process start-up. Previously, there was a small window where an error during process start-up could cause a deadlock on resources used to log the error message. [UNIX] (C9K11-003342)

    • If bash is available, the add_db_key.sh script properly handles Unicode characters in directory paths. Previously, on Ubuntu 6.10 and above the default sh is dash instead of bash. Dash does not properly handle Unicode characters in directory paths, for example, during indirection. Because the add_db_key.sh script runs with the default shell, it failed. [UNIX] (C9L01-003356)

    • GTMSECSHR properly reports an error if it is unable to change directory to its temporary directory. Previously, GTMSECSHR did not report this error. Note: It would be highly unusual for GTMSECSHR not be able to change directories - perhaps indicative of something amiss in the system or OS configuration. [UNIX] (C9L02-003365)

    • The new gtminstall script is an experimental facility to simplify GT.M installation. It attempts to provide reasonable defaults while allowing considerable customization using command line switches. When unpacked and executed as root without any parameters, that is, just ./gtminstall, from within the directory where the GT.M distribution is unpacked it installs GT.M with M mode support only in the directory /usr/lib/fis-gtm/version_platform, for example, /usr/lib/fis-gtm/V5.4-002_x86_64.

      Separated from GT.M as a stand-alone script, it attempts to determine the latest / current production version for its hardware platform, and to download that version and install it. gtminstall --help lists the options.

      Example usage scenarios include:

      sudo gtminstall # installs latest version in M mode only
+

  • For performance reasons, MUPIP RECOVER and MUPIP ROLLBACK never use the synchronous / direct I/O option when opening journal files for recovery or rollback, whether or not the SYNC_IO option of MUPIP SET -JOURNAL was used to create them. In prior versions, RECOVER and ROLLBACK used the same options as the run-time system, even though synchronous / direct I/O is not optimal for these MUPIP operations. [UNIX] (S9E04-002445)

  • Source and Receiver Server processes include additional information (host error number and error string) in their respective log files when they encounter connection reset errors while sending or receiving messages. Prior versions did not include this information and hence made it difficult to determine the cause of the connection reset. (S9I04-002680)

  • [V5.4-002B] MUPIP RECOVER -BACKWARD checks the database transaction number against the journal file transaction number and if they don’t align, issues an error. Previously, RECOVER -BACKWARD, did not detect such a mismatch between database and journal file, which could have allowed an operator error to cause a flawed recovery leaving integrity errors. (S9I05-002683) (C9L01-003351)

  • [V5.4-002B] A new environment variable called gtm_jnl_release_timeout allows you to specify the number of seconds that a replicating Source Server waits when there is no activity on an open journal file before closing it. The default wait period is 300 seconds. If gtm_jnl_release_timeout specifies 0, the Source Server keeps the current journal files open until shutdown. The maximum value for gtm_jnl_release_timeout is 2147483 seconds. Previously, the Source Server kept the current journal files open until its shutdown. [UNIX] (S9I12-002716)

  • [V5.4-002A] The startup of a replicating instance deals appropriately with a sequence where the Receiver Server is killed and restarted with Helper Processes and then the Update Process is killed. Previously, the Receiver Server hung trying to ensure proper shutdown of the Update Process started before its own start. Note that such a condition is more likely to occur in a test environment simulating system crashes than in a real environment - in a real environment, if a system crashes, all processes and all resources go down, a condition from which GT.M recovers well. [UNIX] (S9L04-002809)

  • [V5.4-002A] When a MUPIP REPLICATE -INSTANCE_CREATE command renames an existing file due to a name conflict, it prints a FILERENAME message acknowledging the operation. Additionally, a -NOREPLACE qualifier on the command prevents the renaming of a potentially existing file. Previously, MUPIP REPLICATE did not offer the -NOREPLACE option and did the rename without a warning message. [UNIX] (S9I05-002990)

  • MUPIP JOURNAL issues the JNLTPNEST error message as a Warning because MUPIP processes the associated condition appropriately. In previous versions JNLTPNEST was an Error, which was slightly misleading. (C9D11-002456)

  • MUPIP REPLIC -SOURCE -SHOW -JNLPOOL displays a maximum of 16 printable characters for the "Instance File Created Nodename" field of the replication instance file header. Prior versions, displayed a maximum of 15 printable characters. [UNIX] (C9K03-003241)

  • MUPIP RUNDOWN removes orphaned semaphores even if no shared memory exists. In prior versions, RUNDOWN did not remove abandoned GT.M database semaphores when they had no corresponding shared memory. [UNIX] (C9K07-003297)

  • MUPIP INTEG -SUBSCRIPT and -BLOCK preserve the integrity of the database in case it has a mix of V4 and V5 format GDS blocks. In prior V5 versions, this used to silently introduce a DBBTUWRNG integ error in an otherwise clean database. (C9K07-003303)

  • MUPIP SET JOURNAL and MUPIP BACKUP, as part of turning journaling ON in a database, create journal files that are in sync with the database. In previous versions, it was possible in rare cases for these to create a journal file whose transaction number did not match with the database. This used to result in JNLFILOPN and JNLTRANSLSS errors when opening this journal file which caused GT.M to make one more (extra) journal switch to fix this situation. (C9K08-003304)

  • MUPIP JOURNAL RECOVER and ROLLBACK defer MUPIP STOP request-handling during several brief sections of the code to maintain the integrity of the database state after an interrupted RECOVER/ROLLBACK process. Previously, a MUPIP STOP command received by a MUPIP JOURNAL RECOVER/ROLLBACK process within a certain small window could leave journaling/replication disabled. (C9K08-003305)

  • [V5.4-002B] MUPIP JOURNAL -RECOVER -FORWARD and MUPIP JOURNAL -EXTRACT -FORWARD report a JNLFILEDUP error when the command specifies duplicate journal files in forward recovery. Previously, they incorrectly reported JNLTNOUTOFSEQ or JNLBADRECFMT errors while processing the journal files instead of detecting the duplicate input and refusing to proceed.MUPIP JOURNAL -INTERACTIVE requires a non-empty response but defaults to a NO on an EOF. Previously, it defaulted an empty response to YES and prompted again after an EOF. Because the -INTERACTIVE option seems seldom used, we felt it prudent to adopt a more conservative approach; you can always rerun the RECOVER and answer YES if you desire a different outcome. In addition, -INTERACTIVE only re-prints the continue prompt upon wrong user input and only waits for a single response. Previously, it re-printed the prompt at a fixed interval even if there was no user input and might have ignored a response, sometimes requiring the user to answer twice.Utility programs looking for an interactive YES/NO including LKE, MUPIP ENDIANCVT, and MUPIP JOURNAL report any error reading from user input and consider it as a NO. Previously, MUPIP JOURNAL would re-print the prompt and LKE and MUPIP ENDIANCVT would assume a default NO without reporting the issue. [UNIX] (C9K08-003315)

  • MUPIP REPLICATE -INSTANCE_CREATE defers renaming the current replication instance file until after it verifies that it has sufficient information to create a new one. In prior versions, if the replicating instance name was not provided (either in the command line or through the environment variable gtm_repl_instname), this command renamed the existing instance file and issued a REPLINSTNMUNDEF error without creating a new replacement instance file. [UNIX] (C9K09-003320)

  • MUPIP INTEG reports misaligned database file as DBMISALIGN. Previously, this error was not differentiated from DBTOTBLK. (C9K11-003341)

  • MUPIP JOURNAL ROLLBACK recovers the database correctly even if it has NULL records (a special type of journal record). These records are never written into the journal file when executing normal application logic, but are potentially inserted into the replication stream by schema change filters for rolling upgrades that involve changes to the application schema or internally by GT.M's replication mechanism when replicating between different GT.M versions (for example, from a version with trigger support to one without). Previously, the presence of such records could cause rollback to create more unreplicated (lost) transactions than necessary which also meant rolling the database further back in time than necessary. (C9L02-003362)

  • [V5.4-002A] MUPIP JOURNAL -ROLLBACK consumes less memory when checking transaction consistency. Previously, the memory consumption during ROLLBACK was nearly eight times higher. (C9L02-003366)

  • [V5.4-002A] MUPIP BACKUP allows an argument in the destination list to be as long as the maximum path the platform can support. Previously, MUPIP BACKUP silently truncated arguments longer than 255 characters to that length. [UNIX except z/OS] (C9L03-003386)

  • [V5.4-002A] The Source Server stops with a REPLNOMULTILINETRG error when it is replicating to an instance that does not support multi-line triggers and it needs to send a trigger definition update that includes a multi-line XECUTE code string too large to store in a single record. This fixes an issue resulting from the introduction of multi-line triggers in V5.4-002, in which the Source Server sent the trigger update, the replicating instance accepted the update, but would never XECUTE it because the XECUTE code string appeared empty. [UNIX] (C9L04-003399)

  • [V5.4-002B] The first database access after a MUPIP RESTORE of an encrypted data database leaves the encryption properly set up. Previously, that first database access after a RESTORE cleared the encryption state, even when the database was encrypted. The workaround was to correct the encryption setting with DSE. [UNIX] (C9L04-003406)

  • [V5.4-002B] The replication log files record information about orphaned semaphores (GT.M generated) and shared memory resulting from an error in the shutdown of the Receiver Server or Update Process. In prior versions, GT.M did not record this information in the replication log files. [UNIX] (C9L06-003434)

    • + Utilities-Other Than MUPIP

    • GDE appropriately handles adjacent maximum length (31 character) names. In Previous versions, such names mapped correctly originally, but either gave an error when attempting to use GDE on the global directory or could disappear on reprocessing the directory. (C9E11-002658)

    • The GT.M configure installation script no longer creates arch.gtc in the parent of the installation directory. Previously, this script erroneously created this file. [UNIX] (S9K08-002783)

    • GDE provides a -COMMAND qualifier for the SHOW command with an optional -FILE= qualifier. This displays commands that recreate the current global directory state. -FILE= optionally specifies a file to hold the commands. In addition, SHOW -TEMPLATE gives an encryption indication for BG except on OpenVMS where it does not apply. Prior versions did not offer SHOW -COMMAND or display encryption status for BG templates. (C9H08-002889)

    • If the environment variable $LC_CTYPE is not specified when the $gtm_chset environment variable specifies that GT.M run in UTF-8 mode, the gtmprofile script 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. [UNIX] (C9K07-003299)

    • The automatic execution of GDE in the gtmprofile script to create a default global directory if one does not exist includes an stty sane command to turn on echoing of characters in the terminal session. Previously, it left the terminal in a state where it did not echo characters. Note that this provides a workaround to an issue in GDE/GT.M - in our judgment at the current time this is a better option than attacking the root cause, given the minor nature of the issue and the simplicity of the workaround. [UNIX] (C9K08-003310)

    • The GT.CM OMI server gives an appropriate error message for an over-sized value of gtm_dist and exits. This also changes the GT.CM log file destination to match that of the rest of GT.M. Previously such an operation error caused a stack overflow and core file, and error messages went to the user.error log while messages from other GT.M components go to user.info. [UNIX] (C9K08-003311)

    • GDE SHOW includes reserved bytes value (RES) for templates. In prior releases SHOW did not display this information. (C9K08-003317)

    • The configure installation script correctly modifies the gpgagent.tab file to point to the GT.M encryption library in the installation directory. Previously, it failed to do this on AIX and HP-UX Itanium. This may have resulted in the pinentry program not working correctly on AIX/HP-UX Itanium servers using GPG2 with the reference implementation encryption plugin. [AIX, HP-UX Itanium] (C9K09-003323)

    • The configure installation script is executable and explicitly executes /bin/sh. Previously, the execute bit was not set and a shell had to be explicitly specified. The revised script also supports changing the installation group without also having to restrict access to this group. Previously, the installation group could not be changed without restricting access to this group. The installation script correctly handles invalid ICU version entry lower than 3.6. Previously, this resulted in shell script errors. The installation script correctly handles restricted group for UTF-8 mode. Previously, it did not allow the owner of the installation to execute in UTF-8 mode if not a member of the restricted group. [UNIX] (C9K09-003324)

    • [V5.4-002A] GT.M utilities defer signal handling during process start-up. Previously, there was a small window where an error during process start-up could cause a deadlock on resources used to log the error message. [UNIX] (C9K11-003342)

    • If bash is available, the add_db_key.sh script properly handles Unicode characters in directory paths. Previously, on Ubuntu 6.10 and above the default sh is dash instead of bash. Dash does not properly handle Unicode characters in directory paths, for example, during indirection. Because the add_db_key.sh script runs with the default shell, it failed. [UNIX] (C9L01-003356)

    • GTMSECSHR properly reports an error if it is unable to change directory to its temporary directory. Previously, GTMSECSHR did not report this error. Note: It would be highly unusual for GTMSECSHR not be able to change directories - perhaps indicative of something amiss in the system or OS configuration. [UNIX] (C9L02-003365)

    • The new gtminstall script is an experimental facility to simplify GT.M installation. It attempts to provide reasonable defaults while allowing considerable customization using command line switches. When unpacked and executed as root without any parameters, that is, just ./gtminstall, from within the directory where the GT.M distribution is unpacked it installs GT.M with M mode support only in the directory /usr/lib/fis-gtm/version_platform, for example, /usr/lib/fis-gtm/V5.4-002_x86_64.

      Separated from GT.M as a stand-alone script, it attempts to determine the latest / current production version for its hardware platform, and to download that version and install it. gtminstall --help lists the options.

      Example usage scenarios include:

      sudo gtminstall # installs latest version in M mode only
 sudo gtminstall --utf8 default # install latest version with UTF-8 mode support
-sudo gtminstall --distrib /Distrib/GT.M V5.4-000A # install V5.4-000A from a local directory

      [UNIX](C9L03-003371)

    • [V5.4-002A] DSE CHANGE -BLOCK -TN correctly handles updates to encrypted databases without journaling. In V5.4-002, using DSE on such a database to set the transaction number for a block to a value that is less than the current database transaction number caused segmentation violation (SIG-11). [UNIX] (C9L03-003391)

    • [V5.4-002B] The gtminstall script deals with releases with letter suffixes. Previously the script would fail with an expression error. [UNIX] (C9L05-003410)

    • [V5.4-002B] Command line processing in utilities (like DSE, LKE, MUPIP) handles empty user responses robustly. Previously, in rare cases, an empty response (a newline) could result in segmentation violation (SIG-11) [UNIX] (C9L05-003411)

    +sudo gtminstall --distrib /Distrib/GT.M V5.4-000A # install V5.4-000A from a local directory

    [UNIX](C9L03-003371)

  • [V5.4-002A] DSE CHANGE -BLOCK -TN correctly handles updates to encrypted databases without journaling. In V5.4-002, using DSE on such a database to set the transaction number for a block to a value that is less than the current database transaction number caused segmentation violation (SIG-11). [UNIX] (C9L03-003391)

  • [V5.4-002B] The gtminstall script deals with releases with letter suffixes. Previously the script would fail with an expression error. [UNIX] (C9L05-003410)

  • [V5.4-002B] Command line processing in utilities (like DSE, LKE, MUPIP) handles empty user responses robustly. Previously, in rare cases, an empty response (a newline) could result in segmentation violation (SIG-11) [UNIX] (C9L05-003411)

    • Error Messages

    The new and revised error message(s) for V5.4-002 are as follows:

    BOOLSIDEFFECT

    BOOLSIDEFFECT, Extrinsic ($$), External call ($&) or $INCREMENT() with potential side effects in Boolean expression

    Compile Time Warning: This optional message, accompanied by a line and column pointing to the issue, indicates a Boolean expression that contains a side effect in a term other than its first. By default, GT.M may skip evaluating such terms.

    Action: Revise the code to your standards and use the VIEW (arguments [NO]FULL_BOOLEAN or FULLBOOL_WARN) command and / or the environment variable (gtm_boolean) to select the appropriate setting for GT.M handling of this construct.

    DBBADUPGRDSTATEM

    DBBADUPGRDSTATE, Correcting conflicting values for fields describing database version upgrade state in the file header for region rrrr (ffff) - make fresh backups with new journal files immediately.

    Run Time Warning: This warning message in the operator log indicates region rrrr (file ffff) had an out-of-design combination of database upgrade conditions, which may have caused defective journal files and -online BACKUPs. GT.M automatically corrects this condition, but you should investigate the possible causes for such file header damage.

    Action: Make fresh backups with new journal files immediately.

    DBMISALIGN

    DBMISALIGN, Database file xxxx has yyyy blocks which does not match alignment rules. Reconstruct the database from a backup or extend it by at least zzzz blocks.

    MUPIP Error: This is an auxiliary message, and is preceded by a primary message.

    Action: Follow the primary message description and action as specified in this manual.

    DBSHMNAMEDIFF [V5.4-002B]

    Database file ffff points to shared memory mmmm which points to a different database file

    Runtime Error: Database access gives this error, if the database is copied or moved without properly closing it. This error indicates that database ffff and shared memory mmmmm do not correspond to each other.

    Action: Perform MUPIP RUNDOWN on the database.

    DEVICEWRITEONLY [V5.4-002B]

    Cannot read from a write-only device

    Run-time error: The application made an attempt to READ from a device in a WRITEONLY state, typically due to the OPEN command specifications

    Action: Check for logic errors and revise the code.

    @@ -1238,9 +1238,9 @@ sudo gtminstall --distrib /Distrib/GT.M V5.4-000A # install V5.4-000A from a loc JNLTPNEST

    JNLTPNEST, Mupip journal command found nested TP transactions for journal file jjjj at offset oooo at transaction number nnnn

    MUPIP Warning: MUPIP JOURNAL -RECOVER or ROLLBACK encountered a TSTART record for transaction nnnn at offset oooo in journal file jjjj while already processing an uncommitted transaction. Since the run-time system should never produce this situation, the journal file is suspect. MUPIP discards the in-progress transaction and proceeds.

    Action: Extract the journal file(s) and use the context from the message to find the transactions in question and adjust for any lost or tangled transaction(s).

    REPLJNLCNFLCT

    REPLJNLCNFLCT, Journaling cannot be turned nnnn on database file ffff as the replication state is rrrr and must also be turned nnnn in the same command

    MUPIP Warning: This message indicates that the requested journaling state (nnnn) and current replication state (rrrr, which is either "ON" or "[WAS_ON]" ) do not match and the command must explicitly specify an outcome such that they do match. WAS_ON is a state where journaling has been lost but replication has been able to continue by running from the journal pool without needing the lost journal file(s) - the MUPIP SET command needs to explicitly turn this state back to ON.

    Action: Issue one or more commands that leave journaling and replication either both ON or both OFF.

    REPLNOXENDIAN

    REPLNOXENDIAN, SSSS side is running on a GT.M version that does not support cross-endian replication. Upgrade the SSSS side to at least V5.3-003 to support cross-endian replication. Cannot continue.

    MUPIP Error : The originating or the replicating instance in a cross-endian replication environment issue this error when a replication startup detects that the other side is running on a GT.M version without needed cross-endian support.

    Action : Upgrade the instance for which the error was reported to a version with support for cross-endian replication.

    - REPLNOMULTILINETRG [V5.4-002A]

    REPLNOMULTILINETRG, Sequence number ssss contains a trigger definition too large for transmission to the current replicating instance, which does not support multi-line triggers - stopping replication.

    Run Time Error: If you are upgrading an originating instance before a replicating instance (FIS recommends upgrading the replicating instance first), you must not use any new functionality in the originating instance until all the replicating instances have been upgraded so they can also support that functionality. Starting with V5.4-002, trigger definitions code for XECUTE can have multiple lines while prior to that it had to fit on a single line. The Update Process produces this error and stops the Source Server when an older replicating instance cannot handle a multi-line trigger XECUTE code that is too large to store in a single record.

    Action: To continue replication, either upgrade the replicating instance to V5.4-002 or higher or change the application to eliminate multi-line triggers that are too large to store in a single record.

    + REPLNOMULTILINETRG [V5.4-002A]

    REPLNOMULTILINETRG, Sequence number ssss contains a trigger definition too large for transmission to the current replicating instance, which does not support multi-line triggers - stopping replication.

    Run Time Error: If you are upgrading an originating instance before a replicating instance (FIS recommends upgrading the replicating instance first), you must not use any new functionality in the originating instance until all the replicating instances have been upgraded so they can also support that functionality. Starting with V5.4-002, trigger definitions code for XECUTE can have multiple lines while prior to that it had to fit on a single line. The Update Process produces this error and stops the Source Server when an older replicating instance cannot handle a multi-line trigger XECUTE code that is too large to store in a single record.

    Action: To continue replication, either upgrade the replicating instance to V5.4-002 or higher or change the application to eliminate multi-line triggers that are too large to store in a single record.

    REPLXENDIANFAIL

    REPLXENDIANFAIL, SSSS side encountered error while doing endian conversion at journal sequence number JJJJ

    Error: The originating or the replicating instance in a cross-endian replication environment report this error whenever they detect that the endian conversion failed.

    Action: Restart replication - if the transmission caused the problem, it’s probably intermittent. Perform a MUPIP JOURNAL -EXTRACT -DETAIL on the journal files and search for the sequence number JJJJ to look for anything different about that journal record. If the report is on the secondary, take a fresh backup on the originating instance requesting new journal files, refresh the replicating instance and restart replication.

    - SECNODZTRIGINTP

    SECNODZTRIGINTP, Sequence number ssss contains $ZTRIGGER() updates made inside a transaction which the current replicator does not support. The replicator must be upgraded to at least V5.4-002 to support this type of transaction. Cannot continue

    MUPIP Error: The originating instance encountered a $ZTRIGGER() function within a transaction with sequence number ssss. However, the replicating instance is running a pre-V5.4-002 version which cannot handle $ZTRIGGER() within a transaction.

    Action: Upgrade the replicating instance to V5.4-002 or later. Alternatively adjust the application code to avoid using $ZTRIGGER() within a transaction.

    In [V5.4-002A], changed the message summary of SECNODZTRIGINTP to:

    + SECNODZTRIGINTP

    SECNODZTRIGINTP, Sequence number ssss contains $ZTRIGGER() updates made inside a transaction which the current replicator does not support. The replicator must be upgraded to at least V5.4-002 to support this type of transaction. Cannot continue

    MUPIP Error: The originating instance encountered a $ZTRIGGER() function within a transaction with sequence number ssss. However, the replicating instance is running a pre-V5.4-002 version which cannot handle $ZTRIGGER() within a transaction.

    Action: Upgrade the replicating instance to V5.4-002 or later. Alternatively adjust the application code to avoid using $ZTRIGGER() within a transaction.

    In [V5.4-002A], changed the message summary of SECNODZTRIGINTP to:

    SETINSETTRIGONLY

    SETINSETTRIGONLY, ISV iiii can only be modified in a 'SET' type trigger

    Run Time Error: Code invoked for a trigger other than SET (such as KILL or ZTRIGGER) attempted to modify Intrinsic Special Variable iiii, which applies only within a SET trigger context.

    Action: Review the trigger definition and correct the types or the code to avoid the issue.

    SHMREMOVED [V5.4-002B]

    Shared Memory id mmmm removed from the system

    MUPIP information: MUPIP RUNDOWN removed shared memory segment mmmm with a GT.M signature because it was not currently in use.

    Action: No action required.

    SSFILOPERR

    SSFILOPERR, Error while doing oooo operation on file ffff

    Mupip Error: This operator log message indicates operation oooo on snapshot file ffff failed. Note in certain timing situations this action might be reported to the operator log after the snapshot consuming process (say MUPIP INTEG) has finished with the snapshot file, in which case it's harmless. If the consuming process issues a REGSSFAIL error, then it was definitely prevented from completing its tack because of the SSFILOPERR.

    Action: Analyze the operation and the file characteristics and take appropriate action to clear the problem.

    TPLOCKRESTMAX

    TPLOCKRESTMAX, Transaction restarts due to unavailability of locks not allowed in a final TP retry more than nnnn times

    Run Time Error: This indicated a timed LOCK within a transaction was consistently unavailable. In order to prevent the process from waiting for the LOCK while holding a database resource (critical section) the transaction has restarted nnnn times without success. This error limits the possibilities for this issue cascading into a live-lock (consuming resources trying to do something that is "not happening").

    Action: Analyze the locking protocol for issues of dead lock or unexpected LOCK durations and rework appropriately. Note that FIS recommends against using LOCKs within transactions, as GT.M protects the transaction integrity independent of LOCK protocols. If you wish to impose a conventional locking strategy for a transaction, place the LOCK and unlock around (outside) the transaction. While it is possible to use a LOCK within a transaction for signaling, that technique is typically problematic as it violates transactional Isolation and should likely be restricted to testing.

    diff --git a/articles/GTM_V5_4_000A_Release_Notes.html b/articles/GTM_V5_4_000A_Release_Notes.html index 5136d47..70574fe 100644 --- a/articles/GTM_V5_4_000A_Release_Notes.html +++ b/articles/GTM_V5_4_000A_Release_Notes.html @@ -1,5 +1,5 @@ - Technical Bulletin - GT.M V5.4-000/V5.4-000A Release Notes

    Technical Bulletin - GT.M V5.4-000A Release Notes

    Copyright A(C) 2010 Fidelity Information Services, Inc.  All Rights Reserved. 
     

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

     

    GT.Ma?c is a trademark of Fidelity Information Services, Inc.  Other trademarks are the property of their respective owners.  

     

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

    Revision History

    Version Date Summary
    1.6 June 15, 2011 Added more information on S9I08-002695.
    1.5 July 14, 2010 Improved the description of C9K01-003225.
    1.4 April 5, 2010 Added more information about using GT.M on IBM pSeries AIX.
    1.3 March 25, 2010 Added an entry for S9K03-002761.
    1.2 March 19, 2010
    1.1 February 19, 2010
    1.0 February 2, 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

     

    Table of Contents

    Click here to go directly to the Changes section.
     
     

    Conventions

    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 "/".


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


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


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


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


    Return to Table of Contents

    Bulletin Overview

    GT.M V5.4-000A provides timely remediation of a small number of issues with V5.4-000 (highlighted as V5.4-000A).

     

    In V5.4-000A, there is no change in the adaptive (auto-tuning) behavior of the MOREREADTIME deviceparameter introduced in V5.4-000.  However, in this bulletin, we have added an improved description of the "MOREREADTIME" deviceparameter. For more information, see "GT.M Documentation Addendum".  

      

    GT.M V5.4-000 adds a major new feature to GT.M, as well as a significant enhancement to operational capability for 24x365 database operation.


    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity.  Refer to the GT.M Triggers Technical Bulletin for details.


      Please note: FIS considers the implementation of triggers in V5.4-000/V5.4-000A to be robust, and entirely appropriate for development and testing short of production deployment.  With the next release of GT.M, they will have had gone through many more cycles of automated regression testing under a broader range of conditions, and will be considered production grade at that time.  If you are an FIS customer and are ready to deploy in production an application that uses GT.M triggers, please contact your FIS account manager about the timing and availability of a GT.M release in which triggers will be considered production grade.  Depending on circumstances, we may even decide then that the implementation of triggers in V5.4-000/V5.4-000AA is robust enough for production.  Except for the triggers functionality, everything else in V5.4-000/V5.4-000A is considered production grade.


    • MUPIP INTEG can now check a database for structural integrity while applications continue to operate.  In prior releases of GT.M, MUPIP INTEG would freeze updates.  Online operation is now the default for databases that contain no version 4 format database blocks.

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


    Please note: The deprecated "Z" pseudo-transactions (bracketed by ZTSTART / ZTCOMMIT) are not supported in this release.  FIS strongly urges you to remove their use from your code - since they have been deprecated for many years, they are no longer tested and may be removed from GT.M at any time.

     

     

    Return to Table of Contents

    Platforms

    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:

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


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


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

     

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


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

    Hewlett-Packard Alpha/AXP Tru64 UNIX

    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.


    • While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.
    IBM System z z/OS V1R10 At this time, FIS is not providing a 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 Programmera??s Guide for appropriate alternative solutions.

    x86_64 GNU/Linux

    Red Hat Enterprise Linux 5.4; Ubuntu 8.04 LTS through 9.10

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

     

    Return to Table of Contents

    Migrating to 64-bit platforms

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

     

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

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

    Call-ins and External Calls

    Parameter type

    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

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

    Internationalization (Collation)

    Parameter type

    32-Bit

    64-bit

    Remarks

    gtm_descriptor in gtm_descript.h

    4-byte

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

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

    Environment Translation 

    Parameter type

    32-Bit

    64-bit

    Remarks

    gtm_string_t type in gtmxc_types.h

    4-byte

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

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

     

    Return to Table of Contents

    Recompile

    • Recompile all M and C source files.


     

    Return to Table of Contents

    Rebuild Shared Libraries or Images

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


     

    Return to Table of Contents

    Additional Installation Instructions 

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

    UNIX

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

    2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

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


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

    GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. 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 a system that has the "posixaio" option instead of "aio" (also called "legacy aio"), use SMIT as follows:


    • smit posixaio (for gui mode) or

    • smitty posixaio (for text mode)

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

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


    Since GT.M is not a thread safe application, starting multiple threads in a process, or sometimes even loading libpthreads can cause process failure with symptoms such as SIG-11. On AIX, sometimes seemingly innocuous actions can pull libpthreads into a process and cause it to fail. Two known cases are (a) use of non-POSIX (Olson) names such as America/Chicago for the TZ environment variable - please use POSIX names such as CST6CDT instead - and (b) using LDAP to authenticate userids. Other cases probably exist.


    If you expect a database file or journal 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.

    OpenVMS

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


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

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


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


    Return to Table of Contents

    Upgrading to GT.M V5.4-000A

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


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

     

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

    Stage 1: Upgrading your Global Directory

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

    To upgrade from any prior GT.M version:

     

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

     

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

     

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

     

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

    Stage 2: Upgrading your Database Files  

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

     

     

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

     

     

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

     

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

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

     

     
    No database file upgrade procedure is necessary if you upgrade from GT.M V5.0-000 or later to V5.3-000 or later. However, you may need to run the MUPIP REORG a??UPGRADE command to upgrade any previously used but free block that may have been missed during earlier upgrade cycles.  You do not need to run MUPIP REORG a??UPGRADE in either of the following situations:
     
    • A database was created by a V5 MUPIP CREATE
    • A database has previously been completely processed by a MUPIP REORG a??UPGRADE from V5.3-003 or later
     
    If you have already run the MUPIP REORG a??UPGRADE command in a version prior to V5.3-003, subsequent versions cannot determine whether or not it was done correctly and record warnings in the operator log for running MUPIP REORG -UPGRADE. Therefore, you must either:
     
    • Run the MUPIP REORG a??UPGRADE command again
    • Run the DSE CHANGE a??FULLY_UPGRADED=1 command to stop the warnings
       
      Caution: Do not run the DSE CHANGE -FILEHEADER a??FULLY_UPGRADED=1 command unless you are absolutely certain you have previously successfully run to completion MUPIP REORG a??UPGRADE from V5.3-003 or later. Using this command when inappropriately may lead to database integrity issues.

     

    For additional upgrade considerations, see "Database Compatibility Notes".  
     
    Database Compatibility Notes
    • Changes to the database file header may occur in any release.  GT.M automatically upgrades database file headers as needed.  Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.
    • Databases created with V5.3-004 and later can grow to a maximum size of 224M (234,881,024) blocks.  This means, for example, that with an 8KB block size, the maximum database file size is 1,792GB (this is the size of a single global variable; a database consists of any number of global variables).  A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128M to 224M blocks.
    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128M (134,217,728) blocks.  Until and unless a database created with V5.3-004 (or later), or created in V5.0-000 through V5.3-003, exceeds the 128M block limit of earlier V5 GT.M releases, it can be accessed by releases V5.0-000 through V5.3-003. 

    Stage 3: Upgrading your Replication Instance File

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

     

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


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


    • On AIX systems, if you upgrade from 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later
    • On Linux systems, if you upgrade from a 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later or from a 64-bit release to a newer 32-bit release
    • On Sun SPARC Solaris, if you upgrade from 32-bit pre-V5.3-003 to 64-bit V5.3-003

     

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

     

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

     

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

    Stage 4: Upgrading your Journal Files

    To upgrade from any prior GT.M version: 

     
    • Create a fresh backup of your database.
    • Generate new journal files (without back-links).

     

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

    Return to Table of Contents

    Managing M mode and UTF-8 mode

    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 selected platforms.  On a system that does not have ICU 3.6 or later installed, or on other platforms, 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-000A_i686, then gtmprofile and gtmcshrc set $gtm_dist to /usr/lib/fis-gtm/gtm_V5.4-000A_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. 

           

    Compiling ICU on HP PA-RISC HP-UX

    Note: All GT.M versions prior to V5.3-004 require exactly ICU 3.6, however, V5.3-004 (or later) accept ICU 3.6 or later.
     
    As of this writing (November, 2009), ICU version 3.6 can be compiled on HP PA-RISC HP-UX with the following configuration:
     

     

    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:

     

    1. Ensure that system environment variable $PATH includes the location of all the compilers mentioned above.

    2. Download the source code of ICU (in this example, version 3.6 for C from http://icu.sourceforge.net/download/3.6.html#ICU4C)

    3. At the shell prompt, execute the following commands:

       
       
      gunzip -d < icu4c-3_6-src.tgz | tar -xf -
      cd icu/source/
      chmod +x runConfigureICU configure install-sh
      runConfigureICU --enable-debug HP-UX/ACC --enable-64bit-libs? --enable-rpath a??disable-threads
       
      gmake
       
      gmake check
       
      gmake install
       

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

    5. ICU is now installed in /usr/local.

     

    • By default, ICU is installed in /usr/local.  If you install ICU in a different directory, type:

      • runConfigureICU HP-UX/ACC --prefix=<install_path> --enable-64bit-libs? --enable-rpath a??disable-threads

      • Then execute the gmake commands, and set the environment variable $LD_LIBRARY_PATH to point to the appropriate location.

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

    Compiling ICU on HP Integrity IA64 HP-UX

    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:
     
    1. Ensure that system environment variable PATH includes the location of all the compilers mentioned above.
    2. Download the source code of ICU (in this example version 3.6 for C from http://icu.sourceforge.net/download/3.6.html#ICU4C).
    3. At the shell prompt, run the following commands:

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

    • Then run the gmake commands, and set the environment variable $LD_LIBRARY_PATH to point to the appropriate location.
      

    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.

     

    Return to Table of Contents

    Setting the environment variable TERM

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

     

     
    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M.  GT.M itself does not have any knowledge of specific terminal control characteristics.  Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal.  You may need to add new terminfo entries depending on their specific platform and implementation.  The terminal (emulator) vendor may also be able to help.
    • GT.M uses the following terminfo capabilities.  The full variable name is followed by the capname in parenthesis:
      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

     

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

     

    Return to Table of Contents

    Installing Compression Libraries

    If you plan to use the optional compression facility for replication, you must provide the compression library.  The GT.M interface for compression libraries accepts the zlib compression libraries without any need for adaptation.  These libraries are included in many UNIX distributions and are downloadable from the zlib home page.  If you prefer to use other compression libraries, you need to configure or adapt them to provide the same API provided by zlib.  Simple instructions for compiling zlib on a number of platforms follow.  Although GT.M uses zlib, zlib is not FIS software and FIS does not support zlib.  These instructions are merely provided as a convenience to you.


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


    Solaris/cc compiler from Sun Studio:

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

    HP-UX(IA64)/HP C compiler:

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

    AIX/XL compiler:

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

    Linux/gcc:

    ./configure --shared
    make CFLAGS="-m64"
     
    z/OS:
     

    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.


    Change History 

    V5.4-000A

    Fixes and enhancements specific to V5.4-000A are: 

     

    S9K03-002761 Using buffered reads for accessing the source code required for $TEXT(), ZPRINT, and error reporting.
    S9D10-002376 Checking for defined variables and empty strings in local variable subscripts now conforms to the M standard.
    S9K02-002754 Prevent GDE from losing maximum length NAME entries.
    S9K02-002755 $QUIT on x86 and x86-64 GNU/Linux returns a uniformly appropriate result.
    S9K02-002756 Prevents a process from hanging (or failing) on a compilation error in a line longer than 1023 characters.
    S9K02-002757 Better clean up orphaned snapshot files from an INTEG that terminates abnormally.
    S9K03-002759 VIEW "NOLVLULLSUBS", "NOUNDEF" combination correctly issues an error for a SET using an undefined local variable as a subscript.
    C9K02-002758 During installation correctly set setuid bit for the gtmsecshr wrapper and appropriate permission settings for GDE help in utf-8 mode.
    C9H10-002920 Prevent error for blanks lines in a GDE command file and correctly resume an interrupted (<CTRL-C>) command file.
    C9J07-003156 Replication source server improvements for database files in WAS_ON replication state.
    C9K02-003239 Prevent a rare SIG-11 that occurs when MUPIP BACKUP -ONLINE and MUPIP INTEG -ONLINE run concurrently with M transaction processing.

     

    V5.4-000

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


    S9C11-002251 Error in place of GTMASSERT for full LOCK_SPACE
    S9D08-002354 Error from $GET() when 2nd argument is undefined local variable
    S9I08-002695 New Trigger facility
    S9I09-002699 No more inappropriate error from VIEW "FLUSH" or "JNLWAIT"
    S9J07-002732 Adaptive MOREREADTIME for SOCKET device
    S9J07-002737 More user-friendly UNIX distribution kit
    S9J11-002749 Cleanup of OPEN for [UNIX] PIPE device
    C9902-000839 ONLINE option now usual default for [UNIX] MUPIP INTEG
    C9B12-001842 MUPIP INTEG TN_RESET leaves proper state for BACKUP BYTESTREAM
    C9D07-002356 SOCKET CONNECT improvements
    C9D08-002390 Facility to trigger UNIX diagnostics on processes holding scarce resources
    C9E02-002513 TRUNCATE for sequential files corrected for Linux
    C9F07-002746 $INCREMENT() now starts with a numeric value when adding a string to an undefined global variable
    C9H06-002868 SOCKET device waiting to CONNECT now responds to MUPIP INTRPT
    C9H07-002875 UNIX call-in protects against multiple gtm_init or gtm_exit calls
    C9H10-002913 UTF-8 terminal input protected from loss on INTRPT
    C9J04-003108 $ECODE and $STATUS() protected from change by INTRPT
    C9J04-003110 MUPIP checks journal files for correct ENDIAN
    C9J04-003118 Performance improvement for sequential file READ in UTF-8 mode
    C9J06-003140 UNIX installation makes files executable only if successful
    C9J06-003145 UNIX gtmsecshr protects itself against over-length input in addition to existing wrapper protection
    C9J07-003148 ZWRITE of undefined alias variables
    C9J08-003166 Improve REPLINSTNOHIST error message
    C9J08-003170 Permit z/OS object modules to exceed 32 KB
    C9J08-003174 Improve handling of the loading of ICU used by UTF-8 mode
    C9J08-003178 Improve error message for UNIX IPC issue after an improper shutdown
    C9J08-003179 New ^%XCMD utility to XECUTE shell command line input
    C9J09-003188 Improve CLOSE for [UNIX] PIPE device
    C9J09-003190 Cleanup gtmcrypt_close memory management in the encryption plug-in interface
    C9J09-003195 Improve timing on passive replication server shutdown
    C9J09-003197 Easy of use improvements for managing basic GT.M environments
    C9J09-003198 UNIX deals with invalid group or owner for files
    C9J09-003199 Improvements to UNIX shell interface to protect against over-length input in utility commands
    C9J09-003201 UNIX installation deals with missing "bin" user or group
    C9J10-003202 Prevent rare cases of DBINVGBL errors
    C9J10-003203 Properly maintain $REFERENCE after reverse name-level $ORDER() of a global
    C9J10-003208 DSE protects against failure when encountering certain bad data
    C9J11-003211 Exclusive KILL behavior within an extrinsic function now controlled by an environment variable
    C9J11-003214 Prevent rare cases of an inappropriate TPFAIL GGGG error
    C9J12-003215 Improve performance for very large numbers of local variables
    C9J12-003217 New QUIT * and SET *$$ to return an alias from an extrinsic function
    C9K01-003220 Prevent rare cases of DBKEYORD or DBBADNSUB
    C9K01-003222 MUPIP BACKUP ensures instance file synchronized with database
    C9K01-003225 Maximum UNIX $STORAGE value of 2GB -1


    Return to Table of Contents

    M-Database Access

    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity. Refer to the GT.M Triggers Technical Bulletin for details.


      A MUPIP RECOVER which stops due to an error before making any database modifications also leaves the file header unchanged. Previously, MUPIP RECOVER marked the database header with the "corrupt" flag and did not clear it for that case. (S9I08-002695)

    • GT.M no longer issues JNLCNTRL errors when VIEW "JNLWAIT" commands are executed after a journal file switch. Previously, in rare cases, GT.M incorrectly issued a JNLCNTRL error. (S9I09-002699)

    • GDE now preserves the mapping of multiple lexically adjacent maximum length global names. In prior versions, GDE created such ranges correctly but lost track of them when reloading the global directory for examination or a subsequent update. The workaround was to always reestablish such ranges after invoking GDE. This issue was reported from a pre-V5 environment where the maximum name length was eight characters rather than the current 31 characters. There is less chance of encountering this issue on versions V5.0-000 and later. (S9K02-002754) V5.4-000A

    • GT.M now ensures $INCREMENT() produces a numeric result even when the first argument is an undefined global variable and the second argument is a string containing non-numeric characters. Prior versions returned a string in this condition. If the first argument was a local variable, this worked properly in earlier versions. Note while the case in question is unusual enough to be unlikely, any code that relied on the prior behavior needs updating. (C9F07-002746)

    • GDE now ignores blank lines in command files. After being interrupted while processing a command file, it also properly closes the file and appropriately resumes the next action. In prior versions, GDE treated blank lines as errors and could fail with a GDECHECK error if a command file was interrupted at certain points with <CTRL-C>. (C9H10-002920) V5.4-000A

    • A GT.M process now reports a more helpful ERR_REQRUNDOWN error when it fails to attach to a shared memory segment (because of a prior improper shutdown e.g. kill -9). On detecting such a situation, prior versions instead reported the less helpful ERR_DBFILERR. [UNIX] (C9J08-003178)

    • As long as the operating system permits the access, GT.M now allows access to database files and journals in cases where the system has no user or group information available for the file. Such an unusual situation can arise, for example, when the user and group are provided via NIS, but if NIS is not currently operational the owner and group cannot be determined; or perhaps a user id is deleted while the GT.M process is active. V5.3-004[A] issued a signal-11 in such a case. [UNIX] (C9J09-003198)

    • GT.M now properly releases memory in response to a gtmcrypt_close() function call. Previously, depending upon how quickly memory was re-allocated, a gtmcrypt_close() function call could result in a signal 11 causing GT.M to abnormally terminate. [Unix] (C9J09-003190)

    • GT.M now maintains database integrity even when multiple GT.M processes simultaneously attempt to create the same global variable. This fixes a regression in GT.M V5.3-000 (also present in V5.3-004A and introduced as part of the fixes to C9H09-002901) where, in such situations, it was possible under rare circumstances for the GT.M process to cause database damage (for example, DBINVGBL or DBKEYORD errors). Note that this was an issue only for non-TP updates, that is those which were not surrounded by a TSTART/TCOMMIT. (C9J10-003202)

    • Using "" as the last subscript in a global argument to $ORDER(gvn,-1) or $ZPREVIOUS(gvn) now maintains $REFERENCE correctly. This fixes a regression introduced in GT.M version V5.3-004 (and present in V5.3-004A) as part of the fix for C9E10-002648. (C9J10-003203)

    • GT.M now deals correctly with a set of rare cases where it could inappropriately interpret negative numbers in database block control structures as large positive numbers. Previous versions might terminate with memory access violations, or get into indefinite or inappropriately long loops. This was discovered in testing DSE against a database with intentionally inflicted damage, which we expect is characteristic of the unusual conditions that might expose this issue. (C9J10-003208)

    • GT.M now correctly implements an optimization (that avoids unnecessary global variable tree traversals) for TP transactions. This fixes a regression introduced in GT.M V5.3-004 (and present in V5.3-004A) which in rare cases could cause an incorrect TPFAIL error to be issued (note: this regression did not affect the integrity of the database). (C9J11-003214)
    • GT.M now correctly handles a case where a TP transaction updates the same block, holding the same global multiple times, along with updates of blocks of other globals, and some other process, most likely MUPIP REORG, replaces the block in question with an almost identically configured block from another global in the transaction between the first and second updates of the original block. In previous versions, it was possible for this unusual combination of conditions to cause an incorrect update. The likelihood of this issue increased due to a recent change (C9905-001119) in GT.M V5.3-004 which enabled a global reference caching optimization for TP. (C9K01-003220)


    Return to Table of Contents

    M-Other Than Database Access

    • GT.M now issues a LOCKSPACEFULL error to the application and the operator log when the environment attempts more concurrent M LOCKs than the configured LOCK_SPACE for the region can support. Previously under these conditions, GT.M gave a fatal GTMASSERT error. (S9C11-002251)

    • GT.M now reports an error if the first argument of a two argument $GET() is defined and the second is an undefined local variable. Prior versions returned the value of the first argument and ignored the error mandated by the standard. If the second argument was a global variable, this worked properly in earlier versions. Note that any code that relies on the prior behavior needs updating. (S9D08-002354)

    • GT.M now reports UNDEF errors when it encounters an undefined variable specified for a local variable subscript as it already does for a global variable and as defined in the language standard. In prior versions, KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY() ignored these errors. Under NOUNDEF operation this change has no user impact. Note: code that relied on the earlier non-standard behavior may now give errors and require revision.

      GT.M now supports VIEW "NEVERLVNULLSUBS" to issue the LVNULLSUBS error for any inappropriate use of empty string subscripts in local arrays.  The [new] gtm_lvnullsubs UNIX environment variable can have the values 0 - equivalent to VIEW "NOLVNULLSUBS", 1  (the default) - equivalent to VIEW "LVNULLSUBS" or  2 - equivalent to VIEW "NEVERLVNULLSUBS". In VMS, the initial state of this characteristic is controlled by the GTM$DEFAULTS file. An empty string as the last subscript in $ORDER() and $QUERY() has the semantic significance of requesting the next lexical item and is not subject to NULLSUBS errors. $VIEW("LVNULLSUBS") returns the corresponding numeric value. In prior versions, GT.M only supported NOLVNULLSUBS, which reported the LVNULLSUBS error for SET commands that would have instantiated a prohibited local array subscript, but not for KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY().  $VIEW("LVNULLSUBS") returned 0 for NOLVNULLSUBS and 1 for LVNULLSUBS. Note that code that expected $VIEW("LVNULLSUBS") to provide a truth value must be revised. Empty string subscript checking for global variables is controlled by a database region characteristic that was already comprehensive and is not affected by this change. Note that programs using empty subscripts for references where those references cannot possibly exist are wasting computer resources, so FIS recommends using LVNULLSUBS or NEVERLVNULLSUBS for local variables and NULLSUBS options ALWAYS or NEVER for global variables. (S9D10-002376) V5.4-000A

    • If the OPEN or USE for a SOCKET device does not specify a MOREREADTIME parameter, any READ uses an initial 200msec internal timeout to minimize CPU load. Subsequent attempts to acquire more characters to fulfill the same READ use a 10msec internal timeout. When a MOREREADTIME parameter specifies a value, READ uses that value exclusively. Previously READ used a default of 10msec when no MOREREADTIME parameter was specified and consequently could consume considerable CPU cycles, especially on a lightly loaded system. If your application currently uses the MOREREADTIME parameter, FIS suggest that you consider whether this new behavior provides better performance and/or reduces CPU usage and allows you to avoid specifying MOREREADTIME. (S9J07-002732)

    • The distribution tar file now provides all files owned by the innocuous user:group ids 40535:40535, with no executable or writable files. With the exception of AIX, no directories have write permissions. On AIX, unpacking the distribution file no longer requires root permissions. In prior versions, the configure script adjusted the authorizations, but the distribution had various settings, and, on AIX, required root access to unpack the distribution. [UNIX] (S9J07-002737)

    • GT.M now handles the OPEN of a PIPE device better in certain situations. In prior versions, specifying various device parameters such as ESCAPE for the $PRINCIPAL device when it was a terminal could result in delays or other problems. [UNIX] (S9J11-002749)

    • GT.M now ensures a proper value for $QUIT on x86 and x86-64 GNU/Linux. In V5.4-000 under certain circumstances, it could return an inappropriate result. [x86-64 Linux, x86 Linux] (S9K02-002755) V5.4-000A

    • On compiling an M program, GT.M now omits reports showing the point in the line of code that caused the warning or error for lines longer than 1023 characters; it still reports the line number and column number. In prior versions, attempts to report such long lines could overrun an internal buffer and cause the process to hang or fail. (S9K02-002756) V5.4-000A

    • GT.M now correctly detects an attempt to SET a variable with an "NULL" subscript resulting from an undefined variable when using a VIEW "NOLVNULLSUBS", "NOUNDEF" combination. In versions starting with V5.3-001, the changes associated with C9B03-001664 exposed a latent problem such that GT.M did not detect a SET using an undefined local variable as a subscript as an error, but instead could use an indeterminate value for the subscript. (S9K03-002759) V5.4-000A
    • GT.M now uses buffered reads for accessing the source code required for $TEXT(), ZPRINT, and error reporting. While the performance difference of the buffered read approach is significant, most applications limit their use of the affected features so the overall effect may not be noticeable. Previously, GT.M used unbuffered reads which used many system calls. [UNIX] (S9K03-002761) V5.4-000A

    • The TRUNCATE parameter on USE for sequential file devices now works correctly for Linux. In prior versions, USE could truncate at the wrong position. [Linux] (C9E02-002513)

    • The GT.M SOCKET device behavior has improved in a number of ways.

      SOCKET CONNECT operations now respond to MUPIP INTRPT; in prior versions they did not.

      If the command does not specify a timeout, a SOCKET OPEN now waits for the connection to complete or an interrupting event that terminates the attempt. After an interrupt that does not terminate the connection attempt, such as the default value of $ZINTERRUPT ("IF $ZJOBEXAM()"), the process resumes the wait when the XECUTE of the $ZINTERRUPT completes. Previously, an untimed SOCKET OPEN <device>:CONNECT would make a single attempt to connect and return whether or not it was successful, as if it had a timeout of 0.

      SOCKET CONNECT status values EINPROGRESS, EWOULDBLOCK and, on some platforms, EALREADY now wait for the connection to complete or for the specified timeout to expire.  Previously, GT.M treated these conditions as errors.

      If IOERROR="TRAP" is specified on a SOCKET OPEN or USE, it now invokes any active EXCEPTION, $ETRAP, or $ZTRAP if an error occurs on a CONNECT.  The above status values as well as ECONNREFUSED and ETIMEDOUT are not considered as errors.  Previously, status values other than ECONNREFUSED or ETIMEDOUT would always be treated as errors regardless of the IOERROR value. (C9D07-002356, C9H06-002868)

    • GT.M now allows only a single set of gtm_init/gtm_exit per process and any attempt to call gtm_init/gtm_ci after a gtm_exit returns the code associated with the CALLINAFTERXIT error. Earlier GT.M versions also did not support invoking gtm_init or gtm_ci after a gtm_exit but did not enforce the restriction.[UNIX] (C9H07-002875)

    • GT.M now preserves all terminal input when handling an INTRPT in UTF-8 mode. In addition, INTRPT handling now preserves and restores the INSERT terminal characteristic. In prior versions, there was a slight chance a few characters of UTF-8 mode terminal input for either a READ or Direct Mode input could be lost and/or that the INSERT setting would revert to the default after the INTRPT event. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9H10-002913)
    • GT.M handling of INTRPT processing now protects the values of $ECODE and $STACK() at the time it recognizes the INTRPT. Prior versions allowed the code invoked by the $ZINTERUPT vector to modify those values, probably unintentionally, which could lead to a confused error processing state after completion of the $ZINTERUPT action. (C9J04-003108)

    • READ from a sequential disk file in UTF-8 mode read buffers the file reads for higher throughput. In prior versions, single character reads limited performance. [UNIX] (C9J04-003118)

    • The UNIX installation script for GT.M now sets the executable bits for files such as mumps and mupip only after a successful installation. Previously, the executable bits for these files were sometimes set after an unsuccessful installation. [UNIX] (C9J06-003140)

    • Both gtmsecshr and GT.M now prevent buffer overflow by checking the length of the gtm_tmp environment variable based on the system-specific sun_path length. In recent and properly patched versions of GT.M this was done only in gtmsecshr_wrapper. [UNIX] (C9J06-003145)

    • ZSHOW and ZWRITE now display information about alias variables with no associated data provided at least two of the joined variables are selected by the command argument. In prior releases these commands displayed alias containers with no data, but not alias variables with no data. When an alias exists with no data for the command to display, GT.M holds the variable so that it can become the right-hand side of a proper SET * command. However, if the command selection criteria excludes any other alias, GT.M has insufficient information to form a valid SET * argument and does not display that alias. Alias container variables always have a default value (the empty string), so they are handled differently and display as they did before. (C9J07-003148)

    • GT.M now handles very large object files correctly on z/OS. V5.3-003[A] produced invalid object files if the generated code exceeded 32KB. [z/OS] (C9J08-003170)

    • In UTF8 mode, when the minor version is not specified in the environment variable gtm_icu_version, e.g. 3 instead of 3.6, GT.M issues an ICUSYMNOTFOUND error. Previous versions of GT.M used to issue the ICUVERLT36 error even when the major version specified was greater than or equal to 4. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9J08-003174)

    • ^%XCMD is a utility program that XECUTEs input from the shell command line and returns any error status (truncated to a single byte on UNIX) generated by that code. For example in UNIX: mumps -run %XCMD 'write "hello world",!' would produce "hello world" (C9J08-003179)

    • GT.M now correctly handles the CLOSE of a PIPE device whose STDERR device is the current device.  Prior versions issued a segmentation violation in such a case. [UNIX] (C9J09-003188)

    • The file gtmprofile, which sets up a default environment for GT.M has been completely revamped to make it more robust and to make the out-of-box GT.M experience friendlier.  gtmprofile now sets up default values for more environment variables, creates a default global directory if one does not exist and a default database with before image journaling, if one does not exist.  The new executable shell script gtm uses gtmprofile and automatically recovers the database on startup.  gtm also deletes prior generation journal and temporary files older than the number of days specified by the environment variable gtm_retention.  A new file gdedefaults specifies default values for global directories.  The new gtmprofile script is also idempotent (can be successfully rerun after an abnormal termination), unlike its predecessor.  FIS recommends that system administrators review the gtmprofile and gdedefaults files after installing GT.M, and customize them as needed.  The previous gtmprofile file remains available as gtmprofile_preV54000 - if you want to retain the previous behavior, simply replace gtmprofile with gtmprofile_preV54000.  Note that at this time, the file gtmcshrc has not been similarly revamped for csh/tcsh users (the gtm script does not depend on the underlying shell).  [UNIX] (C9J09-003197)  

    • The distribution tar file may now be installed if there is no "bin" user and/or group defined.  The operator may now enter an alternate user and/or group to own the installation and may also restrict access to this group.  Previously the installation failed if the default bin user were specified and did not exist, or if the bin group did not exist - even if another restricted group was chosen. [UNIX] (C9J09-003201)

    • The new $gtm_stdxkill/GTM_STDXKILL environment/logical variable (UNIX/VMS) which if set to "TRUE", 1, or "YES" enables the standard-compliant behavior to kill local variables in the exclusion list if they had an alias that was not in the exclusion list. GT.M default behavior for exclusive kills thus reverts to its previous behavior, not compliant with the standard, where aliases and pass-by-reference variables specified in an exlusive kill are NOT killed even if their aliases are not specified in the exclusion list. In GT.M V5.3-004 (C9B09-001754), this behavior was changed to be compliant with the standard as part of the alias variables enhancement.  Please note that the default value is FALSE, so you must explicitly ask for standard-compliant behavior. (C9J11-003211)

    • String pool expansion is now more responsive to the rate at which the application requires space for local variables. This enhancement significantly improves the performance of applications that ramp up to atypically large string pool requirements (in the hundreds of thousands of local variable nodes), while preserving the more parsimonious string pool usage of typical applications. (C9J12-003215)

    • GT.M now allows an unsubscripted local variable, alias or alias container to be returned using the QUIT * syntax to a function invocation initiated using a SET *lvn=$$func() syntax. The SET * associates the target "lvn" local variable to the data space specified by the returning QUIT *. Previously GT.M only allowed alias information to be returned using the M pass-by-reference mechanism or by an alias in scope in both the caller and called routines. Additionally, the $QUIT ISV now returns the value "11" to indicate the current routine was invoked by a SET * and is required to return an alias using a QUIT * syntax. Failure to provide a QUIT * return as requested by the invocation produces an ALIASEXPECTED error. Providing a QUIT * return when not requested by the invocation produces a QUITALSINV error. (C9J12-003217)

    • UNIX editions will not report a value for $STORAGE larger than (2GB - 1)  [2,147,483,647], even if more is available. Previous versions could fail with SEG-V (SIG-11) errors while attempting to report $STORAGE values. [UNIX] (C9K01-003225). 

    • The configure installation script now assigns the correct permissions to the gtmsecshr wrapper for a non-restricted group installation.  It also creates symbolic links required for GTM and GDE help in utf-8 mode.  Previously, the setuid bit was not set for the gtmsecshr wrapper on some platforms and [z]help would fail in utf-8 mode.[UNIX] (C9K02-002758) V5.4-000A

     

    Return to Table of Contents

    Utilities-MUPIP

    • MUPIP and GT.M now clean up temporary snapshot files from INTEG under a wider variety of conditions. In V5.4-000, stopping the INTEG with a <CTRL-C> or a signal could leave the snapshot file orphaned. [UNIX] (S9K02-002757) V5.4-000A

    • MUPIP INTEG -REGION now supports the -ONLINE qualifier. This allows checking database structural integrity to run concurrently with database updates. Previously, INTEG froze updates on each region while checking it. Online integ is not supported with the -FILE qualifier. The -NOONLINE qualifier indicates that the database should be frozen during the MUPIP INTEG operation.

      The -ONLINE qualifier is now the default for MUPIP INTEG, except for databases containing V4 blocks, for which the default is -NOONLINE. Note that databases containing V4 blocks should exist only in databases that are in the process of being migrated from V4 to V5; please complete your migration to the V5 format before using MUPIP INTEG -ONLINE.

      The environment variable GTM_BAKTMPDIR (unlike most GT.M environment variables, this is upper case; it is the same directory used for MUPIP BACKUP -ONLINE) can be used to indicate a directory where MUPIP should place the snapshot files (used by online integ). If GTM_BAKTMPDIR does not exist, MUPIP places the snapshot files in the current directory at the time you issue the INTEG command.

      As it checks each database file, MUPIP INTEG -ONLINE creates a sparse file of the same size as the database.  As each GT.M process updates the database, it places a copy of the old block in the sparse file before updating the database.  For any database blocks with a newer transaction number than the start of the INTEG, MUPIP uses the copy in the sparse file.  Thus, analogous with MUPIP BACKUP -ONLINE, INTEG reports on the state of the database as of when it starts, not as of when it completes.  Note: a command such as ls -l command shows sparse files at their full size, but does not show actual disk usage. Use a command such as du -sh to see actual disk usage.

      Temporary directory security settings must allow write access by the the MUPIP process and read access by all processes updating the database. MUPIP creates the temporary file with the same access as the database file so processes updating the database can write to the temporary file. If the database is encrypted, the updating processes write encrypted blocks to the snapshot file and the MUPIP INTEG process must start with access to appropriate key information as it does even -NOONLINE.

      Only one online integ can be active per database region. If an online integ is already active, a subsequent one issues an error and immediately terminates. If an online integ does not successfully complete, GT.M cleans it up in one of the following ways:

    •  
      • A subsequent online integ detects that an earlier one did not successfully complete and releases the resources held by the prior online integ before proceeding.
      • If a MUPIP STOP was issued to the online integ process, the process cleans up any resources it held. Note: since the process was stopped the results of the integ may not be valid.
      • A subsequent MUPIP RUNDOWN ensures the release of resources held by prior unsuccessful online integs for the specified regions.
      • For every 64K transactions after the online integ initiation, online integ health GT.M checks for improperly abandoned online integs and releases resources held by any it finds.
       
      Because the online integ (now the default for most integs) does not freeze database updates, it cannot safely correct errors in the "blocks to upgrade" and "free blocks" fields in the file header, while MUPIP INTEG -NOONLINE can correct these fields.
        
      The -ONLINE qualifier is incompatible with the -TN_RESET qualifier. In any case, there should be no need to use -TN_RESET on a GT.M V5 database. [UNIX] (C9902-000839)

    • MUPIP INTEG -TN_RESET now resets block transaction numbers and backup event recorded transaction numbers to (one) 1, and the current transaction number to two (2) which makes the backup event recorded transaction numbers more meaningful and useful. It also issues an advisory message to perform a backup. Previously the backup event recorded transaction numbers were not maintained by -TN_RESET, which meant they held inappropriate information. Note that there should never be a need for a -TN_RESET on a datbase with only V5 blocks, even when cleaning up after a runaway process. (C9B12-001842)

    • GT.M now provides a new monitoring facility for processes holding a resource for an unexpected amount of time. This facility runs a shell command or a script pointed to by the new environment variable gtm_procstuckexe when any of the following conditions occur:  


      1. An explicit MUPIP FREEZE or an implicit freeze, such as BACKUP, INTEG -ONLINE, and so on, after a one minute wait on a region. 
      2. MUPIP actions find kill_in_prog (KILLs in progress) to be non-zero after a one minute wait on a region. Note that GT.M now internally maintains a list of PIDs (up to a maximum of 8 PIDs) currently doing a KILL operation.  
      3. The BUFOWNERSTUCK, INTERLOCK_FAIL, JNLPROCSTUCK, SHUTDOWN, WRITERSTUCK and MAXJNLQIOLOCKWAIT operator messages are being logged.


      Typically, for the shell script or command pointed to by gtm_procstuckexec, you would write corrective and preventive actions or obtain the stack trace of the troublesome processes (using their PIDs). GT.M passes arguments to the shell command / script in the order specified below:


      1. condition is the name of the condition. For example, BUFOWNERSTUCK, INTERLOCK_FAIL, and so on.
      2. waiting_pid is the PID of the process reporting the condition. 
      3. blocking_pid is the PID of the process holding a resource. 
      4. count is the number of times the script has been invoked for the current condition (1 for the first occurrence).


      Each invocation generates an operator log message and if the invocation fails an error message to the operator log. The shell script should start with a line beginning with #! that designates the shell. 


      Note: Make sure you have sufficient space and permissions to run the shell command / script.


      Prior versions wait for the condition to clear and in most cases send messages to the operator log. [UNIX] [C9D08-002390]

    • MUPIP now verifies that the byte ordering (endian-ness) of a journal file matches the byte ordering of the instance on which it is running and issues an error in case of a mismatch. In prior versions, such a case of operational cross-threading caused MUPIP to fail with various complaints about the journal file format or even a memory access violation (SIG-11 or ACCVIO). (C9J04-003110)

    • The replication source server now handles database files that are in WAS_ON replication state (and in turn a journaling state of OFF) in a safe manner. If it cannot find the journal records in the journal pool, it reads as many journal records as possible from the journal file chain and when it reaches the point where journaling got turned OFF, it periodically displays a REPL_WARN message until journaling gets turned back ON and then correctly issues a NOPREVLINK error. At all points, it behaves as a read-only process as far as journaling is concerned and never switches journal files. In previous versions of GT.M, it was possible for the source server to incorrectly attempt a switch of journal files in such WAS_ON regions eventually terminating with many types of errors (JNLFILOPN etc.). (C9J07-003156) V5.4-000A

    • The messages produced by a replicating instance when the originating instance encounters a REPLINSTNOHIST error now read:

      Originating instance encountered a REPLINSTNOHIST error. JNL_SEQNO of this replicating instance precedes the current history in the originating instance file. uuuu exiting.

      Where uuuu is either a rollback or the receiver server. [UNIX] (C9J08-003166)

    • By default, a Source Server now waits for a maximum of one and a half minute per region to shutdown. In prior versions, the maximum wait period for Source Server shutdown was approximately four minutes irrespective of the number of regions. (C9J09-003195).

    • MUPIP BACKUP -REPLINSTANCE now ensures its backup of the replication instance file is in sync with all databases backed up as part of the same command. This fixes a regression introduced in GT.M V5.3-000 (and present in V5.3-004A) that could in rare cases cause REPLINSTDBMATCH error when attempting to use the backed-up instance file because it held an incorrect sequence number for a database file. A workaround for this is to recreate the instance file, as the backed up databases are correct. (C9K01-003222)[UNIX]

    • GT.M now correctly handles an unusual set of circumstances that can occur if MUPIP BACKUP -ONLINE and MUPIP INTEG -ONLINE are running concurrently with M transaction processing. In V5.4-000, these unusual circumstances could cause a SIG-11. [UNIX] (C9K02-003239) V5.4-000A

     

    Return to Table of Contents

    Utilities-Other Than MUPIP

    • DSE, LKE, and MUPIP now handle unusually long command input lines more gracefully. In prior versions, long commands could damage adjacent memory and lead to difficult to diagnose failures. [UNIX] (C9J09-003199)

     

    Error Messages

    The new error messages introduced in V5.4-000 are as follows:

     

    GVDATAGETFAIL

    GVDATAGETFAIL, Global variable DATAGET sub-operation (in KILL function) failed. Failure code: cccc.

     

    Run Time Trigger Error: The target node for a KILL operation could not present its state to the trigger logic due to a database problem. cccc contains the failure codes for the failed attempts. The database may have integrity errors or the process-private data structures may be corrupted.

     

    Action: Report this database error to the group responsible for database integrity at your operation.  

    JNLENDIANBIG

    JNLENDIANBIG, Journal file jjjj is BIG endian on a LITTLE endian system

      
    MUPIP Error: The MUPIP command on a little endian system specified journal file jjjj which was created on a big endian system. GT.M does not convert journal files with incompatible byte ordering.
      
    Action: Set up operational procedures that ensure journal files are used on systems with the same byte ordering as where they are created. If necessary, extract journal file data on the source system and use an M program on the opposite endian system to restore it. 

    JNLENDIANLITTLE

    JNLENDIANLITTLE, Journal file jjjj is LITTLE endian on a BIG endian system

      
    MUPIP Error: The MUPIP command on a big endian system specified journal file jjjj which was created on a little endian system. GT.M does not convert journal files with incompatible byte ordering.
      
    Action: Set up operational procedures that ensure journal files are used on systems with the same byte ordering as where they are created. If necessary, extract journal file data on the source system and use an M program on the opposite endian system to restore it. 

    MAXSSREACHED

    MAXSSREACHED, Maximum snapshots - mmmm - for region rrrr reached. Please wait for the existing snapshots to complete before starting a new one.

      
    Mupip error: Starting this snapshot would exceed the maximum number of snapshots.
      
    Action: Wait for a currently active process using snapshots to complete or terminate an existing snapshot activity. 

    MAXTRIGRNEST

    MAXTRIGRNEST, Maximum trigger nesting level LLLL exceeded
     
    Run Time Trigger Error: GT.M limits trigger invocation depth to LLLL.
     
    Action: If you are sure that you do not have an application code bug or misfeature, reduce the depth of trigger invocation, possibly by consolidating triggers.  

    MUJNLDBMISSING 

    MUJNLDBMISSING, Journal files for required database dddd missing in the MUPIP JOURNAL command 
     
    MUPIP Error: MUPIP JOURNAL processing requires journal files for database dddd in order to perform the requested recovery, but the invoking command did not supply a path for those files.
     
    Action: Revise the command to include the appropriate journal specification(s) and reissue it.

    NOZTRAPINTRIG  

    NOZTRAPINTRIG, Use of $ZTRAP in a database trigger environment ($ZTLEVEL greater than 0) is not supported.

    Run Time Trigger Error: GT.M requires the use of $ETRAP for error handling within trigger logic.

    Action: Modify the application code to use $ETRAP to handle errors in trigger logic.

    PROCTERM

    PROCTERM, uuuu process termination due to cccc from eeee

    Utility Warning: A utility uuuu, typically MUPIP, executing application code, possibly from a trigger, encountered a command cccc to terminate at $zposition location pppp.

    Action: It is not typically wholesome for MUPIP to terminate this way - review your error handling and trigger definitions for a possible bug or misfeature.

    QUITALSINV

    QUITALSINV, QUIT * return when the extrinsic was not invoked with SET *

    Run Time Error: A [sub-]routine tried to pass an alias back to the caller, but the routine was not invoked to accept an alias return.

    Action: Rework either the invocation or the return, or troubleshoot why the inappropriate invocation occurred. If the routine should conditionally return an alias, use $QUIT to select the proper type of return. 

    REGSSFAIL

    REGSSFAIL, Process pppp encountered error contributing to the snapshot for region rrrr - the snapshot is no longer valid
      
    Mupip error: A GT.M process while trying to write a block to the snapshot failed due to some reason. The reason should be in the operator log.
      
    Action: Examine the operator log for details of the failure and take action, possibly modifying file access characteristics or user roles, to address the problem. 

    SETINTRIGONLY

    SETINTRIGONLY, ISV iiii cannot be modified outside of the trigger environment
      
    Run Time Trigger Error: The Intrinsic Special variable iiii can only be SET within the context of trigger logic ($ZTLEVEL > 0)
      
    Action: Examine the application logic to determine whether code intended for use in a trigger context falls in an execution path outside of trigger logic. For code intended to execute both inside and outside triggers, use a postcondition that limits the SET to within a trigger. 

    SNAPSHOTNOV4

    SNAPSHOTNOV4, Cannot downgrade (to V4) while snapshots are in progress. Currently ssss snapshots are in progress for region rrrr.
      
    Mupip error: A request to downgrade a region to V4 occurred while a snapshot is in progress.
      
    Action: Wait for a currently active process using snapshots to complete before running the downgrade.  Since a downgrade to V4 would not normally be expected, check to verify that the downgrade invocation is appropriate.

    SSFILCLNUPFAIL

    SSFILCLNUPFAIL, Error while unlinking snapshot file -- xxxx

    Mupip error: An attempt to terminate snapshot file maintenance by GT.M updater processes encountered a problem.

    Action: Try a MUPIP RUNDOWN. If that has a similar problem, it may be prudent to shut down all access to the database in question in order to stop the burden of maintaining the snapshot file and to ensure it doesn't unnecessarily consume more space. 

    SSFILOPERR

    SSFILOPERR, Error while doing oooo operation on file ffff
      
    Mupip error: The oooo operation on snapshot file ffff failed
      
    Action: Analyze the operation and the file characteristics and take appropriate action to clear the problem.  

    SSPREMATEOF

    SSPREMATEOF, Premature end of file while reading block nnnn of size: bbbb bytes at offset: oooo from zzzz
      
    Mupip error: The action attempted access to a block beyond the end of the snapshot file. This means either the process was confused or the file is damaged
      
    Action: Retry the action. If the problem persists, contact FIS with information on how to recreate the problem. 

    SSSHMCLNUPFAIL

    SSSHMCLNUPFAIL, Error while doing snapshot shared memory cleanup. Operation -- ssss. Identifier -- dddd
      
    Mupip error: There was an error while doing a snapshot cleanup. The operation ssss indicates what system call failed. The identifier dddd indicates the shared memory identifier that is being cleaned up.
      
    Action: Analyze the failure details and take corrective measures. If appropriate carefully clear abandoned resources using the system ipcrm utility. 

    SSTMPCREATE

    SSTMPCREATE, Cannot create the temporary file in directory dddd for the requested snapshot
      
    Mupip error: An action requiring a snapshot file was unable to create it.
      
    Action: Verify the directory has appropriate access permissions for the user performing the action. 

    SSTMPDIRSTAT

    SSTMPDIRSTAT, Cannot access temporary directory dddd
      
    Mupip error: An action requiring a snapshot file was unable to access the temporary directory.
      
    Action: Verify the directory exists and has appropriate access permissions for the user performing the action. 

    SSTMPFILOPEN

    SSTMPFILOPEN, Failed to open shadow snapshot file ffff
      
    Mupip error: An action requiring a snapshot file was unable to open it.
      
    Action: Verify the file exists and has appropriate access permissions for the user performing the action. 

    SSV4NOALLOW

    SSV4NOALLOW, Database snapshots are supported only on fully upgraded V5 databases. nnnn has V4 format blocks.
      
    Mupip error: An action requiring a snapshot was attempted on a database the contains V4 format blocks.
      
    Action: Upgrade the database to V5 and re-run the action. 

    TRIG2NOTRIG

    TRIG2NOTRIG, Sending transaction sequence number xxxx which used triggers to a replicator that does not support triggers
      
    MUPIP Warning: The source server encountered a transaction that includes triggers, but its replicating node does not support triggers. Unless you are using application level filters to handle this case, your originating instance and replicating instance are no longer consistent.
      
    Action: If this case it not handled by your application level filters, you should either enhance your filters or upgrade the replicating instance to a version of GT.M that supports triggers and load the the appropriate trigger definitions with MUPIP TRIGGER (or $ZTRIGGER()), and then take appropriate action (such as recreating the replicating instance from a backup of the originating instance) to restore consistency.  

    TRIGCOMPFAIL

    TRIGCOMPFAIL, Compilation of database trigger named tttt failed 
     
    Run Time Trigger Error: The -Xecute code of a trigger specification has syntax errors. Because triggers are precompiled when you define them, this error may indicate that either:

    • A database upgrade was performed but the trigger code was not updated to eliminate obsolete syntax
    • The portion of the database holding the trigger definitions may be corrupted

    Action: Validate the definitions by a SELECT option with MUPIP TRIGGER or $ZTRIGGER(), correct the trigger code syntax and apply a trigger update.  

    TRIGINVCHSET

    TRIGINVCHSET, Trigger tttt for global gggg was created with CHSET=cccc which is different from the current $ZCHSET of this process
      
    Run Time Trigger Error: Trigger tttt on global gggg failed because the process that attempted to update global gggg did not have the same character set that was used to load trigger tttt.  Databases with triggers can only be used by processes that are M mode or UTF-8 mode, depending on the mode of the process that loaded the triggers.

    Action: Ensure that processes start with the same character set (as defined by the gtm_chset environment variable) that was used to load the trigger definitions with MUPIP TRIGGER (or $ZTRIGGER() function).

    TRIGJNLSTATE

    TRIGJNLSTATE, Trigger cannot update journaled database file dddd since triggering update was not journaled

    Run Time Trigger Error: A process performed an update on a global in a database region which is not currently journaled, and that update invoked a trigger that, in turn, attempted an update on a global in a database region that is journaled. The secondary GVIS message provides the global name. This would produce a journal state with insufficient information to ensure proper replication of the region with the triggered update.

    Action: Revise global directories, journaling characteristics, or trigger logic to prevent this situation.  

    TRIGNAMEUNIQ

    TRIGNAMEUNIQ, Unable to make trigger name tttt unique beyond vvvv versions already loaded

    Run Time Trigger Error: GT.M encountered more than vvvv different instances of the same trigger name across database regions used by the same process.

    Action: Revise trigger names to prevent such a high degree of overlap.

    TRIGTCOMMIT

    TRIGTCOMMIT, TCOMMIT at $ZTLEVEL=LLLL not allowed as corresponding TSTART was done at lower $ZTLEVEL=BBBB

    Run Time Trigger Error: A TCOMMIT in trigger logic attempted to complete the active transaction that was started outside of the current trigger. Because trigger actions are atomic with the update initiating them, committing a transaction started prior to or by the triggering update cannot be committed inside the trigger.

    Action: Within the trigger context, review the TCOMMIT logic to ensure that it commits only those transactions that are started within the trigger. Ensure that TCOMMIT does not attempt to commit any transaction started prior to or by the triggering update.  

    TRIGTLVLCHNG

    TRIGTLVLCHNG, Detected a net transaction level ($TLEVEL) change during trigger tttt. Transaction level must be the same at exit as when the trigger started

    Run Time Trigger Error: While the trigger logic can use balanced sub-transactions, it cannot cause a net change in $TLEVEL.

    Action: Review the transaction management (TSTART, TCOMMIT and TROLLBACK) within trigger logic to ensure that it commits or rolls back any transactions it starts and does not attempt to commit any transaction started prior to, or by, the trigger update. You can use TROLLBACK within trigger logic to block the current transaction, possibly to write error context information. Nonetheless if you use such a TROLLBACK, GT.M subsequently signals this error when you leave the trigger context in order to notify the process that the original triggering update has been discarded.

    ZGOTOINVLVL

    ZGOTOINVLVL, ZGOTO in a trigger running in mmmm cannot ZGOTO level LLLL

    MUPIP Error: A ZGOTO command in trigger logic attempted to specify an inappropriate destination. Currently that is a ZGOTO in a trigger context with a target level of one (1) and an entryref. GT.M does not support such ZGOTO arguments in MUPIP because there is no context outside that of the trigger.

    Action: Revise the trigger logic to only use ZGOTO with an entryref within the trigger context of trigger logic. Note that you can ZGOTO out of a trigger, but doing so in MUPIP terminates the MUPIP process. FIS recommends limiting the use of ZGOTO to debugging, error handling and testing. Use of ZGOTO in production code, even for error processing, should always be thoroughly tested.

    ZTRIGINVACT

    ZTRIGINVACT, Missing or invalid subcode (first) parameter given to $ZTRIGGER()

    Run Time Trigger Error: The first argument to $ZTRIGGER() is required to specify its mode of action.

    Action: for the first argument of $ZTRIGGER() use an expression that evaluates to "FILE", "ITEM" or "SELECT".

    ZTRIGNOTP

    ZTRIGNOTP, $ZTRIGGER() cannot use update subcodes FILE or ITEM when a TP transaction is in progress ($TLEVEL greater than zero)

    Run Time Trigger Error: A FILE or ITEM operation of $ZTRIGGER() failed because it attempted to apply a trigger definition inside an ongoing transaction. Both FILE and ITEM operations of $ZTRIGGER initiate an implicit transaction to achieve trigger update atomicity, therefore, GT.M does not allow nesting them inside another transaction that potentially might use the very triggers $ZTRIGGER() is attempting to update.

    Action: Move all FILE or ITEM operations of $ZTRIGGER() outside the scope of any open transaction.

    ZTWORMHOLE2BIG

    ZTWORMHOLE2BIG, String length of LLLL bytes exceeds maximum length of mmmm bytes for $ZTWORMHOLE

    Run Time Trigger Error: GT.M limits $ZTWORMHOLE length to mmmm bytes and the application attempted to use LLLL bytes.

    Action: Restrict the size of the string stored in $ZTWORMHOLE to mmmm bytes. Ensure that $ZTWORMHOLE only holds the information that the application needs during trigger execution. If necessary, reorganize the logic to reduce the amount of local context needed during trigger execution, possibly by using global variables. 


    Return to Table of Contents

     
     

    GT.M Documentation Addendum

    This addendum includes an improved description of SOCKET READ operation and MOREREADTIME deviceparameter. 

    SOCKET READ operation

    TCP/IP is a stream-based protocol that guarantees that bytes arrive in the order in which they were sent. However, it does not guarantee that they will be grouped in the same packets.

    If packets arrive infrequently, or at varying rates that are sometimes slow, a short interval can waste CPU cycles checking for an unlikely event. On the other hand, if the handling of packets is time critical, a long interval can introduce an undesirable latency. If packets arrive in a rapid and constant flow (an unusual situation), the interval doesn't matter as much, as there is always something in the buffer for the READ to work with. If you do not specify MOREREADTIME, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive. If you specify an interval, the SOCKET device always uses the specified interval and doesn't adjust dynamically. For more information on MOREREADTIME, see "MOREREADTIME".

    Most SOCKET READ operations terminate as a result of the first condition detected from (a) receipt of delimiters, (b) receipt of the maximum number of characters, or (c) expiration of a timeout.  Note that all of these conditions are optional, and a specific READ may specify zero or more of them.  This document refers to these three conditions as "defined terminating conditions". If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates after it has received at least one character followed by an interval with no new characters. READ also terminates on the receipt of a character that puts the device at its specified WIDTH - you can vary the WIDTH, but it's not optional. An error can also terminate a READ. While none of the terminating conditions is satisfied, the READ continues.
     
    The following flowchart represents the logic of a SOCKET READ.   
     



    SOCKET READ Termination Conditions

     A SOCKET READ operation terminates if any of the following conditions are met:
     
    Terminating Conditions Argument Contains $Device $Key $Test
    Error Empty String Error String Empty String 1
    Timeout* Data received before timeout Empty String Empty String 0
    Delimiter* Data up to, but not including the delimiter Empty String Delimiter String 1
    Fixed Length Met*
    String of Fixed Length
    		 Empty String Empty String 1
    Width
    		 Full width String
    		 Empty String Empty String 1
    Buffer Emptied
    One (1) to as many characters as provided by the transport interface before waiting for an interval (in milliseconds) specified by MOREREADTIME with no additional input. If MOREREADTIME is not specified, buffer is checked every 200 milliseconds for its first input and then every 10 milliseconds until no new input arrives and no other terminating conditions are met.
    IF MOREREADTIME is specified, READ uses that value exclusively for buffer checks.
    		 Empty String Empty String 1
      
    * Defined Terminating Conditions  
     

    A non-fixed-length read, with no timeout and no delimiters (the sixth row in the above table) requires a complex implementation of sequence of READs to ensure a predictable result. This is because the transport layer stream fragments delivered to the reader has only accidental correspondence with the operations performed by the writer. For example, the following:

     

    Write "Message 1","Message 2" is presented to the reader as the stream "Message1Message2" but it can take from one (1) to 18 READ commands to retrieve the entire stream.


    Your messaging protocol should implement READ in any of the following ways: 
     
    1. Use a delimiter to separate messages (generic READ and possibly a larger value for MOREREADTIME). 
    1. Specify messages as <length, value> pairs (a pair of fixed-length READs (READ # ) and possibly a larger value for MOREREADTIME).
    2. Parse the bytes or characters as they come in (possibly a smaller value for MOREADTIME) 

    MOREREADTIME=intexpr

    MOREREADTIME specifies the polling interval (in milliseconds) that a SOCKET device uses to check for arriving packets.

    If you do not specify MOREREADTIME, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive. If you specify an interval, the SOCKET device always uses the specified interval and doesn't adjust dynamically. This applies to any SOCKET READ. For more information on implementing SOCKET READ in your application, see "SOCKET READ Operations".

    If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates either after it has at least one character followed by an interval with no new packets, or by reaching the specified maximum WIDTH for the SOCKET.

    If you use the MOREREADTIME behavior, bear in mind that:
     
    • Usually, it is more efficient and responsive for an application to wait and process input in larger chunks. Therefore, a larger value for MOREREADTIME can bring larger chunks of input to the application. However, large values may make for sluggish response.
    • A short value for MOREREADTIME may consume considerable CPU cycles, especially on a lightly loaded system.
    • The maximum value of MORETREADTIME is 999 (basically 1 second). Never set MOREREADTIME to 0 as it causes excessive CPU "spinning".
     

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



    + Technical Bulletin - GT.M V5.4-000/V5.4-000A Release Notes

    Technical Bulletin - GT.M V5.4-000A Release Notes

    Copyright A(C) 2010 Fidelity Information Services, Inc.  All Rights Reserved. 
     

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

     

    GT.Ma?c is a trademark of Fidelity Information Services, Inc.  Other trademarks are the property of their respective owners.  

     

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

    Revision History

    Version Date Summary
    1.6 June 15, 2011 Added more information on S9I08-002695.
    1.5 July 14, 2010 Improved the description of C9K01-003225.
    1.4 April 5, 2010 Added more information about using GT.M on IBM pSeries AIX.
    1.3 March 25, 2010 Added an entry for S9K03-002761.
    1.2 March 19, 2010
    1.1 February 19, 2010
    1.0 February 2, 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

     

    Table of Contents

    Click here to go directly to the Changes section.
     
     

    Conventions

    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 "/".


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


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


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


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


    Return to Table of Contents

    Bulletin Overview

    GT.M V5.4-000A provides timely remediation of a small number of issues with V5.4-000 (highlighted as V5.4-000A).

     

    In V5.4-000A, there is no change in the adaptive (auto-tuning) behavior of the MOREREADTIME deviceparameter introduced in V5.4-000.  However, in this bulletin, we have added an improved description of the "MOREREADTIME" deviceparameter. For more information, see "GT.M Documentation Addendum".  

      

    GT.M V5.4-000 adds a major new feature to GT.M, as well as a significant enhancement to operational capability for 24x365 database operation.


    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity.  Refer to the GT.M Triggers Technical Bulletin for details.


      Please note: FIS considers the implementation of triggers in V5.4-000/V5.4-000A to be robust, and entirely appropriate for development and testing short of production deployment.  With the next release of GT.M, they will have had gone through many more cycles of automated regression testing under a broader range of conditions, and will be considered production grade at that time.  If you are an FIS customer and are ready to deploy in production an application that uses GT.M triggers, please contact your FIS account manager about the timing and availability of a GT.M release in which triggers will be considered production grade.  Depending on circumstances, we may even decide then that the implementation of triggers in V5.4-000/V5.4-000AA is robust enough for production.  Except for the triggers functionality, everything else in V5.4-000/V5.4-000A is considered production grade.


    • MUPIP INTEG can now check a database for structural integrity while applications continue to operate.  In prior releases of GT.M, MUPIP INTEG would freeze updates.  Online operation is now the default for databases that contain no version 4 format database blocks.

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


    Please note: The deprecated "Z" pseudo-transactions (bracketed by ZTSTART / ZTCOMMIT) are not supported in this release.  FIS strongly urges you to remove their use from your code - since they have been deprecated for many years, they are no longer tested and may be removed from GT.M at any time.

     

     

    Return to Table of Contents

    Platforms

    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:

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


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


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

     

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


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

    Hewlett-Packard Alpha/AXP Tru64 UNIX

    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.


    • While GT.M supports both UTF-8 mode and M mode on this platform, there are problems with the AIX ICU utilities that prevent FIS from testing 4-byte UTF-8 characters as comprehensively on this platform as we do on others.
    IBM System z z/OS V1R10 At this time, FIS is not providing a 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 Programmera??s Guide for appropriate alternative solutions.

    x86_64 GNU/Linux

    Red Hat Enterprise Linux 5.4; Ubuntu 8.04 LTS through 9.10

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

     

    Return to Table of Contents

    Migrating to 64-bit platforms

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

     

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

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

    Call-ins and External Calls

    Parameter type

    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

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

    Internationalization (Collation)

    Parameter type

    32-Bit

    64-bit

    Remarks

    gtm_descriptor in gtm_descript.h

    4-byte

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

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

    Environment Translation 

    Parameter type

    32-Bit

    64-bit

    Remarks

    gtm_string_t type in gtmxc_types.h

    4-byte

    8-byte

    Although it is only the address within these types that changes, the structures may grow by up to 8 bytes as a result of compiler padding to meet platform alignment requirements.

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

     

    Return to Table of Contents

    Recompile

    • Recompile all M and C source files.


     

    Return to Table of Contents

    Rebuild Shared Libraries or Images

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


     

    Return to Table of Contents

    Additional Installation Instructions 

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

    UNIX

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

    2. Use the MUPIP RUNDOWN command of the old GT.M version to ensure all database files are cleanly closed.

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


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

    GT.M for IBM pSeries AIX requires the Asynchronous IO facility to be available and configured. 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 a system that has the "posixaio" option instead of "aio" (also called "legacy aio"), use SMIT as follows:


    • smit posixaio (for gui mode) or

    • smitty posixaio (for text mode)

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

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


    Since GT.M is not a thread safe application, starting multiple threads in a process, or sometimes even loading libpthreads can cause process failure with symptoms such as SIG-11. On AIX, sometimes seemingly innocuous actions can pull libpthreads into a process and cause it to fail. Two known cases are (a) use of non-POSIX (Olson) names such as America/Chicago for the TZ environment variable - please use POSIX names such as CST6CDT instead - and (b) using LDAP to authenticate userids. Other cases probably exist.


    If you expect a database file or journal 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.

    OpenVMS

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


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

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


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


    Return to Table of Contents

    Upgrading to GT.M V5.4-000A

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


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

     

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

    Stage 1: Upgrading your Global Directory

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

    To upgrade from any prior GT.M version:

     

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

     

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

     

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

     

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

    Stage 2: Upgrading your Database Files  

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

     

     

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

     

     

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

     

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

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

     

     
    No database file upgrade procedure is necessary if you upgrade from GT.M V5.0-000 or later to V5.3-000 or later. However, you may need to run the MUPIP REORG a??UPGRADE command to upgrade any previously used but free block that may have been missed during earlier upgrade cycles.  You do not need to run MUPIP REORG a??UPGRADE in either of the following situations:
     
    • A database was created by a V5 MUPIP CREATE
    • A database has previously been completely processed by a MUPIP REORG a??UPGRADE from V5.3-003 or later
     
    If you have already run the MUPIP REORG a??UPGRADE command in a version prior to V5.3-003, subsequent versions cannot determine whether or not it was done correctly and record warnings in the operator log for running MUPIP REORG -UPGRADE. Therefore, you must either:
     
    • Run the MUPIP REORG a??UPGRADE command again
    • Run the DSE CHANGE a??FULLY_UPGRADED=1 command to stop the warnings
       
      Caution: Do not run the DSE CHANGE -FILEHEADER a??FULLY_UPGRADED=1 command unless you are absolutely certain you have previously successfully run to completion MUPIP REORG a??UPGRADE from V5.3-003 or later. Using this command when inappropriately may lead to database integrity issues.

     

    For additional upgrade considerations, see "Database Compatibility Notes".  
     
    Database Compatibility Notes
    • Changes to the database file header may occur in any release.  GT.M automatically upgrades database file headers as needed.  Any changes to database file headers are upward and downward compatible within a major database release number, that is, although processes from only one GT.M release can access a database file at any given time, processes running different GT.M releases with the same major release number can access a database file at different times.
    • Databases created with V5.3-004 and later can grow to a maximum size of 224M (234,881,024) blocks.  This means, for example, that with an 8KB block size, the maximum database file size is 1,792GB (this is the size of a single global variable; a database consists of any number of global variables).  A database created with GT.M versions V5.0-000 through V5.3-003 can be upgraded with MUPIP UPGRADE to increase the limit on database file size from 128M to 224M blocks.
    • Databases created with V5.0-000 through V5.3-003 have a maximum size of 128M (134,217,728) blocks.  Until and unless a database created with V5.3-004 (or later), or created in V5.0-000 through V5.3-003, exceeds the 128M block limit of earlier V5 GT.M releases, it can be accessed by releases V5.0-000 through V5.3-003. 

    Stage 3: Upgrading your Replication Instance File

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

     

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


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


    • On AIX systems, if you upgrade from 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later
    • On Linux systems, if you upgrade from a 32-bit pre-V5.3-001 to 64-bit V5.3-001 or later or from a 64-bit release to a newer 32-bit release
    • On Sun SPARC Solaris, if you upgrade from 32-bit pre-V5.3-003 to 64-bit V5.3-003

     

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

     

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

     

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

    Stage 4: Upgrading your Journal Files

    To upgrade from any prior GT.M version: 

     
    • Create a fresh backup of your database.
    • Generate new journal files (without back-links).

     

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

    Return to Table of Contents

    Managing M mode and UTF-8 mode

    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 selected platforms.  On a system that does not have ICU 3.6 or later installed, or on other platforms, 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-000A_i686, then gtmprofile and gtmcshrc set $gtm_dist to /usr/lib/fis-gtm/gtm_V5.4-000A_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. 

           

    Compiling ICU on HP PA-RISC HP-UX

    Note: All GT.M versions prior to V5.3-004 require exactly ICU 3.6, however, V5.3-004 (or later) accept ICU 3.6 or later.
     
    As of this writing (November, 2009), ICU version 3.6 can be compiled on HP PA-RISC HP-UX with the following configuration:
     

     

    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:

     

    1. Ensure that system environment variable $PATH includes the location of all the compilers mentioned above.

    2. Download the source code of ICU (in this example, version 3.6 for C from http://icu.sourceforge.net/download/3.6.html#ICU4C)

    3. At the shell prompt, execute the following commands:

       
       
      gunzip -d < icu4c-3_6-src.tgz | tar -xf -
      cd icu/source/
      chmod +x runConfigureICU configure install-sh
      runConfigureICU --enable-debug HP-UX/ACC --enable-64bit-libs? --enable-rpath a??disable-threads
       
      gmake
       
      gmake check
       
      gmake install
       

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

    5. ICU is now installed in /usr/local.

     

    • By default, ICU is installed in /usr/local.  If you install ICU in a different directory, type:

      • runConfigureICU HP-UX/ACC --prefix=<install_path> --enable-64bit-libs? --enable-rpath a??disable-threads

      • Then execute the gmake commands, and set the environment variable $LD_LIBRARY_PATH to point to the appropriate location.

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

    Compiling ICU on HP Integrity IA64 HP-UX

    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:
     
    1. Ensure that system environment variable PATH includes the location of all the compilers mentioned above.
    2. Download the source code of ICU (in this example version 3.6 for C from http://icu.sourceforge.net/download/3.6.html#ICU4C).
    3. At the shell prompt, run the following commands:

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

    • Then run the gmake commands, and set the environment variable $LD_LIBRARY_PATH to point to the appropriate location.
      

    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.

     

    Return to Table of Contents

    Setting the environment variable TERM

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

     

     
    • Some terminfo entries may seem to work properly but fail to recognize function key sequences or position the cursor properly in response to escape sequences from GT.M.  GT.M itself does not have any knowledge of specific terminal control characteristics.  Therefore, it is important to specify the right terminfo entry to let GT.M communicate correctly with the terminal.  You may need to add new terminfo entries depending on their specific platform and implementation.  The terminal (emulator) vendor may also be able to help.
    • GT.M uses the following terminfo capabilities.  The full variable name is followed by the capname in parenthesis:
      auto_right_margin(am), clr_eos(ed), clr_eol(el), columns(cols), cursor_address(cup), cursor_down(cud1), cursor_left(cub1), cursor_right(cuf1), cursor_up(cuu1), eat_newline_glitch(xenl), key_backspace(kbs), key_dc(kdch1), key_down(kcud1), key_left(kcub1), key_right(kcuf1), key_up(kcuu1), key_insert(kich1), keypad_local(rmkx), keypad_xmit(smkx), lines(lines).

     

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

     

    Return to Table of Contents

    Installing Compression Libraries

    If you plan to use the optional compression facility for replication, you must provide the compression library.  The GT.M interface for compression libraries accepts the zlib compression libraries without any need for adaptation.  These libraries are included in many UNIX distributions and are downloadable from the zlib home page.  If you prefer to use other compression libraries, you need to configure or adapt them to provide the same API provided by zlib.  Simple instructions for compiling zlib on a number of platforms follow.  Although GT.M uses zlib, zlib is not FIS software and FIS does not support zlib.  These instructions are merely provided as a convenience to you.


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


    Solaris/cc compiler from Sun Studio:

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

    HP-UX(IA64)/HP C compiler:

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

    AIX/XL compiler:

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

    Linux/gcc:

    ./configure --shared
    make CFLAGS="-m64"
     
    z/OS:
     

    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.


    Change History 

    V5.4-000A

    Fixes and enhancements specific to V5.4-000A are: 

     

    S9K03-002761 Using buffered reads for accessing the source code required for $TEXT(), ZPRINT, and error reporting.
    S9D10-002376 Checking for defined variables and empty strings in local variable subscripts now conforms to the M standard.
    S9K02-002754 Prevent GDE from losing maximum length NAME entries.
    S9K02-002755 $QUIT on x86 and x86-64 GNU/Linux returns a uniformly appropriate result.
    S9K02-002756 Prevents a process from hanging (or failing) on a compilation error in a line longer than 1023 characters.
    S9K02-002757 Better clean up orphaned snapshot files from an INTEG that terminates abnormally.
    S9K03-002759 VIEW "NOLVLULLSUBS", "NOUNDEF" combination correctly issues an error for a SET using an undefined local variable as a subscript.
    C9K02-002758 During installation correctly set setuid bit for the gtmsecshr wrapper and appropriate permission settings for GDE help in utf-8 mode.
    C9H10-002920 Prevent error for blanks lines in a GDE command file and correctly resume an interrupted (<CTRL-C>) command file.
    C9J07-003156 Replication source server improvements for database files in WAS_ON replication state.
    C9K02-003239 Prevent a rare SIG-11 that occurs when MUPIP BACKUP -ONLINE and MUPIP INTEG -ONLINE run concurrently with M transaction processing.

     

    V5.4-000

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


    S9C11-002251 Error in place of GTMASSERT for full LOCK_SPACE
    S9D08-002354 Error from $GET() when 2nd argument is undefined local variable
    S9I08-002695 New Trigger facility
    S9I09-002699 No more inappropriate error from VIEW "FLUSH" or "JNLWAIT"
    S9J07-002732 Adaptive MOREREADTIME for SOCKET device
    S9J07-002737 More user-friendly UNIX distribution kit
    S9J11-002749 Cleanup of OPEN for [UNIX] PIPE device
    C9902-000839 ONLINE option now usual default for [UNIX] MUPIP INTEG
    C9B12-001842 MUPIP INTEG TN_RESET leaves proper state for BACKUP BYTESTREAM
    C9D07-002356 SOCKET CONNECT improvements
    C9D08-002390 Facility to trigger UNIX diagnostics on processes holding scarce resources
    C9E02-002513 TRUNCATE for sequential files corrected for Linux
    C9F07-002746 $INCREMENT() now starts with a numeric value when adding a string to an undefined global variable
    C9H06-002868 SOCKET device waiting to CONNECT now responds to MUPIP INTRPT
    C9H07-002875 UNIX call-in protects against multiple gtm_init or gtm_exit calls
    C9H10-002913 UTF-8 terminal input protected from loss on INTRPT
    C9J04-003108 $ECODE and $STATUS() protected from change by INTRPT
    C9J04-003110 MUPIP checks journal files for correct ENDIAN
    C9J04-003118 Performance improvement for sequential file READ in UTF-8 mode
    C9J06-003140 UNIX installation makes files executable only if successful
    C9J06-003145 UNIX gtmsecshr protects itself against over-length input in addition to existing wrapper protection
    C9J07-003148 ZWRITE of undefined alias variables
    C9J08-003166 Improve REPLINSTNOHIST error message
    C9J08-003170 Permit z/OS object modules to exceed 32 KB
    C9J08-003174 Improve handling of the loading of ICU used by UTF-8 mode
    C9J08-003178 Improve error message for UNIX IPC issue after an improper shutdown
    C9J08-003179 New ^%XCMD utility to XECUTE shell command line input
    C9J09-003188 Improve CLOSE for [UNIX] PIPE device
    C9J09-003190 Cleanup gtmcrypt_close memory management in the encryption plug-in interface
    C9J09-003195 Improve timing on passive replication server shutdown
    C9J09-003197 Easy of use improvements for managing basic GT.M environments
    C9J09-003198 UNIX deals with invalid group or owner for files
    C9J09-003199 Improvements to UNIX shell interface to protect against over-length input in utility commands
    C9J09-003201 UNIX installation deals with missing "bin" user or group
    C9J10-003202 Prevent rare cases of DBINVGBL errors
    C9J10-003203 Properly maintain $REFERENCE after reverse name-level $ORDER() of a global
    C9J10-003208 DSE protects against failure when encountering certain bad data
    C9J11-003211 Exclusive KILL behavior within an extrinsic function now controlled by an environment variable
    C9J11-003214 Prevent rare cases of an inappropriate TPFAIL GGGG error
    C9J12-003215 Improve performance for very large numbers of local variables
    C9J12-003217 New QUIT * and SET *$$ to return an alias from an extrinsic function
    C9K01-003220 Prevent rare cases of DBKEYORD or DBBADNSUB
    C9K01-003222 MUPIP BACKUP ensures instance file synchronized with database
    C9K01-003225 Maximum UNIX $STORAGE value of 2GB -1


    Return to Table of Contents

    M-Database Access

    • GT.M triggers are code fragments stored in databases files.  When a process updates a global variable, any triggers in that database file whose signatures match the update are automatically executed along with the update.  The signature of a trigger consists of the command (e.g., Set, Kill), the global variable, and a subscript pattern, as well as, for Set, optionally a piece separator and pieces of interest.  Triggers have many uses, only one of which is to maintain the consistency of application schema by automatically computing cross-reference indexes and maintaining referential integrity. Refer to the GT.M Triggers Technical Bulletin for details.


      A MUPIP RECOVER which stops due to an error before making any database modifications also leaves the file header unchanged. Previously, MUPIP RECOVER marked the database header with the "corrupt" flag and did not clear it for that case. (S9I08-002695)

    • GT.M no longer issues JNLCNTRL errors when VIEW "JNLWAIT" commands are executed after a journal file switch. Previously, in rare cases, GT.M incorrectly issued a JNLCNTRL error. (S9I09-002699)

    • GDE now preserves the mapping of multiple lexically adjacent maximum length global names. In prior versions, GDE created such ranges correctly but lost track of them when reloading the global directory for examination or a subsequent update. The workaround was to always reestablish such ranges after invoking GDE. This issue was reported from a pre-V5 environment where the maximum name length was eight characters rather than the current 31 characters. There is less chance of encountering this issue on versions V5.0-000 and later. (S9K02-002754) V5.4-000A

    • GT.M now ensures $INCREMENT() produces a numeric result even when the first argument is an undefined global variable and the second argument is a string containing non-numeric characters. Prior versions returned a string in this condition. If the first argument was a local variable, this worked properly in earlier versions. Note while the case in question is unusual enough to be unlikely, any code that relied on the prior behavior needs updating. (C9F07-002746)

    • GDE now ignores blank lines in command files. After being interrupted while processing a command file, it also properly closes the file and appropriately resumes the next action. In prior versions, GDE treated blank lines as errors and could fail with a GDECHECK error if a command file was interrupted at certain points with <CTRL-C>. (C9H10-002920) V5.4-000A

    • A GT.M process now reports a more helpful ERR_REQRUNDOWN error when it fails to attach to a shared memory segment (because of a prior improper shutdown e.g. kill -9). On detecting such a situation, prior versions instead reported the less helpful ERR_DBFILERR. [UNIX] (C9J08-003178)

    • As long as the operating system permits the access, GT.M now allows access to database files and journals in cases where the system has no user or group information available for the file. Such an unusual situation can arise, for example, when the user and group are provided via NIS, but if NIS is not currently operational the owner and group cannot be determined; or perhaps a user id is deleted while the GT.M process is active. V5.3-004[A] issued a signal-11 in such a case. [UNIX] (C9J09-003198)

    • GT.M now properly releases memory in response to a gtmcrypt_close() function call. Previously, depending upon how quickly memory was re-allocated, a gtmcrypt_close() function call could result in a signal 11 causing GT.M to abnormally terminate. [Unix] (C9J09-003190)

    • GT.M now maintains database integrity even when multiple GT.M processes simultaneously attempt to create the same global variable. This fixes a regression in GT.M V5.3-000 (also present in V5.3-004A and introduced as part of the fixes to C9H09-002901) where, in such situations, it was possible under rare circumstances for the GT.M process to cause database damage (for example, DBINVGBL or DBKEYORD errors). Note that this was an issue only for non-TP updates, that is those which were not surrounded by a TSTART/TCOMMIT. (C9J10-003202)

    • Using "" as the last subscript in a global argument to $ORDER(gvn,-1) or $ZPREVIOUS(gvn) now maintains $REFERENCE correctly. This fixes a regression introduced in GT.M version V5.3-004 (and present in V5.3-004A) as part of the fix for C9E10-002648. (C9J10-003203)

    • GT.M now deals correctly with a set of rare cases where it could inappropriately interpret negative numbers in database block control structures as large positive numbers. Previous versions might terminate with memory access violations, or get into indefinite or inappropriately long loops. This was discovered in testing DSE against a database with intentionally inflicted damage, which we expect is characteristic of the unusual conditions that might expose this issue. (C9J10-003208)

    • GT.M now correctly implements an optimization (that avoids unnecessary global variable tree traversals) for TP transactions. This fixes a regression introduced in GT.M V5.3-004 (and present in V5.3-004A) which in rare cases could cause an incorrect TPFAIL error to be issued (note: this regression did not affect the integrity of the database). (C9J11-003214)
    • GT.M now correctly handles a case where a TP transaction updates the same block, holding the same global multiple times, along with updates of blocks of other globals, and some other process, most likely MUPIP REORG, replaces the block in question with an almost identically configured block from another global in the transaction between the first and second updates of the original block. In previous versions, it was possible for this unusual combination of conditions to cause an incorrect update. The likelihood of this issue increased due to a recent change (C9905-001119) in GT.M V5.3-004 which enabled a global reference caching optimization for TP. (C9K01-003220)


    Return to Table of Contents

    M-Other Than Database Access

    • GT.M now issues a LOCKSPACEFULL error to the application and the operator log when the environment attempts more concurrent M LOCKs than the configured LOCK_SPACE for the region can support. Previously under these conditions, GT.M gave a fatal GTMASSERT error. (S9C11-002251)

    • GT.M now reports an error if the first argument of a two argument $GET() is defined and the second is an undefined local variable. Prior versions returned the value of the first argument and ignored the error mandated by the standard. If the second argument was a global variable, this worked properly in earlier versions. Note that any code that relies on the prior behavior needs updating. (S9D08-002354)

    • GT.M now reports UNDEF errors when it encounters an undefined variable specified for a local variable subscript as it already does for a global variable and as defined in the language standard. In prior versions, KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY() ignored these errors. Under NOUNDEF operation this change has no user impact. Note: code that relied on the earlier non-standard behavior may now give errors and require revision.

      GT.M now supports VIEW "NEVERLVNULLSUBS" to issue the LVNULLSUBS error for any inappropriate use of empty string subscripts in local arrays.  The [new] gtm_lvnullsubs UNIX environment variable can have the values 0 - equivalent to VIEW "NOLVNULLSUBS", 1  (the default) - equivalent to VIEW "LVNULLSUBS" or  2 - equivalent to VIEW "NEVERLVNULLSUBS". In VMS, the initial state of this characteristic is controlled by the GTM$DEFAULTS file. An empty string as the last subscript in $ORDER() and $QUERY() has the semantic significance of requesting the next lexical item and is not subject to NULLSUBS errors. $VIEW("LVNULLSUBS") returns the corresponding numeric value. In prior versions, GT.M only supported NOLVNULLSUBS, which reported the LVNULLSUBS error for SET commands that would have instantiated a prohibited local array subscript, but not for KILL and its variants or functions including $DATA(), $GET(), $ORDER() and $QUERY().  $VIEW("LVNULLSUBS") returned 0 for NOLVNULLSUBS and 1 for LVNULLSUBS. Note that code that expected $VIEW("LVNULLSUBS") to provide a truth value must be revised. Empty string subscript checking for global variables is controlled by a database region characteristic that was already comprehensive and is not affected by this change. Note that programs using empty subscripts for references where those references cannot possibly exist are wasting computer resources, so FIS recommends using LVNULLSUBS or NEVERLVNULLSUBS for local variables and NULLSUBS options ALWAYS or NEVER for global variables. (S9D10-002376) V5.4-000A

    • If the OPEN or USE for a SOCKET device does not specify a MOREREADTIME parameter, any READ uses an initial 200msec internal timeout to minimize CPU load. Subsequent attempts to acquire more characters to fulfill the same READ use a 10msec internal timeout. When a MOREREADTIME parameter specifies a value, READ uses that value exclusively. Previously READ used a default of 10msec when no MOREREADTIME parameter was specified and consequently could consume considerable CPU cycles, especially on a lightly loaded system. If your application currently uses the MOREREADTIME parameter, FIS suggest that you consider whether this new behavior provides better performance and/or reduces CPU usage and allows you to avoid specifying MOREREADTIME. (S9J07-002732)

    • The distribution tar file now provides all files owned by the innocuous user:group ids 40535:40535, with no executable or writable files. With the exception of AIX, no directories have write permissions. On AIX, unpacking the distribution file no longer requires root permissions. In prior versions, the configure script adjusted the authorizations, but the distribution had various settings, and, on AIX, required root access to unpack the distribution. [UNIX] (S9J07-002737)

    • GT.M now handles the OPEN of a PIPE device better in certain situations. In prior versions, specifying various device parameters such as ESCAPE for the $PRINCIPAL device when it was a terminal could result in delays or other problems. [UNIX] (S9J11-002749)

    • GT.M now ensures a proper value for $QUIT on x86 and x86-64 GNU/Linux. In V5.4-000 under certain circumstances, it could return an inappropriate result. [x86-64 Linux, x86 Linux] (S9K02-002755) V5.4-000A

    • On compiling an M program, GT.M now omits reports showing the point in the line of code that caused the warning or error for lines longer than 1023 characters; it still reports the line number and column number. In prior versions, attempts to report such long lines could overrun an internal buffer and cause the process to hang or fail. (S9K02-002756) V5.4-000A

    • GT.M now correctly detects an attempt to SET a variable with an "NULL" subscript resulting from an undefined variable when using a VIEW "NOLVNULLSUBS", "NOUNDEF" combination. In versions starting with V5.3-001, the changes associated with C9B03-001664 exposed a latent problem such that GT.M did not detect a SET using an undefined local variable as a subscript as an error, but instead could use an indeterminate value for the subscript. (S9K03-002759) V5.4-000A
    • GT.M now uses buffered reads for accessing the source code required for $TEXT(), ZPRINT, and error reporting. While the performance difference of the buffered read approach is significant, most applications limit their use of the affected features so the overall effect may not be noticeable. Previously, GT.M used unbuffered reads which used many system calls. [UNIX] (S9K03-002761) V5.4-000A

    • The TRUNCATE parameter on USE for sequential file devices now works correctly for Linux. In prior versions, USE could truncate at the wrong position. [Linux] (C9E02-002513)

    • The GT.M SOCKET device behavior has improved in a number of ways.

      SOCKET CONNECT operations now respond to MUPIP INTRPT; in prior versions they did not.

      If the command does not specify a timeout, a SOCKET OPEN now waits for the connection to complete or an interrupting event that terminates the attempt. After an interrupt that does not terminate the connection attempt, such as the default value of $ZINTERRUPT ("IF $ZJOBEXAM()"), the process resumes the wait when the XECUTE of the $ZINTERRUPT completes. Previously, an untimed SOCKET OPEN <device>:CONNECT would make a single attempt to connect and return whether or not it was successful, as if it had a timeout of 0.

      SOCKET CONNECT status values EINPROGRESS, EWOULDBLOCK and, on some platforms, EALREADY now wait for the connection to complete or for the specified timeout to expire.  Previously, GT.M treated these conditions as errors.

      If IOERROR="TRAP" is specified on a SOCKET OPEN or USE, it now invokes any active EXCEPTION, $ETRAP, or $ZTRAP if an error occurs on a CONNECT.  The above status values as well as ECONNREFUSED and ETIMEDOUT are not considered as errors.  Previously, status values other than ECONNREFUSED or ETIMEDOUT would always be treated as errors regardless of the IOERROR value. (C9D07-002356, C9H06-002868)

    • GT.M now allows only a single set of gtm_init/gtm_exit per process and any attempt to call gtm_init/gtm_ci after a gtm_exit returns the code associated with the CALLINAFTERXIT error. Earlier GT.M versions also did not support invoking gtm_init or gtm_ci after a gtm_exit but did not enforce the restriction.[UNIX] (C9H07-002875)

    • GT.M now preserves all terminal input when handling an INTRPT in UTF-8 mode. In addition, INTRPT handling now preserves and restores the INSERT terminal characteristic. In prior versions, there was a slight chance a few characters of UTF-8 mode terminal input for either a READ or Direct Mode input could be lost and/or that the INSERT setting would revert to the default after the INTRPT event. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9H10-002913)
    • GT.M handling of INTRPT processing now protects the values of $ECODE and $STACK() at the time it recognizes the INTRPT. Prior versions allowed the code invoked by the $ZINTERUPT vector to modify those values, probably unintentionally, which could lead to a confused error processing state after completion of the $ZINTERUPT action. (C9J04-003108)

    • READ from a sequential disk file in UTF-8 mode read buffers the file reads for higher throughput. In prior versions, single character reads limited performance. [UNIX] (C9J04-003118)

    • The UNIX installation script for GT.M now sets the executable bits for files such as mumps and mupip only after a successful installation. Previously, the executable bits for these files were sometimes set after an unsuccessful installation. [UNIX] (C9J06-003140)

    • Both gtmsecshr and GT.M now prevent buffer overflow by checking the length of the gtm_tmp environment variable based on the system-specific sun_path length. In recent and properly patched versions of GT.M this was done only in gtmsecshr_wrapper. [UNIX] (C9J06-003145)

    • ZSHOW and ZWRITE now display information about alias variables with no associated data provided at least two of the joined variables are selected by the command argument. In prior releases these commands displayed alias containers with no data, but not alias variables with no data. When an alias exists with no data for the command to display, GT.M holds the variable so that it can become the right-hand side of a proper SET * command. However, if the command selection criteria excludes any other alias, GT.M has insufficient information to form a valid SET * argument and does not display that alias. Alias container variables always have a default value (the empty string), so they are handled differently and display as they did before. (C9J07-003148)

    • GT.M now handles very large object files correctly on z/OS. V5.3-003[A] produced invalid object files if the generated code exceeded 32KB. [z/OS] (C9J08-003170)

    • In UTF8 mode, when the minor version is not specified in the environment variable gtm_icu_version, e.g. 3 instead of 3.6, GT.M issues an ICUSYMNOTFOUND error. Previous versions of GT.M used to issue the ICUVERLT36 error even when the major version specified was greater than or equal to 4. [AIX, GNU/Linux, HP-UX, Solaris, z/OS] (C9J08-003174)

    • ^%XCMD is a utility program that XECUTEs input from the shell command line and returns any error status (truncated to a single byte on UNIX) generated by that code. For example in UNIX: mumps -run %XCMD 'write "hello world",!' would produce "hello world" (C9J08-003179)

    • GT.M now correctly handles the CLOSE of a PIPE device whose STDERR device is the current device.  Prior versions issued a segmentation violation in such a case. [UNIX] (C9J09-003188)

    • The file gtmprofile, which sets up a default environment for GT.M has been completely revamped to make it more robust and to make the out-of-box GT.M experience friendlier.  gtmprofile now sets up default values for more environment variables, creates a default global directory if one does not exist and a default database with before image journaling, if one does not exist.  The new executable shell script gtm uses gtmprofile and automatically recovers the database on startup.  gtm also deletes prior generation journal and temporary files older than the number of days specified by the environment variable gtm_retention.  A new file gdedefaults specifies default values for global directories.  The new gtmprofile script is also idempotent (can be successfully rerun after an abnormal termination), unlike its predecessor.  FIS recommends that system administrators review the gtmprofile and gdedefaults files after installing GT.M, and customize them as needed.  The previous gtmprofile file remains available as gtmprofile_preV54000 - if you want to retain the previous behavior, simply replace gtmprofile with gtmprofile_preV54000.  Note that at this time, the file gtmcshrc has not been similarly revamped for csh/tcsh users (the gtm script does not depend on the underlying shell).  [UNIX] (C9J09-003197)  

    • The distribution tar file may now be installed if there is no "bin" user and/or group defined.  The operator may now enter an alternate user and/or group to own the installation and may also restrict access to this group.  Previously the installation failed if the default bin user were specified and did not exist, or if the bin group did not exist - even if another restricted group was chosen. [UNIX] (C9J09-003201)

    • The new $gtm_stdxkill/GTM_STDXKILL environment/logical variable (UNIX/VMS) which if set to "TRUE", 1, or "YES" enables the standard-compliant behavior to kill local variables in the exclusion list if they had an alias that was not in the exclusion list. GT.M default behavior for exclusive kills thus reverts to its previous behavior, not compliant with the standard, where aliases and pass-by-reference variables specified in an exlusive kill are NOT killed even if their aliases are not specified in the exclusion list. In GT.M V5.3-004 (C9B09-001754), this behavior was changed to be compliant with the standard as part of the alias variables enhancement.  Please note that the default value is FALSE, so you must explicitly ask for standard-compliant behavior. (C9J11-003211)

    • String pool expansion is now more responsive to the rate at which the application requires space for local variables. This enhancement significantly improves the performance of applications that ramp up to atypically large string pool requirements (in the hundreds of thousands of local variable nodes), while preserving the more parsimonious string pool usage of typical applications. (C9J12-003215)

    • GT.M now allows an unsubscripted local variable, alias or alias container to be returned using the QUIT * syntax to a function invocation initiated using a SET *lvn=$$func() syntax. The SET * associates the target "lvn" local variable to the data space specified by the returning QUIT *. Previously GT.M only allowed alias information to be returned using the M pass-by-reference mechanism or by an alias in scope in both the caller and called routines. Additionally, the $QUIT ISV now returns the value "11" to indicate the current routine was invoked by a SET * and is required to return an alias using a QUIT * syntax. Failure to provide a QUIT * return as requested by the invocation produces an ALIASEXPECTED error. Providing a QUIT * return when not requested by the invocation produces a QUITALSINV error. (C9J12-003217)

    • UNIX editions will not report a value for $STORAGE larger than (2GB - 1)  [2,147,483,647], even if more is available. Previous versions could fail with SEG-V (SIG-11) errors while attempting to report $STORAGE values. [UNIX] (C9K01-003225). 

    • The configure installation script now assigns the correct permissions to the gtmsecshr wrapper for a non-restricted group installation.  It also creates symbolic links required for GTM and GDE help in utf-8 mode.  Previously, the setuid bit was not set for the gtmsecshr wrapper on some platforms and [z]help would fail in utf-8 mode.[UNIX] (C9K02-002758) V5.4-000A

     

    Return to Table of Contents

    Utilities-MUPIP

    • MUPIP and GT.M now clean up temporary snapshot files from INTEG under a wider variety of conditions. In V5.4-000, stopping the INTEG with a <CTRL-C> or a signal could leave the snapshot file orphaned. [UNIX] (S9K02-002757) V5.4-000A

    • MUPIP INTEG -REGION now supports the -ONLINE qualifier. This allows checking database structural integrity to run concurrently with database updates. Previously, INTEG froze updates on each region while checking it. Online integ is not supported with the -FILE qualifier. The -NOONLINE qualifier indicates that the database should be frozen during the MUPIP INTEG operation.

      The -ONLINE qualifier is now the default for MUPIP INTEG, except for databases containing V4 blocks, for which the default is -NOONLINE. Note that databases containing V4 blocks should exist only in databases that are in the process of being migrated from V4 to V5; please complete your migration to the V5 format before using MUPIP INTEG -ONLINE.

      The environment variable GTM_BAKTMPDIR (unlike most GT.M environment variables, this is upper case; it is the same directory used for MUPIP BACKUP -ONLINE) can be used to indicate a directory where MUPIP should place the snapshot files (used by online integ). If GTM_BAKTMPDIR does not exist, MUPIP places the snapshot files in the current directory at the time you issue the INTEG command.

      As it checks each database file, MUPIP INTEG -ONLINE creates a sparse file of the same size as the database.  As each GT.M process updates the database, it places a copy of the old block in the sparse file before updating the database.  For any database blocks with a newer transaction number than the start of the INTEG, MUPIP uses the copy in the sparse file.  Thus, analogous with MUPIP BACKUP -ONLINE, INTEG reports on the state of the database as of when it starts, not as of when it completes.  Note: a command such as ls -l command shows sparse files at their full size, but does not show actual disk usage. Use a command such as du -sh to see actual disk usage.

      Temporary directory security settings must allow write access by the the MUPIP process and read access by all processes updating the database. MUPIP creates the temporary file with the same access as the database file so processes updating the database can write to the temporary file. If the database is encrypted, the updating processes write encrypted blocks to the snapshot file and the MUPIP INTEG process must start with access to appropriate key information as it does even -NOONLINE.

      Only one online integ can be active per database region. If an online integ is already active, a subsequent one issues an error and immediately terminates. If an online integ does not successfully complete, GT.M cleans it up in one of the following ways:

    •  
      • A subsequent online integ detects that an earlier one did not successfully complete and releases the resources held by the prior online integ before proceeding.
      • If a MUPIP STOP was issued to the online integ process, the process cleans up any resources it held. Note: since the process was stopped the results of the integ may not be valid.
      • A subsequent MUPIP RUNDOWN ensures the release of resources held by prior unsuccessful online integs for the specified regions.
      • For every 64K transactions after the online integ initiation, online integ health GT.M checks for improperly abandoned online integs and releases resources held by any it finds.
       
      Because the online integ (now the default for most integs) does not freeze database updates, it cannot safely correct errors in the "blocks to upgrade" and "free blocks" fields in the file header, while MUPIP INTEG -NOONLINE can correct these fields.
        
      The -ONLINE qualifier is incompatible with the -TN_RESET qualifier. In any case, there should be no need to use -TN_RESET on a GT.M V5 database. [UNIX] (C9902-000839)

    • MUPIP INTEG -TN_RESET now resets block transaction numbers and backup event recorded transaction numbers to (one) 1, and the current transaction number to two (2) which makes the backup event recorded transaction numbers more meaningful and useful. It also issues an advisory message to perform a backup. Previously the backup event recorded transaction numbers were not maintained by -TN_RESET, which meant they held inappropriate information. Note that there should never be a need for a -TN_RESET on a datbase with only V5 blocks, even when cleaning up after a runaway process. (C9B12-001842)

    • GT.M now provides a new monitoring facility for processes holding a resource for an unexpected amount of time. This facility runs a shell command or a script pointed to by the new environment variable gtm_procstuckexe when any of the following conditions occur:  


      1. An explicit MUPIP FREEZE or an implicit freeze, such as BACKUP, INTEG -ONLINE, and so on, after a one minute wait on a region. 
      2. MUPIP actions find kill_in_prog (KILLs in progress) to be non-zero after a one minute wait on a region. Note that GT.M now internally maintains a list of PIDs (up to a maximum of 8 PIDs) currently doing a KILL operation.  
      3. The BUFOWNERSTUCK, INTERLOCK_FAIL, JNLPROCSTUCK, SHUTDOWN, WRITERSTUCK and MAXJNLQIOLOCKWAIT operator messages are being logged.


      Typically, for the shell script or command pointed to by gtm_procstuckexec, you would write corrective and preventive actions or obtain the stack trace of the troublesome processes (using their PIDs). GT.M passes arguments to the shell command / script in the order specified below:


      1. condition is the name of the condition. For example, BUFOWNERSTUCK, INTERLOCK_FAIL, and so on.
      2. waiting_pid is the PID of the process reporting the condition. 
      3. blocking_pid is the PID of the process holding a resource. 
      4. count is the number of times the script has been invoked for the current condition (1 for the first occurrence).


      Each invocation generates an operator log message and if the invocation fails an error message to the operator log. The shell script should start with a line beginning with #! that designates the shell. 


      Note: Make sure you have sufficient space and permissions to run the shell command / script.


      Prior versions wait for the condition to clear and in most cases send messages to the operator log. [UNIX] [C9D08-002390]

    • MUPIP now verifies that the byte ordering (endian-ness) of a journal file matches the byte ordering of the instance on which it is running and issues an error in case of a mismatch. In prior versions, such a case of operational cross-threading caused MUPIP to fail with various complaints about the journal file format or even a memory access violation (SIG-11 or ACCVIO). (C9J04-003110)

    • The replication source server now handles database files that are in WAS_ON replication state (and in turn a journaling state of OFF) in a safe manner. If it cannot find the journal records in the journal pool, it reads as many journal records as possible from the journal file chain and when it reaches the point where journaling got turned OFF, it periodically displays a REPL_WARN message until journaling gets turned back ON and then correctly issues a NOPREVLINK error. At all points, it behaves as a read-only process as far as journaling is concerned and never switches journal files. In previous versions of GT.M, it was possible for the source server to incorrectly attempt a switch of journal files in such WAS_ON regions eventually terminating with many types of errors (JNLFILOPN etc.). (C9J07-003156) V5.4-000A

    • The messages produced by a replicating instance when the originating instance encounters a REPLINSTNOHIST error now read:

      Originating instance encountered a REPLINSTNOHIST error. JNL_SEQNO of this replicating instance precedes the current history in the originating instance file. uuuu exiting.

      Where uuuu is either a rollback or the receiver server. [UNIX] (C9J08-003166)

    • By default, a Source Server now waits for a maximum of one and a half minute per region to shutdown. In prior versions, the maximum wait period for Source Server shutdown was approximately four minutes irrespective of the number of regions. (C9J09-003195).

    • MUPIP BACKUP -REPLINSTANCE now ensures its backup of the replication instance file is in sync with all databases backed up as part of the same command. This fixes a regression introduced in GT.M V5.3-000 (and present in V5.3-004A) that could in rare cases cause REPLINSTDBMATCH error when attempting to use the backed-up instance file because it held an incorrect sequence number for a database file. A workaround for this is to recreate the instance file, as the backed up databases are correct. (C9K01-003222)[UNIX]

    • GT.M now correctly handles an unusual set of circumstances that can occur if MUPIP BACKUP -ONLINE and MUPIP INTEG -ONLINE are running concurrently with M transaction processing. In V5.4-000, these unusual circumstances could cause a SIG-11. [UNIX] (C9K02-003239) V5.4-000A

     

    Return to Table of Contents

    Utilities-Other Than MUPIP

    • DSE, LKE, and MUPIP now handle unusually long command input lines more gracefully. In prior versions, long commands could damage adjacent memory and lead to difficult to diagnose failures. [UNIX] (C9J09-003199)

     

    Error Messages

    The new error messages introduced in V5.4-000 are as follows:

     

    GVDATAGETFAIL

    GVDATAGETFAIL, Global variable DATAGET sub-operation (in KILL function) failed. Failure code: cccc.

     

    Run Time Trigger Error: The target node for a KILL operation could not present its state to the trigger logic due to a database problem. cccc contains the failure codes for the failed attempts. The database may have integrity errors or the process-private data structures may be corrupted.

     

    Action: Report this database error to the group responsible for database integrity at your operation.  

    JNLENDIANBIG

    JNLENDIANBIG, Journal file jjjj is BIG endian on a LITTLE endian system

      
    MUPIP Error: The MUPIP command on a little endian system specified journal file jjjj which was created on a big endian system. GT.M does not convert journal files with incompatible byte ordering.
      
    Action: Set up operational procedures that ensure journal files are used on systems with the same byte ordering as where they are created. If necessary, extract journal file data on the source system and use an M program on the opposite endian system to restore it. 

    JNLENDIANLITTLE

    JNLENDIANLITTLE, Journal file jjjj is LITTLE endian on a BIG endian system

      
    MUPIP Error: The MUPIP command on a big endian system specified journal file jjjj which was created on a little endian system. GT.M does not convert journal files with incompatible byte ordering.
      
    Action: Set up operational procedures that ensure journal files are used on systems with the same byte ordering as where they are created. If necessary, extract journal file data on the source system and use an M program on the opposite endian system to restore it. 

    MAXSSREACHED

    MAXSSREACHED, Maximum snapshots - mmmm - for region rrrr reached. Please wait for the existing snapshots to complete before starting a new one.

      
    Mupip error: Starting this snapshot would exceed the maximum number of snapshots.
      
    Action: Wait for a currently active process using snapshots to complete or terminate an existing snapshot activity. 

    MAXTRIGRNEST

    MAXTRIGRNEST, Maximum trigger nesting level LLLL exceeded
     
    Run Time Trigger Error: GT.M limits trigger invocation depth to LLLL.
     
    Action: If you are sure that you do not have an application code bug or misfeature, reduce the depth of trigger invocation, possibly by consolidating triggers.  

    MUJNLDBMISSING 

    MUJNLDBMISSING, Journal files for required database dddd missing in the MUPIP JOURNAL command 
     
    MUPIP Error: MUPIP JOURNAL processing requires journal files for database dddd in order to perform the requested recovery, but the invoking command did not supply a path for those files.
     
    Action: Revise the command to include the appropriate journal specification(s) and reissue it.

    NOZTRAPINTRIG  

    NOZTRAPINTRIG, Use of $ZTRAP in a database trigger environment ($ZTLEVEL greater than 0) is not supported.

    Run Time Trigger Error: GT.M requires the use of $ETRAP for error handling within trigger logic.

    Action: Modify the application code to use $ETRAP to handle errors in trigger logic.

    PROCTERM

    PROCTERM, uuuu process termination due to cccc from eeee

    Utility Warning: A utility uuuu, typically MUPIP, executing application code, possibly from a trigger, encountered a command cccc to terminate at $zposition location pppp.

    Action: It is not typically wholesome for MUPIP to terminate this way - review your error handling and trigger definitions for a possible bug or misfeature.

    QUITALSINV

    QUITALSINV, QUIT * return when the extrinsic was not invoked with SET *

    Run Time Error: A [sub-]routine tried to pass an alias back to the caller, but the routine was not invoked to accept an alias return.

    Action: Rework either the invocation or the return, or troubleshoot why the inappropriate invocation occurred. If the routine should conditionally return an alias, use $QUIT to select the proper type of return. 

    REGSSFAIL

    REGSSFAIL, Process pppp encountered error contributing to the snapshot for region rrrr - the snapshot is no longer valid
      
    Mupip error: A GT.M process while trying to write a block to the snapshot failed due to some reason. The reason should be in the operator log.
      
    Action: Examine the operator log for details of the failure and take action, possibly modifying file access characteristics or user roles, to address the problem. 

    SETINTRIGONLY

    SETINTRIGONLY, ISV iiii cannot be modified outside of the trigger environment
      
    Run Time Trigger Error: The Intrinsic Special variable iiii can only be SET within the context of trigger logic ($ZTLEVEL > 0)
      
    Action: Examine the application logic to determine whether code intended for use in a trigger context falls in an execution path outside of trigger logic. For code intended to execute both inside and outside triggers, use a postcondition that limits the SET to within a trigger. 

    SNAPSHOTNOV4

    SNAPSHOTNOV4, Cannot downgrade (to V4) while snapshots are in progress. Currently ssss snapshots are in progress for region rrrr.
      
    Mupip error: A request to downgrade a region to V4 occurred while a snapshot is in progress.
      
    Action: Wait for a currently active process using snapshots to complete before running the downgrade.  Since a downgrade to V4 would not normally be expected, check to verify that the downgrade invocation is appropriate.

    SSFILCLNUPFAIL

    SSFILCLNUPFAIL, Error while unlinking snapshot file -- xxxx

    Mupip error: An attempt to terminate snapshot file maintenance by GT.M updater processes encountered a problem.

    Action: Try a MUPIP RUNDOWN. If that has a similar problem, it may be prudent to shut down all access to the database in question in order to stop the burden of maintaining the snapshot file and to ensure it doesn't unnecessarily consume more space. 

    SSFILOPERR

    SSFILOPERR, Error while doing oooo operation on file ffff
      
    Mupip error: The oooo operation on snapshot file ffff failed
      
    Action: Analyze the operation and the file characteristics and take appropriate action to clear the problem.  

    SSPREMATEOF

    SSPREMATEOF, Premature end of file while reading block nnnn of size: bbbb bytes at offset: oooo from zzzz
      
    Mupip error: The action attempted access to a block beyond the end of the snapshot file. This means either the process was confused or the file is damaged
      
    Action: Retry the action. If the problem persists, contact FIS with information on how to recreate the problem. 

    SSSHMCLNUPFAIL

    SSSHMCLNUPFAIL, Error while doing snapshot shared memory cleanup. Operation -- ssss. Identifier -- dddd
      
    Mupip error: There was an error while doing a snapshot cleanup. The operation ssss indicates what system call failed. The identifier dddd indicates the shared memory identifier that is being cleaned up.
      
    Action: Analyze the failure details and take corrective measures. If appropriate carefully clear abandoned resources using the system ipcrm utility. 

    SSTMPCREATE

    SSTMPCREATE, Cannot create the temporary file in directory dddd for the requested snapshot
      
    Mupip error: An action requiring a snapshot file was unable to create it.
      
    Action: Verify the directory has appropriate access permissions for the user performing the action. 

    SSTMPDIRSTAT

    SSTMPDIRSTAT, Cannot access temporary directory dddd
      
    Mupip error: An action requiring a snapshot file was unable to access the temporary directory.
      
    Action: Verify the directory exists and has appropriate access permissions for the user performing the action. 

    SSTMPFILOPEN

    SSTMPFILOPEN, Failed to open shadow snapshot file ffff
      
    Mupip error: An action requiring a snapshot file was unable to open it.
      
    Action: Verify the file exists and has appropriate access permissions for the user performing the action. 

    SSV4NOALLOW

    SSV4NOALLOW, Database snapshots are supported only on fully upgraded V5 databases. nnnn has V4 format blocks.
      
    Mupip error: An action requiring a snapshot was attempted on a database the contains V4 format blocks.
      
    Action: Upgrade the database to V5 and re-run the action. 

    TRIG2NOTRIG

    TRIG2NOTRIG, Sending transaction sequence number xxxx which used triggers to a replicator that does not support triggers
      
    MUPIP Warning: The source server encountered a transaction that includes triggers, but its replicating node does not support triggers. Unless you are using application level filters to handle this case, your originating instance and replicating instance are no longer consistent.
      
    Action: If this case it not handled by your application level filters, you should either enhance your filters or upgrade the replicating instance to a version of GT.M that supports triggers and load the the appropriate trigger definitions with MUPIP TRIGGER (or $ZTRIGGER()), and then take appropriate action (such as recreating the replicating instance from a backup of the originating instance) to restore consistency.  

    TRIGCOMPFAIL

    TRIGCOMPFAIL, Compilation of database trigger named tttt failed 
     
    Run Time Trigger Error: The -Xecute code of a trigger specification has syntax errors. Because triggers are precompiled when you define them, this error may indicate that either:

    • A database upgrade was performed but the trigger code was not updated to eliminate obsolete syntax
    • The portion of the database holding the trigger definitions may be corrupted

    Action: Validate the definitions by a SELECT option with MUPIP TRIGGER or $ZTRIGGER(), correct the trigger code syntax and apply a trigger update.  

    TRIGINVCHSET

    TRIGINVCHSET, Trigger tttt for global gggg was created with CHSET=cccc which is different from the current $ZCHSET of this process
      
    Run Time Trigger Error: Trigger tttt on global gggg failed because the process that attempted to update global gggg did not have the same character set that was used to load trigger tttt.  Databases with triggers can only be used by processes that are M mode or UTF-8 mode, depending on the mode of the process that loaded the triggers.

    Action: Ensure that processes start with the same character set (as defined by the gtm_chset environment variable) that was used to load the trigger definitions with MUPIP TRIGGER (or $ZTRIGGER() function).

    TRIGJNLSTATE

    TRIGJNLSTATE, Trigger cannot update journaled database file dddd since triggering update was not journaled

    Run Time Trigger Error: A process performed an update on a global in a database region which is not currently journaled, and that update invoked a trigger that, in turn, attempted an update on a global in a database region that is journaled. The secondary GVIS message provides the global name. This would produce a journal state with insufficient information to ensure proper replication of the region with the triggered update.

    Action: Revise global directories, journaling characteristics, or trigger logic to prevent this situation.  

    TRIGNAMEUNIQ

    TRIGNAMEUNIQ, Unable to make trigger name tttt unique beyond vvvv versions already loaded

    Run Time Trigger Error: GT.M encountered more than vvvv different instances of the same trigger name across database regions used by the same process.

    Action: Revise trigger names to prevent such a high degree of overlap.

    TRIGTCOMMIT

    TRIGTCOMMIT, TCOMMIT at $ZTLEVEL=LLLL not allowed as corresponding TSTART was done at lower $ZTLEVEL=BBBB

    Run Time Trigger Error: A TCOMMIT in trigger logic attempted to complete the active transaction that was started outside of the current trigger. Because trigger actions are atomic with the update initiating them, committing a transaction started prior to or by the triggering update cannot be committed inside the trigger.

    Action: Within the trigger context, review the TCOMMIT logic to ensure that it commits only those transactions that are started within the trigger. Ensure that TCOMMIT does not attempt to commit any transaction started prior to or by the triggering update.  

    TRIGTLVLCHNG

    TRIGTLVLCHNG, Detected a net transaction level ($TLEVEL) change during trigger tttt. Transaction level must be the same at exit as when the trigger started

    Run Time Trigger Error: While the trigger logic can use balanced sub-transactions, it cannot cause a net change in $TLEVEL.

    Action: Review the transaction management (TSTART, TCOMMIT and TROLLBACK) within trigger logic to ensure that it commits or rolls back any transactions it starts and does not attempt to commit any transaction started prior to, or by, the trigger update. You can use TROLLBACK within trigger logic to block the current transaction, possibly to write error context information. Nonetheless if you use such a TROLLBACK, GT.M subsequently signals this error when you leave the trigger context in order to notify the process that the original triggering update has been discarded.

    ZGOTOINVLVL

    ZGOTOINVLVL, ZGOTO in a trigger running in mmmm cannot ZGOTO level LLLL

    MUPIP Error: A ZGOTO command in trigger logic attempted to specify an inappropriate destination. Currently that is a ZGOTO in a trigger context with a target level of one (1) and an entryref. GT.M does not support such ZGOTO arguments in MUPIP because there is no context outside that of the trigger.

    Action: Revise the trigger logic to only use ZGOTO with an entryref within the trigger context of trigger logic. Note that you can ZGOTO out of a trigger, but doing so in MUPIP terminates the MUPIP process. FIS recommends limiting the use of ZGOTO to debugging, error handling and testing. Use of ZGOTO in production code, even for error processing, should always be thoroughly tested.

    ZTRIGINVACT

    ZTRIGINVACT, Missing or invalid subcode (first) parameter given to $ZTRIGGER()

    Run Time Trigger Error: The first argument to $ZTRIGGER() is required to specify its mode of action.

    Action: for the first argument of $ZTRIGGER() use an expression that evaluates to "FILE", "ITEM" or "SELECT".

    ZTRIGNOTP

    ZTRIGNOTP, $ZTRIGGER() cannot use update subcodes FILE or ITEM when a TP transaction is in progress ($TLEVEL greater than zero)

    Run Time Trigger Error: A FILE or ITEM operation of $ZTRIGGER() failed because it attempted to apply a trigger definition inside an ongoing transaction. Both FILE and ITEM operations of $ZTRIGGER initiate an implicit transaction to achieve trigger update atomicity, therefore, GT.M does not allow nesting them inside another transaction that potentially might use the very triggers $ZTRIGGER() is attempting to update.

    Action: Move all FILE or ITEM operations of $ZTRIGGER() outside the scope of any open transaction.

    ZTWORMHOLE2BIG

    ZTWORMHOLE2BIG, String length of LLLL bytes exceeds maximum length of mmmm bytes for $ZTWORMHOLE

    Run Time Trigger Error: GT.M limits $ZTWORMHOLE length to mmmm bytes and the application attempted to use LLLL bytes.

    Action: Restrict the size of the string stored in $ZTWORMHOLE to mmmm bytes. Ensure that $ZTWORMHOLE only holds the information that the application needs during trigger execution. If necessary, reorganize the logic to reduce the amount of local context needed during trigger execution, possibly by using global variables. 


    Return to Table of Contents

     
     

    GT.M Documentation Addendum

    This addendum includes an improved description of SOCKET READ operation and MOREREADTIME deviceparameter. 

    SOCKET READ operation

    TCP/IP is a stream-based protocol that guarantees that bytes arrive in the order in which they were sent. However, it does not guarantee that they will be grouped in the same packets.

    If packets arrive infrequently, or at varying rates that are sometimes slow, a short interval can waste CPU cycles checking for an unlikely event. On the other hand, if the handling of packets is time critical, a long interval can introduce an undesirable latency. If packets arrive in a rapid and constant flow (an unusual situation), the interval doesn't matter as much, as there is always something in the buffer for the READ to work with. If you do not specify MOREREADTIME, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive. If you specify an interval, the SOCKET device always uses the specified interval and doesn't adjust dynamically. For more information on MOREREADTIME, see "MOREREADTIME".

    Most SOCKET READ operations terminate as a result of the first condition detected from (a) receipt of delimiters, (b) receipt of the maximum number of characters, or (c) expiration of a timeout.  Note that all of these conditions are optional, and a specific READ may specify zero or more of them.  This document refers to these three conditions as "defined terminating conditions". If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates after it has received at least one character followed by an interval with no new characters. READ also terminates on the receipt of a character that puts the device at its specified WIDTH - you can vary the WIDTH, but it's not optional. An error can also terminate a READ. While none of the terminating conditions is satisfied, the READ continues.
     
    The following flowchart represents the logic of a SOCKET READ.   
     



    SOCKET READ Termination Conditions

     A SOCKET READ operation terminates if any of the following conditions are met:
     
    Terminating Conditions Argument Contains $Device $Key $Test
    Error Empty String Error String Empty String 1
    Timeout* Data received before timeout Empty String Empty String 0
    Delimiter* Data up to, but not including the delimiter Empty String Delimiter String 1
    Fixed Length Met*
    String of Fixed Length
    		 Empty String Empty String 1
    Width
    		 Full width String
    		 Empty String Empty String 1
    Buffer Emptied
    One (1) to as many characters as provided by the transport interface before waiting for an interval (in milliseconds) specified by MOREREADTIME with no additional input. If MOREREADTIME is not specified, buffer is checked every 200 milliseconds for its first input and then every 10 milliseconds until no new input arrives and no other terminating conditions are met.
    IF MOREREADTIME is specified, READ uses that value exclusively for buffer checks.
    		 Empty String Empty String 1
      
    * Defined Terminating Conditions  
     

    A non-fixed-length read, with no timeout and no delimiters (the sixth row in the above table) requires a complex implementation of sequence of READs to ensure a predictable result. This is because the transport layer stream fragments delivered to the reader has only accidental correspondence with the operations performed by the writer. For example, the following:

     

    Write "Message 1","Message 2" is presented to the reader as the stream "Message1Message2" but it can take from one (1) to 18 READ commands to retrieve the entire stream.


    Your messaging protocol should implement READ in any of the following ways: 
     
    1. Use a delimiter to separate messages (generic READ and possibly a larger value for MOREREADTIME). 
    1. Specify messages as <length, value> pairs (a pair of fixed-length READs (READ # ) and possibly a larger value for MOREREADTIME).
    2. Parse the bytes or characters as they come in (possibly a smaller value for MOREADTIME) 

    MOREREADTIME=intexpr

    MOREREADTIME specifies the polling interval (in milliseconds) that a SOCKET device uses to check for arriving packets.

    If you do not specify MOREREADTIME, SOCKET READ implements a dynamic approach of using a longer first interval of 200 ms when it finds no data, then shortening the interval to 10 ms when data starts to arrive. If you specify an interval, the SOCKET device always uses the specified interval and doesn't adjust dynamically. This applies to any SOCKET READ. For more information on implementing SOCKET READ in your application, see "SOCKET READ Operations".

    If a SOCKET READ is not subject to any of the defined terminating conditions, it terminates either after it has at least one character followed by an interval with no new packets, or by reaching the specified maximum WIDTH for the SOCKET.

    If you use the MOREREADTIME behavior, bear in mind that:
     
    • Usually, it is more efficient and responsive for an application to wait and process input in larger chunks. Therefore, a larger value for MOREREADTIME can bring larger chunks of input to the application. However, large values may make for sluggish response.
    • A short value for MOREREADTIME may consume considerable CPU cycles, especially on a lightly loaded system.
    • The maximum value of MORETREADTIME is 999 (basically 1 second). Never set MOREREADTIME to 0 as it causes excessive CPU "spinning".
     

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



    \ No newline at end of file diff --git a/articles/images/V52000b.html b/articles/images/V52000b.html new file mode 100644 index 0000000..aa25c83 Binary files /dev/null and b/articles/images/V52000b.html differ diff --git a/articles/images/V53001A.html b/articles/images/V53001A.html new file mode 100644 index 0000000..79c48f9 Binary files /dev/null and b/articles/images/V53001A.html differ diff --git a/articles/images/V54002a.html b/articles/images/V54002a.html new file mode 100644 index 0000000..b5ea9de Binary files /dev/null and b/articles/images/V54002a.html differ diff --git a/articles/images/caution.html b/articles/images/caution.html new file mode 100644 index 0000000..dc2099d Binary files /dev/null and b/articles/images/caution.html differ diff --git a/articles/images/dhpr4zmp_26dcc6vhf4_b.html b/articles/images/dhpr4zmp_26dcc6vhf4_b.html new file mode 100644 index 0000000..07c5ce3 Binary files /dev/null and b/articles/images/dhpr4zmp_26dcc6vhf4_b.html differ diff --git a/articles/images/dhpr4zmp_31wmqvh9f8_b.html b/articles/images/dhpr4zmp_31wmqvh9f8_b.html new file mode 100644 index 0000000..4f5ffb6 Binary files /dev/null and b/articles/images/dhpr4zmp_31wmqvh9f8_b.html differ diff --git a/articles/images/dpqq6h6_116dctrqc96_b.html b/articles/images/dpqq6h6_116dctrqc96_b.html new file mode 100644 index 0000000..cd6c792 Binary files /dev/null and b/articles/images/dpqq6h6_116dctrqc96_b.html differ diff --git a/articles/images/dpqq6h6_121djvxq8t5_b.html b/articles/images/dpqq6h6_121djvxq8t5_b.html new file mode 100644 index 0000000..13fc561 Binary files /dev/null and b/articles/images/dpqq6h6_121djvxq8t5_b.html differ diff --git a/articles/images/dpqq6h6_127drtnzgdx_b.html b/articles/images/dpqq6h6_127drtnzgdx_b.html new file mode 100644 index 0000000..b89a723 Binary files /dev/null and b/articles/images/dpqq6h6_127drtnzgdx_b.html differ diff --git a/articles/images/dpqq6h6_146f2ddzchr_b.html b/articles/images/dpqq6h6_146f2ddzchr_b.html new file mode 100644 index 0000000..287b478 Binary files /dev/null and b/articles/images/dpqq6h6_146f2ddzchr_b.html differ diff --git a/articles/images/dpqq6h6_157hfmf6mgg_b.html b/articles/images/dpqq6h6_157hfmf6mgg_b.html new file mode 100644 index 0000000..2b98b9c Binary files /dev/null and b/articles/images/dpqq6h6_157hfmf6mgg_b.html differ diff --git a/articles/images/dpqq6h6_158fq7xrpdd_b.html b/articles/images/dpqq6h6_158fq7xrpdd_b.html new file mode 100644 index 0000000..ccf3b33 Binary files /dev/null and b/articles/images/dpqq6h6_158fq7xrpdd_b.html differ diff --git a/articles/images/dpqq6h6_162dqb8nrc9_b.html b/articles/images/dpqq6h6_162dqb8nrc9_b.html new file mode 100644 index 0000000..fb33126 Binary files /dev/null and b/articles/images/dpqq6h6_162dqb8nrc9_b.html differ diff --git a/articles/images/dpqq6h6_58srvjvdfg_b.html b/articles/images/dpqq6h6_58srvjvdfg_b.html new file mode 100644 index 0000000..b64e3e1 Binary files /dev/null and b/articles/images/dpqq6h6_58srvjvdfg_b.html differ diff --git a/articles/images/drawing_sEEzwlCChgZAenMJHskeK6g_12.html b/articles/images/drawing_sEEzwlCChgZAenMJHskeK6g_12.html new file mode 100644 index 0000000..78ccf80 Binary files /dev/null and b/articles/images/drawing_sEEzwlCChgZAenMJHskeK6g_12.html differ diff --git a/articles/images/drawing_sQBY8hzphb9II-fQ5xPgUpg_8.html b/articles/images/drawing_sQBY8hzphb9II-fQ5xPgUpg_8.html new file mode 100644 index 0000000..88a92a5 Binary files /dev/null and b/articles/images/drawing_sQBY8hzphb9II-fQ5xPgUpg_8.html differ diff --git a/articles/images/important.html b/articles/images/important.html new file mode 100644 index 0000000..bf7d899 Binary files /dev/null and b/articles/images/important.html differ diff --git a/articles/images/tip.html b/articles/images/tip.html new file mode 100644 index 0000000..0ee18f4 Binary files /dev/null and b/articles/images/tip.html differ diff --git a/articles/images/warning.html b/articles/images/warning.html new file mode 100644 index 0000000..ac44680 Binary files /dev/null and b/articles/images/warning.html differ diff --git a/books/ao/OpenVMS_manual/ao_figures/ch6_1.html b/books/ao/OpenVMS_manual/ao_figures/ch6_1.html new file mode 100644 index 0000000..ac93523 Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/ch6_1.html differ diff --git a/books/ao/OpenVMS_manual/ao_figures/ch6_2_b.html b/books/ao/OpenVMS_manual/ao_figures/ch6_2_b.html new file mode 100644 index 0000000..58d7667 Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/ch6_2_b.html differ diff --git a/books/ao/OpenVMS_manual/ao_figures/ch6_3_b.html b/books/ao/OpenVMS_manual/ao_figures/ch6_3_b.html new file mode 100644 index 0000000..2f6a666 Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/ch6_3_b.html differ diff --git a/books/ao/OpenVMS_manual/ao_figures/cmplx_dual_site_fail.html b/books/ao/OpenVMS_manual/ao_figures/cmplx_dual_site_fail.html new file mode 100644 index 0000000..df18d6a Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/cmplx_dual_site_fail.html differ diff --git a/books/ao/OpenVMS_manual/ao_figures/gtm_recovery_architecture.html b/books/ao/OpenVMS_manual/ao_figures/gtm_recovery_architecture.html new file mode 100644 index 0000000..54fd5f5 Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/gtm_recovery_architecture.html differ diff --git a/books/ao/OpenVMS_manual/ao_figures/log_dual_site_arch.html b/books/ao/OpenVMS_manual/ao_figures/log_dual_site_arch.html new file mode 100644 index 0000000..6378094 Binary files /dev/null and b/books/ao/OpenVMS_manual/ao_figures/log_dual_site_arch.html differ diff --git a/books/ao/OpenVMS_manual/ch06s03.html b/books/ao/OpenVMS_manual/ch06s03.html index 9080351..a071d6a 100644 --- a/books/ao/OpenVMS_manual/ch06s03.html +++ b/books/ao/OpenVMS_manual/ch06s03.html @@ -33,11 +33,11 @@ if the current database is destroyed, you must use Forward Recovery. If a journal file was created using NOBEFORE_IMAGES, that journal permits only Forward Recovery.

    Example of Forward Recovery:

    Example: MUPIP JOURNAL /RECOVER

    - +

    This shows a recovery after a system crash at 10:35 which processes the entire journal file forward.

    - +

    By adding /BEFORE="- @@ -57,7 +57,7 @@ than M-level (or NOBEFORE) journaling.

    Do not dele only occur into an existing/used database.

    Use /RECOVER /FORWARD for databases that have been recreated.

    Example of Backward Recovery:

    - +

    This shows a recovery after a system crash at 10:35. The recovery diff --git a/books/ao/OpenVMS_manual/ch07s01.html b/books/ao/OpenVMS_manual/ch07s01.html index abde293..31c5945 100644 --- a/books/ao/OpenVMS_manual/ch07s01.html +++ b/books/ao/OpenVMS_manual/ch07s01.html @@ -24,7 +24,7 @@ in case of loss of the primary. For optimum performance on the primary system, disk I/O related to the replication process should be zero (i.e., the replication Source Server process should be able to operate without reading from or writing to disk). To achieve this, the network connection and - the software subsystem of the secondary must have adequate bandwidth for peak update rates on the primary.

    Figure 7.1. GT.M Recovery Architecture

    Illustrates the basic configuration and components of the GT.M recovery architecture.
    Shaded areas denote additional system components in logical dual site operation of a GT.M application, not found in single site operation.

    [Note]

    All GT.M processes accessing a replicated database must use the same Global Directory. M-extended references are not allowed.

    Database replication is a general-purpose tool. Although the primary emphasis in this manual is logical + the software subsystem of the secondary must have adequate bandwidth for peak update rates on the primary.

    Figure 7.1. GT.M Recovery Architecture

    Illustrates the basic configuration and components of the GT.M recovery architecture.
    Shaded areas denote additional system components in logical dual site operation of a GT.M application, not found in single site operation.

    [Note]

    All GT.M processes accessing a replicated database must use the same Global Directory. M-extended references are not allowed.

    Database replication is a general-purpose tool. Although the primary emphasis in this manual is logical dual-site operation, GT.M database replication can also be used to do the following:

    • Provide a real-time data feed from a database to another system where a different application runs. Restrictions on updating replicated regions on the secondary system do not apply if the secondary is not used as a backup for the primary.

    • Implement a logical, triple-site operation to provide for continuous application diff --git a/books/ao/OpenVMS_manual/ch07s02.html b/books/ao/OpenVMS_manual/ch07s02.html index 753a8e9..59bdcd7 100644 --- a/books/ao/OpenVMS_manual/ch07s02.html +++ b/books/ao/OpenVMS_manual/ch07s02.html @@ -34,7 +34,7 @@ process.

    • Additional requirements for application the "Messaging" section which follows. As previously noted, all processes accessing a replicated database must use the same Global Directory. Do not use M extended references since they can have -unpredictable results.

    Figure 7.2. Logical Dual-Site Application Architecture

    Represents logical dual-site application architecture.

    Messaging

    For online operations, application servers on the primary respond to +unpredictable results.

    Figure 7.2. Logical Dual-Site Application Architecture

    Represents logical dual-site application architecture.

    Messaging

    For online operations, application servers on the primary respond to messages from clients delivered over a network. Each message is assumed to result in zero (inquiry) or one (updated) transaction on the server. The network that delivers messages must be robust. This means that each message @@ -371,7 +371,7 @@ up, it will act as the secondary and be forced to rollback all transactions performed while it was primary and Site A was down. These transactions become non-replicated transactions. If Site B came up first, then the non-replicated transactions would occur when Site A restarted. These would -be the transactions while A was primary after B failed.

    Figure 7.3. Complex Dual-Site Failure

    Represents Complex Dual-site Failure

    When recovering from these situations, the primary is always the current +be the transactions while A was primary after B failed.

    Figure 7.3. Complex Dual-Site Failure

    Represents Complex Dual-site Failure

    When recovering from these situations, the primary is always the current system of record when the secondary comes up. The secondary must roll its database back to the transaction with the highest journal sequence number for which both systems are known to be in agreement, and "catch up" from diff --git a/books/ao/OpenVMS_manual/images/FIS_RGB_logo.html b/books/ao/OpenVMS_manual/images/FIS_RGB_logo.html new file mode 100644 index 0000000..f6f1a4b Binary files /dev/null and b/books/ao/OpenVMS_manual/images/FIS_RGB_logo.html differ diff --git a/books/ao/OpenVMS_manual/titlepage.html b/books/ao/OpenVMS_manual/titlepage.html index 6427fcf..730ed53 100644 --- a/books/ao/OpenVMS_manual/titlepage.html +++ b/books/ao/OpenVMS_manual/titlepage.html @@ -1,6 +1,6 @@ -GT.M Administration and Operations Guide

    GT.M Administration and Operations Guide
    Next

    GT.M Administration and Operations Guide

    Copyright (C) +GT.M Administration and Operations Guide

    GT.M Administration and Operations Guide
    Next

    GT.M Administration and Operations Guide

    Copyright (C) 2010 Fidelity Information Services, Inc. All rights reserved.

    October 26, 2010 diff --git a/books/pg/OpenVMS_manual/examples_of_query.html b/books/pg/OpenVMS_manual/examples_of_query.html index eac07b2..6b5a430 100644 --- a/books/pg/OpenVMS_manual/examples_of_query.html +++ b/books/pg/OpenVMS_manual/examples_of_query.html @@ -46,7 +46,7 @@

    The tree diagram below represents the structure produced by the preceding routine.

    - +

    The following routine:

    diff --git a/books/pg/OpenVMS_manual/examples_of_ztcommit.html b/books/pg/OpenVMS_manual/examples_of_ztcommit.html
index f1f027a..cd389ed 100644
--- a/books/pg/OpenVMS_manual/examples_of_ztcommit.html
+++ b/books/pg/OpenVMS_manual/examples_of_ztcommit.html
@@ -42,7 +42,7 @@
       
    This ZTCOMMIT issued from Direct Mode would close any open ZTSTARTs.
    
       
    Example:
    
       
    
-    
+    
     
    
       
    This shows a transaction with two independent nested sub-transactions. For additional examples, refer to the ZTSTART examples.
    diff --git a/books/pg/OpenVMS_manual/pg_figures/ch6_001.html b/books/pg/OpenVMS_manual/pg_figures/ch6_001.html new file mode 100644 index 0000000..8e0e32c Binary files /dev/null and b/books/pg/OpenVMS_manual/pg_figures/ch6_001.html differ diff --git a/books/pg/OpenVMS_manual/pg_figures/ch7_001.html b/books/pg/OpenVMS_manual/pg_figures/ch7_001.html new file mode 100644 index 0000000..a02f092 Binary files /dev/null and b/books/pg/OpenVMS_manual/pg_figures/ch7_001.html differ