Environment Variables

A comprehensive list of environment variables that are directly or indirectly used by GT.M follows:

EDITOR is a standard system environment variable that specifies the full path to the editor to be invoked by GT.M in response to the ZEDit command (defaults to vi, if $EDITOR is not set).

GTMCI specifies the call-in table for function calls from C code to M code.

GTMXC_gpgagent specifies the location of gpgagent.tab. By default, GT.M places gpgagent.tab in the $gtm_dist/plugin/ directory. GTMXC_gpgagent is used by pinentry-gtm.sh and is meaningful only if you are using Gnu Privacy Guard version 2.

LC_CTYPE is a standard system environment variable used to specify a locale. When $gtm_chset has the value "UTF-8", $LC_CTYPE must specify a UTF-8 locale (e.g., "en_US.utf8").

LC_ALL is a standard system environment variable used to select a locale with UTF-8 support. LC_ALL is an alternative to LC_TYPE, which overrides LC_TYPE and has a more pervasive effect on other aspects of the environment beyond GT.M.

LD_LIBRARY_PATH (LIBPATH on AIX) is a standard system environment variable used to modify the default library search path. Use this extension when GT.M relies on custom compiled libraries that do not reside in the default library search path. For example ICU, GPG, OpenSSL and/or zlib libraries.

TZ is a standard system environment variable that specifies the timezone to be used by a GT.M process, if they are not to use the default system timezone. GT.M uses the system clock for journal time stamps on the assumption it reflects UTC time.

gtmcompile specifies the initial value of the $ZCOmpile ISV. The SET command can alter the value of $ZCOMPILE in an active process.

gtmcrypt_config specifies the location of the configuration file required for database encryption, Sequential file, PIPE, and FIFO device encryption and/or TLS support. A configuration file is divided into two sections: database and TLS. The "database" section contains a list of database files and their corresponding key files. You do not need to add a database section if you are not using an encrypted database, or a "tls" section if you are not using TLS for replication or sockets. The tls section provides information needed for OpenSSL (in the reference plugin implementation) or other encryption package, such as the location of root certification authority certificate in PEM format and leaf-level certificates with their corresponding private key files. Note that the use of the gtmcrypt_config environment variable requires prior installation of the libconfig package.

gtmcrypt_FIPS specifies whether the plugin reference implementation should attempt to use either OpenSSL or Libgcrypt to provide database encryption that complies with FIPS 140-2. When the environment variable $gtmcrypt_FIPS is set to 1 (or evaluates to a non-zero integer, or any case-independent string or leading substring of "TRUE" or "YES"), the plugin reference implementation attempts to use libgcrypt (from GnuPG) and libcrypto (OpenSSL) in "FIPS mode." Note that to comply with FIPS 140-2 you should be knowledgeable with that standard and take many steps beyond setting this environment variable. By default GT.M does not enforce "FIPS mode."

gtmgbldir specifies the initial value of the $ZGBLDIR ISV. $ZGBLDIR identifies the global directory. A global directory maps global variables to physical database files, and is required to access M global variables. Users who maintain multiple global directories use this environment variable to conveniently choose one to use from the time of process startup. To automate this definition, define gtmgbldir in the user's login file. The SET command can alter the value of $ZGBLDIR in an active process.

gtmroutines specifies the initial value of the $ZROutines ISV, which specifies where to find object and source code. The SET command can alter the value of $ZROUTINES in an active process.

gtmtls_passwd_<label> specifies the obfuscated password of the encrypted private key pair. You can obfuscate passwords using the 'maskpass' utility provided along with the encryption plugin. If you choose to use unencrypted private keys, set the gtmtls_passwd_<label> environment variable to a non-null dummy value; this prevents inappropriate prompting for a password.

gtmver (not used by GT.M directly) - The current GT.M version. The gtmprofile script uses $gtmver to set other environment variables.

gtm_aio_nr_events: For Linux x86_64, the gtm_aio_nr_events environment variable controls the number of structures a process has per global directory to manage asynchronous writes, and therefore determines the number of concurrent writes a process can manage across all regions within a global directory. If not specified, the value controlled by gtm_aio_nr_events defaults to 128. If a process encounters a situation where it needs to perform an asynchronous write, but has no available slots with which to manage an additional one, it either falls back to synchronous writing if the write is blocking other actions, and otherwise defers the write until a slot becomes available as other writes complete. Linux allocates the structures on a system-wide basis with the setting of /proc/sys/fs/aio-max-nr. Therefore you should configure this parameter to account for the needs (as determined by gtm_aio_nr_events or the default) of all processes using asynchronous I/O. When processes use multiple global directories with asynchronous I/O, their need for the system resources increases accordingly. For example, if an environment runs 10,000 processes each of which open two global directories and /proc/sys/fs/aio-max-nr is set to a value of 200,000 then gtm_aio_nr_events needs to be set to a value <= 200,000 / (10,000 * 2) = 10. Conversely if gtm_aio_nr_events is set to a value of 20, then aio-max-nr needs to be bumped up to (10,000 * 2 * 20) = 400,000. GT.M captures the number of errors encountered when attempting to write database blocks for a region, and, barring problems with the storage subsystem, hitting an asynchronous write limit would constitute primary (probably only) contribution to that value, which you can access with $$^%PEEKBYNAME("sgmnt_data.wcs_wterror_invoked_cntr",<region>)

