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

gtm_badchar specifies the initial setting of the VIEW command that determines whether GT.M should raise an error when it encounters an illegal UTF-8 character sequence.It is ignored in M mode.

gtm_baktmpdir specifies the directory where mupip backup creates temporary files. If $gtm_baktmpdir is not defined, GT.M uses the $GTM_BAKTMPDIR environment variable if defined, and otherwise uses the current working directory.

gtm_chset determines the mode in which GT.M 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" (on 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 collation is used. 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_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 extreme 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_crypt_plugin: If you wish to continue using Blowfish CFB with V6.0-001 via the reference implementation of the plugin, you need to change a symbolic link post-installation, or define the environment variable 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 - GT.M uses CIPHER as salt for the hashed key in the database file header, and cryptlib is for your convenience, for example, for troubleshooting. Installing the GT.M distribution creates a default symbolic link.

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_dbkeys is used by the encryption reference plugin (not used by GT.M directly) for the name of a file providing a list of database files and their corresponding key files.

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. The distribution for Unicode 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_env_translate specifies the path to a shared library to implement the optional GT.M environment translation facility.

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.

gtm_fullblockwrites specifies whether a GT.M process should write a full database block worth of bytes when writing a database block that is not full. Depending on your IO subsystem, writing a full block worth of bytes (even when there are unused garbage bytes at the end) may result in better database IO performance by replacing a read-modify-read low level IO operation with a single write operation.

gtm_gdscert specifies the initial value of the VIEW command that controls whether GT.M processes should test updated database blocks for structural damage. 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 of the VIEW command that controls 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", 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.

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 explictly set.

gtm_ipv4_only specifies whether a Source Server should establish only IPv4 connections with a Receiver Server. 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. Set gtm_ipv4_only 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 enables the --keep-obj option. By default, --keep_obj is disabled.

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_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, Tru64 UNIX) or /var/tmp (HP-UX, Solaris). However, this is not recommended because it makes GT.M log files vulnerable to the retention policy of a temporary directory.

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 for which GT.M should wait before reporting any transaction restart to the operator logging facility. 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_max_sockets specifies the maximum number of client connections for socket devices. The default is 64.

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

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_noundef specifies the initial value of the VIEW command that controls whether a GT.M process should treat undefined 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. By default, GT.M signals an error on an attempt to use the value of an undefined variable.

gtm_passwd used by the encryption reference plugin (not used by GT.M directly) for the obfuscated (not encrypted) password to the GNU Privacy Guard key ring.

gtm_patnumeric specifies the initial value of the ISV $ZPATNUMERIC in UTF-8 mode.

gtm_pattern_file and gtm_pattern_table specify alternative patterns for the ? (pattern) syntax.

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

gtm_principal_editing determines whether the previous input to a READ command can be recalled and edited before pressing ENTER to submit it.

gtm_prompt specifies the initial value of the ISV $ZPROMPT, which controls the GT.M direct mode prompt. By default, the direct mode prompt is "GTM>".

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:

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.

gtm_obfuscation_key: If $gtm_obfuscation_key specifies the name of file readable by the process, the encryption reference plug-in uses an SHA-512 hash of the file's contents as the XOR mask for the obfuscated password in the environment variable gtm_passwd. When gtm_obfuscation_key does not point to a readable file, the plug-in creates an XOR mask based on the userid and inode of the mumps executable and then computes an SHA-512 hash of the XOR mask to use as a mask.

gtm_obfuscation_key can be used as a mechanism to pass an obfuscated password between unrelated processes (for example, a child process with a different userid invoked via a sudo mechanism), or even from one system to another (for example, over an ssh connection).

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_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 (not used by GT.M directly) - used by the gtm script to delete old journal files and old temporary files it creates.

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 existing 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). The differences in the compilation modes may include not only differences in results, but differences in flow of control.

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.

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 instance. 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.

gtm_tpnotacidtime specifies the maximum time that a GT.M process waits for non-Isolated timed command (JOB, LOCK, OPEN, READ, 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>3). gtm_tpnotacidtime specifies time in seconds; 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_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, only on UNIX, 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 process 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.

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.

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; this range check does not apply to SET $ZMAXTPTIME. GT.M ignores gtm_zmaxtptime if it contains a values outside of this recognized range.

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 not a compiler-time setting, but rather a run-time one. 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", there is no change in the execution of code of the form QUIT <expr>.

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 of $ZTRAP also implicitly News it.

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

gtmcompile specifies the initial value of the $ZCOmpile ISV.

gtmcrypt_config specifies the location of the configuration file required for database encryption and/or TLS support. A configuration file is divided into two sections–database encryption section and TLS section. The database encryption section contains a list of database files and their corresponding key files. Do not add a database encryption section if you are not using an encrypted database. The TLS section contains a TLSID label that identifies the location of root certification authority certificate in PEM format and leaf-level certificate with its corresponding private key file. Note that the use of the gtmcrypt_config environment variable require the libconfig library to be installed.

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".

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 must choose one to use. To automate this definition, define gtmgbldir in the user's login file.

gtmroutines specifies the initial value of the $ZROutines ISV.

gtmtls_passwd_<label> $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.

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 is a standard system environment variable (LIBPATH in AIX) to point to the location of ICU. GT.M requires ICU 3.6 (or above) to perform Unicode related functionality.

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.

TZ is a standard system environment variable that specifies the timezone to be used by GT.M processes, if they are not to use the default system timezone (GT.M assumes the system clock is set to UTC).

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.

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

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.