GT.M Supplementary Information

Using the ^%gbldef function while journaling (or database replication) is in progress can corrupt the journal file. The workaround is to turn off journaling and then perform ^%gbldef actions. The GT.M team will address this in a future release. (C9B03-001658)

During a TRESTART, GT.M does not reevaluate the TSTART command arguments and post-conditionals (M standard specifies otherwise). (C9B03-001662)

GT.M currently treats all segments whose file specification is of the form VOLUMESET::UCI (access method USER) as remote DDP segments, even if the VOLUMESET is served by the GT.CM DDP server running on the local node. A GT.M client access to a global residing in such a VOLUMESET generates GTM-E-NOCONNECT error. The workaround is to map locally residing globals to local files, and not to a VOLUMESET::UCI pair. FIS has no plans to change this behavior. [OpenVMS] (C9C08-002109)

TSTART may abnormally terminate the process if there are more than 4 variables specified in the list of preserved locals. [OpenVMS] (C9E11-002656)

MERGE ^gvn2=^gvn1 does not work correctly if ^gvn1 and ^gvn2 have two different alternative collation (act) settings, The subscripts of the source global may not be transformed according to the destination collation setting before placing them in the destination global. The workaround is to set up a loop to sequence through the global nodes in ^gvn1 and copy each in turn to ^gvn2. (C9E11-002663)

GT.M does not replicate the fences associated with transaction marked with ZTSTART/ZTCOMMIT instead of the preferred TSTART/TCOMMIT. A primary system recognizes/processes the transaction but its secondary system (specifically, the update process) sees a series of single global variable updates and fails to recognize/process them as a transaction. FIS has no plans to support ZTSTART/ZTCOMMIT in a replicated database environment. (S9C04-002087)

GT.M short-circuits (bypasses) strict left-to-right Boolean evaluation in order to optimize database performance. This behavior remains invisible to an application unless the Boolean evaluation uses an extrinsic function. To get around this short-circuit behavior, place extrinsic functions first in the expression (where possible). Alternatively, store the result of such extrinsic functions in local variables and then use those local variables in the Boolean evaluation. (C9B04-001673)

An intrinsic function that contains extrinsic functions in its arguments that pass a local variable name by reference, and the local variable or its descendants are used in other arguments (of the intrinsic function), may not evaluate according to the standard. The workaround is to avoid extrinsic functions that pass by reference arguments embedded in intrinsic functions. (C9B10-001766)

All versions of GT.M starting from V4.2-000 and after are unable to read the response to the "What file: " prompt on the initiating terminal when a mumps -run does not include a routine name on the command line. The workaround is to specify the routine name as an argument to the original command. The GT.M team will address this in a future release. [UNIX] (C9C04-001965)

In OpenVMS, GT.M truncates all error messages that are longer than 255 characters. This is most likely to happen with long file specifications - a workaround is to shorten file names and paths. [OpenVMS] (C9C04-001974)

For SOCKET devices, certain attributes (WIDTH, LENGTH, [NO]WRAP, EXCEPTION, FILTER, IPCHSET, OPCHSET) and certain status information ($KEY, $DEVICE, $X, $Y, $ZEOF, $ZA, $ZB) apply to the device and are inappropriately shared if there are multiple sockets associated with the device. The GT.M team will address this in a future release. (C9C05-001988)

A construct of a string of indirection operators and nested indirection in certain combinations does not operate in conformance with the M standard. The workaround is to avoid such complex constructs. The GT.M team will address this in a future release. (C9C05-001992)

In UNIX, the STARTUP jobparameter cannot define environment variables for the M process (GT.M documentation specifies otherwise). The GT.M team will address this in a future release. [UNIX] (C9C07-002091)

Attempts to remove the stack level immediately above a Direct Mode frame with a QUIT may not work. The workaround is to use ZGOTO in these cases. (C9C11-002180)