gtm_autorelink_ctlmax specifies the maximum number of entries for unique routine names in the relink control file created by a process for any directory, with a minimum of 1,000, a maximum of 16,000,000 and a default of 50,000 if unspecified. If a specified value is above or below the allowed range, the process logs the errors ARCTLMAXHIGH or ARCTLMAXLOW respectively in the syslog, and uses the nearest acceptable limit instead. MUPIP RCTLDUMP and ZSHOW "A" outputs include the maximum number of unique routine names available in a relink control file.

gtm_autorelink_keeprtn:

When gtm_autorelink_keeprtn is set to 1, t[rue], or y[es] , exiting processes leave auto-relinked routines in shared memory. When the environment variable gtm_autorelink_keeprtn is undefined, 0, f[alse] or n[o], exiting processes purge auto-relinked routines in shared memory if no other processes are using them. Regardless of the value of gtm_autorelink_keeprtn, the Operating System removes an auto-relink shared memory repository when there are no processes accessing it.

All values are case-independent. When gtm_autorelink_keeprtn is defined and TRUE:

gtm_autorelink_shm specifies the size (in MiB) of an initial Rtnobj shared memory segment used by the auto-relink facility. If the value of gtm_autorelink_shm is not a power of two, GT.M rounds the value to the next higher integer power of two. If the first object (.o) file does not fit in a new Rtnobj segment, GT.M rounds the allocation up to the smallest integer power of two required to make it fit. When GT.M needs room for object files, and existing Rtnobj segments have insufficient free space, it creates an additional shared memory segment, double the size of the last. Note that when hugepages are enabled, the actual Rtnobj shared memory size might be more than that requested implicitly or explicitly through $gtm_autorelink_shm.

gtm_badchar specifies the initial setting that determines whether GT.M should raise an error when it encounters an illegal UTF-8 character sequence. This setting can be changed with a VIEW "[NO]BADCHAR" command, and is ignored for I/O processing and in M mode.

gtm_baktmpdir specifies the directory where mupip backup creates temporary files. If $gtm_baktmpdir is not defined, GT.M currently uses the deprecated $GTM_BAKTMPDIR environment variable if defined, and otherwise uses /tmp. All processes performing updates during an online IBACKUP must have the use the same directory and have write access to it.

gtm_boolean specifies the initial setting that determines how GT.M compiles Boolean expression evaluation (expressions evaluated as a logical TRUE or FALSE). If gtm_boolean is undefined or evaluates to an integer zero (0), GT.M behaves as it would after a VIEW "NOFULL_BOOLEAN" and compiles such that it stops evaluating a Boolean expression as soon as it establishes a definitive result . Note that:

gtm_chset determines the mode in which GT.M compiles and operates. If it has a value of "UTF-8" GT.M assumes that strings are encoded in UTF-8. In response to a value of "M" (or indeed anything other than "UTF-8"), GT.M treats all 256 combinations of the 8 bits in a byte as a single character.

gtm_chset_locale (z/OS only) specifies the locale for UTF-8 operations on z/OS.

gtm_collate_n specifies the shared library holding an alternative sequencing routine when using non-M standard (ASCII) collation. The syntax is gtm_collate_n=pathname where n is an integer from 1 to 255 that identifies the collation sequence, and pathname identifies the shared library containing the routines for that collation sequence.

gtm_crypt_plugin: If the environment variable gtm_crypt_plugin is defined and provides the path to a shared library relative to $gtm_dist/plugin, GT.M uses $gtm_dist/plugin/$gtm_crypt_plugin as the shared library providing the plugin. If $gtm_crypt_plugin is not defined, GT.M expects $gtm_dist/plugin/libgtmcrypt.so to be a symbolic link to a shared library providing the plugin. The expected name of the actual shared library is libgtmcrypt_cryptlib_CIPHER.so (depending on your platform, the actual extension may differ from .so), for example, libgtmcrypt_openssl_AESCFB. GT.M cannot and does not ensure that the cipher is actually AES CFB as implemented by OpenSSL.

gtm_custom_errors specifies the complete path to the file that contains a list of errors that should automatically stop all updates on those region(s) of an instance which have the Instance Freeze mechanism enabled.

