Release Notes: GT.M Version 5.2-001 Release
Copyright © 2010 Fidelity Information Services, Inc. All Rights Reserved.
Legal Notice
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.
GT.M.™ is a trademark of Fidelity Information Services, Inc. Other trademarks are the property of their respective owners.
This document contains a description of GT.M and the operating instructions pertaining to the various functions that comprise the system. This document does not contain any commitment of FIS. FIS believes the information in this publication is accurate as of its publication date; such information is subject to change without notice. FIS is not responsible for any errors or defects.
October 26, 2010
| Revision History | |
|---|---|
| Revision 1.2 | October 26, 2010 |
| Marked S9H02-002643 as an all platform enhancement. Due to a documentation error, it was previously marked as [UNIX]. | |
| Revision 1.1 | June 30, 2007 |
| First published version. | |
Contact Information
|
GT.M Group
|
GT.M Support: +1 (610) 578-4226
|
Table of Contents
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 [ ].
V5.2-001 permits NOBEFORE_IMAGE journaling with GT.M database replication. Previously, GT.M database replication required BEFORE_IMAGE journaling. NOBEFORE_IMAGE journaling consumes less I/O bandwidth in normal use while BEFORE_IMAGE journaling delivers faster recovery times from system failures. Especially in a logical multi-site deployment of an application that pushes the I/O bandwidth of the servers it runs on, increased recovery times in the unlikely event of a crash that result from the use of NOBEFORE_IMAGE journaling may well be a trade-off worth making in order to obtain more throughput from available servers.
Also in V5.2-001, it is now possible to replicate from a primary instance deployed on a server with a big-endian hardware architecture (for example, IBM pSeries AIX or Sun SPARC Solaris) to one with a little-endian architecture (for example, x86 GNU/Linux) and vice versa. Run-time conditions such as no available disk space or no authorization for a process attempting to auto-switch a journal file that cause GT.M journaling to turn OFF no longer immediately also turn replication off. Instead, replication remains on for any secondary instances that are updated from the journal pool. GT.M turns off replication for any secondary instances that require updates from a journal file.
Further, V5.2-001 fixes a number of issues, particularly compilation problems introduced in V5.2-000/A/B.
See section V5.2-001 Change History for a brief description of the fixes and enhancements in this release.
As of the publication date, Fidelity supports this release on the following hardware and operating system versions. Contact Fidelity for a current list of supported platforms.
|
Platform |
Supported Versions |
Notes | |||
|---|---|---|---|---|---|
|
Hewlett-Packard HP-PA HP-UX |
11i V2 |
GT.M supports UTF-8 mode and M mode on this platform.
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. | |||
|
Hewlett-Packard Alpha/AXP Tru64 UNIX |
5.1B |
GT.M supports M mode but not UTF-8 mode on this platform. | |||
|
Hewlett-Packard Alpha/AXP OpenVMS |
7.3-1/7.3-2/8.2 |
GT.M supports M mode but not UTF-8 mode on this platform. Users who need to work with external calls written in C with Version 6.x of the Compaq C compiler on Alpha OpenVMS must carefully review all the provided kits for that product and apply them appropriately. | |||
|
IBM eServer pSeries AIX |
5.2/5.3 |
| |||
|
Sun SPARC Solaris |
9.0 |
GT.M supports deprecated DAL calls in M mode but not in UTF-8 mode. | |||
|
x86 GNU/Linux - Red Hat Enterprise Linux |
4 |
Although Red Hat Enterprise Linux is the formally supported distribution, the software should run on any contemporary combination of kernel, glibc (version 2.3.2 or later) and ncurses (version 5).The minimum CPU now must have the instruction set of a 686 (Pentium Pro) or equivalent. Contact Fidelity for support of older CPUs. |
![[Tip]](images/tip.jpg)
Users who upgrade from GT.M V5.0-000 or later do not require a global directory upgrade.
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 there no changes made, an EXIT command automatically replaces the V4 format global directory file with a V5 format global directory file.
![[Note]](images/note.jpg) | |
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:
Open the global directory with V5 GDE.
Execute the SHOW ALL command.
Then, edit the output into a command file or manually enter the commands corresponding to the output into a V4 GDE invocation.
Users who upgrade from a GT.M version prior to V5.0-000 need to perform a database upgrade. See Database Migration Technical Bulletin (GTM_Database_Migration.html) 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.
| |
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. |
See the "Installing GT.M" section in the GT.M Administration and Operations Guide.
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.
Use the MUPIP RUNDOWN command of the old GT.M version to bring down any open database files.
In UNIX editions, make sure gtmsecshr is not running. If found running, perform kill <pid of gtmsecshr>.
![[Caution]](images/caution.jpg)
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).
In UNIX editions, GT.M configure script asks the following question:
Enter the RC node ID of the GT.CM server, if desired (42).
Respond by pressing ENTER.
GT.M for IBM pSeries AIX requires 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
smitty aio (for text mode)
Select "Configure AIO now" which gives a message like "aio0 has been created". This means that there is no further need of setup at this time. Note that some systems may have a "posixaio" option instead of "aio", so in the case that the above SMIT command fails. If this is the case then try posixaio instead. In addition to configuring the aio0 device, select "Change/Show characteristics of Asynchronous I/O" then change the value of "State to be configured at system restart" from "defined" to "available". This ensures that the aio0 device is available when the system is rebooted next.
Users who expect their database files to grow larger than 2GB must configure its file system to permit files larger than 2GB. By default, a journal file can grow to a maximum size of 4GB, therefore users must set the journal auto switch limit to less than 2 GB for any journal file on a file system with a 2GB limit.
In OpenVMS, users who upgrade from a GT.M version prior to V4.3-001 must update any customized copy of GTM$DEFAULTS to include a definition for GTM$ZDATE_FORM.
User can ignore the following section if they choose standard GT.M configuration or if answer yes to the following question:
Do you want to define GT.M commands to the system
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.
On a system that does not have ICU installed, GT.M assumes M mode operation and installs M mode components only.
On a system having 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 when a process executes that module. 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 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. 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 must consider the same 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 V5.2-000 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-0001, then $gtm_dist is set to /usr/local/gtm_V5.2-0001/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.
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]](images/important.jpg) | |
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. |
Fixes and enhancements specific to V5.2-0001 are:
GT.M now maintains the instance file name even if database shared memory is released and then re-initialized. Unusual terminations in previous versions could, in rare cases, trigger inappropriate REPLINSTMISMATCH errors.
Users must now always define the environment variable gtm_repl_instance before accessing an instance. Previously, this was not required for some GT.M utility actions. Fidelity recommends users review their scripts to ensure that the environment variable gtm_repl_instance environment is properly set for database replication. (C9H03-002827)
GT.M now correctly maintains free blocks counter in the file header. Previous versions could, in rare cases, cause this counter to become incorrect and consequently result in GTMASSERT errors. (C9H06-002867)
GT.M now maintains database integrity throughout a database commit operation even when it encounters most known unusual conditions (typically caused by abnormal process terminations). Prior versions used to complete the database commit operation under these unusual circumstances, but in some cases might create a variety of integrity errors. (C9H06-002867)
A GT.M V4 database that was upgraded to GT.M V5 version may contain RECYCLED blocks (previously used, but since freed by a KILL) that are still in the V4 block format. A GT.M process that tries to reuse such a block now completes with no errors. The same condition in previous versions used to trigger GVxxxFAIL or TPFAIL errors with failure code cccc. (C9H06-002867)
$ORDER() now returns local array subscripts with values that are numeric, but non-canonical (over 18 digit), as strings. Previous versions returned such values as numbers, which meant if that returned value was used directly as subscript then it would reference to an undefined value and trigger an error. (S9F03-002537)
The SOCKET device driver correctly manages memory on OPEN/CLOSE sequences. In prior versions, GT.M exhibited process size growth when it encountered many such sequences. (S9H04-002654)
Using an unrecognized Intrinsic Function or Intrinsic Special Variable (ISV) now generates a compile-time error as well as the object file. As long as the function remains unexecuted or the ISV is not accessed at run-time, GT.M triggers no errors at run-time. This fixes a problem introduced in V5.2-000A where certain changes due to S9F10-002572 incorrectly triggered a GTMASSERT, UNIMPLOP or MEMORY error during compilation of an M program resulting in GT.M not generating an object file. (C9H04-002856)
In UTF-8 mode, GT.M now correctly triggers a BADCHAR compile-time error and creates an object file on compiling an M program that contains invalid UTF-8 byte sequences. In prior versions (V5.2-000, V5.2-000A, and V5.2-000B), GT.M triggered a GTMASSERT or MEMORY error on compiling such M programs and did not generate an object file. (C9H05-002861)
GT.M now triggers the same error at both compile-time and run-time. Previous versions sometimes incorrectly triggered different errors at run-time and compile-time. For example, WRITE $PIECE("a",2E300,6) used to generate a NUMOFLOW error at compile-time and an EXPR error at run-time. Now, GT.M correctly reports a NUMOFLOW error at both compile time and run-time. (C9H05-002861)
GT.M now ensures that if an external caller removes the GT.M run-time shared library from memory, AIX performs appropriate GT.M exit handling before removing the library. In prior versions, AIX could go into an indefinite loop using CPU cycles in a vain attempt to figure out how to run GT.M exit handling code that was no longer available. [AIX] (C9H05-002864)
Timed reads using the terminal device now wait for no more than the specified timeout. Previous V5.2 versions could wait for longer than the timeout in case not all bytes of a multi-byte character were available. (C9H06-002866) [UNIX]
Untimed reads using the terminal device sleep until data is available. Previous V5.2 versions used to sleep for around 100 seconds and then use almost 100% of the CPU (albeit at a reduced priority, so they did not impede the execution of other processes). (C9H06-002866) [Linux]
Run-time conditions such as no available disk space or no authorization for a process attempting to auto-switch a journal file cause GT.M to turn journaling off. In such a case, GT.M now operates as follows:
If the journaled database is NOT replicated, GT.M now logs a JNLCLOSED error to the syslog (operator log in VMS).
If the journaled database is ALSO replicated, GT.M now logs a REPLJNLCLOSED to the syslog (operator log in VMS). In this case, GT.M now leaves replication on in a "fragile" state (identified in the header as WAS_ON), continuing to work as long as the secondary keeps up well enough so that a source server on the primary does not need to read from the journal files (using only the journal pool). If a source server needs access to the no-longer available journal files, it stops actively replicating to its secondary. GT.M attempts to restore journaling / replication to normal operation when users corrects the cause of the journal closing and execute MUPIP SET REPLICATION=ON or MUPIP BACKUP REPLICATION=ON command. If an operator does this before replication requires journal file access, replication operates without interruption, and restoration of the secondary is not required. Any secondary instance not able to keep up with the updates from the journal pool, and requiring updating from non-existent journal files needs to be recreated from a backup made after normal operation of the primary is restored.
In order to alert operational staff so they can remedy the situation, MUPIP REPLIC -SOURCE -CHECKHEALTH now detects when GT.M has turned journaling and/or replication off (without an operator command) and reports this state by printing a REPLJNLCLOSED message each for every region that had replication switched to the WAS_ON state. It also exits with a non-zero status in this case.
In prior versions, GT.M did not provide as much operational information, and shut down replication when journaling had to be shut down. (S9H02-002643)
GT.M now supports multi-site replication across little endian and big endian format hardware architectures. Previous versions required all primary and secondary instances of a multi-site replication configuration have the same endian format. The receiver server now automatically detects the endian format of an incoming replication stream and converts it into the native endian format. This conversion happens internally and is transparent to the user.
Always use MUPIP ENDIANCVT command to convert a database file when transferring databases from nodes of different endian other than by replication. [UNIX] (C9C06-002041)
MUPIP BACKUP ONLINE now creates a clean backup database file even when cleanup processing runs due to unusual circumstances. Prior versions used to create broken backup database files even though the live database was undamaged. (C9D08-002392)
GT.M replication now works with NOBEFORE_IMAGE journaling. Previous versions required the use of BEFORE_IMAGE journaling with replication.
NOBEFORE_IMAGE journaling consumes less I/O bandwidth in normal use while BEFORE_IMAGE journaling delivers faster recovery times from system failures. Especially in a logical multi-site deployment of an application that pushes the I/O bandwidth of the servers it runs on, increased recovery times in the unlikely event of a crash that result from the use of NOBEFORE_IMAGE journaling may well be a trade-off worth making in order to obtain more throughput from available servers. To recover an instance using NOBEFORE_IMAGE journaling, restore a backup, bring it up as a secondary and let it "catch up" from the primary (or another secondary acting as a propagating primary to the instance being recovered). This requires that journal files be available on the primary going back to the point from which the instance being restored needs to catch up. If such journal files are not available, recover the instance with a fresh backup from another instance.
MUPIP SET JOURNAL now accepts a NOBEFORE_IMAGE value if REPLICATION is already on, or is also specified. This operation used to trigger an error in previous versions.
Fidelity recommends users specify the desired journaling characteristics (MUPIP SET -JOURNAL=BEFORE_IMAGE or MUPIP SET -JOURNAL=NOBEFORE_IMAGE). When replication is already on, a MUPIP SET REPLICATION=ON command with no JOURNAL qualifier assumes the current journaling characteristics (which are stored in the database file header). By default GT.M sets journal operation to BEFORE_IMAGE if this command changes the replication state from OFF to ON and JOURNAL=NOBEFORE_IMAGE is not specified. This means that conservative scripting should always specify the desired journaling characteristics using the JOURNAL qualifier of the MUPIP SET command.
Backward recovery is not possible with NOBEFORE_IMAGE journaling, therefore MUPIP JOURNAL ROLLBACK with a FETCHRESYNC or RESYNC qualifier where any database targeted by the command has NOBEFORE_IMAGE journaling produces broken and lost (unreplicated) transaction files as expected but does not modify the database content.
All journal files may now contain epoch records. Set EPOCH=<interval> for a more efficient run-time with larger values of interval and more efficient ROLLBACK processing with smaller values of interval. MUPIP JOURNAL EXTRACT –DETAIL of NOBEFORE_IMAGE may now show epoch records. The default epoch interval remains unchanged at 300 seconds.[UNIX] (C9H01-002819)
A GT.CM GNP server updating a journaled database now creates properly formatted journal files. Previous versions could, in rare cases, create journal files with JNLBADRECFMT errors if another process concurrently switched journal files either because it reached the autoswitchlimit or because an operator issued an explicit MUPIP SET JOURNAL command. [UNIX] (C9H06-002865)
RLKBNOBIMG, ROLLBACK cannot proceed as database dddd has NOBEFORE_IMAGE journaling
MUPIP error: Indicates the database file dddd current uses NOBEFORE_IMAGE journaling.
Action: Reenter the command with a FETCHRESYNC or RESYNC qualifier to produce broken and lost transaction files. Without BEFORE_IMAGE journaling ROLLBACK cannot perform any database adjustment. If full ROLLBACK capability is required for future operation, enable BEFORE_IMAGE journaling for all databases in the instance.
RLBKJNLNOBIMG, Journal file jjjj has NOBEFORE_IMAGE journaling
MUPIP information: MUPIP JOURNAL ROLLBACK displays this informational message whenever it finds journal file jjjj with NOBEFORE_IMAGE journaling (DSE DUMP -FILE for the corresponding database reports "Journal Before imaging" as FALSE).
As there are no before-image records in this journal file, MUPIP JOURNAL ROLLBACK does not roll back the database. Instead, it only generates a lost-transaction file.
Action: No user action required except to confirm that this type of rollback is appropriate and expected.
RLBKLOSTTNONLY, ROLLBACK will only create a lost transaction file (database and journal files will not be modified)
MUPIP information: MUPIP JOURNAL -ROLLBACK displays this informational message at startup if it finds at least one database region with NOBEFORE_IMAGE journaling. In such a case, MUPIP JOURNAL -ROLLBACK can only create broken and lost transaction files (if appropriate) but otherwise not modify the database, journal files, or replication instance files.
Action: No user action required except to confirm that this type of rollback is appropriate and expected.
REPLJNLCLOSED, Replication in jeopardy as journaling for database file ddd. Current region seqno is xxx[XXX] and system seqno is yyy[YYY]
GT.M run-time warning: This message indicates that GT.M turned OFF journaling and switched replication from ON to WAS_ON on the specified database. Other preceding messages identify the cause (for example, lack of disk space while writing to journal file, permissions issue while auto-switching to new journal files,and so on). The message also displays the region and journal sequence numbers. From this point, replicating updates on the primary to the secondary might or might not work depending on the backlog on the primary until replication/journaling gets turned back ON.
Action:
First, correct the cause (lack of disk space, permission issues, and so on) that turned journaling OFF.
Execute the MUPIP SET REPLICATION=ON or MUPIP BACKUP REPLICATION=ON command to turn replication (and journaling) ON and switch to a new set of journal files. This command can work while processes are concurrently updating the database and causes GTM to journal subsequent updates in both the journal file and journal pool (rather than only in the journal pool as it does when replication is in the WAS_ON state).
Execute the MUPIP REPLIC -SOURCE -SHOWBACKLOG command. Note down the value of "sequence number of last transaction written to journal pool".
Execute the above command at regular intervals and note down the value of "sequence number of last transaction sent by source server."
If the "sequence number of last transaction sent by source server" is greater than "sequence number of last transaction written to journal pool", it means that the source server successfully sent all journal records during the time interval when journaling was turned OFF. In this case, no further action is required.
On the other hand, if the "sequence number of last transaction sent by source server" is less than "sequence number of last transaction written to journal pool" and reports the same value across repeated SHOWBACKLOG commands, then check the source server log file for any error messages - most likely a NOPREVLINK error from the source server. This means the source server could not locate the corresponding journal records required from the journal files to replicate a particular sequence number and therefore, it failed to synchronize the primary and secondary. In this case, take an online backup of the primary, restore it on the secondary and start the secondary with the UPDATERESYNC qualifier to synchronize the secondary with the primary.