A GTM-E-STACKCRIT error while executing $ZTRAP leaves GT.M in direct mode. In general, such errors in $ZTRAP should cause GT.M to terminate instead of entering direct mode. Error trapping with $ETRAP ensures that the process does not unintentionally enter direct mode. FIS strongly recommends that $ZTRAP code detect the STACKCRIT error and terminate the process or take corrective action such as a suitable ZGOTO.(C9C11-002181)

If a second error occurs after an error that occurred while $ETRAP was in effect and before resetting $ECODE, GT.M always removes a stack level, as described by the standard. In a future release, if $ZTRAP is in effect at the level, GT.M will use $ZTRAP behavior, which does not implicitly remove a stack level. This will create more choices for designers, and make integration and conversion between $ZTRAP and $ETRAP easier to manage. (C9C11-002183)

TRUNCATE deviceparameter with USE command does not work correctly. It prints spurious NULL (\000) characters before the first line it prints. [Linux] (C9E02-002513).

If there is an error while closing a file once, a subsequent OPEN of the same file by the same GT.M process fails with the GTM-E-VARRECBLKSZ error. [OpenVMS] (C9E02-002521)

If a Terminal I/O device has WRAP enabled, the WRITE may not reset $Y to 0 for a single line that wraps even if $Y reaches the virtual page size (i.e. LENGTH deviceparameter) of the terminal. [UNIX] (C9E02-002526)

$QUERY() on global variables using the default GT.M null subscript collation does not work if the last subscript specified in the global variable is a null subscript. This problem exists only when the default GT.M collation is used for the null subscript which collates between numeric and string subscripts. The workaround is to use the standard collation for the null subscript which collates before all other subscripts. With GT.M null collation a process cannot sequence from nodes with numeric subscripts through a node with null subscripts to nodes with string subscripts using $ORDER(), $ZPREVIOUS(). See the GT.M Null Subscripts Technical Bulletin for details on enabling standard collation for null subscripts. (C9E11-002667)

	With standard null collation there is no such limitation. Except for existing applications which rely on older GT.M behavior, FIS strongly recommends the use of standard null collation if there is data with null subscripts.

ZGOTO with an indirect entry reference argument (i.e. ZGOTO level:@entryref where entryref is of the form "lab^rtn") fails with a LABELMISSING error even if the label is available in the specified routine. (C9E11-002669)

If a routine of more than 31 characters long is auto-compiled by auto-ZLINK or ZLINK, GT.M does not truncate the object file name to the maximum routine length (31 characters). This behavior causes any subsequent auto-ZLINK to fail locating the object file. The workaround is to compile the routines with long names explicitly with the mumps command before auto-ZLINK attempts to compile. (C9E12-002678)

The 64-bit descriptors passed to the user-defined alternate collation routines gtm_ac_xform_1()/gtm_ac_xback_1() may contain incorrect values for dsc64$w_mbo and dsc64$l_mbmo fields. Using these fields in the collation routines or passing to the system routines may result in unpredictable behavior. [OpenVMS] (C9F02-002701)

For a SOCKET device, if DELIMITER device parameter is specified (say in the OPEN command, or a USE command) and later in a USE command if NODELIMITER is specified, and WRAP is enabled for the device (default), GT.M may write invalid characters on the output socket pipe when exactly WIDTH (or an exact multiple of WIDTH) number of characters have been written already, and the next character is output. (C9F03-002711)

For example:

O NIO:(CONNECT=IP_":"_SOCK_":TCP":ATTACH="client",DELIMITER=$C(13,10)):TO:"SOCKET" 
U NIO:(WIDTH=80:NODELIMITER) ; WIDTH set to 80 and delimiter turned off 
WRITE $J("A",80) ; exactly WIDTH characters written 
WRITE "A" ; this WRITE might output invalid characters on the socket pipe NIO 

The workaround is to WRITE # every WIDTH characters.

On OpenVMS, for a SOCKET device, if WRAP is enabled for the device (default), and NODELIMITER is specified, or DELIMITER is not specified in the OPEN or USE command, GT.M incorrectly issues an error when exactly WIDTH (or an exact multiple of WIDTH) number of characters have been written already, and the next character is output.

For example:

O NIO:(CONNECT=IP_":"_SOCK_":TCP":ATTACH="client"):TO:"SOCKET" 
U NIO:(WIDTH=80:IOERROR="TRAP") 
WRITE $J("A",80) ; exactly WIDTH characters written 
WRITE "A" ; this WRITE will fail with an error
			; %GTM-E-SOCKWRITE, Write to a TCP/IP socket failed 
			; -GTM-I-TEXT, invalid argument 

After this error is issued, every subsequent WRITE causes the same error, and so, nothing is sent to the process waiting at the other end of the socket pipe.

The workaround is to WRITE # every WIDTH characters.[OpenVMS]

GT.M implements numerics to 18 significant digits. A non-canonical number of more than 18 significant digits is treated as a string. A canonical number is truncated at 18 significant digits. The following example illustrates the condition where GT.M does not adhere to these rules. (S9F03-002537)

D9F03002537     ; program that demonstrates issues with long integer subscripts
        NEW LCLARRAY,NUMSUBS,LNGSUBS,STRSUBS,GBLSUBS,LCLSUBS,LCLMERGE,$ZTRAP
        SET $ZTRAP="GOTO ERROR"
        KILL ^GBLARRAY,^GBLMERGE
        SET NUMSUBS=1
        SET LNGSUBS="98765432109876543210"
        SET STRSUBS="string"
        SET (^GBLARRAY(NUMSUBS),LCLARRAY(NUMSUBS))=1
        SET (^GBLARRAY(LNGSUBS),LCLARRAY(LNGSUBS))=2
        SET (^GBLARRAY(STRSUBS),LCLARRAY(STRSUBS))=3
        ;
        MERGE ^GBLMERGE=^GBLARRAY
        WRITE !,"ZWRITE ^GBLMERGE",!
        ZWRITE ^GBLMERGE
        ;
        MERGE LCLMERGE=^GBLARRAY
        WRITE !,"ZWRITE LCLMERGE",!
        ZWRITE LCLMERGE
        ;
        WRITE !,"GBLOAL ORDER LOOP",!
        SET GBLSUBS=""
        FOR  SET GBLSUBS=$O(^GBLARRAY(GBLSUBS)) Q:GBLSUBS=""  DO
        . WRITE "^GBLARRAY(",GBLSUBS,")=",^GBLARRAY(GBLSUBS),!
        ;
        WRITE !,"LOCAL ORDER LOOP",!
        SET LCLSUBS=""
        FOR  SET LCLSUBS=$O(LCLARRAY(LCLSUBS)) Q:LCLSUBS=""  DO
        . WRITE "LCLARRAY(",LCLSUBS,")=",LCLARRAY(LCLSUBS),!
        ;
        WRITE !,"LOCAL ORDER LOOP WITH WORKAROUND $GET()",!
        SET LCLSUBS=""
        FOR  SET LCLSUBS=$O(LCLARRAY(LCLSUBS)) Q:LCLSUBS=""  DO
        . WRITE "LCLARRAY(",LCLSUBS,")=",$GET(LCLARRAY(LCLSUBS)),!
        QUIT
        ;
ERROR
        WRITE !,"ERROR: ",$ZSTATUS,!
        QUIT

The output of the above code snippet is as follows:

ZWRITE ^GBLMERGE
^GBLMERGE(1)=1
^GBLMERGE("98765432109876543210")=2
^GBLMERGE("string")=3

ZWRITE LCLMERGE
LCLMERGE(1)=1
LCLMERGE(98765432109876543200)=2
LCLMERGE("string")=3

GBLOAL ORDER LOOP
^GBLARRAY(1)=1
^GBLARRAY(98765432109876543210)=2
^GBLARRAY(string)=3

LOCAL ORDER LOOP
LCLARRAY(1)=1
LCLARRAY(98765432109876543210)=

ERROR: 150373850,D9F03002537+27^D9F03002537,%GTM-E-UNDEF, Undefined local variable: LCLARRAY(98765432109876543210)
LCLARRAY(string)=3