gtm_db_startup_max_wait specifies how long to wait for a resolution of any resource conflict when they first access a database file. GT.M uses semaphores maintained using UNIX Inter-Process Communication (IPC) services to ensure orderly initialization and shutdown of database files and associated shared memory. Normally the IPC resources are held in an exclusive state only for very brief intervals. However, under unusual circumstances that might include extremely large numbers of simultaneous database initializations, a long-running MUPIP operation involving standalone access (like INTEG -FILE or RESTORE), an OS overload or an unpredicted process failure the resources might remain unavailable for an unanticipated length of time. $gtm_db_startup_max_wait specifies how long to wait for the resources to become available:

The default value for the wait if $gtm_db_startup_max_wait is not defined is 96 seconds.

gtm_dist specifies the path to the directory containing the GT.M system distribution. gtm_dist must be defined for each user. If you are not using the gtm script or sourcing gtmprofile, consider defining gtm_dist in the login file or as part of the default system environment. In UTF-8 mode, the gtm_dist environment variable specifies the path to the directory containing the GT.M system distribution for Unicode® support. The distribution for UTF-8 mode is located in subdirectory utf8 under the GT.M distribution directory. For example, if the GT.M distribution is in /usr/lib/fis-gtm/V6.1-000_x86, set gtm_dist to point to /usr/lib/fis-gtm/V6.0-003_x86/utf8 for UTF-8 mode. Correct operation of GT.M executable programs requires gtm_dist to be set correctly.

gtm_dmterm specifies a [NO]DMTERM state at process initiation where application setting applied to $PRINCIPAL also apply to direct mode interactions; a case-insensitive value of "1", "yes", or "true" establishes a DMTERM state at process initiation where direct mode uses default terminal characteristics and ignores application settings for $PRINCIPAL; all other values, including no value, result in the default VIEW "NODMTERM" behavior.

gtm_env_translate specifies the path to a shared library to implement the optional GT.M environment translation facility that can assist in resolving extended global referernces.

gtm_etrap specifies an initial value of $ETRAP to override the default value of "B" for $ZTRAP as the base level error handler. The gtmprofile script sets gtm_etrap to "Write:(0=$STACK) ""Error occurred: "",$ZStatus,!" which you can customize to suit your needs.

gtm_extract_nocol specifies whether a MUPIP JOURNAL -EXTRACT (when used without -RECOVER or -ROLLBACK) on a database with custom collation should use the default collation if it is not able to read the database file. In a situation where the database file is inaccessible or the replication instance is frozen with a critical section required for the access held by another process and the environment variable gtm_extract_nocol is defined and evaluates to a non-zero integer or any case-independent string or leading substrings of "TRUE" or "YES", MUPIP JOURNAL -EXTRACT issues the DBCOLLREQ warning and proceeds with the extract using the default collation. If gtm_extract_nocol is not set or evaluates to a value other than a positive integer or any case-independent string or leading substrings of "FALSE" or "NO", MUPIP JOURNAL -EXTRACT exits with the SETEXTRENV error.

[Caution] Warning

Note that if default collation is used for a database with custom collation, the subscripts reported by MUPIP JOURNAL -EXTRACT are those stored in the database, which may differ from those used by application logic.

gtm_nofflf specifies the default WRITE # behavior for STREAM and VARIABLE format sequential files. If it is set to 1, Y[ES] or T[RUE], WRITE # writes only a form-feed <FF> character in conformance to the M standard. If it is not defined or set to 0, NO, or FALSE, WRITE # writes <FF><LF> characters. The [NO]FFLF deviceparameter for USE and OPEN commands takes precedence over any value of gtm_nofflf.

gtm_gdscert specifies the initial setting that controls whether GT.M processes should test updated database blocks for structural damage. If it is defined, and evaluates to a non-zero integer or any case-independent string or leading substrings of "TRUE" or "YES", GT.M performs block-level integrity check on every block as a process commits it. Within a running process, VIEW "GDSCERT":value controls this setting By default, GT.M does not check database blocks for structural damage, because the impact on performance is usually unwarranted.

gtm_gvdupsetnoop specifies the initial value that determines whether a GT.M process should enable duplicate SET optimization. If it is defined, and evaluates to a non-zero integer or any case-independent string or leading substrings of "TRUE" or "YES", when a SET command does not change the value of an existing node, GT.M does not perform the update or execute any trigger code specified for the node. Within a running process, VIEW "GVDUPSETNOOP":value controls this behavior. By default, GT.M enables this optimization.

gtm_hupenable specifies the initial value that determines whether a GT.M process should recognize a disconnect signal from a PRINCIPAL device that is a terminal. If it is defined, and evaluates to a non-zero integer or any case-independent string or leading substrings of "TRUE" or "YES", the proces receives an TERMHANGUP error if the O/S signals that the terminal assigned to the process as the PRINCIPAL device has disconnected. Within a running process, USE $PRINCIPAL:[NO]HUP[ENABLE] controls this behavior. By default, GT.M ignores such a signal, but a process that ignores the signal may subsequently receive an IOEOF or a TERMWRITE error from an attempt to respectively READ from, or WRITE to the missing device. GT.M terminates a process that ignores more than one of these messages and, if the process is not in Direct Mode, sends a NOPRINCIO message to the operator log.

