SET

S{ET}{:postcond} argument,...

argument can be:

• storage ref=expression

• (storage ref{,...})=expression

• piece ref=expression

• character ref=character(s)

• @expr atom

SET assigns the value of an expression to a variable or to a sub-string of a variable. If a list of variable names is enclosed in parentheses on the left hand side of the argument, then all the variables are assigned the value of the expression on the right hand side. The $PIECE and $EXTRACT functions can be used instead of the Variable name on the left side of the equal sign on a SET command. A piece reference has the form: $P{IECE}(storage ref,delimiter{,start field}{,end field}). It allows you to set a sub-string within a string to a given value, in a way that is similar to the way that sub-strings are extracted from strings by the $PIECE function. If the optional $PIECE parameters are not included, the first sub-string is assigned the value of the expression. If the start field is included, then the sub-string it included, all sub-strings between and including those specified by the start and end fields are given the value of the expression. The string specified in the $PIECE or $EXTRACT function will be automatically extended if necessary. With $PIECE, the string is padded with empty pieces using the specified delimiter. With $EXTRACT, the string is padded with blank space.

SET can also be used to assign values to $ECODE, $ETRAP, $X, $Y, $ZERROR, $ZNAME, and $ZTRAP.

The evaluation order in the SET command can affect how M21 determines naked references. Postconditionals cannot be used with arguments, but the $SELECT function can be used to conditionally set arguments.

        ; Set variable ABC to 67
        SET ABC=67

        ; Combine several set statements
        SET A=78,B=6,C="TEXT",D=3+8+9,^TOT(B)=C

        ; Set several variables at once
        SET (A,B,C,D)=0,(X,Y,Z)=^TOT(6)

        ; Set fragment(s) of variables
        SET A="XD\5690\B!G",B="A*S*D*F*G*H*J*K*L",C="",D="-"
        SET $PIECE(A,"\",2)="DINGO"
        SET $PIECE(B,"*",3,4)=99,$P(C,D,10)=""

        ; set specific character in string to new value
        SET A="1234567890"
        SET $EXTRACT(A,7,7)=*

        ; Set various characters to new characters
        S $EXTRACT(A,3,7)="**"

KILL

K{ILL}

K{ILL}{:postcond}

K{ILL}{:postcond} argument,...

argument can be:

• name

• (local{,...})

• @expr atom

KILL deletes the named local or global variable(s). KILL without arguments removes all local variables from your partition. It has no effect on the global variables. When a variable is killed, its value is undefined. Application of $DATA to the variable name produces a value of zero. When a variable name is given as an argument, only that local or global variable is deleted. If the variable does not exist, KILL has no effect. All descendant nodes of a variable are also deleted. If a list of local variables is given as the argument, all local variables except for those in the list are killed.

        ; Remove variable SW and all subnodes that are defined
        ; e.g. SW(5), SW(8,2), SW("Abc") etc.
        KILL SW

        ; Remove several variables and their subnodes. Leave
        ; BILL and other level one nodes such as BILL(1) and
        ; BILL("X"). Nodes such as BILL(3,"Y") etc. will be
        ; removed.
        KILL FRED,^JOHN,BILL(3)

        ; Remove ALL variables except N, ^DF and descendents
        KILL (N,^DF)

MERGE

M{ERGE}{:postcond} argument

argument can be:

• destination Variable = source Variable, {,..)

• @expr atom

The MERGE command copies a local or global variable to another local or global variable. It will also copy all of the descendants of the source variable into the corresponding descendants of the destination variable.

The destination variable cannot be a descendant of the source variable, or vice-versa.

The duration of the MERGE command can be lengthy.

NEW

N{EW}

N{EW}{:postcond}

N{EW}{:postcond} argument,...

argument can be:

• name

• (local{,...})

• @expr atom

NEW saves the values of specified local variables or the special variables $ETRAP, $ESTACK, $TEST, and $ZREFERENCE. The values are restored at the next QUIT statement. The variables are saved in a stack, and are then deleted from the local symbol table. When an implicit or explicit quit is reached, the stacked variables are restored to the local symbol table. The QUIT must not be within the scope of a FOR loop. NEW without arguments saves all variables in the local symbol table.

When a parenthesised list of variables is given for the argument, all variables except those in the list are stacked. All descendant nodes of specified subscripted nodes are also stacked. Only local variables can be saved using NEW. The stack space for saving the variables comes from the user's partition. In programmer direct mode, the effect of NEW is the same as KILL, because no QUIT can be subsequently executed.

A       SET X=34,Y=22 DO NEWTEST
        ; Write X then Y at TAB position 10
        WRITE X,?10,Y
        QUIT
        ;
NEWTEST NEW X
        SET X=7,Y=X*X
        QUIT

>DO A
34        49
>

IF

I{F}

I{F} argument,...

argument can be:

• truth value

• @expr atom

IF controls conditional execution of statements following it on the same line. IF sets $TEST to the truth value of the argument or the truth value of the Boolean AND of all the arguments (evaluated left to right). If no argument is included, the current value of $TEST is used. The statements following the IF statement are executed if $TEST is true (1) and are ignored if $TEST is false (0). Postconditionals cannot be used.

Multiple arguments can be more efficient than one argument containing Boolean AND operators (&) because evaluation of the multiple arguments is terminated when the first false argument is reached.

        IF VAL<0 SET VAL=0

        IF VAL<-1000!(VAL>1000) WRITE "ERROR" GOTO INPUT

        I X'="C"&(X'="A")&(X'="D") WRITE "Must be C, A or D"

        I X'="C",X'="A",X'="D" WRITE "Must be C, A or D"

ELSE

E{LSE}

ELSE conditionally executes the statements following it on the same line depending on the truth value in the $TEST special variable. If $TEST is true, M21 does not execute the remainder of the line to the right of ELSE. If $TEST is false, the remainder is executed. $TEST contains the Boolean result of the last IF command, timed READ, timed LOCK, timed OPEN or JOB commands. ELSE does not effect the value of $TEST. M21 can never execute an ELSE on the same line as an IF statement unless an intervening statement that does not contain an IF statement resets the value of $TEST. In many situations, postconditional expressions or the $SELECT function can replace IF and ELSE statements.

        ; Write Yes or No dependent on value of variable Z
        IF Z=1 WRITE "Yes"
        ELSE  WRITE "No"

FOR

F{OR}

F{OR} local=forparameter,...

forparameter can be:

• expression

• start:step

• start:step:stop

FOR controls the repeated execution of all remaining statements following it on a line for successive values of a local variable. The meaning of FOR depends on the format of the forparameter used as follows.

1. local=expression : M21 gives local the value of expression. It executes all other statements on the same line until it encounters a QUIT or reaches the end of the line, and then evaluates the next line.

2. local=start:step : The remaining statements on the line are executed iteratively, with the local loop variable incremented by step after each iteration. The loop terminates when a GOTO or QUIT is encountered.

3. local=start:step:stop : The remaining statements on the line are executed iteratively, with the local loop variable incremented or decremented by step, depending on whether it is positive or negative. The loop terminates when the loop variable exceeds stop for a positive step, or becomes less than stop for a negative step. The loop is terminated when a QUIT or GOTO is encountered.

The numeric expressions for start,step,and stop can evaluate to integers or decimals. Postconditional expressions cannot be used. Multiple sets of start, start:step, and start:step:stop parameters can be used, but no more than one complete argument can be included. When using multiple sets of parameters, the first start:step parameter is the last one used, because a QUIT or GOTO terminates the entire loop. Subsequent FOR statements on the same line are considered to be nested in left to right order. A GOTO within an inner loop to a point outside the entire nested structure terminates all the nested loops, but a QUIT statement within an inner loop only terminates the inner loop. Argument indirection cannot be used for an entire FOR loop.

Use QUIT and GOTO to terminate the argumentless FOR command.

        ; Write even numbers 10 to 20, each on a new line
        FOR J=10:2:20 WRITE !,J

        ; Input a list of numbers into array A() until a null
        FOR J=1:1 WRITE !,"Number " READ A(J) QUIT:X=""

GOTO

G{OTO}{:postcond} argument,...

argument can be:

• entry ref{:postcond}

• @expr atom

Unconditionally transfers control to the specified line and/or routine. Postconditional expressions can be used with both GOTO and its arguments. If an argument postconditional is false, the argument is ignored. Multiple arguments can be used, but the first argument with no postconditional or with a true postconditional causes an unconditional transfer of control; the remaining arguments are not evaluated. A GOTO within a block structured routine can only transfer control within the same execution block.

        ; Goto LABEL1 if V is zero
        GOTO:V=0 LABEL1
        - or
        GOTO LABEL1:V=0

        ; Run another program from specified label
        GOTO START^PROG12

        ; Branch to appropriate label dependent on input
LABEL5  READ X
        GOTO CREATE:X=1,AMEND:X=2,DELETE:X=3
        WRITE " please enter 1,2 or 3" GOTO LABEL5

        ; Call subroutine to accumulate subtotals if TOT
        ; greater than zero
        DO:TOT>0 SUBTOT
        - rest of main section of program

SUBTOT  ;
        - subtotalling code here
        QUIT

        ; Call several subroutines
        DO INIT,CHOICE,CONFIRM,A^PROG76,TOTALS

        ; Call routine whose name is in variable NAM
        DO @NAM

        ; Create an array, NOD(), holding days in each month
        FOR M=1,3,5,7,8,10,12 SET NOD(M)=31
        FOR M=4,6,9,11 SET NOD(M)=30
        IF YEAR#4=0 SET NOD(2)=29
        ELSE  SET NOD(2)=28

        ; Step through records on a global
        SET ACC=""
        FOR  SET ACC=$O(^CUST(ACC)) QUIT:ACC=""  DO PRINT

QUIT

Q{UIT}{:postcond} {argument}

argument can be:

• expression

QUIT terminates the current flow of execution. If the current flow of execution results from a previous DO or XECUTE command, QUIT returns control to the point immediately after the argument of the DO or XECUTE last evaluated. QUIT terminates the innermost FOR loop in which it occurs. If the FOR loop is not nested, it transfers control to the line following the FOR loop. Appearance of a QUIT in other places within a routine terminates execution of the routine. A QUIT not within a FOR loop restores local variables saved with the NEW command. When a QUIT is encountered in an error handling routine, control is returned to the point immediately following the DO argument in which the routine that caused the error was called.

HALT

H{ALT}{:postcond}

Causes an M21 partition to terminate. Unlocks all variables and closes all devices and files.

        ; Terminate program and log out
        HALT

BREAK

B{REAK}{:postcond} argument,...

argument can be:

• expression

• @expr atom

A BREAK command without arguments will suspend execution of an M routine provided that the M21 debugger ^%MuDbg is active. If debugging is not active the BREAK command will be ignored.

The BREAK command with an argument is used to control recognition of the break key (CTRL+C) or error trapping behaviour dependent on the argument. An argument of 1 will enable recognition of CTRL-C and an argument of 0 will disable recognition.

In certain old versions of Digital Standard MUMPS (DSM) and Micronetics Standard MUMPS (MSM), the system discarded the entire contents of the DO/XECUTE stack when an error occurred. This was done prior to the system passing control to the error-trap routine specified by the $ZTRAP special variable. In newer versions of these implementations of M, as in M21, the DO/XECUTE stack remains at the same level when an error occurs.

Existing applications that rely on the DO/XECUTE stack being cleared using the error trapping techniques provided in these early versions of M will not work properly. The recommended solution to this problem is to modify the error-trapping code so that it does not rely on these outdated techniques. However, this may not be possible in all cases. As a convenience to our users, a compatibility mode has been provided which enables error processing to behave as it did in these old versions of M.

The compatibility mode has been implemented as an extension to the BREAK command. The following describes the implemented compatibility extensions:

When a job is started, the default value is normal M21 error trapping (BREAK -2). To enable the old style of error trapping, a BREAK command with an argument 2 (BREAK 2) is inserted at the beginning of the application before any other code is executed. It is strongly recommended that applications be modified to take advantage of the new error processing capabilities.

XECUTE

X{ECUTE}{:postcond} argument,...

argument can be:

• expression:{postcond}

• @expr atom

XECUTE can execute M21 statements that result from the process of expression evaluation. Each XECUTE argument must evaluate to a string containing M21 statements. The string should not contain a TAB character at the beginning or a carriage return at the end. Each XECUTE argument is therefore like a one line subroutine. If an XECUTE argument contains a FOR command, the implicit QUIT is beyond the scope of the FOR, (the XECUTE argument behaves as if it were a two line subroutine with the second line containing only the QUIT statement).

If an XECUTE statement contains a DO command, the routines specified in the DO arguments are executed. When QUIT is encountered, control returns to the point immediately following the DO argument. Postconditionals used with arguments cause conditional execution of the arguments. If an XECUTE contains a GOTO command, control is transferred to the point specified in the GOTO command, and is returned following a QUIT to the point following the XECUTE argument that contained the QUIT.

        SET ZZ="FOR J=1:1:5 WRITE J"
        XECUTE ZZ

OPEN

O{PEN}{:postcond} argument,...

argument can be:

• device{:{params}:timeout}

• @expr atom

OPEN obtains ownership of one or more devices. For any device except the principal device, an OPEN command must be issued to reserve the device before issuing a USE command to direct all input and output operations to it. (ZUSE is an exception to this rule.) The arguments for OPEN consist of one or more valid device specifiers and their modifying parameters. If parameters are not included, M21 uses default system parameters. The effects of modifying parameters last until the device is closed with a CLOSE command or you leave M21 using a HALT command.

Two users cannot own the same device. Timeouts can be used to avoid suspension of execution. If the device cannot be opened during the time period specified, $TEST is set to false. If the device is successfully opened, $TEST is set to true. Opening a device does not make it the current input/output device. That is the function of the USE command. See individual device types in the devices documentation for a description of the OPEN parameters.

        ; Open device 8100 (printer), wait if necessary  NB 8100 is M21 printer, under MSM it would be 3
        OPEN 8100

        ; Open DEV but don't wait if not available
        OPEN DEV::0
        IF '$TEST WRITE "Not Available" GOTO START

USE

U{SE}{:postcond} argument

argument can be:

• device{:params}

• @expr atom

USE makes the device specified in its argument the current I/O device. Unless the device is the principal device, it must have previously been opened with an OPEN command. All I/O is performed with the device until it is subsequently either closed with a CLOSE command or another USE is executed for a new device or an error occurs for which no trap is set, or a HALT command is executed. If parameters are not included in the argument, system default values are used. The $IO special variable contains the specification of the current device. $X, $Y, $ZA, $ZB and $ZC reflect the state of the device that is currently being used.

READ

R{EAD}{:postcond} argument,...

argument can be:

• format

• string

• local{:timeout}

• local{#inp field}{:timeout}

• *local{:timeout}

• @expr atom

READ receives data from the current device. The action READ performs depends on the argument format you use. If an argument consists of formatting characters, the specified horizontal and vertical spacing is performed, and the values of $X and $Y are updated. If an argument consists of a string, it is written out to the current device (if that device accepts output) and $X is updated. If an argument is a local variable name, a string of up to 255 characters is read from the current device and assigned to the variable, and $X is updated. If an optional input field parameter is included, the string read from the current device is of length specified by the parameter.

If an * precedes a local variable name as an argument, the decimal equivalent for the ASCII code for the next character input is assigned to the variable. Use timeouts to avoid prolonged suspension of execution. If a complete input is not accomplished before the period specified in the timeout parameter, the $TEST variable is set to 0. Otherwise, $TEST is set to 1. Incomplete input strings are assigned to the local variable. Type-ahead is supported except when the local variable is preceded by formatting commands. If the optional inp field parameter has a value of 0, an error is returned. The READ inp field parameter takes precedence over USE command buffer length parameters.

        ; Input variable X from current device
        ; Terminate read when <RETURN> or other
        ; terminator pressed
        READ X

        ; Input a single character as ASCII value into X
        READ *X

        ; Input variable X but terminate read after 8
        ; characters or when <RETURN> pressed
        READ X#8

        ; Input variable X but terminate read after 10
        ; seconds or when <RETURN> pressed
        READ X:10

WRITE

W{RITE}{:postcond} argument,...

argument can be:

• format

• expression

• *integer

• @expr atom

WRITE sends data and/or control information to the current device. If an argument is comprised of one or more formatting characters, WRITE performs the horizontal and/or vertical spacing and updates the values of $X and $Y. If the argument is an expression, the value of the expression is written to the current device and $X is updated. If the argument consists of an * preceding an integer, the ASCII character whose code is equal to the integer is written to the current device, but $X and $Y are not changed. WRITE *12 and WRITE *10 are not equivalent to WRITE # and WRITE !. Remember to begin or end WRITE statements with a carriage-return/line-feed formatting character to prevent overwriting lines, and also after the last line output on a printer.

CLOSE

C{LOSE}{:postcond} argument,...

argument can be:

• device{:params}

• @expr atom

CLOSE releases ownership of one or more specified input/output devices and, optionally, performs device dependent functions prior to the release. CLOSE will not return control to the routine calling it until the device is closed. See the devices documentation for possible parameters to the CLOSE command.

        ; Close device 8100 (printer in M21, would be device 3 in MSM)
        CLOSE 8100

        ; Close device number held in variable DEV as long as
        ; it is not the same as the device number held in
        ; variable VDU
        CLOSE:DEV'=VDU DEV

HANG

H{ANG}{:postcond} argument,...

argument can be:

• seconds

• @expr atom

HANG suspends execution for specified number of seconds. If the integer expression for seconds is 0 or negative, the HANG is ignored. If a decimal expression is used, it is truncated to an integer.

       ; Display message for 3 seconds before starting again
       WRITE !,MESS HANG 3 GOTO START

LOCK

L{OCK}

L{OCK}{:postcond}

L{OCK}{:postcond} {±}argument{:timeout},...

argument can be:

• name

• (name{,...})

• @expr atom

LOCK makes a specified variable or specified nodes of a variable unavailable for locking by another user. LOCK without arguments unlocks all previously locked variables. It does not lock any other variables. LOCK with a local variable name as an argument prevents all other users from locking local variables of the same name. LOCK with a global variable name as an argument prevents all other users in the same UCI from locking the global.

An argument consisting of a parenthesised list of variable names acquires locks on all the variables listed, waiting if necessary, until all are free. All descendants of a node locked using the LOCK command are also locked. LOCK is a convention. It does not prevent simultaneous access of variables. Use timeouts to avoid potentially long suspension of execution. A timeout does not unlock previously locked variables. LOCK sets $TEST to indicate whether it has locked the specified variables or not.

Another form of locking supported by the LOCK command is the incremental lock. When this is used the LOCK command does not release existing locks owned by that job. Instead it locks (if a + sign is used) or unlocks (if a - sign is used) each of the variables in a left to right order.

        ; Lock customer record and subnodes for updating
        ; This will wait until anyone else's prior locks
        ; have been released
        LOCK ^CUST(ACC)

        ; Attempt to lock record but only wait 5 seconds
        LOCK ^CUST(ACC):5 IF '$TEST WRITE "in use" GOTO IU

        ; Unlock customer record
        LOCK

	; show incremental lock
	 LOCK +(^SUPP(SUPP),-^CUST(ACC)

JOB

J{OB}{:postcond} {argument}

argument can be:

• entry ref{[UCI{,SYS}]}{:size}{:timeout}

• @expr atom

JOB starts a specified routine in a new partition. Normally, you can only start routines in your own UCI, but in the system manager's account, routines under any UCI or on remote M21 systems can be started. If M21 is able to create a partition and start the specified routine it sets $TEST to true and $ZINFO(1,"pvector","zjobno") to the job number assigned to the started routine. If M21 is not able to create a partition and start the routine it sets $TEST to false. The symbol table for the new partition is empty, and the new partition does not own any devices. The new partition has the same principal device as the partition that initiated it.

ZALLOCATE

ZA{LLOCATE}

ZA{LLOCATE}{:postcond}

ZA{LLOCATE}{:postcond} argument{:timeout},...

argument can be:

• name

• (name{,...})

• @expr atom

ZALLOCATE makes a specified variable or specified nodes of a variable unavailable for locking by another user. ZALLOCATE without arguments does nothing. ZALLOCATE with a local variable name as an argument prevents all other users from locking local variables of the same name. ZALLOCATE with a global variable name as an argument prevents all other users in the same UCI from locking the specified global.

An argument consisting of a parenthesised list of variable names acquires locks on all the variables listed, waiting if necessary, until all are free. All descendants of a node locked using the ZALLOCATE command are also locked. ZALLOCATE is a convention. It does not prevent simultaneous access of variables. Use timeouts to avoid potentially long suspension of execution. ZALLOCATE sets $TEST to indicate whether it has locked the specified variables or not.

Unlike the simple form of the LOCK command, ZALLOCATE does not release existing locks. Instead it locks each of the variables in a left to right order. In this respect it is equivalent to the LOCK + command.

The ZALLOCATE command is for backwards compatibility with existing applications written for other M systems. The incremental locking and unlocking capabilities of the LOCK command should be used instead.

        ; Lock customer record and subnodes for updating
        ; This will wait until anyone else's prior locks
        ; have been released
        ZALLOCATE ^CUST(ACC)

        ; Attempt to lock record but only wait 5 seconds
        ZALLOCATE ^CUST(ACC):5 IF '$TEST WRITE "in use" GOTO IU

ZDEALLOCATE

ZD{EALLOCATE}

ZD{EALLOCATE}{:postcond}

ZD{EALLOCATE}{:postcond} argument{:timeout},...

argument can be:

• name

• (name{,...})

• @expr atom

The ZDEALLOCATE command unlocks one or more variables that were locked using the ZALLOCATE command. Without arguments all variables for the current job that were locked with the ZALLOCATE command are unlocked. In the form with arguments, only the variables named as arguments are unlocked. The ZDEALLOCATE command does not operate on variables that were locked using the LOCK command. It can only be used for variables locked with the ZALLOCATE command.

The ZDEALLOCATE command is for backwards compatibility with existing applications written for other M systems. The incremental locking and unlocking capabilities of the LOCK command should be used instead.

        ; Unlock customer record and subnodes
        ZDEALLOCATE ^CUST(ACC)

        ; Unlock all variables locked with ZALLOCATE
        ZDEALLOCATE

ZGO

ZG{O}{:postcond}

The ZGO command resumes execution of a routine that has been suspended by a BREAK command. The BREAK command will suspend routine execution when the interactive debugger ^%MuDbg is used to invoke the routine. If changes are made to the routine while it is suspended, then ZGO will not be able to restart the routine.

ZHANG

ZH{ANG}{:postcond} argument,...

argument can be:

• milliseconds

• @expr atom

ZHANG suspends execution for specified number of millseconds. If the integer expression for seconds is 0 or negative, the ZHANG is ignored. If a decimal expression is used, it is truncated to an integer.

       ; Display message for 1/2 second before starting again
       WRITE !,MESS ZHANG 500 GOTO START

ZHOROLOG

ZHO{ROLOG}{:postcond} {{±}date: {±}Time}}

• date is a date value in $HOROLOG format

• time is a time value in $HOROLOG format

ZHOROLOG is used to temporarily adjust the date and/or time that are returned by the $HOROLOG function. When a date or time is specified preceded by +or -, the value is added to or subtracted from the date or time part of the system $HOROLOG. If no sign is specified, the value specified becomes the new date or time value of $HOROLOG.

If either date or time is omitted, then that portion of $HOROLOG will be reset to the system date or time. The ZHOROLOG command only affects the value of the $HOROLOG special variable for the partition issuing the ZHOROLOG command.

       ; Set the date forward by 10 days
       ZHOROLOG +10

ZINSERT

ZI{INSERT} {:postcond} argument

argument can be

• expression {:lineref}

• @expr atom

ZINSERT inserts a line of code into the current routine

ZLOAD

ZL{OAD}{:postcond} {argument,...}

argument can be:

• routine

• @expr atom

ZLOAD loads a routine from the routine directory or from the current device into the routine buffer in the partition. ZLOAD without arguments will transfer a routine from a device. An OPEN and a USE command must first be issued. ZLOAD with an argument loads the specified routine from the routine directory into the partition. In both cases, the implicit edit buffer pointer is left pointing at the last line of the routine. Name and argument indirection can be used with ZLOAD. When ZLOAD loads a routine, it deletes any routine that is currently in the partition. Use ZLOAD only in command lines or in XECUTE arguments and not in routine lines.

ZMTRACE

ZM{TRACE}{:postcond} {argument,...}

• argument can be 1 or 0

The ZMTRACE command is used to turn on tracing of program flow as an aid to debugging. An argument value of 1 is used to enable tracing and a value of 0 will disable tracing.

ZPRINT

ZP{RINT}{:postcond}

ZP{RINT}{:postcond} {start}{:end}

• start is a starting line reference

• end is an ending line reference

The ZPRINT command outputs one or more lines of a routine to the current device. With no arguments supplied the whole routine is written out. Following the command the line pointer used by the edit buffer is set to the end of the routine.

With two arguments, lines from start, to end, are output to the current device. If only start is specified, that single line is output to the current device. If end is specified as null, all lines from start to the end of the routine are output. In all these cases, the line pointer used by the edit buffer is set to the last line output.

ZQUIT

ZQ{UIT}{:postcond}

A ZQUIT command is used in an error handler to return to the next highest execution level that has an error trap set. If there are no higher-level error traps then the system will return to the highest execution level.

ZREMOVE

ZR{EMOVE}{:postcond} {argument,...}

argument can be:

• start ref{:end ref}

• start spec{:end spec}

• @expr atom

ZREMOVE deletes the current routine or specified lines in the current routine. ZREMOVE without arguments deletes the entire routine from the partition. It does not affect the value of any defined local variables. ZREMOVE with arguments deletes only the specified lines from the routine. ZREMOVE with one line reference or line specification as an argument deletes the routine line specified. ZREMOVE with two line references or specifications separated by a colon deletes all lines from the first specified through to the second specified.

The line pointer used by the edit buffer is set to point at the line before the first line deleted in the last argument. If the beginning and ending lines specified in a two-part argument do not occur one before the other in the routine, no lines are deleted. If the ending line does not exist, all lines from the beginning line to the end are deleted. Use ZREMOVE only in command lines or XECUTE arguments and not in routine lines. To delete a routine from your routine directory, you can use a ZREMOVE without arguments followed by a ZSAVE with the name of the routine to be removed as its argument.

ZSAVE

ZS{AVE}{:postcond}

ZS{AVE}{:postcond} argument,...

argument can be:

• routine

• @expr atom

ZSAVE writes the routine currently in memory to the routine directory. If a name has been previously associated with the routine, ZSAVE can be used without an argument. If not, or if the routine is to be stored under a new name, then the new name must be entered as an argument. ZSAVE does not affect the implicit line pointer. ZREMOVE without arguments followed by a ZSAVE with the name of a routine in the routine directory has the effect of deleting the routine.

ZTRAP

ZT{RAP}{:postcond} argument,...

argument can be:

• string

• @expr atom

ZTRAP is used to force an error condition causing routine execution to be terminated in the same manner as any other type of error with any error traps being followed. The argument must evaluate to a string, which gives a user-defined indication of the error type. This string can be up to 77 characters long and will be added to the letter Z to produce the error code in the error message. If the argument is null or not specified, then a default value of TRAP is used.

        ; Trap with the error message <ZApplication Error>
        ZTRAP "Application Error"

        ; Trap with the error message <ZTRAP>
        ZTRAP

ZUSE

ZU{SE}{:postcond} argument,...

argument can be:

• a device identifier

• @expr atom

ZUSE temporarily gains ownership of a terminal device that could be owned by another job. The ZUSE command makes the specified device, which must be a currently active terminal device, current without using the OPEN and USE commands. Only the WRITE command can be used with a device that has been temporarily acquired by means of the ZUSE command.

ZWRITE

ZW{RITE}{:postcond}

ZW{RITE}{:postcond} argument,...

argument can be:

• local variable name

• @expr atom

ZWRITE displays the values of local variables and their descendants on the current device. If no arguments are supplied, all local variables are displayed.

$ASCII

$A{SCII}(string{,position})

$ASCII returns the decimal ASCII value of the character at the specified position in the specified string. If the string is empty or if the integer value in the position argument is larger than the number of characters in the string, $ASCII returns -1. If the position argument is not included, the ASCII decimal value of the first character in the string is returned.

$CHAR

$C{HAR}(ASCII code{,...})

$CHAR returns the ASCII equivalent of the integer specified in the argument(s). The arguments used are integer-valued expressions with values ranging from 0 to 255. If an argument has a value less than 0, it returns the null string. Non-integer arguments are truncated to integers. Formatted writes cannot, in general, be produced with $CHAR. Escape sequences can be generated on video display terminals with $CHAR.

$EXTRACT

$E{XTRACT}(string{,start pos}{,end pos})

$EXTRACT returns a sub-string from a specified position in a string. If there is one argument, it returns the first character from the specified string. If there are two arguments, the character at the position specified in start pos is returned from the specified string. If three arguments are supplied, the characters from start pos to end pos are returned from the specified string. If decimal values are given for the last two arguments, they are truncated and used as integers. In the two-argument form, if start pos is greater or less than the possible positions in the string, it returns a null string. In the three-argument form, if start pos is greater than end pos, it also returns the null string.

$FIND

$F{IND}(string,substring{,position})

$FIND returns an integer specifying the end position of a specified substring within a specified string. $FIND begins searching with the first character of the specified string if there is no position argument. Otherwise, it begins searching at the character specified by the position argument. If $FIND does not find the substring, it returns a 0. If $FIND finds the substring, it returns an integer value that represents the position of the character immediately to the right of the substring. $FIND ends its search with the first, leftmost occurrence of substring and returns only the position of the character immediately to the right of that occurrence.

Decimal position arguments are truncated and used as integers. If the substring argument is null, $FIND returns a 1 in the two argument case and returns the value of the position argument in the three argument case. If the string argument is null, $FIND returns 0 in either case.

$JUSTIFY

$J{USTIFY}(string,field{,decimal field})

$JUSTIFY returns a specified string right-justified in a field of a specified length. The two-argument form of $JUSTIFY returns the string right-justified in a field of spaces whose total length is specified in the field argument. The three-argument form of $JUSTIFY converts the string into a numeric expression and returns it as a decimal number in a field whose total length is specified in the field argument and whose fractional length is specified in decimal field. In the three-argument form, the length of the field includes the decimal point and possibly the sign and a leading zero. The string is returned unjustified if the field argument is less than the number of characters in the string. The decimal field argument cannot be negative. If more places after the decimal point are present in the string than in the result, the result is rounded.

$LENGTH

$L{ENGTH}(string{,delimiter})

$LENGTH returns either the number of characters in a specified string or the number of sub-strings in the specified string. The one argument form returns the number of characters. The two argument form returns the number of sub-strings separated by the string specified in the delimiter argument. The length of a null string is 0. If the string argument is null in the two argument format, $LENGTH returns 1. If delimiter is null, it returns 0.

$PIECE

$P{IECE}(string,delimiter{,start field{,end field})

$PIECE returns the specified sub-string from the specified string. A string is composed of a series of sub-strings separated by delimiters, which are themselves strings or characters. The sub-strings have positions relative to the delimiters. The two-argument form of $PIECE returns the sub-string located before the first occurrence of delimiter. The three-argument form returns the Nth sub-string where N = start field. The four argument form returns the Nth through the Mth sub-strings, where N = start field and M = end field. The sub-string returned includes intermediate occurrences of delimiter.

In the three-argument form, if start field is less than one or; if start field - 1 is greater than the number of delimiting sub-strings, then the null string will be returned. In the four-argument form, if start field is less than one, it is read as one. If end field is greater than the number of delimiters, it is read as the end of the string. If start field is greater than end field, or end field is less than one, $PIECE returns a null string. For both the three and four argument forms, if the delimiter is null or start field - 1 is less than the number of delimiters, then the null string will be returned. If delimiter does not occur in the string, and the start field is one, then the entire string will be returned.

$REVERSE

$RE{VERSE}(string)

Reverses the order of characters in a specified string

	S A="ABCDEF"
	S B=$REVERSE(A)

$TEXT

$T{EXT}(argument)

argument can be:

• entry ref

• line ref

• line spec

$TEXT returns the specified line from the current or specified routine as a string. $TEXT replaces the TAB character with a space character and does not recognize the RETURN that terminates the line. If the line reference or line specification is to a line that does not appear in the body of the routine, $TEXT returns a null string. A line specification of +0 will return the routine name.

$TRANSLATE

$TR{ANSLATE}(string,from{,to})

$TRANSLATE performs a character for character replacement upon a string, by taking each character in the from string and changing each occurrence of that character in string to the equivalent character in the to string. If the from string is greater in length than the to string, then characters in from which have no corresponding character in to are removed from string. If to is not specified, every character in from is removed from string. If the length of to is greater than from, any extra characters are ignored.

$DATA

$D{ATA}(variable name)

$DATA returns an integer that indicates whether a variable is defined or undefined and whether the variable has any descendants.

The following values can be returned by $DATA:

0 - variable has no data value and no descendants (variable is undefined).
1 - variable has a data value but no descendants.
10 - variable has no data value but has descendants.
11 - variable has a data value and has descendants.

$FNUMBER

$FN{UMBER}(number,code string{,decimal field})

$FNUMBER evaluates the code string and returns the number string with decimal field number of decimal places, formatted as follows dependent on the code string:

+ - inserts a + sign on numbers greater than zero
- - suppresses the negative sign on negative values by default
, - Inserts delimiters every third position to the left of the decimal point
T - Places any signs (default or forced) after the string
P - Places a negative number in parentheses, spaces if the number is positive

$GET

$G{ET}(variable name{,default})

Returns the data value of a specified variable. Without $GET, an undefined variable can return an error, dependent on system settings. If the variable does not exist ($DATA=0 or 10), $GET returns the value specified by default or null if no value is specified.

$NAME

$NA{ME}(variable name{,subscripts})

$NAME returns a string value which is a full local or global reference denoting either all or part of the specified variable. If the subscripts argument is not specified or is zero the value returned is the variable name. Otherwise the function returns a full local or global reference containing up to the specified number of subscripts.

$ORDER

$O{RDER}(variable name{,direction})

$ORDER returns the next or previous subscript in collating sequence of a specified global or local array. The specified node must have at least one subscript. If a naked reference is used, then the naked indicator must be defined. If no sibling exists, the function returns null. The null string is used to enable the function to return the first subscript at this level. The subscripts for global variables are returned in the collating sequence in which the global was created, whilst the subscripts of local variables are returned in numeric collating sequence.

The parameter direction can have a value of 1 or -1. If it is not specified or has a value of 1, then the next subscript value that follows the final subscript in variable name will be returned. If it evaluates to -1, the function will return the previous subscript for the variable. If the final subscript in variable name is null, then the value of the first or last subscript at that level is returned, depending on the value of direction.

$ORDER is also used to traverse the local symbol table. If variable name is an un-subscripted local variable $ORDER will return the next defined local variable or null if there is none. The starting point for this traversal is $ORDER() to return the name of the first or last local variable in the partition, dependent on the direction parameter.

$ORDER is also used to traverse the global and routine directories. Specifying an un-subscripted global variable name as a parameter to $ORDER will return the name of the next global in the global directory. Using a pseudo global name consisting of the space character followed by a routine name will return the name of the next routine in the routine directory.

$QLENGTH

$QL{ENGTH}(variable name)

$QLENGTH returns an integer value indicating the total number of subscripts in a local or global reference.

$QSUBSCRIPT

$QS{UBSCRIPT}(variable name,position)

$QSUBSCRIPT returns the value of the subscript within variable name at position. A position value of -1, returns the environment information if present and a value of 0 returns the local or global name.

$QUERY

$Q{UERY}(variable name{,direction})

$QUERY returns the next or previous local or global variable node that is defined and has data. The variable name must be a local or global variable. The parameter direction can have a value of 1 or -1. If it is not specified or has a value of 1, then the next defined node that variable name will be returned. If it evaluates to -1, the function will return the previous defined node of the variable.

$RANDOM

$R{ANDOM}(integer)

$RANDOM returns a pseudo-random integer between 0 and one less than the specified integer value. The value of the specified integer must be nonzero.

$SELECT

$S{ELECT}(truth value:expression{,...})

$SELECT returns the value of the first (leftmost) expression in its argument list whose matched truth-valued expression is true. Each $SELECT argument is a pair of expressions separated by a colon. The left half of the pair is a truth-valued expression. The right half of the pair can be any expression. $SELECT evaluates the arguments from left to right. When $SELECT discovers a truth-valued expression with the value of one (true), it returns that truth-valued expression's matching right expression. $SELECT stops evaluation after it discovers the leftmost true truth-valued expression. It never evaluates later pairs. If all truth-valued expressions in an argument list are false, M21 produces an error.

$STACK

$ST{ACK}(level{,string})

The single operand $STACK function provides the following information about the execution stack.

• If level evaluates to -1, the function returns the current execution nesting level. The $STACK special variable returns the same value as $STACK(-1).

• If level evaluates to 0 and if the partition was initiated via the JOB command, the function returns 1. Otherwise, it returns 0.

• If level evaluates to a positive integer that is less than or equal to $STACK(-1), the function returns a value that indicates how that execution level was initiated. If initiated by a command, the function returns the name of the command fully spelled out and in uppercase (for example: DO or XECUTE). Otherwise, if it was initiated by an extrinsic function or variable, then the function returns $$.

• If level evaluates to a value greater than $STACK(-1), the function returns an empty string.

• All other values of level are reserved for future extensions.

The two-operand $STACK function provides information about the execution level specified using the first operand. The second operand specifies the information to return. This operand can be in uppercase, lowercase, or mixed case, all being equivalent.

• If string evaluates to ECODE, the function returns the list of error codes added at this level or the empty string if no errors occurred at this level.

• If string evaluates to MCODE, the function returns the text of the line identified by $STACK(Level,"PLACE").

• If string evaluates to PLACE, the function returns the last command executed at the specified level. If the location is a routine line, the format of the function value is +offset^routine. If the location is an XECUTE command string, the function returns the at-sign character (@).

• All other values of string are reserved for future extensions.

$ZBAND

$ZBA{ND}(bit string1,bit string2)

$ZBAND returns a bit string that is the result of logically ANDing the string specified by the bit string1 parameter with the string specified by the bit string2 parameter. The length of the resulting bit string is equal to the length of bit string1, if the length of bit string1 is less then the length of bit string2. Otherwise, it is equal to the length of bit string2.

$ZBCOUNT

$ZBC{OUNT}(bit string{,bitval})

$ZBCOUNT returns a number that equals the number of times that bitval appears bit string. If bitval is not specified, a value of 1 is assumed.

$ZBFIND

$ZBF{IND}(bit string,bitval{,bitpos})

$ZBFIND returns a number one greater than the position of the first occurrence bitval in bit string. If specified, the search begins at bitpos location. This function is the equivalent of $FIND for bit strings.

$ZBGET

$ZBG{ET}(bit string,bitpos)

$ZBGET returns the value of the bit that appears in the bit string at the location specified by the bitpos parameter.

$ZBLEN

$ZBL{EN}(bit string)

$ZBLEN returns the count of the number of bits in the specified bit string.

$ZBNOT

$ZBN{OT}(bit string)

$ZBNOT returns a bit string that is the inverse of the string specified by the bit string parameter.

$ZBOR

$ZBO{R}(bit string1,bit string2)

$ZBOR returns a bit string that is the result of logically ORing the string specified by the bit string1 parameter with the string specified by the bit string2 parameter. The length of the resulting bit string is equal to the length of bit string1, if the length of bit string1 is less then the length of bit string2. Otherwise, it is equal to the length of bit string2.

$ZBSET

$ZBSE{T}(bit string,bitpos,bitval)

$ZBSET returns a string equal to the string specified by the bit string parameter, with the bit specified by bitpos set to the value specified by bitval.

$ZBSTR

$ZBST{R}(bit size{,bitval})

$ZBSTR returns a bit string of length bit size, rounded up to a multiple of eight bits. All bits in the string are set to bitval, which defaults to zero if no specified.

$ZBXOR

$ZBX{OR}(bit string1,bit string2)

$ZBXOR returns a bit string that is the result of logically EXCLUSIVE ORing the string specified by the bit string1 parameter with the string specified by the bit string2 parameter. The length of the resulting bit string is equal to the length of bit string1, if the length of bit string1 is less then the length of bit string2. Otherwise, it is equal to the length of bit string2.

$ZBOOLEAN

$ZB{OOLEAN}(expr1,expr2,bit mask)

$ZBOOLEAN performs the bitwise logical operation specified by the bit mask on expr1 and expr2.

$ZDATE

$ZD{ATE}(horolog{,format{,flag}})

$ZDATE converts horolog, which is the number of days since December 31, 1840, to an external date representation. The external format is determined by the value of the format parameter, which can have the following values:

1. MM/DD/YY where MM is the month, DD is the day, and YY is the year.

2. DD MMM YY where DD is the day, MMM is the three-character month, and YY is the year.

3. DD/MM/YY where DD is the day, MM is the month, and YY is the year.

The default for format is 1. If the year is in the current century, then the century is not included unless flag is 1.

$ZDEVICE

$ZDEV{ICE}(device)

$ZDEVICE returns the external name for a terminal port identified by the M21 device number device.

$ZHEX

$ZH{EX}(expr)

$ZHEX converts a hexadecimal value to decimal or vice-versa. If expr evaluates to a string, it is treated as a hexadecimal number and if it evaluates to an integer it is treated as a decimal number.

$ZINFO

$ZI{NFO}(OpType(,Param1{...,Param5}})

The $ZINFO function provides access to information held in system structures and tables. This access is read only or read/write depending on the validity of the operation on the structure or table supplied as a parameter to the function.

OpType denotes a numeric value denoting the type of operation to be performed.

Param1...Param5 Parameters that vary in number and type depending on the value of OpType.

The $ZINFO function examines the contents of in memory structures or internal variables and returns a value to the left-hand side of the calling expression. Some forms of $ZINFO simply return the value of elements in structures or tables, whilst others allow modification of those elements. The following table shows the various forms of the $ZINFO function together with the parameters allowed for each type:

The tables/structures that can be accessed using $ZINFO are as follows:

W $ZINFO(6,"pvector","Pbrena",10)

W $ZINFO(8,"pvector","Pbrena",0,12)

W $ZINFO(8,"pvector","LONG_RTNLINES",1,$JOB)

W $ZINFO(4,"FIRSTFILEDDB")

W $ZINFO(4,"MAXILOCKDDBS")

$ZSOCKET

$ZSO{CKET}(socket,handle,identifier)

$ZSOCKET is used to return implementation specific information on the sockets in use. See the devices documentation for details.

$ZTEXP

$ZTEXP(param)

$ZTEXP raises e to the power of the supplied parameter - note must be spelled in full.

$ZTLOG

$ZTL{OG}(param)

$ZTLOG computes the natural logarithm of the supplied parameter.

$ZUCI

$ZU{CI}(UCIname{,SYSname})

$ZU{CI}(UCIno{,SYSno})

$ZUCI returns the UCI name if UCIno is specified and the UCI number if UCIname is specified. For compatibility with MSM the string returned is of the form UCI name or number followed by a comma and then the system name or zero. In M21 there is only one database per system and no concept of volume groups, so the second piece returned by the function will always be either equal to the system name or zero. Similarly, for compatibility, it is possible to specify a second parameter of SYSname or SYSno to the $ZUCI function, but the function will return null, if this is not the actual system name or the number zero.

If UCIname is specified, $ZUCI returns the number of the specified UCI followed by zero, separated by a comma. If UCIname is specified as the null string, details for the current UCI are returned.

If UCIno is specified, $ZUCI returns the name of the specified UCI followed by the three-character system name, separated by a comma. If UCIno is zero, details for the current UCI are returned.

If either parameter specifies a UCI or system that does not exist, then the $ZUCI function will return the null string.

$ZXCALL

$ZX{CALL}(operation number,param)

The $ZXCALL function is the general XCALL housekeeping interface. See the External Calls documentation for details.

ADD (+)

operand + operand

Binary ADD produces the sum of two numerically interpreted operands. The result of the operation will be accurate to a maximum of 17 digits precision.

AND (&)

operand & operand

Binary AND tests whether both of its operands have a truth value of true.

CONCATENATE ( _ )

operand_operand

Binary CONCATENATE produces a string composed of the right operand appended to the left operand.

DIVIDE (/)

operand A/operand B

Binary DIVIDE produces the quotient that is the result of dividing two numerically interpreted operands. The result of the operation will be accurate to a maximum of 17 digits precision.

EQUALS (=)

operand = operand

Binary EQUALS compares two operands for equality.

EXPONENTIATION (**)

operand A**operand B

Raises the operand A to the power specified by operand B. The result of the operation will be accurate to a maximum of 17 digits precision.

GREATER THAN (>)

operand A>operand B

Binary GREATER THAN tests whether operand A is numerically greater than operand B.

HEXADECIMAL (#)

#operand

Treats the operand as representing an hexadecimal number and converts it to a decimal value.

INCLUSIVE OR (!)

operand!operand

Binary INCLUSIVE OR tests whether one or both of its operands have a truth value of true.

INTEGER DIVIDE (\)

operand A\operand B

Binary INTEGER DIVIDE produces the integer result of the division of operand A by operand B.

LESS THAN (<)

operand A< operand B

Binary LESS THAN tests whether operand A is numerically less than operand B.

MINUS (-)

-operand

Unary MINUS gives the operand an opposite numeric interpretation.

MODULO (#)

operand A#operand B

Binary MODULO returns the remainder that is the result of integer division.

MULTIPLY (*)

operand*operand

Binary MULTIPLY produces the product of two numerically interpreted operands.

NOT (')

'operand

'operator

Unary NOT inverts the truth value of the Boolean operator or operand it modifies.

STRING CONTAINS ([)

operand A[operand B

Binary CONTAINS tests whether the sequence of characters in the right operand is a substring of the left operand.

STRING FOLLOWS (])

operand A] operand B

Binary FOLLOWS tests whether the characters in the left operand come after the characters in the right operand in ASCII collating sequence.

STRING SORTS AFTER (]])

operand A]] operand B

This tests whether the string specified by the operand A follows the string specified by operand B in the subscript collating sequence.

PLUS (+)

+operand

Unary PLUS gives its operand a numeric interpretation.

SUBTRACT (-)

operand A-operand B

Binary SUBTRACT produces the difference between two numerically interpreted operands.