The GT.M Global Directory Editor (GDE) is a utility that enables you to create, examine, and modify a global directory. GDE is a program written in M and you can invoke it from the shell with $gtm_dist/mumps -run ^GDE, with the gtm alias gtm -run GDE, or from inside the direct mode with Do ^GDE.
![[Note]](../common/images/note.jpg) | Note |
|---|---|
The input to GDE can be a text file. In a production environment, FIS recommends using text files to define database configurations, and putting these text files under version control. |
A global directory stores database attributes and mapping rules. The mapping rules are like a sieve for globals that determines which database files hold which global names. The database attributes serve as a blueprint that MUPIP CREATE uses to create new database file(s).
Once a database file is created, GT.M continues to use the global directory as a sieve. However, once MUPIP CREATE applies the database attributes (blueprint) to create a database file, GT.M does not use the blueprint until the next MUPIP CREATE. Therefore, 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.
GT.M identifies the current Global Directory by referring to the environment variable gtmgbldir. GDE, MUPIP, LKE, DSE, and the GT.M run-time system use this environment variable. The run-time system normally uses this environment variable, but may also access a Global Directory by setting $ZGBLDIR or by using the extended global reference || or {} syntax.
If you maintain multiple Global Directories, define gtmgbldir to point to the currently active Global Directory. You may want to define gtmgbldir in your login file. Note that this definition is a pathname. If it does not start with a "/", then it is a relative pathname and GT.M searches for it starting in the current working directory.
To change the current Global Directory assignment, specify a new definition for gtmgbldir.
Example:
$ gtmgbldir=prod.gld $ export gtmgbldir
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 this default Global Directory, exit GDE without making any changes.
Example:
$ gtmgbldir=./mumps.gld $ export gtmgbldir $ gtm GTM>d ^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 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.
When you create a new mapping, GDE ensures that it has all these components by refusing to complete the EXIT command until all components of the mapping exist. Informational messages inform you of any missing or extra components.
The default Global Directory looks like this:
*** TEMPLATES ***
Def Rec Key Null Standard
Region Coll Size Size Subs NullColl Journaling
--------------------------------------------------------------------------------------------
<default> 0 4080 255 NEVER Y Y
Jnl File (def ext: .mjl) Before Buff Alloc Exten
------------------------------------------------------------------------------
<default> <based on DB file-spec> Y 128 2048 2048 8388600
Segment Active Acc Typ Block Alloc Exten Options
------------------------------------------------------------------------------
<default> * BG DYN 4096 5000 10000 GLOB =1000
LOCK = 40
RES = 0
ENCR = OFF
<default> MM DYN 4096 5000 10000 DEFER
LOCK = 40
*** NAMES ***
Global Region
------------------------------------------------------------------------------
* DEFAULT
*** REGIONS ***
Dynamic Def Rec Key Null Standard
Region Segment Coll Size Size Subs NullColl Journaling
------------------------------------------------------------------------------------------------------
DEFAULT DEFAULT 0 4080 255 NEVER Y Y
*** JOURNALING INFORMATION ***
Region Jnl File (def ext: .mjl) Before Buff Alloc Exten AutoSwitch
--------------------------------------------------------------------------------------------------------
DEFAULT $gtmdir/$gtmver/g/gtm.mjl
Y 128 2048 2048 8388600
*** SEGMENTS ***
Segment File (def ext: .dat)Acc Typ Block Alloc Exten Options
-------------------------------------------------------------------------------------------
DEFAULT $gtmdir/$gtmver/g/gtm.dat
BG DYN 4096 5000 10000 GLOB=1000
LOCK= 40
RES = 0
ENCR=OFF
*** MAP ***
- - - - - - - - - - Names - - - - - - - - - -
From Up to Region / Segment / File(def ext: .dat)
-------------------------------------------------------------------------------------------------------
% ... REG = DEFAULT
SEG = DEFAULT
FILE = $gtmdir/$gtmver/g/gtm.dat
LOCAL LOCKS REG = DEFAULT
SEG = DEFAULT
FILE = $gtmdir/$gtmver/g/gtm.datThere 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 name space. The NAMES section of the Global Directory partitions the name space so that different globals reside in different files. While each M global can reside in only one file, each 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 all the M global variables; 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 local locks. 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 Alloc ALLOCATION AutoSwitch AUTOSWITCHLIMIT Block BLOCK_SIZE Def Coll COLLATION_DEFAULT Exten EXTENSION_COUNT File FILE_NAME GLOB GLOBAL_BUFFER_COUNT Journaling [NO]JOURNAL KeySize KEY_SIZE LOCK LOCK_SPACE NullSubs NULL_SUBSCRIPTS StandardNullColl STDNULLCOLL RecSize RECORD_SIZE RES RESERVED_BYTES Region REGION Typ DYNAMIC_SEGMENT
Once you have installed GT.M and verified its operation, create a Global Directory based on your needs. To create this customized Global Directory, use the appropriate GDE commands and qualifiers to build the 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 control 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 128 2048 2048 8388600For more information about journaling, see the section on the JOURNAL qualifier in this chapter and Chapter 6: “GT.M Journaling”.