gtm_icu_version specifies the MAJOR VERSION and MINOR VERSION numbers of the desired ICU. For example "3.6" denotes ICU-3.6. If $gtm_chset has the value "UTF-8", GT.M requires libicu with version 3.6 or higher. If you must chose between multiple versions of libicu or if libicu has been compiled with symbol renaming enabled, GT.M requires gtm_icu_version to be explicitly set. Please see the section on "Configuring and operation GT.M with Unicode® Support" for more information,

gtm_ipv4_only specifies whether a Source Server should establish only IPv4 connections with a Receiver Server or sockets associated with a SOCKET device. If it is defined, and evaluates to a non-zero integer, or any case-independent string or leading substring of "TRUE" or "YES", the Source Server establishes only IPv4 connections with the Receiver Server. gtm_ipv4_only is useful for environments where different server names are not used for IPv4 and IPv6 addresses and the Source Server connects to a Receiver Server running a GT.M version prior to V6.0-003.

gtm_jnl_release_timeout specifies 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 (5 minutes). 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.

gtm_keep_obj specifies whether the gtminstall script should delete the object files from the GT.M installation directory. If gtm_keep_obj is set to "Y", the gtminstall script leaves object files; by default, gtminstall deletes object files after archiving them in a shared library.

gtm_lct_stdnull specifies whether a GT.M process should use standard collation for local variables with null subscripts or legacy GT.M collation.

gtm_link specifies the initial setting that determines whether GT.M permits multiple versions of the same routine to be active at different stack levels of the M virtual machine. The VIEW "LINK":"[NO]RECURSIVE" command modifies this in an active process. If gtm_link is set to "RECURSIVE", auto-relink and explicit ZLINK commands links a newer object even when a routine with the same name is active and available in the current stack. When a process links a routine with the same name as an existing routine, future calls use the new routine. Prior versions of that routine referenced by the stack remain tied to the stack until they QUIT, at which point they become inaccessible. This provides a mechanism to patch long-running processes. If gtm_link is undefined or set to NORECURSIVE, or any value other than "RECURSIVE", auto-zlink defers replacing older routines until they no longer have an invoking use by the process and a ZLINK command produces a LOADRUNNING error when it attempts to relink an active routine on the GT.M invocation stack.

gtm_local_collate specifies an alternative collation sequence for local variables.

gtm_log specifies a directory where the gtm_secshr_log file is stored. The gtm_secshr_log file stores information gathered in the gtmsecshr process. FIS recommends that a system-wide default be established for gtm_log so that gtmsecshr always logs its information in the same directory, regardless of which user's GT.M process invokes gtmsecshr. In conformance with the Filesystem Hierarchy Standard, FIS recommends /var/log/fis-gtm/$gtmver as the value for $gtm_log unless you are installing the same version of GT.M in multiple directories. Note that $gtmver can be in the form of V6.1-000_x86 which represents the current GT.M release and platform information. If you do not set $gtm_log, GT.M creates log files in a directory in /tmp (AIX, GNU/Linux). However, this is not recommended because it makes GT.M log files vulnerable to the retention policy of a temporary directory.

[Important] Important

Starting with V6.0-000, gtmsecshr logs its messages in the system log and the environment variable gtm_log is ignored.

gtm_linktmpdir provides a location into GT.M creates small temporary files used for auto-relink; if unspecified, this location defaults to $gtm_tmp, which in turn defaults to /tmp. The implications for group and permissions of the directory are described in the section Shared Resources Authorization Permissions of Appendix D: “GT.M Security Philosophy. FIS recommends that all processes that share a directory whose contents are subject to ZRUPDATE use the same value for $gtm_linktmpdir so that all processes see update notifications - with different values of $gtm_linktmpdir, a ZRUPDATE by a process with one value of $gtm_linktmpdir would not be observed by a process with a different value of that environment variable.

gtm_max_indrcache_count (use only under the guidance of your GT.M support channel) specifies the number of cached entries in indirection compilation. The default is 128.

gtm_max_indrcache_memory (use only under the guidance of your GT.M support channel) specifies the maximum size (in KiB) of memory that GT.M should use for indirection cache object code. The default is 128.

gtm_max_sockets specifies the maximum number of client connections for socket devices. The default is 64.While it must be large enough to accommodate the actual need, each reservation requires some memory in socket structures, so setting this number unnecessarily high causes requires a bit of additional memory for no benefit.

gtm_memory_reserve specifies the size in kilobytes of the reserve memory that GT.M should use in handling and reporting an out-of-memory condition. The default is 64 (KiB). Setting this too low can impede investigations of memory issues, but GT.M only uses this reserve when a process runs out of memory so it almost never requires actual memory, only address space.

gtm_mstack_crit specifies an integer between 15 and 95 defining the percentage of the stack which should be used before GT.M emits a STACKCRIT warning. If the value is below the minimum or above the maximum GT.M uses the minimum or maximum respectively. The default is 90.

