GT.M Supplementary Information

Supplementary Information - GT.M Version 5.1-000

Legal Notice

June 14, 2006

Revision History
Revision 1.014 June 2006



                        



                        GT.M Group

                        Fidelity National Information Services, Inc.

                        2 West Liberty Boulevard, Suite 300

                        Malvern, PA  19355, 

                        United States of America

                     



                        



                        GT.M Support: +1 (610) 578-4226 

                        Switchboard: +1 (610) 296-8877 

                        Fax: +1 (484) 595-5101

                        http://www.fis-gtm.com

                        gtmsupport@fnf.com

                    

Table of Contents

Miscellaneous Information
M-Database Access
M-Other Than Database Access
Utilities-MUPIP
Utilities-Other Than MUPIP
Typographical Conventions

Return to top

Miscellaneous Information

This section details the salient information pertaining to database access, non-database access and utilities in GT.M V5.1-000. You should go through this comprehensive list before you read the information pertaining to other specific areas (listed in the subsequent sections).

Return to top

M-Database Access

  • The use of the ^%gbldef function is not supported while journaling (or replication) is enabled as it corrupts the journal file; this will be addressed in a future release. The workaround is to perform ^%gbldef actions with journaling off. (C9B03-001658)

  • Unexpected results may be encountered on using a two argument $ORDER(), where both the arguments contain global references. The workaround is to avoid global references in the second argument of any $ORDER() that has a global variable in the first argument, possibly by placing the second value in a local variable. This will be addressed in a future release. (C9B10-001744)

  • A two argument $ORDER() where the second argument contains an extrinsic function that creates or deletes a node that is proximate to the first argument may return a result that reflects the state before the change performed by the extrinsic. The workaround is to avoid extrinsic functions that operate on local or global arrays in the second argument of any $ORDER(), possibly by placing the second value in a local variable. This will be addressed in a future release. (C9B10-001765)

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

  • GT.M Journaling currently does not behave gracefully in the case when there is no room in the disk containing the journal file and might result in closing journaling for that database file. This will be addressed in a future release. (C9B11-001817)

  • 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 work around is to map locally residing globals to local files, and not to a VOLUMESET::UCI pair. [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).

  • If ^gvn1 and ^gvn2 have two different alternative collation (act) settings, MERGE ^gvn2=^gvn1 does not work correctly. The subscripts of the source global may not be transformed according to the destination collation setting before placing them in the destination global (C9E11-002663).

  • Fenced transactions using ZTSTART/ZTCOMMIT are not supported in a replicated environment. Though the primary system will successfully process the fenced transaction, the secondary system (specifically, the update process) will not recognize and process such transactions received from the primary. There are no plans to support ZTStart/ZTCommit with replication. (S9C04-002087)

  • 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 will terminate with a GTMASSERT error. Note that this restriction does not apply for 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)

Return to top

