The Global utilities are:
%G: Displays global variables and their values.
%GC: Copies a global or global sub-tree.
%GCE: Replaces a specified value or part of a value in a set of variables.
%GD: Displays existing globals in the current global directory without displaying their values or descendants.
%GED: Provides full-screen editing capabilities for global variables and values.
%GI: Loads global data from a sequential file into a GT.M database.
%GO: Extracts global data from a GT.M database into a sequential file.
%GSE: Displays global variables and their values when the values contain a specified string or number.
%GSEL: Selects globals.
%ZSHOWVTOLCL: Restores ZSHOW "V":gvn data into its original local variables.
The "%" sign has been removed from the topic headings below, intentionally.
The %G utility displays names, descendants and values of globals currently existing in the database. Use %G to examine global variables and their values. Enter a question mark (?) at any prompt to display help information.
Output Device: <terminal>:
Requests a destination device; defaults to the principal device.
List ^Requests the name, in ZWRITE format, of a global to display.
For descriptions of valid input to the List ^ prompt, see the following table.
Arguments for %G and %GED:
|
ITEM |
DESCRIPTION |
EXAMPLES |
|---|---|---|
Global name |
M name |
SQL, %5 |
|
M pattern form to match several globals |
?1"A".E, ?1A1"TMP" |
|
|
asterisk to match all global names |
* |
|
|
global directory lists request |
?D |
|
|
Subscripts following a global name in parentheses |
M expr |
"rick",599,X, $e(a,7)*10 |
|
[expr]:[expr] for a range |
1:10, "A":"F", :4, PNT:, : |
|
|
M pattern form to match certain subscripts |
1"E"3N, ?1"%F".E |
|
|
* descendants |
* |
Example:
GTM>do ^%G Output Device: <terminal>: <RETURN> List ^C ^C="CLASS" ^C(1)="MARY" ^C(1,2)="MATH" ^C(1,2,1)=80 ^C(1,3)="BIO" ^C(1,3,1)=90 ^C(2)="JOHN" ^C(3)="PETER" List ^ <RETURN> GTM>
This example lists the nodes of global ^C. %G displays the global and its descendants and values, if the node exists.
Example:
GTM>do ^%G Output Device: <terminal>: <RETURN> List ^C(1) ^C(1)="MARY"
This example lists only the node entered and its value.
Example:
GTM>do ^%G Output Device: <terminal>: <RETURN> List ^C(1,*) ^C(1)="MARY" ^C(1,2)="MATH" ^C(1,2,1)=80 ^C(1,3)="BIO" ^C(1,3,1)=90 List ^ <RETURN> GTM>
This example uses the asterisk (*) wildcard to list node ^C(1), its descendants and values.
Example:
GTM>do ^%G Output Device: <terminal>: <RETURN> List ^?D Global Directory Global ^ <RETURN> ^C ^D ^S ^Y ^a Total of 5 globals. List ^ GTM>
This example specifies "?D" as the global that invokes the %GD utility. %GD displays existing globals in the current global directory without displaying their values or descendants.
The %GC utility copies values of globals from one global to another. It is useful for testing and for moving misfiled data.
Show copied nodes <Yes>?:
Asks whether to display the "source nodes" on the principal device.
From global: ^Requests a global variable name from which to copy variable and descendants.
To global: ^Request a global variable name to receive the copy.
The %GCE utility changes every occurrence of a string within the data of selected global nodes to a replacement string. ^%GCE changes the string in each place it occurs, even if it forms part of a longer string. For example, changing the string 12 to 55 changes 312 to 355.
%GCE displays the name of each global as it is processed. You can suppress the output of the names of globals in which no changes are made by using the QUIET utility label.
Global^: Requests (using %GSEL) the name(s) of the globals to change; <RETURN> ends selection.
Old string: Requests an existing string to find.
New string: Requests the replacement string.
Show changed nodes <Yes>?:
Asks whether to display the before and after versions of modified nodes on the current device.
Output Device: <terminal>:
Requests a destination device; defaults to the principal device.
QUIET: Only displays the names of globals in which changes are made.
Example:
GTM>DO ^%GCE Global Change Every occurrence Global ^a:^b ^a ^b Current total of 2 globals. Global ^ <RETURN> Old String: hello New String: good-bye Show changed nodes <Yes>?: <RETURN> Output Device: <terminal>: <RETURN> ^a No changes made in total 1 nodes. ^b ^b(10) Was : hello Adam Now : good-bye Adam 1 changes made in total 25 nodes. Global ^ <RETURN> GTM>
This example searches a range of globals and its nodes for the old string value entered. GT.M searches each global and displays the changes and number of nodes changed and checked.
Example:
GTM>set ^b(12)=12 GTM>set ^b(122)=122 GTM>set ^b(30)=656 GTM>set ^b(45)=344 GTM>set ^b(1212)=012212 GTM>DO ^%GCE Global Change Every occurrence Global ^b Current total of 1 global. Global ^ <RETURN> Old String: 12 New String: 35 Show changed nodes <Yes>?: <RETURN> Output Device: <terminal>: <RETURN> ^b(12) Was : 12 Now : 35 ^b(122) Was : 122 Now : 352 ^b(1212) Was : 12212 Now : 35235 5 changes made in total 5 nodes Global ^ <RETURN> GTM>DO ^%G Output device: <terminal>: <RETURN> List ^b ^b(12)=35 ^b(30)=656 ^b(45)=344 ^b(122)=352 ^b(1212)=35235
This example shows that executing %GCE replaces all occurrences of "12" in the data stored in the global ^b with "35" and displays the affected nodes before and after the change. Then the %G demonstrates that "12" as data was changed, while "12" in the subscripts remained untouched.
The %GD utility displays existing globals in the current global directory without displaying their values or descendants.
%GD prompts for a global name and redisplays the name if that global exists.
%GD interprets a percent sign (%) in the first position of a global name literally.
%GD allows the wildcard characters asterisk (*) and question mark (?). The wildcards carry their usual meanings, an asterisk (*) denotes a field or a portion of a field, and a question mark (?) denotes a single character.
A colon (:) between two globals specifies a range. %GD displays existing globals within that range.
After each selection %GD reports the number of globals selected by the input.
A question mark (?) entered at a prompt displays help information. Pressing <RETURN> exits %GD.
Global^: Requests (using %GSEL) a global name with optional wildcards or a range of names; <RETURN> terminates %GD.
Example:
GTM>DO ^%GD Global directory Global ^k ^k Total of 1 global. Global ^ <RETURN> GTM>
This example verifies that ^k exists in the global directory.
Example:
GTM>DO ^%GD Global directory Global ^C:S ^C ^D ^S Total of 3 globals Global ^ <RETURN> GTM>
This example displays a range of globals that exist from ^C to ^S.
Example:
GTM>DO ^%GD Global directory Global ^* ^C ^D ^S ^Y ^a Total of 5 globals Global ^ <RETURN> GTM>
The asterisk (*) wildcard at the Global ^ prompt displays all globals in the global directory.
The %GED utility enables you to edit the globals in a full-screen editor environment. %GED invokes your default editor as specified by the EDITOR environment variable. When you finish the edit, use the [save and] exit command(s) of the editor you are using, to exit.
Edit^: Requests the name, in ZWRITE format, of a global to edit.
Only one global can be edited at a time with %GED, see “ Prompts” for descriptions of valid input for subscripts.
Example:
GTM>DO ^%GED edit ^ b Beginning screen: ^b(1)="melons" ^b(2)="oranges" ^b(3)="bananas" Screen with a change to ^b(1), elimination of ^b(3), and two new entries ^b(4) and ^b(5): ^b(1)="apples" ^b(2)="oranges" ^b(4)=pears ^b(5)="grapes" %GED responds: Invalid syntax: b(4)=pears return to continue: After screen: ^b(1)="apples" ^b(2)="oranges" ^b(4)="pears" ^b(5)="grapes" %GED responds: node: ^b selected: 3 changed: 1 added: 2 killed: 1 Edit ^ <RETURN> GTM>
This example shows the use of the full-screen editor to change, add, and delete (kill) nodes. When you exit from the editor, %GED checks the syntax and reports any problems. By pressing <RETURN>, return to the full-screen editor to fix the error. At the end of the session, %GED reports how many nodes were selected, changed, killed, and added.
%GI loads global variable names and their corresponding data values into a GT.M database from a sequential file. %GI uses the global directory to determine which database files to use. %GI may operate concurrently with normal GT.M database access. However, a %GI does not use M LOCKs and may produce application-level integrity problems if run concurrently with many applications.
In many ways, %GI is similar to MUPIP LOAD. The format of the input file (GO or ZWRITE) is automatically detected. Like MUPIP LOAD, %GI does not load GT.M trigger definitions. Unlike MUPIP LOAD, %GI invokes triggers just like any other M code, which may yield results other than those expected or intended.
^%GI loads records having up to 1MiB string length.
Enter input file:
Requests name of a file; file should be in standard Global Output (GO) format or Zwrite (ZWR) format .
OK <Yes>?: Asks for confirmation.
%GO copies specified globals from the current database to a sequential output file in either GO or ZWR format. Use %GO to back up specific globals or when extracting data from the database for use by another system. %GO uses the global directory to determine which database files to use. %GO may operate concurrently with normal GT.M database access. To ensure that a %GO reflects a consistent application state, suspend database updates to all regions involved in the extract.
In many ways, the %GO utility is similar to MUPIP EXTRACT (-FORMAT=GO or -FORMAT=ZWR). Like MUPIP EXTRACT, %GO does not extract and load GT.M trigger definitions.
Global^: Requests (using %GSEL) the name(s) of the globals to search; <RETURN> ends selection.
Header label: Requests text describing contents of extract file.
Output Format: GO or ZWR:
Requests the format to output the data. Defaults to ZWR.
Output Device: <terminal>:
Requests destination device, which may be any legal filename.
The %GSE utility finds occurrences of a string within the data values for selected global nodes and displays the variable name and data on a specified output device.
%GSE displays the name of each global as it is processed. You can suppress the output of the names of globals in which the search string is not found by using the QUIET utility label.
Output Device: <terminal>:
Requests a destination device; defaults to the principal device.
Global^: Requests (using %GSEL) the name(s) of the globals to search; <RETURN> ends selection.
String: Requests a search string.
Example:
GTM>do ^%GSE Global Search For Every Occurence Output device: <terminal>: Test.dat Global ^a <RETURN> ^a Current total of 1 global. Global ^ <RETURN> String: Hello ^a ^a(10) Hello Adam Total 1 matches found in 25 nodes. Global ^ <RETURN> GTM>
This example searches global ^a for the string "Hello" and displays all nodes that contain that string.
The %GSEL utility selects globals. %GSEL creates a variable %ZG that is a local array of the selected globals. After each selection %GSEL displays the number of globals in %ZG.
%GSEL accepts the wildcard characters asterisk (*), percent sign (%) and question mark (?). The wildcards carry their usual meanings, asterisk (*) denoting a field or a portion of a field, and question mark (?) or percent sign (%) denoting a single character.
The wildcards question mark (?) and percent sign (%) lose their meanings when in the first position of a global name:
When '%' is in the first position of a global name, %GSEL interprets it literally. For example, "%*" means all global names starting with '%'.
When you specify only '?' as a global name, %GSEL displays the online help.
When you specify a '?' followed by a 'D' or 'd', %GSEL displays the global names currently in the %ZG array.
%GSEL produces an error if there is '?' at the first position of a global name followed by any character other than 'D' or 'd'. For example, "?a" produces an error.
A colon (:) between two globals specifies a range. %GSEL produces an error if you specify a '?' as the first character after a colon (:).
A minus sign (-) or quotation mark (') as the first character will cause the search to remove the proceding global or range from the %ZG array.
Example:
GTM>DO ^%GSEL
Global ^C
^C
Current total of 1 global.
Global ^*
^S ^Y ^c ^class
Current total of 5 globals.
Global ^-S
^S
Current total of 4 globals.
Global ^'Y
^Y
Current total of 3 globals.
Global ^?D
^C ^c ^class
Current total of 3 globals.
Global ^
GTM>ZWRITE
%ZG=3
%ZG("^C")=""
%ZG("^c")=""
%ZG("^class")=""
GTM>
This example adds and subtracts globals from the list of selected globals. "?D" displays all globals selected. ZWRITE displays the contents of the %ZG array.
Example:
GTM>DO ^%GSEL
Global ^a
^a
Current total of 1 global.
Global ^
GTM>ZWRITE
%ZG=1
%ZG("^a")=""
GTM>DO CALL^%GSEL
Global ^?d
^a
Current total of 1 global.
Global ^iv
^iv
Current total of 2 globals.
Global ^
GTM>ZWRITE
%ZG=2
%ZG("^a")=""
%ZG("^iv")=""
GTM>
This example uses CALL^%GSEL to add to an existing %ZG array of selected globals.
The %ZSHOWVTOLCL utility restores ZSHOW "V":gvn data into its original local variables. Invoke this utility with $ECODE set to the empty string. This utility facilitates automated restoration even of nodes exceeding the maximum record size of the global.