gtm_mstack_size specifies the M stack size (in KiB). If gtm_mstack_size is not set or set to 0, GT.M uses the default M stack size (that is, 272KiB). The minimum supported size is 25 KiB; GT.M reverts values smaller than this to 25 KiB. The maximum supported size is 10000 KiB; GT.M reverts values larger than this to 10000 KiB.

gtm_mupjnl_parallel defines the number of processes or threads used by MUPIP JOURNAL -RECOVER/-ROLLBACK when the invoking command does not have a -PARALLEL qualifier. When defined with no value, it specifies one process or thread per region. When undefined or defined to one (1), it specifies MUPIP should process all regions without using additional processes or threads. When defined with an integer value greater than one (1), it specifies the maximum number of processes or threads for MUPIP to use. If the value is greater than the number of regions, MUPIP never uses more processes or threads than there are regions. If it is less than the number of regions, MUPIP allocates work to the additional processes or threads based on the time stamps in the journal files.

gtm_nocenable specifies whether the $principal terminal device should ignore <CTRL-C> or use <CTRL-C> as a signal to place the process into direct mode; a USE command can modify this device characteristic. If gtm_nocenable is defined and evaluates to a non-zero integer or any case-independent string or leading substrings of "TRUE" or "YES", $principal ignores <CTRL-C>. If gtm_nocenable is not set or evaluates to a value other than a positive integer or any case-independent string or leading substrings of "FALSE" or "NO", <CTRL-C> on $principal places the process into direct mode at the next opportunity (usually at a point corresponding to the beginning of the next source line).

gtm_non_blocked_write_retries modifies FIFO or PIPE write behavior. A WRITE which would block is retried up to the number specified with a 100 milliseconds delay between each retry. The default value is 10 times.

gtm_nontprestart_log_delta specifies the number of non-transaction restarts for which GT.M should wait before reporting a non-transaction restart to the operator logging facility. If gtm_nontprestart_log_delta is not defined, GT.M initializes gtm_nontprestart_log_delta to 0.

gtm_nontprestart_log_first specifies the initial number of non-transaction restarts which GT.M should report before placing non-transaction restart reports to the operator logging facility using the gtm_nontprestart_log_delta value. If gtm_nontprestart_log_delta is defined and gtm_nontprestart_log_first is not defined, GT.M initializes gtm_nontprestart_log_first to 1.

gtm_noundef specifies the initial setting that controls whether a GT.M process should treat undefined global or local variables as having an implicit value of an empty string. If it is defined, and evaluates to a non-zero integer or any case-independent string or leading substring of "TRUE" or "YES", then GT.M treats undefined variables as having an implicit value of an empty string. The VIEW "[NO]UNDEF" command can alter this behavior in an active process. By default, GT.M signals an error on an attempt to use the value of an undefined variable.

gtm_obfuscation_key: If $gtm_obfuscation_key specifies the name of file readable by the process, the encryption reference plugin uses a cryptographic hash of the file's contents as the mask for the obfuscated password in the environment variable gtm_passwd. When gtm_obfuscation_key does not point to a readable file, the plugin computes a cryptographic hash using a mask based on the value of $USER and the inode of the mumps executable to use as a mask. $gtm_passwd set with a $gtm_obfuscation_key allows access to all users who have the same $gtm_obfuscation_key defined in their environments. However, $gtm_passwd set without $gtm_obfuscation_key can be used only by the same $USER using the same GT.M distribution.

gtm_passwd specifies the obfuscated (not encrypted) password of the GNU Privacy Guard key ring. When the environment variable $gtm_passwd is set to "", GT.M invokes the default GTMCRYPT passphrase prompt to obtain a passphrase at process startup and uses that value as $gtm_passwd for the duration of the process.

gtm_patnumeric specifies the value of the read-only ISV $ZPATNUMERIC that determines how GT.M interprets the patcode "N" used in the pattern match operator. The SET command can alter the value of $ZPATNUMERIC in an active process. If the environment variable gtm_patnumeric is not defined or set to a value other than "UTF-8", GT.M initializes $ZPATNUMERIC to "M".

gtm_pattern_file and gtm_pattern_table specify alternative patterns for the pattern (?) syntax. Refer to the Internationalization chapter in the Programmer's Guide for additional information.

gtm_poollimit restricts the number of global buffers a process uses in order to limit the potential impact on other processes. It is intended for use by a relatively small subset of processes when those processes have the potential to "churn" global buffers; the value is of the form n[%] when it ends with a per-cent sign (%), the number is taken as an as a percentage of the configured global buffers and otherwise as an ordinal number of preferred buffers; standard M parsing and integer conversions apply. Note that this environment variable applies to all regions accessed by a process; the VIEW command for this feature allows finer grained control. MUPIP REORG uses this facility to limit its buffers with a default of 64 if gtm_poollimit is not specified. Note that this may slightly slow a standalone REORG but can be overridden by defining gtm_poollimit as 0 or "100%".