LOCAL ORDER LOOP WITH WORKAROUND $GET()
LCLARRAY(1)=1
LCLARRAY(98765432109876543210)=2
LCLARRAY(string)=3

Notice that the MERGE operation into LCLMERGE incorrectly yields LCLMERGE(98765432109876543200) whereas the expected result was LCLMERGE("98765432109876543210"). The workaround is to use a GLOBAL for target of MERGE operation when long non-canonical numbers subscripts exist.

Also notice the error in the LOCAL ORDER LOOP where LCLARRAY(98765432109876543210) is incorrectly declared undefined although it defined. The workaround is to use $GET to access the value, that is, $GET(LCLARRAY(98765432109876543210). The GT.M team will address this in a in a future release.

ZLINK or ZPRINT of a routine with a ZGOTO explicitly referring to the same routine fails. The workaround is to use only the label in the ZGOTO argument, and leave the routine implicit. (S9606-000216)

In order to prevent Direct Mode activity from affecting other processes, a process always releases any critical sections at the time of entering the Direct Mode. This means that an M transaction that includes Direct Mode action, may be subject to unbounded restarts. FIS strongly recommends not including any direct mode - or indeed any human interaction - inside a transaction. (S9911-001425)]

FIS strongly recommends that you avoid suspending a running GT.M process (on Unix) with <CTRL>Z or by sending a SUSPEND signal. Suspending a process that includes the run time of a realtime database engine may result in a database hang if the suspended process holds a critical section. You can redefine ^Z in the shell to avoid sending a SUSPEND. [UNIX] (S9C09-002229)

GT.M does not compile a routine containing more than 4096 [AIX, HPUX, Tru64 Unix, OpenVMS] or 16384 [Linux, Solaris] unique local variable names. If a routine contains more local names than this limit, GT.M terminates with a GTMASSERT error. Note that this restriction does not apply to local variable names used in indirection code. The workaround is to break the large routine into the several smaller routines containing fewer local names or use indirection. (S9E11-002507)

For the a terminal Principal device ($PRINCIPAL), GT.M works with the terminal characteristics or settings in place when it’s invoked, changes terminal settings as specified by deviceparameters on USE commands, and leaves the terminal in its then current state when GT.M terminates. If invoking code and GT.M need different terminal characteristics, they must be explicitly managed by some combination of USE commands and code in the invoking program or script. For example in UNIX, an invoking script might use the "stty sane" command after a GT.M invocation. (S9F01-002524)

JOB command fails to compile if the actual list contains a null expression (for example, JOB ^rtn(1,,3)). The GT.M team will address this in a future release. The workaround is to avoid passing null expressions to the JOB command or provide a dummy argument. Since GT.M allows fewer actual parameters than the formal parameters provided all missing actuals correspond to the end of the formal list, a workaround is to rearrange the formallist such that the optional parameters are at the end. (S9F03-002532)

READ from a FIFO device with 0 timeout may fail with an unexpected system error that reports "Resource temporarily unavailable". This error leaves the device in a state that causes any subsequent READs (timed or not) to fail with the same error. The workaround is to use a trivial (insignificant) timeout to read from a FIFO device. For example, READ a:.1 sets the timeout for the READ command to 100 ms. [UNIX] (S9F04-002544)

GT.M needs to be able to execute code in a process' heap/stack space because GT.M is a compiler and M requires code that is able to dynamically compile and execute. As this is not a requirement of typical C/C++ programs, and one of the precepts of good security is to grant no privileges save those that are required, it is increasingly common for default security settings to disable the ability of a process to execute code from heap/stack space.

Different operating systems have different ways to configure this security setting, and there can be multiple ways to configure this functionality on any given operating system. Users may experience unexpected Signal 11 (segmentation violation) errors such as:

%GTM-F-KILLBYSIGSINFO1, GT.M process 23914 has been killed by a signal 11 at address 0x092C57D0 (vaddr 0x092C57D0)

Identify the security configuration setting that prevents GT.M processes from executing code in heap/stack space and configure it to allow GT.M processes to do so. One example of an implementation of such a feature is exec-shield on some distributions of GNU/Linux.

