The GT.M Global Directory Editor (GDE) is a utility for creating, examining, and modifying a global directory. GDE is a program written in M and you can invoke it from the shell with $gtm_dist/mumps -run ^GDE. If you invoke it from the shell, GDE returns a status indicating success (0) or an issue (non-zero).
Because GDE is an M program, you can also invoke GDE from a GT.M process with DO ^GDE. If you invoke GDE with a DO and modify the map of global directly currently opened by that process, you must HALT and restart the process for the process to pick up the revised mapping. FIS expects users normally run GDE from the shell --$gtm_dist/mumps -run GDE.
The input to GDE can be a command file. In a production environment, FIS recommends using command files to define database configurations and putting them under version control.
![[Caution]](images/caution.jpg) |
Caution |
|---|---|
A global directory stores database attributes and mapping rules. Processes use mapping rules to determine which database file contains a global variable node. MUPIP CREATE uses database attributes to create new database file(s). Once MUPIP CREATE applies the database attributes to create a database file, GT.M does not use the attributes until the next MUPIP CREATE. If you use MUPIP SET (or DSE) to change the attributes of a database file, always perform an equivalent change to any global directory used for a subsequent MUPIP CREATE. Conversely, if you change attributes with GDE, existing database files must be explicitly changed with MUPIP SET or DSE. |
At process startup, the environment variable gtmgbldir identifies the global directory to the process. M application code can access and change the global directory through the $ZGBLDIR intrinsic special variable, which is initialized from $gtmgbldir at process startup. M application code can also use extended global references with the || or {} syntax.
Note that $gtmgbldir / $ZGBLDIR are pathnames. If they do not start with a "/", then the pathname is relative and GT.M searches for the global directory starting in the current working directory.
To change the Global Directory used by processes, specify a new value for gtmgbldir.
Example:
$ export gtmgbldir=/home/jdoe/node1/prod.gld
When you invoke GDE and no Global Directory exists for gtmgbldir, GDE creates a minimal default Global Directory that is a starting point or template for building global directories for your specific needs.
To retain the default Global Directory, exit GDE without making any changes.
When you invoke GDE and no Global Directory exists for gtmgbldir, GDE produces a default Global Directory that contains a minimal set of required components and values for database characteristics. It can be used for purposes such as development and testing work. A default Global Directory also serves as a starting point or template for building custom global directories.
To retain the default Global Directory, quit GDE without making any changes.
Example:
$ gtmgbldir=/usr/accntg/jones/mumps.gld $ export gtmgbldir $ $gtm_dist/mumps -dir GTM>do ^GDE %GDE-I-GDUSEDEFS, Using defaults for Global Directory /usr/accntg/jones/mumps.gld GDE> EXIT %GDE-I-VERIFY, Verification OK %GDE-I-GDCREATE, Creating Global Directory file /usr/accntg/jones/mumps.gld
Mapping is the process of connecting a global variable name or a subtree or a subscript range to a database file.
A complete mapping has the following four components:
NAME
REGION
SEGMENT
FILE
These components may be defined in any order, but the final result must be a complete logical path from name to file:
NAME(s) --> REGION --> SEGMENT --> FILE
The default Global Directory contains one complete mapping that comprises these entries for name, region, segment, and file.
* --> DEFAULT --> DEFAULT --> mumps.dat (NAME) (REGION) (SEGMENT) (FILE)
The * wildcard identifies all possible global names. Subsequent edits create entries for individual global names or name prefixes.
Regions and segments store information used to control the creation of the file. The characteristics stored with the region and segment are passed to MUPIP only when creating the database file using the CREATE command, so subsequent changes to these characteristics in the Global Directory have no effect on an existing database.
On EXIT, GDE validates the global directory to ensure that every legal global variable node maps to exactly one region; that every region has at least one global variable node mapping to it and that it maps to exactly one segment; that every segment has exactly one region mapping to it; and that the attributes for each region and segment are internally consistent. GDE will not create a structurally unsound global directory, and will not exit until it validates the global directory. Informational messages advise you of structural inconsistencies.
A Global Directory looks like this:
*** TEMPLATES ***
Std Inst
Def Rec Key Null Null Freeze Qdb Epoch LOCK
Region Coll Size Size Subs Coll Jnl on Err Rndwn Taper AutoDB Stats Crit
----------------------------------------------------------------------------------------------------------------------
<default> 0 256 64 NEVER N N N N Y N Y Sep
Segment Active Acc Typ Block Alloc Exten Options
------------------------------------------------------------------------------
<default> * BG DYN 4096 100 100 GLOB =1024
LOCK = 40
RES = 0
ENCR = OFF
MSLT =1024
DALL = YES
AIO = OFF
FBWR = 0
<default> MM DYN 4096 100 100 DEFER
LOCK = 40
MSLT =1024
DALL = YES
FBWR = 0
*** NAMES ***
Global Region
------------------------------------------------------------------------------
* DEFAULT
*** REGIONS ***
Std Inst
Dynamic Def Rec Key Null Null Freeze Qdb Epoch LOCK
Region Segment Coll Size Size Subs Coll Jnl on Err Rndwn Taper AutoDB Stats Crit
-------------------------------------------------------------------------------------------------------------------------------------------
DEFAULT DEFAULT 0 256 64 NEVER N N N N Y N Y Sep
*** SEGMENTS ***
Segment File (def ext: .dat)Acc Typ Block Alloc Exten Options
----------------------------------------------------------------------------------------------
DEFAULT mumps.dat BG DYN 4096 100 100 GLOB=1024
LOCK= 40
RES = 0
ENCR= OFF
MSLT=1024
DALL= YES
AIO = OFF
FBWR= 0
*** MAP ***
- - - - - - - - - - Names - - - - - - - - - -
From Up to Region / Segment / File(def ext: .dat)
--------------------------------------------------------------------------------------------------------------------------
% ... REG = DEFAULT
SEG = DEFAULT
FILE = mumps.dat
LOCAL LOCKS REG = DEFAULT
SEG = DEFAULT
FILE = mumps.dat
There are five primary sections in a Global Directory:
TEMPLATES
NAMES
REGIONS
SEGMENTS
MAP
The function of each section in the Global Directory is described as follows:
TEMPLATES
This section of the Global Directory provides a default value for every database or file parameter passed to GT.M as part of a region or segment definition. GDE uses templates to complete a region or segment definition where one of these necessary values is not explicitly defined.
GDE provides initial default values when creating a new Global Directory. You can then change any of the values using the appropriate -REGION or -SEGMENT qualifiers with the TEMPLATE command.
NAMES
An M program sees a monolithic global variable namespace. The NAMES section of the Global Directory partitions the namespace so that a global name or a global name with a subscript range reside in different database files. An M global can reside in one more database file, each database file can store many M globals.
REGIONS
The REGIONS section lists all of the regions in the Global Directory. Each region defines common properties for a set of M global variables or nodes; therefore, multiple sets of names from the NAMES section map onto a single region.
You assign these values by specifying the appropriate qualifier when you create or modify individual regions. If you do not specify a value for a particular parameter, GDE assigns the default value from the TEMPLATES section.
SEGMENTS
This section of the Global Directory lists currently defined segments. While regions specify properties of global variables, segments specify the properties of files. There is a one-to-one mapping between regions and segments. You assign these values by specifying the appropriate qualifier when you create or modify individual segments. If you do not specify a value for a particular parameter, GDE assigns the default value from the TEMPLATES section.
MAP
This section of the Global Directory lists the current mapping of names to region to segment to file. In the default Global Directory, there are two lines in this section: one specifies the destination for all globals, the other one is for M LOCK resources with local variable names. If you add any new mapping component definitions (that is, any new names, regions, or segments), this section displays the current status of that mapping. Any components of the mapping not currently defined display "NONE". Because GDE requires all elements of a mapping to be defined, you will not be able to EXIT (and save) your Global Directory until you complete all mappings.
GDE uses the following abbreviations to display the output of a global directory. The following list show global directory abbreviations with the associated qualifiers. For a description of the function of individual qualifiers, see "GDE Command Summary".
Abbreviation Full Form -------------------------------------------------- Acc -ACCESS_METHOD AIO -[NO]ASYNCIO Alloc -ALLOCATION AutoDB -[NO]AUTODB AutoSwitch -AUTOSWITCHLIMIT Block -BLOCK_SIZE Buff -BUFFER_SIZE Dall -[NO]DEFER_ALLOCATE Def Coll -COLLATION_DEFAULT Epoch Taper -[NO]EPOCHTAPER Exten -EXTENSION_COUNT File -FILE_NAME GLOB -GLOBAL_BUFFER_COUNT Inst Freeze On Error -[NO]INST_FREEZE_ON_ERROR JNL -[NO]JOURNAL Key Size -KEY_SIZE LOCK -LOCK_SPACE LOCK Crit -[NO]LOCK_CRIT MSLT -MUTEX_SLOTS Null Subs -[NO]NULL_SUBSCRIPTS Qdb Rndwn -[NO]QDBRUNDOWN Std Null Coll -[NO]STDNULLCOLL Rec Size -RECORD_SIZE RES -RESERVED_BYTES Region -REGION Stats -[NO[STATS Typ -DYNAMIC_SEGMENT
Once you have installed GT.M and verified its operation, create Global Directories based on your needs. To create customized Global Directories, use the appropriate GDE commands and qualifiers to build each desired Global Directory. The GDE commands are described later in this chapter.
You can also create a text file of GDE commands with a standard text editor and process this file with GDE. In a production environment, this gives better configuration management than interactive usage with GDE.
If you select the -JOURNAL option when you ADD or CHANGE a region in a Global Directory, the following section is added to your Global Directory and displays when you invoke SHOW. The columns provided display the values you selected with the journal options, or defaults provided by FIS for any options not explicitly defined.
*** JOURNALING INFORMATION ***
Region Jnl File (def ext: .mjl) Before Buff Alloc Exten AutoSwitch
------------------------------------------------------------------------------------------
DEFAULT $gtmdir/$gtmver/g/gtm.mjl
Y 2308 2048 2048 8386560
For more information about journaling, see the section on the JOURNAL qualifier in this chapter and Chapter 6: “GT.M Journaling”.