gtm_principal specifies the value for $PRINCIPAL, which designates an alternative name (synonym) for the principal $IO device.

gtm_principal_editing specifies the initial settings for $PRINCIPAL of the following colon-delimited deviceparameters: [NO]EDITING [NO]EMPTERM and [NO]INSERT; in an active process the USE command can modify these device characteristics.

[Note] Note

The GT.M direct mode commands have a more extensive capability in this regard, independent of the value of this environment variable.

gtm_procstuckexec specifies a shell command or a script to execute when any of the following conditions occur:

You can use this as a monitoring facility for processes holding a resource for an unexpected amount of time. Typically, for the shell script or command pointed to by gtm_procstuckexec, you would write corrective 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 as follows:

  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] Note

Make sure user processes have sufficient space and permissions to run the shell command / script. For example for the script to invoke the debugger, the process must be of the same group or have a way to elevate priveleges.

gtm_prompt specifies the initial value of the ISV $ZPROMPT, which controls the GT.M direct mode prompt. The SET command can alter the value of $ZPROMPT in an active process.By default, the direct mode prompt is "GTM>".

gtm_quiet_halt specifies whether GT.M should disable the FORCEDHALT message when the process is stopped via MUPIP STOP or by a SIGTERM signal (as sent by some web servers).

gtm_repl_instance specifies the location of the replication instance file when database replication is in use.

gtm_repl_instname specifies a replication instance name that uniquely identifies an instance. The replication instance name is immutable. The maximum length of a replication instance name is 15 bytes. Note that the instance name is not the same as the name of the replication instance file (gtm_repl_instance). You need to specify a replication instance name at the time of creating an replication instance file. If you do not define gtm_repl_instname, you need to specify an instance name using -NAME=<instance_name> with MUPIP REPLICATE -INSTANCE_CREATE.

gtm_repl_instsecondary specifies the name of the replicating instance in the current environment. GT.M uses $gtm_repl_instsecondary if the -instsecondary qualifer is not specified.

gtm_retention (used by the gtm/gtmprofile script) - On every invocation, the gtm script deletes all prior generation journal files (*_<time and date stamp>) older than $gtm_retention days from the directory (and its subdirectories) of the global directory. By default, $gtm_retention is 42.

gtm_side_effects: When the environment variable gtm_side_effects is set to one (1) at process startup, GT.M generates code that performs left to right evaluation of actuallist arguments, function arguments, operands for non-Boolean binary operators, SET arguments where the target destination is an indirect subscripted glvn, and variable subscripts. When the environment variable is not set, or set to zero (0), GT.M retains its traditional behavior, which re-orders the evaluation of operands using rules intended to improve computational efficiency. This reordering assumes that functions have no side effects, and may generate unexpected behavior (x+$increment(x) is a pathological example). When gtm_side_effects is set to two (2), GT.M generates code with the left-to-right behavior, and also generates SIDEEFFECTEVAL warning messages for each construct that potentially generates different results depending on the order of evaluation. As extrinsic functions and external calls are opaque to the compiler at the point of their invocation, it cannot statically determine whether there is a real interaction. Therefore SIDEEFFECTEVAL warnings may be much more frequent than actual side effect interactions and the warning mode may be most useful as a diagnostic tool to investigate problematic or unexpected behavior in targeted code rather than for an audit of an entire application. Note that a string of concatenations in the same expression may generate more warnings than the code warrants. Other values of the environment variable are reserved for potential future use by FIS. It is important to note that gtm_side_effects affects the generated code, and must be in effect when code is compiled - the value when that compiled code is executed is irrelevant. Note also that XECUTE and auto-ZLINK, explicit ZLINK and ZCOMPILE all perform run-time compilation subject to the characteristic selected when the process started. Please be aware that programming style where one term of an expression changes a prior term in the same expression is an unsafe programming practice. The environment variable gtm_boolean may separately control short-circuit evaluation of Boolean expressions but a setting of 1 (or 2) for gtm_side_effects causes the same boolean evaluations as setting gtm_boolean to 1 (or 2). Note that warning reports for the two features are separately controlled by setting their values to 2. The differences in the compilation modes may include not only differences in results, but differences in flow of control when the code relies on side effect behavior.

gtm_snaptmpdir specifies the location to place the temporary "snapshot" file created by facilities such as on-line mupip integ. If $gtm_snaptmpdir is not defined, GT.M uses the $gtm_baktmpdir environment variable if defined, and otherwise uses the current working directory. All processes performing updates during an online INTEG must have the use the same directory and have write access to it.

