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]](images/note.jpg) | |
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. |
MUPIP CREATE uses a global directory to create new database files. At other times, the global directory is used only to map global variable names to database files. So, if you change the global directory, the database file is not changed and vice versa.
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 256 64 NEVER N N
Segment Active Acc Typ Block Alloc Exten Options
------------------------------------------------------------------------------
<default> * BG DYN 1024 100 100 GLOB =1024
LOCK = 40
<default> MM DYN 1024 100 100 DEFER
LOCK = 40
*** NAMES ***
Global Region
------------------------------------------------------------------------------
* DEFAULT
Gharial REPTILES
Hoopoe BIRDS
Jacare REPTILES
Trogon BIRDS
*** REGIONS ***
Dynamic Def Rec Key Null Standard
Region Segment Coll Size Size Subs NullColl Journaling
------------------------------------------------------------------------------
BIRDS BIRDS 0 256 64 NEVER N N
DEFAULT DEFAULT 0 256 64 NEVER N N
REPTILES REPTILES 0 256 64 NEVER N N
*** SEGMENTS ***
Segment File (def ext: .dat) Acc Typ Block Alloc Exten Options
------------------------------------------------------------------------------
BIRDS flap.dat BG DYN 1024 100 100 GLOB=1024
LOCK= 40
RES = 0
ENCR=OFF
DEFAULT mumps.dat BG DYN 1024 100 100 GLOB=1024
LOCK= 40
RES = 0
ENCR=OFF
REPTILES creep.dat BG DYN 1024 100 100 GLOB=1024
LOCK= 40
RES = 0
ENCR=OFF
*** MAP ***
- - - - - - - - - - Names - - - - - - - - - -
From Up to Region / Segment / File(def ext: .dat)
------------------------------------------------------------------------------
% Gharial REG = DEFAULT
SEG = DEFAULT
FILE = mumps.dat
Gharial Gharial0 REG = REPTILES
SEG = REPTILES
FILE = creep.dat
Gharial0 Hoopoe REG = DEFAULT
SEG = DEFAULT
FILE = mumps.dat
Hoopoe Hoopoe0 REG = BIRDS
SEG = BIRDS
FILE = flap.dat
Hoopoe0 Jacare REG = DEFAULT
SEG = DEFAULT
FILE = mumps.dat
Jacare Jacare0 REG = REPTILES
SEG = REPTILES
FILE = creep.dat
Jacare0 Trogon REG = DEFAULT
SEG = DEFAULT
FILE = mumps.dat
Trogon Trogon0 REG = BIRDS
SEG = BIRDS
FILE = flap.dat
Trogon0 ... 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 below.
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.
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.
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.
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.
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 Comman Summary".
Abbreviation Full Form Acc ACCESS_METHOD Alloc ALLOCATION 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 [NO]NULL_SUBSCRIPTS 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(ext:.mjl) Before Buff Alloc Exten -------------------------------------------------------------- DEFAULT <based on DB file> Y 128 100 100
For more information about journaling, see the section on the JOURNAL qualifier in this chapter and Chapter 6: “GT.M Journaling”.