GDE Overview

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]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:

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 Auto
 Region                                     Coll     Size  Size Subs      Coll Jnl on Err Rndwn Taper AutoDB Stats Crit Del
 ---------------------------------------------------------------------------------------------------------------------------
 <default>                                     0      256    64 NEVER     N    N   N      N     Y     N      Y     Sep  N
 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 Auto
 Region                          Segment                         Coll     Size  Size Subs      Coll Jnl on Err Rndwn Taper AutoDB Stats Crit Del
 ------------------------------------------------------------------------------------------------------------------------------------------------
 DEFAULT                         DEFAULT                            0      256    64 NEVER     N    N   N      N     Y     N      Y     Sep  N
                                *** 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:

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
AutoDel                -[NO]AUTODELETE
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 ChapterA 6: a??GT.M Journalinga??.

PrevA UpA Next
A HomeA