This section describes the GDE commands. GDE allows abbreviations of commands. The section describing each command provides the minimum abbreviation for that command and a description of any qualifiers that are not object-related. The section discussing the object-type describes all the associated object-related qualifiers.
The general format for GDE commands is:
command [-object-type] [object-name] [-qualifier]
where:
-object-typeIndicates whether the command operates on a -N[AME] space, -R[EGION], or -S[EGMENT].
object-nameSpecifies the name of the N[AME] space, R[EGION], or S[EGMENT]. Objects of different types may have the same name. Name spaces may include the wildcard operator (*) as a suffix.
-qualifierIndicates an object qualifier.
The format description for each individual command specifies required qualifiers for that command.
The @, EXIT, HELP, LOG, QUIT, SETGD, and SPAWN commands do not use this general format. For the applicable format, refer to the section explaining each of these commands.
Comments on the command line may be delimited by an exclamation mark (!).
![[Caution]](../common/images/caution.jpg) | Caution |
|---|---|
An exclamation mark not enclosed in quotation marks ("") causes GDE to ignore the rest of that input line. |
To ensure that GT.M properly interprets the name of a file you specify as part of a command line, file-names must either appear as the last item on the command line or be surrounded by quotation marks. Because UNIX file naming conventions permit the use of virtually any character in a file-name, once a qualifier such as -FILE_NAME or -LOG introduces a file-name and the first character after the equal sign is not a quotation mark, GT.M treats the entire remainder of the line as the file-name. When using quotation marks around file-names, GDE interprets a pair of embedded quotation marks as a single quotation mark within the file-name. Note that the use of Ctrl or punctuation characters such as exclamation mark (!), asterisk (*), or comma (,) in a file-name creates subsequent significant operational file management challenges.
All GT.M and GDE commands and qualifiers may be entered in either upper or lower case at the command prompt. However, when you SHOW your current Global Directory, note that GDE abides by the following case conventions:
Region and segment names always display in uppercase
Name space object name-always appears in case in which it was entered.
File-name-always appears in case in which it was entered.
![[Note]](../common/images/note.jpg) | Note |
|---|---|
The .dat extension is appended to the file-name when the database file is created, but never appears in the Global Directory listing, unless you entered it that way. |
The descriptions of these commands and qualifiers appear in various cases and fonts throughout this documentation. This section describes the conventions used in describing these commands and qualifiers.
In text: all GT.M commands and qualifiers appear in uppercase.
In examples: the entire command line is shown in lower case, and appears in bold typewriter font.
The @ command executes a GDE command file. Use the @ command to execute GDE commands stored in a text file.
The format of the @ command is:
@file-name
The file-name specifies the command file to execute. Use the file-name alone for a file in the current working directory, or specify the relative path, or the full path.
GDE executes each line of the command file as if it were entered at the terminal.
Example:
GDE> @standard
This command executes the GDE commands in the file to standard in the current working directory. standard should contain GDE commands; comments should start with an exclamation mark (!).
The ADD command inserts a new name, region, or segment into the Global Directory.
The format of the ADD command is one of the following:
A[DD]-N[AME] name-space -R[EGION]=region-name A[DD]-R[EGION] region-name -D[YNAMIC]=segment-name [-REGION-qualifier...] A[DD]-S[EGMENT] segment-name [-SEGMENT-qualifier...] -F[ILE_NAME]=file-name
The ADD command requires specification of an object-type and object-name. GDE supplies default values from the templates for qualifiers not explicitly supplied in the command.
Name spaces and file-names are case-sensitive; other objects are not case-sensitive.
Example:
GDE> add -segment temp -file_name=scratch
This command creates a segment-name TEMP and maps it to the file scratch.dat in the current working directory. However, if you specify scratch is as the file-name, in other words specify it in the form of an environment variable, GT.M finds the file using the translation of that environment variable.
The CHANGE command alters the name-to-region or region-to-segment mapping and /or the environment for a region or segment.
The format of the CHANGE command is:
C[HANGE]-N[AME] name-space -R[EGION]=new-region C[HANGE]-R[EGION] region-name [-REGION-qualifier...] C[HANGE]-S[EGMENT] segment-name [-SEGMENT-qualifier...]
The CHANGE command requires specification of an object-type and object-name.
Once you exit GDE, mapping changes take effect for any subsequent image activation (for example, the next RUN or the mumps -direct command). Changes to database parameters only take effect for new database files created with subsequent MUPIP CREATE commands that use the modified Global Directory. Use the MUPIP SET command (or in some cases DSE) to change characteristics of existing database files.
Example:
GDE> change -region master -dynamic=temp -key=100
This command changes the region master to use the segment temp and establishes a maximum KEY_SIZE of 100 characters for the next creation of a file for this region. The segment change takes effect the first time the system uses the Global Directory after the GDE session EXITs, while the KEY_SIZE change takes effect after the next MUPIP CREATE that creates a new database file for segment temp.
The DELETE command removes a name, region, or segment from the Global Directory. The DELETE command does not delete any actual data. However, GT.M does not access database files that do not have mapped global variables except through extended references using an alternative global directory that does not map to them. Note that GT.M replication does not support global updates made with extended references, unless they actually map to the same file as they would with the master global directory of the instance.
The format of the DELETE command is:
D[ELETE]-N[AME] name-space D[ELETE]-R[EGION] region-name D[ELETE]-S[EGMENT] segment-name
The DELETE command requires specification of an object-type and object-name.
Deleting a name removes the name-to-region mapping. Deleting a region unmaps all names mapped to the region. Deleting a segment unmaps the region mapped to the segment.
You may map the deleted names to another region or the deleted region to another segment using the CHANGE command.
The default name-space (*) cannot be deleted.
Example:
GDE> del -name T*
This command deletes the explicit mapping of all global names starting with the letter "T." This command does not delete any global variables. However, it may make preexisting globals starting with the letter "T" invisible, at least while using this global directory, because the T* global names map to the default namespace going forward.
The EXIT command writes all changes made in the current GDE editing session to the Global Directory and terminates the current editing session.
The format of the EXIT command is:
E[XIT]
GDE performs a full verification test (VERIFY) on the data. If the verification succeeds, GDE writes the new Global Directory to file system and issues a verification message.
If the verification fails, GDE displays a listing of all unverifiable mappings and waits for corrections. Make appropriate corrections, or leave the Global Directory in its original, unedited state by using the QUIT command.
If you have not made any changes to the Global Directory, GDE does not save a new Global Directory unless the original global directory had an older format which GDE has automatically upgraded. Note that while GDE upgrades older global directories to the current version, there is no facility to downgrade global directories to prior versions, so you should always save copies of any global directories that might be needed to retrieve archival data.
The HELP command displays online information about GDE commands and qualifiers.
The format of the HELP command is:
H[ELP] [topic...]
where topic specifies the GDE command for which you want information. If you omit the topic, GDE prompts you for it.
The LOCKS command specifies the region into which GT.M maps locks on resource names not starting with a caret symbol (^). GDE maps locks on resource names, starting with a caret symbol (^), to the database region mapped for the global variable name matching the resource name.
The format of the LOCKS command is:
LOC[KS] -R[EGION]=region-name
The LOCKS -REGION= qualifier allows specification of a region for local locks. By default, GDE maps local locks to the default region DEFAULT.
Example:
GDE> lock -region=main
This command maps all locks on resource names that don't start with the caret symbol, "^" to the region main.
The LOG command creates a log file of all GDE commands and displays for the current editing session. Because the system places an exclamation point (!) (i.e., the comment symbol) before all display lines that are not entered by the user. In the log, the log can be used with the @ symbol as a command procedure.
The format of the LOG command is:
LOG LOG -ON[=file-name] LOG -OF[F]
The LOG command, without a qualifier, reports the current status of GDE logging. The LOG command displays a message showing whether logging is in effect and the specification of the current log file for the GDE session.
The log facility can be turned on and off using the -ON or -OFF qualifiers any time during a GDE session. However, GDE closes the log files only when the GDE session ends.
The -ON qualifier has an optional argument of a file, which must identify a legal UNIX file. If LOG -ON has no file-argument, GDE uses the previous log file for the editing session. If no log file has previously been specified during this editing session, GDE uses the default log file GDELOG.LOG.
Example:
GDE> log -on="standard.log"
This command turns on logging of the session and directs the output to standard.log.
The QUIT command ends the current editing session without saving any changes to the Global Directory. GDE does not update the Global Directory file.
The format of the QUIT command is:
Q[UIT]
If the session made changes to the Global Directory, GDE issues a message warning that the Global Directory has not been updated.
The RENAME command allows you to change a name-space, the name of a region, or the name of a segment.
The format of the RENAME command is:
R[ENAME]-N[AME] old-name new-name R[ENAME]-R[EGION] old-region-name new-region-name R[ENAME]-S[EGMENT] old-segment-name new-segment-name
The RENAME command requires specification of an object-type and two object-names.
When renaming a region, GDE transfers all name mappings to the new region. When renaming a segment, GDE transfers the region mapping to the new segment.
Example:
GDE> rename -segment stable table
This command renames segment stable to table and shifts any region mapped to stable so it is mapped to table.
The SETGD command closes out edits on one Global Directory and opens edits on another.
The format of the SETGD command is:
SE[TGD] -F[ILE]=file-name [-Q[UIT]]
The -FILE=file-name specifies a different Global Directory file. When you provide a file-name without a full or relative pathname GDE uses the current working directory; if the file is missing an extension, then GDE defaults the type to .gld.
The -QUIT qualifier specifies that any changes made to the current Global Directory are not written and are lost when you change Global Directories.
SETGD changes the Global Directory that GDE is editing. If the current Global Directory has not been modified, or the -QUIT qualifier appears in the command, the change simply occurs. However, if the current Global Directory has been modified, GDE verifies the Global Directory, and if the verification is successful, writes that Global Directory. If the verification is not successful, the SETGD fails.
Example:
GDE> SETGD -f="temp"
This changes the Global Directory being edited to temp. The quotation marks around the file name identifies the name of the file unequivocally to UNIX. If the -f is the final qualifier on the line, then the quotation marks are unnecessary.
The SHOW command displays information contained in the Global Directory about names, regions, and segments.
The format of the SHOW command is:
SH[OW] -C[OMMAND] -F[ILE]=[gde-command-file] SH[OW] -N[AME] [name-space] SH[OW] -R[EGION] [region-name] SH[OW] -S[EGMENT] [segment-name] SH[OW] -M[AP] [R[EGION]=region-name] SH[OW] -T[EMPLATE] SH[OW] -A[LL]
-COMMAND: Displays GDE commands that recreate the current Global Directory state.
-F[ILE]=gde-command-file: Optionally specifies a file to hold the GDE commands produced by -COMMAND. -FILE must must always appear after -COMMAND.
-NAME, -REGION, -SEGMENT, -MAP, -TEMPLATE, and -ALL are qualifiers that cause GDE to display selected portions of the Global Directory as follows:
-MAP: Displays the current mapping of all names, regions, segments, and files. This qualifier corresponds to the section of the SHOW report titled ***MAP***. The output of a SHOW -MAP may be restricted to a particular region by specifying a -REGION qualifier with a region name argument.
-TEMPLATE: Displays the current region and segment templates. This qualifier corresponds to the section of the SHOW report titled:
***TEMPLATES***
-ALL: Displays the entire Global Directory. This qualifier corresponds to displaying "all" sections of the SHOW report:
***TEMPLATES***, ***NAMES***, ***REGIONS***, ***SEGMENTS***, ***MAP***.
By default, SHOW displays -ALL.
If you want to print the Global Directory, create a log file by executing LOG -ON= before executing the SHOW command. The -LOG command captures all the commands entered and output. You can print the log file if you want a hard copy record.
If you want to export the current Global Directory state, create a GDE command file with the SHOW -COMMAND -FILE=gde-command-file and run it in the target environment.
Example:
GDE> show -template
*** 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
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 = 40This displays only the TEMPLATES section of the Global Directory.
GDE>SHOW -command TEMPLATE -SEGMENT -ACCESS_METHOD=MM -BLOCK_SIZE=4096 -ALLOCATION=5000 -EXTENSION_COUNT=10000 -LOCK_SPACE=40 -RESERVED_BYTES=0-DEFER TEMPLATE -SEGMENT -ACCESS_METHOD=BG -BLOCK_SIZE=4096 -ALLOCATION=5000 -EXTENSION_COUNT=10000 -LOCK_SPACE=40 -RESERVED_BYTES=0 -GLOBAL_BUFFER_COUNT=1000 TEMPLATE -REGION -RECORD_SIZE=4080 -KEY_SIZE=255 -NULL_SUBSCRIPTS=NEVER -STDNULLCOLL TEMPLATE -REGION -JOURNAL=(BEFORE_IMAGE,BUFFER_SIZE=128,ALLOCATION=2048,EXTENSION=2048,AUTOSWITCHLIMIT=8388600) ! LOCKS -REGION=DEFAULT CHANGE -REGION DEFAULT -DYNAMIC=DEFAULT -COLLATION_DEFAULT=0 -RECORD_SIZE=4080 -KEY_SIZE=255 -NULL_SUBSCRIPTS=NEVER -STDNULLCOLL -JOURNAL=(BEFORE_IMAGE,BUFFER_SIZE=128,ALLOCATION=2048,EXTENSION=2048,AUTOSWITCHLIMIT=8388600, FILE="$gtmdir/$gtmver/g/gtm.mjl") ! CHANGE -SEGMENT DEFAULT -ACCESS_METHOD=BG -BLOCK_SIZE=4096 -ALLOCATION=5000 -EXTENSION_COUNT=10000 -LOCK_SPACE=40 -RESERVED_BYTES=0 -GLOBAL_BUFFER_COUNT=1000 -FILE=$gtmdir/$gtmver/g/gtm.dat !
This command displays the GDE commands to recreate the current global directory state.
Example:
GDE> show -template
*** 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 = 4This displays only the TEMPLATES section of the Global Directory.
The TEMPLATE command maintains a set of -REGION and -SEGMENT qualifier values for use as templates when ADDing regions and segments. When an ADD command omits qualifiers, GDE uses the template values as defaults.
GDE maintains a separate set of -SEGMENT qualifier values for each ACCESS_METHOD. When GDE modifies the ACCESS_METHOD, it activates the appropriate set of TEMPLATEs and sets all unspecified qualifiers to the template defaults for the new ACCESS_METHOD. Use the GDE SHOW command to display qualifier values for all ACCESS_METHODs.
The format of the TEMPLATE command is:
T[EMPLATE] -R[EGION] [-REGION-qualifier...] T[EMPLATE] -S[EGMENT] [-SEGMENT-qualifier...]
The TEMPLATE command requires specification of an object-type.
Example:
GDE> template -segment -allocation=200000
This command modifies the segment template so that any segments ADDed after this time produce database files with an ALLOCATION of 200,000 GDS blocks.
The VERIFY command validates information entered into the current Global Directory. It checks the name-to-region mappings to ensure all names map to a region. The VERIFY command checks region-to-segment mappings to ensure each region maps to a segment, each segment maps to only one region, and the segment maps to a UNIX file. The EXIT command implicitly performs a VERIFY -ALL.
The format of the VERIFY command is:
V[ERIFY] V[ERIFY] -N[AME] [name-space] V[ERIFY] -R[EGION] [region-name] V[ERIFY] -S[EGMENT] [segment-name] V[ERIFY] -M[AP] V[ERIFY] -T[EMPLATE] V[ERIFY] -A[LL]
The object-type is optional. -MAP, -TEMPLATE, and -ALL are special qualifiers used as follows:
-MAPChecks that all names map to a region, all regions map to a segment, and all segments map to a file.
-TEMPLATEChecks that all templates currently are consistent and useable.
-ALLChecks all map and template data.
VERIFY with no qualifier, VERIFY -MAP, and VERIFY -ALL each check all current information.
Example:
GDE> verify -region regis
This command verifies the region regis.