gtm_statsdir specifies the directory for database files into which processes opted-in to sharing global statistics place their statistics as binary data. If you do not explicitly define this environment variable for a process, GT.M defines this to the evaluation of $gtm_tmp, which defaults to /tmp. All processes that share statistics MUST use the same value for $gtm_statsdir. FIS suggests that you point gtm_statsdir at a tmpfs or ramfs on Linux, and a filesystem in a ram disk on AIX. These database files have a name derived from the user defined database file name and a .gst extension. They are not usable as normal database files by application code, except to read statistics. GT.M automatically creates and deletes these database files as needed. Under normal operation, applications do not need to manage them explicitly. The mapping of ^%YGS to statistics database files is managed by GT.M within global directories, transparently to applications. The ^%YGBLSTAT utility program gathers and reports statistics from nodes of ^%YGS(region,pid).

gtm_statshare specifies an initial value for the characteristic controlled by VIEW "[NO]STATSHARE" in application code. A value of 1, or any case-independent string or leading substrings of "TRUE" or "YES" in the environment variable gtm_statshare provides the equivalent of VIEW "STATSHARE" as the initial value. Leaving the gtm_statshare undefined or defined to another value, typically 0, "FALSE" or "NO" provides the equivalent of VIEW "NOSTATSHARE" as the initial value.

gtm_stdxkill enables the standard-compliant behavior to kill local variables in the exclusion list if they had an alias that as not in the exclusion list. By default, this behavior is disabled.

gtm_sysid specifies the value for the second piece of the $SYstem ISV. $SYSTEM contains a string that identifies the executing M in stance. The value of $SYSTEM is a string that starts with a unique numeric code that identifies the manufacturer . Codes were originally assigned by the MDC (MUMPS Development Committee). $SYSTEM in GT.M starts with "47" followed by a comma and $gtm_sysid.

gtm_tmp specifies a directory where socket files used for communication between gtmsecshr and GT.M processes are stored. All processes using the same GT.M should have the same $gtm_tmp. If the environment variable $gtm_tmp is undefined, if its value is longer than GT.M can handle, or if it is defined to a value that is not an absolute pathname (starting with a /), GT.M assumes the /tmp directory as the value for $gtm_tmp. Setting $gtm_temp to /tmp is not recommended because it makes files vulnerable to the retention policy of what is typically a centrally managed temporary directory.

