The routine utilities are:
%FL: Lists the comment lines at the beginning of source programs.
%RANDSTR: Generates a random string.
%RCE: Replaces every occurrence of a text string with another text string in a routine or a list of routines.
%RD: Lists routine names available through $ZROUTINES.
%RI: Loads routines from RO file to *.m files in GT.M format.
%RO: Writes M source code for one or more routines to a sequential device such as a terminal, or a disk file.
%RSE: Searches for every occurrence of a text string in a routine or a list of routines.
%RSEL: Selects M routines and places their directories and names in a local array.
The "%" sign has been removed from the topic headings below, intentionally.
The %FL utility lists the comment lines at the beginning of source programs. %FL writes the routines in alphabetical order to the specified device. If the output device is not the principal device, %FL displays the name of each routine on the principal device as it writes the routine to the output device.
%FL uses %RSEL to select routines. For more information, see “ %RSEL”.
Routine: Requests the name(s) of the routines (using %RSEL); <RETURN> ends the selection.
Output Device: <terminal>:
Requests a destination device; defaults to the principal device.
Example:
GTM>DO ^%FL First Line Lister Routine: %D %D Current total of 1 routine. Routine: %GS* %GSE %GSEL Current total of 3 routines. Routine: - %D %D Current total of 2 routines. Routine: ?D %GSE %GSEL Routine: <RETURN> Output Device: <RETURN> Routine First Line Lister Utility GT.M 21-MAR-2002 16:44:09 %GSE %GSE;GT.M %GSE utility - global search ; %GSEL; %GSEL;GT.M %GSEL utility - global select into a local array ; ;invoke ^%GSEL to create %ZG - a local array of existing globals, interactively ; Total 5 lines in of 2 routines. GTM>
This example selects %D, then selects %GSE and %GSEL and deselects %D. Because the example enters <RETURN> at the Output Device: <terminal>: prompt, the output goes to the principal device.
%RANDSTR generates a random string. The format %RANDSTR is:
%RANDSTR (strlen,charranges,patcodes,charset)
The random string is of length strlen from an alphabet defined by charset or by charranges and patcodes.
strlen: the length of the random string.
charranges: Range of alphabets defined by charset. By default charranges is 1:1:127. charranges uses the same syntax used for FOR loop ranges, for example, 48:2:57 to select the even decimal digits or 48:1:57,65:1:70 to select hexadecimal digits.
patcodes: specifies pattern codes used to restrict the characters to those that match the selected codes. By default, patcodes is "AN".
charset: Specifies a string of non-zero length. If specified, %RANDSTR generates the random string using the characters in charset, otherwise it takes its alphabet as specified by charranges and patcodes. If charset is of zero length, and is passed by reference, %RANDSTR() initializes it to the alphabet of characters defined by charranges and patcodes. If not specified, strlen defaults to 8, charranges defaults to 1:1:127 and patcodes to "AN".
The %RCE utility replaces every occurrence of a text string with another text string in a routine or a list of routines.
%RCE uses %RSEL to select routines. For more information, see “ %RSEL”.
%RCE prompts for a text string to replace and its replacement. %RCE searches for text strings in a case-sensitive manner. %RCE issues a warning message if you specify a control character such as a <TAB> in the text string or its replacement. %RCE confirms your selection by displaying the text string and its replacement between a left and right arrow. The arrows highlight any blank spaces that you might have included in the text string or its replacement.
Regardless of whether you select a display of every change, %RCE displays the name of each routine as it is processed. You can suppress the output of the names of routines in which no changes are made by using the QUIET and QCALL utility labels. %RCE completes processing with a count of replacements and routines changed.
Routine: Requests (using %RSEL) the name(s) of the routines to change; <RETURN> ends the selection.
Old string: Requests string to be replaced.
New string: Requests replacement string.
Show changed lines <Yes>?:
Asks whether to display the before and after versions of the modified lines on an output device.
Output Device: <terminal>:
Requests a destination device; defaults to the principal device.
QUIET: Only displays the names of routines in which changes are made.
CALL: Works without user interaction unless %ZR is not defined.
QCALL: Works without user interaction unless %ZR is not defined. Only displays the names of routines in which changes are made.
The following input variables are only applicable when invoking CALL^%RCE.
%ZR: Contains an array of routines provided or generated with %RSEL.
%ZF: Contains string to find.
%ZN: Contains a replacement string.
%ZD: Identifies the device to display the change trail, defaults to principal device. Make sure you open the device if the device is not the principal device.
%ZC: Truth-value indicating whether to display the change trail, defaults to 0 (no).
Example:
GTM>DO ^%RCE Routine Change Every occurrence Routine: BES* BEST BEST2 BEST3 BEST4 Current total of 4 routines Routine: <RETURN> Old string:^NAME New string:^STUDENT Replace all occurrences of: >^NAME< With >^STUDENT< Show changed lines <Yes>?: <RETURN> Output Device: <RETURN> /usr/smith/work/BEST.m Was: S ^NAME=SMITH Now: S ^STUDENT=SMITH Was: S ^NAME(1)=JOHN Now: S ^STUDENT(1)=JOHN /usr/smith/work/BEST2.m /usr/smith/work/BEST3.m Was: S ^NAME=X Now: S ^STUDENT=X Was: W ^NAME Now: W ^STUDENT /usr/smith/work/BEST4.m Total of 4 routines parsed. 4 occurrences changed in 2 routines. GTM>
This example selects a list of routines that change the string "^NAME" to the string "^STUDENT," and displays a trail of the changes.
Example:
GTM>DO ^%RCE Routine Change Every occurrence Routine: BES* BEST BEST2 BEST3 BEST4 Current total of 4 routines Routine: <RETURN> Old String:<TAB> The find string contains control characters New string: <RETURN> Replace all occurrences of: ><TAB>< With: >< Show changed lines <Yes>?: N BEST BEST2 BEST3 BEST4 Total 4 routines parsed. 4 occurrences changed in 2 routines. GTM>
This example removes all occurrences of the <TAB> key from specified routines and suppresses the display trail of changes.
The %RD utility lists routine names accessible through the current $ZROUTINES. %RD calls %RSEL and displays any routines accessible through %RSEL. Use %RD to locate routines.
%RD accepts 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 in positions other than the first.
A colon (:) between two routine names specifies a range of routines. %RD displays only those routine names accessible through the current $ZROUTINES.
After each selection %RD displays the total number of routines listed.
Pressing <RETURN> exits %RD.
Routine: Requests (using %RSEL) the name(s) of the routines to list; <RETURN> ends the selection.
OBJ: Lists object modules accessible through the current $ZROUTINES.
LIB: Lists percent (%) routines accessible through the current $ZROUTINES.
SRC: Lists the source modules accessible through the current $ZROUTINES (same as %RD).
Example:
GTM>DO ^%RD Routine directory Routine: TAXES TAXES Total of 1 routine Routine:* EMP FICA PAYROLL TAXES YTD Total of 5 Routines Routine: <RETURN> GTM>
This example invokes %RD that prompts for routine TAXES and the wildcard (*). %RD lists five routines accessible through the current $ZROUTINES.
Example:
GTM>DO OBJ^%RD Routine directory Routine:* EMP FICA Total of 2 routines Routine: <RETURN> GTM>
This example invokes %RD with the label OBJ that lists only object modules accessible through the current $ZROUTINES.
Example:
GTM>DO LIB^%RD Routine directory %D %DATE %DH %G %GD %GSEL GTM>
This example invokes %RD with the LIB label that lists all the % routines accessible through the current $ZROUTINES.
Example:
GTM>DO SRC^%RD Routine directory Routine:* DATACHG Total of 1 routines Routine: <RETURN> GTM>
This example invokes %RD with the label SRC that lists only source modules accessible through the current $ZROUTINES.
%RI transforms M routines in the sequential format described in the ANSI standard into individual .m files in GT.M format. ^%RI handles code lines up to 1 MiB. Note that when a code line exceeds 8 KiB, the GT.M compiler automatically inserts a line separator and issues a warning. Use %RI to make M RO format accessible as GT.M routines.
Formfeed delimited <No>?
Requests whether lines should be delimited by formfeed characters rather than carriage returns.
Input Device: <terminal>:
Requests name of RO file containing M routines.
Output Directory:
Requests name of directory to output M routines.
Example:
GTM>DO ^%RI Routine Input utility - Converts RO file to *.m files Formfeed delimited <No>? <RETURN> Input device: <terminal>: file.ro Files saved from FILEMAN directory GT.M 07-MAY-2002 15:17:54 Output directory: /usr/smith/work/ DI DIA DIAO DIAI DIB DIBI Restored 753 lines in 6 routines. GTM>
The %RO utility writes M source code for one or more routines to a sequential device such as, a disk file or a printer. .
^%RO handles code lines up to 1 MiB. Note that when a code line exceeds 8 KiB, the GT.M compiler automatically inserts a line separator and issues a warning.
%RO uses %RSEL to select routines. For more information, see “ %RSEL”.
%RO writes the routines in alphabetical order to the specified device. %RO displays the name of each routine as it writes the routine to the device.
Routine: Requests (using %RSEL) the name(s) of the routines to output; <RETURN> ends selection.
Output device: <terminal>:
Requests a destination device; defaults to the principal device.
Header label: Requests text to place in the first of the two header records.
Strip comments <No>?:
Asks whether to remove all comment lines except those with two adjacent semicolons.
The following input variables are only applicable when invoking CALL^%RO.
%ZR: Contains an array of routines provided or generated with %RSEL.
%ZD: Identifies the device to display output, defaults to principal device.
Example:
GTM>DO ^%RO Routine Output - Save selected routines into RO file. Routine: %D %D Current total of 1 routines. Routine: -%D %D Current total of 0 routines. Routine: BEST* BEST BEST1 BEST2 Current total of 3 routines. Routine: ?D BEST BEST1 BEST2 Routine: <RETURN> Output Device: <terminal>: output.txt Header Label: Source code for the BEST modules. Strip comments <No>?:<RETURN> BEST BEST1 BEST2 Total of 53 lines in 3 routines GTM>
This example adds and subtracts %D from the selection, then adds all routines starting with "BEST" and confirms the current selection. The example sends output to the designated output file output.txt. %RO displays the label at the beginning of the output file. The first record of the header label is the text entered at the prompt. The second record of the header label consists of the word "GT.M" and the current date and time.
The %RSE utility searches for every occurrence of a text string in a routine or a list of routines.
%RSE uses %RSEL to select routines. For more information, see “ %RSEL”.
%RSE searches for text strings that are case-sensitive. %RSE issues a warning message if you specify a control character such as a <TAB> in the text string. %RSE confirms your selection by displaying the text string between a left and right arrow. The arrows display any blank spaces included in the text string.
%RSE displays the name of each routine as it is processed. You can suppress the output of the names of routines in which the search string is not found by using the QUIET and QCALL utility labels.
%RSE completes processing with a count of occurrences found.
Routine: Requests (using %RSEL) the name(s) of the routines to search; <RETURN> ends selection.
Find string: Requests string for which to search.
Output device: <terminal>:
Requests a destination device; defaults to the principal device.
QUIET: Only displays the names of routines in which the search string is found.
CALL: Works without user interaction unless %ZR is not defined.
QCALL: Works without user interaction unless %ZR is not defined. Only displays the names of routines in which the search string is found.
The following input variables are only applicable when invoking CALL^%RSE.
%ZR: Contains an array of routines provided or generated with %RSEL.
%ZF: Contains the string to find.
%ZD: Identifies the device to display the results, defaults to principal device. Make sure you open the device if the device is not the principal device.
Example:
GTM>DO ^%RSE Routine Search for Every occurrence Routine: BES* BEST BEST2 BEST3 BEST4 Current total of 4 routines Routine: <RETURN> Find string:^NAME Find all occurrences of: >^NAME< Output device: <terminal>: /usr/smith/work/BEST.m S ^NAME=SMITH S ^NAME(1)=JOHN /usr/smith/work/BEST2.m /usr/smith/work/BEST3.m S ^NAME=X W ^NAME /usr/smith/work/BEST4.m Total of 4 routines parsed. 4 occurrences found in 2 routines. GTM>
This example invokes %RSE that searches and finds a given string. The output device specifies a terminal display of all lines where the text string occurs.
Example:
GTM>DO ^%RSE Routine Search for Every occurrence Routine: BEST BEST Current total of 1 routine Routine: <RETURN> Find string:^NAME Find all occurrences of: >^NAME< Output Device: out.lis BEST GTM>
This example instructs ^%RSE to write all lines where the text string occurs to an output file, out.lis.
The %RSEL utility selects M routines. %RSEL selects routines using directories specified by the GT.M special variable $ZROUTINES. $ZROUTINES contains an ordered list of directories that certain GT.M functions use to locate source and object files. If $ZROUTINES is not defined, %RSEL searches only the current default directory. Other GT.M utilities call %RSEL.
%RSEL prompts for the name of a routine(s).
%RSEL accepts 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 in positions other than the first.
A colon (:) between two routines specifies a range.
%RSEL creates a read-write variable %ZR, which is a local array of selected routines. After each selection, %RSEL reports the number of routines in %ZR. A minus sign (-) or an apostrophe (') character preceding a routine name removes that routine from the %ZR array. A question mark (?) provides online help, and "?D" displays M routines currently in the array.
![[Note]](images/note.jpg) |
Note |
|---|---|
If a local variable %ZRSET is defined, %RSEL places the output information into a global variable (^%RSET) instead of the local variable %ZR. |
CALL: Performs %RSEL without reinitializing %ZR.
OBJ: Searches only object files.
SRC: Searches only source files (same as %RSEL).
SILENT: Provides non-interactive (batch) access to the functionality of %RSEL. The syntax is SILENT^%RSEL(pattern,label) where pattern is a string that specifies the routine names to be searched. label can be "OBJ", "SRC" or "CALL". The default is "SRC" value corresponds to ^%RSEL if invoked interactively.
The following input variables are only valid when invoking CALL^%RSEL:
%ZE: Contains the file extension, usually either .m for source files or .o for object files.
%ZR: As input, contains an existing list of routines to be modified.
%ZRSET: On being set, requests %RSEL to place the output in the global variable ^%RSET.
%ZR: As output, contains list of directories indexed by selected routine names.
^%RSET($JOB): The output global variable ^%RSET is used instead of the local variable %RD if the input variable %ZRSET is set. It is indexed by job number $JOB and the selected routine names.
Example:
GTM>DO ^%RSEL Routine: TES* TEST2 TEST3 Current total of 2 routines Routine: <RETURN> GTM>DO OBJ^%RSEL Routine:TEST? Current total of 0 routines Routine: <RETURN> GTM>ZWRITE %ZR=0
This example selects two source routines starting with "TES" as the first three characters. Then, the example invokes %RSEL at the OBJ label to select object modules only. OBJ^%RSEL returns a %ZR=0 because object modules for the TEST routines do not exist.
Example:
GTM>DO ^%RSEL
Routine: BES*
BEST BEST2 BEST3 BEST4
Current total of 4 routines
Routine: - BEST
BEST
Current total of 3 routines
Routine: ?D
BEST2 BEST3 BEST4
Routine: 'BEST2
BEST2
Current total of 2 routines
Routine: ?D
BEST3 BEST4
Routine: <RETURN>
GTM>ZWRITE
%ZR=2
%ZR("BEST3")="/usr/smith/work/"
%ZR("BEST4")="/usr/smith/test/"
GTM>
This example selects the routines using the asterisk (*) wildcard and illustrates how to tailor your selection list. Note that %ZR contains two routines from different directories.
By default, %RSEL bases the contents of %ZR on source files that have a .m extension.
Example:
GTM>DO ^%RSEL
Routine:BEST*
BEST2 BEST3
Current total of 2 routines
Routine: <RETURN>
GTM>ZWRITE
%ZR=2
%ZR("BEST2")="/usr/smith/test/"
%ZR("BEST3")="/usr/smith/test/"
This example creates a %ZR array with BEST2 and BEST3.
Example:
GTM>DO ^%RSEL
Routine:LOCK
LOCK
Current total of 1 routine
Routine: <RETURN>
GTM>ZWRITE
%ZR=1
%ZR("LOCK")="/usr/smith/work/"
GTM>DO CALL^%RSEL
Routine:BEST*
BEST2 BEST3
Current total of 2 routines
Routine: <RETURN>
GTM>ZWRITE
%ZR=3
%ZR("BEST2")="/usr/smith/work/"
%ZR("BEST3")="/usr/smith/work/"
%ZR("LOCK")="/usr/smith/work/"
GTM>
This example creates a %ZR array with LOCK and adds to it using CALL%RSEL.
Example:
GTM>do SILENT^%RSEL("myroutine","OBJ")
GTM>ZWRITE
%ZR=1
%ZR("myroutine")="/usr/smith/work"
This example invokes %RSEL non-interactively and creates a %ZR array for myroutine using OBJ%RSEL.