Global Utilities

Global Utilities
Prev	Chapter 10. Utility Routines	Next

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.

The "%" sign has been removed from the topic headings below, intentionally.

%G

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.

Prompts

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	*

Examples of %G

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.

%GC

The %GC utility copies values of globals from one global to another. It is useful for testing and for moving misfiled data.

Prompts

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.

Examples of %GC

Example:

GTM>do ^%GC
Global copy
Show copied nodes <Yes>? <RETURN>
From global ^b
To global ^g
^g(1)=1
^g(2)=2
^g(3)=3
Total 3 nodes copied.
From global ^<RETURN> 
GTM>

This example makes a copy of the nodes and values of global ^b to global ^g.

%GCE

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.

Prompts

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.

Examples of %GCE

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.

%GD

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.

Prompts

Global^: Requests (using %GSEL) a global name with optional wildcards or a range of names; <RETURN> terminates %GD.

Examples of %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.

%GED

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.

Prompts

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.

Examples of %GED

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

%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.

Prompts

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.

Examples of %GI

Example:

GTM>DO ^%GI
Global Input Utility
Input device <terminal>: DATA.GBL
Saved from user's development area
GT.M 07-MAY-2010 14:14:09
OK <Yes>? <RETURN>
^IB ^INFO
Restored 10 nodes in 2 globals
GTM>

%GO

%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.

Prompts

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.

Examples of %GO

Example:

GTM>DO ^%GO
Global Output Utility
Global ^A
^A
Current total of 1 global
Global ^<RETURN>
Header label: Revenues May, 2010
Output Format: GO or ZWR: ZWR
Output device: /usr/dev/out.go
^A
Total of 1 node in 1 global.
GTM>

%GSE

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.

Prompts

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.

Examples of %GSE

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.

%GSEL

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. %GSEL interprets a percent sign (%) in the first position of a global name literally.

A colon (:) between two globals specifies a range.

A minus sign (-) or quotation mark (') preceding a global name removes that global from the %ZG array. A question mark (?) provides online help, and "?D" displays global names currently in the array.

Utility Labels

CALL: Runs %GSEL without reinitializing %ZG.

Output Variables

%ZG Contains array of all globals selected.

Prompts

Global^: Requests a global name with optional wildcards or a range of names.

Examples of %GSEL

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 ^ <RETURN>
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 ^<RETURN> 
GTM>ZWRITE
%ZG=1
%ZG("^a")=""
GTM>DO CALL^%GSEL
Global ^?d
^a
Global ^iv
^iv
Current total of 2 globals.
Global ^<RETURN>
GTM>ZWRITE
%ZG=2
%ZG("^a")=""
%ZG("^iv")=""
GTM>

This example uses CALL^%GSEL to add to an existing %ZG array of selected globals.

Prev	Up	Next
String Utilities	Home	Routine Utilities