gtm_tpnotacidtime specifies the maximum time that a GT.M process waits for non-Isolated timed command (HANG, JOB, LOCK, OPEN, READ, WRITE /* or ZALLOCATE) running within a transaction to complete before it releases all critical sections it owns and sends a TPNOTACID information message to the system log. A GT.M process owns critical sections on all or some of the regions participating in a transactions only during final retry attempts (when $TRETRY>2). gtm_tpnotacidtime specifies time in seconds to millisecond precision (three decimal places); the default is 2 seconds. The maximum value of gtm_tpnotacidtime is 30 and the minimum is 0. If gtm_tpnotacidtime specifies a time outside of this range, GT.M uses the default value. The GT.M behavior of releasing critical sections in final retry attempt to provide protection from certain risky coding patterns which, because they are not Isolated, can cause deadlocks (in the worst case) and long hangs (in the best case). As ZSYSTEM and BREAK are neither isolated nor timed, GT.M initiates TPNOTACID behavior for them immediately as it encounters them during execution in a final retry attempt (independent of gtm_tpnotacidtime). Rapidly repeating TPNOTACID messages are likely associated with live-lock, which means that a process is consuming critical resources repeatedly within a transaction, and is unable to commit because the transaction duration is too long to commit while maintaining ACID transaction properties.

gtm_tprestart_log_delta specifies the number of transaction restarts for which GT.M should wait before reporting a transaction restart to the operator logging facility. If gtm_tprestart_log_delta is not defined, GT.M initializes gtm_tp_restart_log_delta to 0.

gtm_tprestart_log_first specifies the initial number of transaction restarts which GT.M should report before pacing transaction restart reports to the operator logging facility using the gtm_tprestart_log_delta value. If gtm_tprestart_log_delta is defined and gtm_tprestart_log_first is not defined, GT.M initializes gtm_tprestart_log_first to 1.

gtm_trace_gbl_name enables GT.M tracing at process startup. Setting gtm_trace_gbl_name to a valid global variable name instructs GT.M to report the data in the specified global when a VIEW command disables the tracing, or implicitly at process termination. This setting behaves as if the process issued a VIEW "TRACE" command at process startup. However, gtm_trace_gbl_name has a capability not available with the VIEW command, such that if the environment variable is defined but evaluates to zero (0) or to the empty string, GT.M collects the M-profiling data in memory and discards it when the process terminates (this feature is mainly used for in-house testing). Note that having this feature activated for processes that otherwise don't open a database file (such as GDE) can cause them to encounter an error.

gtm_trigger_etrap provides the initial value for $ETRAP in trigger context; can be used to set trigger error traps for trigger operations in both mumps and MUPIP processes.

gtm_zdate_form specifies the initial value for the $ZDATE ISV. The SET command can alter the value of $ZDATE in an active process.

gtm_zinterrupt specifies the initial value of the ISV $ZINTERRUPT which holds the code that GT.M executes (as if it is the argument for an XECUTE command) when a process receives a signal from a MUPIP INTRPT command. The SET command can alter the value of $ZINTERRUPT in an active process.

gtm_zlib_cmp_level specifies the zlib compression level used in the replication stream by the source and receiver servers. By default, replication does not use compression.

gtm_zmaxtptime specifies the initial value of the $ZMAXTPTIME Intrinsic Special Variable, which controls whether and when GT.M issues a TPTIMEOUT error for a TP transaction that runs too long. gtm_zmaxtptime specifies time in seconds and the default is 0, which indicates "no timeout" (unlimited time). The maximum value of gtm_zmaxtptime is 60 seconds and the minimum is 0; GT.M ignores gtm_zmaxtptime if it contains a value outside of this recognized range. This range check does not apply to SET $ZMAXTPTIME.

gtm_zquit_anyway specifies whether the code of the form QUIT <expr> execute as if it were SET <tmp>=<expr> QUIT:$QUIT tmp QUIT, where <tmp> is a temporary local variable in the GT.M runtime system that is not visible to application code. This setting is a run-time setting, rather than a compiler-time setting. If gtm_zquit_anyway is defined and evaluates to 1 or any case-independent string or leading substrings of "TRUE" or "YES", code of the form QUIT <expr> executes as if it were SET <tmp>=<expr> QUIT:$QUIT tmp QUIT. If gtm_zquit_anyway is not defined or evaluates to 0 or any case-independent string or leading substrings of "FALSE" or "NO", GT.M executes QUIT <expr> as specified by the standard..

gtm_zstep specifies the initial value of $ZSTEP, which defines the ZSTEP action; if gtm_zstep is not defined, $ZSTEP defaults to "B".

gtm_ztrap_form and gtm_zyerror specify the behavior of error handling specified by $ZTRAP as described in the Error Processing chapter of the GT.M Programmer's Guide.

gtm_ztrap_new specifies whether a SET $ZTRAP also implicitly performs a NEW $ZTRAP before the SET.

old_gtm_dist (not used by GT.M directly) - The path of the prior GT.M distribution. The gtmprofile script uses this value to set other environment variables.

old_gtmroutines (not used by GT.M directly) - The prior routine search path. The gtmprofile script uses this value to set other environment variables.

old_gtmver (not used by GT.M directly) - The value of gtmver that was set when the gtmprofile script was last sourced. The gtmprofile script uses this value to set other environment variables.

tmp_gtm_tmp (not used by GT.M directly) - It is used by the gtmprofile script in maintaining gtm_tmp.

tmp_passw (not used by GT.M directly) - It is used by the gtmprofile script in maintaining gtm_passwd.

The gtmprofile and gtmschrc scripts sets the following environment variables. FIS recommends using the gtmprofile script (or the gtm script which sources gtmprofile) to set up an environment for GT.M.

Environment Variables

Set up by GT.M shell scripts

* denotes environment variables that must be defined for normal GT.M operation.

LC_CTYPE

gtmprofile

gtmgbldir*

gtmprofile, gtmcshrc

gtmroutines*

gtmprofile, gtmcshrc

gtmver

gtmprofile

gtm_dist*

gtmprofile, gtmschrc

gtm_icu_version

gtmprofile

gtm_log*

gtmprofile

gtm_principal_editing

gtmprofile

gtm_prompt

gtmprofile

gtm_repl_instance

gtmprofile

gtm_retention

gtmprofile

gtm_tmp

gtmprofile

old_gtmroutines

gtmprofile

old_gtm_dist

gtmprofile

old_gtmver

gtmprofile

tmp_gtm_tmp

gtmpropfile

tmp_passw

gtmprofile

While creating an environment for multiple processes accessing the same version of GT.M, bear in mind the following important points:

  1. A GT.M version has an associated gtmsecshr (located by $gtm_dist). If multiple processes are accessing the same GT.M version, each process must use the same combination of $gtm_tmp and $gtm_log.

  2. In conformance with the Filesystem Hierarchy Standard, FIS recommends /var/log/fis-gtm/$gtmver as the value for $gtm_log. Note that $gtmver can be in the form of V5.4-001_x86 which represents the current GT.M release and platform information.

  3. FIS recommends setting $gtm_tmp to a temporary directory /tmp (AIX, GNU/Linux). The gtmprofile script sets $gtm_tmp to /tmp/fis-gtm/$gtmver.

  4. If you do not set $gtm_log, GT.M creates log files in a directory in /tmp (AIX, GNU/Linux). However, this is not recommended because it makes GT.M log files vulnerable to the retention policy of a temporary directory.

Always set the same value of $gtm_tmp for all processes using the same GT.M version. Having different $gtm_tmp for multiple processes accessing the same GT.M version may prevent processes from being able to communicate with gtmsecshr and cause performance issues.