M-Other Than Database Access

  • The TSTART command arguments and post-conditionals are not reevaluated during a TRESTART, as specified by the standard. (C9B03-001662)

  • As a performance optimization, GT.M "short-circuits" boolean evaluations, bypassing strict left-to-right evaluation, once a result is determined. This behavior is invisible to the application except in the case of extrinsic functions, where execution of an extrinsic used in a boolean expression may be bypassed. To avoid short-circuit evaluation, place extrinsic functions that should always be evaluated first in the expression (where possible), or evaluate them and store the result into local variables which are then used in the boolean evaluation. (C9B04-001673)

  • A two argument $GET() where the first argument is defined and the second argument is a global reference, does not update the naked indicator to reflect the reference in the second argument. The workaround is to avoid the use of the naked reference after a $GET() with a global reference in the second argument. This will be addressed in a future release. (C9B10-001767)

  • Versions starting with V4.2-000 are unable to read responses to the "What file: " prompt on the initiating terminal when a mumps -run does not include a routine name on the command line. This will be addressed in a future release. [UNIX] (C9C04-001965)

  • In OpenVMS, error messages longer than 255 characters are truncated. This is most likely to happen with long file specifications - a possible workaround is to shorten file names and paths. This will be addressed in a future release. [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. This will be addressed in a future release. (C9C05-001988)

  • Combining a string of indirection operators with nested indirection in certain combinations does not operate in conformance with the standard; this will be addressed in a future release. The workaround is to avoid such complex constructs. (C9C05-001992)

  • In UNIX, the STARTUP jobparameter cannot currently be used as documented to define environment variables for the M process. This will be fixed 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)

  • Some errors that should cause GT.M to terminate with a fatal error may result in the process entering Direct Mode. For example, 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. (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 an error GTM-E-VARRECBLKSZ. [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. See the GT.M Null Subscripts Technical Bulletin for details on enabling standard collation for null subscripts. (C9E11-002667)

  • ZGOTO with an indirect entry reference argument (i.e. ZGOTO level:@entryref where entryref is of the form "lab^rtn") fails with an 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 doesn't truncate the object file to the maximum routine length (31 characters). This would cause any subsequent auto-ZLINK to fail locating the object file. The workaround is to precompile the long routine names explicitly by the mumps compiler 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. Usage of these fields either in the collation routines or when passed 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 WRITE will cause 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 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 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 yielded LCLMERGE(98765432109876543200) whereas the expected is 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, i.e., $GET(LCLARRAY(98765432109876543210). This will be fixed 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)

  • Direct Mode is currently very restricted in its ability to operate with M transactions. Commands entered from the prompt are not stored, and are therefore inherently not restartable. At the same time, the typical speed differential between terminal interaction and normal program flow means, if there is any possibility of concurrency conflict with a Direct Mode action, it is highly likely that an actual conflict will occur, forcing a restart attempt. In order to prevent Direct Mode activity from affecting other work, a process always releases any critical sections when entering Direct Mode. This means an M transaction that includes Direct Mode action, may be subject to unbounded restarts. Because of this current limitation of Direct Mode with respect to transaction processing, fixes to other known problems in this area have been deferred. (S9911-001425)

  • Suspending a running GT.M process (on UNIX) with ^Z is not recommended. While GT.M will try to not go to sleep while certain resources are held, GT.M cannot always easily determine these resources as there are many possible types that can cause other GT.M processes to hang while waiting for them. Future versions of GT.M will contain better resource management (tracking) to alleviate this limitation and not allow the suspension while potential hang inducing resources are being held. [UNIX] (S9C09-002229)

  • Usage of GT.M call-ins may retain the terminal characteristics that are changed within call-ins instead of restoring the settings to the values before invocation. This may cause annoying terminal behavior by the invoking shell following GT.M call-ins. A workaround is to reset the settings to some reasonable values with the shell command "stty sane" after each call-in invocation. [UNIX] ((S9F01-002524)

  • The pattern match operator may cause a process to hang if the pattern following the question-mark (?) is a string literal with more than 6 characters long and the repitition count consists of a period (.) with no leading and trailing integer literals. An example of such a case is 'write var?."ABCDEFG"'. Until this issue is resolved, either restrict the pattern upto 6 characters long or use a large value for the trailing integer in the repitition count range (S9F01-002526).

  • JOB command fails to compile if the actual list contains a null expression (for example, JOB ^rtn(1,,3)). Until this issue is fixed, either avoid passing null expressions to the JOB command or provide a dummy argument. Since GT.M allows less number of actuals than the formals provided all missing actuals correspond to the end of the formal list, a workaround is to rearrange the formal slist 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 reporting "Resource temporarily unavailable". This error leaves the internal state of the device in such a state that would in turn cause any following READs (timed or not) to fail with the same error. [UNIX] (S9F04-002544).

  • 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().

    [Note]

    With standard null collation there is no such limitation. Except for existing applications, Fidelity strongly recommends the use of standard null collation if there is data with null subscripts.

  • Since GT.M is a compiler, and since M requires code to be dynamically compiled and executed, GT.M needs to be able to execute code in a process' heap/stack space. Since this is not a requirement of normal C/C++ programs, and since 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. If you 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)

    You should look for a security configuration setting that prevents a GT.M process from executing code in heap/stack space. One example of an implementation of such a feature is exec-shield on some distributions of GNU/Linux.

    You can determine whether exec-shield is operating by examining the files /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, you may need to set it to 0:

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

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

Return to top

Utilities-MUPIP

  • MUPIP JOURNAL RECOVER/ROLLBACK -BACKWARD may leave a database with KILL_IN_PROG and "GTM-E-DBMRKBUSY, Block incorrectly marked busy" errors; this will be addressed in a future release. These errors should be corrected as soon as reasonably possible, but, as discussed in the documentation, are benign as long as they are the only integ errors in the database. (C9902-000863)

  • Replication filters are not yet supported; this will be addressed in a future release. [OpenVMS] (C9B04-001674)

  • Certain MUPIP commands cannot handle arguments containing a dash (-); this will be addressed in a future release. The workaround is to avoid choosing names that include a dash for GT.M objects. [UNIX] (C9B04-001681)

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

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

  • MUPIP EXTRACT fails to extract globals residing on a local node if the next global in collation sequence resides on a remote node; this will be addressed in a future release. The workaround is, when doing an extract; use a global directory that omits remote globals. (C9B11-001834)

  • The first step in restoring a journaled database after a crash should be to perform a MUPIP RECOVER or ROLLBACK. Care should be taken not to 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 this ordering is not strictly enforced by GT.M. This will be addressed 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. This will be addressed in a future release. The workaround is to avoid using MUPIP INTRPT on any given process except at measured intervals - even a second should be adequate 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 (e.g. 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)

  • Currently FENCE=ALWAYS may work incorrectly when multiple regions are involved. This will be fixed in a future release. (C9C06-002025)

  • MUPIP RECOVER/ROLLBACK relies on the continuity of time stored in the journal records in order to maintain application consistency across multi-region fenced transactions. It might work incorrectly if the system clock is adjusted by "stepping" while journaling is turned ON. The adjustment includes manual as well as automated adjustments done by a time synchronization utility running in the background (for example, gradual adjustments made to the clock by a Network Time Protocol client running on the GT.M machine). Fidelity strongly recommends the use of "slewing" rather than stepping to make adjustments to the system clock. If the clock must be adjusted backwards by stepping on a system that has a journaled database, it has to be done with caution using the following procedure. (C9D06-002282)

    • Note down current system time

    • Switch to new journal files using MUPIP SET JOURNAL -REG "*"

    • Adjust system time

    • Switch to new journal files using MUPIP SET JOURNAL -REG "*"

    • If the new system time is prior to the noted down system time (that is, the time adjustment 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).

  • MUPIP EXTRACT of a database in binary format 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. [OpenVMS] (C9D06-002295)

  • 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 and 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), this might cause a MUPIP JOURNAL ROLLBACK and/or RECOVER /BACKWARD on this database to error out since they 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. This will be addressed in a future release. (C9E03-002536)

  • Files created by MUPIP EXTRACT /FORMAT=ZWR (or /FORMAT=GO) since V4.4-002 may have a maximum record size of 65,535 which may cause problems if used by some other programs and OpenVMS utilities. To work around this problem, issue the following DCL command:

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

    where "<longest record length>" is replaced with the appropriate value from a DIRECTORY/FULL of the file (i.e. 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. This will be addressed in a future release. [OpenVMS] (S9C07-002161)

Return to top

Utilities-Other Than MUPIP

  • The executable images for utility programs: DSE, LKE and MUPIP are large and will be reduced in a future release. (C9C05-001990)

  • LKE operations on LOCKs mapped to regions served by GT.CM are not supported. LKE still operates on LOCKs that exist on the local node even if they are held by a remote process through a GT.CM server. (C9C05-001991)

Return to top

Typographical Conventions

Command Syntax: UNIX syntax (i.e., lowercase text and "-" for flags/qualifiers) is used throughout this document. VMS accepts both lowercase and uppercase text; flags/qualifiers 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 appears in brackets [ ].

Return to top

For more information, see the GT.M web site.