iSharkFly-Open
/
fis-gtm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fis-gtm/sr_port/mumps.hlp

18238 lines
573 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

1 About_GTM
GT.M Version 4.4
UNIX Edition
October 2003
The information in this manual is subject to change without notice and
should not be construed as a commitment by Sanchez Computer Associates.
The software described in this manual is furnished under a license and
may be used or copied only in accordance with the terms of such a
license.
Copyright 1987 - 2003
Sanchez Computer Associates
All rights reserved
GT.M, and GT.CM are trademarks of Sanchez Computer Associates. All
other company and product names may be trademarks of the respective
companies with which they are associated.
1 Prog_Dev_Cycle
Program Development Cycle
In contrast to M environments that interpret M code, GT.M compiles M
code from source files into the target machine language. The GT.M
compiler produces object files, which are dynamically linked into an
image. Source files and object files may be managed independently, or
placed together in a specific directory. GT.M permits access to source
and object files in multiple directories.
GT.M databases are UNIX files identified by a small file called a
Global Directory. Global Directories allow management of the database
files to be independent of the placement of files containing M
routines. By changing the Global Directory, you can use the same
programs to access different databases.
Program development may utilize both GT.M and UNIX development tools.
The development methodology and environment chosen for a particular
installation, and tailored by the individual user, determines the
actual mix of tools. These tools may vary from entirely GT.M with
little UNIX, to mostly UNIX with a modest use of GT.M.
Direct Mode serves as an interactive interface to the GT.M run-time
environment and the compiler. In Direct Mode, the user enters M
commands at the GT.M prompt, and GT.M compiles and executes the
command. This feature provides immediate turnaround for rapid program
development and maintenance.
The methods described in the GT.M column assume you are already at
the GTM> prompt, which is also called Direct Mode. To get to this
prompt, type $gtm_dist/mumps -direct.
2 Def_Env_Var
Defining Environment Variables
GT.M requires the definition of certain environment variables as part
of setting up the environment.
o To locate the files that Sanchez Computer Associates provides as
part of GT.M
o To hold some user-controlled information which GT.M uses for
run-time operation
The procedure below describes how to define an environment variable.
Use this procedure to define an environment variable either at the
shell prompt or in your shell startup file. If you define the variable
at the shell prompt, it will be effective only until you logout. If you
define it in your .profile file (.cshrc, if using a C shell variant),
it will be in effect whenever you log in. Your system manager may have
already defined some of these variables.
Each environment variable required by GT.M is described and
illustrated in individual sections following the procedure. Only
gtm_dist, and in some cases gtmgbldir, gtm_principal and
gtmroutines, are required by users who do not perform programming
activities.
To define an environment variable type the following commands:
$ env_variable=env_variable_value
$ export env_variable
The following environment variables hold information that determines
some details of GT.M run-time operation, over which the user has
control.
3 gtm_dist
gtm_dist
gtm_dist is used to establish the location of the installed GT.M
program and support files.
The syntax for gtm_dist is as follows:
$ gtm_dist=<GT.M-distribution-directory>
The standard installation places these files in /gtm/bin.
Example:
$ gtm_dist=/usr/staff/smith/GTM.dist
$ export gtm_dist
This identifies /usr/staff/smith/GTM.dist as the location of the
installed GT.M files.
Add gtm_dist to your PATH environment variable to have UNIX search the
GT.M installation directory (when processing a command to activate or
run an image). This allows you to activate GT.M and the utilities
without explicitly specifying a path.
To add gtm_dist to your PATH type the following commands:
$ PATH=$PATH:$gtm_dist
$ export PATH
Most of the examples in this manual assume that you have added
gtm_dist to your PATH.
3 gtmgbldir
gtmgbldir
gtmgbldir defines the path to a Global Directory. A Global Directory
maps global variables to physical database files, and is required to
locate M global variables. gtmgbldir provides the initial value for
$ZGBLDIR, the intrinsic special variable that connects the GT.M
run-time system to the Global Directory. It also connects the Global
Directory to the utilities requiring one.
If you maintain multiple global directories, define gtmgbldir to the
Global Directory you currently want to use.
The syntax of a gtmgbldir definition is:
$ gtmgbldir=/directory/filename.gld
Example:
$ gtmgbldir=/usr/staff/mumps.gld
$ export gtmgbldir
This specifies /usr/staff as the directory containing the Global
Directory file named mumps.gld.
3 gtm_principal
gtm_principal
The gtm_principal environment variable specifies the value for
$principal, which designates the absolute pathname of the principal $IO
device. This is an MDC Type A enhancement to standard M.
The following is an example of gtm_principal definition:
$ gtm_principal=/usr/filename
$ export gtm_principal
This specifies the /usr/filename as the principal $IO device, effective
until changed further or until you logout of the particular session.
3 gtmroutines
gtmroutines
The gtmroutines environment variable specifies a search list of
possible locations for M routines. This value is used to initialize
$ZROUTINES, (the intrinsic special variable that enables GT.M to find
the routine (program) you want to run). gtmroutines is required for
ZLINKing. gtmroutines is particularly helpful in calling percent
utilities and the Global Directory Editor (GDE), which are in gtm_dist.
$ gtmroutines="directories in search list"
The directories in the search list must be separated by a space and
enclosed in quotation marks (" "). Environment variables are accepted
in the search list.
The following is an example of gtmroutines definition:
$ gtmroutines=". $gtm_dist"
$ export gtmroutines
This specifies that GT.M search for a routine first in the current
directory (.), then in the distribution directory (which is identified
by the environment variable gtm_dist). The distribution directory is
included in the list because it contains the percent routines. You will
probably want the search list to contain these two items at a minimum.
In addition, you may want to add directories of your own.
3 Editor
Editor
The EDITOR environment variable specifies the UNIX text editor used
when editing a routine either from the shell or with ZEDIT. Since this
is a standard part of establishing your UNIX environment, you will
probably only need to define this when you want to use a different
editor than the one defined in your shell startup file.
Example:
$ EDITOR=/usr/bin/vi
$ export EDITOR
This defines the current text editor to vi.
2 Prep_the_DB
Preparing the Database
GT.M databases consist of one or more UNIX files. Most database files
have a UNIX file structure externally and a GT.M Database Structure
(GDS) internally. Management of the GDS files by the GT.M run-time
system assures high performance and integrity. GT.M database files are
coordinated by a Global Directory. The Global Directory identifies
which global names belong in which files, and specifies the creation
characteristics for each file. To specify access to a database, each M
process must define the gtmgbldir environment variable to point to the
associated Global Directory.
To define and maintain a Global Directory, use the Global Directory
Editor (
GDE) utility. The GDE utility automatically upgrades existing global
directories to the current format.The MUPIP command CREATE uses the
characteristics as defined in the Global Directory to create the
associated database. In a production environment, the system manager
typically maintains Global Directories.
For more information on GDE and MUPIP refer to the "Global Directory
Editor" and "MUPIP" chapters in the GT.M Administration and Operations
Guide .
Example:
This example is a sequence of events that illustrate steps you might
typically perform in creating a new global directory, in our example
PAYROLL.GLD. To assist you in following the sequence, each actual step
appears in typewriter font, as you might see on your terminal screen,
followed by an explanation in normal text font.
$ ls payroll.gld
payroll.gld not found
The ls command verifies that there are no existing files with the name
payroll.gld.
$ gtmgbldir=payroll.gld
$ export gtmgbldir
This establishes the current value of the environment variable
gtmgbldir as payroll.gld. GT.M uses gtmgbldir to identify the current
Global Directory. When defined at the shell prompt, gtmgbldir maintains
the defined value only for the current login session. The next time you
log into UNIX, you must again define the value of gtmgbldir as
payroll.gld to use it as the current Global Directory.
This example defines gtmgbldir without a full pathname. The environment
variable points to the payroll.gld file in the current working
directory. Therefore if the default directory changes, GT.M attempts to
locate the Global Directory in the new default directory and cannot use
the original file. If you intend for the Global Directory to
consistently point to this file, even if the default directory changes,
use a full file-specification for gtmgbldir.
$ gtm
GTM>d ^GDE
%GDE-I-GDUSEDEFS, Using defaults for Global Directory
/staff/payroll.gld
GDE>
This invokes the Global Directory Editor from the GT.M prompt and
produces an informational message. Refer to the "Program Development
Cycle" in GT.M Programmer's Guide for more details.
Example:
$ mupip load payroll.gld
GT.M
09-OCT-2001 11:26:44
keycnt: 100 max subsc len:12 max data len: 3
Last record number: 202
This uses the MUPIP LOAD command to load a sequential file into the
database.
Because MUPIP uses the environment variable gtmgbldir to locate a
Global Directory, which identifies the database file(s), the LOAD
command does not require any information about the target database.
With few exceptions, the GT.M utilities work in the same way.
For general information on shareable libraries in HP-UX, refer to
the "Programming on HP-UX" manual.
Refer to the documentation accompanying AIX for more information on
shareable libraries on AIX.
entryref: return-value routine-name
(parameter, parameter, ..)
where entryref is an M entryref,
return-value is xc_long_t, xc_status_t, or void
and parameter are in the format: direction:type.
len: void length (I:xc_float_t*, o:xc_float_t*)
Example:
% echo $GTMXC_mathpak
2 Cre_Edt_Source_Prog
Creating and Editing a Source Program
The first step in developing a GT.M program is to create a source file.
In most cases, the user can create and modify GT.M source programs
using UNIX text editors.
When the program is very simple (and its lines do not need revision
after they are entered), you can use the cat command to direct input
from your terminal to your source file.
3 Edit_from_GTM
Editing from GT.M
Invoke Direct Mode to create and edit a source program in GT.M. At the
GTM> prompt, invoke the editor by typing:
ZEDIT <filename>
ZEDIT invokes the editor specified by the EDITOR environment variable,
which creates a seperate file for each M source module.
The GT.M environment works most efficiently if the file has the same
name as the M routine it contains, and has an .m extension. Since ZEDIT
automatically defaults the.m extension, it is not necessary to specify
an extension unless you require a different one. If you use another
extension, you must specify that extension with every reference to the
file. Multiple character file extensions are permitted for M source
file names.
3 Edit_from_Shell
Editing from the Shell
To create and edit a source program from the shell, invoke any text
editor at the shell prompt and specify a UNIX file as the source. The
GT.M environment works best when you give a file the name of the M
routine that it contains, and an .m extension.
Example:
$ vi payroll.m
The vi command initiates an editing session for payroll.m from the
shell prompt. If payroll.m does not already exist, vi creates it.
Because this example uses UNIX rather than GT.M tools, we must specify
the .m file extension.
2 Comp_Source_Prog
Compiling a Source Program
GT.M compiles M source code files and produces object files for
complete integration into the UNIX enviroment. The object modules have
the same name as the compiled M source file with an .o file extension,
unless otherwise specified. The object files contain machine
instructions and information necessary to connect the routine with
other routines, and map it into memory. An M routine source file must
be compiled after it is created or modified. You can compile explicitly
with the ZLINK command or implicitly with auto-ZLINK. At the shell
command line, compile by issuing the mumps command.
The compiler checks M code for syntax errors and displays error
messages on the terminal, when processing is complete. Each error
message provides the source line in error with an indicator pointing to
the place on the line where the error is occurring. For a list and
description of the compiler error messages, refer to the GT.M Message
and Recovery Procedures Reference Manual.
You can generate a listing file containing the compile results by
including the
-list qualifier as a modifier to the argument to the ZLINK command in
Direct Mode. This can also be done by redirecting the compiler messages
to a file by adding >filename 2>&1 to the mumps command when compiling
a program from the shell. Refer to the "Compiling from the Shell"
section for an explanation of the M command describing -list, and other
valid qualifiers for the M and ZLINK commands.
The compiler stops processing a routine line when it detects an error
on that line. Under most conditions the compiler continues processing
the remaining routine lines. This allows the compiler to produce a more
complete error analysis of the routine and to generate code that may
have valid executable paths. The compiler does not report multiple
syntax errors on the same line. When it detects more than 127 syntax
errors in a source file, the compiler ceases to process the file.
3 Comp_from_GTM
Compiling from GT.M
In Direct Mode, GT.M provides access to the compiler explicitly through
the ZLINK and ZCOMPILE commands, and implicitly through automatic
invocation of ZLINK functionality (auto-ZLINK) to add required routines
to the image. ZCOMPILE is a GT.M routine compilation command, it
compiles the routine and creates a new object module. The primary task
of ZLINK is to place the object code in memory and "connect" it with
other routines. However, under certain circumstances, ZLINK may first
use the GT.M compiler to create a new object module.
The difference between ZCOMPILE and ZLINK is that ZCOMPILE creates a
new object module on compiling, whereas the ZLINK command links the
object module with other routines and places the object code in memory.
ZLINK compiles under these circumstances:
o ZLINK cannot locate a copy of the object module but can locate a
copy of the source module.
o ZLINK can locate both object and source module, and finds the
object module to be older than the source module.
o The file-specification portion of the ZLINK argument includes an
explicit extension of .m.
Auto-ZLINK compiles under the first two circumstances, but can never
encounter the last one.
When a command refers to an M routine that is not part of the current
image, GT.M automatically attempts to ZLINK and, if necessary, compile
that routine. In Direct Mode, the most common method to invoke the
compiler through an auto-ZLINK is to enter DO ^routinename at the GTM>
prompt. When the current image does not contain the routine, GT.M does
the following:
o Locates the source and object
o Determines whether the source has been edited since it was last
compiled
o Compiles the routine, if appropriate
o Adds the object to the image
By using the DO command, you implicitly instruct GT.M to compile, link,
and execute the program. With this method, you can test your routine
interactively.
For complete descriptions of ZLINK and auto-ZLINK, refer to the
"Commands" chapter in GT.M Programmer's Guide.
Example:
GTM>do ^payroll
GTM>do ^taxes
This uses the M DO command to invoke the GT.M compiler implicitly from
the GTM> prompt if the routine requires new object code. When the
compiler runs, it produces two object module files, payroll.o and
taxes.o.
If you receive error messages from the compilation, you may fix them
immediately by returning to the editor and correcting the source. By
default, the GT.M compiler operates in "compile-as-written" mode, and
produces object code even when a routine contains syntax errors. This
code includes all lines that are correct and all commands on a line
with an error, up to the error. Therefore, you may decide to tailor the
debugging cycle by running the program without removing the syntax
errors.
3 Comp_from_Shell
Compiling from the Shell
From the shell, invoke the compiler by entering mumps file-name at the
shell prompt.
Example:
$ mumps payroll.m
$ mumps taxes.m
This uses the mumps command to invoke the GT.M compiler from the shell
prompt, and creates .o versions of these files.
Use the mumps command at the shell prompt to:
o Check the syntax of a newly entered program.
o Optionally, get a formatted listing of the program.
o Ensure that all object code is up to date before linking.
The mumps command invokes the compiler to translate an M source file
into object code.
The format for the MUMPS command is:
MUMPS [-qualifier[...]] pathname
o Source programs must have an extension of .m.
o Each pathname identifies an M source program to compile.
o Qualifiers determine characteristics of the compiler output.
o Qualifiers must appear after the command, but before the file name
to be properly applied.
o GT.M allows the UNIX * and ? wildcards in a file name.
The * wildcard accepts any legal combination of numbers and characters
including a null, in the position the wildcard holds.
The ? wildcard accepts exactly one legal character in its position.
For example, mumps *.m compiles all files in the current default
directory with an .m extension. mumps *pay?.m compiles .m files with
names that contain any characters followed by pay, followed by one
character. Unlike when using ZLINK or ZCOMPILE, the filename must be
fully specified when compiling from the shell.
1 Opr_Dbg_Dir_Mode
Operating and Debugging in Direct Mode
Direct Mode is an important tool in GT.M because it allows you to
interactively debug, modify, and execute M routines. Direct Mode is a
shell that immediately compiles and executes GT.M commands providing an
interpretive-like interface. M simplifies debugging by using the same
commands for debugging that are used for programming.
The focus of this chapter is to describe the debugging process in
Direct Mode, and to illustrate the GT.M language extensions that
enhance the process. Command functionality is described only in enough
detail to illustrate why a particular command is useful for a debugging
activity being described. If you have specific functionality questions
about a command or variable, refer to the "Commands", "Functions" or
"Intrinsic Special Variables" chapters in GT.M Programmer's Guide.
2 Opr_Dir_Mode
Operating in Direct Mode
This section provides an overview of the following basic operational
issues in Direct Mode:
o Entering Direct Mode
o Available functionality
o Exiting Direct Mode
3 Entr_Dir_Mode
Entering Direct Mode
To enter Direct Mode, type $gtm_dist/mumps -direct at the shell prompt.
Example:
$ $gtm_dist/mumps -direct
GTM>
This shows using $gtm_dist/mumps -direct at the prompt to enter Direct
Mode.
To create a gtm alias in your shell startup file (in the example below
the startup file is assumed to be a .profile file):
o Open an edition session for your .profile file by typing:
$vi .profile
o Add a function to the file to define your gtm alias
o gtm()
{
$gtm_dist/mumps -direct
}
o save the file.
Now, when you want to enter Direct Mode for an editing or debugging
session, simply type gtm at the shell prompt.
Example:
$ gtm
GTM>
This shows that the gtm alias typed at the shell prompt also takes you
to the Direct Mode.
3 Func_in_Dir_Mode
Functionality Available in Direct Mode
This section provides an overview of basic functionality and concepts
that enhance your use of Direct Mode.
4 Comm_Recall
Command Recall
Direct Mode includes a line command recall function to display
previously entered command lines. Use the Up Arrow key at the GTM>
prompt to scroll back through command lines. Usethe Down Arrow key to
scroll forward through the command lines. GT.M displays one command
line at a time. You may delete and reenter characters starting at the
end of a recalled line.
The RECALL command is another way to access previously entered Direct
Mode command lines. RECALL is only valid in Direct Mode and causes an
error if it appears in other M code.
The format of the
RECALL command is:
REC[ALL] [intlit|strlit]
o The optional integer literal specifies a previously entered command
by the counting back from the present.
o The optional string literal specifies the most recently entered
command line that starts with characters matching the
(case-sensitive) literal.
o When the RECALL command has no argument, it displays up to a
maximum of 99 available past Direct Mode entries.
If the Direct Mode session has just started, you may not have entered
99 lines for GT.M to save and therefore you will not have 99 lines to
look at. The most recently entered GT.M command line has the number one
(1), older lines have higher numbers. GT.M does not include the RECALL
command in the listing. If the RECALL command is issued from a location
other than the Direct Mode prompt, GT.M issues a run-time error.
Example:
GTM>WRITE $ZGBLDIR
M.GLD
GTM>SET $ZGBLDIR TEST.GLD
GTM>SET A=10
GTM>SET B=A
GTM>REC
1 SET B=A
2 SET A=10
3 SET $ZGBLDIR TEST.GLD
4 WRITE $ZGBLDIR
This REC[ALL] command displays the previously entered commands.
You can also display a selected command by entering RECALL and the line
number of the command you want to retrieve.
Example:
GTM>REC 2
GTM>SET A=10
This RECALLs the line number two (2).
If the RE[CALL] command includes a text parameter, GT.M displays the
most recent command matching the text after the RE[CALL] command.
Example:
GTM>REC WRITE
GTM>WRITE $ZGBLDIR
MUMPS.GLD
This RECALLs "WRITE", the command most recently beginning with this
text. Note that the RECALL command text is case sensitive. The RECALL
command with a text argument treats WRITE and write differently, that
is, it treats them case sensitively. If you first type the WRITE
command in lower-case and then type WRITE in upper-case to recall it,
the RECALL command does not find a match.
4 Line_Editing
Line Editing
GT.M permits the use of the GT.M command line editor at the Direct Mode
prompt and during M READs from a terminal. The GT.M line editor allows
cursor positioning using the <CTRL> key, edit keypad and function keys.
The GT.M Direct Mode line editing keys are as follows:
Backspace Deletes the character to the left of the cursor
Delete Same as backspace
Up-arrow Moves to a less recent item in the RECALL list
Down-arrow Moves to a more recent item in the RECALL list
Left-arrow Moves the cursor one character to the left
Right-arrow Moves the cursor one character to the right
<CTRL-A> Moves the cursor to the beginning of the line
<CTRL-B> Moves the cursor one character towards the beginning of
the line
<CTRL-D> Deletes the character at the cursor position
<CTRL-E> Moves the cursor to the end of the line
<CTRL-F> Moves the cursor one character towards the end of the line
<CTRL-K> Deletes all characters from the cursor to the end of the
line
<CTRL-U> Deletes the entire line
4 M_Invo_Stack
The M Invocation Stack
The ANSI M Standard describes certain M operations in terms of how a
stack-based virtual machine would operate. A stack is a repository for
tracking temporary information on a "last-in/first-out" (LIFO) basis. M
program behavior can be understood using a stack-based model. However,
the standard is not explicit in defining how an implementation must
maintain a stack or even whether it must use one at all.
The stack model provides a trail of routines currently in progress that
shows the location of all the M operations that performed the
invocations leading to the current point.
3 Exit_Dir_Mode
Exiting Direct Mode
Four M commands terminate a Direct Mode session:
o HALT
o ZCONTINUE
o GOTO
o ZGOTO
The
HALT command exits Direct Mode and terminates the M process.
The
ZCONTINUE command instructs GT.M to exit Direct Mode and resume routine
execution at the current point in the M invocation stack. This may be
the point where GT.M interrupted execution and entered Direct Mode.
However, when the Direct Mode interaction includes a QUIT command, it
modifies the invocation stack and causes ZCONTINUE to resume execution
at another point.
The
GOTO and
ZGOTO commands instruct GT.M to leave Direct Mode, and transfer control
to a specified entry reference.
2 Debug_Rtn_Dir_Mode
Debugging a Routine in Direct Mode
To begin a debugging session on a specific routine, type the following
command at the GTM prompt:
GTM>DO ^routinename
You can also begin a debugging session by pressing <CTRL-C> after
running an M application at the shell. To invoke Direct Mode by
pressing <CTRL-C>, process must have the Principal Device in the
CENABLE state and not have the device set to CTRAP=$C(3).
When GT.M receives a <CTRL-C> command from the principal device, it
invokes Direct Mode at the next opportunity, (usually at a point
corresponding to the beginning of the next source line). GT.M can also
interrupt at a FOR loop iteration or during a command of indeterminate
duration such as JOB, LOCK, OPEN or READ. The GT.M USE command
enables/disables the <CTRL-C> interrupt with the [NO]CENABLE
deviceparameter. By default, GT.M starts <CTRL-C> enabled. The default
setting for <CTRL-C> handling is controlled by GTM$DEFAULTS.M64 and is
enabled in the distribution version of that file.
GT.M displays the GTM> prompt on the principal device. Direct Mode
accepts commands from, and reports errors to, the principal device.
GT.M uses the current device for all other I/O. If the current device
does not match the principal device when GT.M enters Direct Mode, GT.M
issues a warning message on the principal device. A USE command changes
the current device. For more information on the USE command, refer to
the "Input/Output Processing" chapter.
The default "compile-as-written" mode of the GT.M compiler lets you run
a program with errors as part of the debugging cycle. The object code
produced includes all lines that are correct and all commands on a line
with an error, up to the error. When GT.M encounters an error, it
XECUTEs non empty values of $ETRAP or $ZTRAP. By default $ZTRAP
contains a BREAK command, so GT.M enters Direct Mode.
The rest of the chapter illustrates the debugging capabilities of GT.M
by taking a sample routine, dmex, through the debugging process. dmex
is intended to read and edit a name, print the last and first name, and
terminate if the name is an upper-case or lower-case "Q".
Each of the remaining sections of the chapter uses dmex to illustrate
an aspect of the debugging process in GT.M.
3 Creat_Display_M_Rtn
Creating and Displaying M Routines
To create or edit a routine, use the
ZEDIT command. ZEDIT invokes the editor specified by the EDITOR
environment variable, and opens the specified file. dmex.m, for
editing.
Example:
GTM>ZEDIT "dmex"
Once in the editor, use the standard editing commands to enter and edit
text. When you finish editing, save the changes, which returns you to
Direct Mode.
For further details and examples, refer to the GT.M Programmer's
Guide.
3 Exec_M_Rtn_Inter
Executing M Routines Interactively
To execute an M routine interactively, it is not necessary to
explicitly compile and link your program. When you refer to an M
routine that is not part of the current image, GT.M automatically
attempts to compile and
ZLINK the program.
Example:
GTM>DO ^dmex
Name: Revere, Paul
%GTM-E-UNDEF, Undefined local variable: bame
At M source location name+3^dmex
GTM>
In this example GT.M places you in Direct Mode, but also cites an error
found in the program with a run-time error message. In this example, it
was a reference to bame, which is undefined.
To see additional information about the error message, examine the
$ECODE or
$ZSTATUS special variables.
$ECODE is read-write intrinsic special variable that maintains a list
of comma delimited codes that describe a history of past errors - the
most recent ones appear at the end of the list. In $ECODE, standard
errors are prefixed with an "M", user defined errors with a "U", and
GT.M errors with a "Z". A GT.M code always follows a standard code.
$ZSTATUS is a read-write intrinsic special variable that maintains a
string containing the error condition code and location of the last
exception condition occurring during routine execution. GT.M updates
$ZSTATUS only for errors found in routines and not for errors entered
at the Direct Mode prompt.
For further details and examples, refer to the GT.M Programmer's
Guide.
3 Proc_with_Runtime_Syn_Err
Processing with Run-time and Syntax Errors
When GT.M encounters a run-time or syntax error, it stops executing and
displays an error message. GT.M reports the error in the message. In
this case, GT.M reports an undefined local variable and the line in
error, name+3^dmex. Note that GT.M re-displays the GTM> prompt so that
debugging may continue.
To re-display the line and identify the error, use the
ZPRINT command.
Example:
GTM>ZPRINT, name+3
%GTM-E-SPOREOL, Either a space or an end-of-line was expected but not
found
ZP, name+3
^_____
GTM>
This example shows the result of incorrectly entering a ZPRINT command
in Direct Mode. GT.M reports the location of the syntax error in the
command line with an arrow. $ECODE and $ZSTATUS do not maintain this
error message because GT.M did not produce the message during routine
execution. Enter the correct syntax, (i.e., remove the comma) to
re-display the routine line in error.
Example:
GTM>WRITE $ZPOS
name+3^dmex
This example writes the current line position.
$ZPOSITION is a read-only GT.M special variable that provides another
tool for locating and displaying the current line. It contains the
current entry reference as a character string in the format
label+offset^routine, where the label is the closest preceding label.
The current entry reference appears at the top of the
M invocation stack, which can also be displayed with a
ZSHOW "S" command.
To display the current value of every local variable defined, use the
ZWRITE command with no arguments.
Example:
GTM>ZWRITE
ln=12
name="Revere, Paul"
This ZWRITE displays a listing of all the local variables currently
defined.
ZWRITE displays the variable name. ZWRITE does not display a value
for bame, confirming that it is not defined.
3 Correcting_Errors
Correcting Errors
Use the
ZBREAK command to establish a temporary breakpoint and specify an
action. ZBREAK sets or clears routine-transparent breakpoints during
debugging. This command simplifies debugging by interrupting execution
at a specific point to examine variables, execute commands, or to start
using
ZSTEP to execute the routine line by line.
GT.M suspends execution during execution when the entry reference
specified by ZBREAK is encountered. If the ZBREAK does not specify an
expression "action", the process uses the default,
BREAK, and puts GT.M into Direct Mode. If the ZBREAK does specify an
expression "action", the process XECUTEs the value of "action", and
does not enter Direct Mode unless the action includes a BREAK. The
action serves as a "trace-point". The trace-point is silent unless the
action specifies terminal output.
Example:
GTM>ZBREAK name+3^dmex:"set bame=name"
This uses a ZBREAK with an action that SETs the variable bame equal to
name.
3 Stepping_Thru_Rtn
Stepping Through a Routine
The
ZSTEP command provides a powerful tool to direct GT.M execution. When
you issue a ZSTEP from Direct Mode, GT.M executes the program to the
beginning of the next target line and performs the ZSTEP action.
The optional keyword portion of the argument specifies the class of
lines where ZSTEP pauses its execution, and XECUTEs the ZSTEP action
specified by the optional action portion of the ZSTEP argument. If the
action is specified, it must be an expression that evaluates to valid
GT.M code. If no action is specified, ZSTEP XECUTEs the code specified
by the $ZSTEP intrinsic special variable; by default $ZSTEP has the
value "B", which causes GT.M to enter Direct Mode.
ZSTEP actions, that include commands followed by a BREAK, perform the
specified action, then enter Direct Mode. ZSTEP actions that do not
include a BREAK perform the command action and continue execution. Use
ZSTEP actions that issue conditional BREAKs and subsequent ZSTEPs to
perform tasks such as test for changes in the value of a variable.
Use ZSTEP to incrementally execute a routine or a series of routines.
Execute any GT.M command from Direct Mode at any ZSTEP pause. To resume
normal execution, use ZCONTINUE. Note that ZSTEP arguments are keywords
rather than expressions, and they do not allow indirection.
Example:
GTM>ZSTEP INTO
Break instruction encountered during ZSTEP action
At M source location print^dmex
GTM>ZSTEP OUTOF
Paul Revere
Name: Q
%GTM-I-BREAKZST, Break instruction encountered during ZSTEP action
At M source location name^dmex
GTM>ZSTEP OVER
Break instruction encountered during ZSTEP action
At M source location name+1^dmex
This example shows using the ZSTEP command to step through the routine
dmex, starting where execution was interrupted by the undefined
variable error. The ZSTEP INTO command executes line name+3 and
interrupts execution at the beginning of line print.
The ZSTEP OUTOF continues execution until line name. The ZSTEP OVER,
which is the default, executes until it encounters the next line at
this level on the M invocation stack. In this case, the next line is
name+1. The ZSTEP OVER could be replaced with a ZSTEP with no argument
because they do the same thing.
3 Cont_Exec_Frm_Breakpt
Continuing Execution From a Breakpoint
Use the
ZCONTINUE command to continue execution from the breakpoint.
Example:
GTM>ZCONTINUE
Paul Revere
Name: q
Name: QUIT
Name: ?
Please use last-name, first name middle-initial
or 'Q' to Quit.
Name:
This uses a ZCONTINUE command to resume execution from the point where
it was interrupted. As a result of the ZBREAK action, bame is defined
and the error does not occur again. Because the process does not
terminate as intended when the name read has q as a value, we need to
continue debugging.
3 Interr_Execution
Interruption Execution
Press <CTRL-C> to interrupt execution, and return to the GTM prompt to
continue debugging the program.
Example:
%GTM-I-CTRLC, CTRLC_C encountered.
GTM>
This invokes direct mode with a <CTRL-C>.
3 Using_Invoc_Stac_in_Debug
Using the Invocation Stack in Debugging
M DOs, XECUTEs, and extrinsics add a level to the invocation stack.
Matching QUITs take a level off the stack. When GT.M executes either of
these commands, an extrinsic function, or an extrinsic special
variable, it "pushes" information about the new environment on the
stack. When GT.M executes the
QUIT, it "pops" the information about the discarded environment off the
stack. It then reinstates the invoking routine information using the
entries that have now arrived at the active end of the stack.
In the M stack model, a
FOR command does not add a stack frame, and a QUIT that terminates
a FOR loop does not remove a stack frame.
4 Deter_Levels_of_Nest
Determining Levels of Nesting
$STACK contains an integer value indicating the "level of nesting"
caused by DO commands, XECUTE commands, and extrinsic functions in the
M virtual stack.
$STACK has an initial value of zero (0), and increments by one with
each DO, XECUTE, or extrinsic function. Any QUIT that does not
terminate a FOR loop or any ZGOTO command decrements $STACK. In
accordance with the M standard, a FOR command does not increase $STACK.
M routines cannot modify $STACK with the SET or KILL commands.
Example:
GTM>WRITE $STACK
2
GTM>WRITE $ZLEVEL
3
GTM>
This example shows the current values for
$STACK and
$ZLEVEL. $ZLEVEL is like $STACK except that uses one (1) as the
starting level for the M stack, which $STACK uses zero (0), which means
that $ZLEVEL is always one more than $STACK. Using $ZLEVEL with "Z"
commands and functions, and $STACK with standard functions avoids the
need to calculate the adjustment.
4 Look_Invoc_Stack
Looking at the Invocation Stack
The $STACK intrinsic special variable and the $STACK() function provide
a mechanism to access M stack context information.
Example:
GTM>WRITE $STACK
2
GTM>WRITE $STACK(2,"ecode")
,M6,Z150373850,
GTM>WRITE $STACK(2,"place")
name+3^dmex
GTM>WRITE $STACK(2,"mcode")
if ln<30,bame?1.a.1"-".a1","1" "1a.ap do print q
GTM>
This example gets the value of $STACK and then uses that value to get
various types of information about that stack level using the
$STACK() function. The "ecode" value of the error information for level
two, "place" is similar to
$ZPOSITION, "mcode" is the code for the level.
In addition to the $STACK intrinsic special variable, which provides
the current stack level, $STACK(-1) gives the highest level for which
$STACK() can return valid information. Until there is an error $STACK
and $STACK(-1) are the same, but once
$ECODE shows that there is an "current" error, the information returned
by $STACK() is frozen to capture the state at the time of the error; it
unfreezes after a SET $ECODE="".
Example:
GTM>WRITE $STACK
2
GTM>WRITE $STACK(-1)
2
GTM>
This example shows that under the conditions created (in the above
example), $STACK and $STACK(-1) have the same value.
The $STACK() can return information about lower levels.
Example:
+1^GTM$DMOD
GTM>WRITE $STACK(1,"ecode")
GTM>WRITE $STACK(1,"place")
beg^dmex
GTM>WRITE $STACK(1,"mcode")
beg for read !,"Name:",namde do name
GTM>
This example shows that there was no error at $STACK level one, as well
as the "place" and "mcode" information for that level.
4 Using_ZSHOW_Ex_Context_Info
Using ZSHOW to Examine Context Information
The ZSHOW command displays information about the M environment.
Example:
GTM>ZSHOW "*"
$DEVICE=""
$ECODE=",M6,Z150373850,"
$ESTACK=2
$ETRAP=""
$HOROLOG="59149,36200"
$IO="/dev/pts/17"
$JOB=310051
$KEY=""
$PRINCIPAL="/dev/pts/17"
$QUIT=0
$REFERENCE=""
$STACK=2
$STORAGE=1072300032
$SYSTEM="47,gtm_sysid"
$TEST=1
$TLEVEL=0
$TRESTART=0
$X=0
$Y=23
$ZA=0
$ZB=$C(13)
$ZCMDLINE=""
$ZCOMPILE=""
$ZCSTATUS=0
$ZDIRECTORY="/ext1/home/"
$ZEDITOR=0
$ZEOF=0
$ZERROR="Unprocessed $ZERROR, see $ZSTATUS"
$ZGBLDIR="/ext1/home/mumps.gld"
$ZININTERRUPT=0
$ZINTERRUPT="IF $ZJOBEXAM()"
$ZIO="/dev/pts/17"
$ZJOB=0
$ZLEVEL=3
$ZMODE="INTERACTIVE"
$ZPOSITION="name+3^dmex"
$ZPROCESS=""
$ZPROMPT="GTM>"
$ZROUTINES=". /usr/library/gtm_dist"
$ZSOURCE=""
$ZSTATUS="150373850,name+3^dmex, %GTM-E-UNDEF, Undefined local
variable: bame"
$ZSYSTEM=0
$ZTRAP="B"
$ZVERSION="GT.M V4.3-001D AIX RS6000"
$ZYERROR=""
bame="?"
ln=12
name=""
/dev/pts/17 OPEN TERMINAL NOPAST NOESCA NOREADS TYPE WIDTH=80 LENG=24
name+3^dmex ($ZTRAP)
(Direct mode)
beg^dmex
^GTM$DMOD (Direct mode)
GTM>
This example uses the asterisk (*) argument to show all information
that ZSHOW offers in this context. First are the Intrinsic Special
Variables ($DEVICE-$ZYERROR, also available with ZSHOW "I"), then the
local variables (bame, ln and name, also available with ZSHOW "V"),
then the ZBREAK locations (name+3^dmex, also available with ZSHOW "B"),
then the device information (also available with ZSHOW "D"), then the M
stack (also available with ZSHOW "S"). ZSHOW "S" is the default for
ZSHOW with no arguments.
Context information that does not exist in this example includes M
LOCKs of this process (
ZSHOW "L").
In addition to directing its output to the current device, ZSHOW can
place its output in a local or global variable array. For more
information, refer to the ZSHOW section of the "Commands" chapter in
GT.M Programmer's Guide.
ZSHOW "V" produces the same output as ZWRITE with no arguments, but
ZSHOW "V" can be directed to a variable as well as a device.
3 Transf_Rtn_Control
Transferring Routine Control
The
ZGOTO command transfers control from one part of the routine to
another, or from one routine to another, using the specified entry
reference. The ZGOTO command takes an optional integer expression that
indicates the M stack level reached by performing the ZGOTO, and an
optional entry reference specifying the location to where ZGOTO
transfers control. A ZGOTO command, with an entry reference, performs a
function similar to the GOTO command with the additional capability of
reducing the M stack level. In a single operation, the process executes
$ZLEVEL-intexpr, implicit QUITs from DO or extrinsic operations, and a
GOTO operation transferring control to the named entry reference.
The ZGOTO command leaves the invocation stack at the level of the value
of the integer expression. GT.M implicitly terminates any intervening
FOR loops and unstacks variables stacked with NEW commands, as
appropriate.
ZGOTO $ZLEVEL:LABEL^ROUTINE takes the same action as GO LABEL^ROUTINE.
ZGOTO $ZLEVEL-1 produces the same result as QUIT (followed by
ZCONTINUE, if in Direct Mode).
If the integer expression evaluates to a value greater than the current
value of $ZLEVEL, or less than zero (0), GT.M issues a run-time error.
If ZGOTO has no entry reference, it performs some number of implicit
QUITs and transfers control to the next command at the specified level.
When no argument is specified, ZGOTO 1 is the result, and operation
resumes at the lowest level M routine as displayed by ZSHOW "S". In the
image invoked by mumps -direct, or a similar image, a ZGOTO without
arguments returns the process to Direct Mode.
3 Disp_Source_code
Displaying Source Code
Use the
ZPRINT command to display source code lines selected by its argument.
ZPRINT allows you to display the source for the current routine and any
other related routines. Use the ZPRINT command to display the last call
level.
Example:
GTM>ZPRINT beg
beg for read !,"Name: ",name do name
This example uses a ZPRINT command to print the line indicated as the
call at the top of the stack. Notice that the routine has an error in
logic. The line starting with the label beg has a FOR loop with no
control variable, no QUIT, and no GOTO. There is no way out of the FOR
loop.
3 Correct_Errs_in_M_Rtn
Correcting Errors in an M Routine
Now that the routine errors have been identified, correct them in the M
source file. Use
ZEDIT to invoke the editor and open the file for editing. Correct the
errors previously identified and exit the editor.
Example:
GTM>ZEDIT "dmex"
dmex ;dmex - Direct Mode example
;
beg for read !,"Name: ",name do name q:name="Q"
quit
name set ln=$l(name)
if ln,$e("QUIT",1,ln)=$tr(name,"quit","QUIT") d q
. s name="Q"
if ln<30,name?1.a.1"-".a1","1" "1a.ap do print q
write !,"Please use last-name, "
write "first-name middle-initial or 'Q' to Quit."
quit
print write !,$p(name,", ",2)," ",$p(name,", ")
quit
GTM>
This example shows the final state of a ZEDIT session of dmex.m. Note
that the infinite FOR loop at line beg is corrected.
3 Relink_Edited_Rtn
Relinking the Edited Routine
Use the ZLINK command to add the edited routine to the current image.
ZLINK automatically recompiles and relinks the routine. If the routine
was the most recent one ZEDITed or ZLINKed, you do not have to specify
the routine name with the ZLINK command.
You may have to issue a ZGOTO or a QUIT command to remove the
unedited version of the routine from the M invocation stack before
ZLINKing the edited version.
Example:
GTM>ZLINK
Cannot ZLINK an active routine
This illustrates a GT.M error report caused by an attempt to ZLINK a
routine that is part of the current invocation stack.
To ZLINK the routine, remove any invocation levels for the routine off
of the call stack. You may use the ZSHOW "S" command to display the
current state of the call stack. Use the QUIT command to remove one
level at a time from the call stack. Use the ZGOTO command to remove
multiple levels off of the call stack.
For further details and examples, refer to the GT.M Programmer's
Guide.
3 Reexec_the_Rtn
Re-executing the Routine
Re-display the DO command using the RECALL command.
Execute the routine using the DO command.
Example:
GTM>D ^dmex
Name: Revere, Paul
Paul Revere
Name: q
This example illustrates a successful execution of dmex.
3 Using_Forked_Proc
Using Forked Processes
The
ZSYSTEM command creates a new process called the child process, and
passes its argument to the shell for execution. The new process
executes in the same directory as the initiating process. The new
process has the same operating system environment, such as environment
variables and input/output devices, as the initiating process. The
initiating process pauses until the new process completes before
continuing execution.
Example:
GTM>ZSYSTEM
$ ls dmex.*
dmex.m dmex.o
$ ps
PID TTY TIME COMMAND
7946 ttyp0 0:01 sh
7953 ttyp0 0:00 gtm
7955 ttyp0 0:00 ps
$ exit
GTM>
This example uses ZSYSTEM to create a child process, perform some shell
actions, and return to GT.M.
1 Lang_Features_M
General Language Features of M
MUMPS is a general purpose language with an embedded database system.
This section of the help file describes the features of the language
that are not covered as Commands, Functions, or Intrinsic Special
Variables.
2 Data_Types
Data Types
M operates with a single basic data type, string. However, M evaluates
data using methods that vary according to context.
3 Num_Expressions
Numeric Expressions
When M syntax specifies a numexpr, M evaluates the data as a sequence
of ASCII characters that specify a number. M stops the evaluation and
provides the result generated from successfully evaluated characters
when it encounters any character that is not the following:
o A digit 0-9
o A plus sign (+) or minus sign (-) and also the first character in
the string
o The first decimal point (.) in the string
3 Num_Accuracy
Numeric Accuracy
GT.M provides 18 digits of accuracy, independent of the decimal point
(.) placement, and a numeric range from 10**(-43) to (10**47). Numbers
with three digits or fewer to the right of the decimal point are
precise.
3 Int_Expressions
Integer Expressions
When M syntax specifies an intexpr, M evaluates the data as it would a
numexpr except that it stops the evaluation at any decimal point
including the first.
3 Truth_valued_Expr
Truth-valued Expressions
When M syntax specifies a tvexpr, M evaluates the data as a numeric.
However, it stops the evaluation and returns a true value (1) as soon
as it encounters a non-zero digit, otherwise it returns a false value
(0). In other words, M treats expressions that have a non-zero numeric
value as true, and expressions that have a zero numeric value as false.
The sign and/or decimal have no affect on the evaluation of a
truth-valued expression.
2 M_Names
M Names
M uses names for variables, LOCK command arguments, labels on lines,
and routine names. M names are alphanumeric and must start with an
alphabetic character or a percent sign (%).
The percent sign can only appear as the first character in a name. By
convention, names starting with percent signs are generally
application-independent or distinguished in some similar way.
M does not reserve any names. That is, M always distinguishes keywords
by context. Therefore, M permits a variable or a label called SET even
though the language has a command called SET.
M names are case sensitive. That is, M treats ABC, Abc, ABc, AbC ABC,
and abc as six different names.
M does not restrict the length of names in the main body of the
standard. However, the portability section of the standard recommends
limiting names to a maximum of eight (8) characters. GT.M effectively
limits names to eight characters by ignoring any characters after the
first eight.
2 Variables
Variables
M does not require predefinition of variable type or size. M variables
are either local or global. Any variable may be unsubscripted or
subscripted.
3 Arrays_Subscripts
Arrays and Subscripts
In M, subscripted variables identify elements in sparse arrays. Sparse
arrays comprise existing subscripts and data nodes - no space is
reserved for potential data nodes. These arrays generally serve
logical, rather than mathematical, purposes.
M array subscripts are expressions, and are not restricted to numeric
values.
The format for an M global or local variable is:
[^]name[(expr1[,...])]
o The optional leading caret symbol (^) designates a global variable.
o The name specifies a particular array.
o The optional expressions specify the subscripts
o and must be enclosed in parentheses and separated by commas (,).
The body of the M standard places no restrictions on variable names.
However, the portability section of the standard does suggest limits on
the length of an individual subscript expression, and on the total
length of a variable name. The measurement for the length of names
includes the length of the global variable name itself, the sum of the
lengths of all the evaluated subscripts, and an allowance for an
overhead of two (2) times the number of subscripts. The total must not
exceed 237. For globals, GT.M permits this total to be modified with
GDE up to 255. For locals, GT.M limits the length of individual
subscripts to the maximum string length of 32,767. GT.M restricts the
number of subscripts for local or global variables to 32.
3 M_Collation_Seq
M Collation Sequences
M collates all canonic numeric subscripts ahead of all string
subscripts, including strings such as those with leading zeros that
represent non-canonic numbers. Numeric subscripts collate from negative
to positive in value order. String subscripts collate in ASCII
sequence. In addition, GT.M allows the empty string subscript in most
contexts, (the null, or empty, string collates ahead of all canonic
numeric subscripts).
GT.M allows definition of alternative collation sequences. For complete
information on enabling this functionality, refer to the
"Internationalization" chapter in GT.M Programmer's Guide.
3 Local_Variables
Local Variables
A local variable in M refers to a variable used solely within the scope
of a single process. Local variable names have no leading delimiter.
M makes a local variable available and subject to modification by all
routines executed within a process from the time that variable is first
SET until it is KILLed, or until the process stops executing M.
However, M "protects" a local variable after that variable appears as
an argument to a NEW command, or after it appears as an element in a
formalist used in parameter passing. When M protects a local variable,
it saves a copy of the variable's value and makes that variable
undefined. M restores the variable to its saved value during execution
of the QUIT that terminates the process stack level associated with the
"protecting" NEW or formalist. For more information on NEW and QUIT,
refer to the "Commands" chapter in GT.M Programmer's Guide.
M restricts the following uses of variables to local variables:
o FOR command control variables.
o Elements within the parentheses of an "exclusive" KILL.
o TSTART [with local variables list].
o A KILL with no arguments removes all current local variables.
o NEW command arguments.
Actualnames used by pass-by-reference parameter passing.
3 Glob_Var_Resrc_Nam_Env
Global Variables and Resource Name Environments
M recognizes an optional environment specification in global names or
in the LOCK resource names (nrefs), which have analogous syntax. Global
variable names have a leading caret symbol (^) as a delimiter.
M makes a global variable available, and subject to modification by all
routines executed within all processes in an environment, from the time
that variable is first SET until it is KILLed.
4 Naked_References
Naked References
M accepts an abbreviation of the global name under some circumstances.
When the leading caret symbol (^) immediately precedes the left
parenthesis delimiting subscripts, the global variable reference is
called a naked reference. M evaluates a naked reference by prefixing
the last used global variable name, except for its last subscript, to
the list of subscripts specified by the naked reference. The prefixed
portion is known as the naked indicator. An attempt to use a naked
reference when the prior global reference does not exist, or did not
contain a subscript, generates an error.
Because M has only one process-wide naked indicator which it maintains
as a side affect of every evaluation of a global variable, using the
naked reference requires an understanding of M execution sequence. M
execution generally proceeds from left to right within a line, subject
to commands that change the flow of control. However, M evaluates the
portion of a SET command argument to the right side of the equal sign
before the left side. Also, M does not evaluate any further $SELECT()
arguments within the function after it encounters a true selection
argument.
In general, using naked references only in very limited circumstances
prevents problems associated with the naked indicator.
4 Glob_Var_Name_Env
Global Variable Name Environments
M recognizes an optional environment specification in global names. The
environment specification designates one of some set of alternative
database files.
The syntax for global variable names that include an environment
specification is:
^|expr|name[(subscript[,...])]
In GT.M, the expression identifies the Global Directory for mapping the
global variable.
Environment specifications permit easy access to global variables in
alternative databases, including other "copies" of active variables in
the current database. Environment specifications are sometimes referred
to as extended global syntax or extended value syntax.
GT.M also allows:
^|expr1,expr2|name[(subscript[,...])]
Where the first expression identifies the Global Directory and the
second expression is accepted but ignored by GT.M.
To improve compatibility with some other M implementations, GT.M also
accepts another non-standard syntax. In this syntax, the leading and
trailing up-bar (|) are respectively replaced by a left square-bracket
([) and a right square-bracket (]). This syntax also requires
expratoms, rather than expressions.
The formats for this non-standard syntax are:
^[expratom1]name[(subscript...)]
or
^[expratom1,expratom2]name[(subscript...)]
Where expratom1 identifies the Global Directory and expratom2 is a
dummy variable. Note that the first set of brackets in each format is
part of the syntax. The second set of square brackets is part of the
meta-language identifying an optional element.
Example:
$ gtmgbldir=Test.GLD
$ export gtmgbldir
$ GTM
GTM>WRITE $ZGBLDIR
TEST.GLD
GTM>WRITE ^A
THIS IS ^A IN DATABASE RED
GTM>WRITE ^|"M1.GLD"|A
THIS IS ^A IN DATABASE WHITE
GTM>WRITE $ZGBLDIR
TEST.GLD
GTM>HALT
$ echo gtmgbldir
TEST.GLD
The statement WRITE ^|"M1.GLD"|A writes variable ^A using the Global
Directory, M1.GLD, but does not change the current Global Directory.
Example:
GTM>WRITE $ZGBLDIR
M1.GLD
GTM>WRITE ^A
THIS IS ^A IN DATABASE WHITE
GTM>WRITE ^|"M1.GLD"|A
THIS IS ^A IN DATABASE WHITE
The statement WRITE ^|"M1.GLD"|A is equivalent to WRITE ^A.
Specifying separate Global Directories does not always translate to
using separate databases.
Example:
GTM>WRITE ^|"M1.GLD"|A,!,^|"M2.GLD"|A,!,^|"M3.GLD"
|A,!
THIS IS ^A IN DATABASE WHITE
THIS IS ^A IN DATABASE BLUE
THIS IS ^A IN DATABASE WHITE
In this example, the WRITE does not display ^A from three GT.M database
files. Mapping specified by the Global Directory Editor (GDE)
determines the database file to which a Global Directory points.
This result could have occurred under the following mapping:
^|"M1.GLD"|A --> REGIONA --> SEGMENTA --> FILE1.DAT
^|"M2.GLD"|A --> REGIONA --> SEGMENT1 --> FILE2.DAT
^|"M3.GLD"|A --> REGION3 --> SEGMENT3 --> FILE1.DAT
For more information on Global Directories, refer to the "Global
Directory Editor" chapter of the GT.M Administration and Operations
Guide.
4 Opt_GTM_Env_Trans_Facility
Optional GT.M Environment Translation Facility
For users who wish to dynamically (at run-time) determine a global
directory from non-global directory information (typically UCI and VOL)
in the environment specification, GT.M provides an interface to add an
appropriate translation.
Using this facility impacts the performance of every global access that
uses environment specification. Make sure you use it only when static
determination of the global directory is not feasible. When used, make
every effort to keep the translation routines very efficient.
The use of this facility is enabled by the definition of the
environment variable gtm_env_translate, which contains the path of a
shared library with the following entry point:
5 gtm_env_xlate
gtm_env_xlate
If the shared object is not accessible or the entry point is not
accessible, GT.M reports an error.
The gtm_env_xlate() routine has the following C prototype:
int gtm_env_xlate(xc_string_t *in1, xc_string_t *in2, xc_string *in3,
xc_string_t *out)
where xc_string_t is a structure defined in gtmxc_types.h as follows:
typedef struct
{
int length;
char *address;
} xc_string_t;
The purpose of the function is to use its three input arguments to
derive and return an output argument that can be used as an environment
specification by GT.M. Note that the input values passed (in1, in2 and
in3) are the result of M evaluation and must not be modified. The first
two arguments are the expressions passed within the up-bars "| |" or
the square-brackets "[ ]", and the third argument is the current
working directory as described by $ZDIRECTORY.
A return value other than zero (0) indicates an error in translation,
and is reported by a GT.M error
If the length of the output argument is non-zero, GT.M appends a
secondary message of GTM-I-TEXT, containing the text found at the
address of the output structure.
GT.M does not do any memory management related to the output argument -
space for the output should be allocated by the external routine. The
routine must place the returned environment specification at the
address it has allocated and adjust the length accordingly. On a
successful return, the return value should be zero. If the translation
routine must communicate an error to GT.M, it must return a non-zero
value, and if it is to communicate additional error information, place
the error text at the address where the environment would normally go
and adjust the length to match the length of the error text.
Length of the return value may range from 0-32767, otherwise GT.M
reports an error.
A zero-length (empty) string specifies the current value of $ZGBLDIR.
Non-zero lengths must represent the actual length of the file
specification pointed to by address, excluding any <NUL> terminator. If
the address field of the output argument is NULL, GT.M issues an error.
The file specification may be absolute or relative and may contain an
environment variable. If the file specified is not accessible, or is
not a valid global directory, GT.M reports errors in the same way it
does for any invalid global directory.
It is possible to write this routine in M (as a call-in), however,
global variables in such a routine would change the naked indicator,
which environment references normally do not. Depending on the
conventions of the application, there might be difficult name-space
management issues such as protecting the local variables used by the M
routine.
While it is possible for this routine to take any form that the
application designer finds appropriate within the given interface
definition, the following paragraphs make some recommendations based on
the expectation that a routine invoked for any more than a handful of
global references should be efficient.
It is expected that the routine loads one or more tables, either at
compilation or the first time it is invoked. The logic of the routine
performs a look up on the entry in the set of tables. The lookup might
be based on the length of the strings and some unique set of characters
in the names, or a hash, with collision provisions as appropriate.
The routine may have to deal with a case where one or both of the
inputs have zero length. A subset of these cases may have the first
string holding a comma limited string that needs to be re-interpreted
as being equivalent to two input strings (note that the input strings
must never be modified). The routine may also have to handle cases
where a value (most likely the first) is accidentally or intentionally,
already a global directory specification.
Example:
> cat gtm_env_translate.c
#include <stdio.h>
#include <string.h>
#include "gtmxc_types.h"
static int init = 0;
typedef struct
{
xc_string_t field1, field2, ret;
} line_entry ;
static line_entry table[5], *line, linetmp;
/* Since these errors may occur before setup is complete, they are
statics */
static char *errorstring1 = "Error in function initialization,
environment variable GTM_CALLIN_START not defined. Environment
translation failed.";
static char *errorstring2 = "Error in function initialization, function
pointers could not be determined. Envrironment translation failed.";
#define ENV_VAR "GTM_CALLIN_START"
typedef int (*int_fptr)();
int_fptr GTM_MALLOC;
int init_functable(xc_string_t *ptr)
{
/* This function demonstrates the initialization of other function
pointers as well (if the user-code needs them for any reason, they
should be defined as globals)*/
char *pcAddress;
long lAddress;
void **functable;
void (*setup_timer) ();
void (*cancel_timer) ();
pcAddress = getenv(ENV_VAR);
if (pcAddress == NULL)
{
ptr->length = strlen(errorstring1);
ptr->address = errorstring1;
return 1;
}
lAddress = -1;
lAddress = atol(pcAddress);
if (lAddress == -1)
{
ptr->length = strlen(errorstring2);
ptr->address = errorstring2;
return 1;
}
functable = (void *)lAddress;
setup_timer = (void(*)()) functable[2];
cancel_timer = (void(*)()) functable[3];
GTM_MALLOC = (int_fptr) functable[4];
return 0;
}
void copy_string(char **loc1, char *loc2, int length)
{
char *ptr;
ptr = (char *) GTM_MALLOC(length);
strncpy( ptr, loc2, length);
*loc1 = ptr;
}
int init_table(xc_string_t *ptr)
{
int i = 0;
char buf[100];
char *buf1, *buf2;
FILE *tablefile;
char *space = " ";
char *errorstr1 = "Error opening table file table.dat";
char *errorstr2 = "UNDETERMINED ERROR FROM GTM_ENV_XLATE";
if ((tablefile = fopen("table.dat","r")) == (FILE *)NULL)
{
ptr->length = strlen(errorstr1);
copy_string(&(ptr->address), errorstr1, strlen(errorstr1));
return 1;
}
while (fgets(buf, (int)SIZEOF(buf), tablefile) != (char *)NULL)
{
line= &table[i++];
buf1 = buf;
buf2 =strstr(buf1, space);
line->field1.length = buf2 - buf1;
copy_string( &(line->field1.address), buf1, line->field1.length);
buf1 = buf2+1;
buf2 = strstr(buf1, space);
line->field2.length = buf2-buf1;
copy_string( &(line->field2.address), buf1, line->field2.length);
buf1 = buf2+1;
line->ret.length = strlen(buf1) - 1;
copy_string( &(line->ret.address), buf1, line->ret.length);
}
fclose(tablefile);
/* In this example, the last entry in the table is the error string
*/
line = &table[4];
copy_string( &(line->ret.address), errorstr2, strlen(errorstr2));
line->ret.length = strlen(errorstr2);
return 0;
}
int cmp_string(xc_string_t str1, xc_string_t str2)
{
if (str1.length == str2.length)
return strncmp(str1.address, str2.address, (int) str1.length);
else
return str1.length - str2.length;
}
int cmp_line(line_entry *line1, line_entry *line2)
{
return (((cmp_string(line1->field1,
line2->field1))||(cmp_string(line1->field2, line2->field2))));
}
int look_up_table(line_entry *aline, xc_string_t *ret_ptr)
{
int i;
int ret_v;
for(i=0;i<4;i++)
{
line = &table[i];
ret_v = cmp_line( aline, line);
if (!ret_v)
{
ret_ptr->length = line->ret.length;
ret_ptr->address = line->ret.address;
return 0;
}
}
/*ERROR OUT*/
line = &table[4];
ret_ptr->length= line->ret.length;
ret_ptr->address = line->ret.address;
return 1;
}
int gtm_env_xlate(xc_string_t *ptr1, xc_string_t *ptr2, xc_string_t
*ptr_zdir, xc_string_t *ret_ptr)
{
int return_val, return_val_init;
if (!init)
{
return_val_init = init_functable(ret_ptr);
if (return_val_init) return return_val_init;
return_val_init = init_table(ret_ptr);
if (return_val_init) return return_val_init;
init = 1;
}
linetmp.field1.length= ptr1->length;
linetmp.field1.address= ptr1->address;
linetmp.field2.length= ptr2->length;
linetmp.field2.address= ptr2->address;
return_val = look_up_table(&linetmp, ret_ptr);
return return_val;
}
> cat table.dat
day1 week1 mumps
day2 week1 a
day3 week2 b
day4 week2 c.gld
This example demonstrates the mechanism. A table is set up the first
time for proper memory management, and for each reference, a table
lookup is performed. Note that for the purpose of simplicity, no error
checking is done, so table.dat is assumed to be in the correct format,
and have exactly four entries.
2 Literals
Literals
M has both string and numeric literals.
3 String_Literals
String Literals
String literals (strlit) are enclosed in quotation marks (" ") and must
only contain graphic characters. In other words, control characters
(ASCII 0-31 and 127) cannot appear in a strlit. M attempts to use
character text that appears outside of quotation mark delimiters
according to context, which generally means as a local variable name.
To include a quotation mark (") within a strlit, use a set of two
quotation marks ("" "").
Example:
GTM>WRITE """"
"
GTM>
The WRITE displays a single quotation mark because the first quotation
mark delimits the beginning of the string literal, the next two
quotation marks denote a single quote within the string, and the last
quotation mark delimits the end of the string literal.
Use the $CHAR function and the concatenation operator to include
control characters within a string.
Example:
GTM>WRITE "A"_$CHAR(9)_"B"
A B
GTM>
The WRITE displays an "A," followed by a tab (<HT>), followed by a "B"
using $CHAR(), to introduce the non-graphic character.
3 Numeric_Literals
Numeric Literals
In M, numeric literals (numlit) are entered without surrounding
delimiters.
Example:
GTM>WRITE 1
1
GTM> WRITE 1.1
1.1
These display numeric literals that are integer and decimal.
M also accepts numeric literals in the form of a mantissa and an
exponent, separated by a delimiter of "E" in uppercase. The mantissa
may be an integer or a decimal fraction. The integer exponent may have
an optional leading minus sign (-).
Example:
GTM>WRITE 8E6
8000000
GTM> WRITE 8E-6
.000008
GTM>
2 Expressions
Expressions
The following items are legal M expression atoms (expratom). An
expression atom is a component of an M expression.
o Local variables
o Global variables
o Intrinsic special variables
o Intrinsic functions
o Extrinsic functions
o Extrinsic special variables
o Numeric literals
o String literals
o An expression enclosed in parentheses
o Any of the above preceded by a unary operator
In addition, any of these items may be combined with a binary operator
and another expression atom.
2 Operators
Operators
M has both unary and binary operators.
3 Precedence
Precedence
All unary operations have right to left precedence.
All M binary operations have strict left to right precedence. This
includes all arithmetic, string, and logical operations. Hierarchies of
operations require explicit establishment of precedence using
parentheses (). Although this rule is counterintuitive, it is easy to
remember and has no exceptions.
3 Arithmetic_Operators
Arithmetic Operators
All arithmetic operators force M to evaluate the expressions to which
they apply as numeric. The arithmetic operators are:
+ as a unary operator simply forces M to evaluate the expression
following as numeric; as a binary operator it causes M to perform
addition.
- as a unary operator causes M to negate the expression following;
as a binary operator it causes M to perform subtraction.
* binary operator for multiplication.
** binary operator for exponentiation.
/ binary operator for fractional division.
\ binary operator for integer division.
# binary operator for modulo, that is, causes M to produce the
remainder from integer division of the first argument by the
second.
Remember that precedence is left to right for all arithmetic operators.
Example:
GTM>WRITE 1+1
2
GTM>WRITE 2-1
1
GTM>WRITE 2*2
4
GTM>WRITE 3**2
9
GTM>WRITE 4/2
2
GTM>WRITE 7
2
GTM>WRITE 7#3
1
GTM>
This simple example demonstrates how each arithmetic binary operation
uses numeric literals.
Example:
GTM>WRITE +"12ABC"
12
GTM>WRITE --"-3-4"
-3
GTM>
The first WRITE shows the unary plus sign (+) operation forcing the
numeric evaluation of a string literal. The second WRITE demonstrates
the unary minus sign (-). Note the second minus sign within the string
literal does not cause subtraction, but rather, terminates the numeric
evaluation with the result of negative three (-3). Each of the leading
minus signs causes one negation and therefore, the result is negative
three (-3).
3 Logical_Operators
Logical Operators
M logical operators always produce a result that is TRUE (1) or FALSE
(0). All logical operators force M to evaluate the expressions to which
they apply as truth-valued. The logical operators are:
' unary NOT operator negates current truth-value; M accepts
placement of the NOT operator next to a relational operator, for
example, A'=B as meaning '(A=B).
& binary AND operator produces a true result only if both of the
expressions are true.
! binary OR operator produces a true result if either of the
expressions is true.
Remember that precedence is always left to right, and that logical
operators have the same precedence as all other operators.
Example:
GTM>WRITE '0
1
GTM>WRITE '1
0
GTM>WRITE '5689
0
GTM>WRITE '-1
0
GTM>WRITE '"ABC"
1
GTM>
The above example demonstrates the unary NOT operation. Note that any
non-zero numeric value is true and has a false negation.
Example:
GTM>WRITE 0&0
0
GTM>WRITE 1&0
0
GTM>WRITE 0&1
0
GTM>WRITE 1&1
1
GTM>WRITE 2&1
1
GTM>WRITE 0!0
0
GTM>WRITE 1!0
1
GTM>WRITE 0!1
1
GTM>WRITE 1!1
1
GTM>WRITE 2!1
1
GTM>
The above example demonstrates all cases covered by the binary logical
operators.
3 String_Operators
String Operators
All string operators force M to evaluate the expressions to which they
apply as strings. The string operator is:
_ binary operator causes M to concatenate the second expression
with the first expresion
Example:
GTM>WRITE "B"_"A"
BA
GTM>WRITE "A"_1
A1
GTM>
The above example demonstrates M concatenation.
3 Num_Relational_Operators
Numeric Relational Operators
M relational operators always generate a result of TRUE (1) or FALSE
(0). All numeric relational operators force M to evaluate the
expressions to which they apply as numeric. The numeric relational
operators are:
> binary arithmetic greater than
< binary arithmetic less than
The equal sign (=) does not force numeric evaluation, and should be
viewed as a string operator. However, the equal sign between two
numeric values tests for numeric equality.
Other numeric relations are formed using the logical NOT operator
apostrophe (') as follows:
'> not greater than, that is, less than or equal to
'< not less than, that is, greater than or equal to
'= not equal, numeric or string operation
Example:
GTM>WRITE 1>2
0
GTM>WRITE 1<2
1
GTM>
The above example demonstrates the basic arithmetic relational
operations.
Example:
GTM>WRITE 1'<2
0
GTM>WRITE 2'<1
1
GTM>
The above example demonstrates combinations of arithmetic, relational
operators with the logical NOT operator.
3 Str_Relational_Operators
String Relational Operators
M relational operators always generate a result of TRUE (1) or FALSE
(0). All string relational operators force M to evaluate the
expressions to which they apply as strings. The string relational
operators are:
= binary operator causes M to produce a TRUE if the expressions are
equal.
[ binary operator causes M to produce a TRUE if the first
expression contains the ordered sequence of characters in the
second expression.
] binary operator causes M to produce a TRUE if the first
expression lexically follows the second expression in the character
encoding sequence, which by default is ASCII.
]] binary operator causes M to produce a TRUE if the first
expression lexically sorts after the second expression in the
subscript collation sequence.
Note that all non-empty strings lexically follow the empty string, and
every string contains the empty string.
Other string relations are formed using the logical NOT operator
apostrophe (') as follows:
'[ does not contain.
'] does not follow, that is, lexically less than or equal to.
']] does not sort after, that is, lexically less than or equal to
in the subscript collation sequence.
'= not equal, numeric or string operation.
Example:
GTM>WRITE "A"="B"
0
GTM>WRITE "C"="C"
1
GTM>WRITE "A"["B"
0
GTM>WRITE "ABC"["C"
1
GTM>WRITE "A"]"B"
0
GTM>WRITE "B"]"A"
1
GTM>WRITE "A"]]"B"
0
GTM>WRITE "B"]]"A"
1
These examples demonstrate the string relational operators using string
literals.
Example:
GTM>WRITE 2]10
1
GTM>WRITE 2]]10
0
GTM>WRITE 0]"$"
1
GTM>WRITE 0]]"$"
0
These examples illustrate that when using the primary ASCII character
set, the main difference in the "follows" (]) operator and the
"sorts-after" (]]) operator is the way they treat numbers.
Example:
GTM>WRITE 1=1
1
GTM>WRITE 1=2
0
GTM>WRITE 1="1"
1
GTM>WRITE 1=01
1
GTM>WRITE 1="01"
0
GTM>WRITE 1=+"01"
1
GTM>
These examples illustrate the dual nature of the equal sign operator.
If both expressions are string or numeric, the results are straight
forward. However, when the expressions are mixed, the native string
data type prevails.
Example:
GTM>WRITE "a"'="A"
1
GTM>WRITE "FRED"'["RED"
0
GTM>WRITE "ABC"']""
0
These examples demonstrate combinations of the string relational
operators with the NOT operator.
3 Pat_Match_Operator
Pattern Match Operator
The pattern match operator (?) causes M to return a TRUE if the
expression ahead of the operator matches the characteristics described
by the pattern following the operator. The pattern is not an
expression.
Patterns are made up of two elements:
o A repetition count
o A pattern code, a string literal or an alternation list
The element following the pattern match operator may consist of an
indirection operator, followed by an element that evaluates to a
legitimate pattern.
The repetition count consists of either a single integer literal or a
period (.) delimiter with optional leading and trailing integer
literals. A single integer literal specifies an exact repetition count.
The period syntax specifies a range of repetitions where the leading
number is a minimum and the trailing number is a maximum. When the
repetition count is missing the leading number, M assumes there is no
minimum, (i.e., a minimum of zero). When the repetition count is
missing the trailing number, M does not place a maximum on the number
of repetitions.
The pattern codes are:
A alphabetic characters upper or lower case
C control characters ASCII 0-31 and 127
E any character; used to pass all characters in portions of the
string where the pattern is not restricted
L lower-case alphabetic characters, ASCII 97-122
N digits 0-9, ASCII 48-57
P punctuation, ASCII 32-47, 58-64, 91-96, 123-126
U upper-case alphabetic characters, ASCII 65-90
Pattern codes may be upper or lower case and may be replaced with a
string literal. GT.M allows the M pattern match definition of patcodes
A, C, N, U, L, and P to be extended or changed, (A can only be modified
implicitly by modifying L or U) and new patcodes added. For detailed
information on enabling this functionality, refer to the
"Internationalization" chapter in GT.M Programmer's Guide.
The GT.M compiler accepts pattern codes other than those explicitly
defined above. If, at run-time, the pattern codes come into use and
no pattern definitions are available, GT.M issues a run-time error
(PATNOTFOUND). GT.M does not currently implement a mechanism for Y
and Z patterns and continues to treat those as compile-time syntax
errors.
Example:
GTM>WRITE "ABC"?3U
1
GTM>WRITE "123-45-6789"?3N1"-"2N1"-"4N
1
The first WRITE has a simple one-element pattern while the second has
multiple elements including both codes and string literals. All the
repetition counts are fixed.
Example:
I x?.E1C.E W !,"Must not contain a control character" Q
This example uses a pattern match to test for control characters.
Example:
I acn?1U.20A1","1U.10A D
.S acn=$G((^ACX($P(acn,","),$P(acn,",",2)))
This example uses a pattern match with implicit minimums to determine
that an "account number" is actually a name, and to trigger a look-up
of the corresponding account number in the ^ACX cross index.
The pattern match operator accepts the alteration syntax. Alteration
consists of a repeat count followed by a comma-delimited list of
patatoms enclosed in parentheses "()". The semantic is that the pattern
matches if any of the listed patterns matches the operand string. For
example, ?1(2N1"-"7N,3N1"-"2N1"-"4N).1U might be a way to match either
a social security number or a taxpayer ID. Since alternation is defined
as one of the ways of constructing a patatom, alternation can nest (be
used recursively).
Complex pattern matches may not be efficient to evaluate, so every
effort should be made to simplify any commonly used pattern and to
determine if more efficient alternative logic would be more
appropriate.
2 Gen_M_Comm
General M Commands
M commands may be abbreviated to a defined prefix. Most commands have
arguments. However, some commands have either optional arguments or no
arguments. When a command has no argument and is followed by more
commands on the same line, at least two spaces (<SP>) must follow the
command without arguments. Commands that accept arguments generally
accept multiple arguments on the same command. M treats multiple
arguments the same as multiple occurrences of the same command, each
with its own argument.
3 Postconditionals
Postconditionals
M provides postconditionals as a tool for placing a condition on the
execution of a single command and, in some cases, a single command
argument. A postconditional consists of a colon (:) delimiter followed
by a truth-valued expression. When the expression evaluates to true, M
executes the command occurrence. When the expression evaluates to
false, M does not execute the command occurrence.
4 Comm_Postconditionals
Command Postconditionals
Command postconditionals appear immediately following a command and
apply to all arguments for the command when it has multiple arguments.
All commands except commands that themselves have a conditional aspect
accept a command postconditional. Among the M standard commands, ELSE,
FOR, and IF do not accept command postconditionals. All the GT.M
command extensions accept command postconditionals.
4 Arg_Postconditionals
Argument Postconditionals
Commands that affect the flow of control may accept postconditionals on
individual command arguments. Because multiple arguments act as
multiple commands, this is a straight-forward application of the same
principal as command postconditional. The only M standard commands that
accept argument postconditionals are DO, GOTO, and XECUTE. The GT.M
command extensions that accept argument postconditionals are BREAK,
ZGOTO, and ZSYSTEM.
3 Timeouts
Timeouts
M provides timeouts as a tool to retain program control over commands
of indefinite duration. A timeout consists of a colon (:) delimiter on
an argument, followed by a numeric expression specifying the number of
seconds for M to attempt to execute the command. When the timeout is
zero (0), M makes a single attempt to complete the command.
GT.M has been designed to allow large timeout values, and to protect
against arithmetic overflow when converting large timeout values to
internal representations. When a command has a timeout, M maintains the
$TEST intrinsic special variable as the command completes. If the
command completes successfully, M sets $TEST to TRUE (1). If the
command times out before successful completion, M sets $TEST to FALSE
(0). When a command argument does not specify a timeout, M does not
maintain $TEST.
The following commands accept timeouts:
o LOCK
o JOB
o OPEN
o READ
o ZALLOCATE
When a READ times out, M returns any characters that have arrived
between the start of the command and the timeout. M does not produce
any partial results for any of the other timed commands.
2 Gen_M_Intrin_Func
General M Intrinsic Functions
M Intrinsic Functions start with a single dollar sign ($) and have one
or more arguments enclosed in parentheses () and separated by commas
(,). These functions provide an expression result by performing actions
that would be impossible or difficult to perform using M commands. It
is now possible to invoke a C function in a package via the external
call mechanism.
2 Gen_M_Intr_Spec_Var
General M Intrinsic Special Variables
M Intrinsic Special Variables start with a single dollar sign ($). GT.M
provides such variables for program examination. In some cases, the
Intrinsic Special Variables may be SET to modify the corresponding part
of the environment.
2 Routines
Routines
M routines have a name and consist of lines of code followed by an
end-of-record which is a carriage return, formfeed (<CR><FF>) sequence.
M separates the name of a routine from the body of the routine with an
end-of-line which is a carriage-return, line-feed (<CR><LF>) sequence.
GT.M stores routine sources in UNIX files and implicitly supplies the
end-of-record and end-of-line character sequences.
In M, a routine has no particular impact on variable management and may
include code that is invoked at different times and has no logical
intersection.
3 Lines
Lines
A line of M code consists of the following elements in the following
order:
o An optional label.
o A line-start delimiter. The standard defines the line-start
delimiter as a space (<SP>) character. In order to enhance routine
readability, GT.M extends M by accepting one or more tab (<HT>)
characters as line-start delimiters.
o Zero or more level indicators, which are periods (.). The level
indicators show the level of nesting for argumentless DO commands:
the more periods, the deeper the nesting. M ignores lines that
contain level indicators unless they directly follow an
argumentless DO command with a matching level of nesting.
o Zero or more commands and their arguments. M accepts multiple
commands on a line. The argument(s) of one command are separated
from the next command by a command-start delimiter, consisting of
one or more spaces (<SP>).
o A terminating end-of-line, which is a carriage return, line feed
(<CR><LF>) sequence.
4 Labels
Labels
In addition to labels that follow the rules for M names, M accepts
labels consisting only of digits. In a label consisting only of digits,
leading zeros are considered significant. For example, labels 1 and 01
are different. Formalists may immediately follow a label. A Formalists
consists of one or more names enclosed in parentheses (). Formalists
identify local variables that "receive" passed values in M parameter
passing.
In GT.M, a colon (:) delimiter may be appended to the label, which
causes the label to be treated as "local." Within the routine in which
they appear, they perform exactly as they would without the trailing
colon but they are inaccessible to other routines. Using local labels
reduces object size and linking overhead, for both ZLINK and host
linking.
4 Comments
Comments
In addition to commands, a line may also contain a comment that starts
with a leading semi-colon (;) delimiter. The scope of a comment is the
remainder of the line. In other words, M ignores anything to the right
of the comment delimiter. The standard defines the comment delimiter
(;) as it would a command, and therefore requires that it always appear
after a linestart. GT.M extends the standard to permit comments to
start at the first character of a line or in an argument position.
3 Entry_Ref
Entry References
M entryrefs provide a generalized target for referring to a line within
a routine. An entryref may contain some combination of a label, an
offset, and a routine name (in that order). The offset is delimited by
a plus sign (+) and the routinename is delimited by a caret symbol(^).
When an entryref does not contain a label, M assumes the offset is from
the beginning of the routine. When an entryref does not contain an
offset, M uses an offset of zero (0). When an entryref does not contain
a routine name, M assumes the routine that is currently executing.
M permits every element in an entryref to have the form of an
indirection operator, followed by an element that evaluates to a
legitimate occurrence of that portion of the entryref.
While most commands and functions that use entryrefs permit
argument indirection, M does not accept indirection that resolves
to a combination of label and offset or offset and routine name.
Offsets provide an extremely useful tool for debugging. However, avoid
their use in production code because they generally produce maintenance
problems.
3 Label_Ref
Label References
M labelrefs are a subset of entryrefs that exclude offsets and separate
indirection. Labelrefs are used with parameter passing.
2 Indirection
Indirection
M provides indirection as a means to defer definition of elements of
the code until run-time. Indirection names a variable that holds or
"points" to the element. The indirection operator is the "at" symbol
(@).
3 Arg_Indirection
Argument Indirection
Most commands accept indirection of their entire argument.
Example:
GTM>SET x="^INDER"
GTM>DO @x
This example is equivalent to DO ^INDER.
3 Atomic_Indirection
Atomic Indirection
Any expratom or any local or global variable name may be replaced by
indirection.
Example:
GTM>SET x="HOOP",b="x"
GTM>WRITE a="HULA "__@b
HULA HOOP
GTM>
This example uses indirection within a concatenation operation.
3 Entryref_Indirection
Entryref Indirection
Any element of an entryref may be replaced by indirection.
Example:
GTM>SET lab="START",routine="PROG"
GTM>DO @lab^@routine
This example is equivalent to DO START^PROG.
3 Patt_Code_Indirection
Pattern Code Indirection
A pattern code may be replaced by indirection.
Example:
GTM>FOR p="1U.20A1"",""1U.20A",5N IF x?@p QUIT
GTM>ELSE WRITE !,"Incorrect format" QUIT
This example uses pattern code indirection to test x for either a name
or a number.
3 Name_Indirection
Name Indirection
Indirection may replace the prefix of a subscripted global or local
variable name. This "name" indirection requires two indirection
operators, a leading operator similar to the other forms of
indirection, and a trailing operator marking the transition to those
subscripts that are not specified by indirection.
Example:
GTM>SET from="B",to="^A(15),x=""
GTM>FOR SET x=$O(@from@(x)) Q:x="" S @to@(x)=@from@(x)
This example uses name indirection to copy the level contents of a
local array to a part of a global array. The example assumes that all
existing first level nodes of variable B have data.
3 Indirection_Concerns
Indirection Concerns
M indirection provides a very powerful tool for allowing program
abstraction. However, because indirection is frequently unnecessary and
has some disadvantages, use it carefully.
Because routines that use indirection in some ways do not contain
adequate information for easy reading, such routines tend to be more
difficult to debug and maintain.
To improve run-time performance, GT.M tends to move work from run-time
to compile-time. Indirection forces compiler actions to occur at
run-time, which minimizes the benefits of compilation.
M allows most forms of indirection to be recursive. However, in real
applications, recursive indirection typically makes the code obscure
and slow.
There are circumstances where indirection serves a worthwhile purpose.
For instance, certain utility functions with a general nature may be
clearly abstracted and coded using indirection. Because M has no "CASE"
command, DO (or GOTO) with argument indirection provides a clear
solution to the problem of providing complex branching.
Some M users prototype with indirection and then replace indirection
with generated code that reduces run-time overhead. In any case, always
consider whether indirection can be replaced with a clearer or more
efficient approach.
2 Param_Passing
Parameter Passing
Parameter passing provides a way of explicitly controlling some or all
of the variable context transferred between M routines.
M uses parameter passing for:
o A DO command with parameters
o Extrinsic functions and special variables
Parameter passing is optional on DO commands.
Parameter passing uses two argument lists: the actuallist that
specifies the parameters that M passes to an invoked routine, and the
formalist that specifies the local variables to receive or associate
with the parameters.
3 Actuallists
Actuallists
An actuallist specifies the parameters M passes to the invoked routine.
The actuallist contains a list of zero or more parameters enclosed in
parentheses, immediately following a DO or extrinsic function.
An actuallist:
o Is made up of items separated by commas
o Contains expressions and/or actualnames. Items may be missing, that
is, two commas may appear next to each other, with nothing between
them.
o Must be used in an invocation of a label with a formallist, except
in the case of extrinsic special variables.
o Must not contain undefined variables.
o Must not have more items than a formallist with which it is used.
o May contain the same item in more than one position.
Example:
GTM>DO MULT(3,X,.RESULT)
This example illustrates a DO with parameters. The actuallist contains:
o 3 - a numeric literal
o X - a local variable
o .RESULT - an actualname
3 Actualnames
Actualnames
An actualname starts with a leading period (.) delimiter, followed by
an unsubscripted local variable name. Actualnames identify variables
that are passed by reference, as described in a subsequent section.
While expressions in an actualname are evaluated when control is
transferred to a formallabel, the variables identified by actualnames
are not; therefore, they do not need to be defined at the time control
is transferred.
3 Formallists
Formallists
A formallist specifies the variables M uses to hold passed values. A
formallist contains a list of zero or more parameters enclosed in
parentheses, immediately following a label.
A formallist:
o Is made up of items separated by commas.
o Contains unsubscripted local variable names.
o Must be used and only used with a label invoked with an actuallist
or an extrinsic.
o May contain undefined variables.
o May have more items than an actuallist with which it is used.
o Must not contain the same item in more than one position.
o Must contain at least as many items as the actuallist with which it
is used.
Example:
MULT(MP,MC,RES)
SET RES=MP*MC
QUIT RES
In this example, illustrating a simple parameterized routine, the
formallist contains the following items:
o MP
o MC
o RES
An example in the section describing "Actuallists" shows an invocation
that matches this routine.
3 Formallabel
Formallabel
A label followed by a formallist is called a formallabel.
3 Param_Pass_Operation
Parameter Passing Operation
M performs an implicit NEW on the formallist names and replaces the
formallist items with the actuallist items.
M provides the actuallist values to the invoked procedure by giving
each element in the formallist the value or reference provided by the
corresponding element in the actuallist. M associates the first name in
the formallist with the first item in the actuallist, the second name
in the formallist with the second item in the actuallist and so on. If
the actuallist is shorter than the formallist, M ensures that the
formallist items with no corresponding value are in effect NEWed. If
the formallist item has no corresponding item in the actuallist
(indicated by two adjacent commas in the actuallist), that item in the
formallist becomes undefined.
If the actuallist item is an expression and the corresponding
formallist variable is an array, parameter passing does not affect the
subscripted elements of the array. If an actualname corresponds to a
formallist variable, M reflects array operations on the formallist
variable, by reference, in the variable specified by the actualname.
M treats variables that are not part of the formallist as if parameter
passing did not exist (i.e., M makes them available to the invoked
routine).
M initiates execution at the first command following the formallabel.
A QUIT command terminates execution of the invoked routine. At the time
of the QUIT, M restores the formallist items to the values they had at
the invocation of the routine.
In the case where a variable name appears as an actualname in the
actuallist, and also as a variable in the formallist, the restored
value reflects any change made by reference.
A QUIT from a DO does not take an argument, while a QUIT from an
extrinsic must have an argument. This represents one of the two major
differences between the DO command with parameters and the extrinsics.
M returns the value of the QUIT command argument as the value of the
extrinsic function or special variable. The other difference is that M
stacks $TEST for extrinsics.
Example:
SET X=30,Z="Hello"
DO WRTSQR(X)
ZWRITE
QUIT
WRTSQR(Z)
SET Z=Z*Z
WRITE Z,!
QUIT
Produces:
900
X=30
Z="Hello"
3 Param_Pass_Mechanism
Parameter Passing Mechanisms
M passes the actuallist values to the invoked routine using two
parameter-passing mechanisms:
o Call-by-Value - where expressions appear
o Call-by-Reference - where actualnames appear
A call-by-value passes a copy of the value of the actuallist expression
to the invoked routine by assigning the copy to a formallist variable.
If the parameter is a variable, the invoked routine may change that
variable. However, because M constructs that variable to hold the copy,
it deletes the variable holding the copy when the QUIT restores the
prior formallist values. This also means that changes to the variable
by the invoked routine do not affect the value of the variable in the
invoking routine.
Example:
SET X=30
DO SQR(X)
ZWRITE
QUIT
SQR(Z) SET Z=Z*Z
QUIT
Produces:
X=30
A period followed by a name identifies an actualname and causes a
call-by-reference.
A call-by-reference passes a pointer to the variable of the invoked
routine so operations on the assigned formallist variable also act on
the actualname variable. Changes, including KILLs to the formallist
variable, immediately have the same affect on the corresponding
actualname variable. This means that M passes changes to formallist
variables in the invoked routine back to the invoking routine as
changes in actualname variables.
Example:
SET X=30
DO SQR(.X)
ZWRITE
QUIT
SQR(Z) SET Z=Z*Z
QUIT
Produces:
X=900
3 GTM_Param_Pass_Extn
GT.M Parameter Passing Extensions
The standard does not provide for indirection of a labelref because the
syntax has an ambiguity.
Example:
DO @X(1)
This example could be:
o An invocation of the label specified by X with a parameter of 1.
o An invocation of the label specified by X(1) with no parameter
list.
GT.M processes the latter interpretation as illustrated in the
following example.
Example:
The syntax:
SET A(1)="CUBE",X=5
DO @A(1)(.X)
WRITE X,!
QUIT
CUBE(C) ;cube a variable
SET C=C*C*C
QUIT
Produces the result:
125
GT.M follows analogous syntax for routine indirection:
DO ^@X(A) invokes the routine specified by X(A).
DO ^@(X)(A) invokes the routine specified by X and passes the parameter
A.
DO ^@X(A)(A) invokes the routine specified by X(A) and passes the
parameter A.
2 Ext_Calls
External Calls
GT.M allows references to a GT.M database from programs written in
other programming languages that run under UNIX.
In GT.M, calls to C language routines may be made with the following
syntax:
DO &[packagename.]name[^name][parameter-list]
or as an expression element,
$&[packagename.]name[^name][parameter-list]
Where packagename, like the name elements is a valid M name. Because of
the parsing conventions of M, the identifier between the ampersand (&)
and the optional parameter-list has precisely constrained punctuation -
a latersection describes how to transform this into a more richly
punctuated name should that be appropriate for the called function.
While the intent of the syntax is to permit the name^name to match an M
labelref, there is no semantic implication to any use of the up-arrow
(^).
2 Extrinsic_Func
Extrinsic Functions
An extrinsic function is an M subroutine that another M routine can
invoke to return a value.
The format for extrinsic functions is:
$$[label][^routinename]([expr|.lname[,...]])
o The optional label and optional routinename make up the formallabel
that specifies the name of the subroutine performing the extrinsic
function. The formallabel must contain at least one of its optional
components.
o The optional expressions and actualnames make up the actuallist
that specifies the list of actual parameters M passes to the
invoked routine.
M stacks $TEST for extrinsic functions. This is one of the two major
differences between the DO command with parameters and extrinsics. On
return from an extrinsic function, M restores the value of $TEST to
what it was before the extrinsic function, regardless of the actions
executed by the invoked routine.
M requires a routine that implements an extrinsic function to terminate
with an explicit QUIT command which has an argument. M returns the
value of the QUIT command argument as the value of the extrinsic
function. This is the other major difference between the DO command
with parameters and extrinsics. It is now possible to invoke a C
function in a package via the external call mechanism.
Example:
GTM>ZPRINT ^POWER
POWER(V,X,S,T) ;extrinsic to raise to a power
;ignores fractional powers
SET T=1,S=0
IF X<0 SET X=-X,S=1
FOR X=1:1:X S T=T*V
QUIT $S(S:1/T,1:T)
GTM> WRITE $$^POWER(3,4)
81
GTM>
The POWER routine uses a formallist that is longer than the
"expected" actuallist to protect local working variables. Such
practice may be encouraged or discouraged by your institution's
standards.
2 Extrinsic_Spc_Vars
Extrinsic Special Variables
An extrinsic special variable is a user-written M subroutine that
another M routine can invoke to return a value.
The format for extrinsic special variables is:
$$[label][^routinename]
o The optional label and optional routinename make up the
formallabel, which specifies the name of the subroutine performing
the extrinsic function. The formallabel must contain at least one
of its optional component.
An extrinsic special variable can be thought of as an extrinsic
function without input parameters. $$x is equivalent in operation to
$$x(). Extrinsic special variables are the only case where invocation
of a formallabel does not require an actuallist. M stacks $TEST for
extrinsic special variables.
M requires that a routine that implements an extrinsic special variable
terminate with an explicit QUIT command which has an argument. M
returns the value of the QUIT command argument as the value of the
extrinsic special variable.
Example:
GTM>ZPRINT ^DAYOWEEK
DAYOWEEK() ;extrinsic special variable to
;provide the day of the week
QUIT $ZD($H,"DAY")
GTM>WRITE $$DAYOWEEK^DAYOWEEK
MON
2 Trans_Processing
Transaction Processing
Transaction Processing (TP) provides a way for M programs to organize
database updates into logical groups that occur as a single event
(i.e., either all the database updates in a transaction occur, or none
of them occur). No other process may behave as if it observed any
intermediate state.
Transaction processing has been designed to improve output and
eliminate "live lock" conditions. The number of attempts to complete
the transaction is limited to four. The fourth attempt is made inside a
"critical section" with all other processes temporarily locked out of
the database. Between the second and third tries, GT.M waits for a
random interval between 0 and 500 milliseconds.
3 TP_Def
TP Definitions
In M, a transaction is a sequence of commands that begins with a TSTART
command, ends with a TCOMMIT command, and is not within the scope of
another transaction.
A successful transaction ends with a COMMIT that is triggered by the
TCOMMIT command at the end of the transaction. A COMMIT causes all the
database updates performed within the transaction to become available
to other processes.
An unsuccessful transaction ends with a ROLLBACK. ROLLBACK is invoked
explicitly by the TROLLBACK command, or implicitly at a process
termination that occurs during a transaction in progress. An error
within a transaction does not cause an implicit ROLLBACK. A ROLLBACK
removes any database updates performed within the transaction before
they are made available to other processes. ROLLBACK also releases all
resources LOCKed since the start of the transaction, and makes the
naked reference undefined.
A RESTART is a transfer of control to the TSTART at the beginning of
the transaction. RESTART implicitly includes a ROLLBACK and may
optionally restore local variables to the values they had when the
initial TSTART was originally executed. A RESTART always restores $TEST
and the naked reference to the values they had when the initial TSTART
was executed. RESTART does not manage device state information. A
RESTART is invoked by the TRESTART command or by M if it is determined
that the transaction is in conflict with other database updates.
RESTART can only successfully occur if the initial TSTART includes an
argument that enables RESTART.
3 TP_Characteristics
TP Characteristics
Most transaction processing systems try to have transactions meet the
"ACID" test-Atomic, Consistent, Isolated, and Durable. To conform with
the M approach of providing maximum flexibility and, when possible,
backwards compatibility with older versions of the standard, M
transaction processing requires the use of programming conventions that
meet the ACID test.
For example, some effects of the BREAK, CLOSE, JOB, OPEN, READ, USE
WRITE, and ZSYSTEM commands may be observed by parties to the system.
Because the effects of these commands might cause an observing process
or person to conclude that a transaction executing them was in progress
and perhapsfinished, they violate, in theory, the principle of
Isolation.
The LOCK command is another example. A program may attempt to use a
LOCK to determine if another process has a transaction in progress. The
answer would depend on the management of LOCKs within transactions,
which is implementation-specific. This would therefore clearly violate
the principle of Isolation. The LOCK command is discussed later in this
section.
The simplest way to construct a transaction that meets the ACID test is
not to use any commands within a transaction whose affects may be
immediately "visible" outside the transaction. Unfortunately, because M
applications are highly interactive, this is not entirely
straightforward. When a user interaction relies on database
information, one solution is for the program to save the initial values
of any global values that could affect the outcome, in local variables.
Then, once the interaction is over and the transaction has been
initiated, the program checks the saved values against the
corresponding global variables. If they are the same, it proceeds. If
they differ, some other update has changed the information, and the
program must issue a TROLLBACK, and initiate another interaction as a
replacement.
Even when the "visible" commands appear within a transaction, an M
application may provide wholesome operation by relying on additional
programming or operating conventions.
A program using LOCKs to achieve serializability relies on properly
designed and universally followed LOCKing conventions to achieve
Isolation with respect to database operations. LOCKs placed outside the
transaction (usually a LOCK immediately before the TSTART and an unlock
immediately after the TCOMMIT) achieve serializability by actually
serializing any approximately concurrent transaction. LOCKs placed
inside the transaction (frequently a LOCK immediately after the TSTART
and an unlock immediately before the TCOMMIT) signal M to ensure that
no operations using the same LOCK resource(s) overlap. Within a
transaction, an M implementation may defer both LOCKing and unlocking
to achieve its goal of serializability. A program using TSTARTs with
the SERIAL keyword replaces the convention with a guarantee from M that
all the database activity of the transaction meets the test of
Isolation with respect to database activity.
In GT.M the Durability aspect of the ACID properties relies on the
journaling feature. When journaling is on, every transaction is
recorded in the journal file as well as in the database. The journal
file constitutes a serial record of database actions and states. It is
always written before the database updates and is designed to permit
recovery of the database if the database should be damaged. By default
when a process commits a transaction, it does not return control to the
application code until the transaction has reached the journal file.
The exception to this is that when the TSTART specifies
TRANSACTIONID="BATCH" the process resumes application execution without
waiting for the file system to confirm the successful write of the
journal record. The idea of the TRANSACTIONID="BATCH" has nothing
inherently to do with "batch" processing - it is to permit maximum
throughput for transactions where the application has its own
check-pointing mechanism, or method of recreating the transaction in
case of a failure. The real durability of transactions is a function of
the durability of the journal files. Putting journal files on reliable
devices (RAID with UPS protection) and eliminating common points of
failure with the path to the database (separate drives, controllers
cabling) improve durability. The use of the replication feature can
also improve durability by moving the data to a separate site in real
time.
Attempting to QUIT (implicitly or explicitly) from code invoked by a
DO, XECUTE, or extrinsic after that code issued a TSTART not yet
matched by a TCOMMIT, produces an error. Although this is a consequence
of the RESTART capability, it is true even when that capability is
disabled. For example, this means that an XECUTE containing only a
TSTART fails, while an XECUTE that performs a complete transaction
succeeds.
3 TP_Performance
TP Performance
To achieve the best GT.M performance, transactions should:
o be as short as possible
o consist, as much as possible, only of global updates
o be SERIAL with no associated LOCKs
o have RESTART enabled with a minimum of local variables protected by
a restart portion of the TSTART argument.
Large concurrent transactions using TCOMMIT may result in repeated and
inefficient attempts by competing processes to capture needed scarce
resources, resulting in poor performance.
Example:
TSTART ():SERIAL
SET (ACCT,^M(0))=^M(0)+1
SET ^M(ACCT)=PREC,^PN(NAM)=ACCT
TCOMMIT
This transaction encapsulates these two SETs. The first increments the
tally of patients registered, storing the number in local variable ACCT
for faster access in the current program, and in global variable ^M(0).
The second SET stores a patient record by account number and the third
cross-references the account number with the patient name. Placing the
SETs within a single transaction ensures that the database always
receive either all of the SETs or none of them, thus protecting
database integrity against process or system failure. Similarly,
another concurrent process, whether using transactions or not, never
finds one of the SETs in place without also finding the other one.
Example:
TSTART ():SERIAL
IF $TRESTART>3 DO QUIT
.TROLLBACK
.WRITE !,"Too many RESTARTs"
.QUIT
SET (NEXT,^ID(0))=^ID(0)+1
SET ^ID(NEXT)=RECORD,^XID(ZIP,NEXT)=""
TCOMMIT
This transaction will automatically restart if it cannot serialize the
SETs to the database, and will terminate with a TROLLBACK if more than
3 RESTARTs occur.
GT.M provides a way to monitor transaction restarts by reporting them
to the operator logging facility. If the environment variable
TPRESTART_SYSLOG_DELTA is defined, GT.M reports every Nth restart where
N is the numeric evaluation of the value of TPRESTART_SYSLOG_DELTA. If
the environment variable TPRESTART_SYSLOG_LIMIT is defined, the restart
reporting begins after the number of restarts specified by the value of
TPRESTART_SYSLOG_LIMIT. For example, defining both the environment
variable to the value 1, causes all TP restarts to be logged. When
TPRESTART_SYSLOG_DELTA is defined, leaving TPRESTART_SYSLOG_LIMIT
undefined is equivalent to giving it the value 1.
For more information on enhancements related to TP performance
refer to the "NOISOLATION" section under VIEW command topic in the
"Commands" chapter in GT.M Programmer's Guide.
3 TP_Example
TP Example
Here is a transaction processing example that lets you exercise the
concept. If you use this example, be mindful that the functions
"holdit" and "trestart" are included as tools to allow you access to
information within a transaction which would normally be hidden from
users. These types of functions would not normally appear in production
code. Comments have been inserted into the code to explain the function
of various segments.
trans
;This sets up the program constants
;for doit and trestart
n
s $p(peekon,"V",51)=""
s $p(peekon,"V",25)="Peeking inside Job "_$j
s $p(peekoff,"^",51)=""
s $p(peekoff,"^",25)="Leaving peeking Job "_$j
;This establishes the main loop
s CNFLTMSG="Conflict, please reenter"
f r !,"Name: ",nam q:'$l(nam) d
.i nam="?" d q
..w !,"Current data in ^trans:",! d:$d(^trans) q
...zwrite ^trans
.f s ok=1 d q:ok w !,$C(7),CNFLTMSG,$C(7),!
..s old=$g(^trans(nam),"?")
..i old="?" w !,"Not on file" d q
...;This is the code to add a new name
...f d q:data'="?"
....r !,"Enter any info using '#' delimiter: ",!,data
...i data="" w !,"No entry made for ",nam q
...TSTART ():SERIAL i $$trestart ;$$trestart for demo
...i $d(^trans(nam)) s ok=^trans(nam)=data TRO q
...s ^trans(nam)=data
...TCOMMIT:$$doit ;$$doit for demo
..;This is the beginning of the change and delete loop
..f d q:fld=+fld!'$l(fld) w " must be numeric"
...w !,"Current data: ",!,old
...r !,"Piece no. (negative to delete record) : ",fld
..i 'fld w !,"no change made" q
..;This is the code to delete a new name
..i fld<0 d q ; delete record
...f d q:"YyNn"[x
....w !,"Ok to delete ",nam," Y(es) or N(o) <N>? "
....r x s x=$e(x)
...i "Yy"'[x!'$l(x) w !,"No change made" q
...TSTART ():SERIAL i $$trestart ;$$trestart for demo
...i $g(^trans(nam),"?")'=old TROLLBACK s ok=0 q
...kill ^trans(nam)
...TCOMMIT:$$doit; $$doit for demo
..;This is the code to change a field
..f r !,"Data: ",data q:data'="?"&(data'["#") d
...w " must not be a single '?' or contain any '#'"
..TSTART ():SERIAL i $$trestart ;$$trestart for demo
..i '$d(^trans(nam)) s ok=0 TROLLBACK q
..i $p(^trans(nam),"#",fld)=$p(old,"#",fld) d q
...s ok=$p(^trans(nam),"#",fld)=data TROLLBACK
..s $p(^trans(nam),"#",fld)=data
..TCOMMIT:$$doit; $$doit for demo
q
doit()
;This inserts delay and an optional
;rollback only to show how it works
w !!,peekon d disp
f d q:"CR"[act
.r !,"C(ommit), R(ollback), or W(ait) <C>? ",act
.s act=$tr($e(act),"cr","CR")
.i act="?" d disp
i act="R" TROLLBACK w !,"User requested DISCARD"
w !,peekoff,!
q $TLEVEL
trestart()
;This is only to show what is happening
i $TRESTART d
.w !!,peekon,!,">>>RESTART<<<",! d disp w !,peekoff,!
q 1
disp
w !,"Name: ",nam
w !,"Original data: ",!,old,!,"Current data: "
w !,$g(^trans(nam),"KILLED!")
q
Generally, this type of program would be receiving data from multiple
sessions into the same global.
1 BREAK
Break
The BREAK command pauses execution of the code and initiates Direct
Mode.
The format of the BREAK command is:
B[REAK][:tvexpr] [expr[:tvexpr][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional expression contains a fragment of GT.M code to XECUTE
before the process enters Direct Mode.
o The BREAK command without an argument causes a pause in execution
of the routine code and immediately initiates Direct Mode. In this
case, at least two (2) spaces must follow the BREAK to separate it
from the next command on the line.
o The optional truth-valued expression immediately following the
expression is the argument postconditional that controls whether
GT.M XECUTEs the argument. If present and true, the process
executes the code before entering Direct Mode. If present and
false, the process does not execute the code before entering Direct
Mode.
o An indirection operator and an expression atom evaluating to a list
of one or more BREAK arguments form a legal argument for a BREAK.
Issuing a BREAK command inside a transaction destroys the Isolation of
that transaction. Beacuse of the way that GT.M implements transaction
processing, a BREAK within a transaction may suffer an indefinite
number of restarts ("live lock").
Generally, programs in production must not include BREAK commands.
Therefore, GT.M provides the ZBREAK and ZSTEP commands, which insert
temporary breakpoints into the process rather than the source code.
BREAKs inserted with ZBREAK only exist until the image terminates or
until explicitly removed by another ZBREAK command. ZSTEP also inserts
temporary BREAKs in the image that only exist for the execution of the
ZSTEP command. In the GT.M debugging environment, ZBREAKs and ZSTEPs
that insert BREAKs provide a more flexible and less error-prone means
of setting breakpoints than coding BREAKs directly into a routine. For
more information on ZBREAK and ZSTEP, refer to the sections that
describe those commands.
To resume execution of the interrupted program, use the ZCONTINUE
command.
GT.M displays messages identifying the source of a BREAK as:
o The body of a program
o A
o ZBREAK action
o A device EXCEPTION
o A ZSTEP action
The VIEW "BREAKMSG" mask selectively enables or disables these
messages. See the section on "VIEW" for an explanation of the mask. By
default, a process executing a GT.M image displays all BREAK messages.
When a process encounters a BREAK, it displays a prompt indicating
readiness to process commands in Direct Mode. By default, Direct Mode
displays the GTM> prompt. SETting the $ZPROMPT intrinsic special
variable alters the prompt.
2 Ex_of_Break
Examples of BREAK
Example:
LOOP0 F S act=$O(^act(act)) Q:act="" B:debug D LOOP1
This FOR loop contains a BREAK with a command postconditional.
Example:
B:$D(x) "W !,""OK""":x,"W !,""Wrong again""":'x
This uses a BREAK with both command and argument postconditionals. The
actions display debugging messages.
1 CLOSE
Close
The CLOSE command breaks the connection between a process and a device.
The format of the CLOSE command is:
C[LOSE][:tvexpr] expr[:(keyword[=expr][:...])][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required expression specifies the device to CLOSE.
o The optional keywords specify device parameters that control device
behavior; some device parameters take arguments delimited by an
equal sign (=). If there is only one keyword, the surrounding
parentheses are optional.
o An indirection operator and an expression atom evaluating to a list
of one or more CLOSE arguments form a legal argument for a CLOSE.
1 DO
Do
The DO command makes an entry in the GT.M invocation stack and
transfers execution to the location specified by the entryref.
The format of the DO command is:
D[O][:tvexpr] [entryref[(expr|.lvn[,...])][:tvexpr][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional entryref specifies a location (with some combination
of label, offset, and routinename) at which execution continues
immediately following the DO.
o A DO command without an argument (that is, a DO followed by two (2)
spaces) transfers execution to the next line in the routine if that
line contains a number of periods (.) after the optional label and
before the required linestart. These periods indicate the current
level of "immediate" nesting caused by argumentless DOs. If the
line following the DO contains too many periods, GT.M reports an
error; if the line following the DO contains too few periods, GT.M
ignores the DO command.
o A DO command without an argument stacks the current value of $TEST,
in contrast to a DO with an argument, which does not protect the
current value of $TEST.
o The optional parameter list enclosed in parentheses ( ) contains
parameters to pass to the routine entry point.
o If the DO specifies a parameter list, the entryref location must
start with a label and an argument list (that is, GT.M prohibits
entryrefs with offsets during parameter passing).
o If an element in the parameter list starts with a period, it
specifies an unsubscripted local variable name and the DO passes
that variable by reference. Otherwise, the element specifies an
expression that the DO evaluates and passes as a value.
o The optional truth-valued expression following the parameter list,
or the entryref if the argument contains no parameter list,
specifies the argument postconditional and controls whether GT.M
performs a DO with that argument.
o An indirection operator and an expression atom evaluating to a list
of one or more DO arguments form a legal argument for a DO.
An explicit or implicit QUIT within the scope of the DO, but not within
the scope of any other DO, FOR, XECUTE, or extrinsic, returns execution
to the instruction following the calling point. This point may be the
next DO argument or another command. At the end of a routine, or the
end of a nesting level created by an argumentless DO, GT.M performs an
implicit QUIT. Any line that reduces the current level of nesting by
changing the number of leading periods (.) causes an implicit QUIT,
even if that line only contains a comment.
Terminating the image and execution of ZGOTO commands are the only ways
to avoid eventually returning execution to the calling point. A DO
command may optionally pass parameters to the invoked subroutine.
2 Ex_of_Do
Examples of DO
Example:
GTM>DO ^%RD
This example invokes the routine directory utility program (%RD) from
Direct Mode. The caret symbol (^) specifies that the DO command invokes
%RD as an external routine.
Example:
GTM>DO A(3)
This example invokes the subroutine at label A and passes the value 3
as a parameter. Because the DO argument does not have a caret symbol
(^), it identifies A as a label in the current routine.
Example:
Label A;
SET di="" U outfile
FOR SET di=$O(^div(di)) Q:di="" D PREP D D POST
.SET de="",(nr,gr)=0
.WRITE "Division ",di,! F S de=$O(^de(di,de)) Q:de="" D
..WRITE "Department ",de," Gross Rev: ",^grev(di,de),!
..WRITE "Department ",de," Net Rev: ",^nrev(di,de),!
..SET gr=gr+^grev(di,de),nr=nr+^nrev(di,de)
.W "Division Gross Rev: ",gr,!,"Division Net Rev: ",nr,!
DO PRINT^OUTPUT(outfile)
QUIT
This routine first uses a DO with a label argument (PREP) to do some
pre-processing. Then, it uses an argumentless DO to loop through each
division of a company to format a report. Within the first argumentless
DO, a second argumentless DO (line 4) loops through and formats each
department within a division. After the processing of all departments,
control returns to the first argumentless DO, which prints a summary of
the division. Following processing of all divisions, a DO with a label
argument (POST) does some post-processing. Finally, at the next-to-last
line, the routine uses a DO that invokes a subroutine at a label
(PRINT) in an external routine (^OUTPUT), passing the name of the
output file (outfile) as a parameter.
1 ELSE
Else
GT.M executes the remainder of the line after the ELSE if $TEST is
FALSE (0). GT.M does not execute the rest of the line if $TEST is TRUE
(1).
The format of the ELSE command is:
E[LSE]
o Because ELSE is a conditional command, it does not support a
command postconditional.
o The scope of the ELSE is the remainder of the line.
o Because the ELSE has no argument, at least two (2) spaces must
follow the command to separate it from the next command on the
line.
Because the scopes of both the IF and the ELSE commands extend to the
rest of the GT.M line, placing an ELSE on the same line as the
corresponding IF cannot achieve the desired result. If an ELSE were
placed on the same line as its corresponding IF, then the expression
tested by the IF would be either TRUE or FALSE. If the condition is
TRUE, the code following the ELSE would not be executed. If the
condition is FALSE, the ELSE and everything following it would not be
executed.
ELSE is analogous to IF '$TEST, except the latter statement switches
$TEST to its complement and ELSE never alters $TEST.
The scope of an ELSE can be extended with DO or XECUTE commands.
2 Ex_of_Else
Examples of Else
Example:
IF x=+x SET x=x+y
ELSE WRITE !,x
The IF command evaluates the conditional expression x=+x and sets
$TEST. If $TEST=1 (TRUE), GT.M executes the commands following the IF.
The ELSE on the following line specifies an alternative action to take
if the expression is false.
Example:
IF x=+x DO ^GOFISH
ELSE SET x=x_"^"_y
The DO with an argument after the IF raises the possibility that the
routine ^GOFISH changes the value of $TEST, thus making it possible to
execute both the commands following the IF and the commands following
the ELSE.
Example:
OPEN dev::0 ELSE WRITE !,"Device unavailable" QUIT
This ELSE depends on the result of the timeout on the OPEN command. If
the OPEN succeeds, it sets $TEST to one (1) and GT.M skips the rest of
the line after the ELSE. If the OPEN fails, it sets $TEST to zero (0),
and GT.M executes the remainder of the line after the ELSE.
1 FOR
For
The FOR command provides a looping mechanism in GT.M. A FOR command
does not generate an additional level on the GT.M invocation stack.
The format of the FOR command is:
F[OR][lvn=expr[:numexpr1[:numexpr2]][,...]]]
o Because FOR is a conditional command, it does not support a command
postconditional.
o The scope of the FOR is the remainder of the line.
o When the FOR has no argument, at least two (2) spaces must follow
the command to separate it from the next command on the line. This
specifies a loop that must be terminated by a QUIT, HALT, GOTO, or
ZGOTO.
o The optional local variable name specifies a loop control variable
delimited by an equal sign (=). A FOR command has only one control
variable, even when it has multiple arguments.
o When initiating the FOR, GT.M assigns the loop control variable the
value of the expression. When only an initial value appears, GT.M
executes the remainder of the line once for that argument without
forcing the control variable to be numeric.
o If the argument includes an increment and, optionally, a
terminator, GT.M treats the initial expression as a number.
o The optional numeric expression after the first colon (:) delimiter
specifies the increment for each iteration. The FOR command does
not increment the control variable on the first iteration.
o The optional numeric expression after the second colon (:)
delimiter specifies the limiting value for the control variable.
This expression is evaluated only when the control variable is
initialized to the corresponding initial value, then used for all
subsequent iterations.
o GT.M does not execute the commands on the same line following the
FOR if:
The increment is non-negative and the initial value of the control
variable is greater than the limiting value.
The increment is negative and the initial value of the control variable
is less than the limiting value.
o After the first iteration, GT.M does not alter the control variable
and ceases execution under the control of the FOR if:
The increment is non-negative, and altering the control variable by the
increment would cause the control variable to be greater than the
limiting value.
The increment is negative, and altering the control variable by the
increment would cause the control variable to be less than the limiting
value.
o When the FOR has multiple arguments, each one affects the loop
control variable in sequence. For an argument to gain control, no
prior argument to the FOR can have an increment without a limit.
Increments and limits may be positive, negative, an integer, or a
fraction. GT.M never increments a control variable "beyond" a limit.
Other commands may alter a control variable within the extended scope
of a FOR that it controls. When the argument includes a limit, such
modification can cause the FOR argument to yield control at the start
of the next iteration.
The scope of a FOR can be extended with DO or XECUTE commands.
GT.M terminates the execution of a FOR when it executes an explicit
QUIT or a GOTO (or ZGOTO in GT.M) that appears on the line after the
FOR. FOR commands with arguments that have increments without limits
and argumentless FORs can be infinite loops. Such FORs must terminate
with a QUIT or a GOTO within the immediate scope of the FOR. Also, such
FORs can, but seldom, terminate by a HALT within the scope of the FOR
as extended by DOs, XECUTEs, and extrinsics. FORs terminated by such
commands act as "while" or "until" control mechanisms.
2 Ex_of_For
Examples of FOR
Example:
GTM>KILL i FOR i=1:1:5 WRITE !,i
1
2
3
4
5
GTM>WRITE i
5
GTM>
This FOR loop has a control variable, i, which has the value one (1) on
the first iteration, then the value two (2), and so on, until in the
last iteration i has the value five (5). The FOR terminates because
incrementing i would cause it to exceed the limit. Notice that i is not
incremented beyond the limit.
Example:
GTM>FOR x="hello",2,"goodbye" WRITE !,x
hello
2
goodbye
GTM>
This FOR loop uses the control variable x and a series of arguments
that have no increments or limits. Notice that the control variable may
have a string value.
Example:
GTM>FOR x="hello":1:-1 WRITE !,x
GTM>ZWRITE x
x=0
GTM>
Because the argument has an increment, the FOR initializes the control
variable x to the numeric evaluation of "hello" (0). Then, GT.M never
executes the remainder of the line because the increment is positive,
and the value of the control variable (0) is greater than the limiting
value (-1).
Example:
GTM>FOR y=-1:-3:-6,y:4:y+10,"end" WRITE !,y
-1
-4
-4
0
4
end
GTM>
This FOR uses two limited loop arguments and one value argument. The
first argument initializes y to negative one (-1), then increments y to
negative four (-4). Because another increment would cause y to be less
than the limit (-6), the first argument terminates with y equal to
negative four (-4). The second argument initializes the loop control
variable to its current value and establishes a limit of six (6=-4+10).
After two iterations, incrementing y again would cause it to be greater
than the limit (6), so the second argument terminates with y equal to
four (4). Because the final argument has no increment, the FOR sets y
to the value of the argument, and GT.M executes the commands following
the FOR one more time.
Example:
GTM>S x="" F S x=$O(ar(x)) Q:x="" W !,x
This example shows an argumentless FOR used to examine all first level
subscripts of the local array ar. When $ORDER indicates that this level
contains no more subscripts, the QUIT with the postconditional
terminates the loop.
1 GOTO
Goto
The GOTO command transfers execution to a location specified by its
argument.
The format of the GOTO command is:
G[OTO][:tvexpr] entryref
[:tvexpr][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required entryref specifies the target location for the control
transfer.
o The optional truth-valued expression immediately following the
entryref specifies the argument postconditional, and controls
whether GT.M performs a GOTO with that argument.
o An indirection operator and an expression atom evaluating to a list
of one or more GOTO arguments form a legal argument to a GOTO.
A GOTO command within a line following a FOR command terminates that
FOR command.
2 Ex_of_Goto
Examples of GOTO
Example:
GTM>GOTO TIME+4
This GOTO command transfers control from Direct Mode to the line that
is four (4) lines after the line labeled TIME (in the currently active
routine). Using an offset is typically a debugging technique and rarely
used in production code.
Example:
GOTO A:x<0,^A:x=0,A^B
This GOTO command transfers control to label A in the current routine,
if x is less than zero (0), to routine ^A if x is equal to zero (0), or
to label A in routine ^B. Once any of the transfers occurs, the rest of
the arguments have no effect.
1 HALT
Halt
The HALT command stops GT.M program execution and causes GT.M to return
control to the operating system environment that invoked the GT.M
image.
The format of the HALT command is:
H[ALT][:tvexpr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether GT.M
executes the command.
o Because the HALT command has no argument, at least two (2) spaces
must follow the command to separate it from the next command on the
line. Note that additional commands do not serve any purpose unless
the HALT has a postconditional.
A HALT releases all shared resources held by the process, such as
devices OPENed in GT.M, databases, and GT.M LOCKs. If the value of
$TLEVEL is greater than zero (0), a ROLLBACK is performed.
Because HALT and HANG share the same abbreviation (H), GT.M
differentiates them based on whether an argument follows the command.
Example:
$ gtm
GTM>HALT
$
Because we invoke this GT.M image interactively, the HALT in Direct
Mode leaves the process at the shell prompt.
1 HANG
Hang
The HANG command suspends GT.M program execution for a period of time
specified by the command argument.
The format of the HANG command is:
H[ANG][:tvexpr] numexpr[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The numeric expression specifies the time in seconds to elapse
before resuming execution; actual elapsed time may vary slightly
from the specified time. If the numeric expression is negative,
HANG has no effect. Portability requirements for GT.M only
guarantee accuracy to the nearest second.However, more accuracy can
be found on different UNIX systems.
o An indirection operator and an expression atom evaluating to a list
of one or more HANG arguments form a legal argument to a HANG.
A process that repeatedly tests for some event, such as a device
becoming available or another process modifying a global variable, may
use a HANG to limit its consumption of computing resources.
Because HALT and HANG share the same abbreviation (H), GT.M
differentiates them based on whether an argument follows the command.
2 Ex_of_Hang
Examples of HANG
Example:
FOR QUIT:$D(^CTRL(1)) HANG 30
This FOR loop repeatedly tests for the existence of ^CTRL(1), and
terminates when that global variable exists. Otherwise the routine
HANGs for 30 seconds and tests again.
Example:
SET t=1 F Q:$D(^CTRL(1)) H t I t<30 S t=t+1
This is similar to the previous example, except that it uses an
adaptive time that lengthens from 1 second to a limit of 30 seconds if
the routine stays in the loop.
1 IF
IF
The IF command provides conditional execution of the remaining commands
on the line. When IF has an argument, it updates $TEST with the truth
value of its evaluated argument. GT.M executes the remainder of a line
after an IF statement when $TEST is 1 (TRUE). When $TEST is 0 (FALSE),
GT.M does not execute the rest of the line.
The format of the IF command is:
I[F] [tvexpr[,...]]
o Because IF is a conditional command, it does not support a command
postconditional.
o The scope of the IF is the remainder of the line.
o The action of IF is controlled by the value of the expression and
by $TEST, if there is no expression.
o IF with no argument acts on the existing value of $TEST (which it
does not change); in this case, at least two (2) spaces must follow
the IF to separate it from the next command on the line.
o An indirection operator, and an expression atom evaluating to a
list of one or more IF arguments form a legal argument to IF.
Example:
IF A,B ...
is equivalent to
IF A IF B
An IF with more than one argument behaves as if those arguments were
logically "ANDed." However, execution of the line ceases with the
evaluation of the first false argument. For IF argument expressions
containing the "AND" operator (&), execution still ceases with the
evaluation of the first false argument. Any global references within
the expression act in sequence to maintain the naked reference.
Postconditionals perform a function similar to IF; however, their scope
is limited to a single command or argument, and they do not modify
$TEST. For more information on postconditionals.
2 Ex_of_IF
Examples of IF
Example:
IF x=+x!(x="") DO BAL
In this example, the DO executes if x contains a number or a null
string.
Example:
WRITE !,?50,BAL IF 'BAL WRITE "****"
IF S EMPTY(acct)=""
The IF in the first line changes the value of $TEST, determining the
execution of the code following the argumentless IF in the second line.
Such argumentless IFs may serve as a form of line continuation.
Example:
GTM>SET X=1,Y=1,Z=2 KILL UNDEF
GTM>IF X=1,Y=1,Z=3,UNDEF=0 W "HI"
GTM>
The IF command causes GT.M to cease executing the line after it
determines Z is not equal to three (3). Therefore, GT.M never evaluates
the reference to the undefined variable and never generates an error.
Example:
GTM>SET X=1 KILL UNDEF
GTM>IF X=1!(UNDEF=3) WRITE "HI"
HI
GTM>
Because GT.M recognizes that the X=1 fulfills the IF, it skips
evaluation of the UNDEF variable and executes this IF command without
generating an error. Because GT.M does not require such optimizations
and in fact discourages them by requiring that all global references
maintain the naked indicator, other implementations may generate an
error.
1 JOB
Job
The JOB command initiates another GT.M process that executes the named
routine.
$ZJOB is set to the pid of the process created by the JOB command. For
details refer to the "$ZJOB" section in the "Intrinsic Special
Variable" chapter of GT.M Programmer's Guide.
The format of the JOB command is:
J[OB][:tvexpr] entryref
[(expr[,...])]
[:[(keyword[=value][:...])][:numexpr]][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required entryref specifies a location at which the new process
starts.
o The optional parameter list enclosed in parentheses () contains
parameters to pass to the routine entry point.
o If the JOB specifies a parameter list, the entryref location must
start with a label and a formallist. GT.M prohibits entryrefs with
offsets during parameter passing.
o The optional elements in the parameter list specify expressions
that the JOB evaluates and passes as values.
o The keywords specify optional processparameters that control
aspects of the environment for the new process.
o If the JOB command has only one processparameter, the surrounding
parentheses are optional.
o Some keywords take numeric or string literals delimited by an equal
sign (=) as arguments. Because the values are constants, strings
must be enclosed in quotation marks (" "), and variable arguments
require that the entire argument be constructed and referenced
using indirection.
o The optional numeric expression specifies a time in seconds after
which the command should timeout if unsuccessful; 0 results in a
single attempt.
o When a JOB command contains no processparameters, double colons
(::) separate the time-out numeric expression from the entryref.
o An indirection operator and an expression atom, evaluating to a
list of one or more JOB command arguments, form a legal argument
for a JOB command.
o The maximum command-line length from a JOB command is 8192 bytes.
The operating system deletes the resultant process when execution of
its GT.M process is complete. The resultant process executes
asynchrounously with the current process. Once GT.M starts the
resultant process, the current process continues.
If a JOB command specifies a timeout, and GT.M creates the resultant
process before the timeout elapses, JOB sets $TEST to true (1). If GT.M
cannot create the process within the specified timeout, JOB sets $TEST
to false (0). If a JOB command does not specify a timeout, the
execution of the command does not affect $TEST.
If GT.M cannot create the process because of something that is unlikely
to change during the timeout interval, such as invalid DEFAULT
directory specification, or the parameter list is too long, the JOB
command generates a run-time error. If the command does not specify a
timeout and the environment does not provide adequate resources, the
process waits until resources become available to create the resultant
process.
2 The_JOB_Env
The JOB Environment
When the JOB is forked, UNIX creates the environment for the new
process by copying the environment of the process issuing the JOB
command and making a few minor modifications.By default, the standard
input is assigned to the null device, the standard output is assigned
to routinename.mjo, and the standard error is assigned to
routinename.mje.
3 JOB_Impl_for_Dir
JOB Implications for Directories
By default, GT.M uses the current working directory of the parent
process for the working directory of the initiated process.
If the files specified by processparameters do not exist, and GT.M does
not have permission to create them, the JOBed process terminates. When
the corresponding files are in the current working directory, the
OUTPUT, INPUT, and ERROR processparameters do not require a full
pathname.
2 JOB_ProcParam
JOB Processparameters
The following sections describe the processparameters available for the
JOB command in GT.M.
3 DEFAULT
DEF[AULT]=strlit
The string literal specifies the default directory.
The maximum directory length is 255 characters.
If the JOB command does not specify a DEFAULT directory, GT.M uses the
current default directory of the parent process.
3 ERROR
ERR[OR]=strlit
The string literal specifies a value for stderr.
The maximum string length is 255 characters.
By default, JOB constructs the error file from the routinename using a
file extension of .mje: the default directory of the process created by
the JOB command.
3 GBLDIR
GBL[DIR]=strlit
The string literal specifies a value for the environment variable
gtmgbldir.
The maximum length of the value permitted is 255 characters.
By default, the job uses the same specification for gtmgbldir as that
defined for the process using the JOB command.
3 INPUT
IN[PUT]=strlit
The string literal specifies a value for stdin.
The maximum string length is 255 characters.
GT.M does not supply a default file extension.
By default, the job takes its input from the null device.
3 OUTPUT
OUT[PUT]=strlit
The string literal specifies a value for stdout.
The maximum string length is 255 characters.
By default, JOB constructs the output file pathname from the
routinename using a file extension of .mjo and the current default
directory of the process created by the JOB command.
3 STARTUP
STA[RTUP]=strlit
The string literal specifies a command line that GT.M invokes a shell
to execute before executing the GT.M routine. The command line may
invoke a shell script or other images.
The executed command does not affect the environment of the JOBed
process.
2 Ex_of_JOB
Examples of JOB
Example:
GTM>JOB ^TEST
This creates a job that starts doing the routine ^TEST in the current
working directory.
Example:
JOB PRINTLABELS(TYPE,PRNTR,WAITIM)
This passes three values (TYPE, PRNTR, and WAITIM) to the new job,
which starts at the label PRINTLABELS of the current routine.
1 KILL
Kill
The KILL command deletes local or global variables and their descendant
nodes.
The format of the KILL command is:
K[ILL][:tvexpr] [glvn|[(]lvn[,...][)][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional global or local variable name specifies the variable
to delete; KILL deletes not only the variable specified in the
argument, but also all variables descended from that variable, that
is, those starting with the identical key-prefix.
o KILLing a variable that does not currently exist has no effect.
o The KILL command without an argument deletes all currently existing
local variables; in this case, at least two (2) spaces must follow
the KILL to separate it from the next command on the line.
o When a KILL argument is enclosed in parentheses, that "exclusive"
KILL deletes all local variables except those listed in the
argument.
o An indirection operator and an expression atom evaluating to a list
of one or more KILL arguments
o form a legal argument for a KILL.
KILL does not affect copies of local variables that have been "stacked"
by NEW or parameter passing.
Because a KILL can have a major impact, use KILL with caution.
2 Ex_of_Kill
Examples of KILL
Example:
GTM>KILL SET a=0,a(1)=1,a(1,1)="under" KILL a(1) ZWR
a=0
GTM>
This uses an argumentless KILL to get a "fresh start" by deleting all
existing local variables. After SETting a, a(1), and a(1,1), the KILL
deletes a(1) and its descendants. The ZWRITE shows only a remaining.
Example:
GTM>KILL (a,b),^AB(a,b)
The first argument (an exclusive KILL) specifies to KILL all local
variables except a and b. The second argument deletes ^AB(a,b) and any
descendants of that global variable node.
1 LOCK
Lock
The LOCK command is used to reserve and release resource names,
providing a semaphore capability for GT.M processes. This capability
can be used for interprocess synchronization and signaling.
Assigning a LOCK does not specify any explicit control over variables
and does not directly effect either read or write access to global (or
local) data. However, an application that adheres to clearly defined
conventions of LOCKing before any access can indirectly achieve such an
effect.
The format of the LOCK command is:
L[OCK][:tvexpr] [[-|+]nref|(nref[,...])[:numexpr]
[,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The nref argument specifies a resource name in the format of the
GT.M name, with or without subscripts and with or without a
preceding caret (^). An nref can optionally have an environment
specification, including one without a preceding caret (^).
o Outside of transactions, only one process in an environment can own
a particular LOCK at any given time.
o Because the data storage in GT.M uses hierarchical sparse arrays,
and LOCK frequently serves to protect that data from inappropriate
"simultaneous" access by multiple processes, LOCK treats resource
names in a hierarchical fashion; a LOCK protects not only the named
resource, but also its ancestors and descendants.
o When one or more nrefs are enclosed in parentheses (), LOCK
reserves all the enclosed names "simultaneously," that is, it
reserves none of them until all become available.
o A LOCK with no argument or an argument with no leading sign
releases all names currently reserved with previous LOCK commands
by the process; when a LOCK has no argument, at least two (2)
spaces must follow the LOCK to separate it from the next command on
the line.
o A LOCK argument with a leading plus sign (+) acquires the named
resources without releasing currently held resources; if the named
resource is already LOCKed, such a LOCK "counts up" the process
interest in the resource.
o A LOCK argument with a leading minus sign (-) "counts down" the
process interest in a named resource; if the count on a particular
lock reaches zero (0), GT.M releases the lock without releasing any
other currently held locks; a LOCK that releases a named resource
not currently owned by the process has no effect.
o The optional numeric expression specifies a time in seconds after
which the command should timeout if unsuccessful; 0 provides a
single attempt.
o An indirection operator and an expression atom evaluating to a list
of one or more LOCK arguments form a legal argument for a LOCK.
GT.M records LOCK and ZALLOCATE information in the "lock database."
GT.M distributes the lock database in space associated with the
database identified by the current Global Directory. However, the lock
database does not overlap or coincide with the body of the database
files holding the global data. Only the LOCK, ZALLOCATE and ZDEALLOCATE
commands, and the LKE utility program access the lock database.
GT.M maps reservations of names starting with ^ to the database file
used to map global variables of the same name. If the Global Directory
maps the name A to file A.DAT, GT.M maps all reservations on ^A to file
space associated with A.DAT.
GT.M maps reservations on names not starting with ^ to the region of
the database specified with the GDE command LOCK -REGION=. By default,
when GDE creates a Global Directory any reservations of local names are
mapped to the region DEFAULT.
These two factors effect the following result in the programming
environment:
o ^ reservations automatically intersect for all users of the same
data in any database file independent of the Global Directory
mapping that file.
o reservations without a leading ^ intersect in an arbitrary pattern
dependent on the Global Directory and therefore controlled by a
design decision made independently of application code design.
Since GT.M uses resource names as semaphores for signaling among
multiple processes in a database environment, they interlock in a tree
structured fashion. When LOCK or ZALLOCATE reserves a subscripted
resource name such as ^D(1), other users of the database mapped by the
LOCKing (or ZALLOCATEing) process cannot reserve ancestors of that
name, such as ^D, or descendants, such as ^D(1,2), until LOCK or
ZDEALLOCATE releases that name.
Execution of the LOCK command does not affect the value or the state of
a variable. LOCK tests each argument to determine whether the process
can claim the name space. If another GT.M process has a LOCK on that
name space, GT.M suspends the current process until the other process
releases the name space. To prevent the potential "infinite" suspension
of a routine execution, specify a timeout for the LOCK command.
LOCK with a leading plus (+) or minus (-) sign (incremental LOCKing)
allows the acquisition of locks without releasing currently held locks.
This can lead to deadlocks.
To avoid deadlocks, use LOCK without a leading + or - sign on its
arguments because such a command releases all previously LOCKed
resources; or use a timeout with the LOCK command.
If a LOCK command specifies a timeout, and GT.M acquires ownership of
the named resource before the timeout elapses, LOCK
sets $TEST to TRUE (1). If GT.M cannot acquire ownership of the named
resource within the specified timeout, LOCK sets $TEST to FALSE (0). If
a LOCK command does not specify a timeout, the execution of the command
does not affect $TEST. If a LOCK with an argument having a leading
minus sign (-) specifies a timeout, the command always sets $TEST to
TRUE (1).
If a process issues a LOCK command for a named resource already
ZALLOCATEd by that process, the resource is both ZALLOCATEd and LOCKed.
LOCK does not release ZALLOCATEd resources. To release such a named
resource, the process must both ZDEALLOCATE and unLOCK the resource.
For more information on ZALLOCATE, refer to the "ZALLOCATE".
2 Locks_within_Trans
Using Locks within Transactions
Within transactions LOCKs are used by GT.M to ensure the ability to
serialize. There is no guarantee, however, that attempts by other
processes to examine LOCKs held with a transaction will produce the
same results as when LOCKs are outside of a transaction. In other
words, LOCKs within transactions should never be used as simple
semaphores.
The LOCK command locks a specified resource name that controls a tree
structured name space. Outside of transactions when one process in an
environment acquires a LOCK or a ZALLOCATE on a named resource, no
other GT.M process in that environment can LOCK a resource with an
"overlapping" name until the first process releases the LOCK that it
holds.
2 Ex_of_Lock
Examples of LOCK
Example:
LOCK A,^B,@C
LOCK (A,B,@C)
The first LOCK command LOCKs A and unLOCKs A before LOCKing ^B, then
unLOCKs ^B before locking the name specified by the variable C. The
second LOCK command acquires all three resources at once. GT.M waits
until all the named resources in the argument list become available
before LOCKing all the resources. For example, if the resource
specified by the variable C is not available for LOCKing, GT.M waits
until that resource becomes available before LOCKing A and ^B.
Example:
LOCK (A,B)
LOCK +C
LOCK -B
This LOCKs A and B, then incrementally LOCKs C. Finally it releases the
LOCK on B, while retaining the LOCKs on A and C.
Example:
LOCK (A,B,C)
LOCK +(B,C)
LOCK -(B)
This LOCKs A, B and C together. It then increments the lock "counts" of
B and C. The last LOCK command removes one "count" of B, leaving one
count of A and B and two counts of C.
Example:
LOCK ^D:5
This command attempts to LOCK ^D with a timeout of five seconds. If
LOCK acquires the named resource before the timeout elapses, GT.M sets
$TEST to 1 (TRUE). If LOCK fails to acquire the named resource before
the timeout elapses, GT.M sets $TEST to 0 (FALSE).
1 MERGE
Merge
The MERGE command copies a variable and all its descendants into
another variable. MERGE does not delete the destination variable, nor
any of its descendants.
The format of MERGE command is:
M[ERGE][:tvexpr] glvn1=glvn2[,...]
o The optional truth-valued expression immediately following the
command is a command post conditional that controls whether or not
GT.M executes the command.
o When both glvn1 and glvn2 are local variables, the naked indicator
is not changed.
o If glvn2 is a global variable and glvn1 is a local variable, then
the naked indicator references glvn2.
o When both are global variables, the state of the naked indicator is
unchanged if glvn2 is undefined ($DATA(glvn2)=0).
o In all other cases including $DATA(glvn2)=10, the naked indicator
takes the same value that it would have if the SET command replaced
the MERGE command and glvn2 had a value.
o If glvn1 is a descendant of glvn2, or if glvn2 is a descendant of
glvn1; GT.M generates an error.
o An indirection operator and an expression atom evaluating to a list
of one or more MERGE arguments form a legal argument for a MERGE.
MERGE simplifies the copying of a sub-tree of a local or global
variable to another local or global variable. A sub-tree is all global
or local variables that are descendants of an specified variable. MERGE
offers a one-command alternative to the current technique for doing
sub-tree copy (that is, a series of SET commands with $ORDER
references).
GT.M may permit certain syntax or actions that are described by the
standard as in error. For example, a MERGE command that specifies
an operation where the source and destination overlap but
$DATA(source)=0 does not produce an error (which is equivalent to a
no-operation).
2 Ex_of_Merge
Examples of MERGE
Example:
GTM>SET ^gbl1="one"
GTM>SET ^gbl1(1,1)="oneone"
GTM>SET ^gbl1(1,1,3)="oneonethree"
GTM>SET ^gbl1(1,2,4)="onetwofour"
GTM>SET ^gbl2(2)="gbl2_2"
GTM>SET ^gbl2(2,1,3)="gbl2_2_1_3"
GTM>SET ^gbl2(2,1,4,5)="gbl2_2_1_4_5"
GTM>MERGE ^gbl1(1)=^gbl2(2)
GTM>WRITE $REFERENCE
^gbl1(1)
GTM>ZWRITE ^gbl1
^gbl1="one"
^gbl1(1)="gbl2_2"
^gbl1(1,1)="oneone"
^gbl1(1,1,3)="gbl2_2_1_3"
^gbl1(1,1,4,5)="gbl2_2_1_4_5"
^gbl1(1,2,4)="onetwofour"
GTM>ZWRITE ^gbl2
^gbl2(2)="gbl2_2"
^gbl2(2,1,3)="gbl2_2_1_3"
^gbl2(2,1,4,5)="gbl2_2_1_4_5"
GTM>
The example illustrates how MERGE copies a sub-tree of one global into
another. The nodes in the sub-tree of ^gbl(2), for which $DATA() value
is 1 or 11, are copied to sub-tree of ^gbl1(1) as follows:
^gbl1(1) is updated with value of ^gbl2(2)
^gbl1(1,1,3) is updated with value of ^gbl2(2,1,3)
^gbl1(1,1,4,5) is updated with value of ^gbl2(2,1,4,5)
Since ^gbl1(2,1) and ^gbl2(2,2,4) do not have values ($DATA()=0), the
corresponding nodes ^gbl1(1,1) and ^gbl(1,2,4) respectively are left
unchanged. The naked indicator takes the value ^gbl(1) as if SET
replaced MERGE. Notice that the MERGE command does not change ^gbl2(2)
or its descendants. Ancestor nodes of ^gbl(1) are also left unchanged.
Example:
GTM>KILL
GTM>SET ^gbl(1,2)="1,2"
GTM>MERGE lcl(3,4)=^gbl(1)
GTM>SET ^("naked")=2
GTM>ZWRITE ^gbl
^gbl(1,2)="1,2"
^gbl("naked")=2
GTM>ZWRITE lcl
lcl(3,4,2)="1,2"
GTM>
The example illustrates how MERGE creates a sub-tree of a variable when
the variable does not exist. Also, notice how the naked indicator is
set when the source of the MERGE is a global and the destination a
local.
1 NEW
New
The NEW command "stacks" copies of local variables and reinitializes
the variables. An explicit or implicit QUIT from a DO, XECUTE or
extrinsic function "unstacks" the NEWed variables, that is, restores
the variable to the stacked value. A NEW lasts only for the current
scope of execution.
The format of the NEW command is:
N[EW][:tvexpr] [[(]lvn[,...][)][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o NEW arguments are unsubscripted local variable names; NEW affects
not only the variable specified in the argument, but also all
variables descended from that variable.
o When an undefined variable is NEWed, the fact that it is undefined
is "stacked", and when leaving the current scope, it returns to
being undefined, that is, the variable is KILLed.
o Without an argument GT.M NEWs all currently existing local
variables; in this case, at least two (2) spaces must follow the
NEW to separate it from the next command on the line.
o When a NEW argument is enclosed in parentheses, that NEW is
considered "exclusive" and the variables inside the parentheses are
excluded from the effect of the NEW.
o When the flow of execution leaves the scope of an argumentless or
an exclusive NEW, GT.M restores all stacked variables to their
previous values, and deletes all other local variables.
o The intrinsic special variables $ESTACK, $ETRAP, $ZGBLDIR, and
$ZYERROR can be an explicit argument of a NEW.
o The intrinsic special variable $ZTRAP can also be an explicit
argument of a NEW; this stacks the current value of $ZTRAP and
assigns $ZTRAP a null value ($ZTRAP="").
o An indirection operator and an expression atom evaluating to a list
of one or more NEW arguments form a legal argument for a NEW.
The NEW command provides a means of confining the scope of local
variables. NEW operates only on unsubscripted local names and acts on
the entire named array.
2 Ex_of_New
Examples of NEW
Example:
SET A(1)=1,B=4,C=5
WRITE !,"VARIABLES BEFORE NEW:",!
ZWRITE
DO LABEL
WRITE !,"VARIABLES AFTER RETURN:",!
ZWRITE
QUIT
LABEL NEW A SET C=7
WRITE !,"VARIABLES AFTER NEW:",!
ZWRITE
QUIT
Produces the results:
VARIABLES BEFORE NEW:
A(1)=1
B=4
C=5
VARIABLES AFTER NEW:
B=4
C=7
VARIABLES AFTER RETURN:
A(1)=1
B=4
C=7
Example:
SET (A,B,C,D)="TEST"
DO LABEL
WRITE !,"VARIABLES AFTER RETURN:",!
ZWRITE
QUIT
LABEL NEW (B,C) SET (A,B,Z)="NEW"
WRITE !,"VARIABLES AFTER EXCLUSIVE NEW:",!
ZWRITE
QUIT
Produces the results:
VARIABLES AFTER EXCLUSIVE NEW:
A="NEW"
B="NEW"
C="TEST"
Z="NEW"
VARIABLES AFTER RETURN:
A="TEST"
B="NEW"
C="TEST"
D="TEST"
1 OPEN
Open
The OPEN command creates a connection between a GT.M process and a
device.
The format of the OPEN command is:
O[PEN][:tvexpr] expr[:[(keyword[=expr][:...])]
[:numexpr]][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required expression specifies the device to OPEN.
o The optional keywords specify deviceparameters that control device
behavior; some deviceparameters take arguments delimited by an
equal sign (=); if the argument only contains one deviceparameter,
the surrounding parentheses are optional.
o The optional numeric expression specifies a time in seconds after
which the command should timeout if unsuccessful; choosing 0
results in a single attempt to open the device.
o When an OPEN command specifying a timeout contains no
deviceparameters, double colons (::) separate the timeout numeric
expression from the device expression.
o An indirection operator and an expression atom evaluating to a list
of one or more OPEN arguments form a legal argument for an OPEN.
1 QUIT
Quit
Except when a QUIT appears on a line after a FOR, the QUIT command
terminates execution of the current GT.M invocation stack level
initiated by a DO, XECUTE, extrinsic function or special variable, and
returns control to the next "lower" level. In this case, QUIT restores
any values stacked at the current level by NEWs or by parameter
passing. When a QUIT appears on the line following a FOR, it terminates
execution of the FOR.
The format of the QUIT command is:
Q[UIT][:tvexpr] [expr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o When a QUIT terminates an extrinsic function, it must have an
argument that supplies the value returned by the function; in all
other cases, QUIT must not have an argument and must be followed by
at least two (2) spaces to separate it from the next command on the
line.
o An indirection operator and an expression atom evaluating to a QUIT
argument form a legal argument for a QUIT.
The QUIT performs two similar, but different, functions depending on
its context. Because FORs do not add levels to the GT.M invocation
stack, QUITs inside FOR loops simply terminate the loop. QUITs that
terminate DOs, XECUTEs and extrinsics remove a GT.M invocation stack
level and therefore may adjust the local variable environment resulting
from previous NEWs or parameter passing. A QUIT from an extrinsic or a
frame created by an argumentless DO restores $TEST to its stacked
value.
Attempting to QUIT (implicitly or explicitly) from code invoked by a
DO, XECUTE or extrinsic after that code issued a TSTART not yet matched
by a TCOMMIT, produces an error.
2 Ex_of_Quit
Examples of QUIT
Example:
DO A
QUIT
A WRITE !,"This is label A"
The explicit QUIT at the line preceding the label A prevents line A
from executing twice. The sub-routine at line A terminates with the
implicit QUIT at the end of the routine.
Example:
WRITE $$ESV
QUIT
ESV()
QUIT "value of this Extrinsic Special Variable"
Because the label ESV has an argument list (which is empty), GT.M can
only legally reach that label with a extrinsic invocation. The QUIT on
the second line prevents execution from erroneously "falling through"
to the line labelled ESV. Because ESV identifies a subroutine that
implements an extrinsic special variable, the QUIT on the line after
ESV has an argument to provide the value of the extrinsic.
Example:
SET x="" F S x=$O(^BAL(x)) Q:x]]"AR5999"!'$L(x) D STF
The postconditional QUIT terminates the FOR loop.
1 READ
Read
The READ command transfers input from the current device to a global or
local variable specified as a READ argument. For convenience, READ also
accepts arguments that perform limited output to the current device.
The format of the READ command is:
R[EAD][:tvexpr] (glvn|*glvn|glvn#intexpr)[:numexpr]|strlit|fcc[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o A subscripted or unsubscripted global or local variable name
specifies a variable into which to store the input; the variable
does not have to exist prior to the READ; if the variable does
exist prior to the READ, the READ replaces its old value.
o When an asterisk (*) immediately precedes the variable name, READ
accepts one character of input and places the ASCII code for that
character into the variable.
o When a number-sign (#) and a non-zero integer expression
immediately follow the variable name, the integer expression
determines the maximum number of characters accepted as input to
the read; such reads terminate when GT.M reads the number of
characters specified by the integer expression or a terminator
character in the input stream, whichever occurs first.
o The optional numeric expression specifies a time in seconds at
most, for which the command waits for input to be terminated. When
a timeout is specified, if the input has been terminated before the
timeout expires, $TEST is set to 1 (true), otherwise, $TEST is set
to 0 (false).
o To provide a concise means of issuing prompts, GT.M sends string
literal and format control character (!,?intexpr,#) arguments of a
READ to the current device as if they were arguments of a WRITE.
o An indirection operator and an expression atom evaluating to a list
of one or more READ arguments form a legal argument for a READ.
1 SET
Set
SET assigns values to variables or to a selected portion of a variable.
The format of the SET command is:
S[ET][:tvexpr] glvn|$EXTRACT()|$PIECE()|(glvn[,...])=expr[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o A subscripted or unsubscripted local or global variable name on the
left of the equal-sign (=) specifies a variable in which to store
the expression found on the right side of the equal-sign; the
variable need not exist prior to the SET; if the variable exists
prior to the SET, the SET replaces its old value.
o During a SET, GT.M evaluates the right side of the equal sign
before the left; this is an exception to the left-to-right order of
evaluation in GT.M and means that GT.M maintains the naked
indicator using the expression on the right-hand side of the equal
sign (=) before setting the variable.
o When the portion of the argument to the left of the equal-sign is
in the form of a list of variables enclosed in parentheses, SET
assigns the value of the expression on the right of the equal sign
to all the variables.
o When the portion of the argument to the left of the equal sign is
in the form of a $PIECE function, SET replaces the specified piece
or pieces of the variable (specified as the first argument to the
$PIECE() form) with the value of the expression on the right side
of the equal-sign; if the variable did not exist prior to the SET
or does not currently contain the pieces identified by the optional
third and fourth arguments to the $PIECE() form, SET adds
sufficient leading delimiters, as specified by the second argument
to the $PIECE form, to make the assignment fit the $PIECE() form.
Note that if the fourth argument exceeds the third argument, the
target glvn is not changed and the naked indicator is also not
modifed.
o When the portion of the argument to the left of the equal sign is
in the form of a $EXTRACT function, SET replaces the specified
character or characters of the variable (specified as the first
argument to the $EXTRACT() form) with the value of the expression
on the right side of the equal-sign; if the variable did not exist
prior to the SET or does not contain the characters identified by
the optional second and third arguments to the $EXTRACT() form, SET
adds sufficient leading spaces to make the assignment fit the
$EXTRACT() form. Note that if the third argument exceeds the second
argument, the target glvn is not changed and the naked indicator is
also not modifed.
o The left-hand side of the equal-sign may also contain any of the
following Intrinsic Special Variables:
$ECODE
$ETRAP
$X
$Y
$ZCOMPILE
$ZDIRECTORY
$ZERROR
$ZGBLDIR
$ZINTERRUPT
$ZMAXTPTIME
$ZPROMPT
$ZROUTINES
$ZSOURCE
$ZSTATUS
$ZSTEP
$ZTRAP
$ZYERROR
o An indirection operator and an expression atom evaluating to a list
of one or more SET arguments form a legal argument for a SET.
Because GT.M does not require predeclaration or typing of variables, a
SET with proper syntax always succeeds regardless of the prior state or
value of the variable, as long as GT.M can evaluate the expression to
the right of the equal sign (=).
2 Ex_of_Set
Examples of SET
Example:
GTM>KILL SET a="x",(b,c)=1,@a="hello" ZWRITE
a=x
b=1
c=1
x="hello"
GTM>
The KILL command deletes any previously defined local variables. The
SET command has three arguments. The first shows a simple direct
assignment. The second shows the form that assigns the same value to
multiple variables. The third shows atomic indirection on the left of
the equal sign. The ZWRITE command displays the results of the
assignments.
Example:
GTM>SET ^(3,4)=^X(1,2)
Because GT.M evaluates the right-hand side of the equal sign before the
left-hand side within a SET argument, the right-hand expression
determines the
naked reference indicator prior to evaluation of the left-hand side.
Therefore, this example assigns ^X(1,3,4) the value of ^X(1,2).
Example:
GTM>KILL x SET $P(x,"^",3)="piece 2" ZWRITE x
x="^^piece 2"
GTM>
This SET demonstrates a "setpiece" and shows how SET generates missing
delimiters when required.
Example:
GTM>SET x="I love hotdogs"
GTM>SET $EXTRACT(x,3,6)="want"
GTM>WRITE x
I want hotdogs
GTM>SET $EXTRACT(x,7)=" many "
GTM>WRITE x
I want many hotdogs
GTM>
The SET $EXTRACT command replaces and extracts the specified characters
with the value of the expression on the right hand side of the
equal-sign (=).
1 TCOMMIT
TCommit
The TCOMMIT command marks the end of a transaction or sub-transaction
and decrements $TLEVEL. If TCOMMIT marks the end of a transaction
(decrements $TLEVEL to zero), it invokes a COMMIT, which makes the
database updates performed by the transaction generally available. A
TCOMMIT issued when no transaction is in progress ($TLEVEL=0) produces
an error.
The format of the TCOMMIT command is:
TC[OMMIT][:tvexpr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o Because TCOMMIT has no argument, at least two (2) spaces must
follow the command to separate it from the next command on the
line.
For an example of the use of the TCOMMIT command, refer to the chapter
on General Language Features of M in GT.M Programmer's Guide.
1 TRESTART
TREstart
The TRESTART command attempts to RESTART the current transaction. A
RESTART transfers control back to the initial TSTART and restores much
of the process state to what it was when that TSTART was executed.
Errors are produced if a TRESTART is used when no transaction is in
progress ($TLEVEL=0) and when the transaction does not have RESTART
enabled.
The format for the TRESTART command is:
TRE[START][:tvexpr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o Because TRESTART has no argument, at least two (2) spaces must
follow the command to separate it from the next command on the
line.
TRESTARTs (and implicit RESTARTs) do not restore any device states;
they do restore the following to the state they had when GT.M executed
the initial TSTART:
o $TEST
o The naked indicator
o LOCKs held by the process
They also restore any local variables named by one or more active
TSTARTs to the values they had when they were first named.
For an example of the use of the TRESTART command, refer to the chapter
on "General Language Features of M" in the GT.M Programmer's Guide.
1 TROLLBACK
TROllback
The TROLLBACK command terminates a transaction by causing a ROLLBACK,
which removes all database updates performed within a transaction.
TROLLBACK also sets $TLEVEL and $TRESTART to zero (0). Issuing a
TROLLBACK when no transaction is in progress ($TLEVEL=0) produces an
error.
The format of the TROLLBACK command is:
TRO[LLBACK][:tvexpr] [intexpr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional integer expression indicates an argument specifying
incremental rollback. If the value of the argument expression is
greater than zero, it specifies the value of $TLEVEL to be achieved
by the rollback. If the value of the expression is less than zero,
the result is the number of levels to rollback. For example; -1
means rollback one level. If the argument expression is zero, the
effect is same as not specifying the argument, that is, the entire
GT.M transaction is rolled back.
Attempting to rollback more than $TLEVEL levels (the outermost
transaction) generates an error.
o When the TROLLBACK has no argument, at least two (2) spaces must
follow the command to separate it from the next command on the
line.
In order to allow for error recovery and/or access to the global
context of the error, errors do not initiate implicit ROLLBACKs.
Therefore, the code for handling errors during transactions should
generally include a TROLLBACK. Because the TROLLBACK releases resources
held by the transaction, it should appear as early as possible in the
error handling code.
A TROLLBACK does not cause a transfer of control but is typically
associated with one such as a QUIT or GOTO.
For an example of the use of the TROLLBACK command, refer to the
chapter on "General Language Features of M" in the GT.M Programmer's
Guide.
1 TSTART
TStart
A TSTART command marks the beginning of a transaction or
sub-transaction and increments $TLEVEL. When TSTART marks the beginning
of a transaction ($TLEVEL=1), its arguments determine whether the
transaction may RESTART and whether serializability is enforced. If a
transaction may RESTART, the TSTART arguments determine which local
variables are restored during a RESTART. Serializability is enforced by
LOCK commands or, if the SERIAL keyword is specified, by GT.M.
The format of the TSTART command is:
TS[TART][:tvexpr] [([lvn...])|lvn|*|][:keyword|(keyword...)]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o If $TLEVEL is 0 before the TSTART, the TSTART starts a transaction;
otherwise it starts a sub-transaction.
o If the TSTART initiates a transaction and the portion of the
argument before the colon (:) delimiter is empty, the transaction
is not eligible for RESTART. If the TSTART starts a transaction
($TLEVEL=0) and the portion of the argument before the colon is not
empty, the transaction is eligible for RESTART. If the TSTART is
nested (starts a sub-transaction), its arguments have no effect on
whether the transaction is eligible for RESTART.
o If the portion of the argument before the colon is an asterisk (*),
any subsequent RESTART restores all local variables to the value
they had when the TSTART was executed.
o If the portion of the argument before the colon is an unsubscripted
local variable name or a list of such names enclosed in
parentheses, a RESTART restores the named variables to the value
they had when the TSTART was executed.
o If the portion of the argument before the colon is a set of empty
parentheses (), a RESTART does not restore any local variables.
o The optional portion of the argument after the colon is a keyword
or a colon-separated list of keywords enclosed in parentheses,
where the keywords specify transaction characteristics.
o An indirection operator and an expression atom evaluating to a
TSTART argument form a legal argument for a TSTART.
A TSTART within a transaction starts a sub-transaction. The argument to
such a TSTART has no effect on whether the existing transaction may
RESTART or whether serializability of the transaction is enforced. This
type of TSTART may add local variables to be restored in a transaction
that has RESTART enabled.
It is good coding practice to synchronize enabling of RESTART on
TSTARTs at all levels of a transaction. A nested TSTART that does not
permit RESTART where the transaction does, may indicate that the
sub-transaction has not been coded to properly handle RESTART.
Sub-transactions cannot COMMIT independently from the transaction, nor
can they RESTART independently. Sub-transactions exist largely as a
programming convenience to allow flexibility in organizing code in a
modular fashion, and in addition to allow incremental ROLLBACKs.
When journaling, a transaction with an initial TSTART that has an
argument specifying TRANSACTIONID=expr, where expr is an expression
that evaluates to the keyword (case insensitive) BA[TCH], does not wait
for the journal update to be written before returning control to the
application after a successful TCOMMIT. The goal of this feature is to
permit application control over any performance impact of journaling on
any subset of transactions that can be recreated or recovered by means
other than journaling.
For an example of the use of the TSTART command, refer to the chapter
on "General Language Features of M" in the GT.M Programmer's Guide.
The following keywords may appear in a TSTART argument:
2 SERIAL
S[ERIAL]
The SERIAL keyword indicates that GT.M must ensure the serializability
of the transaction. When the SERIAL keyword is absent, the GT.M program
must ensure serializability by proper use of LOCK commands. On a nested
TSTART, this portion of the argument is ignored.
2 TRANSACTIONID
T[RANSACTIONID]=expr
The TRANSACTIONID keyword declares an arbitrary transaction
identification.
If TRANSACTIONID="BATCH" or "BA" at transaction completion, the process
immediately continues execution. When a process issues a [final]
TCOMMIT for a transaction and journaling is active, by default the
process waits until the entire transaction is written to the journal
file(s) before executing the next command. This ensures that every
transaction is durable before the process moves on to the next step.
Transactions flagged as "BATCH" have lower latency and higher
throughput, but a lower guarantee of durability. Normally this flag is
used when operational procedures (such as a backup) or application code
(such as a checkpoint algorithm) provides an acceptable alternative
means of ensuring durability.
1 USE
Use
The USE command selects the current device for READs (input) and WRITEs
(output).
The format of the USE command is:
U[SE][:tvexpr] expr[:(keyword[=expr][:...])][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required expression specifies the device to make the current
device.
o A USE that selects a device not currently OPENed by the process
causes a run-time error.
o The optional keywords specify deviceparameters that control device
behavior; some deviceparameters take arguments delimited by an
equal sign (=); if the argument only contains one deviceparameter,
the surrounding parentheses are optional.
o An indirection operator and an expression atom evaluating to a list
of one or more USE arguments form a legal argument for a USE.
For more information on USE, devices and deviceparameters, refer to the
"Input/Output Processing" chapter in the GT.M Programmer's Guide.
1 VIEW
View
The VIEW command adjusts an environmental factor selected by a keyword
argument. For example, VIEW controls journal buffer flushing,
determines whether GT.M reports undefined variables as errors or treats
them as null, and determines which BREAK commands should display
messages.
The format of the VIEW command is:
V[IEW][:tvexpr] keyword[:expr2[:...]][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The keyword specifies the environmental factor to change.
o The optional expression following the keyword specifies the nature
of the change to the environmental factor.
o An indirection operator and an expression atom evaluating to a list
of one or more VIEW arguments form a legal argument for a VIEW
2 Key_Words_View
Key Words in VIEW Command
The following sections describe the keywords available for the VIEW
command in GT.M.
3 BREAKMSG
"BREAKMSG":value
Sets the value of the BREAK message mask. When GT.M processes a BREAK
command, the BREAK message mask controls whether to display a message
describing the source of the BREAK.
The mask uses the following four values that are added together to
provide the BREAKMSG value.
1 - BREAKs within the body of a program
2 - BREAKs within a ZBREAK action
4 - BREAKs within a device EXCEPTION
8 - BREAKs within a ZSTEP action
By default GT.M displays all BREAK messages.
Example:
GTM>VIEW "BREAKMSG":5
In this example the BREAKMSG value is 5, representing the sum of 1 and
4. This enables BREAKS within the body of a program (value 1) and for a
device EXCEPTION (value 4).
3 GDSCERT
"GDSCERT":value
Enables (value=1) or disables (value=0) database block certification.
Database block certification causes GT.M to check the internal
integrity of every block as it writes the block. Block certification
degrades performance and exists primarily as a tool for use by Sanchez.
The default is GDSCERT:0.
3 JNLFLUSH
"JNLFLUSH"[:region]
Writes or flushes journaling buffers associated with the given region
to permanent storage, for example, to disk. If the VIEW "JNLFLUSH" does
not specify the optional region, GT.M flushes all active regions of the
current Global Directory.
Normally GT.M writes journal buffers when it fills the journal buffer
pool or when some period of time passes with no journal activity.
For more information on journaling, refer to the "GT.M Journaling"
chapter in the GT.M Administration and Operations Guide.
3 JNLWAIT
"JNLWAIT"
Causes a process to pause until its journaling buffers have been
written. JNLWAIT ensures that GT.M successfully transfers all database
updates issued by the process to the journal file before the process
continues. Normally, GT.M performs journal buffer writes asynchronously
while the process continues execution.
For more information on journaling, refer to the "GT.M Journaling"
chapter in the GT.M Administration and Operations Guide.
3 JOBPID
"JOBPID":"value"
Enables (value=1) or disables (value=0) the addition of the child
process ID to the output and error filenames generated by the JOB
command.
This option prevents output files generated by the JOB command from
being overwritten each time a new job is spawned from the GT.M source
file.
3 LABELS
"LABELS":"value"
Enables (value="LOWER") or disables (value="UPPER") case sensitivity
for labels within routines.
It is important to have the same case handling at compile-time and
run-time.
Because GT.M stores routines as regular files and file names are case
sensitive on UNIX, GT.M always treates routine names as case sensitive.
3 LVNULLSUBS
"[NO]LVNULLSUBS"
Allows or disallows local arrays to have null subscripts. The default
is LVNULLSUBS.
3 NOISOLATION
"NOISOLATION":<expr>
where expr must evaluate to one of the following forms
o "", that is, empty string : turn off the feature for all globals
for which it has previously been turned on
o "^gvn1,^gvn2,..." : turn on the feature for the globals in the
list, turning it off for globals for which it has previously been
turned on
o "+^gvn1,^gvn2,..." : add these globals to the list of globals that
have this feature turned on
o "-^gvn1,^gvn2,..." : turn off the feature for these globals leaving
the status for other globals unchanged
GT.M transaction processing permits the application to specify a set of
globals that do not require GT.M to preserve Isolation, one of the
"ACID" properties of TP. This shifts the responsibility for Isolation
from GT.M to the application logic, and permits GT.M to relax its TP
Isolation rules. This avoids TP restarts in certain cases thus
improving the performance of the application. For example, if a global
variable includes $JOB as a subscript, the application may be written
and scheduled in such a way that no more than one process uses a node
of that global at any given time. Specifying such a global as
"NOISOLATED" avoids transaction restarts that occur when different
processes concurrently update and access nodes that share the same GDS
block.
The rules for enforcement by GT.M of Isolation, and therefore
potentially Consistency, are relaxed for application-specified global
variables in order to allow the application to manage these properties.
GT.M is responsible for Atomicity and Durability, as well as for
database integrity for all variables, and for Isolation and Consistency
for any global variables for which the application does not accept
responsibility.
Note that if an application incorrectly specifies a global to be
NOISOLATED, severe, and possibly intermittent and difficult to diagnose
damage to application-level integrity is likely to result. A thorough
understanding of the application is necessary before declaring a global
to be noisolated. GT.M preserves database integrity (accessibility) for
NOISOLATED, as well as ISOLATED global variables.
GT.M ignores attempts to turn on (or off) the feature for globals that
already have the feature turned on (or off). It is an error to modify
the isolation-status of a global variable within a transaction across
different references (either reads or writes) of that global
variable.The VIEW command by itself is not considered to be a reference
of the global variable. While not recommended programming practice,
this means that a process can change a global's isolation-status within
a transaction as long as it hasn't referenced it yet.
Any reads on a NOISOLATION global are validated at the time of the read
and not re-validated at TCOMMIT time. This means that if the value that
was read changed after the read but before the TCOMMIT, the transaction
would still be committed. Therefore it is important that any reads on a
NOISOLATED global (if any) should be of data that does not change with
time. Sanchez has not identified applications where this could be an
issue.
3 PATCODE
"PATCODE":"tablename"
Identifies the alternative table of unique patterns for use with the
"?" operator to be loaded from the pattern definition file. For
additional information refer to the "Internationalization" chapter in
the GT.M Programmer's Guide.
3 PATLOAD
"PATLOAD":"file-specification"
Identifies the file containing definitions of unique patterns for use
with the "?" operator. These pattern definitions can be used in place
of, or in addition to, the standard C, N, U, L, and P.
3 UNDEF
"[NO]UNDEF"
Enables or disables handling of undefined variables as errors. With
UNDEF, GT.M handles all references to undefined local or global
variables as errors. With NOUNDEF, GT.M handles all references to
undefined local or global variables as if the variable had a value of
the null string. In other words, GT.M treats all variables appearing in
expressions as if they were the argument of an implicit $GET(). UNDEF
is the default.
3 TRACE
"TRACE":value<expr>
Traces GT.M program execution and generates profiling information about
the lines and functions executed; with low impact on the run-time
performance.
The feature turns on (value=1) or turns off (value=0) tracing. <expr>
must evaluate to a string containing the name of a GT.M global
variable. The global may also have subscripts; however the subscripts
must be literals or the special variable $JOB.
The <expr> is optional when turning tracing off, if it exists, it
overrides the global variable set when tracing was turned on.
GT.M-tracing uses a technique called Basic Block Counting where calls
are made to special profiling functions at key points in a GT.M
program. A trace consists of the following run-time data as output for
each GT.M function, as well as for each GT.M statement:
o The number of times it is executed.
o The total CPU time spent across all invocations for each function
and each GT.M statement as three values: user time, system time,
and total time.
Instead of modifying the generated code as done by common profiling
tools, such as gprof, GT.M tracing operates entirely within the GT.M
run-time system; therefore, this feature does not require a special
compilation, has no effect on code size and minimizes run-time
overhead.
When the feature is turned on, it gathers profiling information for
each line and GT.M function invocation. The reported time for a GT.M
line is the time spent in generated code for that line, and does not
include time spent in entreyrefs called from that line. When profiling
is turned off, the accumulated statistics are loaded into a GT.M
global. GT.M profiling accumulates and provides the data; the user may
choose tools and techniques to analyze the data.
The trace information is stored in the variable in the following
format:
o If <expr> is a global variable without subscripts name such as
"^foo", the trace information is stored in the nodes
^foo(<routine>,<label>) and ^foo(<routine>,<label>,<offset>), each
of which has a value in the form
"<count>:<usertime>,:<systemtime>,:<total_time>" on UNIX.
o If <expr> has a value such as "^foo("MYTRACE",$J)", the trace
information is stored in the nodes
^foo("MYTRACE",<pid>,<routine>,<label>) and
^foo("MYTRACE",<pid>,<routine>,<label>,<offset>), each of which has
a value in the form "<count>,<usertime>,<systemtime>,<total_time>"
on UNIX as described above.
o For FOR loops, information for each level of the loop is stored in
the nodes as described above, with the extra subscipts "FOR_LOOP".
<for_level> is the value of the number of iterations at that level
of the FOR loop.
Thus, if the GT.M program lv1.m is:
lv1 f i=1:1:10 d
.s l(i)=i
.d bar
for i=1:1:5 for j=1:1:4 s lij(i,j)=i+j
q
bar s l(-i)=-i
q
And the program lv2.m is:
lv2 VIEW "TRACE":1:"^lvtr"
d ^lv1
VIEW "TRACE":0:"^lvtr"
zwr ^lvtr
q
On executing lv2, the output looks like this (times in the example were
chose for clarity of illustration and are not typical):
^lvtr("lv1","bar")="10:8:1:9"
^lvtr("lv1","bar",0)="10:5:1:6"
^lvtr("lv1","bar",1)="10:3:0:3"
^lvtr("lv1","lv1")="1:37:2:39"
^lvtr("lv1","lv1",0)="1:8:0:8"
^lvtr("lv1","lv1",0,"FOR_LOOP",1)=10
^lvtr("lv1","lv1",1)="10:3:1:4"
^lvtr("lv1","lv1",2)="10:19:2:21"
^lvtr("lv1","lv1",3)="1:15:0:15"
^lvtr("lv1","lv1",3,"FOR_LOOP",1)=5
^lvtr("lv1","lv1",3,"FOR_LOOP",2)=20
^lvtr("lv1","lv1",4)="1:0:0:0"
^lvtr("lv2","lv2",1)="1:47:3:50"
In this case, ^lvtr("lv1","bar",0)="10:5:1:6" means that the statement
bar s l(-i)=-i was executed 10 times, with a total of 5 microseconds of
user time and 1 microsecond of system time.
^lvtr("lv1","lv1")="1:37:2:39" means that 37 microseconds of user time
was spent within that GT.M frame (lv1^lv1), and does not include time
spent in routines called from it (such as bar^lv1), whereas
^lvtr("lv1","lv1",3)= "1:15:0:15" includes the time spent at bar^lv1.
Note that there is no data in ^lvtr("lv2","lv2",0) or for
^lvtr("lv2","lv2",2) because the execution of the lines containing the
VIEW commands that turn profiling on and off are not profiled.
Because of the underlying timers provided by the operating systems,
times of less than a microsecond are measured as zero. Therefore, even
if a statement executes one million times, it may report zero time if
it took less than a microsecond each time.
GT.M profiling cannot handle more than 1024 levels. If the GT.M code
executed has more than 1024 levels, frame information cannot be
recorded, and frame information upto the first point where this limit
is reached is reported with a note (":INCOMPLETE DATA: MAXTRACELEVEL" )
appended to the data.
2 Ex_of_View
Examples of VIEW
Example 1:
GTM>KILL A
GTM>VIEW "NOUNDEF"
GTM>WRITE A,?10,$L(A)
0
GTM>
This demonstrates how a VIEW that specifies NOUNDEF prevents UNDEFined
errors.
Example 2:
GTM>ZL "NOSENSE"
%GTM-E-LABELMISSING Label referenced but
not defined:lab
%GTM-I-SRCNAM in source module /usr/work/NOSENSE.m
GTM>
GTM>ZPRINT ^NOSENSE
NOSENSE;
DO lab
QUIT
LAB WRITE !,"THIS IS NOSENSE"
QUIT
GTM>VIEW "LABELS":"UPPER"
GTM>ZLINK "NOSENSE.m"
GTM>DO ^NOSENSE
THIS IS NOSENSE
GTM>
This demonstrates use of VIEW "LABELS" to make label handling case
insensitive. Notice that the routine was ZLINKed with an extension of
.m to force a recompile and ensure that the object code and the
run-time handling of labels is the same.
1 WRITE
Write
The WRITE command transfers a character stream specified by its
arguments to the current device.
The format of the WRITE command is:
W[RITE][:tvexpr] expr|*intexpr|fcc[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o An expression argument supplies the text of a WRITE.
o When a WRITE argument consists of a leading asterisk (*) followed
by an integer expression, WRITE outputs one ASCII character
associated with the ASCII code specified by the integer evaluation
of the expression.
o WRITE arguments may also be format control characters; format
control characters modify the position of a virtual cursor: an
exclamation point (!) produces a new line, a number-sign (#)
produces a new page and a question-mark (?) followed by an
expression moves the virtual cursor to the column specified by the
integer evaluation of the expression provided that the virtual
cursor is to the "left" of the specified column; if the virtual
cursor is not to the left of the specified column, then the text is
printed at the current cursor position.
o An indirection operator and an expression atom evaluating to a list
of one or more WRITE arguments form a legal argument for a WRITE.
For more information on WRITE, devices, input, output and format
control characters, refer to the "Input/Output Processing" chapter in
GT.M Programmer's Guide.
1 XECUTE
Xecute
The XECUTE command makes an entry in the GT.M invocation stack and
executes the argument as GT.M code.
The format of the XECUTE command is:
X[ECUTE]:tvexpr expr[:tvexpr][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required expression specifies a fragment of GT.M source code.
o The optional truth-valued expression immediately following the
argument expression specifies the argument postconditional and
controls whether GT.M performs an XECUTE with that argument.
o An indirection operator and an expression atom evaluating to a list
of one or more XECUTE arguments form a legal argument for an
XECUTE.
An explicit or implicit QUIT within the scope of the XECUTE, but not
within the scope of any other DO, FOR, XECUTE or extrinsic, returns
execution to the instruction following the calling point. This may be
the next XECUTE argument or another command. At the end of the code
specified by the XECUTE argument expression, GT.M performs an implicit
QUIT.
Because XECUTE causes run-time compilation in GT.M, and because it
tends to obscure code, use XECUTE only when other approaches clearly do
not meet your particular requirement.
2 Ex_of_Xecute
Examples of XECUTE
Example:
GTM>SET A="HELLO" XECUTE "WRITE A"
HELLO
GTM>
This demonstrates a simple use of XECUTE.
Example:
SET x="" F S x=$O(^%x(x)) Q:x="" X x
This $ORDER() loop XECUTEs code out of the first level of the global
array ^%x. Note that, in most cases, having the code in a GT.M source
file, for example TMPX.m, and using a DO ^TMPX improves efficiency.
1 ZALLOCATE
ZAllocate
The ZALLOCATE command reserves the specified name without releasing
previously reserved names. Other GT.M processes cannot reserve the
ZALLOCATEd name with a ZALLOCATE or LOCK command.
The ZALLOCATE command provides compatibility with some other GT.M
implementations. The M Development Committee chose to add the + and -
delimiters to the LOCK command (incremental locking) rather than adopt
the ZALLOCATE and ZDEALLOCATE approach. Therefore, when a design
requires an incremental lock mechanism, LOCK +/- has the advantage over
ZALLOCATE / ZDEALLOCATE of being part of the M standard. LOCK +/- also
has the advantage of working symmetrically when routines using LOCKs
are nested. That is, a ZALLOCATE command issued by a process for a
named resource already ZALLOCATEd by that process results in no change
of state. This means that routines that do ZALLOCATE followed by a
ZDEALLOCATE on a named resource that is already ZALLOCATEd by the same
process (at routine entry time), will end up ZDEALLOCATEing the named
resource (which might not be desired). On the other hand, a LOCK +
command issued by a process for a named resource already LOCKed by that
process causes the LEVEL of the LOCK to be incremented (as seen in a
ZSHOW "L" output). Every LOCK - command on that named resource causes
the LEVEL to be decremented. When the LEVEL becomes 0, the named
resource is no longer LOCKed.
For more information on troubleshooting LOCKs with the GT.M Lock
Utility (LKE), refer to the appropriate chapter of the GT.M
Administration and Operations Guide.
The format of the ZALLOCATE command is:
ZA[LLOCATE][:tvexpr] [(]nref[,...][)][:intexpr][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The nref argument specifies a name in the format of a GT.M name
with or without subscripts, and with or without a preceding caret
(^).
o Outside of transactions, only one process in an environment can
ZALLOCATE (or LOCK) a particular resource name at any given time.
o Because the data storage in GT.M uses hierarchical sparse arrays
and ZALLOCATE may serve to protect that data from inappropriate
"simultaneous" access by multiple processes, ZALLOCATE treats
resource names in a hierarchical fashion; a ZALLOCATE protects not
only the named resource, but also its ancestors and descendants.
o When one or more nrefs are enclosed in parentheses (), ZALLOCATE
reserves all the enclosed names "simultaneously," that is, it
reserves none of them until all become available.
o The optional numeric expression specifies a time in seconds after
which the command should timeout if unsuccessful; choosing 0
results in a single attempt.
o An indirection operator and an expression atom evaluating to a list
of one or more ZALLOCATE arguments form a legal argument for a
ZALLOCATE.
For an explanation of the LOCK command see the "LOCK" section in the M
LOCK Utility chapter of GT.M Administration and Operations Guide.
If a ZALLOCATE command specifies a timeout, and GT.M acquires ownership
of the named resource before the timeout elapses, ZALLOCATE sets $TEST
to TRUE (1). If GT.M cannot acquire ownership of the named resource
within the specified timeout, ZALLOCATE sets $TEST to FALSE (0). If a
ZALLOCATE command does not specify a timeout, the execution of the
command does not affect $TEST.
When given a list of nrefs, ZALLOCATE tries to reserve each nref from
left to right in the order specified taking into account the timeout
specified for each. If the timeout elapses before reserving an nref,
GT.M terminates the ZALLOCATE command. Any nrefs already acquired as
part of the current ZALLOCATE command stay acquired.
2 Ex_of_ZAllocate
Examples of ZALLOCATE
Examples:
ZALLOCATE A
ZALLOCATE ^A
ZALLOCATE ^A(1)
ZALLOCATE (^B("smith"),^C("jones"))
ZALLOCATE @A
The first command ZALLOCATEs A; the second, ^A; the third, ^A(1) and
the fourth, both ^B("smith") and ^C("jones") simultaneously. The last
command ZALLOCATEs the resources named by the value of the variable A.
Example:
ZALLOCATE A,^B,@C
ZALLOCATE (A,B,C)
If ZALLOCATE arguments are enclosed in parentheses, the command waits
until all names in the argument list become available before reserving
any of the names. For example, in the statement ZA (A,B,C), if the
resource named C is not available, ZALLOCATE waits until C becomes
available before reserving A and B. Using the format illustrated in the
first line above, can cause deadlocks because the resource names are
reserved as they come available.
When a process attempts to ZALLOCATE a name currently ZALLOCATEd or
LOCKed (with the LOCK command) by another process, the ZALLOCATEing
process hangs until the other process releases the name. In the event
that names remain unavailable for significant periods of time, timeouts
allow the process issuing a ZALLOCATE to regain program control.
Example:
ZALLOCATE ^D:5
This example specifies a timeout of five seconds. If GT.M reserves ^D
before the five seconds elapses, ZALLOCATE sets $TEST to TRUE. If GT.M
cannot reserve ^D within the five second timeout, ZALLOCATE sets $TEST
to FALSE.
When you ZALLOCATE a name, no names previously reserved with ZALLOCATE
or the LOCK command are released (similarly, LOCKing a name does not
release names that have been ZALLOCATEd). For example, after
ZALLOCATEing A and LOCKing B, LOCKing B does not release A, and
ZALLOCATEing C does not release A or B.
To release a ZALLOCATEd name, use the ZDEALLOCATE command. The
ZDEALLOCATE command can only release previously ZALLOCATEd (not LOCKed)
names.
Resource name arguments for LOCKs and ZALLOCATEs intersect. That is, if
one process holds a LOCK or ZALLOCATE, another process can neither LOCK
nor ZALLOCATE any name falling in the hierarchy of the resource name
held by the first process. When a process holds a LOCK or ZALLOCATE,
that same process may also LOCK or ZALLOCATE resource names falling in
the hierarchy of the currently held resource name. When a single
process holds both LOCKs and ZALLOCATEs, a LOCK does not release the
ZALLOCATEd resource(s) and a ZDEALLOCATE does not release the LOCKed
resource(s).
Example:
L ^AR(PNT)
.
.
.
ZALLOCATE ^AR(PNT,SUB)
.
.
.
L ^TOT(TDT)
.
.
.
ZDEALLOCATE ^AR(PNT,SUB)
This LOCKs ^AR(PNT), then, after performing some unspecified commands,
it ZALLOCATEs ^AR(PNT,SUB). Because ZALLOCATE does not imply any change
to LOCKs or existing ZALLOCATEd resource names, the LOCK of ^AR(PNT)
remains in effect. Assuming the routine does not modify the variable
PNT, ^AR(PNT,SUB) is already protected by the LOCK. Next, because an
unsigned LOCK releases all resource names currently LOCKed by the
process, the routine releases ^AR(PNT) with the LOCK of ^TOT(TDT). This
leaves the ZALLOCATE of ^AR(PNT,SUB). The name ^AR and all its
subscripts except for those that begin with ^AR(PNT,SUB) are now
available for LOCKing by other processes. Finally the routine releases
^AR(PNT,SUB) with a ZDEALLOCATE command. The ZDEALLOCATE does not
affect the LOCK on ^TOT(TDT). Note that this example was constructed to
illustrate the interaction between LOCK, ZALLOCATE and ZDEALLOCATE, and
not to illustrate sound programming practice.
1 ZBREAK
ZBreak
The ZBREAK command sets or clears routine breakpoints during debugging.
The format of the ZBREAK command is:
ZB[REAK][:tvexpr] [-]entryref[:[expr][:intexpr]]
[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required entryref specifies a location within a routine at
which to set or remove a breakpoint.
o The optional minus sign (-) specifies that ZBREAK remove the
breakpoint; -* means remove all breakpoints.
o The optional expression specifies a fragment of GT.M code to XECUTE
when GT.M execution encounters the breakpoint; if the ZBREAK
argument does not specify an action, the default action is "BREAK".
o The optional integer expression immediately following the
expression specifies a count of process transits through the
breakpoint before the breakpoint action takes effect; once GT.M
exhausts the count and the action takes effect, the action occurs
every time the process encounters the breakpoint. If the action
expression is omitted, the optional integer expression must be
separated from the entryref by two adjacent colons (::).
o An indirection operator and an expression atom evaluating to a list
of one or more ZBREAK arguments form a legal argument for a ZBREAK.
When GT.M encounters the entryref, GT.M suspends execution of the
routine code and XECUTEs the breakpoint action before executing any of
the commands on the line.
When the optional integer expression is used, GT.M activates the
breakpoint on the intexpr-th time the process encounters the breakpoint
during routine execution. Once GT.M activates the breakpoint, that
breakpoint remains active for the process until explicitly replaced or
removed, or until the process terminates.
2 Ex_of_ZBreak
Examples of ZBREAK
Example:
GTM>ZPRINT ^ZBTEST
ZBTEST;
DO SUB
QUIT
SUB WRITE !,"This is ZBTEST"
QUIT
GTM>ZBREAK SUB^ZBTEST
GTM>DO ^ZBTEST
%GTM-I-BREAKZBA, Break instruction encountered
during ZBREAK action
At M source location SUB^ZBTEST
GTM>
ZSHOW "B"
SUB^ZBTEST
This inserts a ZBREAK with a default action at SUB^ZBTEST. After GT.M
encounters the BREAK, the ZSHOW "B" displays this as the only ZBREAK in
the image.
Example:
GTM>ZBREAK -*
GTM>ZGOTO
GTM>ZBREAK SUB^ZBTEST:"W !,""Trace"""
GTM>DO ^ZBTEST
Trace
This is ZBTEST
GTM>
This removes all existing ZBREAKs with a ZBREAK -*. Note that it is not
necessary to remove ZBREAKs before modifying them. It also clears the
process invocation stack with an argumentless ZGOTO. Then it uses a
ZBREAK to insert a trace-point. Every time GT.M executes the line to
where ZBREAK has established a trace-point, it performs the specified
action without entering Direct Mode.
Example:
ZBREAK PRINT^TIME::5
This BREAKs execution at line PRINT in routine just before the fifth
time the line is executed.
Example:
ZBREAK PRINT^TIME:"WRITE AVE BREAK":3
This inserts a ZBREAK action of WRITE AVE and BREAK before the third
execution of PRINT^TIME.
1 ZCOMPILE
ZCOMpile
The ZCOMPILE command invokes the GT.M compiler from within the GT.M
run-time environment.
Within GT.M itself, ZCOMPILE provides the functionality of the mumps
command, except for mumps -direct.
The format of the ZCOMPILE command is:
ZCOM[PILE][:tvexpr] expr[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The expression argument specifies one or more filenames, which must
include the .m extension. Wildcards are acceptable in the filename
specification. The filename specification can be optionally
prefixed by qualifiers valid for a mumps command.
The $ZCSTATUS intrinsic special variable holds the value of the status
code for the compilation performed by a ZCOMPILE command.
2 Ex_of_ZCOMpile
Examples of ZCOMPILE
ZCOMPILE "EXAMPLE.m"
This compiles EXAMPLE.m in the current working directory.
Example:
ZCOMPILE "-list A*.m"
This compiles all files starting with a [capital] A and an extension of
.m in the current working directory.
1 ZCONTINUE
ZContinue
The ZCONTINUE command continues routine execution after a BREAK command
or a <CTRL-C>.
The format of the ZCONTINUE command is:
ZC[ONTINUE][:tvexpr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o Because ZCONTINUE changes the flow of execution away from control
of the principal device back to the current routine, it is usually
the final command on a line; however, if it is not, because the
ZCONTINUE has no argument, at least two (2) spaces must follow the
command to separate it from the next command on the line.
o If the process is not in Direct Mode, ZCONTINUE has no effect.
1 ZDEALLOCATE
ZDeallocate
The ZDEALLOCATE command releases a specified resource name or names
previously reserved by the ZALLOCATE command. The ZDEALLOCATE command
releases only the specified name(s) without releasing other names
previously reserved with the ZALLOCATE or LOCK command.
The ZDEALLOCATE command provides compatibility with some other GT.M
implementations. The M Development Committee choose to add the + and -
delimiters to the LOCK command rather than adopt the ZALLOCATE and
ZDEALLOCATE approach. Therefore, when a design requires an incremental
lock mechanism, LOCK +/- has the advantage of being part of the M
standard. LOCK +/- also has the advantage of working symmetrically when
routines using LOCKs are nested.
The format of the ZDEALLOCATE command is:
ZD[EALLOCATE][:tvexpr] [nref[,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command
o The nref argument specifies a name in the format of a GT.M name
with or without subscripts and with or without a leading caret (^).
o A ZDEALLOCATE with no argument releases all names currently
reserved with ZALLOCATE by the process; in this case, at least two
(2) spaces must follow the ZDEALLOCATE to separate it from the next
command on the line.
o ZDEALLOCATEing a named resource that is not currently owned by the
process has no effect.
o An indirection operator and an expression atom evaluating to a list
of one or more ZDEALLOCATE arguments form a legal argument for a
ZDEALLOCATE.
1 ZEDIT
ZEDit
The ZEDIT command invokes the editor specified by the EDITOR
environment variable for GT.M and opens the specified file for editing.
If the EDITOR environment variable is undefined, ZEDIT tries to invoke
the UNIX vi editor.
By default, ZEDIT puts a new file into the first source directory in
$ZROUTINES. Previously, it used the current working directory. The old
behavior can be obtained by specifying the current working directory
explicitly in the argument to the ZEDIT command:
o ZEDIT "./file"
The format of the ZEDIT command is:
ZED[IT][:tvexpr] [expr[,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional expression(s) specifies the name of a file to edit;
note the argument is an expression rather than a routinename; ZEDIT
rejects arguments with a file extension of .o as illegal. A valid
GT.M file name with no extension will be given an extension of .m;
therefore it is not possible, through ZEDIT, to edit a file with a
valid GT.M filename and no extension.
o If ZEDIT has an argument, it not only invokes the editor, but also
sets $ZSOURCE=expr.
o If ZEDIT has no argument or expr="", the command acts as a ZEDIT
$ZSOURCE; at least two (2) spaces must follow a ZEDIT command with
no argument to separate it from the next command on the line.
o GT.M stores source code in files with standard operating system
format; generally the file name is the same as the GT.M routinename
with a default type of .m.
o An indirection operator and an expression atom evaluating to a list
of one or more ZEDIT arguments form a legal argument for a ZEDIT
If the expression includes a directory, ZEDIT searches only that
directory. If $ZROUTINES is not null, a ZEDIT command that does not
specify a directory uses $ZROUTINES to locate files. If $ZROUTINES is
null, ZEDIT edits a new file in the first source directory specified in
$ZROUTINES.
When the argument to a ZEDIT includes a file or path name, $ZSOURCE
maintains that as a default for ZEDIT and ZLINK.
2 Ex_of_ZEDit
Examples of ZEDIT
Example:
GTM>ZEDIT "BAL"
This invokes the editor for a file with a name of BAL and an extension
of .m. Notice that BAL is a string literal.
Example:
GTM>SET prog="BAL"
GTM>ZEDIT prog
This is similar to the first example except that it uses a variable
argument rather than a string literal.
Example:
GTM>zedit ".login"
This invokes the editor for a file with the name .login. Notice that in
this case the file is not a GT.M file, since .login starts with a
period, and therefore, cannot be a GT.M file.
1 ZGOTO
ZGoto
The ZGOTO command transfers control to various levels in the GT.M
invocation stack. It also can transfer control from one part of the
routine to another or from one routine to another using the specified
entryref.
The format of the ZGOTO command is:
ZG[OTO][:tvexpr] [[intexpr][:entryref
[:tvexpr]],...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional integer expression specifies the stack frame nesting
level reached by performing the ZGOTO.
o A ZGOTO with no argument returns control to the next command at the
bottom of the stack (level 1); in this case, at least two (2)
spaces must follow the command to separate it from the next command
on the line.
o The optional entryref specifies a location to which ZGOTO transfers
control.
o If ZGOTO specifies no entryref, it returns control to the next
command at the level specified by the integer expression.
o The optional truth-valued expression immediately following the
entryref specifies the argument postconditional and controls
whether GT.M uses the argument.
o If the ZGOTO includes the level and the argument postconditional
but not the entryref, two colons (::) separate the integer
expression from the truth-valued expression.
o An indirection operator and an expression atom evaluating to a list
of one or more ZGOTO arguments form a legal argument for a ZGOTO.
A ZGOTO command with an entryref performs a similar function to the
GOTO command, with the additional capability of reducing the GT.M stack
level. In a single operation, ZGOTO executes ($ZLEVEL - intexpr)
implicit QUITs and a GOTO operation, transferring control to the named
entryref.
The ZGOTO command leaves the invocation stack at the level specified by
the integer expression. GT.M implicitly terminates any intervening FOR
loops and unstacks variables stacked with NEW commands as appropriate.
Using ZGOTO results in an exit from the current GT.M invocation. ZGOTO
resembles HALT (and not QUIT) in that it causes an exit regardless of
the number of active levels in the current invocation. ZGOTO resembles
QUIT (and not HALT) in that it destroys the GT.M context and terminates
the process only if the current GT.M invocation is at the base of the
process. Understanding the difference between ZGOTO and HALT has an
impact only in an environment where GT.M is invoked recursively from
other languages.
ZGOTO $ZLEVEL:LABEL^ROUTINE produces identical results to GOTO
LABEL^ROUTINE. ZGOTO $ZLEVEL-1 responds like a QUIT (followed by
ZCONTINUE, if in Direct Mode). If the integer expression evaluates to a
value greater than the current value of $ZLEVEL or less than zero (0),
GT.M issues a run-time error.
If ZGOTO has no entryref, it performs some number of implicit QUITs and
transfers control to the next command at the specified level. If ZGOTO
has no argument, it behaves like ZGOTO 1, which resumes operation of
the lowest level GT.M routine as displayed by ZSHOW "S". In the image
invoked by $gtm_dist mumps -direct, a ZGOTO without arguments returns
the process to Direct Mode.
ZGOTO provides a useful debugging tool in Direct Mode. However, because
ZGOTO is not conducive to structured coding, it is best to restrict its
use in production programs to error handling.For more information on
error handling, refer to the "Error Processing" chapter in GT.M
Programmer's Guide.
2 Ex_of_ZGOTO
Examples of ZGOTO
Example:
GTM>ZGOTO
GTM>ZSHOW
+1^GTM$DMOD (Direct mode)
GTM>
This uses ZGOTO to clear all levels of the GT.M invocation stack. ZSHOW
with no arguments displays the stack.
Example:
SET $ZTRAP="ZGOTO "_$ZLEVEL_":^ERROR"
This SETs $ZTRAP to contain a ZGOTO, so if an error causes GT.M to
XECUTE $ZTRAP, the routine ERROR executes at the same level as the SET
command shown in the example.
1 ZHELP
ZHelp
The ZHELP command provides access to help information from the GTM help
library or from any help library specified in the command argument.
The format of the ZHELP command is:
ZH[ELP][:tvexpr] [expr1[:expr2],...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional first expression specifies the help topic.
o If ZHELP has no argument or expr1="", ZHELP invokes base level
help; at least two (2) spaces must follow a ZHELP command with no
argument to separate it from the next command on the line.
o The optional second expression specifies the name of a Global
Directory containing ^HELP.
o If ZHELP does not specify the second expression, the name of the
Global Directory defaults to $gtm_dist/gtmhelp.gld.
o An indirection operator and an expression atom evaluating to a list
of one or more ZHELP arguments form a legal argument for a ZHELP
2 Ex_of_ZHelp
Examples of ZHELP
Example:
GTM>zhelp "func $data"
This lists the help for function $DATA, which is a subtopic of
functions topic.
Example:
GTM>zhelp
This uses ZHELP to list all the keywords in the help library.
Example:
GTM>zhelp "ZSHOW"
This lists the help for command ZSHOW.
1 ZLINK
ZLink
If the current process does not contain a copy of a routine, the ZLINK
command adds an executable GT.M routine to the current process. If the
current process contains a copy of a routine and the routine is not
active, the ZLINK command replaces the current routine process with a
"new" version. If necessary, the ZLINK command compiles the routine
prior to integrating it with the process.
The format of the ZLINK command is:
ZL[INK][:tvexpr] [expr1[:expr2][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional first expression specifies the pathname of a routine
to ZLINK; if ZLINK has an argument, it not only adds the routine to
the image, but also sets $ZSOURCE=expr.
o If ZLINK has no argument, or expr="", it uses value of $ZSOURCE as
the routine specification filename; at least two (2) spaces must
follow a ZLINK command with no argument to separate it from the
next command on the line.
o The optional second expression specifies a string holding MUMPS
command qualifiers delimited by a dash (-); the qualifiers control
compile options when the current ZLINK requires a compile; if ZLINK
omits the second expression, the command uses the $ZCOMPILE
intrinsic special variable to determine the compile qualifiers.
o An indirection operator and an expression atom evaluating to a list
of one or more ZLINK arguments form a legal argument for a ZLINK.
ZLINK cannot change a routine that GT.M is currently executing. An
attempt to ZLINK an active routine results in a run-time error because
changing a routine in progress could have unpredictable results. Before
ZLINKing the routine, use the ZSHOW command to display the currently
active routines, then remove it from the GT.M stack using ZGOTO, or the
appropriate number of QUITs.
When the ZLINK command specifies a file, GT.M sets $ZSOURCE to that
filename. By default, ZLINK and ZEDIT use $ZSOURCE for a filename when
they have a missing or null argument. A subsequent ZLINK without an
argument is equivalent to ZLINK $ZSOURCE.
In order to ensure compatibility with GT.M versions that do not
permit the percent sign (%) in a file name, use an underscore (_)
in place of the percent in the ZLINK file name for routines
beginning with a percent sign.
If the expression includes an explicit directory, ZLINK searches only
that directory. Otherwise, if $ZROUTINES is not null, a ZLINK command
uses $ZROUTINES to locate files. If $ZROUTINES is null, ZLINK uses the
current directory.
If the filename contains an explicit file extension, ZLINK processes
the file according to the extension, object (.o) or source (usually
.m). If the file name does not specify a file extension, ZLINK attempts
to find and match both the object and source for a routine.
2 ZLINK_Compilation
ZLINK Compilation
If ZLINK compiles a routine and the -OBJECT= qualifier does not
redirect the output, it places the resulting object file in the
directory indicated by the search criteria. ZLINK incorporates the new
object file into the image, regardless of its directory placement.
If the command does not specify compile qualifiers (with expr2) and
$ZCOMPILE is null, GT.M uses the default M command qualifiers, -ignore,
-labels=lower, -nolist, and -object. For more information on $ZCOMPILE,
refer to the appropriate section in the "Intrinsic Special Variables"
chapter in this manual.
For information on producing object files, but not adding them to the
current image, refer to ZCOMPILE.
2 Ex_of_ZLink
Examples of ZLINK
Example:
GTM>ZLINK "test"
If ZLINK finds test.m or test.o, it adds the routine test to the
current image. If ZLINK does not find test.o, or finds that test.o is
older than test.m, GT.M compiles test.m to produce a new test.o, and
adds the contents of the new object file to the image.
Example:
GTM>
zlink "test.m":"-noobject -list"
This compiles the routine "test" and produces a listing but no object
file. Because the example produces no object file, it does not change
the current image.
2 Auto_ZLink
Auto-ZLINK
If a GT.M routine refers to a routine that is not linked to the GT.M
image, GT.M automatically attempts to ZLINK that routine. An auto-ZLINK
is functionally equivalent to an explicit ZLINK of a routine without a
specified directory or file extension.
The following GT.M commands and functions can initiate auto-ZLINKing:
DO
GOTO
ZBREAK
ZGOTO
ZPRINT
$TEXT()
GT.M auto-ZLINKs the routine if the following conditions are met:
o ZLINK can locate and process the routine file, as indicated in the
previous ZLINK Operation Summary table
o The name of the routine is the same as the name of the source file;
the only exception is in cases where GT.M converts a leading
percent sign (%) in a file name to an underscore (_)
2 ZL_AutoZL_and_Rtn_Nam
ZLINK, Auto-ZLINK and Routine Names
In GT.M, the name of the source file determines the name of the GT.M
routine. The file name of the object file is not required to match the
name of the routine. Linking the object file makes the internal routine
name (derived from the source file) known to GT.M. This can lead to
potential confusion, however, since both ZLINK and auto-ZLINK use the
name of the object file to find the routine. When the object file name
differs from the name of the routine, auto-ZLINK generates a run-time
error.
1 ZKILL
ZKill
The ZKILL command KILLs the data value for a variable name without
affecting the nodes descended from that node.
The format of the ZKILL command is:
ZK[ILL][:tvexpr] glvn
The functionality of ZKILL is identical to ZWITHDRAW. For a
comprehensive description of the format and usage, refer to the entry
for ZWITHDRAW.
1 ZMESSAGE
ZMessage
The ZMESSAGE command signals a specified condition.
The format of the ZMESSAGE command is:
ZM[ESSAGE][:tvexpr] intexpr
[:expr...][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required integer expression specifies the exception condition
to signal.
o The additional expressions specify one or more arguments passed to
the GT.M message formatter to substitute as parameters to the
message text. For example, if the message associated with the
condition contains a corresponding !AD substitution directive,
passing a string as an additional expression causes the string to
be inserted in the message text instead of the !AD. $ZMESSAGE
function returns the message text with the substitution directives
for a given message number.
2 Ex_of_ZMessage
Examples of ZMESSAGE
All of the following examples issue ZMESSAGE from Direct Mode where
exception conditions do not invoke $ZTRAP. ZMESSAGE allows you to feed
an undefined message number back into GT.M to try and determine the
message and/or mnemonic associated with it.
Example:
GTM>ZMESSAGE 2
%SYSTEM-E-ENO2, No such file or directory
This ZMESSAGE does not specify substitution text and the message does
not include any substitution directives.
Example:
GTM>ZMESSAGE 150372994
%GTM-E-GVUNDEF, Global Variable undefined:
The message specified by this ZMESSAGE command includes a substitution
directive but the command does not supply any text.
Example:
GTM>ZMESSAGE 150373850:"x"
%GTM-E-GVUNDEF, Undefined local variable: x
This ZMESSAGE command supplies the substitution text for the message.
GT.M treats odd-numbered conditions as "successful." GT.M handles
successful conditions by displaying the associated message and
continuing execution. GT.M treats even-numbered conditions as failures.
GT.M handles failure conditions by storing the error information in
$ZSTATUS and XECUTEing $ZTRAP or by terminating if $ZTRAP="". In Direct
Mode, GT.M only reports failure conditions to the principal device and
does not XECUTE $ZTRAP or set $ZSTATUS. For more information on error
handling, refer to the "Error Processing" chapter in GT.M Programmer's
Guide.
1 ZPRINT
ZPrint
The ZPRINT command displays source code lines selected by its argument.
The format of the ZPRINT command is:
ZP[RINT][:tvexpr][entryref
[:label[+intexpr]][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o A ZPRINT with no argument prints the entire current routine, which
is the routine closest to the top of an invocation stack, as
displayed by a ZSHOW "S"; in this case, at least two (2) spaces
must follow the command to separate it from the next command on the
line.
o The optional entryref specifies the location in a routine at which
to start printing; the entryref can include either a routinename or
a label plus a routinename in the format LABEL^ROUTINENAME or
LABEL+OFFSET^ROUTINENAME; if the entryref does not contain a
routinename, ZPRINT defaults to the current routine.
o The optional label following the entryref identifies a location at
which to stop printing; the optional integer expression specifies
an offset from the label; the label and offset together are
referred to as a lineref and this lineref identifies the last line
to print; if the offset is specified without the label, the offset
in the optional lineref is always counted from the beginning of the
routine, even when the entryref specifies a label.
o If the ZPRINT argument includes the colon (:) delimiter, then the
argument must also include at least one component of the optional
lineref.
o If the ZPRINT argument contains only the entryref, with no
components of the optional lineref and the entryref contains a
label or offset, ZPRINT displays only the one line that occurs at
that entryref.
o If the entryref contains only a routinename, ZPRINT displays the
entire routine.
o If the entryref contains only a routinename and the argument
includes the optional lineref, ZPRINT starts the display at the
beginning of the routine.
o If the optional lineref specifies a line prior to the lineref
specified within the entryref, ZPRINT does not display any lines.
o If the offset in the optional lineref specifies a line beyond the
end of the routine, ZPRINT displays the remainder of the routine.
o If ZPRINT cannot locate the routine or if either of the labels does
not appear in the routine, ZPRINT issues an error.
o An indirection operator and an expression atom evaluating to a list
of one or more ZPRINT arguments form a legal argument for a ZPRINT.
Note that the routinename may only appear before the colon (:)
delimiter. The integer expression offsets may be positive or negative,
but they must always be delimited by a plus sign (+).
2 Ex_of_ZPrint
Examples of ZPRINT
Example:
GTM>ZPRINT X^RTN
This example displays the line beginning with the label X in the
routine RTN.
Example:
GTM>ZPRINT X^RTN:X+5
GTM>ZPRINT X+-5^RTN:X
GTM>ZPRINT X^RTN:X+-5^RTN
The first line displays the line beginning with the label X and the
next 5 lines in routine RTN. The second line displays the 5 lines
preceding label X in the same routine and the line beginning with label
X. The third line generates a run-time error because the routine name
must appear only before the colon in the argument.
1 ZSHOW
ZSHow
The ZSHOW command displays information about the current GT.M
environment.
The format of the ZSHOW command is:
ZSH[OW][:tvexpr][expr[:glvn][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional expression specifies one or more codes determining the
nature of the information displayed.
o A ZSHOW with no argument defaults to ZSHOW "S"; in this case, at
least two (2) spaces must follow the ZSHOW to separate it from the
next command on the line.
o The optional global or local variable name specifies the
destination for the ZSHOW output; if the ZSHOW argument does not
contain a global or local variable name, ZSHOW directs its display
to the current device ($IO).
o An indirection operator and an expression atom evaluating to a list
of one or more ZSHOW arguments form a legal argument for a ZSHOW.
2 ZSH_Info_Codes
ZSHOW Information Codes
A ZSHOW argument is an expression containing codes selecting one or
more types of information.
B displays active ZBREAK breakpoints
C displays available external call table entry names
D displays device information
I displays the current values of all intrinsic special variables
L displays GT.M LOCKs and ZALLOCATEs held by the process
S displays the GT.M invocation stack
V displays local variables
* displays all possible types of ZSHOW information
Codes may be upper- or lower-case. Invalid codes produce a run-time
error. Multiple occurrences of the same code in one ZSHOW argument only
produce one output instance of the corresponding information. The order
of the first appearance of the codes in the argument determines the
order of the corresponding output instances.
If you are using a local variable destination and place another
code ahead of "V", the effect is to have the results of the earlier
code also appear in the results of the "V" code.
If the wildcard (*) occurs in the list, ZSHOW uses the default order:
o intrinsic special variables
o local variables
o ZBREAK information
o device information
o LOCK and ZALLOCATE information
o the GT.M stack
2 Ex_of_ZSHow
Examples of ZSHOW
Example:
GTM>ZSHOW "db"
This command displays all devices with deviceparameters reflecting
their current characteristics followed by any current ZBREAK locations
with their corresponding actions.
Example:
GTM>ZSHOW "dbd"
This command displays the same output as the previous example.
Example:
GTM>ZSHOW "ax"
This command generates a run-time error.
Example:
LAB1 DO LAB2
QUIT
LAB2 DO LAB3
QUIT
LAB3 ZSHOW
QUIT
Produces the results:
LAB3^RTN
LAB2^RTN
LAB1^RTN
2 ZSH_Destination_Vars
ZSHOW Destination Variables
ZSHOW may specify an unsubscripted or subscripted global or local
variable name (glvn) into which ZSHOW places its output. If the
argument does not include a global or local variable name, ZSHOW
directs its output to the current device.
When ZSHOW directs its output to a variable, it adds two levels of
descendants to that variable. The first level subscript contains a
one-character string from the set of upper-case ZSHOW action codes,
identifying the type of information. ZSHOW implicitly KILLs all
descendants of the first level nodes. ZSHOW stores information elements
at the second level using ascending integers, starting at 1.
When a ZSHOW "V" directs its output to a local variable (lvn), the
result does not contain a copy of the descendants of the resulting "V"
node.
Example:
GTM>KILL SET b(1,"two")="test" ZSHOW "v":a ZWR
a("V",1)="b(1,""two"")=""test"""
b(1,"two")="test"
GTM>
This ZSHOW stores all local variables in the local variable a. Note
that ZSHOW does not replicate a("V") and a("V",1).
Example:
GTM>KILL SET a(1,"D",3,5)="stuff",a(1,"X",2)="",a(1)=1
GTM>zsh "d":a(1)
GTM>zwrite
a(1)=1
a(1,"D",1)="/dev/ttyp8 OPEN TERMINAL NOPAST NESCA
NOREADS TYPE WIDTH=80 LENG=52"
a(1,"X",2)=""
GTM>
This ZSHOW stores the current open device information under a(1).
Notice how the ZSHOW deletes a(1,"D",3,5).
Example:
GTM>KILL ^ZSHOW
GTM>ZB -*,lab^rout ZSH "B":^ZSHOW
GTM>ZWRITE ^ZSHOW
^ZSHOW("B",1)="LAB^ROUT"
GTM>
This ZSHOW stores the current ZBREAK information under the global
variable ^ZSHOW.
2 Use_of_ZSHow
Use of ZSHOW
Use ZSHOW as
o a debugging tool to display information on the environment.
o an error-handling tool to capture context information after an
unpredictable error with output directed to a sequential file or a
global.
o part of a context-switching mechanism in a server program that must
manage multiple contexts.
o a development tool to determine the external call table entries
available from the current process.
To prevent confusing data interactions, avoid directing ZSHOW output
into variables holding other kinds of information and directing ZSHOW
"V" output into local variables. For a comparison of ZSHOW "V" and
ZWRITE, refer to the ZWRITE section in the "Commands" chapter in GT.M
Programmer's Guide.
1 ZSTEP
ZSTep
The ZSTEP command provides the ability to control GT.M execution. When
a ZSTEP is issued from Direct Mode, execution continues to the
beginning of the next target line and then GT.M XECUTEs the ZSTEP
action. The keyword in the optional ZSTEP argument determines the class
of eligible target lines.
The format of the ZSTEP command is:
ZST[EP][:tvexpr] [keyword[:expr]][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional keyword specifies the nature of the step; the keywords
are INTO, OVER, and OUTOF.
o A ZSTEP with no argument performs the default action OVER; in this
case, at least two (2) spaces must follow the ZSTEP to separate it
from the next command on the line, which will be ignored.
o The optional expression specifies GT.M code to XECUTE when the
ZSTEP arrives at its destination.
o If the ZSTEP argument does not contain an expression argument,
ZSTEP defaults the action to the value of $ZSTEP, which defaults to
"BREAK."
The ZSTEP argument keywords are not expressions and ZSTEP does not
accept argument indirection.
In Direct Mode, ZSTEP performs an implicit ZCONTINUE and therefore GT.M
ignores all commands on the Direct Mode command line after the ZSTEP.
The keyword arguments define the class of lines where ZSTEP next pauses
execution to XECUTE the ZSTEP action. When a ZSTEP command has multiple
arguments, it ignores all arguments except the last.
2 ZSTEP_Into
ZSTEP Into
ZSTEP INTO pauses at the beginning of the next line, regardless of
transfers of control. When the ZSTEPed line invokes another routine or
a subroutine in the current routine, ZSTEP INTO pauses at the first
line of code associated with the new GT.M stack level.
2 ZSTEP_OUtof
ZSTEP OUtof
ZSTEP OUTOF pauses at the beginning of the next line executed after an
explicit or implicit QUIT from the current GT.M invocation stack level.
A ZSTEP OUTOF does not pause at lines associated with the current GT.M
stack level or with levels invoked from the current level.
2 ZSTEP_OVer
ZSTEP OVer
ZSTEP OVER pauses at the beginning of the next line in the code
associated with either the current GT.M stack level or a previous GT.M
stack level if the ZSTEPed line contains an explicit or implicit QUIT
from the current level. A ZSTEP OVER does not pause at lines invoked
from the current line by DOs, XECUTEs or extrinsics.
2 ZSTEP_Actions
ZSTEP Actions
The optional action parameter of a ZSTEP must contain an expression
evaluating to valid GT.M code. By default, ZSTEP uses the value of
$ZSTEP, which defaults to "B" ("BREAK"), and enters Direct Mode. When a
ZSTEP command specifies an action, the process does not enter Direct
Mode unless the action explicitly includes a BREAK command.
2 ZSTEP_Interact
ZSTEP Interactions
ZSTEP currently interacts with certain other elements in the GT.M
environment.
o If a <CTRL-C> or a CTRAP character arrives at certain points in
ZSTEP processing, there is a small chance GT.M may ignore the
<CTRL-C> or CTRAP; in a later release, <CTRL-C> and CTRAPs will
always have priority over ZSTEP.
o If GT.CM reports an asynchronous network error, a ZSTEP may cause
the network error to go unreported; the chance of such an
occurrence is small and the chance the error would subsequently be
reported is high; in a later release, network errors will always be
given priority over ZSTEP.
2 Use_of_ZSTEP
Use of ZSTEP
Use ZSTEP to incrementally execute a routine or series of routines.
Execute any GT.M command from Direct Mode at any ZSTEP pause. To resume
normal execution, use ZCONTINUE.
Note that ZSTEP arguments are keywords rather than expressions. They do
not allow indirection, and argument lists have no utility.
ZSTEP actions that include commands followed by a BREAK perform some
action before entering Direct Mode. ZSTEP actions that do not include a
BREAK perform the command action and continue execution. Use ZSTEP
actions that issue conditional BREAKs and subsequent ZSTEPs to do such
things as test for changes in the value of a variable.
2 Ex_of_ZSTEP
Examples of ZSTEP
Example:
GTM>ZSTEP INTO:"W ! ZP @
$ZPOS W !"
This ZSTEP resumes execution of the current routine. At the beginning
of the next line executed, the ZSTEP action ZPRINTs the source code for
that line. Because the specified action does not contain a BREAK
command, execution continues to the next line and all subsequent lines
in the program flow.
Example:
GTM>S curx=$g(x),zact="ZST:curx=$g(x) I:zact B:curx'=$g(x)"
GTM>ZSTEP INTO:zact
This sequence uses ZSTEP to invoke Direct Mode at the beginning of the
first line after the line that alters the value of x.
1 ZSYSTEM
ZSYstem
The ZSYSTEM command creates a child of the current process.
The format of the ZSYSTEM command is:
ZSY[STEM][:tvexpr] [expr[:tvexpr][,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional expression specifies the command passed to the shell;
after processing the command, the shell returns control to GT.M.
o If ZSYSTEM has no argument or expr="", the shell prompts for input
until provided with an exit command; at least two (2) spaces must
follow a ZSYSTEM command with no argument to separate it from the
next command on the line.
o The optional truth-valued expression following the argument
expression specifies the argument postconditional and controls
whether ZSYSTEM processes that argument.
o An indirection operator and an expression atom evaluating to a list
of one or more ZSYSTEM arguments form a legal argument for a
ZSYSTEM.
The ZSYSTEM command creates a new process and passes its argument to
the shell for execution. The new process executes in the same directory
as the initiating process using the shell specified by the SHELL
environment variable, or if that is not defined, the Bourne shell. The
new process has the same operating system environment, such as
environment variables and input/output devices, as the initiating
process. The initiating process pauses until the new process completes
before continuing execution. The return status of the forked process is
reflected in $ZSYSTEM.
If a ZSYSTEM command has multiple arguments, it starts a new process
for each argument, one at a time. ZSYSTEM waits for one process to
complete before starting the next one.
A ZSYSTEM with a null argument creates a shell with the standard input
and output devices. When the shell exits, control is returned to GT.M.
For an interactive process, both stdin and stdout are generally the
user's terminal. A ZSYSTEM with no arguments is equivalent to a ZSYSTEM
with a single null string argument.
If a command postconditional is false, GT.M does not process the
ZSYSTEM command. If an argument postconditional is false, GT.M does not
process that argument.
Issuing a ZSYSTEM command inside a transaction destroys the Isolation
of that transaction. Because of the way that GT.M implements
transaction processing, a ZSYSTEM within a transaction may suffer an
indefinite number of restarts ("live lock").
2 Ex_of_ZSYSTEM
Examples of ZSYstem
Example:
GTM>ZSYSTEM "ls *.m"
This uses ZSYSTEM to fork a process that then performs the ls command
with *.m as an argument to ls. Once the command completes, the forked
process terminates.
Example:
GTM>ZSYSTEM
$
This ZSYSTEM has no argument so the forked process prompts for input.
1 ZTCOMMIT
ZTCommit
The ZTCOMMIT command marks the end of a logical transaction within a
GT.M program. ZTCOMMIT used with ZTSTART "fences" transactions (that
is, marks the end and beginning). Fencing transactions allows the MUPIP
JOURNAL facility to prevent incomplete application transactions
consisting of multiple global updates from affecting the database
during a database recovery.
The format of the ZTCOMMIT command is:
ZTC[OMMIT][:tvexpr] [intexpr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional integer expression specifies the number of currently
open ZTSTARTs for the ZTCOMMIT to close.
o A ZTCOMMIT with no argument closes one ZTSTART; in this case, at
least two (2) spaces must follow the command to separate it from
the next command on the line; with an argument of 0, ZTCOMMIT
closes all open ZTSTARTs.
o An indirection operator and an expression atom evaluating to a list
of one or more ZTCOMMIT arguments form a legal argument for a
ZTCOMMIT.
When an application requires sub-transactions, it may nest ZTSTARTs and
ZTCOMMITs to a maximum depth of 255. However, a ZTCOMMIT must "close"
the outer-most ZTSTART before journaling accepts any part of the
"transaction" as complete.
2 Ex_of_ZTCommit
Examples of ZTCOMMIT
Example:
GTM>ZTCOMMIT 0
This ZTCOMMIT issued from Direct Mode would close any open ZTSTARTs.
Example:
1 ZTSTART
ZTStart
The ZTSTART command marks the beginning of a logical transaction within
a GT.M program. ZTSTART and ZTCOMMIT "fence" transactions (that is,
mark the beginning and end). Fenced transactions prevent the MUPIP
JOURNAL facility from recovering incomplete transactions. All ZTSTARTs
must be matched with ZTCOMMITs before the journal processing facility
recognizes the transaction as complete.
The format of the ZTSTART command is:
ZTS[TART][:tvexpr]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o Because ZTSTART has no argument, at least two (2) spaces must
follow the command to separate it from the next command on the
line.
For more information on Journaling and transaction fencing, refer to
the section on ZTCOMMIT and the "GT.M Journaling" chapter in the GT.M
Administration and Operations Guide.
2 Ex_of_ZTStart
Examples of ZTSTART
Example:
LOCK ^P(t)
ZTSTART
SET ^P(t)=prec,^($H)=$G(^P(t,+$H))+1,^(+$H,s)=hrec
ZTCOMMIT
LOCK
This uses a LOCK on ^P(t) to serialize the transaction. The logical
transaction consists of three global sets that are enclosed within a
ZTSTART and a ZTCOMMIT.
Example:
BASE DO WORK
QUIT
GRP LOCK ^FAM(prn)
SET b=^FAM(prn)
ZTSTART
FOR i=1:1:$L(b,"|") D GET,WORK
ZTCOMMIT
LOCK
QUIT
WORK LOCK +^ACT(acct)
ZTSTART
SET ^ACT(acct)=actrec
SET ^ACTX(lname,fname,acct)=""
ZTCOMMIT
LOCK -^ACT(acct)
This has a sub-routine WORK, which BASE invokes directly and GRP
invokes to perform a sub-transaction.
1 ZWITHDRAW
ZWIthdraw
The ZWITHDRAW command KILLs the data value for a variable name without
affecting the nodes descended from that node.
The format of the ZWITHDRAW command is:
ZWI[THDRAW][:tvexpr] glvn
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The global or local variable name identifies the variable for which
ZWITHDRAW removes the data value.
o An indirection operator and an expression atom evaluating to a list
of one or more ZWITHDRAW arguments form a legal argument for a
ZWITHDRAW.
ZWITHDRAW provides a tool to quickly restore a node to a state where it
has descendants and no value-that is, where $DATA for that node will
have a value of 10-for the case where such a state has some control
meaning. GT.M also provides the ZKILL command, with functionality
identical to ZWITHDRAW.
2 Ex_of_ZWIthdraw
Examples of ZWITHDRAW
Example:
KILL A
SET A="A",A(1)=1,A(1,1)=1
WRITE $D(A(1)),!
ZWITHDRAW A(1)
WRITE $D(A(1)),!
ZWRITE A
QUIT
produces the result:
11
10
A="A"
A(1,1)=1
This sets up local variables A and A(1) and A(1,1). It then deletes the
data for A(1) with ZWITHDRAW. The ZWRITE command shows ZWITHDRAW KILLed
A(1) but left A and A(1,1).
1 ZWRITE
ZWRite
The ZWRITE command displays the current value of one or more local or
global variables. ZWRITE formats its output so that each item in the
display forms a valid argument to a SET @ command. This means ZWRITE
encloses string values in quotes and represents non-graphic (control)
characters in $CHAR() syntax.
The format of the ZWRITE command is:
ZWR[ITE][:tvexpr] [zwrglvn[,...]]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The optional global or local variable name specifies the variable
for ZWRITE to display.
o ZWRITE accepts several alternative syntaxes in place of subscripts;
ZWRITE also accepts arguments specifying naked references to
globals. Because ZWRITE is primarily a debugging tool, ZWRITE does
not affect the naked indicator.
o ZWRITE accepts null subscripts in its arguments, when these are
allowed, and reports array nodes that have null subscripts.
o A ZWRITE with no arguments displays all the currently available
local variables; in this case, at least two (2) spaces must follow
the command to separate it from the next command on the line.
o If the global or local variable name is unsubscripted, ZWRITE
displays the unsubscripted variable and all subscripted
descendants.
o If an asterisk (*) appears in the space normally occupied by the
last subscript in a subscripted variable name, ZWRITE displays all
variable nodes descended from the previously specified subscripts.
o ZWRITE accepts GT.M pattern-match syntax in place of both variable
names and subscripts.
o ZWRITE <name>(), where <name> is a local or a global is treated as
a synonym for ZWRITE <name>.
o A colon acts as a range operator for subscript values; ZWRITE
displays all subscripts of the variable starting with the value on
the left side of the colon and ending with the value on the right
side of the colon; if the range delimiter has no left-hand value,
or has the empty string as the left-hand value, the display begins
at the first subscript; if the range delimiter has no right-hand
value or has the empty string as the right-hand value, the display
ends at the last subscript at that level; if the range delimiter
has no values or empty strings on either side, ZWRITE displays all
subscripts at that level; an empty subscript level also displays
all subscripts at that level.
o An indirection operator and an expression atom evaluating to a list
of one or more ZWRITE arguments form a legal argument for a ZWRITE.
o Long ZWRITE format records can be loaded.
2 Ex_of_ZWRite
Examples of ZWRITE
Example:
GTM>ZWRITE ^?1"%"2U(0:":",)
This command displays the descendants of all subscripts between 0 and
":" of all global names starting with a "%" and having two upper case
letters-for example, "%AB".
Example:
GTM>ZWRITE A(,:,3)
This command displays all of the third level nodes with a subscript of
3 for local variable A.
Example:
ZWRITE ?1"A".E(?1"X"3N)
This would display data for any local variables starting with "A",
optionally followed by any characters, and having any subscripts
starting with "X" followed by three numerics.
1 Functions
Functions
M Intrinsic Functions start with a single dollar sign ($) and have one
or more arguments enclosed in parentheses () and separated by commas
(,). These functions provide expression results by performing actions
that are impossible or difficult to perform using M commands.
2 $ASCII()
$ASCII()
The $ASCII function returns the integer ASCII code for a character in a
string.
The format for the $ASCII function is:
$A[SCII](expr[,intexpr])
o The expression acts as the source string from which $ASCII()
extracts the character it decodes.
o The optional integer expression contains the position within the
expression of the character that $ASCII() decodes. If this argument
is missing, $ASCII() returns a result based on the first character
position. $ASCII() starts numbering character positions at one (1),
(i.e., the first character of a string is at position one (1)).
o If the explicit or implicit position is before the beginning or
after the end of the expression, $ASCII() returns a value of
negative one (-1).
$ASCII() provides a means of examining non-graphic characters in a
string. Used with $CHAR(), $ASCII() also provides a means to perform
arithmetic operations on the codes associated with characters.
3 Ex_of_$ASCII()
Examples of $ASCII()
Example:
GTM> FOR i=0:1:3 WRITE !,$A("HI",i)
-1
72
73
-1
GTM>
This loop displays the result of $ASCII() specifying a character
position before, first and second positions, and after the string.
2 $Char()
$CHAR()
The $CHAR function returns a string of one or more characters
corresponding to integer ASCII codes specified in its argument(s).
The format for the $CHAR function is:
$C[HAR](intexpr[,...])
o The integer expression(s) specify the ASCII codes of the
character(s) $CHAR() returns.
The M standard does not restrict the number of arguments to $CHAR().
However, GT.M does limit the number of arguments to a maximum of 254.
$CHAR() provides a means of producing non-graphic characters, as such
characters cannot appear directly within an M string literal. Used with
$ASCII(), $CHAR() can also perform arithmetic operations on the codes
associated with characters.
3 Ex_of_$CHAR()
Examples of $CHAR()
Example:
GTM> WRITE $CHAR(77,85,77,80,83,7)
MUMPS
GTM>
This example uses $CHAR() to WRITE the word MUMPS and signal the
terminal "bell."
Example:
SET nam=$E(nam,1,$L(nam)-1)_$C($A(nam,$L(nam))-1))
This example uses $CHAR() and $ASCII() to set the variable nam to a
value that immediately precedes its previous value in the set of
strings of the same length as nam.
2 $Data()
$Data()
The $DATA function returns an integer code describing the value and
descendent status of a local or global variable.
The format for the $DATA function is:
$D[ATA](glvn)
o The subscripted or unsubscripted global or local variable name
specifies the target node.
o If the variable is undefined, $DATA() returns 0.
o If the variable has a value but no descendants, $DATA() returns 1.
o If the variable has descendants but no value, $DATA() returns 10.
o If the variable has a value and descendants, $DATA() returns 11.
3 Ex_of_$Data()
Examples of $DATA()
Example:
GTM> KILL WRITE $DATA(a)
0
GTM> SET a(1)=1 WRITE $DATA(a(1))
1
GTM> WRITE $DATA(a)
10
GTM> SET a=0 WRITE $DATA(a)
11
GTM>
This uses $DATA to display all possible $DATA() results.
Example:
L ^ACCT(0)
I '$D(^ACCT(0)) S ^ACCT(0)=0
S (ACCT,^ACCT(0))=^ACCT(0)+1
L
This uses $DATA() to determine whether a global node requires
initialization.
Example:
FOR SET cus=$O(^cus(cus)) Q:cus="" I $D(^(cus))>1 D WORK
This uses $DATA() to determine whether a global node has descendants
and requires additional processing.
2 $Extract()
$EXTRACT()
The $EXTRACT function returns a substring of a given string.
The format for the $EXTRACT function is:
$E[XTRACT](expr[,intexpr1[,intexpr2]])
o The expression specifies a string from which $EXTRACT() derives a
substring.
o The first optional integer expression (second argument) specifies
the starting character position in the string expr of the substring
result. If the starting position is beyond the end of the
expression, $EXTRACT() returns the null string. If the starting
position is zero (0) or negative, $EXTRACT() starts at the first
position in the expression; if this argument is omitted, $EXTRACT()
returns the first character of the expression. $EXTRACT() numbers
character positions starting at one (1) (i.e., the first character
of a string is at position one (1)).
o The second optional integer expression (third argument) specifies
the ending character position for the result. If the ending
position is beyond the end of the expression, $EXTRACT() stops with
the last character of the expression. If the ending position
precedes the starting position, $EXTRACT() returns the null string.
If this argument is omitted, $EXTRACT() returns one character at
most.
$EXTRACT() provides a tool for manipulating strings based on character
positions.
A SET command argument can have something that has the format of a
$EXTRACT() on the left-hand side of its equal sign (=). This construct
permits easy maintenance of individual pieces within a string. It can
also be used to right justify a value padded with blank characters. For
more information on SET $EXTRACT(), refer to SET in the "Commands"
chapter.
3 Ex_of_$Extract()
Examples of $EXTRACT()
Example:
GTM> FOR i=0:1:3 WRITE !,$EXTRACT("HI",i),"<"
<
H<
I<
<
GTM>
This loop displays the result of $EXTRACT(), specifying no ending
character position and a beginning character position "before, " first
and second positions, and "after" the string.
Example:
GTM> FOR i=0:1:3 WRITE !,$E("HI",1,i),"<"
<
H<
HI<
HI<
GTM>
This loop displays the result of $EXTRACT() specifying a beginning
character position of 1 and an ending character position "before, "
first and second positions, and "after" the string.
Example:
TRIM(x)
NEW i,j
FOR j=$L(x):-1:0 S nx=$E(x,1,j) Q:$EXTRACT(x,j)'=" "
FOR i=1:1:j S fx=$E(nx,i,$L(x)) Q:$EXTRACT(x,i)'=" "
QUIT fx
GTM>SET str=" MUMPS "
GTM>WRITE $LENGTH(str)
7
GTM>WRITE $LENGTH($$TRIM^trim(str))
5
This extrinsic function uses $EXTRACT() to remove extra leading and
trailing spaces from its argument.
2 $Find()
$FIND()
The $FIND function returns an integer character position that locates
the occurrence of a substring within a string.
The format for the $FIND function is:
$F[IND](expr1,expr2[,intexpr])
o The first expression specifies the string in which $FIND() searches
for the substring.
o The second expression specifies the substring for which $FIND()
searches.
o The optional integer expression identifies the starting position
for the $FIND() search. If this argument is missing, zero (0), or
negative, $FIND() begins its search in the first position of the
string.
o If $FIND() locates the substring, it returns the position after the
last character of the substring. If the end of the substring
coincides with the end of the string (expr1), it returns an integer
equal to the length of the string plus one ($L(expr1)+1).
o If $FIND() does not locate the substring, it returns zero (0).
$FIND() provides a tool to locate characters. The ( [ ) operator and
the two-argument $LENGTH() are other tools that provide related
functionality.
3 Ex_of_$Find()
Examples of $FIND()
Example:
GTM> WRITE $FIND("HIFI","I")
3
GTM>
This example uses $FIND() to WRITE the position of the first occurrence
of the character "I." The return of 3 gives the position after the
"found" substring.
Example:
GTM> WRITE $FIND("HIFI","I",3)
5
GTM>
This example uses $FIND() to WRITE the position of the next occurrence
of the character "I" starting in character position three.
Example:
GTM> SET t=1 FOR SET t=$FIND("BANANA","AN",t) Q:'t W !,t
4
6
GTM>
This example uses a loop with $FIND() to locate all occurrences of "AN"
in "BANANA". The $FIND() returns 4 and 6 giving the positions after the
two occurrences of "AN".
Example:
GTM> SET str="MUMPS databases are hierarchical"
GTM>WRITE $FIND(str," ")
7
GTM>WRITE $FIND(str,"Z")
0
GTM>WRITE $FIND(str,"d",1)
8
GTM>WRITE $FIND(str,"d",10)
0
The above example searches a string for a sub string, and returns an
integer value which corresponds to the next character position after
locating the sub string.
2 $FNumber()
$FNumber()
The $FNUMBER function returns a string containing a formatted number.
The format for the $FNUMBER function is:
$FN[UMBER](numexpr,expr[,intexpr])
o The numeric expression specifies the number that $FNUMBER()
formats.
o The expression (second argument) specifies zero or more single
character format control codes; if the expression contains any
character other than the defined codes, $FNUMBER() generates a
run-time error.
o The optional integer expression (third argument) specifies the
number of digits after the decimal point. If the numeric expression
has more digits than specified by this argument, $FNUMBER() rounds
to obtain the result. If the numeric expression has fewer digits
than specified by this argument, $FNUMBER() zero-fills to obtain
the result.
o When the optional third argument is specified and the first
argument evaluates to a fraction between -1 and 1, $FNUMBER()
returns a number with a leading zero (0) before the decimal point
(.).
$FNUMBER() formats or edits numbers, usually for reporting. For more
information on rounding performed by $FNUMBER(), refer to the section
on $JUSTIFY().
The formatting codes are:
+ Forces a "+" on positive values.
- Suppresses the "-" on negative values.
, Inserts commas every third position to the left of the decimal
within the number.
T Represents the number with a trailing, rather than a leading
sign; positive numbers have a trailing space unless the expression
includes a plus sign (+).
P Represents negative values in parentheses, positive values with a
space on either side; combining with any other code except comma
(,) causes a run-time error.
M accepts both lower-case and upper-case alphabetic codes. The order of
the codes does not affect the result.
3 Ex_of_$FNumber()
Examples of $FNUMBER()
Example:
SET X=-100000,Y=2000
WRITE "SUPPRESS NEGATIVE SIGN:",?35,$FNUMBER(X,"-"),!
WRITE "TRAILING SIGN:",?35,$FNUMBER(X,"T"),!
WRITE "NEGATIVE NUMBERS IN ():",?35,$FNUMBER(X,"P"),!
WRITE "COMMAS IN NUMBER:",?35,$FNUMBER(X,","),!
WRITE "NUMBER WITH FRACTION:",?35,$FNUMBER(X,"",2),!
WRITE "FORCE + SIGN IF POSITIVE:",?35,$FNUMBER(Y,"+"),!
Produces the results:
SUPPRESS NEGATIVE SIGN: 100000
TRAILING SIGN: 100000-
NEGATIVE NUMBERS IN (): (100000)
COMMAS IN NUMBER: -100,000
NUMBER WITH FRACTION: -100000.00
FORCE + SIGN IF POSITIVE: +2000
Example:
SET x=$FNUMBER(x,"-")
This example uses $FNUMBER() to SET x equal to its absolute value.
2 $Get()
$Get()
The $GET function returns the value of a local or global variable if
the variable has a value. If the variable has no value, the function
returns a value specified by an optional second argument, and otherwise
returns a null string.
The format for the $GET function is:
$G[ET](glvn[,expr])
o The subscripted or unsubscripted global or local variable name
specifies the node for which $GET() returns a value.
o If the global or local variable has a data value, $GET() returns
the value of the variable.
o If the global or local variable has no data value, $GET() returns
the value of the optional expression (second argument), or a null
string if the expression is not specified.
M defines $GET(x,y) as equivalent to:
$SELECT($DATA(x)[0:y,1:x)
and $GET(x) as equivalent to:
$GET(x,"")
$GET() provides a tool to eliminate separate initialization of
variables. This technique may provide performance benefits when used to
increase the density of a sparse global array by eliminating nodes that
would otherwise hold absent optional information. On the other hand,
some uses of one argument $GET() can mask logic problems.
GT.M has a "NOUNDEF" mode of operation, which treats all variable
references as if they were arguments to a one argument $GET(). The VIEW
command controls "NOUNDEF" mode.
3 Ex_of_$Get()
Examples of $GET()
Example:
I '$D(^PNT(NAME,TSTR)) S STATUS="NEW TEST"
E I ^PNT(NAME,TSTR)="" S STATUS="WAITING FOR RESULT"
E S STATUS=^PNT(NAME ,TSTR)
This example can be reduced to two lines of code by using $GET(), shown
in the following example. However, by using $GET() in its one-argument
form, the distinction between an undefined variable and one with a null
value is lost:
S STATUS=$G(^PNT(NAME,TSTR))
I STATUS="" S STATUS="WAITING FOR RESULT"
This is solved by using the two-argument form of $GET():
S STATUS=$G(^PNT(NAME,TSTR),"NEW TEST")
I STATUS="" S STATUS="WAITING FOR RESULT"
2 $Justify()
$Justify()
The $JUSTIFY function returns a formatted string.
The format for the $JUSTIFY function is:
$J[USTIFY](expr,intexpr1[,intexpr2])
o The expression specifies the string formatted by $JUSTIFY().
o The first integer expression (second argument) specifies the
minimum size of the resulting string. If the first integer
expression is larger than the length of the expression, $JUSTIFY()
right justifies the expression to a string of the specified length
by adding leading spaces. Otherwise, $JUSTIFY() returns the
expression unmodified unless specified by the second integer
argument.
o The optional second integer expression (third argument) specifies
the number of digits to follow the decimal point in the result, and
forces $JUSTIFY() to evaluate the expression as numeric. If the
numeric expression has more digits than this argument specifies,
$JUSTIFY() rounds to obtain the result. If the expression had fewer
digits than this argument specifies, $JUSTIFY() zero-fills to
obtain the result.
o When the second argument is specified and the first argument
evaluates to a fraction between -1 and 1, $JUSTIFY() returns a
number with a leading zero (0) before the decimal point (.).
$JUSTIFY() fills expressions to create fixed length values. However, if
the length of the specified expression exceeds the specified field
size, $JUSTIFY() does not truncate the result (although it may still
round based on the third argument). When required, $EXTRACT() performs
truncation.
$JUSTIFY() optionally rounds the portion of the result after the
decimal point. In the absence of the third argument, $JUSTIFY() does
not restrict the evaluation of the expression. In the presence of the
third (rounding) argument, $JUSTIFY() evaluates the expression as a
numeric value. The rounding algorithm can be understood as follows:
o If necessary, the rounding algorithm extends the expression to the
right with 0s (zeros) to have at least one more digit than
specified by the rounding argument.
o Then, it adds 5 (five) to the digit position after the digit
specified by the rounding argument.
o Finally, it truncates the result to the specified number of digits.
The algorithm rounds up when excess digits specify a half or more
of the last retained digit and rounds down when they specify less
than a half.
3 Ex_of_$Justify()
Examples of $JUSTIFY()
Example:
GTM> WRITE $JUSTIFY("HELLO",10),!,$JUSTIFY("GOODBYE",5)
HELLO
GOODBYE
GTM>
This uses $JUSTIFY() to display "HELLO" in a field of 10 spaces and
"GOODBYE" in a field of 5 spaces. Because the length of "GOODBYE"
exceeds five spaces, the result overflows the specification.
Example:
GTM> WRITE "1234567890",!,$JUSTIFY(10.545,10,2)
1234567890
10.55
GTM>
This uses $JUSTIFY() to WRITE a rounded value right justified in a
field of 10 spaces. Notice that the result has been rounded up.
Example:
GTM> WRITE "1234567890",!,$JUSTIFY(10.544,10,2)
1234567890
10.54
GTM>
Again, this uses $JUSTIFY() to WRITE a rounded value right justified in
a field of 10 spaces. Notice that the result has been rounded down.
Example:
GTM> WRITE "1234567890",!,$JUSTIFY(10.5,10,2)
1234567890
10.50
GTM>
Once again, this uses $JUSTIFY() to WRITE a rounded value right
justified in a field of 10 spaces. Notice that the result has been
zero-filled to 2 places.
Example:
GTM> WRITE $JUSTIFY(.34,0,2)
0.34
GTM>
This example uses $JUSTIFY to ensure that the fraction has a leading
zero. Note the use of a second argument of zero in the case that
rounding is the only function that $JUSTIFY is to perform.
2 $Length()
$Length()
The $LENGTH function returns the length of a string measured in
characters, or in "pieces" separated by a delimiter specified by one of
its arguments.
The format for the $LENGTH function is:
$L[ENGTH](expr1[,expr2])
o The first expression specifies the string that $LENGTH()
"measures."
o The optional second expression specifies the delimiter that defines
the measure; if this argument is missing, $LENGTH() returns the
number of characters in the string.
o If the second argument is present and not a null string, $LENGTH
returns one more than the count of the number of occurrences of the
second string in the first string; if the second argument is a null
string, the M standard specifies that $LENGTH() returns a zero (0).
$LENGTH() provides a tool for determining the lengths of strings in two
ways, characters and pieces. The two argument $LENGTH() returns the
number of existing pieces, while the one argument returns the number of
characters.
3 Ex_of_$Length()
Examples of $LENGTH()
Example:
GTM> WRITE $LENGTH("KINGSTON")
8
GTM>
This uses $LENGTH() to WRITE the length in characters of the string
"KINGSTON".
Example:
GTM> SET x="Smith/John/M/124 Main Street/Ourtown/KA/USA"
GTM> WRITE $LENGTH(x,"/")
7
GTM>
This uses $LENGTH() to WRITE the number of pieces in a string, as
delimited by /.
Example:
GTM> WRITE $LENGTH("/2/3/","/")
4
GTM>
This also uses $LENGTH() to WRITE the number of pieces in a string, as
delimited by /. Notice that GT.M. adds one count to the final number of
pieces (in this case 3), in the string (displays 4).
2 $NAme()
$NAme()
The $NAME function returns an evaluated representation of some or all
of a local or global variable name.
The format for the $NAME function is:
$NA[ME](glvn[,intexpr])
o The subscripted or unsubscripted global or local variable name,
including naked references, specifies the name for which $NAME()
returns an evaluated representation.
o The optional integer expression (second argument) specifies the
maximum number of subscript levels in the representation. If the
integer expression is not provided or exceeds the actual number of
subscript levels, $NAME() returns a representation of the whole
name. If the integer expression is zero (0), $NAME() returns only
the name. A negative integer expression produces a run-time error.
3 Ex_of_$Name()
Examples of $NAME()
Example:
GTM> SET X="A""B",^Y(1,X,"B",4)=""
GTM> WRITE $NAME(^(3),3)
^Y(1,"A""B","B")
GTM>
This example sets up a naked reference and then uses $NAME() to display
the first three levels of that four-level reference.
Example:
GTM> WRITE $NAME(^(3),0)
^Y
GTM>
This example shows the name level for the same naked reference.
2 $Next()
$Next()
The $NEXT function returns the next subscripted local or global
variable name in collation sequence within the array level specified by
its argument.
$NEXT() has been replaced by $ORDER(). $NEXT has been retained in the
current standard only for compatibility with earlier versions of the
standard. $NEXT() is similar to $ORDER(). However, $NEXT() has the
deficiency that when it encounters negative one (-1) as a subscript, it
returns the same result as when it finds no other data at the level.
This deficiency is particularly disruptive because it occurs in the
middle of the M collating sequence.
As $NEXT() has been removed from the standard in the MDC, you
should use $ORDER.
The format for the $NEXT function is:
$N[EXT](glvn)
o The subscripted global or local variable name specifies the node
following which $NEXT() searches for the next node with data and/or
descendants; the number of subscripts contained in the argument
implicitly defines the array level.
o If $NEXT() finds no node at the specified level after the specified
global or local variable, it returns negative one (-1).
o If the last subscript in a subscripted global or local variable
name is null or negative one (-1), $NEXT() returns the first node
at the specified level.
2 $Order()
$Order()
The $ORDER function returns the subscript of the next or prior local or
global variable name in collation sequence within the array level
specified by its first argument. In doing so, it moves in the direction
specified by the second argument. In GT.M, when $ORDER() has an
unsubscripted argument, it returns the next or previous unsubscripted
local or global variable name in collating sequence.
The format for the $ORDER function is:
$O[RDER](glvn[,expr])
o The subscripted global or local variable name specifies the node
from which $ORDER() searches for the next or previous node that has
data and/or descendants. The number of subscripts contained in the
argument implicitly defines the array level.
o The optional expression (second argument) specifies the direction
for the $ORDER(); 1 specifies forward operation and -1 specifies
reverse operation. Any other values for the expression will cause
an error.
o GT.M extends the M standard to allow unsubscripted names. In this
case, $ORDER() returns the next or previous unsubscripted name.
o If $ORDER() finds no node (or name) at the specified level after
(or before) the specified global or local variable, it returns a
null string (" ").
o If the last subscript in the subscripted global or local variable
name is null, $ORDER() returns the first (or last) node at the
specified level.
$ORDER() provides a tool for retrieving data from M sparse arrays in an
ordered fashion, independent of the order in which it was entered. In
M, routines generally sort by SETting data into an array with
appropriate subscripts and then retrieving the information with
$ORDER().
$ORDER() returns subscripts, not data values, and does not discriminate
between nodes that have data values and nodes that have descendants.
Once $ORDER() provides the subscript, the routine must use the
subscript to access the data value, if appropriate. Using $ORDER()
maintains the naked reference indicator, even if $ORDER() returns a
null.
GT.M optionally permits the use of null subscripts. This feature is
enabled via the VIEW command for local variables and a REGION qualifier
in GDE for global variables. When an application uses null subscripts,
they are "invisible" in a $ORDER() loop so the application must test
for them as a special case, perhaps using $DATA().
3 Ex_of_$Order()
Examples of $ORDER()
Example:
GTM>K S (a(1),a(2000),a("CAT"),a("cat"),a("ALF"), a(12))=1
GTM>S x="" F S x=$O(a(x)) Q:x="" W !,x
1
12
2000
ALF
CAT
cat
GTM>K a("CAT") SET a(5,10)="woolworths",a("cat")="last"
GTM> S x="" F S x=$O(a(x),-1) Q:x="" W !,x
cat
ALF
2000
12
5
1
GTM>
This example uses a $ORDER() loop to display all the subscripts at the
first level of local variable a, make some changes in a, and then
display all the subscripts in reverse order. Notice that $ORDER()
returns only the existing subscripts in the sparse array and returns
them in M collation sequence, regardless of the order in which they
were entered. Also, $ORDER() does not differentiate between node A(5),
which has only descendants (no data value), and the other nodes, which
have data values.
Example:
GTM>k s (%(1),tiva(2),A(3),tiv(4),Q(5),%a(6))=""
GTM>s x="%"
GTM>w:$d(@x) !,x f s x=$order(@x) q:x="" w !,x
%
%a
A
Q
tiv
tiva
x
GTM>s x="zzzzzzzz"
GTM>w:$d(@x) !,x f s x=$order(@x,-1) q:x="" w !,x
x
tiva
tiv
Q
A
%a
%
GTM>
This loop uses $ORDER() to display the current local variable names in
both forward and reverse order. Notice that the first ([^]%) and last
([^]zzzzzzzz) names require handling as special cases and require a
$DATA() function.
Example:
SET acct="",cntt=""
FOR SET acct=$OREDER(^acct(acct)) QUIT:acct="" DO
. F SET cntt=$ORDER(^acct(acct,cntt)) DO WORK
QUIT
This uses two nested $ORDER() loops to cycle through the ^acct global
array and perform some action for each second level node.
2 $Piece()
$Piece()
The $PIECE function returns a substring delimited by a specified string
delimiter made up of one or more characters. In M, $PIECE() returns a
logical field from a logical record.
The format for the $PIECE function is:
$P[IECE](expr1,expr2[,intexpr1[,intexpr2]])
o The first expression specifies the string from which $PIECE() takes
its result.
o The second expression specifies the delimiting string that
determines the piece "boundaries"; if this argument is a null
string, $PIECE() returns a null string.
o If the second expression does not appear anywhere in the first
expression, $PIECE() returns the entire first expression (unless
forced to return a null string by the second integer expression).
o The optional first integer expression (third argument) specifies
the beginning piece to return; if this argument is missing,
$PIECE() returns the first piece.
o The optional second integer expression (fourth argument) specifies
the last piece to return. If this argument is missing, $PIECE()
returns only one piece unless the first integer expression is zero
(0) or negative, in which case it returns a null string. If this
argument is less than the first integer expression, $PIECE()
returns a null string.
o If the second integer expression exceeds the actual number of
pieces in the first expression, $PIECE() returns all of the
expression after the delimiter selected by the first integer
expression.
o The $PIECE() result never includes the "outside" delimiters;
however, when the second integer argument specifies multiple
pieces, the result contains the "inside" occurrences of the
delimiter.
$PIECE() provides a tool for efficiently using values that contain
multiple elements or fields, each of which may be variable in length.
Applications typically use a single character for a $PIECE() delimiter
(second argument) to minimize storage overhead, and increase efficiency
at run-time. The delimiter must be chosen so the data values never
contain the delimiter. Failure to enforce this convention with edit
checks may result in unanticipated changes in the position of pieces
within the data value. The caret symbol (^), backward slash (\), and
asterisk (*) characters are examples of popular visible delimiters.
Multiple character delimiters may reduce the likelihood of conflict
with field contents. However, they decrease storage efficiency, and are
processed with less efficiency than single character delimiters. Some
applications use control characters, which reduce the chances of the
delimiter appearing in the data but sacrifice the readability provided
by visible delimiters.
A SET command argument can have something that has the format of a
$PIECE() on the left-hand side of its equal sign (=). This construct
permits easy maintenance of individual pieces within a string. It also
can be used to generate a string of delimiters. For more information on
SET $PIECE(), refer to SET in the "Commands" chapter.
3 Ex_of_$Piece()
Examples of $PIECE()
Example:
GTM> FOR i=0:1:3 WRITE !,$PIECE("1 2"," ",i),"<"
<
1<
2<
<
GTM>
This loop displays the result of $PIECE(), specifying a space as a
delimiter, a piece position "before," first and second, and "after" the
string.
Example:
GTM> FOR i=-1:1:3 WRITE !,$PIECE("1 2"," ",i,i+1),"<"
<
1<
1 2<
2<
<
GTM>
This example is similar to the previous example except that it displays
two pieces on each iteration. Notice the delimiter (a space) in the
middle of the output for the third iteration, which displays both
pieces.
Example:
F p=1:1:$L(x,"/") W ?p-1*10,$piece(x,"/",p)
This loop uses $LENGTH() and $PIECE() to display all the pieces of x in
columnar format.
Example:
GTM> s $P(x,".",25)="" W x
........................
This SETs the 25th piece of the variable x to null, with a delimiter of
a period. This produces a string of 24 periods preceding the null.
2 $Qlength()
$Qlength()
The $QLENGTH function returns the number of subscripts in a variable
name. The format is:
$QL[ENGTH] (namevalue)
o The namevalue has the form of an evaluated subscripted or
unsubscripted global variable (which yields a length of zero, and
which may have an environment - not counted) or local variable
name.
o The form returns a value which is derived from namevalue. If
namevalue has the form NAME(s1, s2,..., sn), considering n to be
zero, if there are no subscripts, then the function returns n.
o This function only affects the naked indicator if the string in
question is stored in a global variable.
3 Ex_of_$Qlength()
Examples of $Qlength()
Example:
WRITE $DATA(^|"XXX"|ABC(1,2,3,4))
GTM>0
SET X=$NAME(^(5,6))
WRITE $QLENGTH(X)
GTM>5
Refer to $NAme() section earlier in this chapter for an understanding
of the $NAME function.
2 $Qsubscript()
$Qsubscript()
The $QSUBSCRIPT function returns a component of a variable name.
The format of the $QSUBSCRIPT function is:
$QS[UBSCRIPT](namevalue, intexpr)
o The namevalue has the form of an evaluated subscripted or
unsubscripted global or local variable name.
o The intexpr selects the component of the name as follows:
-2 is reserved but may be "error",
-1 for environment,
0 for the unsubscripted name,
1 for the first subscript,
2 for the second subscript, and so on.
If the second argument selects a component that is not part of the
specified name, $QSUBSCRIPT() returns an empty string ("").
3 Ex_of_$Qsubscript()
Examples of $Qsubscript()
Example:
Assume that X is defined as in the "Examples of $Qlength()" earlier in
this chapter;
$QLENGTH (X="^|""XXX""|ABC(1,2,3,5,6)")
WRITE $QSUBSCRIPT(X,-2)
GTM>error
WRITE $QSUBSCRIPT(X,-1)
GTM>XXX
WRITE $QSUBSCRIPT(X,0)
GTM>^ABC
WRITE $QSUBSCRIPT(X,1)
GTM>1
WRITE $QSUBSCRIPT(X,4)
GTM>5
WRITE $QSUBSCRIPT(X,7)
GTM>""
2 $Query()
$Query()
The $QUERY function returns the next subscripted local or global
variable node name, independent of level, which follows the node
specified by its argument in M collating sequence and has a data value.
The format for the $QUERY function is:
$Q[UERY](glvn)
o The subscripted or unsubscripted global or local variable name
specifies the starting node from which $QUERY() searches for a node
with a data value.
o If $QUERY() finds no node after the specified global or local
variable, it returns a null string.
$QUERY() provides a tool for scanning an entire array for nodes that
have data values. Because $QUERY() can return a result specifying a
different level than its argument, the result provides a full variable
name. This contrasts with $ORDER(), which returns a subscript value. To
access the data value at a node, a $ORDER() return can be used as a
subscript; however, a $QUERY() return must be used with indirection.
Because arrays tend to have homogeneous values within a level but not
between levels, $QUERY() is more useful as a tool in utility programs
than in application programs. The $QUERY() is useful in avoiding nested
$ORDER loops.
Note that the standard does not unambiguously define the state of the
naked reference indicator after a $QUERY(). While in GT.M after
$QUERY(), the naked reference indicator reflects the $QUERY() argument,
NOT its result.
3 Ex_of_$Query()
Examples of $QUERY()
Example:
SET ^X(1,2,3)="123"
SET ^X(1,2,3,7)="1237"
SET ^X(1,2,4)="124"
SET ^X(1,2,5,9)="1259"
SET ^X(1,6)="16"
SET ^X("B",1)="AB"
The following routine:
SET y="^X"
FOR SET y=$QUERY(@y) QUIT:y="" WRITE !,y,"=",@y
produces the results:
^X(1,2,3)=123
^X(1,2,3,7)=1237
^X(1,2,4)=124
^X(1,2,5,9)=1259
^X(1,6)=16
^X("B",1)=AB
2 $Random()
$Random()
The $RANDOM function returns a random integer from a range specified by
its argument.
The format for the $RANDOM function is:
$R[ANDOM](intexpr)
o The integer expression specifies the upper exclusive limit of a
range of integers from which $RANDOM() may pick a result; $RANDOM()
never returns a number less than zero (0).
o If $RANDOM() has an argument less than one (1), it generates a
run-time error.
o $RANDOM can generate numbers up to 2147483646 (that is 2GB - 2).
$RANDOM() provides a tool for generating pseudo-random patterns useful
in testing or statistical calculations. $RANDOM() results fall between
zero (0) and one less than the argument.
Random number generators use factors from the environment to create
sequences of numbers. True random number generation requires a source
of what is known as noise. Pseudo-random numbers appear to have no
pattern, but are developed using interactions between factors that vary
in ways not guaranteed to be entirely random. In accordance with the M
standard, the GT.M implementation of $RANDOM() produces pseudo-random
numbers.
3 Ex_of_$Random()
Examples of $RANDOM()
Example:
GTM> FOR i=1:1:10 WRITE $RANDOM(1)
0000000000
GTM>
This shows that when $RANDOM() has an argument of one (1), the result
is too confined to be random.
Example:
SET x=$RANDOM(100)+1*.01
This $RANDOM() example produces a number between 0 and 99. The example
then shifts with addition, and scales with multiplication to create a
value between .01 and 1.
2 $Reverse()
$Reverse()
The $REVERSE function returns a string with the characters in the
reverse order from that of its argument.
The format for the $REVERSE function is:
$RE[VERSE](expr)
o The expr in the syntax is the string to be reversed.
3 Ex_of_$Reverse()
Examples of $REVERSE()
Example:
WRITE $REVERSE(123)
GTM>321
WRITE $REVERSE("AbCDe")
GTM>"eDCbA"
2 $Select()
$Select()
The $SELECT function returns a value associated with the first true
truth-valued expression in a list of paired expression arguments.
The format for the $SELECT function is:
$S[ELECT](tvexpr:expr[,...])
o $SELECT() evaluates expressions from left to right.
o If a truth-valued expression is TRUE (1), $SELECT() returns the
corresponding expression after the colon (:) delimiter.
o Once $SELECT() finds a TRUE, the function does not process any
remaining arguments.
o If $SELECT() finds no TRUE truth-value in its list of arguments,
the function generates a run-time error.
$SELECT() is one of a limited set of functions that permit an
indefinite number of arguments. $SELECT() provides a means of selecting
from a list of alternatives.
Generally, the last $SELECT() argument has numeric literal one (1) for
a truth-value to prevent run-time errors, and to provide a "default"
value.
3 Ex_of_$Select()
Examples of $SELECT()
Example:
GTM> F i=3:-1:0 W !,$S(i=1:"here",i=2:"come",i=3: "Watson")
Watson
come
here
%GTM-E-SELECTFALSE, No argument to $SELECT was true
GTM>
This loop uses $SELECT() to WRITE a series of strings. Because there is
no true argument on the fourth iteration, when i=0, $SELECT() produces
an error.
Example:
SET name=$S(sex="M":"Mr. ",sex="F":"Ms. ",1:"")_name
This example uses $SELECT() to add a prefix to the name based on a sex
code held in the variable sex. Notice that the default handles the case
of a missing or incorrect code.
Example:
IF $S(x=+x:x,x="":0,"JANAPRJULOCT"[x:1,1:0) D THING
This uses $SELECT() to perform complex logic as the truth-valued
expression argument to an IF command.
2 $Stack()
$Stack()
The $STACK function returns strings describing aspects of the execution
environment.
The format for the $STACK function is:
$ST[ACK](intexpr[,expr])
o The intexpr identifies the M virtual machine stack level (as
described by the standard), on which the function is to provide
information.
o The optional second argument is evaluated as a keyword that
specifies a type of information to be returned as follows: "PLACE"
for position in the code (for which, GT.M. due to its compiled
nature, has no information), "MCODE" for the source code if
available, or "ECODE" for the $ECODE value associated with the
stack level.
o When $STACK has only one argument, values corresponding to
available stack levels specify a return value that indicates how
the level was created, as follows:
o If intexpr is zero (0), the function returns information on how
GT.M was invoked.
o If intexpr is minus one (-1), the function returns the highest
level for which $STACK can return information. Note that, if
$ECODE="", $STACK(-1) returns the same value as $STACK.
o If intexpr is greater than zero (0) and less than or equal to
$STACK (-1), indicates how this level of process stack was created
("DO", "XECUTE", or "$$". "$$" being for an extrinsic function).
o If intexpr is greater than $STACK (-1), the function returns an
empty string.
o For any integer value of "level" between 0 and max (inclusive), the
function $STACK(level, type) provides the following information:
Type Information
"MCODE" the line of code that was executed
"PLACE" the address of the above line of code or the symbol at
("@") to indicate code executed from a string value
"ECODE" either an empty string, or the error code(s) that was added
at this execution level.
3 Ex_of_$Stack()
Examples of $STACK()
Example:
WRITE !,$STACK
XECUTE "WRITE !,$STACK"
DO Label
WRITE !,$$ELabel
WRITE !,$STACK
QUIT
Label
WRITE !,$STACK
DO DLabel
QUIT
ELabel()
QUIT $STACK
DLabel
WRITE !,$STACK
QUIT
The above example when executed displays the current M stack level. The
result of the execution is:
GTM>0
1
1
2
1
0
Example for error processing:
For i=$STACK(-1):-1:1 DO
. WRITE !,$STACK(i,"PLACE"),":"
. WRITE $STACK(i,"MCODE")
. QUIT
The above example can be used to display a trace of the code path that
led to an error.
2 $Text()
$Text()
The $TEXT function returns source text for the line specified by its
argument.
The format for the $TEXT function is:
$T[EXT](entryref)
o The entryref specifies the label, offset, and routine of the source
line that $TEXT() returns.
o If the label+offset combination do not fall within the routine,
$TEXT returns a null string.
o If the entryref explicitly or implicitly specifies an offset of
zero (0) from the beginning of the routine, $TEXT() returns the
routine name.
o If the entryref does not specify a routine, GT.M assumes the
current routine, that is, the routine at the top of a ZSHOW "S."
o A GT.M extension to $TEXT() permits negative offsets; however,
every offset must still be preceded by a plus sign (+) delimiter,
(for example, LABEL+-3). If a negative offset points to a line
prior to the zero line, $TEXT() generates a run-time error.
$TEXT() provides a tool for examining routine source code and the name
of the current routine. $TEXT() assists, along with the ZPRINT command,
in debugging programs. $TEXT() also allows the insertion of small
tables of driver information into a routine. Because $TEXT() is not
very efficient and the table-driven technique is generally best suited
to minimal program changes, this approach is best used for prototyping
and the tables should reside in global variables for production.
If $TEXT() cannot access the source file for the current object, either
because it is not in the location from which it was compiled or because
the process does not have access to some piece of the path to the
source, or if the located source does not match the object currently in
use by the process, $TEXT() returns the empty string.
3 Ex_of_$Text()
Examples of $TEXT()
Example:
F i=1:1 S x=$T(+i) Q:x="" W !,x
This loop uses $TEXT() to write out the entire source for the current
routine.
Example:
GTM> WRITE $TEXT(+0)
GTM$DMOD
GTM> WRITE $TEXT(+1)
GTM>
This uses $TEXT() to WRITE the name of the current routine, then it
tries to access the source and returns an empty string. This occurs
because the default Direct Mode image is compiled by Sanchez and
delivered without source. The exact failure message may vary.
2 $TRanslate()
$TRanslate()
The $TRANSLATE function returns a string that results from replacing or
dropping characters in the first of its arguments as specified by the
patterns of its other arguments.
The format for the $TRANSLATE function is:
$TR[ANSLATE](expr1[,expr2[,expr3]])
o The first expression specifies the string on which $TRANSLATE()
operates. If the other arguments are omitted, $TRANSLATE() returns
this expression.
o The optional second expression specifies the characters for
$TRANSLATE() to replace. If a character occurs more than once in
the second expression, the first occurrence controls the
translation, and $TRANSLATE() ignores subsequent occurrences. If
this argument is omitted, $TRANSLATE() returns the first expression
without modification.
o The optional third expression specifies the replacement characters
for the second expression that corresponds by position. If this
argument is omitted or shorter than the second expression,
$TRANSLATE() drops all occurrences of characters in the second
expression that have no replacement in the corresponding position
of the third expression.
$TRANSLATE() provides a tool for tasks such as changing case and doing
encryption. For examples of case translation, refer to the ^%LCASE and
^%UCASE utility routines.
The $TRANSLATE() algorithm can be understood as follows:
o $TRANSLATE() evaluates each character in the first expression,
comparing it character by character to the second expression
looking for a match. If there is no match in the second expression,
the resulting expression contains the character without
modification.
o When it locates a character match, $TRANSLATE() uses the position
of the match in the second expression to identify the appropriate
replacement for the original expression. If the second expression
has more characters than the third expression, $TRANSLATE()
replaces the original character with a null, thereby deleting it
from the result. By extension of this principle, if the third
expression is missing, $TRANSLATE() deletes all characters from the
first expression that occur in the second expression.
3 Ex_of_$TRanslate()
Examples of $TRANSLATE()
Example:
GTM> WRITE $TR("ABC","CB","1")
A1
GTM>
o First, $TRANSLATE() searches for "A" (the first character in the
first expression, "ABC") within the second expression ("CB"). Since
"A" does not exist in the second expression, it appears unchanged
in the result.
o Next, $TRANSLATE() searches for "B" (the second character in the
first expression) within the second expression ("CB"). Because "B"
holds the second position in the second expression ("CB"),
$TRANSLATE() searches for the character holding the second position
in the third expression. Since there is no second character in the
third expression, $TRANSLATE() replaces "B" with a null,
effectively deleting it from the result.
o Finally, $TRANSLATE() searches for "C" (the third character in the
first expression) within the second expression ("CB"), finds it in
the first position, and replaces it with the number 1, which is in
the first position of the third expression. The translated result
is "A1."
Example:
GTM> WRITE $TR("A","AA","BC")
B
GTM>
This $TRANSLATE() example finds the first occurrence of "A" in the
second expression, which holds the first character position, and
substitutes the character in the first position of the third
expression.
Example:
GTM> WRITE $TR("BACKUP","AEIOU")
BCKP
GTM>
Because the $TRANSLATE() has only two parameters in this example, it
finds the characters in the first expression that also exist in the
second expression and deletes them from the result.
2 $View()
$View()
The $VIEW function returns information about an environmental factor
selected by the arguments. In GT.M, the first argument contains a
keyword identifying the environmental factor and, where appropriate,
subsequent arguments select among multiple possible occurrences of that
factor.
The format for the $VIEW() function is:
$V[IEW](expr1[,expr2])
o The first expression specifies a keyword identifying the target
factor for $VIEW() to examine.
o The second expression differentiates between multiple possible
targets for some keywords. $VIEW() requires the second expression
for some keywords and does not permit it for others.
The $VIEW function returns 1 (true) if the region is frozen by MUPIP or
DSE and returns 0 (false) otherwise.
3 Arg_Key_of_$View()
Argument Keywords of $VIEW()
$VIEW() provides a means of accessing GT.M environmental information.
$VIEW() is similar in purpose to Intrinsic Special Variables. When GT.M
permits modification of the factors accessible with $VIEW(), the VIEW
command generally provides the tool for performing the change.
3 Ex_of_$View()
Examples of $VIEW()
Example:
S len=$L(name)
S be4=$EXTRACT(name,1,len-1)_$CHAR($ASCII(name,len)-1)
I $V("RTNNEXT",be4_$E("ZZZZZZZ",1,8-len))=name D
. ZLINK name
Given a routine name this uses $VIEW() to determine whether the image
contains the routine. If the routine already exists the ZLINK replaces
it. Otherwise, auto-ZLINK will bring in a new copy.
2 $ZBIT_Func
$ZBIT Functions
A series of functions beginning with $ZBIT let you manipulate bits.
Each function is described in its own section, and an example at the
end of the last section illustrates the use of several of the functions
in context.
3 $ZBITAND()
$ZBITAND()
The $ZBITAND function performs an AND function on two bit strings and
returns a bit string equal in length to the shorter of the two
arguments (containing set bits in those positions where both of the
input strings have set bits). Positions corresponding to positions
where either of the input strings have a cleared bit, also have cleared
bits in the resulting string.
The format for the $ZBITAND() function is:
$ZBITAND(expr1,expr2)
o The first expression specifies one of the bit strings that is input
to the AND operation.
o The second expression specifies the other bit string that is input
to the AND operation.
3 $ZBITCOUNT()
$ZBITCOUNT()
The $ZBITCOUNT function returns the number of ON bits in a bit string.
The format for the $ZBITCOUNT function is:
$ZBITCOUNT(expr)
o The expression specifies the bit string to examine.
3 $ZBITFIND()
$ZBITFIND()
The $ZBITFIND function performs the analog of the $FIND function on a
bit string. It returns an integer that identifies the position after
the first position equal to a truth-valued expression that occurs at,
or after, the specified starting position.
The format for the $ZBITFIND function is:
$ZBITFIND(expr,tvexpr[,intexpr])
o The expression specifies the bit string to examine.
o The truth-valued expression specifies the bit value for which
$ZBITFIND() searches (1 or 0).
o The optional integer argument specifies the starting position at
which to begin the search. If this argument is missing, $ZBITFIND()
begins searching at the first position of the string. $ZBIT
functions count the first bit as position one (1).
If the optional integer argument exceeds the length of the string, or
if the function finds no further bits, $ZBITFIND() returns a zero
value.
3 $ZBITGET()
$ZBITGET()
The $ZBITGET function returns the value of a specified position in the
bit string.
The format for the $ZBITGET function is:
$ZBITGET(expr,intexpr)
o The expression specifies the bit string to examine.
o The integer argument specifies the position in the string for which
the value is requested. If the integer argument is negative, zero,
or exceeds the length of the bit string, it is rejected with a
run-time error. $ZBIT functions count the first bit as position one
(1).
3 $ZBITLEN()
$ZBITLEN()
The $ZBITLEN function returns the length of a bit string, in bits.
The format for the $ZBITLEN function is:
$ZBITLEN(expr)
o The expression specifies the bit string to examine.
3 $ZBITNOT()
$ZBITNOT()
The $ZBITNOT function returns a copy of the bit string with each input
bit position inverted.
The format for the $ZBITNOT function is:
$ZBITNOT(expr)
o The expression specifies the bit string whose inverted bit pattern
becomes the result of the function.
3 $ZBITOR()
$ZBITOR()
The $ZBITOR function performs a bitwise OR on two bit strings, and
returns a bit string equal in length to the longer of the two arguments
(containing set bits in those positions where either or both of the
input strings have set bits). Positions that correspond to positions
where neither input string has a set bit have cleared bits in the
resulting string.
The format for the $ZBITOR function is:
$ZBITOR(expr1,expr2)
o The first expression specifies one of the bit strings that is input
to the OR operation.
o The second expression specifies the other bit string that is input
to the OR operation.
3 $ZBITSET()
$ZBITSET()
The $ZBITSET function returns an edited copy of the input bit string
with a specified bit set to the value of the truth-valued expression.
The format for the $ZBITSET function is:
$ZBITSET(expr,intexpr,tvexpr)
o The expression specifies the input bit string.
o The integer expression specifies the position of the bit to
manipulate. Arguments that are negative, zero, or exceed the length
of the bit string produce a run-time error. $ZBIT functions count
the first bit as position one (1).
o The truth-valued expression specifies the value to which to set the
specified bit (0 or 1).
3 $ZBITSTR()
$ZBITSTR()
The $ZBITSTR function returns a bit string of a specified length with
all bit positions initially set to either zero or one.
The format for the $ZBITSTR function is:
$ZBITSTR(intexpr[,tvexpr])
o The integer expression specifies the length of the bit string to
return; arguments that exceed the maximum length of 253,952 produce
a run-time error.
o The optional truth-valued expression specifies the value to which
all bit positions should initially be set (0 or 1). If this
argument is missing, the bits are set to zero.
3 $ZBITXOR()
$ZBITXOR()
The $ZBITXOR performs a bitwise exclusive OR on two bit strings, and
returns a bit string equal in length to the shorter of the two
arguments (containing set bits in those position where either but not
both of the input strings have set bits). Positions that correspond to
positions where neither or both input string has a set bit have cleared
bits in the resulting string.
The format for the $ZBITXOR function is:
$ZBITXOR(expr1,expr2)
o The first expression specifies one of the bit strings that is input
to the XOR operation.
o The second expression specifies the other bit string that is input
to the XOR operation.
3 Ex_of_$ZBIT_Func
Examples of $ZBIT Functions
Example:
ZCRC(X)
NEW R,I,J,B,X1,K
SET R=$ZBITSTR(8,0)
FOR I=1:1:$L(X) S R=$ZBITXOR(R,$$BITIN($A(X,I)))
QUIT $$BITOUT(R)
;CONVERT A BYTE TO A BIT STRING
BITIN(X)
SET X1=$ZBITSTR(8,0)
FOR J=1:1:8 S B=X#2,X=X\2 i B s X1=$ZBITSET(X1,J,1)
QUIT X1
; CONVERT A BITSTRING TO A NUMBER
BITOUT(X)
SET X1=0
FOR K=1:1:8 I $ZBITGET(X,K) S X1=X1+(2**(K-1))
QUIT X1
This uses several $ZBIT functions to turn a character into a bit stream
and return a coded value.
While this example illustrates the use of several of the $ZBIT
functions, the following example produces identical results if you need
to code the function illustrated above for production.
ZCRC(X)
NEW R,I,J,B,X1,K
SET R=$ZBITSTR(8,0)
FOR I=1:1:$L(X) S R=$ZBITXOR(R,$C(0)_$E(X,I))
QUIT $A(R,2)
This example illustrates the use of $C to specify the number of invalid
bits that exist at the end of the character string. In this case there
are zero invalid bits.
2 $ZDate()
$ZDate()
The $ZDATE function returns a date and/or time formatted as text based
on an argument formatted in the manner of $HOROLOG. For information on
the format of $HOROLOG, refer to the "Intrinsic Special Variables"
chapter in this manual.
The format for the $ZDATE function is:
$ZD[ATE](expr1[,expr2[,expr3[,expr4]]]])
o The first expression specifies in $HOROLOG format the date and/or
time that $ZDATE() returns in text format. If the output requires
only the date or the time, the other piece of the argument that is
delimited by a comma (,) may be null.
o The optional second expression specifies a string providing
$ZDATE() with a "picture" of the desired output format. If this
argument is missing or null, $ZDATE() uses the default format
string "MM/DD/YY". If the optional second expression exceeds 64
characters, $ZDATE() generates a run-time error.
o The optional third expression specifies a list of 12 month codes,
separated by commas (,), that $ZDATE() uses in formatting text
months called for by the "MON" picture, (i.e., $ZDATE() outputs
$PIECE(expr3,",",month-number) when "MON" appears in the second
expression). If this argument is missing or null, $ZDATE() uses
three-character English abbreviations for months.
o The optional fourth expression specifies a list of seven day codes,
separated by commas (,), which $ZDATE() uses in formatting text
days of the week called for by the "DAY" picture, $ZDATE() outputs
$PIECE (expr4,",",day-of-week-number) when "DAY" appears in the
second expression; if this argument is missing or null, $ZDATE()
uses three-character English abbreviations for days of the week.
$ZDATE() provides an easy and flexible tool for putting M internal
date/time ($HOROLOG) formats into more user-friendly formats.
The Intrinsic Special Variable $ZDATEFORM determines the output format
for years. The default value is zero (0), in which case $ZDATE() with
one argument (no format specification) uses a "YY" (two digit) format
for all years. If $ZDATEFORM is one (1), a "YYYY" (four digit) format
is used for years later than 1999. For all other values of $ZDATEFORM,
"YYYY" (four digit) format is used for all years. $ZDATEFORM does not
affect $ZDATE() when the format argument is specified.
3 $ZDate_Form_Spec_Ele
$ZDATE Format Specification Elements
This section lists the $ZDATE() format specification elements. $ZDATE()
format specifications must appear in upper case. When any alphabetic
characters in format specifications are in lower case, $ZDATE()
generates a run-time error.
YY Outputs the rightmost two digits of the year.
YEAR Outputs the year as a four-digit number.
MM Outputs the month as a two-digit zero-filled number between 01
and 12.
MON Outputs the month as a three-letter abbreviation. (You can
modify the output further using expr3).
DD Outputs the day of the month as a two-digit zero-filled number
between 01 and 31.
DAY Outputs the day of the week as a three-letter abbreviation.
(You can modify the output further using expr4).
24 Outputs the hour of the day as a zero-filled number between 00
and 23.
12 Outputs the hour of the day as a zero-filled number between 01
and 12.
60 Outputs the minute of the hour as a zero-filled number between
00 and 59.
SS Outputs the second of the minute as a zero-filled number between
00 and 59.
AM Outputs the letters AM and PM depending on the time.
+ Inserts a plus sign (+) in the output string
- Inserts a minus sign (-) in the output string.
. Inserts a period (.) in the output string.
, Inserts a comma (,)in the output string.
/ Inserts a slash (/) in the output string.
: Inserts a colon (:) in the output string.
; Inserts a semi-colon (;) in the output string.
* Inserts an asterisk (*) in the output string.
A blank space inserts a blank space in the output string.
3 Ex_of_$ZDate()
Examples of $ZDATE()
Example:
GTM> WRITE $H,!,$ZDATE($H)
55243,43223
04/01/2002
GTM>
This displays $HOROLOG and then uses $ZDATE() to display today's date.
The output shown would appear if today were the first of April, 2002.
Example:
GTM> W $ZDATE($H,"DD-MON-YEAR")
01-APR-2002
GTM>
This uses the second argument to specify a text format different from
the default.
Example:
GTM> SET m="Januar,Februar,Marz,April,Mai,Juni,Juli,August,"
GTM> SET m=m_"September,October,November,Dezember"
GTM> WRITE $ZDATE($H,"DD-MON-YEAR",m)
01-April-2002
GTM>
This is similar to the prior example, however it uses the third
argument to specify the months in German.
Example:
GTM> SET d="Dimanche,Lundi,Mardi,Mercredi,Jeudi,Vendredi,Samedi"
GTM> WRITE $ZD($H,"DAY, DD/MM/YY","",d)
Mercredi, 01/04/2002
GTM>
This example displays the first of April, however it uses the fourth
argument to specify the days of the week in French.
Example:
GTM> WRITE !,$ZDATE($H,"12:60:55 AM")
10:35:51 PM
GTM>
This example shows hours, minutes, and seconds in a 12 hour clock with
an AM/PM indicator.
Example:
GTM> WRITE !,$ZDATE(",36524","24-60")
10-08
GTM>
This example shows hours and minutes on a 24 hour clock. Notice that
the first argument must provide the time in the second comma delimiter
piece to match $HOROLOG format.
Example:
GTM>WRITE $ZDATEFORM
0
GTM>WRITE $ZDATE($H)
11/15/02
GTM>SET $ZDATEFORM=1
GTM>WRITE $ZDATE($H)
11/15/2002
GTM>WRITE $ZDATE($H,"MM/DD/YY")
11/15/02
This example converts the output format for years from the default
("YY") format to the four digit format ("YYYY") using the Intrinsic
Special Variable $ZDATEFORM.
2 $ZJOBEXAM()
$ZJOBEXAM()
The $ZJOBEXAM function returns the full specification of the file into
which the function places a ZSHOW "*". The return value serves as a way
to save, to notify others of the exact location of the output, or to
open the file for further processing. GT.M reports each $ZJOBEXAM() to
the operator log facility with its file specification.
The optional expression argument is a template output device
specification. It can be a device, a file directory, or a file name.
The template is an expression that is pre-processed to create a file
specification as the target for the ZSHOW. The preprocessing is
equivalent to $ZPARSE(), as illustrated by the following M code:
Set deffn="GTM_JOBEXAMINE.ZSHOW_DMP_"_$JOB_"_"_<cntr>
Set filespec=$ZPARSE(expr1,"",deffn)
The $ZJOBEXAM()does not trigger error processing except when there is a
problem storing its return value, so no error is reported to the
process until after any dump is complete. In the event of any error
encountered during the $ZJOBEXAM(), GT.M sends an appropriate message
to operator log facility and returns control to the caller. Note that
this special error handling applies only to the $ZJOBEXAM(), and is not
a property of the $ZINTERRUPT interrupt handler, which uses $ZJOBEXAM()
by default.
$ZJOBEXAM() dump files contain the context of a process at the time the
function executes. Placement and management of these files should
consider their potential size and security implications.
3 Ex_of_$ZJOBEXAM()
Examples of $ZJOBEXAM()
Example:
GTM>Set x=$ZJOBEXAM()
GTM>Write x
/home/testarea/demo/GTM_JOBEXAM.ZSHOW_DMP_28760_1
GTM>Set x=$ZJOBEXAM("test.file")
GTM>write x
/home/testarea/demo/test.file
GTM>
Shows default file name and type of the files created containing the
zshow dump information and the difference when the name and type are
specified.
2 $ZMessage()
$ZMessage()
The $ZMESSAGE function returns a message string associated with a
specified status code.
The format for the $ZMESSAGE function is:
$ZM[ESSAGE](intexpr)
o The integer expression specifies the status code for which
$ZMESSAGE() returns error message text.
$ZMESSAGE() provides a tool for examining the message associated with a
particular message code as reported in $ZSTATUS.
The $ZSTATUS Intrinsic Special Variable holds the message code and the
message of the last non-Direct Mode GT.M error. For more information on
$ZSTATUS, refer to the "Intrinsic Special Variables" chapter in GT.M
Programmer's Guide.
3 Ex_of_$ZMessage()
Examples of $ZMESSAGE()
Example:
GTM> WRITE $ZMESSAGE(36)
Interrupted system call
GTM>
This uses $ZMESSAGE() to display the message string corresponding to
code 36.
2 $ZPARSE()
$ZPARSE()
The $ZPARSE function expands a file name to a full pathname and then
returns the full pathname or one of its fields (directory, name, or
extension).
The format for the $ZPARSE function is:
$ZPARSE(expr1[,expr2[,expr3[,expr4[,expr5]]]])
o The first expression specifies the file name; if the file name is
not valid, $ZPARSE() returns a null string; if the file name
contains a wildcard (* and/or ?), $ZPARSE() returns a file name
containing the wildcard(s).
o The optional second expression specifies the field of the pathname
that $ZPARSE() returns; if this argument is missing or null,
$ZPARSE() returns a full pathname constructed using default values
in place of any fields missing for directory, file and extension.
o The optional third and fourth expressions specify default values to
use during file name expansion for missing fields (directory, name,
or extension), if any, in the original file name. For any field
missing in the original file name specified in expr1, $ZPARSE()
will attempt to substitute the corresponding field from expr3; if
that field is not present in expr3, $ZPARSE() will attempt to use
the corresponding field from expr4.
o If the file extension is missing from all three of expr1, expr3,
and expr4, $ZPARSE() will return a null string for the
corresponding field. If the file, or directory is missing from all
three of expr1, expr3, and expr4, $ZPARSE() will substitute the
information from your current working directory.
o The optional fifth expression specifies the mode or type of parse
that $ZPARSE() performs.
$ZPARSE() provides a tool for verifying that a file name is
syntactically correct, for examining specific fields of a file name,
and for filling in missing pieces in a partial specification based on a
hierarchy of defaults. For information about determining whether a file
exists, refer to the description of $ZSEARCH().
$ZPARSE() arguments, after the first, are optional. If you use no other
arguments, a single argument is sufficient. However, if you use
selected arguments $ZPARSE() requires that null strings ("") be filled
in for the unspecified arguments.
The acceptable keywords for the second argument are:
"DIRECTORY" Directory name
"NAME" File name (excluding file extension)
"TYPE" File typeextension
The keywords may be entered in either upper or lower case. Variables
that evaluate to these strings and indirection are acceptable for
argument two. When the keywords themselves appear as string literals,
they must be enclosed in quotation marks (" ").
The following guidelines must be followed in constructing arguments
one, three and four:
o Directory specifications must end in a slash; anything after the
final slash in the directory specification is assumed to be part of
the name specification.
o A file name with an extension must include at least one character
to the left of the period (.). Thus, "/user/.login" refers to the
file named ".login", while "/usr/taxes.c" refers to a file named
"taxes" with the extension "c". If a file name includes more than
one period, the extension includes all letters to the right of the
rightmost period.
The keywords for the fifth argument $ZPARSE() are:
NULL ("") Returns a full file-specification or device
"SYNTAX_ONLY"
Disables checking for the existence of the directory or device.
3 Ex_of_$ZPARSE()
Examples of $ZPARSE()
Example:
GTM> WRITE $ZPARSE("test","","/usr/work/","dust.lis")
/usr/work/test.lis
GTM>
This uses $ZPARSE() to demonstrate defaulting using the third and
fourth arguments. The result gets the directory field from the third
expression, the name from the first expression, and the type from the
fourth expression.
Example:
GTM>r!,"file :",f w ?20,$zparse(f,"directory")
file: test.list /usr/work/
GTM>
This uses $ZPARSE() to display the directory for the file name entered
as input at the prompt file: , in this case, the current working
directory.
Example:
$ cd /usr/work/me
$ $gtm
GTM>W $ZPARSE("test","","x.list","y.c")/usr/work/me/test.lis
GTM>W $ZPARSE("test","","/usr/work/","/dev/y.c")/usr/work/test.c
GTM>W $ZPARSE("test","","/usr/work","/dev/y.c")/usr/test.c
GTM>
This example illustratest the use of the third and fourth arguments to
$ZPARSE(). In the first statement, the first argument has no directory
or extension field, so $ZPARSE() substitutes the extension field from
the third argument. Since neither the third nor fourth argument
specifies a directory, and because the fourth argument does not contain
any fields that are not present in the third argument, the fourth
argument is not used.
In the second statement, the first argument to $ZPARSE() is again
missing both the directory and extension. In this instance, $ZPARSE()
uses the directory specified in the third argument and, becuase neither
the first nor third argument specifies a file extension, $ZPARSE() uses
the file extension from the fourth argument.
In the third statement, because "/usr/work" does not end with a
backward slash (/), $ZPARSE() interprets the substring "work" as a file
name. Then, $ZPARSE() substitutes "/usr/" for the directory missing in
the first argument and substitutes ".c" from the fourth argument for
the extension missing from both the first and third arguments.
Example:
$ cd /usr/work/met
$ $gtm_dist/mumps -direct
GTM>f i="DIRECTORY","NAME","TYPE",""d
. W $zparse("test.m",i),!
/usr/work/me/
test
.m
/usr/work/me/test.m
GTM>
This example illustrates the output produced for each of the possible
values for the second argument.
2 $ZPrevious()
$ZPrevious()
The $ZPREVIOUS function returns the subscript of the previous local or
global variable name in collation sequence within the array level
specified by its argument. When $ZPREVIOUS() has an unsubscripted
argument, it returns the previous unsubscripted local or global
variable name in collating sequence.
The $ZPREVIOUS function provides compatibility with some other M
implementations. The M Development Committee chose to implement this
functionality with the optional second -1 argument of $ORDER().
Therefore, when a design requires this functionality $ORDER() has the
advantage over $ZPREVIOUS of being part of the M standard.
The format for the $ZPREVIOUS function is:
$ZP[REVIOUS](glvn)
o The subscripted or unsubscripted global or local variable name
specifies the node prior to which $ZPREVIOUS() searches backwards
for a defined node with data and/or descendants. The number of
subscripts contained in the argument implicitly defines the array
level.
o If $ZPREVIOUS() finds no node at the specified level before the
specified global or local variable, it returns a null string.
o If the last subscript in the subscripted global or local variable
name is null, $ZPREVIOUS() returns the last node at the specified
level.
$ZPREVIOUS() is equivalent to $ORDER() with a second argument of -1.
2 $ZQGBLMOD()
$ZQGBLMOD()
The $ZQGBLMOD function enables an application to determine whether it
can safely apply a lost transaction to the database. A lost transaction
is a transaction that must be rolled off a database to maintain
dual-site consistency.
The format for the $ZQGBLMOD function is:
$ZQGBLMOD(gvn)
o The subscripted or non-subscripted global variable name (gvn)
specifies the target node.
o A return value of zero (0) means the value of the global variable
has not changed since the last synchronization of the primary and
secondary.
o A return value of one (1) means the value of the global variable
may have changed since the last synchronization of the primary and
secondary.
$ZQGBLMOD function produces an error if you submit an argument that is
not a global variable name.
Internally, $ZQGBLMOD (gvn) compares the GT.M transaction number in the
database block in which the global variable name is stored with the
value in the resync_tn field stored in the database file header.
For example, if x is the transaction number of the level-0 database
block in which gvn resides, and y is the value of resync_tn of region
reg containing gvn, then the following is true:
o If x £ y, no transaction modified the level-0 database block z in
which gvn resides since the databases at primary and secondary
became synchronized with each other. $ZQGBLMOD() returns a zero
(0).
o If x > y, some transaction modified z, but not necessarily
❇❖■
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
, after the primary and secondary system databases synchronized with each
If a transaction is a lost transaction that has been rolled back and it
is determined that for all the M globals set and killed in the
transaction $ZQGBLMOD() is zero (0), it is probably safe to apply the
updates automatically. However, this determination of safety can only
be made by the application designer and not by GT.M. If the $ZQGBLMOD()
is one (1) for any set or kill in the transaction, it is not safe to
apply the update.
The test of $ZQGBLMOD() and applying the updates must be
encapsulated inside a GT.M transaction.
Another approach to handling lost transactions would be to store in the
database the initial message sent by a client, as well as the outcome
and the response, and to reprocess the message with normal business
logic. If the outcome is the same, the transaction can be safely
applied.
If restartable batch operations are implemented, lost batch
transactions can be ignored since a subsequent batch restart will
process them correctly.
2 $ZSEARCH()
$ZSEARCH()
The $ZSEARCH function attempts to locate a file matching the specified
file name. If the file exists, it returns the file name; if the file
does not exist, it returns the null string.
The format for the $ZSEARCH function is:
$ZSEARCH(expr[,intexpr])
o The expression contains a file name, with or without wildcards, for
which $ZSEARCH() attempts to locate a matching file. Repeating
$ZSEARCH with the same filename uses the same context and return a
sequence of matching files when they exist; when the sequence is
exhausted, $ZSEARCH() returns an empty string (""). Any change to
the file name starts a new context.
o $ZSEARCH() uses the process current working directory, if the
expression does not specify a directory.
o The optional integer expression specifies a "stream" number from 0
to 255 for each search; streams provide a means of having up to 256
$ZSEARCH() contexts simultaneously in progress.
o If a $ZSEARCH() stream has never been used or if the expression
differs from the argument to the last $ZSEARCH() of the stream, the
function resets the context and returns the first pathname matching
the expression; otherwise, it returns the next matching file in
collating sequence; if the last prior pathname returned for the
same expression and same stream was the last one matching the
argument, $ZSEARCH() returns a null string.
$ZSEARCH() provides a tool for verifying that a file exists. For
information to help determine the validity of a file name, refer to the
section on $ZPARSE()
3 Ex_of_$ZSEARCH()
Examples of $ZSEARCH()
Example:
GTM> WRITE $ZSEARCH("data.dat")
/usr/staff/ccc/data.dat
GTM>
This uses $ZSEARCH() to display the full file path name of "data.dat"
in the process current default directory.
Example:
GTM>SET x=$ZSEARCH("*.M")
GTM>FOR S x=$ZSEARCH("*.M") Q:x="" W !,$ZPARSE(x,"NAME")
This FOR loop uses $ZSEARCH() and $ZPARSE() to display M source file
names in the process current working directory. To ensure that the
search starts at the beginning, the example resets the context by first
searching with a different argument.
2 $ZTRNLNM()
$ZTRNLNM()
The $ZTRNLNM function gives the value of an environment variable.
$ZTRNLNM() does iterative translation in cases where one environment
variable is set to the name of another environment variable.
The format for the $ZTRNLNM function is:
$ZTRNLNM(expr)
The expression specifies the target environment variable.
3 Ex_of_$ZTRNLNM()
Examples of ZTRNLNM()
Example:
GTM> write $ztrnlnm("gtm_dist")
/usr/dev/bin
GTM>
This uses $ZTRNLNM() to display the translation value for gtm_dist.
1 Intr_Spe_Vars
Intrinsic Special Variables
M Intrinsic Special Variables start with a single dollar sign ($). GT.M
provides such variables for program examination. In some cases, the
Intrinsic Special Variables may be set to modify the corresponding part
of the environment.
None of the Intrinsic Special Variables can be KILLed. SETting or
NEWing is generally not allowed, but is specifically noted in the
descriptions of those that do.
2 $Device
$Device
$D[EVICE] reflects the status of the current device. If the status of
the device does not reflect any error-condition, the value of $DEVICE,
when interpreted as a truth-value is 0 (FALSE). If the status of the
device reflect any error-condition, the value of $DEVICE, when
interpreted as a truth-value is 1 (TRUE).
The initial value of $DEVICE is implementation dependant. However,
if the initial value of $IO is the empty string, then the initial
value of $DEVICE is also empty string.
$DEVICE gives status code and meaning, in one access:
Example:
1,Connection reset by peer
The above message is displayed on the server side when the socket
device is closed on the client side.
2 $ECode
$ECode
$EC[ODE] contains a list of error codes for "active" errors -the error
conditions which are not yet resolved. If there are no active errors,
$ECODE contains the empty string. Whenever an error occurs, a code for
that error is appended to the value of $ECODE in such a way that the
value of $ECODE always starts and ends with a comma.
The value of $ECODE can be SET, and when it is set to a non-NULL value,
error processing starts.
List of codes for $ECODE start with comma seperated by commas. A code
starts with "M", "U", or "Z", with rest numeric. "M" codes are assigned
by MDC (MUMPS Development Committee), "U" by application (programmers),
and "Z" codes by MUMPS implementors (in this case GT.M).
An error always has a GT.M specified code and many errors also have an
ANSI Standard code. The complete list of standardized error codes can
be referenced from GT.M Message and Recovery Procedures Reference
Manual version 4.3 and onwards.
IF $ECODE[",M61," WRITE "Undefined local variable"
The leftmost character of the value of $ECODE is always a comma.
This means that every error code that is stored in $ECODE is
surrounded by commas. If $ECODE was to contains the error code
without the commas (that is, "M61"), the variable would check for
subset "M6" as well. Thus, it is recommended that you include the
commas in the value to check. For example; check whether $ECODE
contains ",M61,".
$ECODE can be SET but not NEW'd. When $ECODE is set to the empty string
(" "), error handling becomes "inactive" and therefore QUIT does not
trigger additional error handling.
When $ECODE is not set to the empty string, M error handling is active,
which also affects behaviour in some aspects of $STACK.
2 $EStack
$EStack
$ES[TACK] contains an integer count of the number of M virtual machine
stack levels that have been activated and not removed since the last
time $ESTACK was NEW'd.
A NEW $ESTACK saves the value of current $ESTACK and then sets its
value to zero (0). If $ESTACK has not been NEW'd in the current
execution path, $ESTACK=$STACK.
SET $ETRAP="QUIT:$ESTACK GOTO LABEL^ROUTINE"
$ESTACK maybe used as a flag to indicate error traps invoked in
particular stack levels needed to perform some different action(s).
$ESTACK can be most useful in setting up a layered error trapping
mechanism.
GT.M does not permit $ESTACK to be SET, however $ESTACK can be
NEWed.
2 $ETrap
$ETrap
$ET[RAP] contains a string value that GT.M invokes when an error occurs
during routine execution. When a process is initiated, but before any
commands are processed, the value of $ETRAP is empty string.
The value of this variable is the M[UMPS] code that gets executed when
an error occurs.
SET $ETRAP="QUIT:$ESTACK GOTO LABEL^ROUTINE"
The value of $ETRAP is changed with the SET command. Changing the value
of $ETRAP with the SET command initiates a new trap; it does not save
the old trap.
For more examples of the use of special variable $ETRAP, see the
function $STACK().
2 $Horolog
$Horolog
$H[OROLOG] contains a string value specifying the number of days since
"31 December, 1840," and the number of seconds since midnight of the
current day, separated by a comma (,).
At midnight, the piece of the string following the comma resets to zero
(0) and the piece preceding the comma increments by one (1). GT.M does
not permit the SET command to modify $HOROLOG.
Example:
GTM> WRITE $HOROLOG
Produces the result 58883,55555 at 3:25:55 pm on 20 March, 2002.
For further information on formatting $HOROLOG for external use, see
the section on $ZDATE().
2 $Io
$IO
$I[O] contains the name of the current device specified by the last USE
command. The M standard does not permit the SET command to modify $IO.
USE 0 produces the same $IO as USE $P[RINCIPAL], but $P is the
preferred construct.
2 $Job
$Job
$J[OB] contains the current process identifier.
$JOB is guaranteed to be unique for every concurrently operating
process on a system. However, operating systems reuse PIDs over time.
GT.M does not permit the SET command to modify $JOB.
Example:
LOOP0 FOR SET itm=$O(^tmp($J,itm)) Q:itm="" DO LOOP1
This uses $J as the first subscript in a temporary global to insure
that every process uses separate data space in the global ^tmp.
2 $Key
$Key
$K[EY] contains the string that terminated the most recent READ command
from the current device (including any introducing and terminating
characters). If no READ command s issued to the current device or if no
terminator is used, the value of $KEY is an empty string. However, when
input is terminated by typing a function key, the value of $KEY is
equal to the string of characters that is transmitted by that function
key.
The effect of a READ *glvn on $KEY is unspecified.
If a Character Set Profile input-transform is in effect, then this is
also applied to the value stored in $KEY.
2 $Principal
$Principal
$P[RINCIPAL] contains the absolute pathname of the principal (initial
$IO) device. $PRINCIPAL is an MDC Type A enhancement to standard M.
Input and output for a process may come from separate devices, namely,
the standard input and output. However, the M I/O model allows only one
device to be USEd (or active) at a time. When and image starts, GT.M
implicitly OPENs the standard input and standard output device(s) and
assigns the device(s) to $PRINCIPAL. For USE deviceparameters, it is
the standard input that determines the device type.
For an image invoked interactively, $PRINCIPAL is the user's terminal.
For an image invoked from a terminal by means of a shell script,
$PRINCIPAL is the shell script's standard input (usually the terminal)
and standard output (also usually the terminal) for output, unless the
shell redirects the input or output.
GT.M provides a mechanism for the user to create a name for $PRINCIPAL
in the shell before invoking GT.M. The environment variable
gtm_principal, if defined becomes a synonym for the actual device and
the value for $PRINCIPAL. $IO holds the same value as $PRINCIPAL. $ZIO
in this case, holds the fully expanded name of the actual device. Refer
to $ZIO section in this chapter for an example of its usage.
GT.M ignores a CLOSE specifying the principal device. GT.M does not
permit the SET command to modify $PRINCIPAL.
2 $Quit
$Quit
$Q[UIT] indicates whether the current block of code was called as an
extrinsic function or as a subroutine.
If $Q[UIT] contains 1 (when the current process-stack frame is invoked
by an extrinsic function), the QUIT would therefore require an
argument.
When a process is initiated, but before any commands are processed,
the value of $Q[UIT] is zero (0).
This special variable is mainly used in error-trapping conditions. Its
value tells whether the current DO level was reached by means of a
subroutine call (DO xxx) or by a function call (SET variable=$$xxx).
A typical way of exiting from an error trap is:
QUIT:$QUIT "" QUIT
GT.M does not permit $QUIT to be SET or NEWed.
2 $Reference
$Reference
$R[EFERENCE] contains the last global reference. Until the first global
reference is made by an M program, $REFERENCE contains the empty string
(""). This way it is useful in determining if the usage of a naked
reference is valid.
A typical way of using this is:
IF $REFERENCE="" QUIT "<undefined>"
$R[EFERENCE] being a read-only variable cannot be SET or NEW'd.
2 $STack
$STack
$ST[ACK] contains an integer value of zero (0) or greater indicating
the current level of M execution stack depth.
When a process is initiated but before any command is executed, the
value of $STACK is zero (0).
The difference between $STACK and $ESTACK is that $ESTACK may
appear as an argument of the NEW command. NEWing $ESTACK resets its
value to zero (0), and can be useful to set up a layered error
trapping mechanism.
The value of $STACK is "absolute" since the start of a GT.M. process,
whereas the value of $ESTACK is "relative" to the most recent
"anchoring point".
For examples on the use of special variable $STACK, refer to $STACK()
in the "Functions" chapter in this manual.
2 $Storage
$Storage
$S[TORAGE] contains an integer value specifying the number of free
bytes of address space remaining between the memory currently under
management by the process and the theoretical maximum available to the
process.
GT.M uses memory for code (instructions) and data. If the amount of
virtual memory available to the process exceeds 2,147,483,647 bytes, it
is reported as 2,147,483,647 bytes.
Instruction space starts out with the original executable image.
However, GT.M may expand instruction space by ZLINKing additional
routines.
Data space starts out with stack space that never expands, and pool
space which may expand. Operations such as opening a database or
creating a local variable may cause an expansion in pool space. GT.M
expands pool space in fairly large increments. Therefore, SETs of local
variables may not affect $STORAGE at all or may cause an apparently
disproportionate drop in its value.
Once a GT.M process adds either instruction or data space, it never
releases that space. However, GT.M does reuse process space made
available by actions such as KILLs of local variables. $STORAGE can
neither be SET or NEWed.
2 $SYstem
$SYstem
$SY[STEM] contains a string that identifies the executing M instance.
The value of $SYSTEM is a string that starts with a unique numeric code
that identifies the manufacturer. Codes are assigned by the MDC (MUMPS
Development Committee).
$SYSTEM in GT.M starts with "47" followed by a comma and the evaluation
of the environment variable gtm_sysid. If the name has no evaluation,
the value after the comma is gtm_sysid.
2 $Test
$Test
$T[EST] contains a truth value specifying the evaluation of the last IF
argument or the result of the last operation with timeout. If the last
timed operation timed out, $TEST contains FALSE (0); otherwise, it
contains TRUE (1).
$TEST serves as the implicit argument for ELSE commands and
argumentless IF commands.
M stacks $TEST when invoking an extrinsic and performing an
argumentless DO. After these operations complete with an implicit or
explicit QUIT, M restores the corresponding stacked value. Because,
with these two exceptions, $TEST reflects the last IF argument or
timeout result on a process wide basis. Use $TEST only in immediate
proximity to the operation that last updated it.
M routines cannot modify $TEST with the SET command.
Example:
IF x=+x DO ^WORK
ELSE SET x=0
The ELSE statement causes M to use the value of $TEST to determine
whether to execute the rest of the line. Because the code in routine
WORK may use IFs and timeouts, this use of $TEST is not recommended.
Example:
SET MYFLG=x=+x
IF MYFLG DO ^WORK
IF 'MYFLG SET x=0
This example introduces a local variable flag to address the problems
of the prior example. Note that its behavior results in the opposite
$TEST value from the prior example.
Example:
IF x=+x DO ^WORK IF 1
ELSE SET x=0
This example uses the IF 1 to ensure that the ELSE works counter to the
IF.
2 $TLevel
$TLevel
$TL[EVEL] contains a count of executed TSTARTs that are currently
unmatched by TCOMMITs. $TLEVEL is zero (0) when there is no TRANSACTION
in progress. When $TLEVEL is greater than one (>1), it indicates that
there are nested sub-transactions in progress. Sub-transactions are
always subject to the completion of the main TRANSACTION and cannot be
independently acted upon by COMMIT, ROLLBACK, or RESTART.
$TLEVEL can be used to determine whether there is a TRANSACTION in
progress and to determine the level of nesting of sub-transactions.
M routines cannot modify $TLEVEL with SET.
Example:
IF $TLEVEL TROLLBACK
This example performs a TROLLBACK if a transaction is in progress. A
statement like this should appear in any error handler used with
transaction processing. For more information on transaction processing
refer to the "General Language Features of M" chapter in GT.M
Programmer's Guide.
2 $TRestart
$TRestart
$TR[ESTART] contains a count of the number of times the current
TRANSACTION has been RESTARTed. A RESTART can be explicit (specified in
M as a TRESTART) or implicit (initiated by GT.M as part of its internal
concurrency control mechanism). When there is no TRANSACTION in
progress, $TRESTART is zero (0).
$TRESTART can be used by the application to limit the number of
RESTARTs, or to cause a routine to perform different actions during a
RESTART than during the initial execution.
GT.M does not permit the SET command to modify $TRESTART.
Example:
TRANS TSTART ():SERIAL
IF $TRESTART>2 WRITE !;"Access Conflict" QUIT
This example terminates the sub-routine with a message if the number of
RESTARTs exceeds 2.
For more information on transaction processing, refer to the section on
that topic in the "General Language Features of M" chapter in GT.M
Programmer's Guide.
2 $X
$X
$X contains an integer value ranging from 0 to 65,535, specifying the
horizontal position of a virtual cursor in the current output record.
$X=0 represents the left-most position of a record or row.
Every OPEN device has a $X. However, M only accesses $X of the current
device. Therefore, exercise care in sequencing USE commands and
references to $X.
Generally, GT.M increments $X for every character written to and read
from the current device. M format control characters, write filtering,
and the device WIDTH also have an effect on $X.
$X never equals or exceeds the value of the device WIDTH. Whenever it
reaches the value equal to the device WIDTH, it gets reset to zero (0).
GT.M follows the MDC Type A recommendation and permits an M routine to
SET $X. However, SET $X does not automatically issue device commands or
escape sequences to reposition the physical cursor.
For more information on $X, refer to the "Input/Output Processing"
chapter in GT.M Programmer's Guide.
2 $Y
$Y
$Y contains an integer value ranging from 0 to 65,535 specifying the
vertical position of a virtual cursor in the current output page. $Y=0
represents the top row or line.
Every OPEN device has a $Y. However, M only accesses $Y of the current
device. Therefore, exercise care in sequencing USE commands and
references to $Y.
When GT.M finishes the logical record in progress, it generally
increments $Y. GT.M recognizes the end of a logical record when it
processes certain M format control characters, or when the record
reaches its maximum size, as determined by the device WIDTH, and the
device is set to WRAP. The definition of "logical record" varies from
device to device. For an exact definition, see the sections on each
device type. Write filtering and the device LENGTH also have an effect
on $Y.
$Y never equals or exceeds the value of the device LENGTH. Whenever it
reaches the value equal to the device LENGTH, it gets reset to zero (0)
GT.M permits an M routine to SET $Y. However, SET $Y does not
automatically issue device commands or escape sequences to reposition
the physical cursor.
For more information on $Y, refer to the "Input/Output Processing"
chapter in GT.M Programmer's Guide.
2 $ZA
$ZA
$ZA contains a status determined by the last read on the device. The
value is a decimal integer with a meaning determined by the device as
follows:
For Terminal I/O:
0 Indicating normal termination of a read operation
1 Indicating a parity error
2 Indicating that the terminator sequence was too long
9 Indicating a default for all other errors
For Sequential Disk Files I/O:
0 Indicating normal termination of a read operation
9 Indicating a failure of a read operation
For Fifos I/O:
Decimal representing $JOB (identifier) of the process that wrote the
last message the current process read
$ZA refers to the status of the current device. Therefore, exercise
care in sequencing USE commands and references to $ZA.
GT.M does not permit the SET command to modify $ZA.
For more information on $ZA, refer to the "Input/Output Processing"
chapter in GT.M Programmer's Guide.
2 $ZB
$ZB
$ZB contains a string specifying the input terminator for the last
terminal READ. $ZB contains null and is not maintained for devices
other than terminals. $ZB may contain any legal input terminator, such
as <CR> (ASCII 13) or an escape sequence starting with <ESC> (ASCII
27), from zero (0) to 15 bytes in length. $ZB contains null for any
READ terminated by a timeout or any fixed-length READ terminated by
input reaching the maximum length.
$ZB contains the actual character string, not a sequence of numeric
ASCII codes.
Example:
SET zb=$ZB FOR i=1:1:$L(zb) WRITE !,i,?5,$A(zb,i)
This displays the series of ASCII codes for the characters in $ZB.
$ZB refers to the last READ terminator of the current device.
Therefore, exercise care in sequencing USE commands and references to
$ZB.
GT.M does not permit the SET command to modify $ZB.
For more information on $ZB, refer to the "Input/Output Processing"
chapter in GT.M Programmer's Guide.
2 $ZCMdline
$ZCMdline
$ZCM[DLINE] contains a string value specifying the "excess" portion of
the command line that invoked the GT.M process. By "excess" is meant
the portion of the command line that is left after GT.M has done all of
its command line processing. For example, a command line mumps -direct
extra1 extra2 causes GT.M to process the command line upto mumps
-direct and place the "excess" of the command line, that is "extra1
extra2" in $ZCMDLINE. $ZCMDLINE gives the M routine access to the shell
command line input.
Note that the actual user input command line might have been
transformed by the shell (for example, removing one level of quotes,
filename, and wildcard substituion, and so on.), and it is this
transformed command line that GT.M processes.
M routines cannot modify $ZCMDLINE.
Example:
$ cat > test.m
write " $ZCMDLINE=",$ZCMDLINE,!
quit
$ mumps -run test OTHER information
$ZCMDLINE=OTHER information
$
This creates the program test.m, which writes the value of $ZCMDLINE.
Note how the two spaces specified in OTHER information in the command
line gets transformed to just one space in OTHER information in
$ZCMDLINE due to the shell's pre-processing.
2 $ZCOmpile
$ZCOmpile
$ZCO[MPILE] contains a string value composed of one or more qualifiers
that control the GT.M compiler. Explicit ZLINKs and auto-ZLINKs use
these qualifiers as defaults for any compilations that they perform.
$ZCOMPILE is a read-write ISV, that is, it can appear on the left side
of the equal sign (=) in the argument to the SET command. A $ZCOMPILE
value has the form of a list of M command qualifiers each separated by
a space ( ).
When the environment variable gtmcompile is defined, GT.M initializes
$ZCOMPILE to the translation of gtmcompile. Otherwise GT.M initializes
$ZCOMPILE to null. Changes to the value of $ZCOMPILE during a GT.M
invocation only last for the current invocation and do not change the
value of the environment variable gtmcompile.
When $ZCOMPILE is null, GT.M uses the default M command qualifiers
-IGNORE, -LABEL=LOWER, -NOLIST, and -OBJECT. Refer to the "Program
Development Cycle" chapter in this manual for detailed descriptions of
the M command qualifiers.
Example:
$ setenv gtmcompile "-LIST -LENGTH=56 -SPACE=2"
$ gtm
GTM>WRITE $ZCOMPILE
-LIST -LENGTH=56 -SPACE=2
GTM>SET $ZCOMPILE="-LIST -NOIGNORE"
GTM>WRITE $ZCOMPILE
-LIST -NOIGNORE
GTM>ZLINK "A.m"
GTM>HALT
$ echo $gtmcompile
-LIST -LENGTH=56 -SPACE=2
This example uses the environment variable gtmcompile to set up
$ZCOMPILE. Then it modifies $ZCOMPILE with the SET command. The ZLINK
argument specifies a file with a .m extension (type), which forces a
compile. The compile produces a listing for routine A.m and does not
produce an object module if A.m contains compilation errors. After GT.M
terminates, the shell command echo $gtmcompile demonstrates that the
SET command did not change the environment variable.
2 $ZCstatus
$ZCstatus
$ZC[STATUS] holds the value of the status code for the last compilation
performed by a ZCOMPILE command.
GT.M does not permit the SET command to modify $ZSTATUS.
2 $ZDAteform
$ZDAteform
$ZDA[TEFORM] contains an integer value, specifying the output year
format of $ZDATE(). $ZDATEFORM can be modified using the SET command.
GT.M initializes $ZDATEFORM to the translation of the environment
variable gtm_zdate_form. If gtm_zdate_form is not defined, GT.M
initializes $ZDATEFORM to zero (0).
Refer to "Functions" and "M utility Routines" chapter in GT.M
Programmer's Guide for more details.
Example:
GTM>WRITE $ZDATEFROM
0
GTM>WRITE $ZDATE($H)
11/15/02
GTM>SET $ZDATEFORM=1
GTM>WRITE $ZDATE($H)
11/15/2002
2 $ZDirectory
$ZDirectory
$ZD[IRECTORY] contains the string value of the full path of the current
directory. Initially $ZDIRECTORY contains the default/current directory
from which the GT.M image/process was activated.
If the current directory does not exist at the time of GT.M process
activation, GT.M errors out.
Example:
GTM>WRITE $ZDIR
/usr/tmp
GTM>SET $ZDIR=".."
GTM>WRITE $ZDIR
/usr
This example displays the current working directory and changes $ZDIR
to the parent directory.
$ZDIRECTORY is a read-write Intrinsic Special Variable, that is, it can
appear on the left side of the equal sign (=) in the argument to a SET
command. If an attempt is made to set $ZDIRECTORY to a non-existent
directory specification, GT.M issues an error and keeps the value of
$ZDIRECTORY unchanged.
At image exit, GT.M restores the current directory to the directory
that was the current directory when GT.M was invoked even if that
directory does not exist.
2 $ZEDit
$ZEDit
$ZED[IT] holds the value of the status code for the last edit session
invoked by a ZEDIT command.
GT.M does not permit the SET or NEW command to modify $ZEDIT.
2 $ZEOf
$ZEOf
$ZEO[F] contains a truth-valued expression indicating whether the last
READ operation reached the end-of-file. $ZEOF equals TRUE (1) at EOF
and FALSE (0) at other positions.
GT.M does not maintain $ZEOF for terminal devices.
$ZEOF refers to the end-of-file status of the current device.
Therefore, exercise care in sequencing USE commands and references to
$ZEOF.
GT.M does not permit the SET or NEW command to modify $ZEOF.
For more information on $ZEOF, refer to the "Input/Output Processing"
chapter.
2 $ZError
$ZError
$ZE[RROR] is supposed to hold the application-specific error-code
corresponding to the GT.M error-code stored in $ECODE/$ZSTATUS (refer
to their description in this chapter).
$ZERROR contains a default value of "Unprocessed $ZERROR, see $ZSTATUS"
at process startup.
$ZERROR can be SET but not NEWed.
The mapping of a GT.M error-code to the application-specific error-code
is achieved as follows. Whenever GT.M encounters an error,
$ECODE/$ZSTATUS gets set first. It then invokes the code that $ZYERROR
(see description later in this chapter) points to if it is not null. It
is intended that the code invoked by $ZYERROR use the value of $ZSTATUS
to select or construct a value to which it SETs $ZERROR. If an error is
encountered by the attempt to execute the code specified in $ZYERROR,
GT.M sets $ZERROR to the error status encountered. If $ZYERROR is null,
GT.M does not change the value of $ZERROR. In all cases, GT.M proceeds
to return control to the code specified by $ZTRAP/$ETRAP or device
EXCEPTION whichever is applicable.
2 $ZGbldir
$ZGbldir
$ZG[BLDIR] contains the value of the current Global Directory filename.
When $ZGBLDIR specifies an invalid or inaccessible file, GT.M cannot
successfully perform database operations.
GT.M initializes $ZGBLDIR to the translation of the environment
variable gtmgbldir. If gtmgbldir is not defined, GT.M initializes
$ZGBLDIR to null. When $ZGBLDIR is null, GT.M constructs a file name
for the Global Directory using the name gtmgbldir and the extension
.gld in the current working directory. A $ZGBLDIR value may include an
environment variable.
$ZGBLDIR is a read-write Intrinsic Special Variable, (i.e., it can
appear on the left side of the equal sign (=) in the argument to the
SET command). SET $ZGBLDIR="" causes GT.M to assign $ZGBLDIR to the
translation of gtmgbldir if that environment variable is defined. If it
is not defined, then SET $ZGBLDIR="" causes GT.M to assign the string
gtmgbldir to $ZGBLDIR. This syntax specifies the file gtmgbldir.gld in
the current directory. GT.M permits $ZGBLDIR to be NEW'd.
SETting $ZGBLDIR also causes GT.M to attempt to open the specified
file. If the file name is invalid or the file is inaccessible, GT.M
triggers an error without changing the value of $ZGBLDIR.
To establish a value for $ZGBLDIR outside of M, use the appropriate
shell command to assign a translation to gtmgbldir. Defining gtmgbldir
provides a convenient way to use the same Global Directory during a
session where you repeatedly invoke and leave GT.M.
Changes to the value of $ZGBLDIR during a GT.M invocation only last for
the current invocation and do not change the value of gtmgbldir.
Example:
$ gtmgbldir=test.gld
$ export gtmgbldir
$ gtm
GTM> WRITE $zgbldir
/usr/dev/test.gld
GTM> SET $zgbldir="mumps.gld"
GTM> WRITE $zgbldir
mumps.gld
GTM> HALT
$ echo $gtmgbldir
test.gld
This example defines the environment variable gtmgbldir. Upon entering
GT.M Direct Mode, $ZGBLDIR has the value supplied by gtmgbldir. The SET
command changes the value. After the GT.M image terminates, the echo
command demonstrates that gtmgbldir was not modified by the M SET
command.
Example:
$ ls test.gld
test.gld not found
$ gtm
GTM> WRITE $zgbldir
/usr/dev/mumps.gld
GTM> set $zgbldir="test.gld"
%GTM-E-ZGBLDIRACC, Cannot access global directory
"/usr/dev/test.gld". Continuing with
/usr/dev/mumps.gld"
%SYSTEM-E-ENO2, No such file or directory
GTM> WRITE $zgbldir
/usr/dev/mumps.gld
GTM> halt
$
The SET command attempts to change the value of $ZGBLDIR to test.gld.
Because the file does not exist, GT.M reports an error and does not
change the value of $ZGBLDIR.
Attempting to restore an inaccessible initial Global Directory that
has been NEW'd, can cause an error.
2 $ZINTerrupt
$ZINTerrupt
$ZINT[ERRUPT] specifies the code to be XECUTE'd when an interrupt (for
example, through a MUPIP INTRPT) is processed. While a $ZINTERRUPT
action is in process, any additional interrupt signals are discarded.
When an interrupt handler is invoked, the current values of $REFERENCE
is saved and restored when the interrupt handler returns. The current
device ($IO) is neither saved nor restored.
GT.M permits the SET command to modify the value of $ZINTERRUPT.
If an interrupt handler changes the current IO device (via USE), it is
the responsibility of the interrupt handler to restore the current IO
device before returning. There are sufficient legitimate possibilities
why an interrupt routine would want to change the current IO device
(for example; daily log switching), that this part of the process
context is not saved and restored automatically.
The initial value for $ZINTERRUPT is taken from the UNIX environment
variable gtm_zinterrupt if it is specified, otherwise it defaults to
the following string:
IF $ZJOBEXAM()
The IF statement executes the $ZJOBEXAM function but effectively
discards the return value.
If the default value for $ZINTERRUPT is modified, no $ZJOBEXAM()
will occur unless the replacement value directly or indirectly
invokes that function. In other words, while $ZJOBEXAM() is part of
the interrupt handling by default, it is not an implicit part of
the interrupt handling.
3 Inter_Handl_GTM
Interrupt Handling in GT.M
The interrupt handler is executed by GT.M when on a statement boundary
or on an appropriate boundary in a potentially long running COMMAND (in
the same place as <CTRL>-C is recognized). If a GT.M process is in a
long running external call (for example; waiting in a message queue)
the interrupt handler cannot be driven immediately. The interrupt
request is recognized and the handler is driven after the external call
returns to GT.M and an appropriate execution boundary is reached.
Since sending an interrupt signal requires the sender to have
appropriate permissions from UNIX, the use of the interrupt facility
itself does not present any inherent security exposures. Nonetheless,
because the dump files created by the default action contain the values
of every local variable in the context at the time they are made,
inappropriate access to the dump files would constitute a security
exposure. Make sure the design and implementation of any interrupt
logic includes careful consideration to security issues.
If an error occurs while compiling the $ZINTERRUPT code, the action
taken depends on the process state at the time the interrupt was
received and the error handler is not invoked (the error handler is
invoked if an error occurs while executing the $ZINTERRUPT code). If
the GT.M process is at a direct mode prompt or is executing a direct
mode command (for example, a FOR loop), the error message is sent to
the user console along with the GTM-ERRWZINTR error (refer to the GT.M
Error and Message Recovery Manual). In addition, the GTM-ERRWZINTR
error is also sent to the operator log facility. IF the process is not
at a direct mode prompt or executing a direct mode command, the
GTM-ERRWZINTR message and the compiler error message are sent to the
operator log facility and nothing is displayed on the user's console.
In both cases, the interrupted process resumes execution.
If an error occurs during execution of the interrupt handler's stack
frame (before it calls anything), that error is prefixed with the
GTM-ERRWZINTR error. The error handler then executes normal error
processing associated with the module that was interrupted. Any other
errors that occur in code called by the interrupt handler are handled
by normal error handling.
The interrupt handler does not operate "outside" the current M
environment but rather within the environment of the process.
If a TP transaction is in progress (0<$TLEVEL), updates to globals are
not safe since a TP restart can be signaled at any time prior to the
transaction being committed - even after the interrupt handler returns.
A TP restart reverses all global updates and unwinds the M stack so it
is as if the interrupt never occurred. The interrupt handler is not
redriven as part of a transaction restart. Referencing (reading)
globals inside an interrupt handler can trigger a TP restart if a
transaction is active. When programming interrupt handling, either
discard interrupts when 0<$TLEVEL (forcing the interrupting party to
try again), or use local variables that are not restored by a TRESTART
to defer the interrupt action until after the final TCOMMIT.
Note that it is possible for the interrupt handler to be executed while
the process executing the M routine is holding the critical section for
one or more regions. Use of this feature may create temporary hangs or
pauses while the interrupt handler executes. For the default case where
the interrupt handler uses $ZJOBEXAM() to create a dump, the pause
duration depends on the number of local variables in the process at the
time of the dump and on the speed of the disk being written to. The
dumps are slower on a network-mounted disk than on a disk directly
connected to the local system. Any interrupt driven code should be
designed to account for this issue.
2 $ZINInterrupt
$ZINInterrupt
$ZINI[NTERRUPT] evaluates to 1 (TRUE) when a process is executing code
initiated by the interrupt mechanism, and otherwise 0 (FALSE).
GT.M does not permit the SET or NEW commands to modify $ZININTERRUPT.
2 $ZIO
$ZIO
$ZIO contains the translated name of the current device, in contrast to
$IO, which contains the name as specified by the USE command.
GT.M does not permit the SET or NEW command to modify $ZIO.
An example where $ZIO contains a value different from $IO is if the
environment variable gtm_principal is defined.
Example:
$ gtm_principal="foo"
$ export gtm_principal
GTM>WRITE $IO
foo
GTM>WRITE $ZIO
/dev/pts/8
Notice that $ZIO contains the actual terminal device name while $IO
contains the string pointed to by the environment variable
gtm_principal.
2 $ZJob
$ZJob
$ZJ[OB] holds the pid of the process created by the last JOB command
performed by the current process.
GT.M initializes $ZJOB to zero (0) at process startup. If the JOB
command fails to spawn a new job, GT.M sets $ZJOB to zero (0). Note
that because of the left to right evaluation order of M, using $ZJOB in
the jobparameter string results in using the value created by the last,
rather than the current JOB command, which is not likely to match
common coding practice.
GT.M does not permit the SET or NEW command to modify $ZJOB.
2 $ZLevel
$ZLevel
$ZL[EVEL] contains an integer value indicating the "level of nesting"
caused by DO commands, XECUTE commands, and extrinsic functions in the
M invocation stack.
$ZLEVEL has an initial value of one (1) and increments by one with each
DO, XECUTE or extrinsic function. Any QUIT that does not terminate a
FOR loop decrements $ZLEVEL. ZGOTO may also reduce $ZLEVEL. In
accordance with the M standard, a FOR command does not increase
$ZLEVEL. M routines cannot modify $ZLEVEL with the SET or NEW commands.
Use $ZLEVEL in debugging or in an error-handling mechanism to capture a
level for later use in a ZGOTO argument.
Example:
GTM>ZPRINT ^ZLEV
A DO B
WRITE X,!
QUIT
B GOTO C
QUIT
C DO D
QUIT
D SET X=$ZLEVEL
QUIT
GTM>DO ^ZLEV
4
This program, executed from Direct Mode, produces a value of 4 for
$ZLEVEL. If you run this program from the shell, the value of $ZLEVEL
is three (3).
2 $ZMAXTPTIme
$ZMAXTPTIme
$ZMAXTPTI[ME] contains an integer value indicating the time duration
GT.M should wait for the completion of all activities fenced by the
current transaction's outermost TSTART/TCOMMIT pair.
$ZMAXTPTIME can be SET but cannot be NEWed.
The initial value of $ZMAXTPTIME is zero (0) seconds, which indicates
"no timeout" (unlimited time). The value of $ZMAXTPTIME when a
transaction's outermost TSTART operation executes determines the
timeout setting for that transaction.
When a $ZMAXTPTIME expires, GT.M executes the $ETRAP/$ZTRAP exception
handler currently in effect.
Negative values of $ZMAXTPTIME are also treated as "no timeout".
Timeouts apply only to the outermost transaction, that is,
$ZMAXTPTIME has no effect when TSTART is nested within another
transaction.
Example:
Test ;testing TP timeouts
set $ZMAXTPTIME=6,^X=0,^Y=0,^Z=0
write "Start with $ZMAXTPTIME=",$ZMAXTPTIME,":",!
for sleep=3:2:9 do
. set retlvl=$zl
. do longtran ;ztrap on longtran
;continues execution
;on next line
. write "(^X,^Y)=(",^X,",",^Y,")",!
write !,"Done TP Timeout test.",!
quit
longtran ;I/O in TP doesn't get rolled back
set newzt="set $ZT="""" ";avoid recursive ZTRAP
set $ZT=newzt_" goto err"
tstart ():serial ;plain tstart works as well
set ^X=1+^X
write !,"^X=",^X,",will set ^Y to ",sleep
write " in ",sleep," seconds..."
hang sleep
set ^Y=sleep
write "^Y=",^Y
tcommit
write "...committed.",!
quit
err ;
set $ZT=""
write !,"In $ZTRAP handler. Error was: "
write !," ",$zstatus
if $TLEVEL do ;test allows handler use outside of TP
. trollback
. write "Rolled back transaction."
write !
zgoto retlvl
Results:
Start with $ZMAXTPTIME=6:
^X=1,will set ^Y to 3 in 3 seconds...^Y=3...committed.
^X=2,will set ^Y to 5 in 5 seconds...^Y=5...committed.
^X=3,will set ^Y to 7 in 7 seconds...
In $ZTRAP handler. Error was:
150377322,longtran+7^tptime,%GTM-E-TPTIMEOUT, Transaction timeoutRolled
back transaction.
^X=3,will set ^Y to 9 in 9 seconds...
In $ZTRAP handler. Error was:
150377322,longtran+7^tptime,%GTM-E-TPTIMEOUT, Transaction timeoutRolled
back transaction.
Done TP Timeout test.
2 $ZMOde
$ZMOde
$ZMO[DE] contains a string value indicating the process execution mode.
The mode can be:
o INTERACTIVE
o OTHER
M routines cannot modify $ZMODE.
Example:
GTM> WRITE $ZMODE
INTERACTIVE
This displays the process mode.
2 $ZPOSition
$ZPOSition
$ZPOS[ITION] contains a string value specifying the current entryref,
where entryref is [label][+offset]^routine, and the offset is evaluated
from the closest preceding label.
GT.M does not permit the SET or NEW commands to modify $ZPOSITION.
Example:
GTM>WRITE !,$ZPOS,! ZPRINT @$ZPOS
This example displays the current location followed by the source code
for that line.
2 $ZPROMpt
$ZPROMpt
$ZPROM[PT] contains a string value specifying the current Direct Mode
prompt. By default, GTM> is the Direct Mode prompt. M routines can
modify $ZPROMPT by means of a SET command. $ZPROMPT cannot exceed 16
characters. If an attempt is made to assign $ZPROMPT to a longer
string, only the first 16 characters will be taken.
Example:
GTM>SET $ZPROMPT="NEWZPROMPT>"
NEWZPROMPT>
This example changes the GT.M prompt to be NEWZPROMPT
2 $ZROutines
$ZROutines
$ZRO[UTINES] contains a string value specifying a directory or list of
directories containing object files. Each object directory may also
have an associated directory, or list of directories, containing the
corresponding source files. These directory lists are used by certain
GT.M functions, primarily auto-ZLINK, to locate object and source
files. The order in which directories appear in a given list determines
the order in which they are searched for the appropriate item.
Searches that use $ZROUTINES treat files as either object or source
files. GT.M treats files with an extension of .o as object files and
files with an extension of .m as source files.
Paths used in $ZROUTINES to locate routines must not include
embedded spaces, as $ZROUTINES uses spaces as delimiters.
3 Est_Val_frm_gtmroutines
Establishing the Value from gtmroutines
When the environment variable gtmroutines is defined, GT.M initializes
$ZROUTINES to the value of gtmroutines. Otherwise, GT.M initializes
$ZROUTINES to a null value. When $ZROUTINES is null, GT.M attempts to
locate all source and object files in the current working directory.
$ZROUTINES="" is equivalent to $ZROUTINES=".".
Commands or functions such as DO, GOTO, ZGOTO, ZBREAK, ZPRINT, and
$TEXT may auto-ZLINK and thereby indirectly use $ZROUTINES. If their
argument does not specify a directory, ZEDIT and explicit ZLINK use
$ZROUTINES. ZPRINT and $TEXT use $ZROUTINES to locate a source file if
GT.M cannot find the source file pointed to by the object file. For
more information on ZLINK and auto-ZLINK, refer to the "Program
Development Cycle" and "Commands" chapters in GT.M Programmer's Guide.
3 Set_Val_for_$ZRO
Setting a Value for $ZROUTINES
$ZRO[UTINES] is a read-write Intrinsic Special Variable, so M can also
SET the value.
By default, each directory entry in $ZROUTINES is assumed to contain
both object and source files. However, each object directory may have
an associated directory or list of directories to search for the
corresponding source files. This is done by specifying the source
directory list, in parentheses, following the object directory
specification.
If the command specifies more than one source directory for an object
directory, the source directories must be separated by spaces, and the
entire list must be enclosed in parentheses ( ) following the object
directory-specification. If the object directory should also be
searched for source, the name of that directory must be included in the
parentheses, (usually as the first element in the list).
Directory-specifications may also include empty parentheses, directing
GT.M to proceed as if no source files exist for objects located in the
qualified directory.
To set $ZROUTINES outside of M, use the appropriate shell command to
set gtmroutines. Because gtmroutines is a list, enclose the value in
quotation marks (" ").
Changes to the value of $ZROUTINES during a GT.M invocation only last
for the current invocation, and do not change the value of gtmroutines.
Directory specifications may include an environment variable. When GT.M
SETs $ZROUTINES, it translates all environment variables and verifies
the syntax and the existence of all specified directories. If
$ZROUTINES is set to an invalid value, GT.M generates a run-time error
and does not change the value of $ZROUTINES. Because the environment
variables are translated when $ZROUTINES is set, any changes to their
definition have no effect until $ZROUTINES is set again.
3 $ZRO_Examples
$ZROUTINES Examples
Example:
GTM> s $zroutines=".(../src) $gtm_dist"
This example directs GTM to look for object modules first in your
current directory, then in the distribution directory that contains the
percent routines. GT.M locates sources for objects in your current
directory in the sibling /src directory.
Example:
$ gtmroutines="/usr/jones /usr/smith"
$ export gtmroutines
$ gtm
GTM> write $zroutines
"/usr/jones /usr/smith"
GTM> set $zro="/usr/jones/utl /usr/smith/utl"
GTM> write $zroutines
"/usr/jones/utl /usr/smith/utl"
GTM> halt
$ echo $gtmroutines
/usr/jones /usr/smith
This example defines the environment variable gtmroutines. Upon
entering GT.M Direct Mode $zroutines has the value supplied by
gtmroutines. The SET command changes the value. When the GT.M image
terminates, the shell echo command demonstrates that gtmroutines has
not been modified by the M SET command.
Example:
GTM> SET $ZRO=". /usr/smith"
This example sets $zroutines to a list containing two directories.
Example:
GTM> set $zro="/usr/smith(/usr/smith/tax /usr/smith/fica)"
This example specifies that GT.M should search the directory /usr/smith
for object files, and the directories /usr/smith/tax and
/usr/smith/fica for source files. Note that in this example. GT.M does
not search /usr/smith for source files.
Example:
GTM> set $zro="/usr/smith(/usr/smith /usr/smith/tax /usr/smith/fica)"
This example specifies that GT.M should search the directory /usr/smith
for object files and the directories /usr/smith/tax and /usr/smith/fica
for source files. Note that the difference between this example and the
previous one is that GT.M searches /usr/smith for both object and
source files.
Example:
GTM> set $zro="/usr/smith /usr/smith/tax()
/usr/smith/fica"
This specifies that GT.M should search /usr/smith and /usr/smith/fica
for object and source files. However, because the empty parentheses
indicate directories searched only for object files, GT.M does not
search /usr/smith/tax for source files.
Omitting the parentheses indicates that GT.M can search the directory
for both source and object files. $ZROUTINES=/usr/smith is equivalent
to $ZROUTINES=/usr/smith(/usr/smith).
3 $ZRO_Search_Types
$ZROUTINES Search Types
GT.M uses $ZRO[UTINES] to perform three types of searches:
o Object-only when the command or function using $ZROUTINES requires
a .o file extension.
o Source-only when the command or function using $ZROUTINES requires
a file extension other than .o.
o Object-source match when the command or function using $ZROUTINES
does not specify a file extension.
An explicit ZLINK that specifies a non .o extension is considered as a
function that has not specified a file extension for the above
searching purposes.
All searches proceed from left to right through $ZROUTINES. By default,
GT.M searches directories for both source and object files. GT.M
searches directories followed by empty parentheses ( ) for object files
only. GT.M searches directories in parentheses only for source files.
Once an object-matching search locates an object file, the source
search becomes limited. If the directory containing the object file has
an attached parenthetical list of directories, GT.M only searches the
directories in the attached list for matching source files. If the
directory containing the object files does not have following
parentheses, GT.M restricts the search for matching source files to the
same directory. If the object module is in a directory qualified by
empty parentheses, GT.M cannot perform any operation that refers to the
source file.
3 $ZRO_Search_Ex
$ZROUTINES Search Examples
This section describes a model for understanding $ZROUTINES operations
and the illustrating examples, which may assist you if you wish to
examine the topic closely.
You may think of $ZROUTINES as supplying a two dimensional matrix of
places to look for files. The matrix has one or more rows. The first
row in the matrix contains places to look for object and the second and
following rows contain places to look for source. Each column
represents the set of places that contain information related to the
object modules in the first row of the column.
Example:
GTM> s $zro=". /usr/smi/utl() /usr/jon/utl
(/usr/jon/utl/so /usr/smi/utl)"
3 Sh_Lib_FileSpec_in_$ZRO
Shared Library File Specification in $ZROUTINES
The $ZROUTINES ISV allows individual UNIX shared library file names to
be specified in the search path. During a search for auto-ZLINK, when a
shared library is encountered, it is probed for a given routine and, if
found, that routine is linked/loaded into the image. During an explicit
ZLINK, all shared libraries in $ZROUTINES are ignored and are not
searched for a given routine.
Currently GT.M supports this feature on Tru64 operating system, and
plans to support other UNIX operating system in near future.
$ZROUTINES syntax contains a file-specification indicating shared
library file path. GT.M does not require any designated extension for
the shared library component of $ZROUTINES. Any file specification that
does not name a directory is treated as shared library. However, it is
recommended that the extension commonly used on a given platform for
shared library files be given to any GT.M shared libraries. (Refer to
the following section on "Linking GT.M Shared Images"). A shared
library component cannot specify source directories. GT.M reports an
error at an attempt to associate any source directory with a shared
library in $ZROUTINES.
The following traits of $ZROUTINES help support shared libraries:
o The $ZROUTINES search continues to find objects in the first place,
processing from left to right, that holds a copy; it ignores any
copies in subsequent locations. However, now for auto-ZLINK, shared
libraries are accepted as object repositories with the same ability
to supply objects as directories.
o Explicit ZLINK, never searches Shared Libraries. This is because
explicit ZLINK is used to link a newly created routine or re-link a
modified routine and there is no mechanism to load new objects into
an active shared library.
o ZPRINT and $TEXT() of the routines in a shared library, read source
file path from the header of the loaded routine. If the image does
not contain the routine, an auto-ZLINK is initiated. If the source
file path recorded in the routine header when the module was
compiled cannot be located, ZPRINT and $TEXT() initiate a search
from the beginning of $ZROUTINES, skipping over the shared library
file specifications. If the located source does not match the code
in image (checked via checksum), ZPRINT generates an object-source
mismatch status and $TEXT() returns a null string.
o ZEDIT, when searching $ZROUTINES, skips shared libraries like
explicit ZLINK for the same reasons. $ZSOURCE ISV is implicitly set
to the appropriate source file.
For example, if libshare.so is built with foo.o compiled from
./shrsrc/foo.m, the following commands specify that GT.M should search
the library ./libshare.so for symbol foo when do ^foo is encountered.
GTM>SET $ZROUTINES="./libshare.so ./obj(./shrsrc)"
GTM>DO ^foo ;auto-ZLINK foo - shared
GTM>ZEDIT "foo" ;edit ./shrsrc/foo.m
GTM>W $ZSOURCE,! ;prints foo
GTM>ZPRINT +0^foo ;issues a source-object mismatch status TXTSRCMAT
error message
GTM>ZLINK "foo" ;re-compile ./shrsrc/foo.m to generate ./obj/foo.o.
GTM>W $TEXT(+0^foo) ;prints foo
Note that ZPRINT reports an error, as foo.m does not match the routine
already linked into image. Also note that, to recompile and re-link the
ZEDITed foo.m, its source directory needs to be attached to the object
directory [./obj] in $ZROUTINES. The example assumes the shared library
(libshare.so) has been built using shell commands. The procedure to
build a shared library from a list of GT.M generated object (.o) files
is detailed in the following section on "Linking GT.M Shared Images".
4 Link_GTM_Sh_Image
Linking GT.M Shared Images
Following are the steps (UNIX system commands, and GT.M commands) that
need to be taken to use GT.M shared image linking with $ZROUTINES.
5 Comp_SrcFile_to_ObjFile
Compile Source (.m) Files to Object (.o) Files
In order to share M routines, GT.M generates objects (.o) with position
independent code, a primary requirement for shared libraries. All
objects must be generated by a release of GT.M that supports shared
binaries linking.
5 Creat_ShLib_from_ObjFile
Create a Shared Library from Object (.o) Files
On each UNIX platform, the native linker ld provides command line
options to create a shared library from a list of .o files. The
specific ld options vary depending on the platform.
Although GT.M does not require a specific file extension for shared
libraries, it is recommended that the conventional extension (.so on
Tru64) be used on a given platform. For example, the following Tru64
linker command
$ ld -shared -taso -o libabc.so a.o b.o c.o -lc
creates a shared library libabc.so from GT.M object files a.o, b.o and
c.o. The flag -taso directs the linker to generate 32-bit addressable
Shared Library. Without this option, Tru64 UNIX ld generates a 64-bit
addressable shared library by default. Even though GT.M can
successfully load 64-bit shared library, Sanchez recommends the use of
the -taso option for best compatibility with the GT.M memory model.
Notes on Tru64 UNIX linker:
o The linker (ld) may have a limit on the number of object files that
it can accept on the command line. If ld fails to read all objects
from the command line, users are recommended to use -input to
specify a text file <command-file> that contains all object files
as if they were specified on the command line.
o When creating a shared library, Sanchez suggests linking with the C
library (-lc at the end of link line) to prevent ld from reporting
various undefined-symbol warnings. These undefines are not relevant
to the use of the GT.M shared library routines but linking with the
C library eliminates the linker warning messages.
o See ld manual pages (UNIX shell command - man ld) for more details
of linker options.
5 Est_$ZRO_frm_gtmroutines
Establish $ZROUTINES from gtmroutines
When the UNIX environment variable gtmroutines is defined, GT.M
initializes $ZROUTINES to the value of gtmroutines. The $ZROUTINES ISV
can also be modified using SET command.
Example:
$ gtmroutines="./libabc.so ./obj(./src)"
$ export gtmroutines
$ mumps -direct
GTM>write $ZROUTINES,! ;writes "./libabc.so ./obj(./src)"
GTM> do ^a ;runs ^a from libabc.so
GTM> do ^b ;runs ^b from libabc.so
GTM> do ^c ;runs ^c from libabc.so
GTM> halt
$
2 $ZSOurce
$ZSOurce
$ZSO[URCE] contains a string value specifying the default pathname for
the ZEDIT and ZLINK commands. ZEDIT or ZLINK without an argument is
equivalent to ZEDIT/ZLINK $ZSOURCE.
$ZSOURCE initially contains the null string. When ZEDIT and ZLINK
commands have a pathname for an argument, they implicitly set $ZSOURCE
to that argument. This ZEDIT/ZLINK argument can include a full pathname
or a relative one. A relative path could include a file in the current
directory, or the path to the file from the current working directory.
In the latter instance, do not include the slash before the first
directory name. $ZSOURCE will prefix the path to the current working
directory including that slash.
The file name may contain a file extension. If the extension is .m or
.o, $ZSOURCE drops it. The ZEDIT command accepts arguments with
extensions other than .m or .o. $ZSOURCE retains the extension when
such arguments are passed.
If $ZSOURCE contains a file with an extension other than .m or .o,
ZEDIT processes it but ZLINK returns an error message
$ZSOURCE is a read-write Intrinsic Special Variable, (i.e., it can
appear on the left side of the equal sign (=) in the argument to the
SET command). A $ZSOURCE value may include an environment variable.
Example:
GTM> ZEDIT "subr.m"
.
.
GTM> WRITE $ZSOURCE
subr
Example:
GTM> ZEDIT "test"
.
.
.
GTM> WRITE $ZSOURCE
test
Example:
GTM> ZEDIT "/usr/smith/report.txt"
.
.
.
GTM> WRITE $ZSOURCE
/usr/smith/report.txt
Example:
GTM> ZLINK "BASE.O"
.
.
.
GTM> WRITE $ZSOURCE
BASE
2 $ZStatus
$ZStatus
$ZS[TATUS] contains a string value specifying the error condition code
and location of the last exception condition that occurred during
routine execution.
GT.M maintains $ZSTATUS as a string consisting of three or more
substrings. The string consists of the following:
o An error message number as the first substring.
o The entryref of the line in error as the second substring; a comma
(,) separates the first and second substrings.
o The message detail as the third substring. The format of this is a
percent sign (%) identifying the message facility, a hyphen (-)
identifying the error severity, another hyphen identifying the
message identification followed by a comma (,), which is followed
by the message text if any:
Format: %<FAC>-<SEV>-<ID>, <TEXT>
Example: %GTM-E-DIVZERO, Attempt to divide by zero
GT.M sets $ZSTATUS when it encounters errors during program execution,
but not when it encounters errors in a Direct Mode command.
$ZSTATUS is a read-write Intrinsic Special Variable, (i.e., it can
occur on the left side of the equal sign (=) in the argument to the SET
command). While it will accept any string, Sanchez Computer Associates
recommends setting it to null. M routines cannot modify $ZSTATUS with
the NEW command.
Example:
GTM> WRITE $ZSTATUS
150373110,+1^MYFILE,%GTM-E-DIVZERO,
Attempt to divide by zero
This example displays the status generated by a divide by zero (0).
2 $ZSTep
$ZSTep
$ZST[EP] contains a string value specifying the default action for the
ZSTEP command. $ZSTEP provides the ZSTEP action only when the ZSTEP
command does not specify an action.
$ZSTEP initially contains the string "B" to enter direct mode. $ZSTEP
is a read-write Intrinsic Special Variable, (i.e., it can appear on the
left side of the equal sign (=) in the argument to the SET command).
Example:
GTM> WRITE $ZSTEP
B
GTM>
This example displays the current value of $ZSTEP, which is the
default.
Example:
GTM> SET $ZSTEP="ZP @$ZPOS B"
This example sets $ZSTEP to code that displays the contents of the next
line to execute, and then enters Direct Mode.
2 $ZSYstem
$ZSYstem
$ZSY[STEM] holds the value of the status code for the last subprocess
invoked with the ZSYSTEM command.
2 $ZTExit
$ZTExit
$ZTE[XIT] contains a string value that controls the GT.M interrupt
facility at the transaction commit or rollback. At each outermost
TCOMMIT or TROLLBACK, If +$ZTEXIT evaluates to non-zero (TRUE), then
$ZINTERRUPT is XECUTEd after completing the commit or rollback.
$ZTEXIT is a read-write ISV, that is, it can appear on the left side of
the equal sign (=) in the argument to the SET command. M routines
cannot NEW $ZTEXIT. GT.M initializes $ZTEXIT to null at the process
startup. Note that the changes to the value of $ZTEXIT during a GT.M
invocation last for the entire duration of the process, so it is the
application’s responsibility to reset $ZTEXIT after $ZINTERRUPT is
delivered in order to turn off redelivering the interrupt each every
subsequent transaction commit or rollback.
Example:
ztran.m
foo ;
set $ztexit=1
set $zinterrupt="d ^throwint"
tstart ()
for i=1:1:10 do
. set ^ACN(i,"bal")=i*100
tstart ()
do ^throwint
do ^proc
tcommit:$tlevel=2
for i=1:1:10 do
. set ^ACN(i,"int")=i*0.05
do ^srv
if $tlevel trollback
do ^exc
set $zte="",$zint=""
quit
bar ;
write "Begin Transaction",!
set $zte=1
tstart ()
i '$zsigproc($j,$ztrnlnm("sigusrval")) w "interrupt sent...",!!
for i=1:1:4 set ^B(i)=i*i
tcommit
write "End Transaction",!
do ^srv
quit
throwint.m
thrint
set $zint="write !,""interrupt occurred at :
"",$stack($stack-1,""PLACE""),! set $zte=1"
if '$zsigproc($j,$ztrnlnm("sigusrval")) write "interrupt sent to
process"
write "***************************************",!!
quit
Example:
GTM>d foo^ztran
interrupt sent to process
interrupt occurred at : thrint+3^throwint
***************************************
interrupt occurred at : foo+13^ztran
GTM>
In the above call to foo^ztran, the interrupt handler is a user-defined
routine, throwint. The process is sent a signal (SIGUSR1), and
$ZINTERRUPT is executed. At the outermost trollback, the interrupt is
rethrown, causing $ZINTERRUPT to be executed again.
Example:
GTM>w $zint
IF $ZJOBEXAM()
GTM>zsy "ls GTM*"
ls: No match.
GTM>d bar^ztran
Begin Transaction
interrupt sent...
End Transaction
GTM>zsy "ls GTM*"
GTM_JOBEXAM.ZSHOW_DMP_22551_1 GTM_JOBEXAM.ZSHOW_DMP_22551_2
GTM>
This uses the default value of $ZINTERRUPT to service interrupts issued
to the process. The $ZJOBEXAM function executes a ZSHOW "*", and stores
the output in each GTM_ZJOBEXAM_ZSHOW_DMP for the initial interrupt,
and at tcommit when the interrupt is rethrown.
2 $ZTrap
$ZTrap
$ZT[RAP] contains a string value that GT.M XECUTEs when an error occurs
during routine execution.
The following discussion assumes that $ETRAP error handling is
simultaneously not in effect (that is, $ETRAP="").
When the $ZTRAP variable is not null, GT.M executes $ZTRAP at the
current level. The $ZTRAP variable has the initial value of "B," and
puts the process in Direct Mode when an error condition occurs. If the
value of $ZTRAP is null (""), an exception causes the image to run-down
with the condition code associated with the exception. If $ZTRAP
contains invalid source code, GT.M displays an error message and puts
the process into Direct Mode.
$ZTRAP is a read-write Intrinsic Special Variable, (i.e., it can appear
on the left side of the equal sign (=) in the argument to the SET
command).
$ZTRAP may also appear as an argument to an inclusive NEW command. NEW
$ZTRAP causes GT.M to set $ZTRAP to null ($ZTRAP="") and to stack the
old value of $ZTRAP. When the program QUITs from the invocation level
where the NEW occurred, GT.M restores the value previously stacked by
the NEW. NEW $ZTRAP provides nesting of $ZTRAP. Because $ZTRAP=""
terminates the image when an error occurs, SET $ZTRAP= generally
follows immediately after NEW $ZTRAP. You may use this technique to
construct error handling strategies corresponding to the nesting of
your programs. If the environment variable gtm_ztrap_new evaluates to
boolean TRUE (case insensitive string "TRUE", or case insensitive
string "YES", or a non-zero number), $ZTRAP is NEWed when $ZTRAP is
SET; otherwise $ZTRAP is not stacked when it is SET.
QUIT from a $ZTRAP terminates the level at which the $ZTRAP was
activated.
Keep $ZTRAP simple and put complicated logic in another routine. If the
action specified by $ZTRAP results in another run-time error before
changing the value of $ZTRAP, GT.M invokes $ZTRAP until it exhausts the
process stack space, terminating the image. Carefully debug exception
handling.
Example:
GTM> S $ZTRAP="ZP @$ZPOS B"
This example modifies $ZTRAP to display source code for the line where
GT.M encounters an error before entering Direct Mode.
There are four accepted behavioural forms of $ZTRAP controlled by the
UNIX environment variable gtm_ztrap_form. If gtm_ztrap_form is defined
to "code" (or not defined to one of the subsequently described values),
then GT.M treats $ZTRAP as code and handles it as previously described
in the documentation.
The four different behavioural forms of gtm_ztrap_form are:
o entryref - If gtm_ztrap_form evaluates to "entryref" then GT.M
treats it as an entryref argument to an implicit GOTO command.
o adaptive - If gtm_ztrap_form evaluates to "adaptive" then if
$ZTRAP does not compile to valid M code, then $ZTRAP is treated as
just described for "entryref." Since there is little ambiguity,
code and entryref forms of $ZTRAP can be intermixed in the same
application.
Note that GT.M attempts to compile $ZTRAP before evaluating $ZTRAP as
an entryref. Since GT.M allows commands without arguments such as QUIT,
ZGOTO, or HANG as valid labels, be careful not to use such keywords as
labels for error handling code in "adaptive" mode.
o pope[ntryref] / popa[daptive] - If gtm_ztrap_form evaluates to
"POPE[NTRYREF]" or "POPA[DAPTIVE]" (case insensitive) and $ZTRAP
value is in the form of entryref, GT.M unwinds the M stack from the
level at which an error occurred to (but not including) the level
at which $ZTRAP was last SET. Then, GT.M transfers control to the
entryref in $ZTRAP at the level where the $ZTRAP value was SET. If
the UNIX environment variable gtm_zyerror is defined to a valid
entryref, GT.M transfers control to the entryref specified by
GTM_ZYERROR (with an implicit DO) after unwinding the stack and
before transferring control to the entyref specified in $ZTRAP.
2 $ZVersion
$ZVersion
$ZV[ERSION] contains a string value specifying the currently installed
GT.M. $ZV[ERSION] is a space-delimited string with four pieces
described below:
o The M product name, for example "GT.M".
o The M product version identifier; the format is: the capital letter
"V" followed by the major version number, then a period (.),
followed by the minor version number, then a patch number.
o The host operating system name and optional version identifier;
this identifier is only included if different versions of the OS
support different, compatible versions of the M product.
o The host hardware designation and optional chipset identifier; this
identifier is only included if different versions of the hardware
support different compatible versions of the M product.
M routines cannot modify $ZVERSION.
Example:
GTM> WRITE $ZVERSION
GT.M V4.3-001B AIX RS6000
This example displays the current version identifier for GT.M.
2 $ZYERror
$ZYERror
$ZYER[ROR] is a read/write ISV that contains a string value pointing to
an entryref. After GT.M encounters an error, if $ZYERROR is set a
non-null value, GT.M invokes the routine at the entryref specified by
$ZYERROR with an implicit DO. It is intended that the code invoked by
$ZYERROR use the value of $ZSTATUS to select or construct a value to
which it SETs $ZERROR. If $ZYERROR is not a valid entryref or if an
error occurs while executing the entryref specified by $ZYERROR, GT.M
SETs $ZERROR to the error status encountered. GT.M then returns control
to the M code specified by $ETRAP/$ZTRAP or device EXCEPTION.
$ZYERROR is implicitly NEWed on entry to the routine specified by
$ZYERROR. However, if GT.M fails to compile, GT.M does not transfer
control to the entryref specified by $ZYERROR.
GT.M permits $ZYERROR to be modified by the SET and NEW commands.
1 In_Out_Processing
Input Output Processing
OPEN, USE, and CLOSE commands accept deviceparameters, which are
keywords that permit an GT.M program to control the device state. Some
deviceparameters accept arguments, and some require them. The current
ANSI standard for GT.M does not define the deviceparameters for all
devices.
2 IO_ISV
I/O Intrinsic Special Variables
GT.M intrinsic special variables provide a means of communication
between a device and its device driver and GT.M routines. These
variables allow a GT.M routine to manage the I/O with a particular
device.
3 Device_Nam_Var
Device Name Variables
GT.M provides three intrinsic special variables that identify devices.
4 $IO
$IO
$I[O] contains the name of the current device specified by the last USE
command. The M standard does not permit a SET command to modify $IO.
USE produces the same $IO as USE $PRINCIPAL, but $P is the preferred
construct.
4 $Principal
$Principal
$P[RINCIPAL] contains the absolute pathname of the principal (initial
$IO) device.
Input and output for a process may come from separate devices, namely,
the standard input and output. However, the GT.M I/O model allows only
one device to be USEd (or active) at a time. When an image starts, GT.M
implicitly OPENs the standard input and standard output device(s) and
assigns the device(s) to $PRINCIPAL. For USE deviceparameters, it is
the standard input that determines the device type.
For an image invoked interactively, $PRINCIPAL is the user's terminal.
For an image invoked from a terminal by a shell script, $PRINCIPAL is
the shell script's standard input (usually the terminal) and standard
output (also usually the terminal), unless the shell redirects the
input or output.
GT.M ignores a CLOSE command specifying the principal device. GT.M does
not permit a SET command to modify $PRINCIPAL.
4 $ZIO
$ZIO
$ZIO contains the translated name of the current device, in contrast to
$IO, which contains the name as specified by the USE command.
3 Cur_Position_Var
Cursor Position Variables
GT.M provides two intrinsic special variables for determining the
virtual cursor position. $X refers to the current column, while $Y
refers to the current row.
4 $X
$X
$X contains an integer value ranging from 0 to 65,535, specifying the
horizontal position of a virtual cursor in the current output record.
$X=0 represents the left-most position of a record or row.
Every OPENed device has a $X. However, GT.M only has access to $X of
the current device. Therefore, be careful when sequencing USE commands
and references to $X.
Generally, GT.M increments $X for every character written to and read
from the current device. GT.M format control characters, FILTER, and
the device WIDTH and WRAP also have an effect on $X.
SET $X does not automatically issue device commands or escape sequences
to reposition the physical cursor.
4 $Y
$Y
$Y contains an integer value ranging from 0 to 65,535, specifying the
vertical position of a virtual cursor in the current output record.
$Y=0 represents the top row or line.
Every OPEN device has a $Y. However, GT.M only accesses $Y of the
current device. Therefore, be careful when sequencing USE commands and
references to $Y.
When GT.M finishes the logical record in progress, it generally
increments $Y. GT.M recognizes the end of a logical record when it
processes certain GT.M format control characters, or when the record
reaches its maximum size, as determined by the device WIDTH, and the
device is set to WRAP. The definition of "logical record" varies from
device to device. For an exact definition, see the sections on each
device type. FILTER and the device LENGTH also have an effect on $Y.
SET $Y does not automatically issue device commands or escape sequences
to reposition the physical cursor.
4 Maint_of_$X_and_&Y
Maintenance of $X and $Y
In GT.M, the following factors affect the maintenance of the virtual
cursor position ($X and $Y):
o The bounds of the virtual "page"
o GT.M format control characters
o GT.M character filtering
Each device has a WIDTH and a LENGTH that define the virtual "page."
The WIDTH determines the maximum size of a record for a device, while
the LENGTH determines how many records fit on a page. GT.M starts a new
record when the current record size ($X) reaches the maximum WIDTH and
the device has WRAP enabled. When the current line ($Y) reaches the
maximum LENGTH, GT.M starts a new page.
GT.M has several format control characters that allow the manipulation
of the virtual cursor. For all I/O devices, the GT.M format control
characters do the following:
! Sets $X to zero (0) and increments $Y, and terminates the logical
record in progress. The definition of "logical record" varies from
device to device, and is discussed in each device section.
# Sets $X and $Y to zero (0), and terminates the logical record in
progress.
?n If n is greater than $X, writes n-$X spaces to the device,
bringing $X to n. If n is less than or equal to $X, ?n has no
effect. When WRAP is enabled and n exceeds the WIDTH of the line,
WRITE ?n increments $Y and sets $X equal to n#WIDTH, where # is the
GT.M modulo operator.
GT.M provides two modes of character filtering. When filtering is
enabled, certain <CTRL> characters and/or escape sequences have special
effects on the cursor position (e.g., <BS> (ASCII 8) may decrement $X,
if $X is non-zero). For more information on write filtering, refer to
the section on the [NO]FILTER deviceparameter.
3 Status_Var
Status Variables
GT.M provides several I/O status variables that convey information
about the status of individual operations.
4 $ZA
$ZA
$ZA contains a status determined by the last read on the device. The
value is a decimal integer with a meaning determined by the device as
follows:
For Terminal I/O:
0 Indicating normal termination of a read operation
1 Indicating a parity error
2 Indicating the terminator sequence was too long
9 Indicating a default for all other errors
For Sequential Disk:
0 Indicating normal termination of a read operation
9 Indicating a failure of a read operation
For FIFO:
0 Indicating normal termination or time out
9 Indicating a failure of a read operation
For socket:
0 Indicating normal termination or time out
9 Indicating failure of a read operation
$ZA refers to the status of the current device. Therefore, exercise
care in sequencing USE commands and references to $ZA.
4 $ZB
$ZB
$ZB contains a string specifying the input terminator for the last
terminal READ. $ZB is null, and it is not maintained for devices other
than terminals. $ZB may contain any legal input terminator, such as
<CR> (ASCII 13) or an escape sequence starting with <ESC> (ASCII 27),
from zero (0) to 15 bytes in length. $ZB is null for any READ
terminated by a timeout or any fixed-length READ terminated by input
reaching the maximum length.
$ZB contains the actual character string, not a sequence of numeric
ASCII codes.
Example:
SET zb=$ZB FOR i=1:1:$LENGTH(zb) WRITE !,i,?5,$A(zb,i)
This example displays the series of ASCII codes for the characters in
$ZB.
$ZB refers to the last READ terminator of the current device.
Therefore, be careful when sequencing USE commands and references to
$ZB.
4 $ZEOF
$ZEOF
$ZEOF contains a truth-valued expression indicating whether the last
READ operation reached the end-of-file. $ZEOF is TRUE(1) at EOF and
FALSE (0) at other positions. GT.M does not maintain $ZEOF for terminal
devices.
$ZEOF refers to the end-of-file status of the current device.
Therefore, be careful when sequencing USE commands and references to
$ZEOF.
2 IO_Devices
I/O Devices
Each device type supported by GT.M responds to a particular subset of
deviceparameters, while ignoring others. Devices may be programmed in a
device-specific manner, or in a device-independent manner.
Device-specific I/O routines are intended for use with only one type of
device. Device-independent I/O routines contain appropriate
deviceparameters for all devices to be supported by the function, so
the user can redirect to a different device output while using the same
program.
GT.M supports the following I/O device types:
o Terminals and Printers
o Sequential Disk Files
o FIFOs
o Null Devices
o Socket Devices
3 IO_Devi_Recog
I/O Device Recognition
GT.M OPEN, USE, and CLOSE commands have an argument expression
specifying a device name. In the operating system environment, a device
may be referred to either by its physical name or by a name containing
one or more environment variables, each with a dollar-sign ($) prefix
that expand to its physical name. Because environment variables permit
program coding independent of hardware configuration, they tend to
isolate the code from hardware changes.
During an OPEN, GT.M attempts to resolve the specified device names to
physical names. When GT.M successfully resolves a device name to a
physical device, that device becomes the target of the OPEN. If the
device name contains a dollar sign ($), GT.M attempts an environment
variable translation; the result becomes the name of the device. If it
does not find such an environment variable, it assumes that the dollar
sign is a part of the filename, and opens a file by that name.
Once a device is OPEN, GT.M establishes an internal correspondence
between a name and the device or file. Therefore, while the device is
OPEN, changing the translation of an environment variable in the device
specification does not change the device.
The following names identify the original $IO for the process:
o $PRINCIPAL
0
Some versions of GT.M also treat the empty string as identifying $P.
However, Sanchez recommends using the empty string to identify a null
device, so it would be wise to avoid or eliminate this behavior.
3 Devi_Spec_Defaults
Device Specification Defaults
GT.M uses standard filenames for device specifiers.
The complete format for a filename is:
/directory/file
If the expression specifying a device does not contain a complete
filename, the expression may start with an environment variable that
translates to one or more leading components of the filename. GT.M
applies default values for the missing components.
The GT.M file-name defaults are the following:
Directory Current working directory
File No default (user-defined filename)
Filetype No default (user-defined filetype)
3 How_IO_DeviParam_Work
How I/O Deviceparameters Work
I/O deviceparameters either perform actions that cause the device to do
something (for example, CLEARSCREEN), or specify characteristics that
modify the way the device subsequently behaves (for example,
BLOCKSIZE). When an I/O command has multiple action deviceparameters,
GT.M performs the actions in the order of the deviceparameters within
the command argument. When a command has characteristic
deviceparameters, the last occurrence of a repeated or conflicting
deviceparameter determines the characteristic.
Deviceparameters often relate to a specific device type. GT.M ignores
any deviceparameters that do not apply to the type of the device
specified by the command argument. Specified device characteristics are
in force for the duration of the GT.M image, or until modified by an
OPEN, USE, or CLOSE command.
When reopening a device that it previously closed, a GT.M process
restores all characteristics not specified on the OPEN to the values
the device had when it was last CLOSEd. GT.M treats sequential disk
files differently and uses defaults for unspecified sequential disk
file characteristics on every OPEN (that is, GT.M does not retain
sequential disk file characteristics on a CLOSE).
The ZSHOW command with an argument of "D" displays the current
characteristics for all devices OPENed by the process. ZSHOW can direct
its output into a GT.M variable.
3 Abbv_DeviParam
Abbreviating Deviceparameters
GT.M deviceparameters do not have predefined abbreviations. GT.M
recognizes deviceparameters using a minimum recognizable prefix
technique. Most deviceparameters may be represented by four leading
characters, except ERASELINE, all deviceparameters starting with WRITE,
and Z* deviceparameters in a mnemonicspace (such as SOCKET). The four
leading characters recognized do not include a leading NO for negation.
For compatibility with previous versions, GT.M may recognize certain
deviceparameters by abbreviations shorter than the minimum. While it is
convenient in Direct Mode to use shorter abbreviations, Sanchez
Computer Associates may add additional deviceparameters, and therefore,
recommends all programs use at least four characters. Because GT.M
compiles the code, spelling out deviceparameters completely has no
performance penalty, except when used with indirection or XECUTEd
arguments.
3 Devi_Independent_Prog
Device-Independent Programming
When a user may choose a device for I/O, GT.M routines can take one of
two basic programming approaches.
o The user selection directs the program into different code
branches, each of which handles a different device type.
o The user selection identifies the device. There is a single code
path written with a full complement of deviceparameters to handle
all selectable device types.
The latter approach is called device-independent programming. To permit
device independent programming, GT.M uses the same deviceparameter for
all devices that have an equivalent facility, and ignores
deviceparameters applied to a device that does not support that
facility.
Example:
OPEN dev:(EXCE=exc:REWIND:VARIABLE:WRITEONLY)
This example OPENs a device with deviceparameters that affect different
devices. The EXCEPTION has an effect for all device types. When dev is
a terminal or a null device, GT.M ignores the other deviceparameters.
When dev is a sequential file on disk, GT.M uses REWIND and VARIABLE.
This command performs a valid OPEN for all the different device types.
A file that has been previously created and contains data that
should be retained can also be opened with the device parameter
APPEND.
2 Terminals
Using Terminals
A typical GT.M application is largely interactive and uses terminals
extensively. By default, a GT.M process directs its terminal I/O to
$PRINCIPAL. $PRINCIPAL identifies the terminal that the user signed
onto in UNIX.
While all terminals support the CTRAP deviceparameter, which optionally
allows terminal input to optionally redirect program flow, only
$PRINCIPAL supports CENABLE, which optionally allows the terminal user
to invoke the Direct Mode shell.
Directly connected printers often appear to GT.M as a terminal
(although printers generally do not provide input) regardless of
whether the printer is connected to the computer with a high speed
parallel interface, or an asynchronous terminal controller.
3 Set_Terminal_Char
Setting Terminal Characteristics
GT.M does not isolate its handling of terminal characteristics from the
operating system environment at large. GT.M inherits the operating
system terminal characteristics in effect at the time the GT.M image is
invoked. When GT.M exits, the invoking environment retains the device
characteristics established with GT.M.
However, if the process temporarily leaves the GT.M environment with a
ZSYSTEM command, GT.M does not recognize any changes to the terminal
characteristics left by the external environment. This may cause
disparities between the physical behavior of the terminal, and the
perceived behavior by GT.M.
UNIX enforces standard device security for explicit OPENs of terminals
other than the sign-in terminal ($PRINCIPAL). If you are unable to OPEN
a terminal, contact your system manager.
USE of a terminal causes the device driver to flush the output buffer.
This feature of the USE command provides routine control over the
timing of output, which is occasionally required. However, it also
means that redundant USE commands may induce an unnecessary performance
penalty. Therefore, Sanchez Computer Associates recommends restricting
USE commands to redirecting I/O, modifying deviceparameters, and
initiating specifically required flushes.
3 Logical_Rec_for_Term
Logical Records for Terminals
A logical record for a terminal equates to a line on the physical
screen. The WIDTH device characteristic specifies the width of the
screen, while the LENGTH device characteristic specifies the number of
lines on the screen.
3 READ_Comm_for_Term
READ* Command for Terminals
If the terminal has ESCAPE sequencing enabled, and the input contains a
valid escape sequence or a terminator character, the terminal device
driver stores the entire sequence in $ZB and returns the ASCII
representation of the first character.
Example:
GTM> KILL
GTM> USE $P:ESCAPE
GTM> READ *X SET ZB=$ZB ZWRITE
(Press the F11 key on the VT220 terminal keyboard)
x=27
zb=$C(27)_"[23~"
This enters an escape sequence in response to a READ *. The READ *
assigns the code for <ESC> to the variable X. The terminal handler
places the entire escape sequence in $ZB. Because some of the
characters are not graphic, that is, visible on a terminal, the example
transfers the contents of $ZB to the local variable ZB and uses a
ZWRITE so that the non-graphic characters appear in $CHAR() format.
The READ * command for terminals does not affect $ZB when escape
sequencing is not enabled. If the input contains a valid escape
sequence and escape sequencing is not enabled, the variable for the
READ * command returns the first character of the escape sequence, for
example, ASCII 27. The terminal device driver stores the remaining
characters of the escape sequence in the read buffer. A READ command
following a READ * command returns the remaining characters of the
escape sequence. An application that operates with NOESCAPE must
provide successive READ * commands to remove the remaining escape
characters from the buffer.
Example:
GTM> KILL
GTM> USE $P:(NOESCAPE:TERM=$C(13))
GTM> READ *X SET ZB=$ZB READ Y:0 ZWRITE
(Press the F11 key on the terminal keyboard)
[23~i=5
x=27
y="[23~"
zb=""
GTM> USE $P:NOECHO READ *X S ZB=$ZB READ Y:0 USE $P:ECHO ZW
i=5
x=27
y="[23~"
zb=""
GTM> READ *X SET ZB=$ZB USE $P:FLUSH READ Y:0 ZWRITE
i=5
x=27
y=""
zb=""
While the first READ Y:0 picks up the sequence after the first
character, notice how the graphic portion of the sequence appears on
the terminal - this is because the READ *X separated the escape
character from the rest of the sequence thus preventing the VMS
terminal driver logic from recognizing it as a sequence, and
suppressing its echo. The explicit suppression of echo removes this
visual artifact. In the case of the final READ *X, the FLUSH clears the
input buffer so that it is empty by the time of the READ Y:0.
3 READmaxlen_Comm_for_Term
READ X#maxlen Command for Terminals
Generally, GT.M performs the same maintenance on $ZB for a READ
X#maxlen as for a READ. However, if the READ X#maxlen terminates
because the input has reached the maximum length, GT.M sets $ZB to
null. When the terminal has ESCAPE sequencing enabled, and the input
contains an escape sequence that does not fit in the read buffer, GT.M
sets $ZB to contain the escape sequence.
3 Term_Examples
Terminal Examples
This section contains examples of GT.M terminal handling.
Example:
USE $PIECE:(exception="zg "_$zl_":C^MENU")
This example USEs the principal device, and sets up an EXCEPTION
handler. When an EXCEPTION occurs, it transfers control to label C in
the routine ^MENU at the process stack level where the EXCEPTION was
established.
Example:
USE $PIECE:(X=0:Y=0:CLEARSCREEN)
This example positions the cursor to the upper left-hand corner and
clears the entire screen.
Example:
USE $PIECE:(NOECHO:WIDTH=132:WRAP)
This example disables ECHOing, enables automatic WRAPping, and sets the
line width to 132 characters.
Example:
USE $PIECE:NOCENABLE
This example disables <CTRL-C>.
2 Sequential_Files
Using Sequential Files
GT.M provides access to sequential files both on disk. These files
allow linear access to records. Sequential files are used to create
programs, store reports, and to communicate with facilities outside of
GT.M.
3 Setting_Seq_File_Charc
Setting Sequential File Characteristics
The ANSI standard specifies that when a process CLOSEs and then reOPENs
a device, GT.M restores any characteristics not explicitly specified
with deviceparameters to the values they had prior to the last CLOSE.
However, because it is difficult for a large menu-driven application to
ensure the previous OPEN state, GT.M always sets unspecified sequential
file characteristics to their default value on OPEN. This approach also
reduces potential memory overhead imposed by OPENing and CLOSEing a
large number of sequential files during the life of a process.
GT.M does not restrict multiple OPEN commands. However, if a file is
already open, GT.M ignores attempts to modify sequential file OPEN
characteristics, except for RECORDSIZE and for deviceparameters that
also exist for USE.
Sequential files can be READONLY, or read/write (NOREADONLY).
Sequential files can be composed of either FIXED or VARIABLE (NOFIXED)
length records. By default, records have VARIABLE length.
UNIX enforces its standard security when GT.M OPENs a sequential file.
This includes any directory access required to locate or create the
file. If you are unable to OPEN a file, contact your system manager.
3 SeqFile_Pointers
Sequential File Pointers
Sequential file I/O operations use a construct called a file pointer.
The file pointer logically identifies the next record to read or write.
OPEN commands position the file pointer at the beginning of the file
(REWIND) or at the end-of-file (APPEND). APPEND cannot reposition a
file currently open. Because the position of each record depends on the
previous record, a WRITE destroys the ability to reliably position the
file pointer to subsequent records in a file. Therefore, by default
(NOTRUNCATE), GT.M permits WRITEs only when the file pointer is
positioned at the end of the file.
If a device has TRUNCATE enabled, a WRITE issued when the file pointer
is not at the end of the file causes all contents after the current
file pointer to be discarded. This effectively moves the end of the
file to the current position and permits the WRITE.
3 SeqFile_Examples
Sequential File Examples
This section contains a few brief examples of GT.M sequential file
handling.
Example:
FREAD READ "File > ",sd
OPEN sd:(readonly:exception="g BADOPEN")
USE sd:exception="G EOF"
FOR USE sd READ x USE $P WRITE x,!
EOF IF '
$ZEOF ZM +$ZS
CLOSE sd
QUIT
BADOPEN IF $P($ZS,",",1)=2 DO QUIT
. WRITE !,"The file ",sd," does not exist."
IF $P($ZS,",",1)=13 DO QUIT
. WRITE !,"The file ",sd," is not accessible."
ZM +$ZS
QUIT
This example OPENs a file READONLY and specifies an EXCEPTION. The
exception handler for the OPEN deals with file-not-found and
file-access errors, and reissues all other errors with the ZMESSAGE
command. The first USE sets the EXCEPTION to handle end-of-file. The
FOR loop reads the file one record at a time and transfers each record
to the principal device. The GOTO in the EXCEPTION terminates the FOR
loop. At label EOF, if $ZEOF is false, the code reissues the error that
triggered the exception. Otherwise, the CLOSE releases the file.
Example:
SET sd="temp.dat",acct=""
OPEN sd:newversion U sd:width=132
FOR SET acct=$O(^ACCT(acct)) QUIT:acct="" DO
. SET rec=$$FORMAT(acct)
. WRITE:$Y>55 #,hdr W !,rec
CLOSE sd
This OPENs a NEWVERSION of file temp.dat. The FOR loop cycles through
the ^ACCT global formatting (not shown in this code fragment) lines and
writing them to the file. The FOR loop uses the argumentless DO
construct to break a long line of code into more manageable blocks. The
program writes a header record (set up in initialization not, shown in
this code fragment) every 55 lines, because that is the application
page length, allowing for top and bottom margins.
2 FIFO_Charc
FIFO Characteristics
FIFOs have the same characteristics as other sequential files, except
that READs and WRITEs can occur in any order.
The following characteristics of FIFO behavior may be helpful in using
them effectively.
With
READ:
o If a READ is done while there is no data in the FIFO:
The process hangs until data is put into the FIFO by another process,
or the READ times out, when a timeout is specified.
With
WRITE:
o If a process tries into write to a full FIFO, the process hangs
until another process reads from the FIFO, emptying enough data to
make room for the new data.
While it is hung, the process will not respond to <CTRL-C>.
With
CLOSE:
o The FIFO is not deleted unless the DELETE qualifier is specified.
o If a process closes the FIFO with the DELETE qualifier, the FIFO
becomes unavailable to new users at that time.
o All processes currently USEing the FIFO may continue to use it,
until the last process attached to it CLOSES it, and is destroyed.
o Any process OPENing a FIFO with the same name as a deleted FIFO
creates a new one to which subsequent OPENs attach.
A process must have read and write privileges on a FIFO to access it.
File permissions have no affect on a process that already has the FIFO
open.
3 Consider_Impl_FIFOs
Considerations in Implementing FIFOs
As you establish FIFOs for interprocess communication, consider
whether, and how, the following issues will be addressed:
o Do READs occur immediately, or can the process wait?
o Are timed READs useful to avoid system hangs and provide a way to
remove the process?
o Does the WRITE process need to know whether the READ data was
received?
o Will there be multiple processes READing and WRITEing into a single
FIFO?
3 GTM_Recog_FIFOs
GT.M Recognition of FIFOs
Like other GT.M devices a FIFO can be specified as an argument
expression to the OPEN, USE, and CLOSE commands. A device OPENed with a
FIFO qualifier becomes a FIFO unless another device of that name is
already OPEN. In that case, OPENing a device that has previously been
OPENed by another process as a FIFO causes the process (the process
here is the process trying to open the FIFO) to attach to the existing
FIFO.
3 FIFO_Devi_Ex
FIFO Device Examples
The following two examples represent a master/slave arrangement where
the slave waits in a read state on the FIFO until the master sends it
some data that it then processes.
Example:
set x="named.pipe"
open x:fifo
do getres
use x write res,!
This routine opens the FIFO, performs its own processing which includes
starting the slave process (not shown in this code fragment).
Example:
set x="named.pipe"
open x:fifo
use x read res
do process(res)
This routine waits for information from the master process, then begins
processing.
2 NULL_Devices
Using NULL Devices
The null device is accessed through /dev/null. A null device fulfills
every input request by returning a null string and setting $ZEOF. A
null device discards all output. GT.M maintains a virtual cursor
position for null devices as it does for terminals. Use null devices
for program testing and debugging, or for jobs that permit I/O to be
discarded under certain circumstances. For example, JOB processes must
have input and output devices associated with them, even though they do
not use them. Null devices are low overhead never-fail alternatives.
3 Null_Dev_Ex
Null Device Examples
Example:
SET dev="/dev/null"
OPEN dev USE dev
SET x="" WRITE hdr,!,$ZDATE($h),?30,$J,!
FOR SET x=$O(^tmp($J,x)) q:x="" DO REPORT
CLOSE dev
This program produces a report derived from the information in the
global variable ^tmp. The unspecified routine REPORT may potentially
contain a large amount of code. To see that the basic program functions
without error, the programmer may discard the output involved in favor
of watching the function. To run the program normally, the programmer
simply has to change the variable dev to name another device.
Example:
JOB ^X:(IN="/dev/null":OUT="/dev/null":ERR= "error.log")
This example issues a GT.M JOB command to execute the routine ^X in
another process. This routine processes a large number of global
variables and produces no output. In the example, the JOBbed process
takes its input from a null device, and sends its output to a null
device. If the JOBbed process encounters an error, it directs the error
message to error.log.
2 Socket_Devices
Using Socket Devices
SOCKET devices are used to access and manipulate sockets. A SOCKET
device can have from zero (0) to 64 associated sockets. At any time,
only one socket from the collection can be the current socket. If there
is no current socket, an attempt to READ from, or WRITE to the device,
generates an error.
Sockets can be attached and detached from the collection of sockets
associated with a device. Detached sockets belong to a pseudo-device
called the "socketpool". A process can detach a socket from a device
and later attach it to the same device or another device.
The GT.M socket device interface does not have the ability to pass
sockets between related or unrelated processes. Currently error
trapping operates on a device, rather than on a socket.
3 Msg_Mgmt
Message Management
From an application perspective, the transport layers used by a socket
device are stream-oriented media, with no provisions for implicit
application messages. Therefore, the following are two common protocols
used to segment application messages.
o One method is to use a, typically small, fixed length message
containing the length of the next, variable length, message. In
GT.M a simplistic writer might be:
Write $Justify($Length(x),4),x
A corresponding simplistic reader might be:
Read len#4,x#len
The advantage of this approach is that the message content (the value
of x in the code fragments above) can contain any character. The
disadvantage is that detecting that the protocol has become
desynchronized is a problem.
o The other common method is to place a delimiter between each
application message. The protocol breaks if a message ever includes
a delimiter as part of its content.
The SOCKET device has the capability to handle delimiters because
parsing messages for delimiters is cumbersome.
3 Msg_Delimi
Message Delimiters
Each device can have from zero (0) to 64 delimiters associated with it.
Each delimiter can be from one (1) to 64 characters. All the delimiters
declared for a device are valid for any READ from any associated
socket, which means, any of the defined delimiters terminate the READ.
The actual terminating delimiter is available in $KEY. A WRITE to a
socket associated with a device with one or more delimiters inserts the
first of the delimiters for any WRITE ! format.
3 Read_Comm
READ Command
The READ command may be used to obtain data from a socket. A
non-fixed-length read, with no timeout and no delimiters requires a
complex implementation of sequence of READs to ensure a predictable
result. This is because the transport layer stream fragments delivered
to the reader has only accidental correspondence with the operations
performed by the writer. For example, the following
Write "Message 1","Message 2"
is presented to the reader as the stream "Message1Message2" but it can
take from one (1) to 18 READ commands to retrieve the entire stream.
3 Write_Comm
WRITE Command
The WRITE command sends data to a socket.
The WRITE command for SOCKET devices accepts following controlmnemonics
on a bound socket:
/L[ISTEN][(numexpr)]
Where numexpr is in the range 1-5 and specifies the listen queue depth.
/W[AIT][(timeout)]
Where timeout is a "numexpr" that specifies how long a server waits for
a connect before returning control to the GT.M routine.
"WRITE !" inserts the character(s) of the first I/O delimiter (if any)
to the sending buffer. If "ZFF=expr" has been used to define a
delimiter, "WRITE #" inserts the characters of that delimiter.
Otherwise WRITE # has no effect on the stream content. WRITE ! and
WRITE # always maintain $X and $Y in a fashion that emulates a terminal
cursor position.
3 Socket_Devi_Ops
Socket Device Operation
Each socket may be in one of the following states:
o Created - indicates that the socket exists.
o Bound - indicates that the socket exists and is bound to a port; a
"Bound socket" needs a listen queue which currently requires a
WRITE /LISTEN [after a USE].
o Connected - indicates that the socket exists and has a connection.
A server socket used for accepting new connections goes through the
first two states in one step with a single OPEN or in two steps with an
OPEN and a USE. When a server does a WRITE /WAIT on a Bound socket, a
client can establish a connection which Creates another server socket
that is Connected. In server operation, $KEY supplies the port value
when a socket is bound (important when port 0 is specified to get the
system to choose the port), and a socket id when a Connected socket is
created. A client socket goes through the first and third states with a
single OPEN or in two steps with an OPEN and a USE.
3 Socket_Devi_Ex
Socket Device Examples
This section contains examples on Socket Device usage.
;server.m
Set portno=6321,delim=$c(13)
Set tcpdev="server$"_$j,timeout=30
Open tcpdev:(ZLISTEN=portno_":TCP":attach="server"):timeout:"SOCKET"
Use tcpdev
Write /listen(1)
Write /wait(timeout)
;
;dialogue with the client
;
;client.m
Set host="orlando"
Set portno=6321
Set delim=$c(13)
Set tcpdev="client$"_$j,timeout=30
O
tcpdev:(connect=host_":"_portno_":TCP":attach="client"):timeout:"SOCKET"
Use tcpdev
;
;dialogue with the server
;
2 IO_Comm
I/O Commands
This section describes the following GT.M I/O commands:
o OPEN establishes a connection from a GT.M process to a device.
o USE declares a device as the current source of input and
destination for output.
o READ accepts characters from the current device into a global or
local variable.
o WRITE sends characters to the current device.
o CLOSE breaks the connection between a GT.M process and a device.
2 Open
Open
The OPEN command establishes a connection from a GT.M process to a
device.
The format of the OPEN command is:
O[PEN][:tvexpr] expr[:[(keyword[=expr][:...])][:numexpr][:expr]][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required expression specifies the device to OPEN.
o The optional keywords specify deviceparameters that control device
behavior; some deviceparameters take arguments delimited by an
equal sign (=); if the argument only contains one deviceparameter,
the surrounding parentheses are optional.
o The optional numeric expression specifies a time in seconds after
which the command should timeout if unsuccessful; 0 provides a
single attempt to open the device.
o When an OPEN command specifying a timeout contains no
deviceparameters, double colons (::) separate the timeout numeric
expression from the device expression.
o The optional expression specifies a mnemonicspace that selects a
device binding. The only mnemonicspace that GT.M currently accepts
is SOCKET.
o When an OPEN command specifies a mnemonicspace with no timeout,
double colons separate the mnemonicspace string expression from the
deviceparameters; if there are neither a timeout nor
deviceparameters, triple colons separate the mnemonicspace from the
device expression.
o An indirection operator and an expression atom evaluating to a list
of one or more OPEN arguments form a legal argument for an OPEN.
With the exception of FIFOs, UNIX device access is exclusive. READONLY
sequential disk files may be shared among many readers, but no writers.
Spooled devices are devices, usually printers, which buffer output from
multiple sources, processing it after the writing process CLOSEs the
file. Spooled devices appear to GT.M as a terminal type device. For
more information on spooled devices, refer to the UNIX System Manager's
Manual. When one process successfully OPENs a device exclusively, no
other process can access that device until the first process CLOSEs
that device.
By default, when a device is unavailable, GT.M retries the OPEN
indefinitely at approximately one second intervals. A device is
unavailable when another process is using it exclusively, or when the
OPENing process does not have the resources left to open the device.
All other errors on OPEN raise an error condition and interrupt program
flow. A timeout is a tool that lets a GT.M routine regain program
control when a device remains unavailable. When the OPEN specifies a
timeout, GT.M keeps retrying until either the OPEN succeeds or the
timeout expires.
If OPEN establishes a connection with a device before the timeout
expires, GT.M sets $TEST to TRUE (1). If the timeout expires, GT.M sets
$TEST to FALSE (0). If an OPEN command does not specify a timeout, the
execution of the command does not affect $TEST.
If a process has not previously OPENed a device within the context of
an image, any deviceparameters not supplied on the OPEN take their
default values. When reOPENing a device that it previously closed, a
GT.M process restores all characteristics not specified on the OPEN to
the values the device had when it was last CLOSEd, except with
sequential disk files. If you have a menu-driven application that OPENs
and CLOSEs devices based on user selections, take care that every OPEN
explicitly includes all deviceparameters important to the application.
GT.M treats sequential disk files differently and uses defaults for
unspecified sequential disk file characteristics on every OPEN (i.e.,
GT.M does not retain sequential disk file characteristics on a CLOSE).
If a process OPENs an already OPEN device, GT.M modifies any
characteristics that accept changes when a device is OPEN to reflect
any new deviceparameter specifications.
3 Ex_of_Open
Examples of OPEN
Example:
SET sd="report.dat" OPEN sd:NEWVERSION
This OPENs a NEWVERSION of a sequential disk file named report.dat for
both read and write access.
3 Open_DeviParam
OPEN Deviceparameters
4 APPEND
APPEND Applies to: Sequential Files
Positions the file pointer at the end-of-file. This deviceparameter
only affects the device on the first OPEN command. Re-OPENing an
already OPEN device with this deviceparameter has no effect.
By default, OPEN sets the file pointer to the beginning-of-file.
4 ATTACH
Attach=expr Applies to: Socket Device
When ATTACH is used and one of ZLISTEN and CONNECT is specified at the
same time, the value of expr becomes the identifier of the newly
created socket. If neither ZLISTEN nor CONNECT is specified, ATTACH is
ignored.
4 BLOCKSIZE
BLOCKSIZE=intexpr Applies to: Terminals and Printers
Specifies the size in bytes of the maximum single read or write for the
specified device.
4 CANONICAL
[NO]CANONICAL Applies to: Terminals and Printers
Enables or disables canonical input as controlled by the ICANON
terminal attribute. See the documentation on your platform for details,
but in general this would be erase and kill edit functions, and lines
delimited by NL (usually <LF>), EOF (usually ^D), and EOL (usually not
defined).
By default, canonical input is enabled.
4 CONNECT
CONNECT=expr Applies to: Socket Device
Enables a client connection with a server, which is located by the
information provided by expr. A new socket is allocated for the client
connection and is made the current socket for the device, if the
operation is successful.
expr specifies the protocol and protocol specific information.
Currently, TCP/IP is the only protocol GT.M supports. expr should be of
the format "<host>:<port>:TCP", where host is either an IP address or a
hostname like server.sanchez.com.
CONNECT is not compatible with ZLISTEN.
4 DELIMITER
[NO]DELIMITER=expr Applies to: Socket Device
DELIMITER establishes or replaces the list of delimiters used by the
sockets associated with the device. The default for on a command that
first OPENs a device is NODELIMITER. The delimiter list on a
preexisting device remains the same until it is explicitly replaced or
deleted.
expr must be a string of the following format:
':' is used to separate delimiters (it is the delimiter for
delimiters).
'/' serves as an escape character.
expr "ab:/:://:bc" is interpreted as four delimiters, which are "ab",
":", "/", and "bc". One socket can have 0-64 delimiters and each
delimiter can contain 1-64 characters.
4 EXCEPTION
EXCEPTION=expr Applies to: All devices
Defines an error handler for an I/O device. The expression must contain
a fragment of GT.M code (for example, GOTO ERRFILE) that GT.M XECUTEs
when the driver for the device detects an error, or an entryref to
which GT.M transfers control, as appropriate for the current
gtm_ztrap_form.
For more information on error handling, refer to the "Error Processing"
chapter in GT.M Programmer's Guide.
4 FIFO
FIFO Applies to: FIFO
Specifies that the device for the OPEN is a FIFO name. GT.M creates the
FIFO if it does not already exist and if the process has adequate
privileges. However, in the event that the process does not have
adequate privileges, the process generates a run-time error. A process
does not require any privileges to OPEN an existing FIFO.
4 FIXED
[NO]FIXED Applies to: Sequential Files and FIFO
Selects a fixed record length format for sequential disk files. FIXED
does not specify the actual length of a record. Use RECORDSIZE to
specify the record length.
NOFIXED specifies a variable length record format for sequential disk
files. NOFIXED is a synonym for VARIABLE. FIXED is incompatible with
STREAM and VARIABLE.
By default, records have VARIABLE length.
4 GROUP
GROUP=expr Applies to: Sequential Files and FIFO
Specifies access permission on a UNIX file for other users in the file
owner's group. The expression is a character string evaluating to null
or to any combination of the letters RWX, indicating respectively Read,
Write, and eXecute access. When any of the permissions controlling
deviceparameters appears on an OPEN of a new file, any user category
(OWNER, SYSTEM, WORLD), that is not explicitly specified is given the
default access permissions. When any one of these deviceparameters
appears on an OPEN of an existing device, any user category that is not
explicitly specified remains unchanged.
In order to modify file security, the user who issues the OPEN must
have ownership.
By default, OPEN does not modify the permissions on an existing file.
Unless otherwise specified, when OPEN creates a new file, it
establishes security using standard defaulting rules.
4 IOERROR
IOERROR=expr Applies to: Socket Device
Enables exception handling in socket devices. expr specifies the I/O
error trapping mode. A value equal to "TRAP" specifies that I/O errors
on a device raise error conditions. A value equal to "NOTRAP", or when
IOERROR is not specified, indicates that I/O error on a device does not
raise error conditions.
GT.M currently handles exception handling at device level instead
of socket level.
4 NEWVERSION
NEWVERSION Applies to: Sequential Files and FIFO
The NEWVERSION deviceparameter assures that when an existing file is
used, it is empty upon the OPEN.
By default, if any version of the file exists, OPEN accesses the
current version. If no version of the file exists, OPEN without
READONLY creates a new file.
4 OWNER
OWNER=expr Applies to: Sequential Files and FIFO
Specifies access permission on a UNIX file for the owner of the file.
The expression is a character string evaluating to null or to any
combination of the letters RWX, indicating Read, Write, and eXecute
access. When any one of these deviceparameters appears on an OPEN of a
new file, any user category that is not explicitly specified is given
the default mask. When any one of these deviceparameters appears on an
OPEN of an existing file, any user category (GROUP, SYSTEM, WORLD) that
is not explicitly specified remains unchanged.
To modify file security, the user who issues the OPEN must have
ownership.
By default, OPEN does not modify the permissions on an existing file.
Unless otherwise specified, OPEN establishes security using standard
defaulting rules when it creates a new file.
4 READONLY
[NO]READONLY Applies to: Sequential Files and FIFO
OPENs a device for reading only (READONLY) or reading and writing
(NOREADONLY).
To open a sequential file using the READONLY parameter, the file must
exist on the disk. If it does not, GT.M issues a run-time error.
When GT.M encounters a WRITE directed to a file OPENed READONLY, GT.M
issues a run-time error.
By default, OPEN accesses the device or file NOREADONLY (read-write).
4 RECORDSIZE
RECORDSIZE=intexpr Applies to: Sequential Files and FIFO
Overrides the default record size for a disk and specifies the new
maximum record size in bytes.
4 REWIND
REWIND Applies to: Sequential Files
REWIND positions the file pointer of a sequential disk to the first
record.
By default, OPEN does not REWIND.
5 [NO]STREAM Applies to: SD
4 STREAM
[NO]STREAM Applies to: Sequential Files
STREAM and VARIABLE are essentially the same; VARIABLE is preferred.
The combination of the STREAM and NOWRAP options on disk files allows
you to write a record of arbitrary length. While each WRITE argument is
truncated if it exceeds the WIDTH, the total record can be of arbitrary
length. Note that, for efficiency, the compiler combines sequential
literal arguments of a single WRITE into a single string so that the
run-time system considers the combined length of the sequence.
Automatic record termination does not occur when record length exceeds
the device width.
By default, records are VARIABLE, NOSTREAM.
4 SYSTEM
SYSTEM=expr Applies to: Sequential Files
This deviceparameter is a synonym for OWNER that is maintained in UNIX
for compatibility with VMS applications.
4 TRUNCATE
[NO]TRUNCATE Applies to: Sequential Files and FIFO
Enables or disables overwriting of existing data in sequential disk
files. Because the position of each record depends on the prior record,
a WRITE destroys the ability to reliably position to subsequent records
in a file. Therefore, by default (NOTRUNCATE), GT.M permits WRITEs only
when the file pointer is positioned at the end-of-file. When a device
has TRUNCATE enabled, a WRITE issued when the file pointer is not at
end-of-file truncates the file by destroying all data from the file
pointer to the end-of-file.
By default, OPEN accesses the file NOTRUNCATE.
4 UIC
UIC=expr Applies to: Sequential Files and FIFO
Specifies the group that has access to the file. The format of the
string is "g,i" where g is a decimal number representing the group
portion of the UIC and i is a decimal number representing the
individual portion. A process with the VMS privilege CMKRNL may set the
file UIC to a UIC other than the UIC under which it is running, thereby
giving ownership of the file to another user.
Specifies the owner and affects access to the file. The expression
evaluates to the numeric identifier of the new owner.
4 VARIABLE
VARIABLE Applies to: Sequential Files and FIFO
Specifies the VARIABLE record length format for sequential disk files.
By default, records have VARIABLE length.
4 WORLD
WORLD=expr Applies to: Sequential Files and FIFO
Specifies access permissions for users not in the owner's group on a
UNIX file. The expression is a character string evaluating to null or
to any combination of the letters RWX, indicating respectively Read,
Write, and eXecute access. When any one of these deviceparameters
appears on an OPEN of a new file, any user category that is not
explicitly specified is given the default character string. When any
one of these deviceparameters appears on an OPEN of an existing file,
any user category (OWNER, GROUP, SYSTEM), that is not explicitly
specified remains unchanged.
To modify file security, the user who issues the OPEN must have
ownership.
By default, OPEN and CLOSE do not modify the permissions on an existing
file. Unless otherwise specified, when OPEN creates a new file, it
establishes security using standard defaulting rules.
4 WRAP
[Z][NO]WRAP Applies to: FIFO, Sequential Devices, and Socket Device
Enables or disables automatic record termination. When the current
record size ($X) reaches the maximum WIDTH and the device has WRAP
enabled, GT.M starts a new record, as if the routine had issued a WRITE
! command.
NOWRAP causes GT.M to require a WRITE ! to terminate the record. NOWRAP
allows $X to become greater than the device WIDTH for terminals and
null devices.
The combination of STREAM and NOWRAP options on disk files allows you
to write a record of arbitrary length. Without the STREAM option, the
WRAP option determines the action taken when the record length exceeds
the device WIDTH. NOWRAP causes GT.M to truncate the record, while WRAP
causes GT.M to insert a format control character.
By default, records WRAP.
4 ZBFSIZE
ZBFSIZE Applies to: Socket Devices
Allocates a buffer used by GT.M when reading from a socket. The ZBFSIZE
deviceparameter should be at least as big as the largest message
expected.
By default, the size of ZBFSIZE is 1024 and the maximum it can be is
1048576.
4 ZDELAY
Z[NO]DELAY Applies to: Socket Devices
Controls buffering of data packets by the system TCP stack using the
TCP_NODELAY option to the SETSOCKOPT system call. This behavior is
sometimes known as the Nagle algorithm. The default is ZDELAY. This
delays sending additional packets until either an acknowledgement of
previous packets is received or an interval passes. If several packets
are sent from one end of a connection before the other end responds,
setting ZNODELAY may be desirable though at the cost of additional
packets being transmitted over the network. ZNODELAY must be fully
spelled out.
4 ZFF
Z[NO]FF=expr Applies to: Socket Device
expr specifies a string of characters, typically in $CHAR() format to
send to socket device, whenever a routine issues a WRITE #. When no
string is specified or when ZFF="", then no characters are sent. The
default in GT.M is ZNOFF.
4 ZIBFSIZE
ZIBFSIZE Applies to: Socket Device
Sets the buffer size used by the network software (setsockopt
SO_RCVBUF).
The default and the maximum values depend on the platform and/or system
parameters.
4 ZLISTEN
ZLISTEN=expr Applies to: Socket Device
A new socket is allocated to listen for a connection. It is made the
current socket for the device, if the operation is successful. Upon
successful completion, $KEY is set to the format of
"BOUND|<socket handle>|<port number>"
otherwise, $KEY is assigned the empty string.
expr specifies the protocol and protocol specific information.
Currently, TCP/IP is the only protocol GT.M supports. expr must be of
the format "<port>:TCP", where port specifies the port number at which
the socket is waiting for a connection.
ZLISTEN is not compatible with ATTACH in the USE command and
CONNECT in both USE and OPEN commands.
2 Use
Use Command
The USE command selects the current device for READs (input) and WRITEs
(output).
The format of the USE command is:
U[SE][:tvexpr] expr[:(keyword[=expr][:...])][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required expression specifies the device to make the current
device.
o A USE that selects a device not currently OPENed by the process
causes a run-time error.
o The optional keywords specify deviceparameters that control device
behavior; some deviceparameters take arguments delimited by an
equal sign (=). If there is only one deviceparameter, the
surrounding parentheses are optional.
o An indirection operator and an expression atom evaluating to a list
of one or more USE arguments form a legal argument for a USE.
The intrinsic special variable $IO identifies the current device, so
GT.M directs all READs and WRITEs to $IO. When a GT.M image starts,
$PRINCIPAL is implicitly OPENed and USEd. Once the GT.M image USEs a
device, $IO holds the name of that device until the next USE command.
A USE command modifies the device in accordance with the
deviceparameters that apply to the device type and ignores those that
do not apply. Characteristics set with USE deviceparameters persist
until another USE for the same device with the corresponding
deviceparameter. Characteristics persist through USEs of other devices
and, except for sequential files, through a subsequent CLOSE and
re-OPEN.
Example:
USE $P:(X=0:Y=$Y-1:NOECHO)
This example USEs the principal device. If that device is a terminal,
the deviceparameters turn off echo and position the cursor to the
beginning of the previous line.
3 Use_DeviParam
Use Deviceparameters
4 ATTACH
ATTACH=expr Applies to: Socket Device
When ATTACH is used and one of ZLISTEN and CONNECT is specified at the
same time, the value of expr becomes the identifier of the newly
created socket. If neither ZLISTEN nor CONNECT is specified, expr
specifies the socket to be moved from the socketpool to the socket
device argument of USE.
4 CANONICAL
[NO]CANONICAL Applies to: Terminals and Printers
Enables or disables canonical input as controlled by the ICANON
terminal attribute. See the documentation on your platform for details,
but in general this would be erase and kill edit functions, and lines
delimited by NL (usually <LF>), EOF (usually ^D), and EOL (usually not
defined).
By default, canonical input is enabled (that is [NO]CANONICAL is the
default).
4 CENABLE
[NO]CENABLE Applies to: Terminals and Printers
Enables or disables the ability to force GT.M into Direct Mode by
entering <CTRL-C> at $PRINCIPAL.
[NO]CENABLE is subordinate to a CTRAP that includes <CTRL-C> ($C(3)).
By default, images have CENABLEd.
4 CLEARSCREEN
CLEARSCREEN Applies to: Terminals and Printers
Clears the terminal screen from the present cursor position to the
bottom of the screen. The CLEARSCREEN deviceparameter does not change
the cursor position or the $X and $Y variables.
Example:
U $P:(X=0:Y=0:CLEAR)
This example positions the cursor to "home" in the upper left corner of
a VDT and clears the entire current screen "page."
4 CONNECT
CONNECT=expr Applies to: Socket Device
Enables a client connection with a server, which is located by the
information provided by expr. A new socket is allocated for the client
connection and is made the current socket for the device, if the
operation is successful.
expr specifies the protocol and protocol specific information.
Currently, TCP/IP is the only protocol GT.M supports. expr should be of
the format "<host>:<port>:TCP", where host is either an IP address or a
hostname like server.sanchez.com.
CONNECT is not compatible with ZLISTEN.
4 CONVERT
[NO]CONVERT Applies to: Terminals and Printers
Enables or disables the terminal device driver from converting
lowercase input to uppercase during READs.
By default, the terminal device driver operates NOCONVERT.
4 CTRAP
CTRAP=expr Applies to: Terminals and Printers
Establishes the <CTRL> characters in the expression as trap characters
for the current device. When the terminal device driver receives a trap
character in the input from a device, GT.M issues a run-time exception.
The device does not have to be the current device, that is $IO.
The <CTRL> characters are ASCII 0 though 31.
For example, the command U $P:CTRAP=$C(26,30,7,19) sets a trap for the
ASCII characters <SUB>, <RS>, <BEL> and <DC3>.
Specifying CTRAP completely replaces the previous CTRAP list. Setting
CTRAP to the null string ("") disables character trapping.
A trap character enabled by CTRAP produces one of the following
actions:
o If an EXCEPTION deviceparameter has been issued for the device, the
process executes the EXCEPTION argument.
o Otherwise, if $ETRAP is not the empty string, execute $ETRAP.
o Otherwise, if $ZTRAP is not the empty string, the process executes
$ZTRAP.
o Otherwise, the GT.M image terminates.
For more information on error handling, refer to the "Error Processing"
chapter in GT.M Programmer's Guide.
When CTRAP includes <CTRL-C>, [NO]CENABLE has no effect. CTRAPping
<CTRL-C> also takes precedence over CENABLE.
4 DELIMITER
[NO]DELIMITER Applies to: Socket Device
DELIMITER establishes or replaces the list of delimiters used by the
sockets associated with the device. The default when the socket device
is first OPENed is NODELIMITER. The delimiter list on a preexisting
device remains the same until it is explicitly replaced or deleted.
expr must be a string of the following format:
':' is used to separate delimiters (it is the delimiter for
delimiters).
'/' serves as an escape character.
expr "ab:/:://:bc" is interpreted as four delimiters, which are "ab",
":", "/", and "bc". One socket can have 0-64 delimiters and each
delimiter can contain 1-64 characters.
4 DETACH
DETACH=expr Applies to: Socket Device
Removes the socket identified by expr from the current socket device,
without affecting any existing connection of that socket. The removed
socket is placed in the socketpool and may be attached to another
socket device. If the socket being removed is the current socket, then
GT.M does the following:
o The socket ATTACHed prior to the removed socket, is made current,
if one such exists.
o The socket ATTACHed after the removed socket, is made current, if
the removed one was the first socket.
o $PRINCIPAL is made the current device ($IO), if the removed socket
was the only one in the current socket device.
4 DOWNSCROLL
DOWNSCROLL Applies to: Terminals and Printers
If $Y=0, DOWNSCROLL does nothing. Otherwise, DOWNSCROLL moves the
cursor up one line on the terminal screen and decrements $Y by one.
DOWNSCROLL does not change the column position or $X. Some terminal
hardware may not support DOWNSCROLL.
4 ECHO
[NO]ECHO Applies to: Terminals and Printers
Enables or disables terminal device driver echo of input.
By default, terminal device drivers ECHO.
4 ERASELINE
ERASELINE Applies to: Terminals and Printers
Clears the current line from the physical cursor position to the end of
the line. ERASELINE does not affect the physical cursor position, or $X
and $Y.
4 ESCAPE
[NO]ESCAPE Applies to: Terminals and Printers
Enables or disables terminal device driver processing of escape
sequences.
The following events result when a terminal has ESCAPE sequencing
enabled. When an <ESC> or <CSI> arrives in the terminal input, the
device driver verifies the sequence that follows as a valid ANSI escape
sequence, terminates the READ, and sets $ZB to contain the entire
escape sequence. In this case, if the sequence starts with an <ESC>,
READ * returns the decimal ASCII representation for the character of
the escape introducer.
When escape processing is disabled, READ *x returns 27 in x for an
<ESC>. If the escape introducer is also a TERMINATOR, $ZB has a string
of length one (1), and a value of the $ASCII() representation of the
escape introducer; otherwise, $ZB holds the empty string. For single
character and short fixed reads with NOESCAPE, the terminal device
driver places the remaining characters of the escape sequence in the
input buffer for subsequent READs, regardless of [NO]TYPEAHEAD."
4 EXCEPTION
EXCEPTION=expr Applies to: All devices
Defines an error handler for an I/O device. The expression must contain
a fragment of GT.M code (e.g., GOTO ERRFILE) that GT.M XECUTEs when the
driver for the device detects an error, or an entryref to which GT.M
transfers control, as appropriate for the current gtm_ztrap_form.
For more information on error handling, refer to the "Error Processing"
chapter in GT.M Programmer's Guide.
4 FILTER
[NO]FILTER[=expr] Applies to: Terminals and Printers, Socket Device,
and NULL Device
Specifies character filtering for valid filtering expressions.
Filtering requires character by character examination of all output and
reduces I/O performance.
Each FILTER deviceparameter can have only one argument. However,
multiple FILTER deviceparameters can appear in a single USE command,
each with different arguments.
The valid values for expr:
[NO]CHARACTERS enables or disables maintenance of $X and $Y according
to the M ANSI standard for the characters <BS>, <LF>, <CR> and <FF>.
CHARACTERS causes the device driver to examine all output for the above
characters, and to adjust $X and $Y accordingly. By default, GT.M
performs special maintenance on $X and $Y only for M format control
characters, WRAPped records, and certain action deviceparameters.
[NO]ESCAPE alters the effect of ANSI escape sequences on $X and $Y.
ESCAPE causes GT.M to filter the output, searching for ANSI escape
sequences and preventing them from updating $X and $Y. By default, GT.M
does not screen output for escape sequences.
By default, GT.M does not perform output filtering. For GT.M to
maintain $X for non-graphic characters as described by the standard,
FILTER="CHARACTERS" must be enabled. Output filtering adds additional
overhead to I/O processing.
4 HOSTSYNC
[NO]HOSTSYNC Applies to: Terminals and Printers
Enables or disables the use of XON/XOFF by the host to throttle input
and prevent impending buffer overruns for a terminal. This
deviceparameter provides a control mechanism for the host over
asynchronous communication lines to help prevent data loss when
hardware is slow and/or processing load is high.
By default, the device driver operates HOSTSYNC.
4 IOERROR
IOERROR=expr Applies to: Socket Device
Enables exception handling in socket devices. expr specifies the I/O
error trapping mode. A value equal to "TRAP" specifies that I/O errors
on a device raise error conditions. A value equal to "NOTRAP", or when
IOERROR is not specified, indicates that I/O error on a device does not
raise error conditions.
GT.M currently handles exception handling at device level instead
of socket level.
4 LENGTH
[Z]LENGTH=intexpr Applies to: Terminals and Printers, Socket Device,
and NULL Device.
Sets the virtual page length for an I/O device to the integer
expression. The page length controls the point at which the device
driver automatically resets $Y to 0.
By default, GT.M uses the LENGTH specified by the device
characteristics at image activation. The terminal default depends on
the type of terminal. The default length for null device and socket
device is 66.
4 PASTHRU
[NO]PASTHRU Applies to: Terminals and Printers
Enables or disables interpretation of the ERASE character for a
terminal. PASTHRU shifts management of handling and response to ERASE
characters in the input stream from the driver to the GT.M application
code.
Exercise caution with PASTHRU in debugging, because using a PASTHRU
terminal in Direct Mode is somewhat awkward.
[NO]TTSYNC must be used with [NO]PASTHRU to control XON/XOFF handling.
By default, the device driver operates NOPASTHRU.
4 READSYNC
[NO]READSYNC Applies to: Terminals and Printers
Enables or disables automatic output of <XON> before a READ and <XOFF>
after a READ.
By default, the terminal drivers operate NOREADSYNC.
4 REWIND
REWIND Applies to: Sequential Files
REWIND for a disk file is a logical rather than a physical operation.
By default, USE does not REWIND.
4 SOCKET
SOCKET=expr Applies to: Socket Device
The socket specified in expr is made the current socket. Specifying a
socket that has not been previously OPENed generates an error.
SOCKET is compatible with DELIMITER only.
4 TERMINATOR
[NO]TERMINATOR[=expr] Applies to: Terminals and Printers
Specifies which of the 256 ASCII characters terminate a READ. For
example, TERMINATOR=$C(0) makes <NUL> the terminator.
When [NO]ESCAPE is in effect, TERMINATOR controls whether or not <ESC>
or <CSI> are treated as terminators, however, when ESCAPE processing is
enabled, the entire escape sequence is treated as a terminator
regardless of the TERMINATOR specification.
NOTERMINATOR eliminates all terminators. When a terminal has all
terminators disabled, fixed length READ and READ * terminate on receipt
of some number of characters, and a timed READ terminates on timeout,
but any other READ only terminates when the input fills the terminal
read buffer.
By default, terminals recognize <CR> and <ESC> as terminators, (i.e.,
TERMINATOR=$C(13,27)). TERMINATOR="" restores the default. However,
unless the terminal has PASTHRU, the operating system interprets some
escape sequences rather than passing them to the READ.
Example:
GTM> USE $P:TERM=$C(26,13,11,7)
This example enables the ASCII characters <SUB>, <CR>, <VT> and <BEL>
as READ terminators.
4 TRUNCATE
[NO]TRUNCATE Applies to: Sequential Files
Enables or disables overwriting of existing data in sequential files.
Because the position of each record depends on the prior record, a
WRITE destroys the ability to reliably position to subsequent records
in a file. Therefore, by default (NOTRUNCATE), GT.M permits WRITEs only
when the file pointer is positioned at the end-of-file. When a device
has TRUNCATE enabled, a WRITE issued when the file pointer is not at
end-of-file truncates the file by destroying all data from the file
pointer to the end-of-file.
By default, OPEN accesses files NOTRUNCATE, which does not allow
overwriting of sequential files.
This deviceparameter may not be supported by your platform.
4 TTSYNC
[NO]TTSYNC Applies to: Terminals and Printers
Enables or disables recognition of XON/XOFF for terminal output. A
terminal may have its own handling of XON/XOFF, controlled by a
set-up mode or by switches. If an application requires program
recognition of <CTRL-S> and <CTRL-Q>, the terminals may require
reconfiguration.
4 TYPEAHEAD
[NO]TYPEAHEAD Applies to: Terminals and Printers
Enables or disables type-ahead buffering for a terminal. With
NOTYPEAHEAD and no outstanding READ, the terminal device driver
discards input entered at the terminal. With TYPEAHEAD and no
outstanding READ, the device driver stores input entered at the
terminal in a type-ahead buffer. The device driver uses data from the
type-ahead buffer for subsequent READs.
The size of the type-ahead buffer limits the amount of data entered at
the terminal that the device driver can store in anticipation of future
READs.
By default, the terminal device driver accepts TYPEAHEAD.
4 UPSCROLL
UPSCROLL Applies to: Terminals and Printers
Moves the cursor down one line on the terminal screen. If $Y=LENGTH-1,
UPSCROLL sets $Y=0. Otherwise UPSCROLL increments $Y by one. If the
cursor is physically at the bottom of the page, the screen scrolls up
one line. UPSCROLL does not change the column position or $X.
4 WIDTH
[Z]WIDTH=intexpr Applies to: Terminals and Printers, Socket Device,
NULL Device, and Sequential Files
Sets the device's logical record size and enables WRAP.
NOWRAP and WIDTH supersede each other. When WIDTH and NOWRAP appear
together on the same USE command, the final one controls the device
behavior. For a terminal, WIDTH=0 is equivalent to WIDTH=n:NOWRAP,
where n is the default length of a logical record on that terminal.
Terminals inherit their default WIDTH in GT.M from the invoking shell
environment. The default WIDTH for null and socket device is 255.
4 WRAP
[Z][NO]WRAP Applies to: Terminals and Printers, FIFO, Socket Device,
NULL Device, and Sequential Files
Enables or disables automatic record termination. When the current
record size ($X) reaches the maximum WIDTH and the device has WRAP
enabled, GT.M starts a new record, as if the routine had issued a WRITE
! command.
NOWRAP causes GT.M to require a WRITE ! to terminate the record. NOWRAP
allows $X to become greater than the device WIDTH for terminals.
By default, WIDTH sets WRAP. When WIDTH and NOWRAP appear together on
the same USE command, the last one controls the device behavior.
By default, records WRAP.
4 X
X=intexpr Applies to: Terminals and Printers
$X positions the cursor to a vertical column on the terminal. If NOWRAP
is enabled or intexpr<WIDTH, the terminal device driver sets
$X=intexpr. If WRAP is enabled and intexpr>WIDTH, GT.M sets
$X=intexpr#WIDTH, where # is the GT.M modulo operator. The resulting $X
determines the actual physical position.
To ensure that $Y and $X match what is occurring visually on the
terminal, the GT.M deviceparameters and the device characteristics must
match at all times. For example, if a process initiates a subprocess
that changes the terminal wrap setting from NOWRAP, to WRAP, GT.M
returns to the NOWRAP condition when the subprocess completes, and
wraps on the terminal do not reflect in the values of $X and $Y.
The terminal hardware may affect physical cursor positioning. The X
deviceparameter does not change the cursor row or update $Y.
4 Y
Y=intexpr Applies to: Terminals and Printers
Positions the cursor to a horizontal row on the terminal.
The terminal device driver sets $Y=intexpr#LENGTH, where # is the GT.M
modulo operator. If intexpr<LENGTH, the resulting $Y determines the
physical position. If intexpr>LENGTH, the cursor is positioned so that
$Y=intexpr#LENGTH, where # is the GT.M module operator. The terminal
hardware may affect physical cursor positioning.
To ensure that $Y and $X match what is occurring visually on the
terminal, the GT.M deviceparameters and the device characteristics must
match at all times. For example, if a process initiates a subprocess
that changes the terminal wrap setting from NOWRAP, previously set with
the GT.M USE command to WRAP, GT.M does not reflect the change when the
subprocess completes. Therefore, wraps on the terminal do not reflect
in the values of $X and $Y.
The Y deviceparameter does not change the cursor column or update $X.
4 ZBFSIZE
ZBFSIZE Applies to: Socket Device
Allocates a buffer used by GT.M when reading from a socket. The ZBFSIZE
deviceparameter should be at least as big as the largest message
expected.
By default, the size of ZBFSIZE is 1024 and the maximum it can be is
1048576.
4 ZDELAY
Z[NO]DELAY Applies to: Socket Device
Controls buffering of data packets by the system TCP stack using the
TCP_NODELAY option to the SETSOCKOPT system call. This behavior is
sometimes known as the Nagle algorithm. The default is ZDELAY. This
delays sending additional packets until either an acknowledgement of
previous packets is received or an interval passes. If several packets
are sent from one end of a connection before the other end responds,
setting ZNODELAY may be desirable though at the cost of additional
packets being transmitted over the network. ZNODELAY must be fully
spelled out.
4 ZFF
Z[NO]FF=expr Applies to: Socket Device
expr specifies a string of characters, typically in $CHAR() format to
send to socket device, whenever a routine issues a WRITE #. When no
string is specified or when ZFF="", then no characters are sent. The
default in GT.M is ZNOFF.
4 ZIBFSIZE
ZIBFSIZE Applies to: Socket Device
Sets the buffer size used by the network software (setsockopt
SO_RCVBUF).
The default and the maximum values depend on the platform and/or system
parameters.
4 ZLISTEN
ZLISTEN=expr Applies to: Socket Device
A new socket is allocated to listen for a connection. It is made the
current socket for the device, if the operation is successful. Upon
successful completion, $KEY is set to the format of
"BOUND|<socket handle>|<port number>"
otherwise, $KEY is assigned the empty string.
expr specifies the protocol and protocol specific information.
Currently, TCP/IP is the only protocol GT.M supports. expr must be of
the format "<port>:TCP", where port specifies the port number at which
the socket is waiting for a connection.
2 Read
Read
The READ command transfers input from the current device to a global or
local variable specified as a READ argument. For convenience, READ also
accepts arguments that perform limited output to the current device.
The format of the READ command is:
R[EAD][:tvexpr] glvn|*glvn|glvn#intexpr|strlit|fcc[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o A subscripted or unsubscripted global or local variable name
specifies a variable into which to store the input; the variable
does not have to exist prior to the READ; if the variable does
exist prior to the READ, the READ replaces its old value.
o When an asterisk (*) immediately precedes the variable name, READ
accepts one character of input and places the ASCII code for that
character in the variable.
o When a number sign (#) and a non-zero integer expression
immediately follow the variable name, the integer expression
determines the maximum number of characters accepted as input to
the read; such reads terminate when GT.M reads the number of
characters specified by the integer expression or a terminator in
the input stream, whichever occurs first.
o To provide a concise means of issuing prompts, GT.M sends string
literal and format control character (!,?intexpr,#) arguments of a
READ to the current device as if they were arguments of a WRITE.
o An indirection operator and an expression atom evaluating to a list
of one or more READ arguments form a legal argument for a READ.
The maximum length of the input string is the smaller of the device
buffer size limitation or the GT.M maximum string length (32,767
characters). If a record is longer than the maximum record length, GT.M
returns the record piece by piece during sequential reads, for devices
that allow it.
When a string literal appears as an argument to a READ, M writes the
literal to the current device. String literals appear as READ arguments
to serve as prompts for input. GT.M does not permit expression
arguments on a READ to act as prompts. Variable prompts must appear as
arguments to a WRITE. If a variable appears as an argument to a READ,
GT.M always interprets it as input, never as output. This facility is
used mostly with terminal I/O.
The READ commands adjust $X and $Y, based on the length of the input
read.
3 Read_Comm
READ * Command
The READ * command reads one character from the current device and
returns the decimal ASCII representation of that character into the
variable specified for the READ * command. READ * appears most
frequently in communication protocols, or in interactive programs where
single character answers are appropriate.
The following example reads the value "A", and returns the decimal
ASCII representation of "A" in the variable X.
Example:
GTM> READ *X
A
GTM> WRITE X
65
If a timeout occurs before GT.M reads a character, the READ * returns a
negative one (-1) in the variable.
3 Read_maxlen_Comm
READ X#maxlen Command
The READ X#maxlen command limits the maximum size of the input to a
maximum of "maxlen" characters, where maxlen is an integer expression.
If a READ follows a READ X#maxlen command, the READ returns the
remainder of the current record.
If a terminator arrives before maxlen characters are received the READ
X#maxlen terminates.
2 Write
Write
The WRITE command transfers a character stream specified by its
arguments to the current device.
The format of the WRITE command is:
W[RITE][:tvexpr] expr|*intexpr|fcc[,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o An expression argument supplies the text of a WRITE.
o When a WRITE argument consists of a leading asterisk (*) followed
by an integer expression, WRITE outputs one character associated
with the ASCII code specified by the integer evaluation of the
expression.
o WRITE also accepts format control characters as arguments; format
control characters modify the position of a virtual cursor: an
exclamation point (!) produces the device specific record
terminator (for example, new line for a terminal), a number sign
(#) produces device specific page terminator (for example, form
feed for a terminal) and a question mark (?) followed by an
expression moves the virtual cursor to the column specified by the
integer evaluation of the expression if the virtual cursor is to
the "left" of the specified column.
o When directed to a device bound to a mnemonicspace, WRITE also
accepts controlmnemonics, which are keywords specific to the
binding - they are delimited by a slash (/) prefix and optionally
followed by a parenthetical list of arguments. The parentheses "(
)" are optional when there are no arguments, but must appear even
if there is a single argument
o An indirection operator and an expression atom evaluating to a list
of one or more WRITE arguments form a legal argument for a WRITE.
GT.M can write up to 32,767 bytes (the GT.M maximum string length) as a
result of a single WRITE argument. GT.M buffers output into a "logical
record" for all devices except sockets without DELIMITERs and
sequential devices with STREAM enabled. The WRITE command appends a
string to the current record of the current device. GT.M does not write
to the output device until the buffer is full, a GT.M format control
character forces a write, a USE command, a CLOSE command, or, for
terminals, the buffer becomes stale.
Each device has a WIDTH and a LENGTH that define the virtual "page".
The WIDTH determines the maximum size of a record for a device, while
the LENGTH determines how many records fit on a page. When the current
record size ($X) reaches the maximum WIDTH and the device has WRAP
enabled, GT.M starts a new record. When the current line ($Y) reaches
the maximum LENGTH, GT.M starts a new page.
A WRITE with an asterisk preceding the argument, which it would expect
to be a decimal ASCII representation, writes the character
corresponding to the ASCII representation. The WRITE command also has
several format control characters that allow the manipulation of the
virtual cursor. For all I/O devices, the GT.M format control characters
do the following:
WRITE ! Clears $X and increments $Y and terminates the logical
record in progress. The definition of "logical record" varies from
device to device, and is discussed in each device section.
WRITE # Clears $X and $Y and terminates the logical record in
progress.
WRITE ?n If n is greater than $X, writes n-$X spaces to the device,
bringing $X to n. If n is less than or equal to $X, WRITE ?n has no
effect. When WRAP is enabled and n exceeds the LENGTH of the line,
WRITE ?n increments $Y.
For more information, refer to the sections on specific I/O devices.
2 Close
Close
The CLOSE command breaks the connection between a process and a device.
The format of the CLOSE command is:
C[LOSE][:tvexpr] expr[:(keyword[=expr][:...])][,...]
o The optional truth-valued expression immediately following the
command is a command postconditional that controls whether or not
GT.M executes the command.
o The required expression specifies the device to CLOSE.
o The optional keywords specify deviceparameters that control device
behavior; some deviceparameters take arguments delimited by an
equal sign (=); if there is only one keyword, the surrounding
parentheses are optional.
o An indirection operator and an expression atom evaluating to a list
of one or more CLOSE arguments form a legal argument for a CLOSE.
When a CLOSE is issued, GT.M flushes all pending output to the device,
and processes any deviceparameters. CLOSEing a device not currently
OPEN has no effect.
GT.M retains the characteristics of all device types, except a
sequential file, for use in case of subsequent re-OPENs. If the device
is a sequential file, characteristics controlled by deviceparameters
are lost after the CLOSE.
If the device being CLOSEd is $IO, GT.M implicitly USEs $PRINCIPAL.
GT.M ignores CLOSE $PRINCIPAL.
Example:
CLOSE SD:RENAME=SD_".SAV"
This closes the device and, if it is a disk file, renames it to have
the type .SAV.
3 Close_DeviParam
CLOSE Deviceparamenter
4 DELETE
DELETE Applies to: Sequential Files, and FIFO
Instructs GT.M to delete the current version of the disk file after
GT.M closes it.
4 EXCEPTION
EXCEPTION=expr Applies to: All devices
Defines an error handler for an I/O device. The expression must contain
a fragment of GT.M code (for example, GOTO ERRFILE) that GT.M XECUTEs
when the driver for the device detects an error, or an entryref to
which GT.M transfers control, as appropriate for the current
gtm_ztrap_form.
For more information on error handling, refer to the "Error Processing"
chapter in GT.M Programmer's Guide.
4 GROUP
GROUP=expr Applies to: Sequential Disk Files, and FIFO
Specifies access permission on a UNIX file for other users in the file
owner's group. The expression is a character string evaluating to null
or to any combination of the letters RWX, indicating respectively Read,
Write, and eXecute access. When any one of these deviceparameters
appears on a CLOSE of a new file, any user category that is not
explicitly specified is given the default character string. When any
one of these deviceparameters appears on a CLOSE of an existing file,
any user category (OWNER, SYSTEM, WORLD), that is not explicitly
specified remains unchanged.
In order to modify file security, the user who issues the CLOSE must
have ownership.
By default, CLOSE does not modify the permissions on an existing file.
4 OWNER
OWNER=expr Applies to: Sequential Disk Files, and FIFO
Specifies access permission on a UNIX file for the owner of the file.
The expression is a character string evaluating to null or to any
combination of the letters RWX, indicating respectively Read, Write,
and eXecute access. When any one of these deviceparameters appears on a
CLOSE of a new file, any user category that is not explicitly specified
is given the default mask. When any one of these deviceparameters
appears on a CLOSE of an existing file, any user category (GROUP,
SYSTEM, WORLD), that is not explicitly specified remains unchanged.
In order to modify file security, the user who issues the CLOSE must
have ownership.
By default, CLOSE does not modify the permissions on an existing file.
4 RENAME
RENAME=expr Applies to: Sequential Disk Files
Changes the file name to the name contained in the argument string.
When the expression omits part of the pathname, GT.M constructs the
full pathname by applying the defaults discussed in the section on
device specifications.
If the process has sufficient access permissions, it may use RENAME to
specify a different directory as well as file name. RENAME cannot move
a file to a different device.
4 SOCKET
SOCKET=expr Applies to: Socket Device
The socket specified in expr is closed. Specifying a socket that has
not been previously OPENed generates an error. If no SOCKET
deviceparameter is specified on a CLOSE for a socket device, the socket
device and all sockets associated with it are closed.
4 SYSTEM
SYSTEM=expr Applies to: Sequential Disk Files, and FIFO
This deviceparameter is a synonym for OWNER that is maintained in UNIX
for compatibility with VMS applications.
By default, CLOSE does not modify the permissions on an existing file.
4 UIC
UIC=exprgroup number Applies to: Sequential Disk Files, and FIFO
Specifies the group that has access to the file. The format of the
string is "g,i" where g is a decimal number representing the group
portion of the UIC and i is a decimal number representing the
individual portion. A process with the VMS privilege CMKRNL may set the
file UIC to a UIC other than the UIC under which it is running, thereby
giving ownership of the file to another user.
Specifies the owner and affects access to the file. The expression
evaluates to the numeric identifier of the new owner.
4 WORLD
WORLD=expr Applies to: Sequential Disk Files, and FIFO
Specifies access permissions for users not in the owner's group on a
UNIX file. The expression is a character string evaluating to null or
to any combination of the letters RWX, indicating respectively Read,
Write, and eXecute access. When any one of these deviceparameters
appears on a CLOSE of a new file, any user category that is not
explicitly specified is given the default character string. When any
one of these deviceparameters appears on a CLOSE of an existing file,
any user category (OWNER, GROUP, SYSTEM), that is not explicitly
specified remains unchanged.
In order to modify file security, the user who issues the CLOSE must
have ownership.
By default, CLOSE and CLOSE do not modify the permissions on an
existing file. Unless otherwise specified, when CLOSE creates a new
file, it establishes security using standard defaulting rules.
In order to modify file security, the user who issues the CLOSE must
have ownership.
By default, CLOSE does not modify the permissions on an existing file.
1 M_Utility_Rtns
M Utility Routines
GT.M provides library utilities to perform frequently used tasks, and
to access frequently used information. Most of the utilities are for
GT.M programmers, but some provide tools for system administration and
operation.
The GT.M utilities fall into the following general categories:
o Date and time utilities
o Conversion utilities
o Mathematic utilities
o Global utilities
o Routine utilities
o Internationalization utilities
o System Management utilities
The GT.M distribution includes the source files for these utilities.
The default installation compiles them to produce object modules in the
$gtm_dist distribution library.
You may wish to examine the utilities and include some of them in your
programs if the programs access the function frequently or you may want
to modify the utilities to better fit your particular needs. If you
modify a utility, store your copy in a directory that precedes gtm_dist
in the search list $ZROUTINES to prevent a new release of GT.M from
overlaying your copy.
2 Using_Util
Using the Utilities
You can either use a utility in Direct Mode or include it in a source
application program with one or more of the following formats.
Italicized items are to be supplied by the user:
o DO ^%UTILITYNAME
o DO LABEL^%UTILITYNAME
o $$FUNC^%UTILITYNAME[(para1,...)]
Many utilities contain labels that invoke variations of the basic
utility functionality. Some also provide the label FUNC to invoke an
extrinsic function with optional or required parameters.
GT.M passes input to non-extrinsic forms of the utilities interactively
or by using "input" variables. GT.M passes output from non-extrinsic
forms of the utilities using "output" variables. For extrinsic entry
points, the utilities receive input as parameters and pass output as
the returned result. For other entry points, GT.M uses predefined
"input" and "output" variables to pass information. Some utilities
interactively request user inputs and display their results. Each
utility is described individually in this chapter where appropriate
labels, input, and output variables are identified.
By convention, the utilities use upper-case variables for external
input and output. Since M is case-sensitive, when an invocation uses a
lower-case or misspelled variable name, the routine does not output the
expected information. Instead it supplies a default value, if one
exists, or produces an error message.
Example:
GTM>SET %ds="11/22/2002"
GTM>DO INT^%DATE
GTM>ZWRITE
%DN=59123
%ds="11/22/2002"
This example sets the lowercase variable %ds to the date 11/22/2002.
Since the %DATE routine expects the input to be provided in the
uppercase %DS variable, it returns a default value in the output
variable $DN. The default is the $HOROLOG format of the current date,
which is 11/15/2002 in the example.
2 Date_Time_Util
Date and Time Utilities
The date and time utilities are:
%D Displays the current date using the [d]d-mmm-[yy]yy format.
%DATE Converts input date to the $HOROLOG format.
%H Converts date and time to and from $HOROLOG format.
%T Displays the current time in [h]h:mm AM/PM format.
%TI Converts time to $HOROLOG format.
%TO Converts the current time from $HOROLOG format to [h]h:mm AM/PM
format.
For details and examples, refer to the GT.M Programmer's Guide.
The "%" sign has been removed from the topic headings below,
intentionally.
3 D_
%D
The %D utility displays the current date using the [d]d-mmm-[yy]yy
format. If a routine uses this function repetitively, put the utility
code directly into the M program.
4 Util_Labels
Utility Labels
INT Sets variable %DAT to current date.
FUNC[()] Invokes an extrinsic function returning today's date.
4 Output_Vars
Output Variables
%DAT Contains the current date.
4 Ex_of_D
Examples of %D
For the following examples, $ZDATEFORM is assumed to be one (1).
Example:
GTM>DO ^%D
22-NOV-2002
This example invokes %D in Direct Mode. Then %D displays the current
date.
Example:
GTM>DO INT^%D
GTM>ZWRITE
%DAT="22-NOV-2002"
This example invokes %D with the label INT (INT^%D). The variable %DAT
contains the current date. ZWRITE displays the contents of the output
variable.
Example:
GTM>WRITE $$FUNC^%D
22-NOV-2002
This example invokes %D as an extrinsic function with the label FUNC.
$$FUNC^%D returns today's date.
3 DATE
%DATE
The %DATE utility converts an input date to the $HOROLOG format. The
$HOROLOG format represents time as the number of days since December
31, 1840. The routine has entry points for interactive or
non-interactive use.
4 Util_Labels
Utility Labels
INT Converts %DS input non-interactively, if defined, otherwise the
current date.
FUNC(t) Invokes an extrinsic function returning $HOROLOG format of
the argument.
4 Prompts
Prompts
Date: Interactively requests a date for conversion to $HOROLOG
format.
4 Input_Vars
Input Variables
%DS Contains input date; refer to %DATE Input Formats table.
4 Output_Vars
Output Variables
%DN Contains output date in $HOROLOG format
4 Ex_of_DATE
Examples of %DATE
Example:
GTM>DO ^%DATE
Date:
GTM>ZWRITE
%DN=59105
This example invokes %DATE at the GTM> prompt. After pressing <RETURN>
at the Date: prompt, %DATE converts today's date (for example,
10/28/2002) to the $HOROLOG format. ZWRITE displays the contents of the
output variable.
Example:
GTM>DO INT^%DATE
GTM>ZWRITE
%DN=59105
This example invokes INT^%DATE, which converts the current date
non-interactively into $HOROLOG format. ZWRITE displays the contents of
the output variable.
Example:
GTM>SET %DS="10/20/2002"
GTM>DO INT^%DATE
GTM>ZWRITE
%DN=59097
%DS="10/20/2002"
This example sets the input variable %DS prior to invoking INT^%DATE,
which converts that date non-interactively to $HOROLOG format.
Example:
GTM>WRITE $$FUNC^%DATE("10/20/2002")
59097
This example invokes %DATE with the label FUNC as an extrinsic function
to convert an input date to $HOROLOG. If the invocation does not supply
a date for $$FUNC^%DATE, FUNC converts the current date.
Example:
GTM>WRITE $ZDATEFORM
1975
GTM>WRITE $$FUNC^%DATE("10/20/80")
51062
GTM>WRITE $ZDATE(51062)
10/20/1980
GTM>WRITE $$FUNC^%DATE("10/20/10")
62019
GTM>WRITE $ZDATE(62019)
10/20/2010
This example shows the use of a year limit in $ZDATEFORM. Two digit
years are interpreted to be in the interval (1975, 2074) since
$ZDATEFORM is 1975; the input year "80" is interpreted as the year
"1980" and "10" is interpreted as the year "2010". The example invokes
FUNC^%DATE to convert the input date to $HOROLOG format. $ZDATE() is
used to convert the $HOROLOG format date to mm/dd/yyyy format.
3 H
%H
The %H utility converts date and time to and from $HOROLOG format.
4 Util_Labels
Utility Labels
%CDS Converts %DT $HOROLOG input date to mm/dd/yyyy format.
%CTS Converts %TM $HOROLOG input time to external format.
%CDN Converts %DT input date to $HOROLOG format.
%CTN Converts %TM input time to $HOROLOG format.
CDS(dt) Extrinsic entry that converts the $HOROLOG argument to
external date format.
CTS(tm) Extrinsic entry that converts the $HOROLOG argument to
external time format.
CDN(dt) Extrinsic entry that converts the argument to $HOROLOG
format.
CTN(tm) Extrinsic entry that converts the argument to $HOROLOG
format.
4 Input_Vars
Input Variables
%DT Contains input date in either $HOROLOG or mm/dd/[yy]yy format,
depending on the format expected by the utility entry point.
%TM Contains input time in either $HOROLOG or [h]h:mm:ss format,
depending on the format expected by the utility entry point.
4 Output_Vars
Output Variables
%DAT Contains converted output date,
%TIM Contains converted output time,
4 Ex_of_H
Examples of %H
Example:
GTM>SET %DT=+$H DO %CDS^%H
GTM>ZWRITE
%DAT="10/20/2002"
%DT=59097
This example sets %DT to the current date in $HOROLOG format and
converts it to mm/dd/yyyy format by invoking %H at the label %CDS. %H
returns the converted date in the variable %DAT. ZWRITE displays the
contents of the variables.
Example:
GTM>SET %DT="10/20/2002" DO %CDN^%H
GTM>ZWRITE
%DAT=59097
%DT="10/20/2002"
This example sets the variable %DT to a date in mm/dd/yyyy format and
invokes %H at the label %CDN. %H returns the converted date in the
variable %DAT. ZWRITE displays the contents of the variables.
Example:
GTM>SET %TM=$P($H,",",2) DO %CTS^%H
GTM>ZWRITE
%TIM="17:41:18"
%TM=63678
This example sets the variable %TM to the current time in $HOROLOG
format using a $PIECE() function to return only those digits of the
$HOROLOG string that represent the time. The example then invokes %H at
the label %CTS. %H returns the converted time in the variable %TIM.
ZWRITE displays the contents of the variables.
Example:
GTM>SET %TM="17:41:18" DO %CTN^%H
GTM>ZWRITE
%TIM=63678
%TM="17:41:18"
This example sets the variable %TM to a time in hh:mm:ss format, and
invokes %H at the label %CTN. %H returns the converted time in the
variable %TIM. ZWRITE displays the contents of the variables.
Example:
GTM>WRITE $$CDS^%H(59130)
11/22/2002
This invokes CDS^%H as an extrinsic function to convert the external
argument to external date format.
Example:
GTM>WRITE $ZDATEFORM
1980
GTM>WRITE $$CDN^%H("10/20/02")
59097
GTM>WRITE $ZDATE(59097)
10/20/2002
GTM>WRITE $$CDN^%H("10/20/92")
55445
GTM>WRITE $ZDATE(55445)
10/20/1992
This example shows the use of a year limit in $ZDATEFORM. Two digit
years are interpreted to be in the interval of 1980 - 2079; since
$ZDATEFORM is 1980, the input year "02" is interpreted as "2002" and
"92" is interpreted as "1992". This example invokes CDN^%H to convert
the argument in mm/dd/yy format to $HOROLOG format. $ZDATE() is used to
conver the $HOROLOG format date to mm/dd/yyyy format.
3 T_
%T
The %T utility displays the current time in [h]h:mm AM/PM. If a routine
uses this function repetitively, put the utility code directly into the
M program.
4 Util_Labels
Utility Labels
INT Sets %TIM to current time in [h]h:mm AM/PM format.
FUNC[()] Invokes an extrinsic function returning the current time.
4 Output_Vars
Output Variables
%TIM Contains current time in [h]h:mm AM/PM format.
4 Ex_of_T
Examples of %T
Example:
GTM>DO ^%T
8:30 AM
This example invokes %T, which prints the current time and does not set
%TIM.
Example:
GTM>DO INT^%T
GTM>ZWRITE
%TIM="8:30 AM"
This example invokes INT^%T, which sets the variable %TIM to the
current time. ZWRITE displays the contents of the variable.
Example:
GTM>WRITE $$FUNC^%T
8:30 AM
This example invokes FUNC as an extrinsic function, which returns the
current time.
3 TI
%TI
The %TI utility converts time to $HOROLOG format. The $HOROLOG format
represents time as the number of seconds since midnight. %TI returns
the converted time in the variable %TN. The routine has entry points
for interactive or non-interactive use.
4 Util_Labels
Utility Labels
INT Non-interactively converts %TS to $HOROLOG format; if %TS is
not defined, then current time is converted.
FUNC[(ts)] Invokes an extrinsic function returning $HOROLOG format
of the argument, or if no argument, the $HOROLOG format of the
current time.
4 Prompts
Prompts
Time: Requests time in [h]h:mm:ss format to convert to $HOROLOG
format.
4 Input_Vars
Input Variables
%TS Contains input time.
4 Output_Vars
Output Variables
%TN Contains output time in $HOROLOG format
4 Ex_of_TI
Examples of %TI
Example:
GTM>DO ^%TI
Time: 4:02 PM
GTM>ZWRITE
%TN=57720
This example invokes %TI, which prompts for an input time. Press
<RETURN> to convert the current time. ZWRITE displays the contents of
the output variable.
Example:
GTM>ZWRITE
GTM>DO INT^%TI
GTM>ZWRITE
%TN=40954
This example invokes INT^%TI to convert the current time
non-interactively. ZWRITE displays the contents of the output variable
%TN.
Example:
GTM>SET %TS="8:30AM"
GTM>DO INT^%TI
GTM>ZWRITE
%TN=30600
%TS="8:30AM"
This example sets the variable %TS prior to invoking INT^%TI. %TI uses
%TS as the input time. ZWRITE displays the contents of the variables.
Example:
GTM>WRITE $$FUNC^%TI("8:30AM")
30600
This example invokes %TI as an extrinsic function to convert the
supplied time to $HOROLOG format. If there is no argument (i.e.,
$$FUNC^%TI), %TI converts the current time.
3 TO
%TO
The %TO utility converts the input time from $HOROLOG format to [h]h:mm
AM/PM format. Put the utility code directly into the M program if the
routine uses this function repetitively.
4 Util_Labels
Utility Labels
INT Converts non-interactively %TS, or if %TS is not defined the
current time to [h]h:mm AM/PM format.
4 Input_Vars
Input Variables
%TN Contains input time in $HOROLOG format.
4 Output_Vars
Output Variables
%TS Contains output time in [h]h:mm AM/PM format.
4 Ex_of_TO
Examples of %TO
Example:
GTM>DO INT^%TI,^%TO
GTM>ZWRITE
%TN=62074
%TS="5:14 PM"
This example invokes INT^%TI to set %TN to the current time and invokes
%TO to convert the time contained in %TN to the [h]h:mm AM/PM format.
%TO returns the converted time in the variable %TS. ZWRITE displays the
contents of the variables.
2 Conversion_Util
Conversion Utilities
The conversion utilities are:
%DH Decimal to hexadecimal conversion.
%DO Decimal to octal conversion.
%HD Hexadecimal to decimal conversion.
%HO Hexadecimal to octal conversion.
%LCASE Converts a string to all lower case.
%OD Octal to decimal conversion.
%OH Octal to hexadecimal conversion.
%UCASE Converts a string to all upper case.
The conversion utilities can be invoked as extrinsic functions.
The "%" sign has been removed from the topic headings below,
intentionally.
3 DH
%DH
The %DH utility converts numeric values from decimal to hexadecimal.
%DH defaults the length of its output to eight digits. However the
input variable %DL overrides the default and controls the length of the
output. The routine has entry points for interactive or non-interactive
use.
4 Util_Labels
Utility Labels
INT Converts interactively entered decimal number to hexadecimal
number with the number of digits specified.
FUNC(d[,l]) Invokes %DH as an extrinsic function returning the
hexadecimal equivalent of the argument.
4 Input_Vars
Input Variables
%DH As input, contains input decimal number.
%DL Specifies how many digits appear in the output, defaults to
eight.
4 Prompts
Prompts
Decimal: Requests a decimal number for conversion to hexadecimal.
Digits: Requests the length of the output in digits; eight by
default.
4 Output_Vars
Output Variables
%DH As output, contains the converted number in hexadecimal.
4 Ex_of_DH
Examples of %DH
Example:
GTM>DO INT^%DH
Decimal: 12
Digits: 1
GTM>ZWRITE
%DH="C"
This example invokes %DH interactively with INT^%DH. %DH prompts for a
decimal number and output length, then returns the result in the
variable %DH. ZWRITE displays the contents of the variables.
Example:
GTM>SET %DH=12
GTM>DO ^%DH
GTM>ZWRITE
%DH="0000000C"
%DL=8
This example sets the read-write variable %DH to 12 and invokes %DH to
convert the number to a hexadecimal number. Because the number of
digits was not specified, %DH used the default of 8 digits. Set %DL to
specify the number of output digits.
Example:
GTM>WRITE $$FUNC^%DH(12,4)
000C
This example invokes %DH as an extrinsic function using the FUNC label.
The first argument specifies the input decimal number and the optional,
second argument specifies the number of output digits. If the extrinsic
does not have a second argument, the length of the output defaults to
eight characters.
3 DO
%DO
The %DO utility converts numeric values from decimal to octal. The
default length of its output is 12 digits. The value assigned to the
input variable %DL overrides the default and controls the length of the
output. The routine has entry points for interactive or non-interactive
use.
4 Util_Labels
Utility Labels
INT Converts the specified decimal number to an octal number with
the specified number of digits, interactively.
FUNC(d[,ln]) Invokes %DO as an extrinsic function, returning the
octal equivalent of the argument.
4 Prompts
Prompts
Decimal: Requests a decimal number for conversion to octal.
Digits: Requests the length of the output in digits; 12 by default.
4 Input_Vars
Input Variables
%DO As input, contains input decimal number.
%DL Specifies the number of digits in the output, defaults to 12.
4 Output_Vars
Output Variables
%DO As output, contains the converted number in octal.
4 Ex_of_DO
Examples of %DO
Example:
GTM>DO INT^%DO
Decimal: 12
Digits: 4
GTM>ZWRITE
%DO="0014"
This example invokes %DO interactively with INT^%DO. %DO prompts for a
decimal number and an output length. If the output value of %DO has
leading zeros, the value is a string. ZWRITE displays the contents of
the variables.
Example:
GTM>SET %DO=12
GTM>DO ^%DO
GTM>ZWRITE
%DO="000000000014"
This example sets the read-write variable %DO to 12 and invokes %DO to
convert the number non-interactively. Because the number of digits was
not specified, %DO used the default of 12 digits. Set %DL to specify
the number of output digits. ZWRITE displays the contents of the
variables.
Example:
GTM>WRITE $$FUNC^%DO(12,7)
0000014
This example invokes %DO as an extrinsic function with the label FUNC.
The first argument specifies the number to be converted and the
optional, second argument specifies the number of output digits. If the
second argument is not specified, %DO uses the default of 12 digits.
3 HD
%HD
The %HD utility converts numeric values from hexadecimal to decimal.
%HD returns the decimal number in the read-write variable %HD. %HD
rejects input numbers beginning with a minus (-) sign and returns null
(""). The routine has entry points for interactive or non-interactive
use.
4 Util_Labels
Utility Labels
INT Converts hexadecimal number entered interactively to decimal
number.
FUNC(h) Invokes %HD as an extrinsic function returning the decimal
equivalent of the argument.
4 Prompts
Prompts
Hexadecimal: Requests a hexadecimal number for conversion to
decimal.
4 Input_Vars
Input Variables
%HD As input, contains input hexadecimal number.
4 Output_Vars
Output Variables
%HD As output, contains the converted number in decimal.
4 Ex_of_HD
Examples of %HD
Example:
GTM>DO INT^%HD
Hexadecimal:E
GTM>ZWRITE
%HD=14
This example invokes %HD in interactive mode with INT^%HD. %HD prompts
for a hexadecimal number, then returns the converted number in the
variable %HD. ZWRITE displays the contents of the variable.
Example:
GTM>SET %HD="E"
GTM>DO ^%HD
GTM>ZWRITE
%HD=14
This example sets the read-write variable %HD to "E" and invokes %HD to
convert non-interactively the value of %HD to a decimal number. %HD
places the converted value into the read-write variable %HD.
Example:
GTM>WRITE $$FUNC^%HD("E")
14
This example invokes %HD as an extrinsic function with the label FUNC
and writes the results.
3 HO
%HO
The %HO utility converts numeric values from hexadecimal to octal. %HO
returns the octal number in the read-write variable %HO. %HO rejects
input numbers beginning with a minus (-) sign and returns null ("").
The routine has entry points for interactive or non-interactive use.
4 Util_Labels
Utility Labels
INT Converts hexadecimal number entered interactively to octal
number.
FUNC(h) Invokes %HO as an extrinsic function returning the octal
equivalent of the argument.
4 Prompts
Prompts
Hexadecimal: Requests a hexadecimal number for conversion to octal.
4 Input_Vars
Input Variables
%HO As input, contains input hexadecimal number.
4 Output_Vars
Output Variables
%HO As output, contains the converted number in octal.
4 Ex_of_HO
Examples pf %HO
Example:
GTM>DO INT^%HO
Hexadecimal:C3
GTM>ZWRITE
%HO=303
This example invokes %HO in interactive mode using INT^%HO. %HO prompts
for a hexadecimal number that it converts to an octal number. ZWRITE
displays the contents of the variable.
Example:
GTM>SET %HO="C3"
GTM>DO ^%HO
GTM>ZWRITE
%HO=303
This example sets the read-write variable %HO to "C3" and invokes %HO
to convert the value of %HO non-interactively. ZWRITE displays the
contents of the variable.
Example:
GTM>WRITE $$FUNC^%HO("C3")
303
This example invokes %HO as an extrinsic function with the FUNC label.
3 LCASE
%LCASE
The %LCASE utility converts a string to all lower-case letters. If a
routine uses this function repetitively, put the utility code directly
into the M program.
4 Util_Labels
Utility Labels
INT Converts interactively a string to lower-case.
FUNC(s) Invokes %LCASE as an extrinsic function returning the
lower-case form of the argument.
4 Prompts
Prompts
String: Requests a string for conversion to lower case.
4 Input_Vars
Input Variables
%S As input, contains string to be converted to lower case.
4 Output_Vars
Output Variables
%S As output, contains the converted string in lower case.
4 Ex_of_LCASE
Examples of %LCASE
Example:
GTM>DO INT^%LCASE
String: LABEL
Lower: label
This example invokes %LCASE in interactive mode using INT^%LCASE.
%LCASE prompts for a string that it converts to all lower case.
Example:
GTM>SET %S="Hello"
GTM>do ^%LCASE
GTM>zwrite
%S="hello"
This example sets the variable %S to the string "Hello" and invokes
%LCASE non-interactively to convert the string.
Example:
GTM>SET ^X="Hello"
GTM>WRITE $$FUNC^%LCASE(^X)
hello
This example sets the variable ^X to the string "Hello" and invokes
%LCASE as an extrinsic function that returns "hello" in lower case.
3 OD
%OD
The %OD utility converts numeric values from octal to decimal. %OD
returns the decimal number in the read-write variable %OD. %OD rejects
input numbers beginning with a minus (-) sign and returns null ("").
The routine has entry points for interactive or non-interactive use.
4 Util_Labels
Utility Labels
INT Converts octal number entered interactively to decimal number.
FUNC(oct) Invokes %OD as an extrinsic function returning the
decimal equivalent of the argument.
4 Prompts
Prompts
Octal: Requests an octal number for conversion to decimal.
4 Input_Vars
Input Variables
%OD As input, contains input octal number.
4 Output_Vars
Output Variables
%OD As output, contains the converted number in decimal.
4 Ex_of_OD
Examples of %OD
Example:
GTM>DO INT^%OD
Octal:14
GTM>ZWRITE
%OD=12
This example invokes INT^%OD to interactively convert the octal number
entered. %OD prompts for an octal number that it converts to a decimal.
%OD returns the converted value in the variable %OD.
Example:
GTM>SET %OD=14
GTM>DO ^%OD
GTM>ZWRITE
%OD=12
This example sets the read-write variable %OD to 14 and invokes %OD to
convert the number non-interactively. ZWRITE displays the contents of
the variables.
Example:
GTM>WRITE $$FUNC^%OD(14)
12
This example invokes %OD as an extrinsic function with the FUNC label.
The argument specifies the number to be converted.
3 OH
%OH
The %OH utility converts numeric values from octal to hexadecimal. %OH
returns the hexadecimal number in the read-write variable %OH. %OH
rejects input numbers beginning with a minus (-) sign. The routine has
entry points for interactive or non-interactive use. In interactive
mode, %OH rejects non-octal numbers with the following message, "Input
must be an octal number". In non-interactive mode, %OH returns a null
string ("") upon encountering a non-octal number.
4 Util_Labels
Utility Labels
INT Converts interactively octal number entered to hexadecimal
number.
FUNC(oct) Invokes %OH as an extrinsic function returning the
hexadecimal equivalent of the argument.
4 Prompts
Prompts
Octal: Requests an octal number for conversion to hexadecimal.
4 Input_Vars
Input Variables
%OH As input, contains input octal number.
4 Output_Vars
Output Variables
%OH As output, contains the converted number in hexadecimal.
4 Ex_of_OH
Examples of %OH
Example:
GTM>DO INT^%OH
Octal:16
GTM>ZWRITE
%OH="E"
This example invokes %OH in interactive mode using INT^%OH. %OH prompts
for an octal number that it converts to a hexadecimal number. ZWRITE
displays the contents of the variable.
Example:
GTM>SET %OH=16
GTM>DO ^%OH
GTM>ZWRITE
%OH="E"
This example sets the read-write variable %OH to 16 and invokes %OH to
convert the value of %OH non-interactively. ZWRITE displays the
contents of the variable.
Example:
GTM>WRITE $$FUNC^%OH(16)
E
This example invokes %OH as an extrinsic function with the FUNC label.
3 UCASE
%UCASE
The %UCASE utility converts a string to all upper-case letters. If a
routine uses this function repetitively, put the utility code directly
into the M program.
4 Util_Labels
Utility Labels
INT Converts a string to upper case interactively.
FUNC(s) Invokes %UCASE as an extrinsic function, returning the
upper-case form of the argument.
4 Prompts
Prompts
String: Requests a string for conversion to upper case.
4 Input_Vars
Input Variables
%S As input, contains string to be converted to upper case.
4 Output_Vars
Output Variables
%S As output, contains the converted string in upper case.
4 Ex_of_UCASE
Examples of %UCASE
Example:
GTM>DO INT^%UCASE
String: test
Upper: TEST
This example invokes %UCASE in interactive mode using INT^%UCASE.
%UCASE prompts for a string that it converts to all upper case.
Example:
GTM>SET ^X="hello"
GTM>WRITE $$FUNC^%UCASE(^X)
HELLO
This example sets the variable X to the string "hello" and invokes
%UCASE as an extrinsic function that returns "HELLO" in upper case.
2 Math_Util
Mathematic Utilities
The mathematic utilities are:
%EXP Raises one number to the power of another number.
%SQROOT Calculates the square root of a number.
The mathematic utilities can be invoked as extrinsic functions.
The "%" sign has been removed from the topic headings below,
intentionally.
3 EXP
%EXP
The %EXP utility raises one number provided to the power of another
number provided. While this utility provides an interactive interface
for exponential calculations, most production code would perform inline
calculation with the "**" operator. The routine has entry points for
interactive or non-interactive use.
4 Util_Labels
Utility Labels
INT Calculates a number to the power of another number
interactively.
FUNC(i,j) Invokes %EXP as an extrinsic function returning the first
argument raised to the power of the second argument.
4 Prompts
Prompts
Power: Requests an exponent or power.
Number: Requests a base number to raise by the power.
4 Input_Vars
Input Variables
%I As input, contains number to be raised to a power.
%J Contains exponential power by which to raise %I.
4 Output_Vars
Output Variables
%I As output, contains the result of the exponential calculation.
4 Ex_of_EXP
Examples of %EXP
Example:
GTM>DO INT^%EXP
Power: 3
Number: 12
12 raised to 3 is 1728
This example invokes %EXP in interactive mode using INT^%EXP. %EXP
prompts for an exponent (power) and a base number.
Example:
GTM>SET %I=2,%J=9
GTM>DO ^%EXP
GTM>ZWRITE
%I=512
%J=9
This example sets the read-write variable %I to 2, variable %J to 9,
and invokes %EXP to calculate the result. ZWRITE displays the contents
of the variables. %I contains the result.
Example:
GTM>WRITE $$FUNC^%EXP(2,9)
512
This example invokes %EXP as an extrinsic function with the label FUNC.
3 SQROOT
%SQROOT
The %SQROOT utility calculates the square root of a number provided.
While this utility provides an interactive interface for taking square
roots, most production code would perform inline calculation by raising
a number to the .5 power (n**.5). The routine has entry points for
interactive or non-interactive use.
4 Util_Labels
Utility Labels
INT Calculates the square root of a number interactively.
FUNC(s) Invokes %SQROOT as an extrinsic function returning the
square root of the argument.
4 Prompts
Prompts
The square root of: Requests a number.
4 Input_Vars
Input Variables
%X Contains the number for which to calculate the square root.
4 Output_Vars
Output Variables
%Y Contains the square root of %X.
4 Ex_of_SQROOT
Examples of %SQROOT
Example:
GTM>SET %X=81
GTM>DO ^%SQROOT
GTM>ZWRITE
%X=81
%Y=9
This example sets the variable %X to 81 and invokes %SQROOT to
calculate the square root non-interactively. ZWRITE displays the
contents of the variables.
Example:
GTM>DO INT^%SQROOT
The square root of: 81 is: 9
The square root of: <RETURN>
GTM>
This example invokes INT^%SQROOT interactively that prompts for a
number. The square root of the number appears on the same line. %SQROOT
then prompts for another number. Press <RETURN> to exit.
Example:
GTM>WRITE $$FUNC^%SQROOT(81)
9
This example invokes %SQROOT as an extrinsic function with the label
FUNC.
2 Glob_Util
Global Utilities
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.
3 G_
%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.
4 Prompts
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.
4 Ex_of_G
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.
3 GC_
%GC
The %GC utility copies values of globals from one global to another. It
is useful for testing and for moving misfiled data.
4 Prompts
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.
4 Ex_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.
3 GCE
%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.
4 Prompts
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.
4 Ex_of_GCE
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.
3 GD
%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.
4 Prompts
Prompts
Global ^ Requests (using %GSEL) a global name with optional
wildcards or a range of names; <RETURN> terminates %GD.
4 Ex_of_GD
Exampels 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.
3 GED
%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.
4 Prompts
Prompts
Edit ^ Requests the name, in ZWRITE format, of a global to edit.
Only one global can be edited at a time with %GED, refer to GT.M
Programmer's Guide for descriptions of valid input for subscripts.
4 Ex_of_GED
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.
3 GI
%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.
The %GI utility corresponds to MUPIP LOAD. The format of the input file
(GO or ZWRITE) is automatically detected.
4 Prompts
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.
4 Ex_of_GI
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-2002 14:14:09
OK <Yes>? <RETURN>
^IB ^INFO
Restored 10 nodes in 2 globals
GTM>
3 GO
%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.
The %GO utility corresponds to MUPIP EXTRACT (FORMAT=GO or FORMAT=ZWR).
4 Prompts
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.
4 Ex_of_GO
Examples of %GO
Example:
GTM>DO ^%GO
Global Output Utility
Global ^A
^A
Current total of 1 global
Global ^<RETURN>
Header label: Revenues May, 2002
Output Format: GO or ZWR: ZWR
Output device: /usr/dev/out.go
^A
Total of 1 node in 1 global.
GTM>
3 GSE_
%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.
4 Prompts
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.
4 Ex_of_GSE
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.
3 GSEL
%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.
4 Util_Labels
Utility Labels
CALL Runs %GSEL without reinitializing %ZG.
4 Output_Vars
Output Variables
%ZG Contains array of all globals selected.
4 Prompts
Prompts
Global ^ Requests a global name with optional wildcards or a range
of names.
4 Ex_of_GSEL
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.
2 Rtn_Util
Routine Utilities
The routine utilities are:
%FL Lists the comment lines at the beginning of source programs.
%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.
3 FL
%FL
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, refer to the
section on %RSEL in this chapter.
4 Prompts
Prompts
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.
4 Ex_of_FL
Examples of %FL
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.
3 RCE
%RCE
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, refer to the
section on %RSEL in this chapter.
%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 and completes
processing with a count of replacements and routines changed.
4 Prompts
Prompts
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.
4 Util_Labels
Utility Labels
CALL Works without user interaction unless %ZR is not defined.
4 Input_Vars
Input Variable
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).
4 Ex_of_RCE
Examples of %RCE
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.
3 RD
%RD
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.
4 Prompts
Prompts
Routine: Requests (using %RSEL) the name(s) of the routines to
list; <RETURN> ends the selection.
4 Util_Labels
Utility Labels
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).
4 Ex_of_RD
Examples of %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.
3 RI
%RI
%RI transforms M routines in the sequential format described in the
ANSI standard into individual .m files in GT.M format. Use %RI to make
M RO format accessible as GT.M routines.
4 Prompts
Prompts
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.
4 Ex_of_RI
Examples of %RI
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>
3 RO
%RO
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 uses %RSEL to select routines. For more information, refer to the
section on %RSEL in this chapter.
%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.
4 Prompts
Prompts
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.
4 Util_Labels
Utility Labels
CALL Works without user interaction unless %ZR is not defined.
4 Input_Vars
Input Variables
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.
4 Ex_of_RO
Examples of %RO
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.
3 RSE_
%RSE
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, refer to the
section on %RSEL in this chapter.
%RSE searches for text strings 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 completes processing with a count of occurrences found.
4 Prompts
Prompts
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.
4 Util_Labels
Utility Labels
CALL Works without user interaction unless %ZR is not defined.
4 Input_Vars
Input Variables
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.
4 Ex_of_RSE
Examples of %RSE
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.
3 RSEL
%RSEL
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 UNIX 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.
If a local variable %ZRSET is defined, %RSEL places the output
information into a global variable (^%RSET) instead of the local
variable %ZR.
4 Prompts
Prompts
Routine: Requests the name(s) of the routines; <RETURN> ends
selection.
4 Util_Labels
Utility Labels
CALL Performs %RSEL without reinitializing %ZR.
OBJ Searches only object files.
SRC Searches only source files (same as %RSEL).
4 Input_Vars
Input Variables
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.
4 Output_Vars
Output Variables
%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.
4 Ex_of_RSEL
Examples of %RSEL
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.
2 Internationalization_Util
Internationalization Utilities
The internationalization utilities are:
%GBLDEF Manipulates the collation sequence assigned to a global.
%LCLCOL Manipulates the collation sequence assigned to local
variables in an active process.
%PATCODE Loads pattern definition files for use within an active
database.
These utilities are an integral part of the GT.M functionality that
permits you to customize your applications for use with other
languages. For a description of these utilities, refer to the
"Internationalization" chapter in GT.M Programmers Guide.
2 Sys_Mgmt_Util
System Management Utilities
The System Management utilities are:
%FREECNT Displays the number of free blocks in the database files
associated with the current global directory.
3 FREECNT
%FREECNT
The %FREECNT utility displays the number of free blocks in the database
files associated with the current global directory.
Reference in New Issue View Git Blame Copy Permalink