Several environment variables control the operation of GT.M. Some of them must be set up for normal operation, where as for others GT.M assumes a default value if they are not set.
Your GT.M distribution comes with many scripts that set up a default GT.M environment for the shell of your choice. These scripts are as follows:
gtmprofile: uses reasonable defaults to set up a system and GT.M application development environment for POSIX shells. The gtmprofile script sets default values for environment variables gtm_dist, gtmgbldir, gtm_icu_version, gtm_log, gtm_principal_editing, gtm_prompt, gtm_retention, gtmroutines, gtm_tmp, and gtmver. When you source the gtmprofile script, it creates a default execution environment (global directory and a default database file with BEFORE_IMAGE journaling) if none exists.
gtmcshrc: sets up a default GT.M environment for C-shell compatible shells. It sets up default values for gtm_dist, gtmgbldir, gtm_chset and gtmroutines. It also creates aliases so you can execute GT.M and its utilities without typing the full path. While gtmprofile is current with GT.M releases, gtmcshrc is at the same level of sophistication as gtmprofile_preV54000. It is not as actively maintained as the gtmprofile script.
gtmprofile_preV54000: This script was provided as gtmprofile in GT.M distributions prior to V5.4-000. This script is a POSIX shell equivalent of gtmschrc.
gtmbase: detects the shell type and adds gtmprofile to .profile or gtmchsrc to .cshrc so the shell automatically sources gtmprofile or gtmschrc on a subsequent login operation. FIS does not recommend using gtmbase as is - use it as an example of a script for you to develop suitable for your systems. It is not as actively maintained as the gtmprofile script.
gtm: starts GT.M in direct mode on POSIX shells. The gtm script sources gtmprofile. It also deletes prior generation journal and temporary files older than the number of days specified by the environment variable gtm_retention. It attempts to automatically recover the database when it runs and as such is suitable for "out of the box" usage of GT.M. Although it will work for large multi-user environments, you may want to modify or replace it with more efficient scripting.
gdedefaults: a GDE command file that specifies the default values for database characteristics defined by GDE.
These scripts are designed to give you a friendly out-of-the-box GT.M experience. Even though you can set up an environment for normal GT.M operation without using these scripts, it is important to go through these scripts to understand the how to manage environment configuration.
gtmprofile helps you set an environment for POSIX shells. It uses reasonable defaults to set up all environment variables for normal GT.M operation. gtmprofile sets the following environment variables:
gtmprofile sets the following environment variables:
gtm_dist, gtmgbldir, gtm_icu_version, gtm_log, gtm_principal_editing, gtm_prompt, gtm_retention, gtmroutines, gtm_tmp, gtmver.
If $gtm_chset is set to UTF-8, gtmprofile also attempts to set LC_CTYPE to the first usable utf8 locale.
The following shell variables are used by the script and left unset at its completion:
old_gtm_dist, old_gtmroutines, old_gtmver, tmp_gtm_tmp, tmp_passwd.
The gtmpscript (and gtm) scripts, by design, are idempotent so that calling them repeatedly is safe. The GT.M installation process ensures that gtmprofile always sets gtm_dist correctly. Idempotency is implemented by checking the value of $gtm_dist, and skipping all changes to environment variables of $gtm_dist.
When gtm sources gtmprofile, it provides a default execution environment (global directory and a default database with BEFORE_IMAGE journaling) if none exists. It also creates a directory .fis-gtm with a default structure like the following:
.fis-gtm |-- V6.1-000_x86 | |-- g | | |--gtm.dat| | |--gtm.gld| | |--gtm.mjl| |-- o | | '-- utf8 | '-- r '-- r
where V6.1-000_x86 represents current release and platform information. Note that this directory structure has different locations for GT.M routines (r) , object files (o), and database-related files (g). gtmprofile sets gtmroutines to something like /usr/gtmnode1/.fis-gtm/V6.0-003_x86/o(/usr/gtmnode1/.fis-gtm/V6.0-003_x86/r /usr/gtmnode1/.fis-gtm/r) <path to the GT.M distribution>. This specifies that GT.M searches for routines in /usr/gtmnode1/.fis-gtm/V6.0-003_x86/r, then /usr/gtmnode1/.fis-gtm/r, and finally in your GT.M distribution directory. gtmroutines also specifies that all object files should be generated in /usr/gtmnode1/.fis-gtm/V6.0-003_x86/o, which also specifies the GT.M lookup location for finding object files.
Suppose you have a routine MyRoutine.m in /usr/gtmnode1/.fis-gtm/V6.1-000_x86/r. On compilation, GT.M stores MyRoutine.o in /usr/gtmnode1/.fis-gtm/V6.0-003_x86/o. Everytime a process first runs this routine, GT.M looks in the /fis-gtm/V6.0-003_x86/o directory and links it prior to its first execution. For a comprehensive discussion of GT.M source and object file management, refer to the $ZROUTINES section in the GT.M Programmer's Guide.
When $gtm_chset is set to UTF-8, gtmprofile sets gtmroutines to something like /usr/gtmnode1/.fis-gtm/V6.1-000_x86/o/utf8(/usr/gtmnode1/.fis-gtm/V6.0-003_x86/r /usr/gtmnode1/.fis-gtm/r) <path to the GT.M distribution>/utf8. So, on compilation, GT.M stores MyRoutine.o in /usr/gtmnode1/.fis-gtm/V6.0-003_x86/o/utf8. Note that GT.M does not store object files in /usr/gtmnode1/.fis-gtm/V6.0-003_x86/o which was the case in M mode. Everytime your run this routine, GT.M looks for MyRoutine.o in the .../o/utf8 directory and executes it.gtmprofile automatically modifies environment variables based on the required settings. In the above example, notice how gtmprofile modifies gtmroutines based on the character mode set for gtm_chset.
If a GT.M environment exists, gtmprofile looks for and replaces substrings in environment variables with the GT.M version (gtmver and gtm_dist). This allow you to to switch between different GT.M versions and character set modes (M and UTF-8). This way you can use the same source code files to generate different object code files, depending on the GT.M version and the setting of $gtm_chset.
On platforms where GT.M supports object code in shared libraries, if there are any shared libraries in object directories such as /usr/gtmnode1/.fis-gtm/V6.1-000_x86_64/o, the gtmprofile script automatically includes them in the gtmroutines environment variable.
The gtmprofile script also provides a framework to extend GT.M with plug-ins. Place the M code in $gtm_dist/plugin/r, the M mode object code in the $gtm_dist/plugin/o directory and UTF-8 mode object modules in the $gtm_dist/plugin/o/utf8 directory. On platforms where GT.M supports object code in shared libraries, you can create shared libraries instead of .o files. You can place external call tables in the plugin subdirectory, as well as shared libraries of calls to C code. The gtmprofile script automatically includes these in the gtmroutines environment variable.
gtmprofile automatically changes the environment variable values based on the values of gtmver and gtmdir set by the last sourced gtmprofile. Consider the following example:
$ env | grep gtm $ source /usr/lib/fis-gtm/V6.1-000_x86_64/gtmprofile $ env | grep gtm gtm_repl_instance=/home/jdoe/.fis-gtm/V6.1-000_x86_64/g/gtm.repl gtm_log=/tmp/fis-gtm/V6.1-000_x86_64 gtm_prompt=GTM> gtm_retention=42 gtmver=V6.1-000_x86_64 gtm_icu_version=4.2 gtmgbldir=/home/jdoe/.fis-gtm/V6.1-000_x86_64/g/gtm.gld PATH=/home/jdoe/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin :/bin:/usr/games:/usr/lib/fis-gtm/V6.1-000_x86_64 gtmroutines=/home/jdoe/.fis-gtm/V6.1-000_x86_64/o(/home/jdoe/.fis-gtm/V6.0-003_x86_64/r /home/jdoe/.fis-gtm/r) /usr/lib/fis-gtm/V6.1-000_x86_64/plugin/o (/usr/lib/fis-gtm/V6.1-000_x86_64/plugin/r) /usr/lib/fis-gtm/V6.1-000_x86_64/libgtmutil.so /usr/lib/fis-gtm/V6.0-003_x86_64/ gtmdir=/home/jdoe/.fis-gtm gtm_principal_editing=EDITING gtm_tmp=/tmp/fis-gtm/V6.1-000_x86_64 gtm_dist=/usr/lib/fis-gtm/V6.1-000_x86_64 $
Notice how gtmprofile sets up $gtmroutines to allow for a single source directory /home/jdoe/.fis-gtm/r to generate object files used by multiple GT.M versions, in this case in /home/jdoe/.fis-gtm/V6.1-000_x86_64/o. Now, let's consider the following example for a different version of GT.M.
Now, let us source gtmprofile for a different GT.M:
$ env | grep "gtm" $ source /usr/lib/fis-gtm/V6.1-000_x86/gtmprofile $ env | grep "gtm" gtm_repl_instance=/home/jdoe/.fis-gtm/V6.1-000_x86/g/gtm.repl gtm_log=/tmp/fis-gtm/V6.1-000_x86 gtm_prompt=GTM> gtm_retention=42 gtmver=V6.1-000_x86 gtm_icu_version=4.4 gtmgbldir=/home/jdoe/.fis-gtm/V6.1-000_x86/g/gtm.gld PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games: /usr/lib/fis-gtm/V6.1-000_x86 gtmroutines=/home/jdoe/.fis-gtm/V6.1-000_x86/o(/home/jdoe/.fis-gtm/V6.0-003_x86/r /home/jdoe/.fis-gtm/r) /usr/lib/fis-gtm/V6.1-000_x86/plugin/o(/usr/lib/fis-gtm/V6.0-003_x86/plugin/r) /usr/lib/fis-gtm/V6.0-003_x86 gtmdir=/home/jdoe/.fis-gtm gtm_principal_editing=EDITING gtm_tmp=/tmp/fis-gtm/V6.1-000_x86 gtm_dist=/usr/lib/fis-gtm/V6.1-000_x86 $
Notice how gtmprofile automatically changes the environment variables to the new GT.M version. Notice that the same routines in /home/jdoe/.fis-gtm/r now put their object files in /home/jdoe/.fis-gtm/V6.1-000_x86/o.
Now, let us edit gtmroutines and source the original gtmprofile:
$ export gtmroutines="/tmp/$gtmver $gtm_dist" $ source /usr/lib/fis-gtm/V6.1-000_x86_64/gtmprofile $ echo $gtmroutines /tmp/V6.1-000_x86_64 /usr/lib/fis-gtm/V6.0-003_x86_64/libgtmutil.so $
Notice how gtmprofile again automatically modifies gtmroutines.
![[Note]](images/note.jpg) |
Note |
|---|---|
This scenario of sourcing gtmprofile is only for the sake of example. |
gtmprofile creates the following aliases:
alias dse="$gtm_dist/dse" alias gde="$gtm_dist/mumps -run GDE" alias gtm="$gtm_dist/gtm" alias lke="$gtm_dist/lke" alias mupip="$gtm_dist/mupip"
If /var/log/fis-gtm/$gtmver directory exists, gtmprofile sets it as the value for $gtm_log. If gtmprofile does not find /var/log/fis-gtm/$gtmver, it uses $gtm_tmp to set the value of $gtm_log, which may not meet your file retention needs.
gtmprofile creates the following aliases:
alias dse="$gtm_dist/dse" alias gde="$gtm_dist/mumps -run GDE" alias gtm="$gtm_dist/gtm" alias lke="$gtm_dist/lke" alias mupip="$gtm_dist/mupip"
If /var/log/fis-gtm/$gtmver directory exists, the gtmprofile script sets it as the value for $gtm_log. If gtmprofile does not find /var/log/fis-gtm/$gtmver, it uses $gtm_tmp to set the value of $gtm_log, which may not meet your file retention needs.
Sets a default GT.M environment for C type shell. It sets the $gtm_dist, $gtmgbldir, $gtm_chset, $gtmroutines, and adds $gtm_dist to the system environment variable PATH.
To source the gtmcshrc script, type:
$ source <path_to_GT.M_installation_directory>/gtmcshrc
You can also run the gtmbase script which places the above command in the .cshrc file so the script will get automatically sourced the next time you log in.
gtmcshrc also creates the following aliases.
alias gtm '$gtm_dist/mumps -direct' alias mupip '$gtm_dist/mupip' alias lke '$gtm_dist/lke' alias gde '$gtm_dist/mumps -r ^GDE' alias dse '$gtm_dist/dse'
Now you run can GT.M and its utilities without specifying a full path to the directory in which GT.M was installed.
Adds the following line to .profile or .cshrc file depending on the shell.
In the POSIX shell, gtmbase adds the following line to .profile:
. <gtm_dist pathname>/gtmprofile
In the C shell, adds the following line to .cshrc:
source <gtm_dist pathname>/gtmcshrc
The gtm script starts with #!/bin/sh so it can run with any shell. Also, you can use it to both run a program and run in direct mode. It sources gtmprofile and sets up default GT.M database files with BEFORE_IMAGE journaling. It automatically recovers the database on startup.This script sets up everything you need to run GT.M for a simple out-of-box experience.
For multi-user multi-environment systems, you should modify or replace the gtm script for your configuration.
The gtm script deletes all prior generation journal files (*_<time and date stamp> files) older than $gtm_retention days from the directory that contains the global directory (as pointed to by $gtmgbldir) and any subdirectories of that directory. By default, $gtm_retention is 42. However, you might want to align it with the backup frequency of your database.
Note that the removal of prior generation journal files is not specific to the database/journal files indicated by the current $gtmgbldir but the directory from where you run the gtm script.
If you plan to use GT.M in UTF-8 mode, set $gtm_chset to UTF-8 and then run the gtm script.
If you intend to use Database Encryption, set $gtm_passwd and $gtm_dbkeys first and then run the gtm script.
To run the gtm script type:
$ <path to your GT.M Distribution>/gtm
To invoke the help to assist first-time users, type:
$ <path to your GT.M Distribution>/gtm -help gtm -dir[ect] to enter direct mode (halt returns to shell) gtm -run <entryref> to start executing at an entryref gtm -help / gtm -h / gtm -? to display this text