Users must examine the following files to determine the status of exec-shield:

/proc/sys/kernel/exec-shield and /proc/sys/kernel/exec-shield-randomize
cat /proc/sys/kernel/exec-shield
cat /proc/sys/kernel/exec-shield-randomize

If either value is non-zero, users may need to set it to 0:

echo 0 >/proc/sys/kernel/exec-shield 
echo 0 >/proc/sys/kernel/exec-shield-randomize

Using ZGOTO 0:entryref can corrupt the invocation stack level and trigger a segmentation fault (SIG-11). An example for such a case is:

zg0entryref1    SET i=$g(i)+1 WRITE " ",i ZGOTO 0:zg0entryref1+1^zg0entryref1
                .QUIT

The workaround is to ensure that the stack frame nesting level of the entryref to which ZGOTO transfers control is not 0 or if the intention is to terminate GT.M so that there is no entryref. The GT.M team will address this in a future release. (C9H04-002845)

Using ZMESSAGE with arguments outside the range of messages defined by GT.M can simulate operating system conditions that terminate the process. (C9A10-001605)

MUPIP JOURNAL RECOVER/ROLLBACK -BACKWARD may leave a database with KILL_IN_PROG and "GTM-E-DBMRKBUSY, Block incorrectly marked busy" errors. The GT.M team will address this in a future release. Even though users must address these errors as soon as reasonably possible, these errors are benign as long as they are the only integ errors in the database (as discussed in the GT.M User documentation). (C9902-000863)

Replication filters are not supported on OpenVMS. (C9B04-001674) [OpenVMS]

When the disk space is too low for recover/rollback to operate, recover/rollback may terminate abnormally. (C9B09-001758)

Replication instance definition on OpenVMS uses a global directory, rather than a replication instance file. (C9B11-001785) [OpenVMS]

If there is no space left in the disk where a journal file resides, GT.M will stop journaling for that database. If that database is part of a replicated instance, GT.M also turns replication off. Depending on the circumstances, recovery may involve recreating secondary instances that replicate from that instance. Please ensure that there is always adequate space on devices where journal files are written. (C9B11-001817)

MUPIP EXTRACT fails to extract globals residing on a local node if the next global in collation sequence resides on a remote node. The GT.M team will address this in a future release. The workaround is to use a global directory that omits remote globals before performing MUPIP EXTRACT operations. (C9B11-001834)

Always perform a MUPIP RECOVER or ROLLBACK as the first step to restore a journaled database after a crash. Never start GT.M updates or use MUPIP SET -JOURNAL before the recovery, as this affects subsequent recover or rollbacks and prevents them from being successful. Currently GT.M does not strictly enforce this order of steps. The GT.M team will address this in a future release. (C9C01-001892)

MUPIP INTRPT commands initiated while the target process is already handling an interrupt can cause failure of the target process. The workaround is to avoid using MUPIP INTRPT on any given process too soon after the previous MUPIP INTRPT - a delay of a second is ample in most environments. [OpenVMS] (C9C04-001970)

If the logical names SYS$OUTPUT and/or SYS$ERROR are redefined to a file with a DEFINE /USER command, certain utility commands (for example. MUPIP JOURNAL /SHOW, MUPIP BACKUP, DSE) on a journaled database terminate with a RMS-E-FLK error. The workaround is to use a script that runs only the utility command. The script then can perform, in the beginning, a DEFINE SYS$OUTPUT and DEFINE SYS$ERROR without the /USER qualifier. [OpenVMS] (C9C05-001984)

FENCE=ALWAYS may work incorrectly when multiple regions are involved. FIS recommends M standard transaction processing rather than the less capable ZTSTART/ZTCOMMIT approach. (C9C06-002025)

GT.M relies on the monotonic increase of time stored in the journal records to maintain application consistency across multi-region fenced transactions. If the time stamp in later journal records states an earlier time than the time stamp in earlier journal records, GT.M database recovery after a crash may be complicated and even compromised.

When adjusting the system clock to maintain the correct time, Fidelity strongly recommends "slewing" it rather than "stepping" it. Standard packages such as NTP provide this capability.

On UNIX/Linux systems, the system clock is traditionally set to UTC, and therefore the transition from Daylight Savings Time to Standard Time does not involve stepping the clock, and the transition is transparent to GT.M on such systems.

On systems where the system clock is set to local time (which includes OpenVMS systems as well as those UNIX/Linux systems where the clock is not set to UTC), stepping the clock backwards is required when changing from Daylight Saving Time to Standard Time. Sometimes when the system clock has drifted so far that slewing it back to the right time will take too long, it may be necessary to step system time.

Use the procedure below when you need to step the time backwards.

Whenever the new system time is prior to the noted down system time (that is, the time step was negative), then all future MUPIP RECOVER commands that use time qualifiers, which fall in the time range of adjustment need to use a time that is either less than the start time (for SINCE and AFTER qualifiers), or greater than the end time of the time range (for BEFORE qualifiers). In other words, possible recovery time options should never reference a time that’s ambiguous because of the time change, but rather one that’s either before any “overlapping time” or after the change. This includes the time in the journal files created by the first command in the instructions, but may include earlier times as well.(C9D06-002282)

MUPIP EXTRACT of a database in binary format on OpenVMS fails when database block sizes are over 32,765. In addition, MUPIP JOURNAL EXTRACT or MUPIP EXTRACT in ZWR or GO format terminates if they produce a record larger than 32,767 bytes, including the record header and terminators. This is due to OpenVMS RMS' limitation of 32767 bytes for the maximum record size of a sequential file. FIS recommends that you use a database block size of 32254 (the largest legal block size smaller than 32768) on OpenVMS to use this functionality. (C9D06-002295) [OpenVMS]

If the duplicate set optimization (see Release Notes for GT.M V4.4-004 for C9D12-002472) is enabled and if the update pattern is such that the last update in a sequence of updates is a duplicate-set and there are no more updates for quite a while although the updating processes are still attached to the database, it is possible that the database file header does not get flushed in a timely manner. In this case, if before-image journaling is turned ON, it is also possible that EPOCHs are not written to disk in a timely manner. If the processes attached to the database are then killed abnormally due to a system crash or using a kill -9 (Unix) or STOP/ID (OpenVMS), then a MUPIP JOURNAL ROLLBACK and/or RECOVER /BACKWARD on the same database triggers an error out as these commands rely on EPOCHs being written in a timely manner. The workaround is to issue a backward recovery with a /SINCE_TIME that matches the time of last update to this database or a rollback with a /RESYNC_SEQNO that matches the last update to this database. The GT.M team will address this in a future release. (C9E03-002536)

In GT.M versions starting from V4.4-002, the files that are created as a result of MUPIP EXTRACT /FORMAT=ZWR (or /FORMAT=GO) command has a maximum record size of 65,535 which may cause problems if other programs and OpenVMS utilities use them. To resolve this, issue the following DCL command:

set file/attribute=mrs=<ongest record length> file.glo

where "<longest record length>" is the appropriate value from a DIRECTORY/FULL of the file (file.glo above.) [OpenVMS] (C9E03-002549)

A file specification for the -LOG qualifier containing semicolon (;), or a version number causes the replication server to issue an RMS file specification error. (S9C07-002161) [OpenVMS]

If a process containing a HANG command is frequently interrupted by MUPIP INTRPT and the length of that HANG exceeds the period of the interrupt, the HANG command will never complete as it is restarted in its entirely when it is resumed after the process responds to the interrupt. The same is applicable to timeout on locks. Any timeout except READ SOCKET and READ TERMINAL reset when a RETURN from $ZINTERRUPT restarts the command.

In a future release, the GT.M team will reduce the size of the executable images for utility programs: DSE, LKE and MUPIP. (C9C05-001990)

GT.M does not support LKE operations on LOCKs that are mapped to regions served by GT.CM. LKE still operates on LOCKs that exist on the local node even if a remote process through a GT.CM server holds them . The solution is to use LKE on the node which is processing the LOCK. (C9C05-001991)