Copyright: REF.HLP, documentation for MSM-Server 4.4.0 and MSM-Workstation 2.0.0, copyright © 1998 Micronetics Design Corporation   Wednesday, April 15, 1998 15:16:51
Citation: Extract from REF.HLP, documentation for MSM-Server 4.4.0 and MSM-Workstation 2.0.0, copyright © 1998 Micronetics Design Corporation


Help Contents
Contents

Preface

Language Syntax

Expression Elements

MSM Operators

MSM Commands

MSM Functions

MSM Special Variables

MSM Structured System Variables

ASCII Collating Sequence

Error Processing

Mnemonic Namespaces

User-Defined Commands

Macro Facility


Preface

Acknowledgment

Documentation Conventions


Language Syntax

Overview

MSM Character Set

Language Components

Command Lines and Routines

Data Types

Variables

Objects


Expression Elements

Overview

Building Expressions

Evaluating Expressions

Numeric Expressions

String Expressions

Truth-Valued Expressions

Post-Conditional Expressions


MSM Operators

Overview

ADDITION (+)

AND (&)

CONCATENATE ( _ )

DIVISION (/)

EQUAL TO (=)

EXPONENTIATION (**)

GREATER THAN (>)

HEXADECIMAL (#)

INDIRECTION (@)

INTEGER DIVISION (\)

LESS THAN (<)

MINUS (-)

MODULO DIVISION (#)

MULTIPLICATION (*)

NOT (')

OR (!)

PATTERN MATCH (?)

PLUS (+)

STRING CONTAINS ([ )

STRING FOLLOWS (])

STRING SORTS AFTER (]])

SUBTRACTION ()


MSM Commands

Overview

BREAK

CLOSE

DO

DO with Parameter Passing

ELSE

FOR

GOTO

HALT

HANG

IF

JOB

JOB with Parameter Passing

KILL

LOCK

MERGE

NEW

OPEN

QUIT

READ

SET

TCOMMIT

TRESTART

TROLLBACK

TSTART

USE

VIEW

WRITE

XECUTE

ZALLOCATE

ZDEALLOCATE

ZFLUSH

ZGO

ZHOROLOG

ZINSERT

ZLOAD

ZMSM

ZNEW

ZPRINT

ZQUIT

ZREMOVE

ZSAVE

ZSETOBJ

ZSYNC

ZTRAP

ZUSE

ZWRITE


MSM Functions

Overview

$ASCII

$CHAR

$DATA

$EXTRACT

$FIND

$FNUMBER

$GET

$JUSTIFY

$LENGTH

$NAME

$NEXT

$ORDER

$PIECE

$QLENGTH

$QSUBSCRIPT

$QUERY

$RANDOM

$REVERSE

$SELECT

$STACK

$TEXT

$TRANSLATE

$VIEW

$ZASCII

$ZBN

$ZBname

$ZBOOLEAN

$ZCALL

$ZCHAR

$ZCRC

$ZCREATEOBJECT

$ZDATE

$ZDEVICE

$ZGETOBJECT

$ZHEX

$ZHL

$ZNEXT

$ZOBJREFERENCE

$ZORDER

$ZOS

$ZPOSITION

$ZPREVIOUS

$ZSORT

$ZUCI

$ZVERIFY

$ZWIDTH


MSM Special Variables

Overview

$DEVICE

$ECODE

$ESTACK

$ETRAP

$HOROLOG

$IO

$JOB

$KEY

$PRINCIPAL

$QUIT

$STACK

$STORAGE

$SYSTEM

$TEST

$TLEVEL

$TRESTART

$X

$Y

$ZA

$ZB

$ZC

$ZERROR

$ZLEVEL

$ZNAME

$ZORDER

$ZREFERENCE

$ZTRAP

$ZVERSION


MSM Structured System Variables

Overview

^$DEVICE

^$GLOBAL

^$JOB

^$LOCK

^$ROUTINE


ASCII Collating Sequence

Overview


Error Processing

Overview

Error Processing

MSM Error Codes

MSM Error Numbers

$ECODE Errors


Mnemonic Namespaces

Overview

ANSI X3.64-1979 Namespace

ZWINTERM Namespace

ZWINTERM Namespace Commands

SYSGEN Mnemonic Namespaces


User-Defined Commands

Overview

Commands, Functions, and Special Variables

Passing Parameters to the Routine


Macro Facility

Overview

Definitions

Basic Usage

Advanced Capabilities

Preprocessor Directives

Technical Components


Acknowledgment

Micronetics Standard M (MSM) is an implementation, with extensions, of the ANSI Standard Specification (X11.1-1995) for the Massachusetts General Hospital Utility Multi Programming System (MUMPS). MUMPS was developed by the Laboratory of Computer Science at Massachusetts General Hospital under grant number HS00240 from the National Center for Health Services Research and Development. MUMPS was a trademark of the Massachusetts General Hospital.


Documentation Conventions

The following documentation conventions are used in this manual.

Convention	Description
RETURN	The carriage return key (normally labeled RETURN, ENTER, and so on).
CTRL+X	The CTRL key pressed at the same time as the X key, where X  is any valid key used in combination with the control key.
<ERROR>	An MSM error message.
'val'	In Help messages, 'val' is used to indicate that the user can enter the indicated value. The value is entered without the quotes.
>	The MSM programmer prompt.
...	The series of items repeats a user-specified number of times.
.  .  .	Shows a break in a list where consecutive lines have been omitted.
Bold	Items in a dialog are shown in bold to indicate a user response.


Language Syntax - Overview
Overview

Micronetics Standard M (MSM) is an implementation, with extensions, of the ANSI Standard (X11.1-1995) M programming language. The M language has been implemented in MSM through a language compiler and a pseudo-code (p-code) interpreter. The language compiler converts M code into pseudo-machine code that can be processed by the p-code interpreter. The rapid interpretation of the p-code during program execution allows applications to run in a stand-alone environment or under a host operating system with exceptionally fast response time.

Even though MSM has been implemented as a compiler, it still provides all of the flexibility of an interpreter. M code can be entered directly from the keyboard into the compiler to provide instantaneous results without a separate compilation step. The file system in MSM has been implemented using a compressed-key, B-tree structure to ensure optimum performance. The system supports a disk buffer cache, delayed write operations on modified buffers, and other performance features aimed at maximizing throughput.


MSM Character Set

The MSM system supports the full 128-character ASCII character set. ASCII characters are represented by seven binary bits of information. Refer to "ASCII Collating Sequence" in this manual for a complete list of the ASCII character set. The MSM system internally carries all characters as 8-bit values and expands the accessible character set to 256 distinct combinations. Within the ASCII character set, certain characters have special meaning to MSM, and are grouped as: delimiters, prefixes, line terminators, format characters, and control characters.

See Also:

Delimiters

Prefixes

Line Terminators

Format Characters

Control Characters


Delimiters

Delimiter characters are recognized by the compiler to separate various pieces of the language so that an unambiguous translation can be made. The following table lists the delimiter characters that are recognized by the MSM system.

Delimiter Characters

Character	Description
,	A comma is used to separate arguments and subscripts.
=	An equal sign performs value assignment and tests for equality in an expression.
:	A colon is used to separate a post-conditional expression from a command and to separate sub-arguments within a command.
( )	Parentheses are used for grouping subscripts, function arguments, elements within complex expressions, etc.
@	An at-sign indicates indirection in an expression (evaluate the expression and use the result).
"	Double quotes are used to form a string literal by bounding a string of information.
;	A semicolon indicates the beginning of a comment field within a command line or at the beginning of a command line.
^	A circumflex character separates a line label from a routine name in a DO or GOTO command, denote globals, etc.
E	An uppercase E indicates where the exponent portion of a numeric literal begins in pattern matching operands (for example: 1.23E7).
.	A period indicates where the fractional part of a numeric literal begins (for example: 123.45).
SP	A space character separates arguments from commands and commands from commands within a line of a routine.


Prefixes

Prefix characters are recognized by the compiler to distinguish global variable names, function names, special variable names, and special routine names from local variable names. The following table lists the prefix characters that are recognized by the compiler in the MSM system.

Prefixes

Character	Description
^	A circumflex indicates the start of a global variable name or the start of a routine name.
^$	A circumflex followed by a dollar sign indicates the start of a structured system variable name.
$	A dollar sign indicates the start of an MSM function name or an MSM special variable name.
$$	Two consecutive dollar signs ($$) indicate the start of an extrinsic function name or an extrinsic special variable name.
$&	A dollar sign followed by an ampersand indicates the start of an external function name.
&	An ampersand indicates the start of an external routine name.
.	A period indicates that a variable in a parameter list should be passed by reference instead of by value.


Line Terminators

Line terminators are recognized by the compiler to signal the end of data input to the compiler or a program. The following table lists the default line terminators recognized by the system.

Line Terminators

Character	Description
RETURN	Signals the end of input to the compiler or an executing routine.
ESC	Signals the end of input unless escape processing is enabled.


Format Characters

Format characters can be used in READ or WRITE commands to send carriage control commands to a device. The following table lists the format characters recognized by MSM.

Format Characters

Character	Description
#	A pound sign (#) instructs the system to send a carriage return and a form-feed sequence to the device. The $X and $Y special variables are reset to 0.
!	An exclamation point (!) instructs the system to send a carriage return and a line-feed sequence to the device. The $X special variable is reset to 0, and the $Y special variable is incremented by 1.
?	A question mark followed by an integer value (for example: ?2) indicates the column where the next output is to take place. The $X special variable is adjusted to reflect the new output position, and the $Y special variable is not changed.
/	A slash (/) indicates the start of a mnemonic namespace request.


Control Characters

The MSM system interprets control characters entered from the keyboard. The following table lists the control characters supported by MSM.

Control Characters

Character	Description
BACKSPACE	Backspaces the cursor one position. This is equivalent to the CTRL+H sequence.
DEL	Deletes the last character entered from the terminal and backspaces the cursor one position.
ESC	Terminates the current input operation if escape processing is disabled. Otherwise, one more character is read from the terminal, and the input operation is terminated.
RETURN	Terminates the current input operation. This is equivalent to a CTRL+M sequence.
TAB	Moves the cursor to the next tab position (tab stops are every eight positions). It is also used as the separator between the line label and the line body when entering M code into a program. This key is equivalent to entering the CTRL+I sequence.
CTRL+I	Moves the cursor to the next tab position (tab stops are every eight positions). It is also used as the separator between the line label and the line body when entering M code into a program. This is equivalent to entering TAB.
CTRL+L	Performs the same function as entering a form feed character. This character is echoed back to the terminal. The action taken depends on the terminal connected to the system.
CTRL+M	Terminates the current input operation. This is equivalent to RETURN.
CTRL+O	Suspends all output to a terminal. Any information sent to the terminal by the system is discarded. Output to the terminal is resumed when the system receives another CTRL+O character.
CTRL+Q	Resumes output to the terminal that was suspended using the CTRL+S function.
CTRL+R	Reprints the current input line and leaves the cursor positioned at the end of the line.
CTRL+S	Suspends all output to the terminal. Information is not lost, and output is resumed when a CTRL+Q is received.
CTRL+U	Deletes the current input line (erases all characters typed so far) and re-prompts for input.
CTRL+X	Deletes the current input line, displays (DELETED) on the same line, and re-prompts for input.
Refer to "Using Peripheral Devices" in the MSM User's Guide for information on preventing or altering interpretation of these control characters by MSM.


Language Components

MSM conforms to the M ANSI standard specification (X11.1-1995) and includes extensions that were approved for the language by the M Development Committee. The M language is comprised of three primary components: commands, functions, and special variables.

See Also:

Commands

Functions

Special Variables


Commands

A command is the method by which the compiler is directed to perform a specific action. Each command in M performs a specific task that is further defined by the arguments passed to the compiler with the command. In addition to the ANSI-standard M commands, MSM includes commands that provide increased capability and functionality in the language. These commands begin with the letter Z.


Functions

Built-in functions in MSM provide the programmer with a powerful set of capabilities to perform common operations. While most of these functions can be accomplished using a series of M commands, these built-in functions allow the programmer to specify a complete operation with a single instruction to the compiler. MSM function names always begin with a dollar sign ($). In addition to the ANSI-standard M functions, MSM includes that provide increased capability and flexibility. These commands begin with a dollar sign followed by the letter Z.


Language Syntax - Language Components - Special Variables
Special Variables

Special variables are designed to provide feedback information for executing programs as they interact with the operating system and the user. These variables are maintained by the MSM system and can be examined by a program as it executes. Based on the content of these variables, decisions can be made that alter the flow of execution. MSM special variable names always begin with a dollar sign ($). In addition to the ANSI-standard M special variables, MSM includes special variables that provide supplementary feedback. These special variables begin with a dollar sign followed by the letter Z.


Command Lines and Routines

The basic unit of work in the M language is the command. A command line is one or more commands grouped together. When one or more command lines are grouped together, the group is referred to as a routine. The following sections describe the format of commands, command lines, and routines.

See Also:

Command and Command Line Syntax

Routine Structure

Entering Command Lines into a Routine

Block Structured Subroutines


Command and Command Line Syntax

A command consists of a command name (for example, DO, GOTO) followed by none, one, or more arguments that the command acts upon. Interpretation of the arguments and the syntax of the arguments is determined by the command. Although the arguments are separated from the command name by one space, multiple spaces can be used between commands to improve readability. For example, the following two structures are equivalent:

WRITE SP "BASKET" SP WRITE SP "BALL"

WRITE SP "BASKET" SPSP WRITE SP "BALL"

The vast majority of commands in MSM allow the user to specify more than one argument. When multiple arguments are specified on a command, the arguments are separated from each other by commas. This collection of arguments is referred to as an argument list. The following example illustrates the use of an argument list:

WRITE SP "HELLO","!"

The same result can be achieved without an argument list. Instead, the command can be specified repeatedly with each of the arguments in the argument list. The following  example is equivalent to the previous example:

WRITE SP "HELLO" SP WRITE SP "!"

Generally, command names can be abbreviated to a single letter (such as G for GOTO), or in the case of MSM-specific command names, two letters (such as ZI for ZINSERT). In some cases, more than one command name in the M language has the same first letter (for example, HALT and HANG). In this situation, the syntax of the argument determines which command is specified.

In MSM, the following rules must be used when writing commands and command lines:

•	Every command line begins with a command.

•	Arguments are separated from the command name by one space.

•	A command can be followed by none, one, or several arguments.

•	All commands are separated from other commands by at least one space. Additional spaces can be used to enhance readability.

•	When a command with no arguments appears in a command line, the absence of the argument is indicated by a single space. Within a command line, a command with no arguments is separated from the following command by two or more spaces. The following example illustrates the format of MSM command lines:

Command SP Argument SP... SP Command SP Argument

Comments can be appended to any command line. The start of a comment is indicated by a semicolon (;) when a command name is expected (the first command in the command line or when separated from the last command in the command line by zero, one, or more spaces). Anything after the semicolon is considered to be a comment and is not interpreted by MSM.

Interpretation of each command line is performed in left-to-right order. The first command is interpreted before the second, the second before the third, and so on.


Routine Structure

When one or more command lines are grouped together to form a routine, the command lines are considered to be routine lines. A routine line is the same as a command line except that it is preceded by a TAB and optionally can include a line label that uniquely identifies the routine line. A line label can be either an integer value (for example: 1, 123, 765) or a name. If it is a name, it must begin with either a percent sign (%) or an alpha character. Characters after the first character can be any alpha-numeric value. If the label is more than eight characters, MSM ignores all characters after the eighth character. The following are examples of valid labels.

ABC
400
%12
%A99

When a routine is created, it can be assigned a unique name (referred to as RoutName). The name must begin with either a percent sign (%) or an alpha character and can be followed by any combination of alpha-numeric characters. If the name is more than eight characters, MSM ignores all characters after the eighth character.

Internally, a routine is stored so that the zero line is the name of the routine, the first line is the first routine line, the second is the second routine line, etc. In the internal representation, the routine line consists of the line label separated from the first command by one or more spaces.

Several commands are used to reference a routine or a routine line in a routine. These commands take as their argument a value that is an entry reference (referred to as EntryRef). An entry reference can be a routine name, the label of a routine line, or the label of a routine line in a specified routine. In an entry reference, the routine name is always preceded by a circumflex (^). The following are examples of valid entry references:

ABC
^CUSLOOK
123^TESTRTN
LINE1+3^MYPROG

In the previous example, the label indicated the third routine line after the routine line labeled LINE1. Although this syntax is grammatically correct, it generally is not used because it can cause unexpected results if routine lines are added or deleted from the routine.


Entering Command Lines into a Routine

Normally, when text is entered into the MSM system, it is immediately acted upon. This is referred to as direct mode. Commands and command lines can be entered in direct mode. They are evaluated by the compiler and their results displayed if appropriate. To enter routine lines that will be acted upon at a later time, a different form of data entry must be used. The routine line is entered in one of the following formats:

Label TAB Command Line
TAB Command Line

This form of data entry signals the compiler that the information being entered is to be stored for execution at a later time. When the information is executed, it is acted upon in run mode. Refer to "Using Peripheral Devices" in the MSM User's Guide for information on run mode and building routines.


Block Structured Subroutines

Often it is desirable to group several lines of code into a subroutine that will be executed only once. This most frequently occurs because the scope of the FOR, IF, and ELSE commands is limited to the amount of text that fits on the remainder of a routine line. To facilitate the development of this limited-use subroutine, M supports block structured code. This technique allows a subroutine to directly follow the code that invokes it. Block-structured subroutines are used to create programs that have a more consistent logical flow and are easier to read.

The key to understanding the operation of block structured subroutines is to become familiar with the concept of execution levels. When an M program first is invoked, it is considered to be at execution level 1. When a DO command is used in a routine to invoke a subroutine, the subroutine is at execution level 2. If that subroutine then invokes another subroutine using the DO command, the new subroutine is at execution level 3, and so on.

When a subroutine terminates, it always returns to the previous execution level, and execution continues with the command that immediately follows the DO command. Generally, a subroutine starts with a routine line that contains a label and ends with a QUIT command.

With a block structured subroutine, a slightly different approach is taken. Each command line in the subroutine is preceded by one or more PERIOD characters to indicate the execution level of the routine line. The following example illustrates the format of a routine line in a block structured subroutine:

Label TAB PERIOD ... PERIOD Command Line
TAB  PERIOD  ... PERIOD Command Line

In a general sense, the execution level of a routine line is equal to the number of PERIOD characters plus one. Thus, a routine line that is not preceded by any PERIOD characters can be considered to be at execution level 1, a line that is preceded with one PERIOD character is at execution level 2, and so on.

A block structured subroutine is invoked with a DO command that has no arguments. The subroutine must immediately follow the routine line that contains the DO command, and the execution level of the subroutine must be exactly one greater than the level of the routine line that invoked it.

Execution of the subroutine proceeds sequentially from top to bottom. The subroutine terminates when a QUIT command is encountered or when a line is processed that has a lower execution level number. When the subroutine terminates, execution resumes at the previous level at the command immediately following the DO command that invoked the subroutine.

When a block structured subroutine lies within the path of normal program execution and is not entered as the result of a DO command, all lines in the subroutine are skipped and execution continues with the first line at the same execution level following the subroutine. Subroutines encountered during execution can be no more than one level greater than the preceding level. If a subroutine is more than one level greater, the lines within it are ignored even if they are properly preceded by a DO without arguments.

The GOTO command can only be used to transfer control between lines that are at the same execution level. It is invalid to use the GOTO command to transfer control to a higher level. Therefore, the subroutine can be exited either by processing all statements in the subroutine or issuing a QUIT command.


Data Types

In the M language, all data is logically stored as variable length strings of ASCII information. When data is used, it is interpreted in the required format. In a calculation, data is converted to a number (either an integer or a floating point value); in a Boolean logical operation it is converted to a Boolean truth value; and when a string value is required, it is used as an ASCII string.

See Also:

Numbers and Strings

Literals

Constants

Object References


Numbers and Strings

In MSM, numbers can be represented as integer values or as floating point numbers. Integers always have 16 or more digits of precision, and real numbers (floating point numbers) may only have 16 digits depending on the value of the non-exponent portion of the number.

An integer number consists of the digits 0 through 9, which optionally can be preceded by a sign character (-). If the sign character is omitted, the integer is considered to be positive. At least one digit must be present. The following are examples of canonic (valid integer) numbers:

1
10
123
-25
12345678901234567

Floating point numbers are similar to integers, except that they contain a fractional part that follows the integer value. The fractional part is separated from the integer part by a decimal point. A floating point number may contain one and only one decimal point, and it need not contain an integer portion. If there is no integer portion, the number begins with a decimal point and is followed by at least one digit.

M also allows an exponent to be specified as part of the number. This is done by appending the uppercase letter E followed by an integer value to the end of a floating point number. The following are examples of valid floating point numbers:

12.34
1234.5678
987.65E9	(i.e., 987650000000)
987.65E-9	(i.e., .00000098765)

When a computation is performed, MSM automatically converts mixed-mode arithmetic to the proper format. For example, when a floating point number is added to an integer number, the result is a floating point number.

In each example in this section, the numeric values were specified as a string of ASCII characters. In MSM, a string is any combination of ASCII characters. Strings can be a maximum of 32764 characters in length when they are used with local variables, and a maximum of 511 characters (the default is 255 characters) in length when they are used with global variables.


Literals

In MSM, a literal is a string that is enclosed within quotation marks (" "). If the quote character is to appear in the literal, it is indicated by two consecutive quotes. The value of a literal can be acted upon by a command, but it cannot be changed by a command. The following are examples of valid literals.

"THIS IS AN EXAMPLE OF A LITERAL"
"123.456"
"99+44"
"!#$%|& SPECIAL CHARACTERS"

A literal can contain any valid ASCII character. When a literal is entered from a terminal, certain characters may be excluded from input because they have meaning to MSM. Refer to Control Characters in this manual for additional information.


Constants

A constant is a numeric value that is fully specified in an expression and whose value cannot be changed. The numeric value can be an integer or a floating point number. The following are examples of constants.

1234
-123.9876E3
986.65
0

Constants can be used in numeric expressions (for example: 2+2), in assignment commands (for example: SET X=2), and so on.


Object References

Objects are an "encapsulation of functionality and data values." Associated with each object is a set of properties and methods that represent values and functionality, respectively. The value associated with a property or method can be numeric or string or a reference to other objects (if the object is a container for other objects). An object reference has no graphic representation. It represents a "link" to an interface to packaged functionality and values.


Variables

In MSM, a variable is a symbolic name assigned to a data value that can be either temporary or permanent. A local variable is a temporary data value that exists for the duration of the terminal session or routine that creates it. A global variable is a data value that exists permanently after the terminal session ends. Variables differ from literals and constants because their values can be changed by commands.

The following sections describe variables within MSM. Variable names are case-sensitive. Variable names that differ only in uppercase or lowercase characters are distinct.

See Also:

Local Variables

Global Variables

Arrays and Subscripts

Naked References

Collating Sequence

Extended Global References

UCI Translation and Replication

External Program Calls

Special Variables


Local Variables

Local variables (locals) are temporary and exist only for the duration of a terminal session. Locals are created by referencing them in a SET or READ command or within parameter passing. They can be removed by referencing them in a KILL or NEW command or a QUIT command when exiting a routine invoked with parameter passing. When a local is created, it is assigned to the user who created it and is known only by that user. Two users may have local variables that have the same name but have different values.

A local variable name must begin with a percent sign (%) or an alpha character. It can be followed by any combination of alpha-numeric characters. If the name contains more than eight characters, MSM ignores all characters after the eighth character. The following are examples of valid local variable names.

ABC
%123
X21

The data value assigned to a local variable can be a maximum of 32764 characters in length or can be an object reference, and the local variable optionally can include one or more subscripts. Refer to Arrays and Subscripts in this manual for additional information.


Global Variables

Global variables (globals) are permanent and continue to exist after a terminal session ends. Globals are created by referencing them in a SET or READ command, and they are removed by referencing them in a KILL command. When a global is created, it is assigned a permanent location in the MSM database and can be known to users other than the user who created it. Thus, two users can both reference one global variable and obtain the same value.

A global variable name must begin with a circumflex (^) followed by a percent sign (%) or an alpha character, followed, in turn, by any combination of alphanumeric characters. If the name contains more than eight characters, MSM ignores all characters after the eighth character. A global variable name can be distinguished from a local variable name by the circumflex (^) that precedes it. The following are examples of valid global variable names.

^CUSTFILE
^%999
^CTRL12

The data value assigned to a global variable can be a maximum of 511 characters (the default is 255 characters) in length, and the global variable name optionally can include one or more subscripts. The value cannot be an object reference. Refer to Arrays and Subscripts for additional information.


Arrays and Subscripts

An array is a collection of one or more data items that is stored in a specified order. The order of the data items is specified by a subscript. A subscript is a series of expressions separated by commas, enclosed in parentheses, and appended to a local or global variable name. This combination is referred to as a local array or a global array. The following examples illustrate global arrays that have a single subscript value.

^CUSTOMER(1)
^CUSTOMER(2)
^CUSTOMER(3)
.
.
.
^CUSTOMER(997)
^CUSTOMER(998)
^CUSTOMER(999)

In the first example, customers are ordered into an array in which the first customer is number 1, the second is number 2, and so on. Arrays can be more complex, containing additional levels of information.

The following example illustrates a more complex array in which invoice and address information is added to the array shown in the first example.

^CUSTOMER(1,1)
^CUSTOMER(1,3,2)
^CUSTOMER(2,99)
^CUSTOMER(2,"INVOICE",18761)
.
.
.
^CUSTOMER(998,"ADDRESS")
^CUSTOMER(999,".01")
^CUSTOMER(999,".01",".997","TEST RESULT")

In a local array, individual subscripts can be a maximum of 2044 characters in length, and the data value can be a maximum of 32764 characters in length. The subscripts and data values can contain any ASCII values from 0 through 255.

For global variables, individual subscripts can be a maximum of 252 characters in length, and data values can be a maximum of 511 characters in length (the default is 255). The subscripts can contain any ASCII values from 1 through 255, and the data can contain any ASCII values from 0 through 255. The total length of the global reference (global name and subscripts) cannot exceed 255 characters. Refer to the MSM User's Guide for additional information on local and global variables and default data lengths.


Naked References

For each job, the system maintains a naked indicator, which is a value that is used to evaluate a naked reference. The value of this indicator is either null or a subscripted global variable name. The naked indicator is changed if one of the following conditions is met:

•	At the start of a job, the naked indicator is set to null.

•	Execution of a reference to an unsubscripted global variable sets the indicator to a null value.

•	Except as above, a global reference or a naked reference to a global sets the naked indicator to the immediate ascendant of the referenced global. That is, the global reference less the right-most subscript of the reference is set into the naked indicator.

Generally, a naked reference can be used wherever a global reference is allowed. In any situation in which this is not true, MSM provides information about the restrictions.

The syntax of a naked reference is as follows:

^(Subscript{, ... ,Subscript})

Execution of a naked reference when the naked indicator is null results in an error condition (<NAKED>). When the naked indicator is defined, the subscripts specified in the naked reference are appended to the right of the right-most subscript of the naked indicator to form the full reference.

Because the right side of a SET statement is evaluated first, care should be exercised to prevent unwanted results when using naked references. For example:

I '$D(^ABC(1)) S ^(1)=^XYZ(1,2)                 ;does not set ^ABC(1)

I '$D(^ABC(1)) S ^XYZ(1,1)=^XYZ(1,2)       ;is equivalent to the above


Collating Sequence

Subscripted global variables can include numeric valued subscripts, string-valued subscripts, or a combination of both. For this reason, MSM allows you to specify the order (either numeric or string sequence) in which subscripts are to be collated.

For globals in which a collating sequence string type was specified, all subscripts (numeric and non-numeric) are treated as character strings and stored in ASCII collating sequence.

In the following example, global variable X has subscripts -10, -2, -1, 1, 0, 1.1, 2, 3, 10, 20, 30, and ABC defined. In string collating sequence, the subscripts of X are stored in the following order:

^X(-1)
^X(-10)
^X(-2)
^X(0)
^X(1)
^X(1.1)
^X(10)
^X(2)
^X(20)
^X(3)
^X(30)
^X("ABC")

In globals in which the collating sequence is numeric, the system stores canonic numbers (numeric values with no leading zeroes or trailing zeroes after the decimal point) first, followed by the non-numeric values in ASCII collating sequence.

In the following example, global variable X has the same subscripts as in the prior example, and numeric collating sequence is assigned. The subscript values are stored in the following order:

^X(-10)
^X(-2)
^X(-1)
^X(0)
^X(1)
^X(1.1)
^X(2)
^X(3)
^X(10)
^X(20)
^X(30)
^X("ABC")

A newly created global is assumed to be in numeric collating sequence. A global's collating sequence is modified using the %GCH utility. Before a sequence can be changed, the global must exist but cannot have subscripts defined. The default collating sequence for new globals is changed using the SYSGEN utility.


Extended Global References

The MSM system allows users to access both globals that are stored in their own UCI and globals stored in different UCIs. The UCI can be on the same system or on other MSM systems that are connected by MSM-NET. This is done using an extended global reference notation that includes the global name, UCI name, and volume group name. The notation for accessing globals stored in different UCIs or volume groups can be any one of the following:

^[UCI{,VolName}]Variable

^|UCI{,VolName }|Variable

^[UCIVOL]Variable

^|UCIVOL|Variable

In this notation, UCI is an expression that evaluates to the three-character UCI name (for example: MGR). The VolName field is an expression that evaluates to the three-character volume group name where the global resides. If VolName is omitted, the system uses the current volume group. The variable name is any global variable name (subscripted or unsubscripted).

Alternatively, the notation UCIVOL can be used. This expression evaluates to a string which contains both the three-character UCI name and the three-character volume group name, separated by a comma (for example: MGR,VVV).

Any error condition caused by the reference is treated as if the referenced global was in the current UCI. The most common error caused by an extended global reference is the <PROT> error, which occurs when access to the referenced global is not authorized.


UCI Translation and Replication

MSM's global translation feature allows every reference to a specific global in a UCI within a volume group to be internally changed to reference a global with the same name in a different UCI. The UCI can be in a different volume group on the same system or on a different system when MSM-NET is used.

The replication feature allows globals SETs and KILLs to be duplicated in a maximum of seven additional UCIs. As with translation, the UCIs can be in different volume groups on the same system or on different systems.

A global can be translated and replicated at the same time. Use of extended global references bypasses the translation and replication features.


External Program Calls

The MSM system allows the M programmer to access routines and functions that are written in other programming languages. A special syntax indicates to the system that the routine or function being called is external to MSM. When an external call is made to a function or a routine, one of the following formats is used.

SET Variable=$&PackageName.ExtRoutName(Arg1, ... ,Argn)

DO &PackageName.ExtRoutName(Arg1, ... ,Argn)

In these formats, Variable is a local or global variable, PackageName is the name of the library (the compiled load module) being accessed, and ExtRoutName is the name of the routine or function in the library to be called.

For backwards compatibility, the MSM system still supports the $ZCALL function for accessing external routines. However, this syntax is obsolete and should be replaced with the newer external call syntax as soon as possible. In the future, support for the $ZCALL function will be discontinued.


Language Syntax - Variables - Special Variables
Special Variables

As explained in Language Components in this chapter,special variables are reserved variable names whose value is determined by the MSM system. Generally, special variable names can be used anywhere that constants and variable names can be specified. The exception is that many of the special variable names cannot be used in assignment commands or parameter passing by reference because their value cannot be changed.


Objects

Objects represent a "packaging" of functionality and data. The functionality of an object is provided (exposed) via methods, and the values associated with the object are exposed via properties. The distinction between properties and methods is primarily conceptual because both can accept parameters and return values. The one notable distinction is that properties can be updated via the SET and ZSETOBJ commands, while methods can only be referenced in expressions.

Object references in MSM are always in the following format:

ObjectExpression.member1.member2....membern

ObjectExpression is either a local variable whose value is an object reference or an intrinsic or extrinsic function or a system variable that returns an object reference. The members, separated by a period, are optional. Evaluation proceeds from left to right. After the ObjectExpression is evaluated, an object reference is returned. The object reference is used to invoke member1, and then its returned value is used to invoke member2, and so on, until all members of the object reference are invoked. All but the last member must evaluate to an object reference to allow the member on its immediate right to be invoked. The following are legal examples of object references:

myobj(1,2)

myobj(1,2).directory(path)

myobj(1,2).directory(path).filename(file)

myobj(1,2).directory(path).filename(file).size

Parameters optionally can be passed to members. In the above example, local variable myobj(1,2) contains an object handle that is used to invoke member function directory, passing to it the value of local variable path. The result of this invocation must be an object reference, which then is used to invoke the member function filename with the value of local variable file as a parameter. The returned value (which must also be an object reference) is used to invoke member size with no parameters. This last invocation may return either a value or an object reference.

In the following example, an extrinsic function is used to specify the initial object reference. This requires that user-defined (extrinsic) function, $$myobj(1,2), return an object reference which then is used for the leading member function.

$$myobj(1,2).directory(path).filename(file).size

MSM supports external (non-M) objects on platforms that support COM objects. These external objects often have member names that do not strictly conform to M naming rules (such as the member name calculate_interest, in which the underscore character would mean concatenation in M). These member names require the use of quotes around the member name, followed by the optional parameters. The following example illustrates this requirement:

myobj(1,2)."directory_lookup"(path).fileame."size of file"

In the example, the parameter is specified outside the quotes. Any character can appear inside the quotes, including a quote (which must be double-quoted; that is, two consecutive quotes used to represent a single embedded quote).

While the current maximum member length is 31 characters (MSM ignores any characters after the thirty-first), it is good practice to limit names to 31 characters to allow future expansion to longer names as object technology evolves.

An object exists as long as something references it. After the last reference to an object is deleted (discarded), the object is no longer accessible and conceptually no longer exists. The reference can be transitory as part of an expression evaluation, or more permanent when it is assigned to a local variable.

M variables conceptually are considered objects with built-in methods and properties defined by the M language. The "kill" method destroys objects, the "new" method hides them, a "value" property provides the data value, and so on.

Refer to the MSM User's Guide for additional information on objects.

See Also:

Default Values


Default Values

COM objects may have a default property that retrieves the value associated with an object reference when a member name is not explicitly specified. This feature of COM objects is supported by MSM.

For example, cell(3,9) is a local variable whose value is an object reference to cell (3,9) of a Microsoft Excel spreadsheet. The command WRITE cell(3,9) invokes the default member function associated with the Excel object (the contents of the cell in the spreadsheet), which then is displayed on the current output device. Explicit members also can be specified (such as cell(3,9).font or cell(3,9).width, etc.). An object's default property can be referred to explicitly by suffixing the expression with a period and omitting the member name (for example: cell(3,9)).

There are two major benefits in allowing default values: variables that contain object references can participate transparently in any M expressions, and there is immediate compatibility with COM objects both as M and non-M objects.

When the last member of an object reference returns an object reference, the default property of that last object reference is invoked whenever the entire object expression appears as part of an M expression, except as noted in the sections below. This means that SET A=B assigns to local variable A the value of the default property of B (assuming that B contains an object reference). Even if local variable A originally contained an object reference, it is replaced by the value of B (the value returned by the default property). The command SET cell(3,9)=3 attempts to assign a value of 3 to the default property of the cell(3,9) object. Similarly, IF A=B compares the values returned by the default properties of A and B.


Expression Elements - Overview
Overview

The building blocks that are used to form expressions in M include: functions, literals, variables, unary operators, and binary operators.

An expression is a substring of a command which, when executed, produces a value. The execution (evaluation) of expressions is the principal means by which values are obtained for subscripts, for arguments of functions, and for assignment of variables.

The simplest element of an expression is an expression atom. An expression atom can be an intrinsic or extrinsic function, a literal, a variable, or another expression atom preceded by a unary operator.

In its simplest form, an expression can be a single expression atom. For example, the following are simple expressions:

123.45	A numeric literal
CUST	A local variable name
$DATA(X)	A function
-X	A local variable name preceded by a minus sign
Expressions also can be complex, limited only by practical issues such as command line length and readability. Generally, complex expressions are formed by combining expression atoms with binary operators.


Building Expressions

Two fundamental rules apply to the process of building expressions. First, every expression must contain at least one expression atom. By definition, an expression atom is an intrinsic or extrinsic function, a literal, a variable, a constant, or another expression atom preceded by a unary operator.

Second, an expression is defined to be an expression atom, two expression atoms separated by a binary operator, or an expression enclosed in parentheses. By definition, an expression atom is an expression. The following examples illustrate expressions.

2+2	Two expressions separated by a binary operator
(A+B)	An expression enclosed in parentheses
(A+B)/(C+D)	Two expressions separated by a binary operator
-((A+B)/(C+D))	An expression preceded by a unary operator
Extremely complex expressions can be formed using these rules. In MSM, a function is an expression. Whenever an expression is allowed, a function can be used. This significantly increases the flexibility of the language.


Evaluating Expressions

Expressions generally are evaluated in a strict left-to-right order. First, within the expression atom, the system evaluates all indirection operators in a left-to-right sequence. Each occurrence of indirection is replaced with the value of the indirection.

Next, all unary operators are evaluated and the appropriate action is applied to the operand to the right of the unary operator. If multiple unary operators appear in a sequence, each operator is applied one-by-one in a left-to-right order.

Finally, all binary operators are evaluated in a left-to-right order. Unlike other languages, all binary operators have equal precedence (there is no specified evaluation sequence for binary operators). The strictly left-to-right order in which binary operators are evaluated can be changed by enclosing expressions in parentheses.

When an expression contains one or more subexpressions (an expression enclosed in parentheses), then the subexpressions are evaluated first in a left-to-right order. This is done before the binary operator is applied. The same rule applies if the subexpression contains a subexpression.

When an expression is evaluated, its result can be considered a character string, which is the only data type defined in MSM. However, based on the usage of the result, an implicit data type may be required. In MSM, certain commands and functions expect implicit data types.

The following types of expression are used in MSM:

•	Numeric expressions

•	String expressions

•	Truth-valued expressions

•	Post-conditional expressions

The following sections describe these expression types and the rules that pertain to them.


Numeric Expressions

A numeric expression in MSM is an expression that is interpreted as a number. The interpreted number may be an integer (for example: 123) or a real number (for example: 123.45).

When interpreting the expression as a number, MSM scans the value of the expression in a left-to-right sequence searching for numeric characters (unary operators, decimal digits, a decimal point, and the letter E). If none of these characters is present, the expression is assigned a value of zero.

Both unary and binary arithmetic operators always force numeric conversion of expressions. After the conversion is performed, the indicated arithmetic operation is performed. If a numeric expression must yield an integer value, the expression is referred to as an integer expression. If a real number is specified in this situation, MSM truncates the value to make it an integer. Otherwise, the expression is referred to simply as an expression, and either an integer or a real number can be specified.


String Expressions

A string expression in MSM is one in which the operands contain any valid ASCII character string. No interpretation is given to the operands. The binary CONCATENATE operator or any of the string relational operators (CONTAINS or FOLLOWS) can be used in string expressions.

The operands are considered to be variable length strings with a given value. For the CONCATENATE operator, the value of the expression is the value of the second operand concatenated to the value of the first operand. For relational values, the result is a Boolean true (1) or a Boolean false (0) value.


Truth-Valued Expressions

A truth-valued expression is one in which the operands are interpreted as Boolean truth values. The expression may contain either binary relational operators or binary logical operators.

When the expression is evaluated, if the relationship between the operands is true, the expression is assigned a Boolean true value (1). Otherwise, a Boolean false value (0) is assigned to the expression.


Post-Conditional Expressions

A post-conditional expression is used to conditionally execute a command or argument of a command. When it is used to control execution of a command, it is referred to as a command post-conditional. In the case of conditional execution of an argument, it is referred to as an argument post-conditional.

A post-conditional expression consists of a colon (:) followed by a truth-valued expression. In a command post-conditional, the expression is appended to the command word. In an argument post-conditional, the expression is appended to the argument.

When a command contains a post-conditional, the command is executed only if the conditional expression is true. Otherwise, execution moves to the next command. Similarly, when an argument contains a post-conditional, the argument is only interpreted and executed if the expression is true. If it is false, the argument is interpreted but not executed.

A command post-conditional can be used with all commands except the ELSE, FOR, and IF commands. The argument post-conditional can be used only with arguments of the DO, GOTO, and XECUTE commands. Command post-conditionals and argument post-conditionals can be used in the same statement.


MSM Operators - Overview
Overview

The M language operators are used to specify an action that is to be performed. The following table summarizes MSM operators and their characteristics.

MSM Operators

Operator	Name	Type	Characteristics
+	ADDITION	Binary	Arithmetic
&	AND	Binary	Logical
_	CONCATENATE	Binary	String
/	DIVIDE	Binary	Arithmetic
=	EQUAL TO	Binary	Relational
**	EXPONENTIATION	Binary	Arithmetic
>	GREATER THAN	Binary	Relational
#	HEXADECIMAL	Unary	Arithmetic
@	INDIRECTION	Unary	Unary
\	INTEGER DIVISION	Binary	Arithmetic
<	LESS THAN	Binary	Relational
-	MINUS	Unary	Arithmetic
#	MODULO DIVISION	Binary	Arithmetic
*	MULTIPLICATION	Binary	Arithmetic
'	NOT	Unary	Logical
!	OR	Binary	Logical
?	PATTERN MATCH	Binary	Binary
+	PLUS	Unary	Arithmetic
[	STRING CONTAINS	Binary	Relational
]	STRING FOLLOWS	Binary	Relational
]]	STRING SORTS AFTER	Binary	Relational
-	SUBTRACTION	Binary	Arithmetic
For additional information on writing programs using operators, refer to the MSM User's Guide.


ADDITION (+)

Performs addition of two operands after evaluating them as numeric values.

Syntax

operand1+operand2

Definition

The ADDITION operator evaluates each operand as a numeric value and then computes the algebraic sum of the two values.

Considerations

The result of the ADDITION operation is accurate to 16 or 17 digits of precision, depending on the values of the operands.

Associated Topics

Numeric Expressions

Examples

Writes the value 4:

WRITE 2+2

Writes the value 3068.113:

W 986.513+2081.6

Writes the value 579 after evaluating the strings as numbers:

W "123XYZ"+"456ABC"

Writes the value 123 because the string "ABC" evaluates to zero as a number:

W "123XYZ"+"ABC"


AND (&)

Performs a Boolean AND operation on two operands after evaluating them as truth values.

Syntax

operand1&operand2

Definition

The AND operator evaluates each operand as a truth value and then tests both operands to see if they are true. An operand is true if its numeric value is non-zero. Otherwise, its value is false. If both operands are true, a value of 1 (true) is returned; otherwise, a value of 0 (false) is returned.

Considerations

The Boolean NAND operator (NOT AND) can be obtained by preceding the AND operator with the NOT operator ( ' ) to form the NAND operator ('&).

Associated Topics

Truth-Valued Expressions

Examples

Writes the value 1 because both operands are non-zero:

WRITE 5&4

Writes the value 0 because the second operand is not true (0):

W 1&0

Sets X to the value 1 because operand1 evaluates to 123 and operand2 evaluates to 456:

SET X="123XYZ"&"456ABC"

Sets Y to the value 0 because operand2 evaluates to 0:

S Y="123XYZ"&"ABC"


CONCATENATE ( _ )

Appends the operand2 string to the end of the operand1 string.

Syntax

operand1_operand2

Definition

The CONCATENATE operator treats both operands as string values and forms a new string by appending operand2 to the end of operand1. The length of the new string is the sum of the lengths of operand1 and operand2. MSM generates an error if the result produces a string longer than the maximum string size allowed for a local or a global variable, and the result is assigned to a local or global variable.

Considerations

Although the string generated by the CONCATENATE operation can be a maximum of 65528 characters in length, strings of this size can be assigned only to  local variables. Any attempt to assign a string of this length to a global variable results in an error. For globals, system administrator can set the maximum size to 255 or 511.

Associated Topics

String Expressions

Examples

Writes the string "BASKETBALL" to the current device:

WRITE "BASKET"_"BALL"

Writes the string 1,234,567.89 to the current device:

W "1,"_"234"_",567."_89

Writes the string "HELLO JIM, WELCOME TO MSM." to the current device:

SET X="JIM",Y="MSM" W "HELLO "_X_", WELCOME TO "_Y_"."


DIVISION (/)

Performs an arithmetic division of operand1 by operand2.

Syntax

operand1/operand2

Definition

The DIVISION operator evaluates each operand as a numeric value and then computes the quotient that is the result of dividing operand1 by operand2.

Considerations

The result of the DIVISION operation is accurate to 16 or 17 digits of precision, depending on the values of the operands. Any attempt to perform division by zero results in an error.

Associated Topics

Numeric Expressions

Examples

Writes the value 2 to the current device:

WRITE 4/2

Writes the value 39.317197452229299 to the current device:

SET A=123.456,B=3.14 W A/B

Writes the value 2 because the first string evaluates to 246 and the second string evaluates to 123:

W "246XYZ"/"123ABC"


EQUAL TO (=)

Performs a Boolean EQUAL TO comparison of two string operands.

Syntax

operand1=operand2

Definition

The EQUAL TO operator treats both operands as string values and compares them to determine if they are identical (operand1 exactly matches operand2). If the strings are identical, the operator returns a value of 1 (true); otherwise, it returns a value of 0 (false). This operator does not test for numeric equality; it is strictly a string-comparison operation. However, if both operands are written as numeric literals, the compiler evaluates them as numeric values. At execution time, string values of the numeric literals are compared, and leading and trailing zeros after the decimal point are ignored.

Considerations

The Boolean NOT EQUAL TO operator can be obtained by preceding the EQUAL TO operator with the NOT ( ' ) operator to form the NOT EQUAL TO operator ( '=).

Associated Topics

String Expressions

Examples

Writes the value 0 because operand2 has a trailing blank:

WRITE "ABC"="ABC "

Writes the value 0 because operand2 has leading zeroes:

W "123"="00123"

Writes the value 1 because the values are equivalent numeric literals:

W 123=00123

Writes the value 1 because numeric conversion is forced by the PLUS operator:

W +"123"=+"00123"


EXPONENTIATION (**)

Raises operand1 to the power specified by operand2.

Syntax

operand1**operand2

Definition

The EXPONENTIATION operator evaluates each operand as a numeric value and then computes a new value that is the result of raising operand1 to the power specified by operand2.

Considerations

The result of the EXPONENTIATION operation is accurate to 16 or 17 digits of precision, depending on the values of the operands. If a negative power is specified (operand2 is less than zero) and it is not an integer, and operand1 is less than zero, an error occurs. If a positive non-integer power is specified and operand1 is negative, an error occurs. If zero is raised to a negative power (operand1 is zero and operand2 is negative), an error occurs.

Associated Topics

Numeric Expressions

Examples

Writes the value 64 to the current device:

WRITE 8**2

Writes the value 3692736.4489861373 to the current device:

SET A=123.456,B=3.14 W A**B

Writes the value 65536 (evaluates to 16**4):

W "16ABC"**"4XYZ"


GREATER THAN (>)

Performs an arithmetic GREATER THAN comparison of two operands after evaluating them as numeric values.

Syntax

operand1>operand2

Definition

The GREATER THAN operator evaluates each operand as a numeric value and then performs a numeric comparison of the two values. If the numeric value of operand1 is strictly greater than the numeric value of operand2, the operator returns a value of 1 (true); otherwise, it returns a value of 0 (false).

Considerations

The Boolean NOT GREATER THAN operator can be obtained by preceding the GREATER THAN operator with the NOT  ( ' ) operator to form the NOT GREATER THAN operator ('>). The NOT GREATER THAN operator is equivalent to the LESS THAN OR EQUAL TO Boolean operation.

Associated Topics

Numeric Expressions
Truth-Valued Expressions

Examples

Writes the value 0 because operand1 is not greater than operand2:

WRITE "123">"456"

Writes the number 1 (true) because operand1 evaluated as a number is greater than operand2 evaluated as a number:

W "123">"001"

Writes the number 0 (false) because both operands evaluate to 0 as numbers:

W "DEF">"ABC"

Writes the number 0 (false) because the numeric value of operand1 (123) is not greater than the numeric value of operand2 (456):

W "123XYZ">"456ABC"


HEXADECIMAL (#)

Interprets a hexadecimal number as a numeric value.

Syntax

#operand

Definition

The HEXADECIMAL operator computes the decimal value of the operand, which must be a valid hexadecimal number. A valid hexadecimal number includes the digits 0 through 9 and the letters A through F. The letters can be specified in uppercase, lowercase, or a mixture of uppercase and lowercase characters.

Considerations

The HEXADECIMAL operator can be used in WRITE commands; however, care must be taken so that the operator is not mistaken for the eject page format character (#).

Associated Topics

Constant Values

Examples

Writes 1021 to the current device. The PLUS operator forces numeric conversion, thus allowing the # operator to be recognized:

WRITE +#3FD

Sets the local variable X to a value of 7933:

SET X=#1efd

Writes 60 to the current device. First, the two hexadecimal operands are evaluated, and then the integer division is performed:

S Y=#3BFC\#FF W Y


INDIRECTION (@)

Evaluates the argument of the operator and substitutes it into the command line.

Syntax

@Expression Atom

@Expression Atom@(Subscript{,...Subscript})

Definition

The INDIRECTION operator is used to dynamically alter the M code within a command. When indirection is encountered in a command, the indirection expression is evaluated and the derived value is substituted for the indirection before the command is executed. There are four types of indirection: name indirection, argument indirection, pattern indirection, and subscript indirection. The indirection types are described in the following paragraphs.

Name Indirection

When an indirection expression atom is evaluated, it must yield a valid MSM name. The name derived from the expression atom may be a routine name, variable name, or line label. Names can begin with a percent sign or an alpha character and can be followed by any number of alphanumeric characters. For a variable name, subscripts also can be specified as part of the indirection. This type of indirection can be used with commands such as DO, GOTO, and SET.

Argument Indirection

When an indirection expression is evaluated, it must yield one or more complete command arguments. The form of the derived argument or arguments is specific to the command being used with indirection. The command detects any errors in the argument structure. This type of indirection can be used on all commands unless explicit restrictions are noted on the command.

Pattern Indirection

When the indirection expression is evaluated, it must yield a valid pattern for the PATTERN MATCH operator. Refer to "Pattern Match" in this manual for information on valid patterns. This type of indirection can be used only with the PATTERN MATCH operator.

Subscript Indirection

When an indirection expression is evaluated, it must yield a valid subscripted local or global variable name). This type of indirection is in the following form:

@Expression Atom@(Subscript{,...Subscript})

An expression atom must yield a valid variable name (with or without subscripts). (Subscript{,...Subscript}) is a list of subscripts enclosed in parentheses and separated by commas. The two pieces of the indirection are combined to form a complete subscripted variable name by appending the explicit subscripts to the variable name and subscripts obtained from the expression atom.

Associated Topics

Expression Atom
PATTERN MATCH

Examples

This form of name indirection sets variable Y to a value of 2:

SET X="Y",@X=2

This form of name indirection writes the string "YOU ARE NOW LOGGED ON AS " followed by the value of the local variable USRNAME to the current device:

S X="""YOU ARE NOW LOGGED ON AS "",USRNAME" WRITE @X

This form of pattern indirection writes 1 to the current device because the string conforms to the indicated pattern:

S X="3N1""-""2N1""-""4N" W "123-45-6789"?@X

This form of subscript indirection sets the local variable Y to the value of the ^CUS("JONES",1,100,0) global:

S X="^CUS(ID)",ID="JONES",Y=@X@(1,100,0)

The next line sets up the following three examples:

S X="A",y="1^2^3",Z="$PIECE(Y,""^"",2)"

An example of argument indirection; this command sets variable A=2:

S @(X_"="_Z)

This command is equivalent to the previous command:

S ARG=X_"="_Z S @ARG

This command is a common misuse of indirection. It incurs an error because Z does not evaluate to a name. This is an attempt to use name indirection with an expression:

S @X=@Z


INTEGER DIVISION (\)

Performs an integer division of operand1 by operand2.

Syntax

operand1\operand2

Definition

The INTEGER DIVISION operator evaluates each operand as a numeric value. It then computes a result that is the integer portion of the quotient that results from dividing operand1 by operand2. The fractional part of the result is not returned.

Considerations

The result of the INTEGER DIVISION operation is accurate to 16 or 17 digits of precision, depending on the values of the operands. Any attempt to perform integer division by zero results in an error.

Associated Topics

Numeric Expressions

Examples

Writes the value 2 to the current device:

WRITE 4\2

Writes the value 39 to the current device. The fractional part of the result (.317197452229299) is discarded:

SET A=123.456,B=3.14 W A\B

Writes the value 3 because the first string evaluates to 456 and the second string evaluates to 123. The remainder value is discarded:

W "456XYZ"\"123ABC"


LESS THAN (<)

Performs an arithmetic LESS THAN comparison of two operands after evaluating them as numeric values.

Syntax

operand1<operand2

Definition

The LESS THAN operator evaluates each operand as a numeric value and then performs a numeric comparison of the two values. If the numeric value of operand1 is strictly less than the numeric value of operand2, the operator returns a value of 1 (true); otherwise, it returns a value of 0 (false).

Considerations

The Boolean NOT LESS THAN operator can be obtained by preceding the LESS THAN operator with the NOT ( ' ) operator to form the NOT LESS THAN operator ( '<). The NOT LESS THAN operator is equivalent to the GREATER THAN OR EQUAL TO Boolean operation.

Associated Topics

Numeric Expressions
Truth-Valued Expressions

Examples

Writes the value 1 because operand1 is less than operand2:

WRITE "123"<"456"

Writes the number 0 ( false) because operand1 evaluated as a number is greater than operand2 evaluated as a number:

W "123"<"001"

Writes the value 0 because both operands evaluate to 0 as numbers:

W "DEF"<"ABC"

Writes the value 1 because the numeric value of operand1 (123) is less than the numeric value of operand2 (456):

W "123XYZ"<"456ABC"


MINUS (-)

Inverts the numeric sign of the operand.

Syntax

-operand

Definition

The MINUS operator evaluates the operand as a numeric value and then reverses the sign of the numeric value.

Considerations

The MINUS operator has precedence over the arithmetic operators. This means that when an expression is evaluated, the MINUS operator is evaluated before the arithmetic operations.

Associated Topics

Expression Evaluation
Numeric Expressions

Examples

Writes the value -3 to the current device:

WRITE -3

Writes the value 579 to the current device because the MINUS operator inverts the subtraction to addition:

W 123--456

Writes the value -123 to the current device because the string evaluates to the positive number 123, and the inverse is -123:

W -"123XYZ"

Writes the value 0 to the current device because the string "ABC" has a numeric value of 0:

W -"ABC"


MODULO DIVISION (#)

Performs modulo division of operand1 by operand2.

Syntax

operand1#operand2

Definition

The MODULO DIVISION operator first evaluates each operand as a numeric value. It then computes a result that is the remainder portion of the quotient derived by dividing operand1 by operand2 according to the following formula.

operand1 - (operand2 * FLOOR(operand1/operand2))

The function FLOOR(x) is defined as the largest integer that does not exceed the value of x. The following example illustrates the FLOOR function.

FLOOR(5)=5	FLOOR(4.5)=4	FLOOR(-1)=-1	FLOOR(-1.5)=-2

In the MODULO DIVISION operation, the integer portion of the quotient is not returned.

When both operands are positive, the MODULO DIVISION operator yields the familiar remainder function. For negative values, the results are not immediately obvious.

The following table illustrates the results. In the table, R is the remainder of the absolute value of operand1 divided by the absolute value of operand2. The table shows the results if R is a non-zero value.

	operand1<0	operand1≥0
operand2<0	-R	operand2+R
operand2≥0	operand2-R	R
Considerations

The result of the MODULO DIVISION operation is accurate to 16 or 17 digits of precision, depending on the values of the operands. Any attempt to perform modulo division by zero results in an error.

Associated Topics

Numeric Expressions

Examples

Writes the value 0 to the current device:

WRITE 4#2

Writes the value .996 (the remainder) to the current device. The integer portion of 39 is discarded:

SET A=123.456,B=3.14 W A#B

Writes the value 87 because the first string evaluates to 456 and the second string evaluates to 123. The integer portion of 3 is discarded:

W "456XYZ"#"123ABC"

Writes the value -1 to the current device:

W 5#(-3)

Writes the value 1 to the current device:

W -5#3

Writes the value -2 to the current device:

W -5#(-3)

Writes the value 1 to the current device:

W 4#1.5


MULTIPLICATION (*)

Performs a multiplication of operand1 by operand2.

Syntax

operand1*operand2

Definition

The MULTIPLICATION operator evaluates each operand as a numeric value and then computes the product that is the result of multiplying operand1 by operand2.

Considerations

The result of the MULTIPLICATION operation is accurate to 16 or 17 digits of precision, depending on the values of the operands.

Associated Topics

Numeric Expressions

Examples

Writes the value 8 to the current device:

WRITE 4*2

Writes the value 387.65184 to the current device:

SET A=123.456,B=3.14 W A*B

Writes the value 30258 because the first string evaluates to 246 and the second string evaluates to 123:

W "246XYZ"*"123ABC"


NOT (')

Inverts the value of an M operator or a Boolean truth value.

Syntax

'operand

Definition

The NOT operator takes as its argument either an M relational or logical operator (!,  =, >, and so on) or a Boolean truth value (0 or 1). It inverts the value of the operator or the Boolean truth value. If the truth value is true (1), it becomes false (0), and if it is false (0), it becomes true (1). With operators, it reverses the value of the operation result.

Considerations

The value of a relational operation can be reversed using either of the following methods:

operand1 'Relation operand2	'(operand1 Relation operand2)

Associated Topics

Truth-Valued Expressions

Examples

Writes the value 0 to the current device:

WRITE '1

Writes the value 0 to the current device because 123 is not less than 456:

W 123'<456

Writes the value 0 to the current device because 123 is less than 456 and the inverse of that is false:

W '(123<456)


OR (!)

Performs a Boolean OR operation on two operands after evaluating them as truth values.

Syntax

operand1!operand2

Definition

The OR operator evaluates each operand as a truth value and then tests both operands to see if either or both are true. An operand is true if its numeric value is non-zero. Otherwise, its value is false. If either one or both are true, a value of 1 (true) is returned; otherwise, a value of 0 (false) is returned.

Considerations

The Boolean NOR operator ( NOT OR) can be obtained by preceding the OR operator with the NOT ( ' ) operator to form the NOR operator ( '!).

Associated Topics

Truth-Valued Expressions

Examples

Writes the value 1 because both operands are non-zero:

WRITE 5!4

Writes the value 1 because the value of operand1 is true (1):

W 1!0

Sets X to the value 1 because operand1 evaluates to 123 and operand2 evaluates to 456:

SET X="123XYZ"!"456ABC"

Sets Y to the value 0 because both operand1 and operand2 evaluate to 0:

SET Y="XYZ"!"ABC"


PATTERN MATCH (?)

Tests whether a value conforms to a specified pattern.

Syntax

operand?pattern

Definition

The PATTERN MATCH operator tests to see if the string specified by the operand is in the form indicated by the pattern that appears after the operator. If it is in the correct form, the PATTERN MATCH operator returns a value of 1 (true). Otherwise, it returns a value of 0 (false).

Combinations of the pattern characters listed in the following table can be used to specify the pattern. Refer to "ASCII Collating Sequence" in this manual for additional information on the ASCII character set.

Code Description

Code	Description
A or a	The 52 alphabetic characters (all uppercase characters and all lowercase characters)
C or c	The 33 ASCII control characters (decimal values 0 through 31 and decimal value 127)
E or e	All 128 ASCII characters plus the 128 extended ASCII characters (matches everything)
L or l	The 26 lowercase alphabetic characters
N or n	The 10 numeric digits 0 through 9
P or p	The 32 punctuation characters plus the SPACE character
U or u	The 26 uppercase alphabetic characters
(	Indicates the start of a logical OR pattern group
)	Indicates the end of a logical OR pattern group
,	Used to separate individual patterns in a logical OR pattern group
A pattern is composed of one or more pattern elements. Multiple pattern elements can be specified by placing them adjacent to each other. Pattern elements are in the following general form.

Min.Max Code

Where:

Code	Either of the allowable pattern match codes specified in the previous section or a string literal (a string of characters enclosed in quotes).
Min	The minimum number of occurrences required to successfully match the pattern element (the minimum repetition count). It must be specified as an integer value.
Max	The maximum number of occurrences that is allowed to successfully match the pattern element (the maximum repetition count). It must be specified as an integer value.
The following valid combinations are allowed for the Min and Max elements.

Min	This is equivalent to specifying a pattern element of Min.Min.
Min.	The implied value of Max defaults to the largest possible number of occurrences.
.	This is equivalent to specifying a pattern element of 0. .
.Max	This is equivalent to specifying a pattern element of 0.Max.
Min.Max	When both a Min value and a Max value are specified, the value of Max must not be less than the value of Min.
For example, a 3P pattern element is the same as a 3.3P pattern element. This same pattern element also can be expressed as 2P1P, 1P2P, 2.2P1P, and so on.

As another example, a 1.3L pattern element is identical to 1L, 2L, or 3L. In other words, the pattern matches from one to three lowercase alphabetic characters.

A notation is provided to allow a logical OR capability in the PATTERN MATCH operator. Two or more patterns enclosed in parentheses and separated by commas indicate that a match should be successful if either pattern matches. Indirection also can be used to specify pattern arguments.

Considerations

Pattern match codes can be specified in uppercase, lowercase, or a combination of uppercase and lowercase characters. If the PATTERN MATCH operator is preceded by the NOT ( ' ) operator, the logic of the operation is inverted.

Pattern match codes A, C, N, L, P, and U are defined only for the standard 128 ASCII characters. The pattern match code E now is extended to match all 256 characters (128 ASCII and 128 Extended ASCII).

Associated Topics

ASCII Character Set
INDIRECTION Operator
Truth-Valued Expressions

Examples

This pattern match writes 1 to the current device because the specified string conforms to the indicated pattern:

SET X="3N1""-""2N1""-""4N" WRITE "123-45-6789"?@X

This pattern tests to see if the string is one or more alphabetic characters followed by one and only one comma followed by one or more alphabetic characters. In this case, the pattern match writes a 1 to the current device:

WRITE "JONES,JOHN"?1A.A1","1A.A

This example shows how a logical OR condition can be specified within a PATTERN MATCH operation:

IF X?2N1(3P2A,2P3A).E

The pattern shown in the above example is equivalent to the following:

I (X?2N3P2A.E)!(X?2N2P3A.E)


PLUS (+)

Forces numeric conversion of the operand.

Syntax

+operand

Definition

The PLUS operator evaluates the operand as a numeric value and preserves the sign of the numeric value. The numeric value of an operand is the leading portion of the operand that includes the MINUS operator, the PLUS operator, the letter E, a decimal point, and the digits 0 through 9.

Considerations

The PLUS operator only forces conversion of a string to a numeric value. It does not alter the sign of the converted string.

Associated Topics

Numeric Expressions

Examples

Writes the value 123 to the current device:

WRITE +"123XYZ"

Writes the value 1 to the current device because the PLUS operator forces numeric conversion and the values are then equal:

W 123=+"123ABC"

Writes the value -123 to the current device because the string evaluates to the negative number -123:

W +"-123XYZ"

Writes the value 0 to the current device because the string "ABC" has a numeric value of 0:

W +"ABC"


STRING CONTAINS ([ )

Tests whether or not one string is contained in another string.

Syntax

operand1[operand2

Definition

The STRING CONTAINS operator tests if the string specified by operand2 is contained within the string specified by operand1. If it is, the operator returns a value of 1 ( true); otherwise, it returns a value of 0 (false). The string specified by operand2 must match exactly a substring contained in operand1 (the substring must be the same length and the characters must be in the same order). By definition, if operand2 is null (a string of zero length), the operator always returns a value of 1.

Considerations

The STRING DOES NOT CONTAIN operator can be obtained by preceding the STRING CONTAINS operator with the NOT ( ' ) operator. This forms the DOES NOT CONTAIN relational operator ( '[).

Associated Topics

String Expressions
Truth-Valued Expressions

Examples

Writes 1 to the current device because "DEF" is contained in "ABCDEFGHI" :

WRITE "ABCDEFGHI"["DEF"

Writes 0 to the current device because "246" is not contained as a substring in "123456" :

W "123456"["246"

Writes 1 to the current device because the null string is contained in all strings:

W "TEST STRING"[""

Writes 1 to the current device because the zip code specified by operand2 is contained in operand1:

SET X="ROCKVILLE, MD. 20850",Y="20850" W X[Y


STRING FOLLOWS (])

Tests whether or not one string follows another string in the ASCII collating sequence.

Syntax

operand1]operand2

Definition

The STRING FOLLOWS operator tests to see if the string specified by operand1 follows the string specified by operand2 in the ASCII collating sequence. If it does, the operator returns a value of 1 (true); otherwise, it returns a value of 0 (false). A character-by-character comparison is made between operand1 and operand2 until the two strings do not match. If the character in operand1 that does not match the character in operand2 follows the character in operand2 in the ASCII collating sequence, operand1 is said to follow operand2. By definition, if operand2 is null (a string of zero length) the operator returns a true value. If operand1 and operand2 match exactly, the operator returns a value of false.

Considerations

The STRING DOES NOT FOLLOW operator can be obtained by preceding the STRING FOLLOWS operator with the NOT ( ') operator to form the STRING DOES NOT FOLLOW operator ( ']).

Associated Topics

String Expressions
Truth-Valued Expressions

Examples

Writes 1 to the current device because "S" follows "J" in the ASCII collating sequence:

WRITE "SMITH"]"JONES"

Writes 1 to the current device because "S" (the sixth character of operand1) follows the null string (the sixth character of operand2) in ASCII collating sequence:

W "APPLES"]"APPLE"

Writes 0 to the current device because the "A" in the third position of operand1 comes before "B" in the third position of operand2:

W "AAA"]"AAB"

Writes 0 to the current device because the two strings are identical:

SET X="GOLF CLUBS",Y="GOLF CLUBS" W X]Y

Writes 0 to the current device. Although 10 is greater than 2, the STRING FOLLOWS operator treats the value of all expressions as strings, and in a strict character-by-character-by-character comparison, 2 follows 1 and the 0 is ignored:

W 10]2


STRING SORTS AFTER (]])

Tests if one string follows another string in subscript ordering sequence.

Syntax

operand1]]operand2

Definition

The STRING SORTS AFTER operator tests to see if the string specified by operand1 follows the string specified by operand2 in the subscript collating sequence. If it does, the operator returns a value of 1 (true); otherwise, it returns a value of 0 (false). The subscript collating sequence is produced by the single argument form of the $ORDER function. The value of A]]B ( the string A SORTS AFTER the string B) is equivalent to the following.

$S(A=+A&(B=+B):A>B,A=+A:B="",B=+B:A'="",1:A]B)

As this formula illustrates, canonic numbers collate before strings when they are used as subscripts in local or global variables.

Considerations

The STRING DOES NOT SORT AFTER operator can be obtained by preceding the STRING SORTS AFTER operator with the NOT ( ' ) operator to form the STRING DOES NOT SORT AFTER operator ( ']]).

Associated Topics

Collating Sequence
Canonic Numbers
String Expressions
Truth-Valued Expressions
STRING FOLLOWS Operator
$ORDER Function

Examples

Writes 1 to the current device because "SMITH" follows "JONES" in the subscript ordering sequence:

WRITE "SMITH"]]"JONES"

Writes 1 to the current device because 45 follows 23 in the subscript ordering sequence:

W 45]]23

Writes 0 to the current device because 9 does not follow 10 in the subscript ordering sequence. Note that 9]10 would produce a result of 1 because 9 does follow 1 in the ASCII collating sequence:

W 9]]10

Writes 0 to the current device because 9 does not follow the string "05" in the subscript ordering sequence:

W 9]]"05"


SUBTRACTION ()

Performs subtraction of two operands after evaluating them as numeric values.

Syntax

operand1-operand2

Definition

The SUBTRACTION operator evaluates each operand as a numeric value and then computes the algebraic difference of the two values by subtracting operand2 from operand1.

Considerations

The result of the SUBTRACTION operation is accurate to 16 or 17 digits of precision, depending on the values of the operands.

Associated Topics

Numeric Expressions

Examples

Writes the value 2 to the current device:

WRITE 4-2

Writes the value 514:3893 to the current device.

W 617.343-102.9537

Writes the value 333 after evaluating the strings as numbers:

W "456ABC"-"123XYZ"

Writes the value 123 because the string "ABC" evaluates to zero as a number:

W "123XYZ"-"ABC"


MSM Commands - Overview
Overview

This chapter describes the ANSI Standard M commands and other commands that are provided in MSM.

The M language contains commands that programmers can use to create programs or routines, as they are referred to in MSM. A command is the method by which the compiler is directed to perform a specific action. Each command performs a specific action that is further defined by the operands or arguments associated with the command.

MSM provides all of the ANSI Standard commands, as well as an extended set of commands that are specific to MSM. The ANSI Standard commands begin with the letters A through Y, and the MSM-specific commands begin with the letter Z. For each command, a single, defined abbreviation for the command can be used in place of the entire name. Each abbreviation consists of one or more letters of the name and always begins with the first letter of the name. In the definition of each command, the abbreviation is shown in bold, and the remainder of the name is shown within braces. Command names can be specified in uppercase, lowercase, or a combination of uppercase and lowercase characters.

The following examples illustrate valid abbreviations.

CLOSE
close
C
c

The following sections contain information about the commands provided in MSM. For each command, the following information is provided: syntax, a description of the command's function, special considerations, associated topics, and examples. For additional information on writing M programs, refer to the MSM User's Guide.


BREAK

Interrupts program execution to allow debugging.

Syntax

B{REAK}{:Postcond}

B{REAK}{:Postcond}SP{Expression}

Definition

Postcond	Any post-conditional expression.
Expression	A numeric expression that is used to enable or disable BREAK recognition.
The BREAK command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the BREAK command.

A BREAK command without arguments is used to suspend execution of a program. Before this can occur, MSM's interactive debugging facility must be active. If the interactive debugging facility is not active, a BREAK command without arguments is ignored.

When program execution is suspended, you can enter the interactive debugger and have full access to the M language for debugging purposes. When MSM enters direct mode as a result of a BREAK command, a message is displayed indicating that a break occurred, and the system prompts for input with the name of the program displayed between < and > signs.

At this point, use the ZGO command to resume execution of the suspended routine; enter QUIT to exit the debugging system and return to the current executing routine; or enter any M command. To obtain a list of commands that can be used within the interactive debugger, enter a question mark (?).

The BREAK command with an argument is used to control recognition of the break key (CTRL+C). The break key is used to interrupt execution of a routine. If the value of the expression is true (evaluates to 1), the break key is recognized. Otherwise, the break key is treated like any other character. When a BREAK 0 command is issued, 15 (interrupt received) is turned off in $ZA for the current device, if it is a terminal. Refer to "Using Peripheral Devices" in the MSM User's Guide for additional information on this bit.

If the BREAK argument has a value of -2 or 2, it is used to control the mode of error processing that is performed. A value of 2 indicates that the DO/XECUTE stack is to be discarded before the error is processed. A value of -2 indicates that the DO/XECUTE stack is preserved and that error processing is performed at the current execution level. When the system is initialized, a default of -2 is in effect for the BREAK command. The default setting can be configured through the MODE flags in the SYSGEN utility.

Associated Topics

ZGO Command
ZQUIT Command
Break Key, MSM User's Guide
Error Processing, MSM User's Guide

Examples

Command	Explanation
BREAK	This command shows an unconditional BREAK.
B:X=3	This command only BREAKs if X=3.
S X=^A(3) I X=0 B K ^A	A BREAK is inserted before the global is deleted so that the programmer may examine the job's status.
B 1	The BREAK character CTRL+C is recognized.
B 0	The BREAK character CTRL+C is not recognized.
B @X	Indirection may be used in the BREAK command.


CLOSE

Releases a device that is owned by a job.

Syntax

C{LOSE}{:Postcond}SPDevice{:Parm}{,...}

Definition

Postcond	Any post-conditional expression.
Device	An integer expression that indicates which device is to be closed.
Parm	One or more expressions separated by colons and enclosed in parentheses that have meaning specific to the device being closed.
The CLOSE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the CLOSE command.

Use the CLOSE command to release ownership of a device. To close multiple devices, specify a list of device number that are separated by commas on the CLOSE command. If the job issuing the command does not own the specified device, no action takes place. Use the OPEN command to achieve ownership of a device.

The device specified can be any valid MSM device, and its number can be specified using indirection. When the device is closed, MSM makes the principal device the current device. (The principal device is the device that was used to log on to MSM.) However, the system does not attempt to OPEN the principal device. When a HALT command is encountered, all devices owned by the job are closed and returned to the pool of available devices.

In MSM, Device number 0 indicates the principal device. When a Device number of 0 is specified on a CLOSE command, it is ignored (no action takes place).

Associated Topics

Using Peripheral Devices, MSM User's Guide

Examples

Command	Explanation
CLOSE 3	Device 3 is CLOSEd.
C:X=1 Y	Device Y is CLOSEd only when X=1.
C 5,X,7	CLOSE multiple devices.
C A+B*3	CLOSE a device using a calculated device number.
C @X	Indirection may be used in the CLOSE command.


DO

Calls a subroutine and then continues with the next command upon completion of the subroutine.

Syntax

D{O}{:Postcond}

D{O}{:Postcond}SPEntryRef{:Postcond}{,...}

Definition

Postcond	Any post-conditional expression.
EntryRef	Any valid entry reference.
The DO command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the DO command. For post-conditional expressions on the argument of the DO command, the argument is skipped if the expression is false.

The DO command is used to call a subroutine within the current routine or a subroutine in another routine. If the EntryRef does not contain a routine name, control passes to the label (or label + offset) in the routine containing the DO command. When the EntryRef contains a routine name, control passes to the label (or label + offset) in the named routine.

The EntryRef also can be specified as an extended reference. In an extended reference, the routine name can be preceded with the UCI name, the volume group name, or both. The format for the extended reference is the same format used for extended global references. Refer to "Language Syntax" in this manual for additional information on the format of the extended reference.

If no label (or label + offset) is specified with the routine name, control passes to the first line of the named routine. The called subroutine terminates when a QUIT command, which is not within the scope of a FOR command, is encountered or the physical end of the routine is encountered. When the subroutine terminates, control passes to the next argument on the DO command or the next command following the DO command.

In the form without arguments, the DO command invokes a block structured subroutine at the next higher execution level. The subroutine being invoked must immediately follow the routine line that contains the argumentless DO command.

When a QUIT command or the end of the block structured subroutine is reached, execution continues with the next command following the DO. If no commands follow the DO command, execution continues with the next routine line following the DO command that is at the same execution level as the DO command.

The value of the $TEST variable is never changed as a result of invoking a block structured subroutine. This differs from a subroutine that is invoked by a DO with an argument, which does not preserve the value of $TEST.

Associated Topics

FOR Command
QUIT Command
Block Structured Subroutines
DO with Parameter Passing
Extended Global References
Extended Routine References

Examples

Command	Explanation
DO X WRITE Y	The subroutine beginning at the line labeled X is executed, and then the variable Y is written.
D X,Y	This is equivalent to DO X DO Y.
D ^PGM W Y	Routine PGM is invoked, and then Y is written.
D A,^PGM,^ROU	Multiple routine names and labels may be listed as arguments.
D INT^PROG	Routine PROG is invoked beginning at the line labeled INT.
D:X=1 A^PGM,B,^TEST	The list of subroutines is invoked only if X=1.
D ^CEN:A=0,B	Routine CEN is invoked if A=0, and then subroutine B is invoked, regardless of the value of A.
D ^[TST,RMT]LABRSLT	Routine LABRST, from the TST UCI in the RMT volume group, is invoked.
D @X D @X^PGM D ^@XYZ D @A^@B D:@A=B @C^@D:@E=@F S R="^RTN:X=1" D @R	Indirection may be used in the DO command.
Example of argumentless DO command:

SAMPLE          ;SAMPLE PROGRAM FOR ARGUMENTLESS DO COMMAND
                ;
                WRITE !,"BEGIN ARGUMENTLESS DO TEST"
                DO  W !,"RETURN FROM SUBRTN"
                .WRITE !,"FIRST LINE OF SUB"
                .FOR I=1:1 DO  IF '(I#100) WRITE "." Q:$D(J)
                ..SET K=$RANDOM(I)
                ..IF K>1000 GOTO LABEL
                ..SET ^X(I)=I*K QUIT
LABEL           ..SET J=1
                ..QUIT ; this line is optional
                .WRITE !,"LAST LINE OF SUB"
                WRITE !,"END OF RTN"


DO with Parameter Passing

Calls a subroutine, passes it one or more parameters, and then continues execution with the next command upon completion of the subroutine.

Syntax

D{O}{:Postcond}SPEntryRef(ActualList){:Postcond}{,...}

Definition

Postcond	Any post-conditional expression.
EntryRef	Any valid entry reference.
ActualList	A list of arguments to pass to the called routine.
This form of the DO command allows you to call a routine and pass it one or more parameters using MSM's parameter-passing mechanism. Arguments in the ActualList can be passed to the routine using either call-by-value or call-by-reference parameter passing.

Normally, all arguments in the ActualList are passed to the routine using call-by-value. However, if the local variable name is preceded by a period, call-by-reference is used for the argument. Refer to "MSM Functions" in this manual for a description of how parameter passing is implemented in MSM.

The same general considerations and restrictions that exist for extrinsic functions apply to the DO command with parameter passing. The first line of the routine or subroutine specified by the EntryRef must contain a label reference with a formal list (FormalList). If it does not, then a <DPARM> error occurs.

If the specified ActualList is shorter than the FormalList, any variables in the FormalList that do not have a corresponding entry in the ActualList are undefined. The converse of this situation is not allowed. If the FormalList is shorter than the ActualList, a <DPARM> error occurs.

Associated Topics

DO Command
FOR Command
QUIT Command
Block Structured Subroutines
Extrinsic Functions

Examples

Command	Explanation
DO ^VOLUME(LEN,HEIGHT,DEP)	The VOLUME routine is invoked, and the LEN, HEIGHT, and DEP variables are passed as parameters.
D PRINT^INVOICE(CUST)	The INVOICE routine is invoked at entry point PRINT, and the CUST variable is passed as a parameter.
D ^%TRIAREA(BASE/2,HEIGHT)	The %TRIAREA routine is invoked and the value of BASE/2 is passed, as well as the value of the HEIGHT variable.
D ^%SQRT(.X)	The %SQRT routine is invoked, and the address of the variable X is passed. If the variable in %SQRT, which points to this address is updated or KILLed, then the X variable is updated or KILLed also.
D ^SEARCH(.^CUST)	It is illegal to pass global values by reference.


ELSE

Executes a group of commands only if the value of the $TEST special variable is false.

Syntax

E{LSE}

Definition

The ELSE command executes the commands that follow it on the same line only if the value of the $TEST special variable is 0. If the value is 1, all remaining commands on the line are ignored, and control passes to the next line in the routine. There must be at least two spaces between the ELSE command and the commands that follow it. The $TEST special variable is set by the IF command and by a command that is used with a timeout (READ, LOCK, ZALLOCATE, OPEN, JOB). Execution of an ELSE command does not affect the value of $TEST.

An ELSE command that is on the same line as an IF command is not executed unless an intervening command sets the value of $TEST. If the IF command sets $T to 0, the ELSE command is never executed. Post-conditional expressions on commands and arguments, as well as with the $SELECT function, often can be used in place of the ELSE command.

Associated Topics

$TEST Special Variable

Examples

The following three examples produce the same effect, except that the value of the $TEST special variable is not altered in the second and third examples.

IF X=1 WRITE "YES"
ELSE WRITE "NO"

WRITE:X=1 "YES" WRITE:(X=1) "NO"

WRITE $S(X=1:"YES",X'=1:"NO")


FOR

Controls repeated execution of all commands that follow it on a line for a specified sequence of values of a local variable.

Syntax

F{OR}

F{OR}SPLocalVar=ForParm{,...}

Definition

LocalVar	An expression that evaluates to a local variable name.
ForParm	A value used to describe the repetition of the loop. It must be in one of the following forms:  Expression Begin:Incr  Begin:Incr:End
Expression	Any valid expression.
Begin	A numeric expression that is the starting value of the loop.
Incr	A numeric expression whose value is added to the begin value for each repetition.
End	A numeric expression that is the ending value for the loop.
The FOR command is used to control repeated execution of the commands that follow it on the same line. All commands after the FOR command (starting with the first command after the FOR and through the last command on the same line as the FOR) are referred to as the scope of the FOR command. Although arguments on the FOR command cannot be listed, the ForParm can be listed and the different types of ForParm that are allowed can be intermixed. Although argument indirection is not permitted on the FOR command, name indirection is permitted in the Begin, Incr, and End portions of the ForParm.

Within a FOR command, each ForParm causes the local variable to be given a specified sequence of values, and the scope of the FOR command is executed once for each value. Successive ForParm sequences continue this process in left-to-right order. Any expression occurring in the local variable (for example, in a subscript or in indirection) is evaluated only once at the beginning of the FOR command prior to execution of any ForParm.

If the FOR command is specified without any operands (argumentless form), the command continuously loops until a QUIT or GOTO command is encountered within the scope of the FOR command.

The following sections describe how each ForParm format specifies and controls the values of the local variables and the sequence of executions of the scope of the FOR command.

Local=Expression

In this form, the local variable is assigned the value of the expression and the scope of the FOR command is executed once. The next ForParm, if one exists, is then processed. If none exists, then execution moves to the next line of M code.

Local=Begin:Incr

In this form, the following steps are performed.

1.	Assign the value of Begin to the local variable.

2.	Execute the Scope of the FOR command once.

3.	Add the value of Incr to the value of the local variable.

4.	Go to step 2.

This procedure specifies an endless loop. Termination of the loop must occur by execution of a QUIT or GOTO within the scope of the FOR command. Additional ForParms to the right of this type of ForParm are never performed.

Local=Begin:Incr:End

In this form, the following steps are performed if the value of Incr is 0 or greater than 0.

1.	Assign the value of Begin to the local variable.

2.	The system determines whether the value of the local variable is greater than the value of End. If it is, execution of the current ForParm is complete. The next ForParm, if one exists, is then processed. If none exists, execution moves to the next line of M code.

3.	Execute the scope of the FOR command once.

4.	The system determines whether the value of the local variable is greater than the value of End. If it is, execution of the current ForParm is complete. The next ForParm, if one exists, is then processed. If none exists, execution moves to the next line of M code.

5.	Add the value of Incr to the value of the local variable.

6.	Go to step 2.

If Incr is less than 0, the following steps are performed.

1.	Assign the value of Begin to the local variable.

2.	The system determines whether the value of the local variable is less than the value of End. If it is, execution of the current ForParm is complete. The next ForParm, if one exists, is then processed. If none exists, execution moves to the next line of M code.

3.	Execute the scope of the FOR command once.

4.	The system determines whether the value of the local variable is less than the value of End. If it is, execution of the current ForParm is complete. The next ForParm, if one exists, is then processed. If none exists, execution moves to the next line of M code.

5.	Add the value of Incr to the value of the local variable.

6.	Go to step 2.

If there is more than one FOR command in a line, their executions are considered to be nested. The FOR to the right is considered to be "within" or "inside" a FOR to the left. When two FOR commands are nested, one execution of the scope of the outer FOR includes one execution of the entire inner FOR command. This corresponds to one complete pass through the inner FOR's entire ForParm list (subject to early termination by a GOTO or QUIT).

Any execution of any command in the scope of a FOR is under control of exactly one ForParm of that FOR at the time of the command's execution. Two commands, GOTO and QUIT, have special effects when they are executed in the scope of a FOR command.

Execution of a QUIT within the scope of a FOR has the following effects:

•	The QUIT terminates this execution of the scope at the QUIT command. Any commands to the right of the QUIT are not executed during this iteration of the scope.

•	With respect to the innermost FOR in whose scope the QUIT occurs, the QUIT causes the remaining values specified by the controlling ForParm and all values specified by any remaining ForParms in the same parameter list, not to be calculated. The QUIT also causes the scope not to be executed under their control.

In other words, execution of a QUIT in the scope of a FOR causes the immediate termination of execution of the innermost FOR command. If there is a next outer FOR, execution of this QUIT causes the immediate termination of one execution of the scope of this FOR.

•	Execution of a GOTO within the scope of a FOR causes the immediate termination of all FORs to the left of the GOTO in the same line, and it transfers control to the point specified by the GOTO command.

Considerations

Within the scope of the FOR command, the code being executed can modify the value of the local variable. When this is done, execution continues until the end value is exceeded.

Associated Topics

DO Command
QUIT Command

Examples

Command	Explanation
FOR I=1:1 WRITE I QUIT:I>2 W "*"	The output is 1*2*3.
F I=1:1:3 W I	The output is 123.
F I=3:-2:-2 W I	The output is 31-1.
F I=5,3.4,7,9 W I	The output is 53.479.
F  Q:$DATA(^LOCK)	This routine executes until ^LOCK exists. In this example, the FOR command is followed by at least two spaces.
F I=.4,1:2:5,9,10:1 DO A IF I>15 QUIT	A is executed 12 times.
F I=1:1:2 F J=2:2:6 W I,"@",J,"*"	The output is the string: 1@2*1@4*1@6*2@2*2@4*2@6*
F I=1:1:3 F J=10:10:30 Q:I*J>30 W   I,"@",J,"*"	The output is the string: 1@10*1@20*1@30*2@10*3@10*
F I=3:5:0 W I	Nothing is written. The final value of I is 3.
F I=.01:.0001:.02 D A	This executes A 101 times.
F I=X:Y:Z D A	Routine A is called once for each iteration of the loop.
F I=1:2:10 S I=I-1 W I	Changing the value of the local variable which is used as the index is permitted. The output is 0123456789.
S Z=10 F I=2:2:Z S Z=Z-1 D A	Because the ending value of the loop is computed before the scope is executed, A is executed 5 times.
F I="TEST",X,3:4:5 ...	When the simple form of the FOR parameter is used, the index may be given non-numeric values.
F I=X:Y:Z F J=A:B:C G LCS	The GOTO exits from all nested FORs.
F I=@X:1:3 D @B	Name indirection can be used on the FOR command.
F @i=@X:@Y:@Z D @B	FOR using indirection.


GOTO

Transfers control to another statement in a program or to an entirely new program.

Syntax

G{OTO}{:Postcond}SPEntryRef{:Postcond}{,...}

Definition

Postcond	Any post-conditional expression.
EntryRef	Any valid entry reference.
The GOTO command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the GOTO command. For Postcond expressions on the arguments of the GOTO command, the argument is skipped if the expression is false. In contrast to the DO command, when arguments are listed, no more than one argument actually transfers control.

The GOTO command is used to pass control to a line of code in the current routine or to a line of code in a different routine. If the EntryRef does not contain a routine name, control passes to the label (or label + offset) in the routine that contains the GOTO command. When the EntryRef contains a routine name, control passes to the label (or label + offset) in the named routine. If no label (or label + offset) is specified with the routine name, control passes to the first line of the named routine.

The GOTO command can be used in a block structured subroutine, but only under the following condition: there can be no routine lines at a lower execution level (with fewer dots at the beginning of the line) between the GOTO command and the label which is the GOTO argument. In other words, GOTO is valid only within its own block structured subroutine. If this rule is violated, an error is not generated, but the routine executes in an unpredictable manner.

Associated Topics

Entry Reference
Execution Level
Block Structure Subroutine

Examples

Command	Explanation
GOTO XYZ	Execution continues at the start of the line labeled XYZ in the current routine.
GOTO ^PGM	Execution switches from the routine containing the GOTO to the first line of the routine PGM.
G CC+2^ABC	Execution switches to the second line after the line labeled CC in routine ABC.
G 13^GRAY:A=1	If and only if A=1, execution switches to the line labeled 13 in routine GRAY.
G:A=1 13^GRAY	This is equivalent to the previous example.
G ^ADM:A=0,X^CEN	If A=0, then execution switches to the first line of routine ADM; otherwise, execution switches to the line labeled X in routine CEN.
G:A=1 AAA:B=2,13:D=4	This line is equivalent to G AAA:A=1&(B=2) G 13:A=1&(D=4).
G @X G ^@B G A^@B G @A^B G @A^@B S A="^RTN:X=1" G @A	There are many opportunities to use indirection within the GOTO command. The first and last examples are using argument indirection. The others illustrate name indirection.
G:X=@Y @A+@C+D^@PGM:@E=@F	If execution switches, the line at which execution continues is @C+Dth line after label @A.


HALT

Terminates the user's session.

Syntax

H{ALT}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The HALT command is executed if the Postcond expression is true, or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the HALT command.

The HALT command is used to terminate the job that issues the command. When the job halts, all open devices are closed, all variables that are locked as a result of LOCK or ZALLOCATE commands are unlocked, and the partition associated with the job is released.

Examples

Command	Explanation
HALT	This is an unconditional HALT command.
H:A=1  WRITE "TEST"	If A=1, the process HALTs. Otherwise, execution continues and TEST is written to the current device. Note that there must be at least two spaces after the HALT command in this example.
H:A=@B	Indirection may be used in the post-conditional expression.


HANG

Suspends program execution for a specified period of time.

Syntax

H{ANG}{:Postcond}SPExpression

Definition

Postcond	Any post-conditional expression.
Expression	A numeric expression.
The HANG command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the HANG command.

The HANG command is used to suspend execution of a job for a specified period of time. The time interval is specified in whole seconds, fractions of a second, or a combination of whole seconds and fractions of a second. After the time interval expires, execution resumes with the next command following the HANG command. If the time interval is 0 or less than 0, the HANG command has no effect.

Examples

Command	Explanation
IF $PIECE($HOROLOG,",",2)<X HANG 3	If the number of seconds after midnight is less than X, then execution hangs for three seconds.
H:I=3 10 WRITE !	If I=3, a 10-second HANG is executed before the WRITE.
H @X H:$E(@A,B,@C) X+@Y+Z	Indirection may be used in the HANG command.
H 4.2	Fractional values may be used in the HANG command; however, the fractional part is ignored in all versions of MSM.


IF

Tests the validity of a truth-valued expression and executes a group of commands if it is true.

Syntax

I{F}

I{F}SP{TruthExp{,...}}

Definition

TruthExp 	An expression that evaluates to either true or false.

In the argumentless form, the IF command executes the commands that follow it on the same line, only if the value of the $TEST special variable is 1 (true). If the value is 0 (false), all remaining commands on the line are ignored, and control passes to the next line in the routine. The $TEST special variable is set by the IF command and by a command that is used with a timeout (READ, LOCK, ZALLOCATE, OPEN, JOB). Execution of an argumentless IF command does not affect the value of $TEST.

In the form of the IF command with an argument, the additional commands on the line are executed only if the value of the TruthExp is 1. If the value is 0, all remaining commands on the line are ignored and control is passed to the next line in the routine. When this form of the IF command is used, the $TEST special variable is assigned the value of the truth-valued expression.

When multiple arguments, separated by commas, are specified on the IF command, they are evaluated in left-to-right order. If all of the arguments are true (truth value of 1), the remainder of the line is processed. If any of the arguments are false, the remainder of the line is ignored.

Associated Topics

Truth-Valued Expressions

Examples

Command	Explanation
IF X=1 WRITE X	The code to the right of the IF command is executed only if X=1.
I Y SET Z=3	The code to the right of the IF command is executed only if the numeric interpretation of the value of Y is non-zero.
I X=2,Y=2 DO 3	The following are equivalent: IF X=2 IF Y=2 DO 3 IF X=2&(Y=2) DO 3
I X,^A(Y) GOTO 3	The following code is similar: IF X&(^A(Y)) G 3. However, the side effects are different because the latter always evaluates ^A(Y), while the former may not, depending on the value of X.
I X?1N2A!(Y=2)	Complex expressions occur frequently in IF commands.
IF X=1 W !,"TEST" ELSE W !,"EXAM" IF W "ARGUMENTLESS"	If X=1, this code writes TEST ARGUMENTLESS. Otherwise, it writes EXAM.
IF @X IF A,@B,C IF A=@B,@C=D,E=F+@G+H	Indirection may be used in the IF command.


JOB

Initiates execution of a new M process.

Syntax

J{OB}{:Postcond}SPJobParm{,...}

where JobParm is:

EntryRef{|UCI{,Vol{,Sys}}|}{:{({PartSiz}{:SymFlag})}{:TimeOut}}

Definition

Postcond	Any post-conditional expression.
EntryRef	Any valid entry reference.
UCI	The name of the user class identifier (UCI) that contains the program.
Vol	The name of the volume grop that contains the UCI and program.
Sys	The system or node name on which the program will be run.
PartSiz	The partition size in 1-K blocks.
SymFlag	A flag indicating whether or not the local symbol table of the current job is to be copied to the new job.
TimeOut	A timeout value.
The JOB command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the JOB command.

The JOB command is used to start a new M process (job), which is referred to as a background job in MSM. When the JOB command is executed, MSM assigns a new partition to the job if one is available. MSM then internally performs a DO command with the specified EntryRef as its argument. The new process executes in parallel with the process that contain the JOB command.

A user-class identifier (UCI), volume group (Vol), and system name (Sys) can be appended to the EntryRef to indicate where the routine specified in the EntryRef is stored. Alternatively, the UCI parameter can be an expression that evaluates to a string containing the UCI, Vol, and Sys names separated by a comma. For backward compatibility, the ANSI Standard vertical bars ( | ) can be used in place of the left bracket ( [ ) and right bracket ( ] ) characters.

Although the Vol and Sys parameters are both optional, Sys can be used only if Vol also is specified. The purpose of the Sys parameter is to resolve the ambiguity that occurs when a remote volume group is mounted. If Sys is not specified in this case, the job executes on the local system.

When the new process is started, it is assigned a unique job number and partition size equal to the size specified through the SYSGEN program. You can override this default value by including the PartSiz argument on the JOB command. The partition size is specified in 1-K blocks. When the JOB command completes, the $ZB special variable contains the job number of the job that was started. For networked systems, an offset can be added to the job number to ensure unique numbers throughout the network. If only PartSiz is specified in JobParm, parentheses are not required.

The SymFlag can be used to indicate whether the local symbol table of the job issuing the JOB command should be copied into the partition of the new job. The SymFlag is an expression that evaluates to a numeric value. A value of 1 indicates that the symbol table should be copied. When the symbol table is copied, only those variables that are visible (have not been hidden by the NEW command) are copied. A value of 0 indicates that the symbol table should not be copied. If the SymFlag is not specified, a value of 0 is assumed. SymFlag is ignored when the job is started on a different system.

If no additional partitions are available in the system, then the process issuing the JOB command is suspended until one becomes available. An indefinite suspension of the process can be avoided by including the TimeOut parameter. When a timeout is specified, execution is resumed after the specified interval, even if a partition is not available. The $TEST special variable then can be interrogated to determine whether a job was started. If the job was started successfully, the value of $TEST is 1 (true); otherwise, it is 0 (false). If the timeout value is 0 or less then 0, no suspension occurs and the value of the $TEST special variable is set to indicate the success or failure of the JOB command. After a timeout, $ZB is 0, indicating that no job was started.

Associated Topics

JOB with Parameter Passing
Entry Reference
$ZB Special Variable

Examples

Command	Explanation
JOB X	New process is initiated with the current routine, and execution begins with the line labeled X.
J ^A,^B,^C	In turn, a new process is initiated and execution begins at the first line of routines A, B, and C, respectively. A total of 3 new processes are initiated by this command. It is equivalent to JOB ^A JOB ^B JOB ^C.
J ^NAME::10 GOTO ERR:'$T	An attempt is made to start a new process at the first line of routine NAME. The command waits up to 10 seconds for the new process to begin. If it does, $T is 1. Otherwise, $T is 0, and execution switches to the line labeled ERR.
J ^NAME::10 ELSE G ERR	This is equivalent to the previous example.
J:N>6 ^TEST	Post-conditionals may be used.
J START^CUSLOOK:(24)	A new process is initiated with a 24-K partition. Execution begins at label START in routine CUSLOOK.
J ^NAME|"FMR","VAB"|	A new process is initiated and execution begins at the first line of routine NAME in the UCI called FMR on volume group VAB.
J ^NAME:(25:1)	A new process is initiated and execution begins at the first line of routine NAME with a 25-K partition and a copy of the current job's local symbol table.
J @X	Argument indirection may be used.
J ^|"PRD,APP,BAS"|NAME:(:1)	A new process is initiated on node BAS, regardless of whether or not the APP volume group is remotely mounted. Although the system indicates that the symbol table is to be copied, this feature is not honored (the parameter is ignored) for cross-system JOB commands.


JOB with Parameter Passing

Initiates execution of a new M process and passes to it one or more parameters.

Syntax

J{OB}{:Postcond}SPJobParm{,...}

where JobParm is:

EntryRef(ActualList){|UCI{,Vol{,Sys}}|}{:{({PartSiz} {:SymFlag})}{:TimeOut}}

Definition

Postcond	Any post-conditional expression.
EntryRef	Any valid entry reference.
ActualList	A list of arguments to pass to the new job.
UCI	The name of the user class identifier (UCI) that contains the program.
Vol	The name of the volume group that contains the UCI and program.
Sys	The system or node name on which the process is run.
PartSiz	The partition size in 1-K blocks.
Sym Flag	A flag that indicates whether or not the local symbol table of the current job is to be copied to the new job.
TimeOut	A timeout value.
This form of the JOB command allows you to pass one or more parameters to the new job using the MSM parameter-passing facilities. All entries in the ActualList are passed to the new job using call-by-value parameter passing. The M language does not support call-by-reference parameter-passing for the Job command. If a period is specified before a local variable name in the ActualList, a <DPARM> error occurs. Refer to "MSM Functions" in this manual for additional information on parameter passing.

The same general considerations and restrictions that exist for extrinsic functions also apply to the JOB command with parameter passing. This means that the first line of the routine or subroutine specified by the EntryRef must contain a label reference with a Formal List (FormalList). If it does not, a <DPARM error occurs.

If the specified ActualList is shorter than the FormalList, any variables in the FormalList that do not have a corresponding entry in the ActualList are undefined. The converse is not allowed. If the FormalList is shorter than the ActualList, a <DPARM> error occurs.

Associated Topics

Entry Reference
DO Command with Parameter Passing
JOB Command
Extrinsic Functions

Examples

Command	Explanation
JOB ^TASKMAN(FLAGS)	The TASKMAN routine is invoked, and the FLAGS variable is passed as a parameter.
J PRINT^INV(CUST,YTD/12)	The INV routine is invoked at entry point PRINT. The value of the CUST variable is passed as the first parameter, and the value of YTD/12 is passed as the second.
J ^UPDATE(X)["VAH"]	The UPDATE routine is invoked in UCI "VAH", and the value of the variable X is passed.
J ^REPORT["PRD","CPU"]	The REPORT routine is invoked in UCI "PRD" within volume group "CPU". The specified volume group may be on another machine if MSM-NET is in use.


KILL

Deletes all or part of one or more local and/or global variables.

Syntax

K{ILL}

K{ILL}{:Postcond}SPVariable{,...}

K{ILL}{:Postcond}SP(LocalVar{,...})

Definition

Postcond	Any post-conditional expression.
Variable	A local or global variable name.
LocalVar	An unsubscripted local variable name.
The KILL command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the KILL command.

The KILL command is used to delete local variables, global variables, or a combination of local and global variables.

There are three forms of the KILL command:

Argumentless form	KILL ALL
Variable,... form	Selective (inclusive) KILL
(LocalVar,...) form	Non-selective (exclusive) KILL
In the KILL ALL (argumentless form), all local variables that have not been hidden by the NEW command are deleted. After execution of this form, the local symbol table is empty.

In the selective KILL form, only the local or global variables specifically named as arguments of the KILL command are deleted. The local and global variable names can include subscripts.

In the exclusive KILL form, all local variables are deleted except the named local variables and their descendants. Global variable names and subscripted local variable names may not be specified in an exclusive KILL.

When a variable is deleted, all of its descendants also are deleted. If the specified variable does not exist, no action occurs. When arguments are listed, the selective KILL form can be mixed with the exclusive KILL form.

Associated Topics

Variables
NEW Command

Examples

Command	Explanation
KILL X	Local variable X is killed.
K X,Y,^A(3,4)	Local variables X and Y and global variable ^A(3,4) are killed.
K (A)	All local variables except A and its descendants are killed.
K (X,Y,ZZ1,%NAM)	All local variables except those named and their descendants are killed.
K SET X=$S	The argumentless form causes all local variables to be killed. After execution of this line, X is the only local variable defined.
K:Y=1 ^T(Y)	If Y=1, then ^T(1) is killed. All forms of KILL may have post-conditional expressions on the command.
K ^CUS	The entire ^CUS global is killed.
K @A K X,@Y,Z K:@Y=Z CUS(NUM,@NODE)	Indirection may be used in the KILL command.


LOCK

Provides a mechanism to synchronize control of a resource between two or more processes.

Syntax

L{OCK}

L{OCK}{:Postcond}SP{(+-}Variable{:TimeOut}{,...}

L{OCK}{:Postcond}SP{(+-}(Variable,...){:TimeOut}

Definition

Postcond	Any post-conditional expression.
Variable	A local or global variable name.
TimeOut	A timeout value.
The LOCK command is executed if the Postcond expression is true or if it is not supplied. If it is supplied and it is false, execution moves to the next command after the LOCK command.

The LOCK command is used to lock both local and global variables. The MSM system maintains a table of all locked variables, which is referred to as the LOCK table. When a user attempts to lock a variable, the system searches the table to determine if another user already locked the variable. If the variable is locked, the new lock is not granted.

When a lock is requested for a local variable, the lock is known throughout the system and no other system user can lock the variable. When the lock is for a global variable, the lock is known only within the UCI, and only users in the same UCI are prevented from locking the variable.

When a variable is unlocked, its name is removed from the LOCK table, thereby allowing other users to lock the variable. LOCK is only a convention. Rather than prevent users from accessing a locked variable, LOCK prevents them from locking the same variable. MSM does not require the variable that is to be locked to actually exist or have data. If all users follow the same conventions, simultaneous updates to the same data can be prevented.

The LOCK command functions in either of the following ways:

•	In the simple form, the user specifies one or more variables to lock, which replace the entire list of previously locked variables. The LOCK command first releases all existing locks that are owned by the job. Any jobs that were suspended while waiting for a locked variable can be resumed. No new variables are locked.  The LOCK command then attempts to lock all of the variable names in a left-to-right order. No variables are locked unless all of the variables in the argument can be locked.

•	In the other form, in which each variable name or the list of variables is preceded by a plus sign (+) or minus sign (-),  one or more variables are added to or removed from the list of currently locked variables. This is known as an incremental LOCK.

When incremental LOCKs are used, the LOCK command does not release any of the existing locks that are owned by the job. Any jobs that were suspended while waiting for a locked variable continue to be suspended. The LOCK command attempts to lock (plus sign used) or unlock (minus sign used) each of the variable names in left-to-right order. No variables are locked or unlocked unless all of the variables in the argument can be locked.

When multiple variables are to be locked, the names must be separated by commas and enclosed in parentheses. Listing the variable names separated by commas on the command does not have the same effect because the system interprets this as multiple LOCK commands.

The specified variable name must be a full reference; a naked reference is not permitted. If the variable name is unsubscripted, the entire variable (including all descendants) is locked. If a subscripted variable is used, the specified node and all descendants of the node are locked. In addition, all ancestors of the node are made unavailable for locking. The naked indicator is not updated for global references in the LOCK argument.

If any one of the LOCK variables cannot be obtained exclusively, the process issuing the LOCK command is suspended until it becomes available. An indefinite suspension of the process can be avoided by including the TimeOut parameter. When a timeout is specified, execution is resumed after the specified interval, even if a LOCK variable is not available. The $TEST special variable then can be interrogated to determine whether the LOCK was successful. If the LOCK was successful, the value of $TEST is 1 (true); otherwise, it is 0 (false).

If the timeout value is 0 or less then 0, no suspension occurs and the $TEST special variable is set to indicate the success or failure of the LOCK command. If the LOCK command does not complete before the time interval expires, then any variables previously locked by the same command are unlocked.

When a LOCK command is issued without any variables specified (the argumentless form), all locked variables are unlocked by the system.

Considerations

When incremental LOCKs with a plus sign are used and the same variable is specified, it is LOCKed multiple times. To remove the variable from the LOCK list, multiple incremental LOCKs with a minus sign or a lock with no arguments are required.

Associated Topics

ZALLOCATE Command
ZDEALLOCATE Command

Examples

Command	Explanation
LOCK ^TST	Between the time execution is resumed after this LOCK, and the time of execution of the next LOCK by this process, no other process is able to execute an argument of LOCK containing the unsubscripted global name ^TST or any subscripted global name whose name part is TST. In addition, any variables previously LOCKed by the process are unLOCKed.
L  SET X=1	The argumentless LOCK command unlocks all previous locks held by this process.
L (^P(1,2),^Q(3))	Between the time execution is resumed after the LOCK, and the time of execution of the next LOCK by this process, no other process is able to lock any of the following: ^P          ^P(1,2)         ^P(1,2,3) ^Q          ^Q(3)           ^Q(3,4,5) ^P(1)  However, any process can LOCK any of the following variables: ^P(2)       ^P(1,3,4)        ^Q(4)
L D(1):3 GOTO A:'$TEST	An attempt is made for an interval of three seconds to LOCK D(1). If it is successful, $T is 1. Otherwise, $T is 0 and execution continues with line A.
L +(A,^GL)	Add LOCKs for the two variables to the list of variables previously LOCKed by this job.
L +TEST,-B(1,2)	LOCK the variable TEST and unlock the variable B(1,2) without affecting other LOCKs for this job.
L D(1):3 ELSE  G A	This is equivalent to the previous example.
L:X=1 ^EF(^A(5))	The LOCK command can be post-conditionalized. Appearance of a global name does not affect the naked indicator unless, as in this example, it occurs in an evaluated expression. Here it is a subscript; other such possibilities are in post-conditionals and indirection. After this command, the naked indicator is set to ^A(.
L +^TST,-^Q(3),+A	This command adds ^TST to the list of locked variables, then removes ^Q(3) from the list, and then adds A.
L +(^TST,A),-^Q(3)	This command adds ^TST and A to the list of locked variables, and then removes ^Q(3) from the list.
L @A L:@B=C (X(@A),@B)	Indirection may be used in the LOCK command.


MERGE

Copies a tree or subtree of a local or global variable into the tree of another local or global variable.

Syntax

M{ERGE}{:Postcond}SPDestVar=SourceVar{,...}

Definition

Postcond	Any post-conditional expression.
DestVar	Either a local or global variable name, optionally with subscripts.
SourceVar	Either a local or global variable name, optionally with subscripts.
The MERGE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the MERGE command.

The MERGE command copies a specified local or global variable (SourceVar) to a specified local or global variable (DestVar). It also copies all of the descendants of the specified SourceVar into corresponding descendants of the specified DestVar. The copy operation can be defined as a series of rules.

For explanatory purposes, it is assumed that DestVar is represented as A(i1,i2, ... ,ix), where x '< 0, and that SourceVar is represented as B(j1,j2, ... ,jy), where y '< 0. By definition, if x or y is 0, the corresponding variable is unsubscripted. Similarly, if x or y is greater than 0, the corresponding variable contains one or more subscripts. Given these assumptions, the following rules determine the actual data that is copied by the MERGE command.

If $DATA (B(j1,j2, ..., jy) has a value of 1 or 11, the value of SourceVar is given to DestVar.

For every occurrence of z such that z > 0, and $DATA(B(j1,j2, ... ,jy+z) has a value of 1 or 11, the value of B(j1,j2, ... ,jy+z) is given to A(i1,i2, ... ,ix,jy+1,jy+2, ... ,jy+z)

The current value of the naked indicator is modified by the MERGE command. The new value assigned to the naked indicator is the same as if $DATA(SourceVar)#10=1 and the command SET DestVar=SourceVar were executed (the naked indicator is determined by the value of DestVar).

It is erroneous for the DestVar to be a descendant of the SourceVar, or for the SourceVar to be a descendant of the DestVar. If either occurs, MSM generates an error.

Considerations

The duration of the MERGE command can be lengthy. If MSM is interrupted during execution of the MERGE command (for example, if there is a system failure or the break key is pressed), only part of the data may be merged.

If the SourceVar contains any OLE automation object references then the object is copied to the DestVar and not the default value of the object.

Associated Topics

SET Command
$DATA Function
$ORDER Function

Examples

Command	Explanation
MERGE ^A=^B	All of global B is merged into global A.
M ^CUST("ABC",3,5)=CUST	Merge the local variable CUST into the global variable CUST(ABC,3,5).
M A(1)=A(2)	All of local A(2) is merged into the local A(1).
M A(1)=A(1,2)	This is an illegal operation because A(1,2) is a descendant node of A(1).
M @X=Y(1,2,3) M A(4,5,6)=@B M @A@(1,2)=B	Indirection is often used in the MERGE command.


NEW

Stacks one or more local variables or selected special variables, allowing creation of a new copy.

Syntax

N{EW}

N{EW}{:Postcond}SPVar{,...}

N{EW}{:Postcond}SP(LocalVar{,...})

Definition

Postcond	Any post-conditional expression.
Var	Any unsubscripted local variable name or selected special variables ($ETRAP, $ESTACK, $TEST, and $ZREFERENCE).
LocalVar	An unsubscripted local variable name.
The NEW command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the NEW command.

The NEW command is used to make temporary copies of local variables. When a temporary copy is created, the old variable, its value, and the values of all its descendants are copied onto a stack. The original variable then is removed from the local symbol table (KILLed). When a QUIT command is encountered on the same execution level as the NEW command was executed, the stacked values are restored to the local symbol table.

There are three forms of NEW:

Argumentless form	NEW ALL
Var,... form	Selective (inclusive) NEW
(LocalVar,...) form	Non-selective (exclusive) NEW
In the NEW ALL (argumentless form), all local variables are stacked and a KILL ALL (argumentless KILL) then is performed. After execution of this form, the local symbol table is empty.

In the selective NEW form, only the local variables or selected special variables specifically named as arguments of the NEW command are stacked. For local variables, a selective KILL is performed using the same argument. Local variable names may not include subscripts. If the name includes subscripts, an error occurs.

In the exclusive NEW form, all local variables are stacked except the named local variables and their descendants. An exclusive KILL is performed using the same argument. Subscripted local variable names cannot be specified in an exclusive NEW.

An inclusive NEW on a selected special variable makes a copy of the special variable. This copy is retrieved (unstacked) when the corresponding QUIT command is encountered. In the case of $ESTACK, the new command also resets it to zero.

Considerations

The NEW command works only on local variables and selected special variables, and not on global variables, structured system variables, system functions, or most special variables. In direct mode, the NEW command can be used to stack variables; however, after the command line is executed, an implicit QUIT is performed before returning to direct mode. This causes the stacked variables to be unstacked. Excessive use of the NEW command in a program can result in an out-of-space condition in the partition ($STORAGE=0).

Associated Topics

KILL Command
QUIT Command
$ETRAP Special Variable
$ESTACK Special Variable
$TEST Special Variable
$ZREFERENCE Special Variable

Examples

Command	Explanation
NEW X	This routine stacks local variable X.
NEW (A,B)	This routine stacks all local variables except A and B and their descendants. On a QUIT, the system does a KILL (A,B) and then unstacks the hidden A and B variables.
NEW	The argumentless form of NEW stacks all local variables.
N:X=1 X	This routine stacks local variable X and all of its descendants if and only if X=1.
N @X N A,@B,C N:@B=C (A,@B)	Indirection can be used in the NEW command.
The following routine illustrates the NEW stacking process. The output of this routine is OK.

NEWTEST;
       SET X=1  DO LABEL
       IF X=1,Y=4 WRITE "OK"
       QUIT
LABEL  NEW X
       S X=2,Y=X*2 QUIT

N $ESTACK,$TEST,$ZREFERENCE	Stacks the current values of $ESTACK, $TEST, and $ZREFERENCE. The current value of $ESTACK is reset to zero.


OPEN

Obtains ownership of a device.

Syntax

O{PEN}{:Postcond}SPDevice{{:Parm{:TimeOut}}}{,...}

Definition

Postcond	Any post-conditional expression.
Device	An integer expression that indicates which device is to be OPENed.
Parm	One or more expressions separated by colons and enclosed in parentheses that have meaning specific to the device being opened.
TimeOut	A timeout value.
The OPEN command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the OPEN command.

The OPEN command is used to acquire exclusive ownership of a device. For the OPEN command to be successful, the device must not be owned by any other partition. The device specified can be any valid MSM device number. The parameters specified on the OPEN command are specific to the device being OPENed. When a user logs on to MSM, the logon device is designated as the principal device (its value is assigned to $PRINCIPAL). This device is OPENed by the system and does not need to be OPENed by the user. All other devices must be OPENed before they can be accessed with a USE command.

If the device is not available, then the process issuing the OPEN command is suspended until it becomes available. An indefinite suspension of the process can be avoided by including the TimeOut parameter. When a timeout is specified, execution is resumed after the specified interval even if the device is not available. The $TEST special variable then can be interrogated to determine whether a device was OPENed.

If the device was successfully OPENed, the value of $TEST is 1 (true); otherwise it is 0 (false). If the timeout value is 0 or less then 0, no suspension occurs and the value of the $TEST special variable is set to indicate the success or failure of the OPEN command.

Associated Topics

USE Command
ZUSE Command
$PRINCIPAL Special Variable
Using Peripheral Devices, MSM User's Guide

Examples

Command	Explanation
OPEN 4	Ownership of device 4 is obtained. If another process already owns device 4, this process hangs until the device is available.
O 4,X,Y	Similarly, devices 4, X, and Y are OPENed in turn.
O X::3 G A:'$T	The process attempts to OPEN device X for up to three seconds. If it is successful, $T is 1 (true). Otherwise, $T is 0 (false) and execution continues at line A.
O X::3 ELSE  G A	This is equivalent to the previous example.
O:X=1 A,B,C	The OPEN command may be post-conditionalized.
O 3:(132::::1)	Device-specific parameters may be supplied on the OPEN. In this case, the right margin is set to 132 and echo is turned off.
O @X	Indirection can be used in arguments of the OPEN command.


QUIT

Terminates execution of a DO command, a FOR command, an XECUTE command, or an extrinsic function.

Syntax

Q{UIT}{:Postcond}

Q{UIT}{:Postcond}SPExpression

Definition

Postcond	Any post-conditional expression.
Expression	Any expression used to return a value.
The QUIT command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the QUIT command.

The QUIT command is used to terminate execution of any of the following: a subroutine that was invoked with a DO command, an XECUTE command, a FOR command, or an extrinsic function. When a QUIT command is encountered that is not on the same line as a FOR command, it causes an exit from the subroutine that was initiated by a DO or XECUTE command or an extrinsic function call. An XECUTE command can be thought of as a one-line subroutine. The QUIT returns to the calling routine and continues execution with the next command that follows the DO or XECUTE command or extrinsic function call that invoked the subroutine.

When the QUIT command is on the same line as a FOR command, it terminates the innermost FOR command. If the line containing the QUIT has only one FOR, execution of the QUIT terminates execution of the line. If the line has more than one FOR, execution of the QUIT causes termination of the innermost FOR and causes termination of the current repetition of the second-from-innermost FOR.

When a routine called as an extrinsic function terminates, the QUIT must include an Expression as an operand. If it does not, an error occurs. If the Expression evaluates to an object reference, the QUIT command returns the object reference rather than the value associated with the default property. Extrinsic functions are permitted to return object references, and the calling context decides whether to invoke the default property.  This differs from object references in most other contexts in which the default property is invoked.

Upon termination, the system returns to the argument immediately following the one that contains the extrinsic function reference. If the QUIT includes an expression and the routine was not called as an extrinsic function, an error occurs.

Considerations

Execution of the last line of a routine that does not transfer control to another location (falls off the end of a routine) causes an implicit QUIT to be performed.

Associated Topics

DO Command
FOR Command
HALT Command
NEW Command
XECUTE Command
ZSETOBJ Command

Examples

Command	Explanation
IF X>3 QUIT WRITE Y
Q:X>3 WRITE Y	These two examples do not have the same effect because the scope of the IF extends to the end of the line. In the first example, the WRITE Y is never executed.
Consider the following routine:

A	F I=1:1:100 D B Q:I+6+X>6 W I
W "END" Q
B	S X=I*2 D C W "B"
Q
C	W "C" Q

In this routine, the following occurs:

a.  The QUIT in line A terminates the FOR loop.
b.  The QUIT in line A+1 terminates the routine.
c.  The QUIT in line B+1 ends execution of the DO B, causing execution to return inside the FOR loop.
d.  The QUIT in line C ends execution of the DO C, causing execution to return to line B.

Q Y*2/3.14	Returns value from an extrinsic function to the calling routine.
Q @RETURN	Indirection may be used with the QUIT command.


READ

Reads information from the current device.

Syntax

R{EAD}{:Postcond}SPStringLit

R{EAD}{:Postcond}SPFormat

R{EAD}{:Postcond}SPVariable{#Length}{:TimeOut}

R{EAD}{:Postcond}SP*Variable{:TimeOut}

Definition

Postcond	Any post-conditional expression.
StringLit	A string literal.
Format	A formatting character or mnemonic namespace value that indicates the control characters to be sent to the device.
Variable	A local or global variable name.
#Length	An integer expression preceded by a # (pound sign) that indicates the number of characters to read.
*Variable	A local or global variable name preceded by an * (asterisk).
TimeOut	A timeout value.
The READ command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the READ command.

The READ command is used to accept input characters from the current device. Optionally, the READ command can send an output sequence to the device before accepting input. The different types of argument forms can be listed on the READ command to achieve the desired results. Each argument form is described below.

StringLit

The specified string literal is sent to the current device, and the value of the $X special variable is adjusted accordingly. If the current device does not allow output, an error occurs and the value of $X is not updated.

Format

The specified formatting characters or mnemonic namespace characters are sent to the current device, and the values of $X and $Y are adjusted accordingly. Multiple formatting characters can be specified in a single argument of the READ command. If the current device does not allow output, an error occurs and the values of $X and $Y are not updated.

Variable{#Length}{:TimeOut}

In this form, the system reads a string of characters from the current device and assigns the string to the specified local or global variable. If the #Length field is specified, the maximum length of the input string is the value specified by the Length field. If the Length field is not specified, a length of 255 characters is assumed for terminal devices. For non-terminal devices, no default value is assumed.

The READ operation terminates when a line terminator character is received (ESC key, RETURN key, or a user-defined read terminator), when the maximum number of characters have been read, or when a timeout occurs. When the READ operation terminates, the value of $X is updated to reflect the characters that were read.

If a TimeOut value is not specified on the READ, the job issuing the command is suspended until the READ command completes (a read terminator is received or the maximum number of characters is received). When a timeout is specified, execution resumes after the specified interval even if the READ command has not completed. The $TEST special variable can then be interrogated to determine whether any characters were received. If the READ terminated normally before the TimeOut interval, the input string is assigned to the local or global variable, the value of $X is updated, and the value of $TEST is 1 (true).

If the TimeOut occurs while the user is entering data, the received characters are assigned to the local or global variable, the value of $X is updated, and the value of $TEST is set to 0 (false). If no characters were received when the TimeOut occurred, the local or global variable is set to null, the value of $X is not adjusted, and the value of $TEST is 0 (false).

If the timeout value is 0 or less than 0, no suspension occurs and the value of the $TEST special variable is set to indicate the success or failure of the READ command. In this case, the READ can be satisfied only if there were characters in the typeahead buffer.

*Variable{:TimeOut}

In this form, MSM accepts one character of input from the current device and terminates the READ. The decimal equivalent of the received character is assigned to the specified local or global variable. If a TimeOut value is not specified, MSM waits until a character is received. The READ terminates when a single character is received. MSM does not wait for a line terminator character.

If a TimeOut value is specified, MSM waits for the duration of the specified interval. If the character is received before the TimeOut, the local or global variable is assigned the decimal value of the character, $X is updated, and the value of $TEST is true. If the character is not received, the local or global variable is assigned a value of -1, $X is not updated, and the value of $TEST is false.

Considerations

The MSM system supports typeahead, a feature that allows the user to type information into the system before the corresponding READ operation is performed. Information that is received in this manner is stored in the typeahead buffer. The typeahead buffer is discarded if the READ command includes a Format or StringLit argument.

The $X special variable is updated not because input is received, but rather because data is echoed back to the input device. The ECHO feature affects only terminal devices and can be disabled via the USE command.

Associated Topics

$TEST Special Variable
$X Special Variable
$Y Special Variable
Format Characters
Using Peripheral Devices, MSM User's Guide

Examples

Command	Explanation
READ X	A data string is entered into local variable X.
R X,Y,Z	Data strings are entered into local variables X, Y, and Z.
R "PATIENT? " ,^X	The message PATIENT? appears on the current device, and execution waits for data to be entered, after which it is placed in global X.
R !!,"FIRST?",X,?30,"SECOND?",Y	This code causes two carriage return line feeds to occur on the current device. The message FIRST? is then displayed. After data is entered into variable X, the device spaces to column 30 and the message SECOND? is displayed. Data may then be entered and read into variable Y.
R "TIMING?",X:10 GOTO A:'$T	After displaying TIMING?, the job waits for up to 10 seconds for input. If RETURN is pressed during this time period, $T is set to 1; otherwise, $T is 0, X may contain partial input, and execution continues at A. If no characters were entered, X contains the empty string.
R "TIMING?",X:10 ELSE  G A	This is equivalent to the previous example.
R *X,*Y,*Z	This form of the READ returns single characters that have been converted to their ASCII equivalent numeric codes. If the characters 'AB RETURN' are entered, then the following values result: X=65 Y=66 Z=13
R *X:10 E G A	The asterisk form may also use a timeout. If the timeout expires without a character having been entered, X has the value -1, and execution continues at A.
R X#10	Up to 10 characters can be entered before the READ terminates. The READ terminates after the tenth character is entered or when RETURN or ESC is entered.
R:$D(^A) !!,"TEST",X:12,*Y,   *Z:10,#,"SAMPLE",!,A:9	The READ command may include a post-conditional expression. All of the argument forms may appear in one argument list. If more than one timeout is present, the value of $T reflects the last executed timeout.
R /CUP(10,20),X	This routine positions the cursor using a mnemonic namespace sequence and READs a value into X.
R @X R X:@Y R:@C @X:@Y R *@A	Indirection can be used with the READ command.


SET

Assigns a value to a local or global variable.

Syntax

S{ET}{:Postcond}SPVariable=Expression

S{ET}{:Postcond}SP(Variable{,...})=Expression

Definition

Postcond	Any post-conditional expression.
Variable	A local or global variable name, or the $PIECE or $EXTRACT function containing a local or global variable name.
Expression	Any expression.
The SET command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the SET command.

The SET command is used to assign the value of an expression to one or more local variables. When multiple variables are to be assigned the same value, their names are separated by commas and enclosed in parentheses. Execution of the SET command occurs in the following order:

1.	Any indirection or subscripts that appear in the argument are evaluated in a left-to-right order.

2.	The Expression is evaluated according to the specified rules.

3.	Each Variable is evaluated one at a time in a left-to-right order ,and the value of the Expression is assigned to it. When the value is assigned, any of the following conditions can occur.

If a naked reference was used to specify the Variable to which the value is to be assigned, the naked indicator is used to produce the full reference. In turn, the full reference that is generated sets the naked indicator to a new value.

If the Variable includes subscripts and the specified node does not exist, the system creates the node and the minimum number of ancestor nodes required to provide a path to the new node. When the ancestor nodes are created, they are defined so that they have descendants but no data value (when the $DATA function is applied to the created ancestor node, its value is 10).

Considerations

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. When this form is used, the appropriate piece or substring is assigned the value of the Expression. The string specified in the $PIECE or $EXTRACT function can be extended if necessary to satisfy the function. For $PIECE, the string is padded with empty pieces using the specified delimiter. For $EXTRACT, the string is padded with blanks. Some special variables in MSM can be assigned values using the SET command. In particular, the values of $ECODE, $ETRAP, $X, $Y, $ZNAME, and $ZTRAP can be modified with the SET command.  SET $X and SET $Y do not move the cursor.

If the Expression evaluates to an object reference, the default property of that object is invoked, and the returned value is used as the value of the Expression.

Associated Topics

Variables
Objects
Binary EQUALS Operator
ZSETOBJ Command
$EXTRACT Function
$PIECE Function
$ECODE Special Variable
$ETRAP Special Variable
$X and $Y Special Variables
$ZERROR Special Variable
$ZNAME Special Variable
$ZTRAP Special Variable

Examples

Command	Explanation
SET ^X=Y	The value of the unsubscripted variable Y is assigned to the unsubscripted global variable ^X.
S ^A(1,2)=B(3,4)	The value of the subscripted variable Y is assigned to the subscripted global variable ^X.
S ^A(1)=X,B(4)=D,^C="TEST",Z=^D	Multiple arguments of SET.
S ^(2)=^C(X,2)+1	Because the expression to the right of the equal sign is evaluated before the variable name to its left is determined, the naked reference ^(2) denotes ^C(X,2). If the line had been:   S ^C(X,2)=^(2)+1 the meaning of the naked reference would depend on the state of the naked indicator prior to execution of the SET.
Command	Explanation
S (A,B,C)=123	This is a "multiple" set. All variables in the parentheses are set to the same value.
S (A,B,C,D)=0,^A(3)=W,(^A(3,4),   ^B(5))=I	Multiple and single SETs may be mixed in one command.
S ^A(5)=10,B(^(3))=^C(4)	When subscripts occur to the left of the equal sign, they are evaluated before the right side expression. Thus, this line is equivalent to:   S ^A(5)=10,B(^A(3))=^C(4)
S ^A(3)=10,^(^(3))=^C(4)	This line is executed as follows: a.  ^A(3) is given the value 10. b.  The subscript ^(3), which is ^A(3), is evaluated as 10. c.  ^C(4) is evaluated. d.  This value is given to ^(10), which is ^C(10). This line is then the same as:   S ^A(3)=10,^C(^A(3))=^C(4) The order is always: a.  First, evaluate left subscripts. b.  Then, evaluate right expression. c.  Then, evaluate left name.
S I=3,(I,I(4))=4	Even in a multiple set, the left-hand subscripts are evaluated before the assignment is made; however, each argument is completed before the next is begun. Thus, this line is equivalent to:   S I=3 S (I,I(4))=4 and I ends up with the value 4.
S:X=3 X=4.5	The SET command may include a post-conditional expression. In this example, if X has the value 3, then it is given the value 4.5.
S X=$S(X=3:4.5,1:X)	The $SELECT function is valuable when used in the right-hand expression of a SET command. This line has the same effect as example 10.
S X=X=3*1.5+X	The expression to be evaluated can be quite complex. In this example, the expression X=3*1.5+X is evaluated, and the result is given to the variable X.
S $PIECE(X,"^",3)=99	The third piece of the local variable X is assigned a value of 99. It is valid for only one $PIECE expression to the left of the equal sign. For example: S ($P(X,"^",3),$P(Y,"^",2))=Z is not allowed.
S $EXTRACT(X,7,20)=123	Positions 7 through 20 of the local variable X are set to the string 123. If X was previously longer than nine characters and shorter than 21 characters, its length will be nine after this command.
S $ZTRAP="^%ET"	The $ZTRAP special variable is set to the name of the system error trapping routine.
S @X S @A=B+C S A=@B+C S A=B+@(C_D)	Indirection is often used in the SET command.
SET CIRCLE.=5	If CIRCLE contains an object reference, the '.' indicates that the value 5 should be assigned to the default property of the object. This example could portray the radius of the circle equal to 5.
SET system.apps(jobnum)   .partsize=system.apps   (jobnum).partsize*2	Doubles the partition size for job jobnum. While evaluating the right side of the equal sign, MSM uses local variable system to point to the object. Its apps method is invoked with jobnum as a parameter. The resulting object reference is used to invoke the partsize property, which returns the partition size for the job. That value is used to set the partsize property of the object pointed to by method apps(jobnum) of object system.
SET (A,B.,$P(C.D,"^",5),$X)=   $$VALUE($H)	The extrinsic function $$VALUE is invoked with $H as a parameter. The value of the operand of the QUIT command which exits the extrinsic function is used to perform the multiple SETs. If the value is an object reference, then the default property of that object is invoked. Its returned value is then used to perform the SETs. The SET command then sets the value of A and the default property of the object referenced by B. The fifth "^" piece of the value of property D is updated, and then $X is updated. Errors are generated if: B or C do not contain object references, the object referenced by variable C does not support a method called D, or method D is read-only.


TCOMMIT

Indicates to the system that the most recently started transaction or sub-transaction has completed.

Syntax

TC{OMMIT}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The TCOMMIT command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the TCOMMIT command.

The TCOMMIT command indicates to the system that the current transaction or subtransaction is complete. If the $TLEVEL special variable is 1, TCOMMIT performs a commit of the transaction (applies all associated SETs and KILLs to the database) and sets the $TRESTART special variable to 0.

If $TLEVEL is greater than 0, TCOMMIT subtracts 1 from $TLEVEL. If $TLEVEL is 0, TCOMMIT generates an error.

Considerations

In MSM Version 4.3 and later, the commands and special variables associated with the M Development Committee (MDC) Type A Standard for transactions are only partially supported; however, the syntax is fully supported.

In addition, if the after-image journal is applied to the database (rolling forward a bulletproof database after a system failure or applying the journal after a database restore) the system attempts to apply only complete transactions (SETs and KILLs bracketed by TSTART and TCOMMIT). A future release of MSM will fully support transaction processing.

Associated Topics

TRESTART Command
TROLLBACK Command
TSTART Command
$TLEVEL Special Variable
$TRESTART Special Variable

Examples

Command	Explanation
TCOMMIT	Indicates to the system that the current transaction should be committed.
TC:UPDATE=1	Commits the transaction if and only if UPDATE is equal to 1.


TRESTART

Causes the current transaction to be restarted.

Syntax

TRE{START}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The TRESTART command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the TRESTART command.

The TRESTART command indicates to the system that the current transaction should be restarted. If $TLEVEL is greater than 0 and the transaction is marked as restartable (the TSTART command at $TLEVEL=1 indicates that it is restartable), TRESTART performs a restart. As part of the restart, local variables specified on the TSTART command (the TSTART issued with $TLEVEL=1) are restored to their original value; the program stack is restored to its original location; the naked indicator is restored; $TEST is restored; and any database updates performed by the job are rolled back. If $TLEVEL is 0, TRESTART generates an error.

Considerations

In MSM Version 4.3 and later, the commands and special variables associated with the M Development Committee (MDC) Type A Standard for transactions are only partially supported; however, the syntax is fully supported.

In addition, if the after-image journal is applied to the database (rolling forward a bulletproof database after a system failure or applying the journal after a database restore) the system attempts to apply only complete transactions (SETs and KILLs bracketed by TSTART and TCOMMIT). A future release of MSM will fully support transaction processing.

Associated Topics

TCOMMIT Command
TROLLBACK Command
TSTART Command
$TLEVEL Special Variable
$TRESTART Special Variable

Examples

Command	Explanation
TRESTART	Indicates to the system that the current transaction should be restarted.
TRE:ABORT=1	Restarts the current transaction if and only if ABORT is equal to 1.


TROLLBACK

Indicates the unsuccessful end of the current transaction.

Syntax

TRO{LLBACK}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The TROLLBACK command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the TROLLBACK command.

The TROLLBACK command indicates to the system that the current transaction was not successful. This means that any database changes initiated within the transaction are not reflected in the database. If $TLEVEL is greater than 0, TROLLBACK causes a rollback on the SETs and KILLs in the transaction; sets $TRESTART and $TLEVEL to 0; and causes the naked indicator to become undefined. If $TLEVEL is 0, TROLLBACK generates an error.

Considerations

In MSM Version 4.3 and later, the commands and special variables associated with the M Development Committee (MDC) Type A Standard for transactions are only partially supported; however, the syntax is fully supported.

In addition, if the after-image journal is applied to the database (rolling forward a bulletproof database after a system failure or applying the journal after a database restore) the system attempts to apply only complete transactions (SETs and KILLs bracketed by TSTART and TCOMMIT). A future release of MSM will fully support transaction processing.

Associated Topics

TCOMMIT Command
TRESTART Command
TROLLBACK Command
TSTART Command
$TLEVEL Special Variable
$TRESTART Special Variable

Examples

Command	Explanation
TROLLBACK	Indicates to the system that the current transaction should be rolled back.
TRO:ROLLBK=1	Rolls back the current transaction if and only if ROLLBK is equal to 1.


TSTART

Indicates the beginning of a transaction or subtransaction.

Syntax

TS{TART}{:Postcond}SPRestartVar{:TransParm}

Definition

Postcond	Any post-conditional expression.
RestartVar	One or more local variable names separated by commas and enclosed in parentheses or asterisk (*).
TransParm	One or more keywords or expressions separated by colons and enclosed in parentheses. When a single keyword or expression is specified, the parentheses can be omitted.
The TSTART command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the TSTART command.

The RestartVar parameter is used to specify one or more unsubscripted local variables that are to be saved at the start of the transaction. The names of the local variables to be saved are separated by commas and enclosed in parentheses. In place of the local variable names, an asterisk can be specified to indicate that all of the local variables are to be saved. When a single local variable name is specified, the parentheses can be omitted. For a transaction to be restartable, one or more local variables must be specified.

The TransParm parameter is used to specify information about the transaction. The user can specify SERIAL (abbreviated S) to indicate that the transaction is to be serialized relative to other transactions. The user also can specify TRANSACTIONID=Expression (abbreviated T=Expression) to identify arbitrary classes of transactions.

The TSTART command indicates to the system the beginning of a transaction or subtransaction . The TSTART command adds 1 to the current value of the $TLEVEL special variable. If, as a result, $TLEVEL is equal to 1, TSTART initiates a transaction that is restartable if a RestartVar has been specified. Otherwise, TSTART initiates a transaction that is not restartable. The transaction that is started is serializable independently of LOCKs if the SERIAL parameter is present. Otherwise, it is dependent upon LOCKs for serialization.

When a TSTART command is performed, the system places key information about the transaction on the system stack. This includes the values of $TEST and the naked indicator, the execution location of the TSTART command, a copy of the job's LOCK list, and the appropriate names and values of local variables specified by the RestartVar parameter.

Considerations

In MSM Version 4.3 and later, the commands and special variables associated with the M Development Committee (MDC) Type A Standard for transactions are only partially supported; however, the syntax is fully supported.

In addition, if the after-image journal is applied to the database (rolling forward a bulletproof database after a system failure or applying the journal after a database restore) the system attempts to apply only complete transactions (SETs and KILLs bracketed by TSTART and TCOMMIT). A future release of MSM will fully support transaction processing.

Associated Topics

LOCK Command
TCOMMIT Command
TRESTART Command
TROLLBACK Command
TSTART Command
$TLEVEL Special Variable
$TRESTART Special Variable

Examples

Command	Explanation
TSTART	Indicates to the system the start of a transaction.
TS:$TLEVEL=0	Starts a transaction if and only if $TLEVEL is equal to 0.
TS *:S	Starts a serializable transaction after saving all of the local variables for the job.
TS (A,B,C):T=2	Starts a transaction with an ID of 2 after saving local variables A, B, and C.


USE

Designates a specified device as the current device.

Syntax

U{SE}{:Postcond}SPDevice{:Parm{:Domain}}

Definition

Postcond	Any post-conditional expression.
Device	An integer expression that indicates which device is to be used.
Parm	One or more expressions separated by colons and enclosed in parentheses that have meaning specific to the device being used.
Domain	The name of the mnemonic namespace to be used with the device.
The USE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the USE command.

The USE command makes the specified device the current device. Unless the specified device is the principal device, ownership of the device must have been obtained previously with the OPEN command. All input/output operations are always performed using the current device.

When a CLOSE command is executed for the current device, the system automatically makes the principal device the current device. No attempt is made to OPEN the principal device. If an error condition occurs and the $ZTRAP special variable has not been set to trap the error, the system makes the principal device the current device before issuing the error message.

The device specified on the USE command can be any valid MSM device. The Parm specified for the device is specific to the device type. When arguments are listed, the last argument in the list becomes the current device.

The MSM system maintains device-specific information separately for each device. This includes the $DEVICE, $KEY, $X, $Y, $ZA , $ZB, and $ZC special variables, as well as options specified through the Parm specified for a device.

Associated Topics

OPEN Command
CLOSE Command
$DEVICE Special Variable
$KEY Special Variable
$X and $Y Special Variables
$ZA, $ZB, and $ZC Special Variables
Using Peripheral Devices, MSM User's Guide

Examples

Command	Explanation
USE 4	Device 4 is specified for routing of READ and WRITE data.
U 4 SET X=$IO	X receives the value 4.
U 3:132	Device 3 has the right margin set to 132 and is the current device.
U:X'=0 X	The USE command may include a post-conditional expression. This example inhibits making device 0 the current device.
U 64::"X3.64-1979"	Device 64 is assigned the ANSI X3.64-1979 mnemonic namespace.
U @X	Argument indirection is permitted.


VIEW

Modifies specific memory or disk database locations.

Syntax

V{IEW}{:Postcond}SP{-}Block{:VolGroup}

V{IEW}{:Postcond}SPViewParm where ViewParm is of the form:

Address:{Domain}:Expression{:{ Length}{:Type}}

Definition

Postcond	Any post-conditional expression.
Block	An expression that identifies a disk block.
VolGroup	A string value identifying a volume group.
Address	An integer expression.
Domain	An integer expression that indicates the area of memory to modify.
Expression	An expression that is to be assigned to the memory area.
Length	An integer expression that specifies the length of the area in memory to modify.
Type	Indicates the data type of Expression.
The VIEW command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the VIEW command.

The VIEW command is used to modify the contents of memory and to read or write disk blocks in the MSM database. In the first form, it is used to access the MSM database.

The VolGroup specifies the name of the volume group, and the block number specifies the relative block within the volume group. The VolGroup is specified using the letter G followed by the volume group number from 0 through 31 (for example: G0, G1, and so on).

The first block of a volume group is 0, the second block is 1, and so on. If the block number is non-negative, the specified block is read into the VIEW buffer. If it is negative, the specified block is written from the VIEW buffer to the database. When this form of the VIEW command is used, the VIEW device (device 63) must be owned.

In the second form, the VIEW command is used to modify the contents of system memory. The user specifies a relative address within memory, the type of memory, the replacement value, the length of memory to be replaced, and the replacement type. It is not necessary to own the VIEW device to patch memory unless the area being patched is within the VIEW buffer.

The Address argument is any positive integer, either odd or even (word boundary alignment is not required). The range of the number is determined by the area of memory being patched. When patching system memory, the value may be from 0 through the last byte address of the machine. For partitions, the range is from 0 through the last byte address in the partition vector. For the VIEW buffer, the range is from 0 through the last byte address of the VIEW buffer (normally 1023).

The Domain argument is used to indicate which area of memory is to be patched. Negative values indicate system memory. A value of 0 indicates the VIEW buffer. When this area is specified, the user must own the VIEW device. A value greater than 0 indicates a job's partition, where 1 is the partition associated with job number 1, 2 is the partition associated with job number 2, and so on. If this argument is omitted, a value of -3 is assumed.

The Expression argument specifies the new value that is to be patched into memory. It must evaluate to the form indicated by the Type argument. If this argument is not specified, a syntax error occurs.

The Length argument indicates the size of the memory area that is to be patched. For integers, this is a maximum of four; for real numbers, it must be exactly eight. For string values, this number can be any value up to 65536. Numbers of this size can only be used to move areas within memory or to display areas of memory on the current device. If this value is omitted, the natural word size of the machine is assumed (two for 16-bit machines and four for 32-bit machines). A length of eight is assumed if Type = 4. A length equal to $L(Expression) is assumed if Type = 1.

The Type argument is used to indicate the data type of value being patched into memory. A value of 0 indicates an integer, a value of 1 indicates a character string, and a value of 4 indicates a real (floating point) number. If this argument is omitted, a value of 0 is assumed.

Associated Topics

$VIEW Function
Using Peripheral Devices, MSM User's Guide

Examples

Command	Explanation
VIEW 20	Reads block 20 from the MSM database.
V 1:0:255:1	Replaces the second location in the VIEW buffer with 255.
V-20	Writes the VIEW buffer to the MSM database at block number 20.
V 120:0:"TEST":4:1	Moves the character string TEST into location 120 of the VIEW buffer.
V 5:"G1"	Reads block 5 from volume group index number 1.


WRITE

Writes constants and variables to the current device.

Syntax

W{RITE}{:Postcond}SPFormat

W{RITE}{:Postcond}SPExpression

W{RITE}{:Postcond}SP*Integer

Definition

Postcond	Any post-conditional expression.
Format	One or more format or mnemonic controls.
Expression	Any valid expression.
*Integer	Any valid integer expression.
The WRITE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the WRITE.

The WRITE command is used to output data to the current device. Arguments can be listed on the WRITE command, and argument types can be intermixed in a single command. If the current device does not allow output operations, an error occurs.

Format

The WRITE Format form is used to send control commands or mnemonic namespace sequences to a device. One or more formatting characters can be specified in each argument. The values of $X and $Y are adjusted accordingly.

Expression

The WRITE Expression form causes the value of the Expression to be written to the output device, one character at a time, in left-to-right order. The effect of each character sent to the device is defined by the ASCII Standard and conventions. The values of the $X and $Y special variables are updated accordingly.

*Integer

The WRITE *Integer form is a one-character write operation that sends the ASCII character whose decimal code is equal to the integer expression specified as the argument. The expression is evaluated as modulo 256. This form allows the programmer to send device-specific sequences to the current device (for example: Escape sequences or ring the bell). Depending on the device type of the current device, the value of Integer may be interpreted as a device control command rather than a single character.

Associated Topics

Mnemonic Namespaces
Format Characters
$X and $Y Special Variables
$DEVICE Special Variable
$KEY Special Variable
$ASCII Function
$CHAR Function

Examples

Command	Explanation
WRITE X	This routine writes the contents of local variable X to the current device.
W !,"Line Feed",#,"Form Feed",   ?20,"TAB",A(3)	The arguments used on the WRITE command may be mixed.
W *7,*7,*97	This command rings the bell twice, and then outputs the character a to the current device.
W X,*Y,*Z,!!,"TEST",A=B	Expressions containing operators may be used as arguments.
W:X>10 $J(X,7,2)	The WRITE command may be post-conditionalized. The $JUSTIFY function is frequently used in the WRITE command.
W /CUP(10,20),X	This routine positions the cursor using a mnemonic namespace sequence and then writes the value of X.
W @X W Z,@X,Y	Indirection may be used in arguments of WRITE.


XECUTE

Allows interpretation and execution of commands that were stored as data.

Syntax

X{ECUTE}{:Postcond}SP{Expression}{:Postcond}{,...}

Definition

Postcond	Any post-conditional expression.
Expression	Any valid expression.
The XECUTE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the XECUTE command. For Postcond expressions on the argument of the XECUTE command, the argument is skipped if the expression is false.

The XECUTE command is used to execute a line of M code that has been specified as an argument to the command. Each argument of the command must evaluate to a string, and the string must be a line of M code in the format returned by the $TEXT function. In this form, it does not contain a leading TAB, does not end with RETURN, and must not contain a label at the beginning of the string. When execution of the argument terminates, it returns to process the next argument of the command or the next command following the XECUTE command.

Considerations

The XECUTE command can be thought of as a DO of a one-line subroutine. When the one-line subroutine is complete, an implicit QUIT is performed by the system.

Associated Topics

DO Command
GOTO Command
QUIT Command

Examples

Command	Explanation
XECUTE A	If A has the value "S X=1", then X receives the value 1.
X "S X=B Q:X<3 W Y" W "OUT"	In this example, the QUIT in the value of the argument may terminate the execution of the subroutine. The "OUT" is always written.
X "G A" W "OUT"	The string "OUT" is written when A issues a QUIT command.
X A,B_" D 3 G "_C,D	XECUTE may have multiple arguments. Note the use of concatenation for stringing together commands and arguments.
X:Y=1 A_" X B,C",Z	XECUTE may contain a post-conditional expression. Note the nesting of XECUTEs.
X A_" X B,C",Z:Y=1	XECUTE may contain a post-conditional expression in the argument of the XECUTE.
X @Y,"I @A G "_@D	This routine provides an example with indirection at two levels.


ZALLOCATE

Incrementally LOCKs one or more local or global variables.

Syntax

ZA{LLOCATE}{:Postcond}

ZA{LLOCATE}{:Postcond}SPVariable{:TimeOut}

ZA{LLOCATE}{:Postcond}SP(Variable{,...}){:TimeOut}

Definition

Postcond	Any post-conditional expression.
Variable	Any local or global variable name.
TimeOut	A timeout value.
The ZALLOCATE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZALLOCATE command.

The ZALLOCATE command is used to lock both local and global variables. The MSM system maintains a table of all locked variables (the LOCK table). When a user attempts to ZALLOCATE a variable, the table is searched to see if it is already locked by another user. If so, the LOCK request is not granted.

When a lock is requested for a local variable, the lock is known throughout the system and no other system user can lock the variable. When the lock is for a global variable, the lock is known only within the UCI and only users running in the same UCI are prevented from locking the variable.

When a variable is ZDEALLOCATEd, its name is removed from the LOCK table. Other users then can lock the variable.  ZALLOCATE is only a convention. Rather than preventing users from accessing the locked variable, ZALLOCATE only prevents them from issuing a LOCK or ZALLOCATE command for the same variable. In fact, there is no requirement that the locked variable actually exist. The goal is to have all users follow the same conventions so that simultaneous updates can be prevented.

Unlike the simple form of the LOCK command, the ZALLOCATE command does not automatically unlock previously locked variables before trying to lock the variables specified in the argument. Because the ZALLOCATE command has a cumulative effect, listing variable names on the command is equivalent to separating the names with commas and enclosing them in parentheses.

The specified variable name must be a full reference. A naked reference is not permitted. If the variable name is unsubscripted, the entire variable (including all descendants) is locked. If a subscripted variable is used, the specified node and all descendants of the node are locked. In addition, all ancestors of the node are made unavailable for locking. The naked indicator is not updated for global references in the LOCK or ZALLOCATE argument.

If any one of the ZALLOCATE arguments cannot be obtained exclusively, the process issuing the ZALLOCATE command is suspended until it becomes available. An indefinite suspension of the process can be avoided by including the TimeOut parameter. When a timeout is specified, execution is resumed after the specified interval even if a ZALLOCATE argument is not available. The $TEST special variable then can be interrogated to determine whether the ZALLOCATE was successful. If the ZALLOCATE was successful, the value of $TEST is 1 (true); otherwise, it is 0 (false). If the timeout value is 0 or less then 0, no suspension occurs and the value of the $TEST variable is set to indicate the success or failure of the ZALLOCATE command.

Compatibility Note

The ZALLOCATE command has been retained for compatibility with older releases of the MSM system. This command should no longer be used. Instead, the incremental locking and unlocking capabilities of the LOCK command should be used.

Considerations

When multiple ZALLOCATE commands are issued for the same variable, it is LOCKed multiple times. Multiple ZDEALLOCATE commands are required to remove it from the LOCK list.

Associated Topics

LOCK Command
ZDEALLOCATE Command

Examples

Command	Explanation
ZALLOCATE ^TST	Between the time execution is resumed after this ZALLOCATE and the time of execution of a ZDEALLOCATE containing ^TST by this process, no other process is able to execute an argument of LOCK or ZALLOCATE containing the unsubscripted global name ^TST or any subscripted global name whose name part is TST. In addition, any variable previously LOCKed or ZALLOCATEd by the process remain LOCKed or ZALLOCATEd.
ZA ^P(1,2),^Q(3)	Between the time execution is resumed after the ZALLOCATE, and the time of execution of a ZDEALLOCATE with an argument of either ^P(1,2) or ^Q(3) by this process, no other process is able to LOCK or ZALLOCATE any of the following: ^P      ^P(1,2)    ^P(1,2,3) ^Q      ^Q(3)      ^Q(3,4,5) ^P(1) However, any process can LOCK or ZALLOCATE any of the following variables: ^P(2)    ^P(1,3,4) ^Q(4)
Command	Explanation
ZA D(1):3 G A:'$T	An attempt is made for an interval of 3 seconds to ZALLOCATE D(1). If it is successful, $T is Otherwise, $T is 0 and execution continues with line A.
ZA D(1):3 ELSE G A	This routine is equivalent to the previous example.
ZA:X=1 ^EF(^A(5))	The ZALLOCATE command can be post-conditionalized. Appearance of a global name does not affect the naked indicator unless, as in this example, it occurs in an evaluated expression. Here it is a subscript; other such possibilities are in post-conditionals and indirection.
ZA @A ZA:@B=C (X(@A),@B)	Indirection may be used in the ZALLOCATE command.


ZDEALLOCATE

Incrementally unLOCKS one or more local or global variables.

Syntax

ZD{EALLOCATE}{:Postcond}

ZD{EALLOCATE}{:Postcond}SPVariable

ZD{EALLOCATE}{:Postcond}SP(Variable{,...})

Definition

Postcond	Any post-conditional expression.
Variable	Any local or global variable name.
The ZDEALLOCATE command is used to unlock one or more variables that were locked using the ZALLOCATE command. In the argumentless form, all variables for the current job that were locked with the ZALLOCATE command are unlocked. In the form with arguments, only the variables specifically named as arguments are unlocked. Locked variables not specified in the arguments remain locked.

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.

Compatibility Note

The ZDEALLOCATE command has been retained for compatibility with older releases of MSM. This command should no longer be used. The incremental locking and unlocking capabilities of the LOCK command should be used instead.

Associated Topics

LOCK Command
ZALLOCATE Command

Examples

Command	Explanation
ZALLOCATE (^A,^B,^C) ZDEALLOCATE ^A	Removes ^A from the list of variables LOCKed by the process. The variables ^B and ^C remain LOCKed by the process.
ZA (^A,^B,^C) ZD (^A,^B) ZA (^D,^E)	Removes ^A and ^B from the list of variables LOCKed by the process and adds ^D and ^E to the list.
ZD:X=1 ^EF(^A(5))	The ZDEALLOCATE command can be post-conditionalized. Appearance of a global variable name does not affect the naked indicator unless (as in this example), it occurs in an expression that is evaluated. Here it appears as a subscript; other such possibilities are in indirection and post-conditional expressions.
ZA @A ZD:@B=C X(@A),@B	Indirection may be used in the ZDEALLOCATE command and arguments may be listed.


ZFLUSH

Empties the disk buffer cache of all buffers.

Syntax

ZF{LUSH}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The ZFLUSH command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZFLUSH command.

The ZFLUSH command is used to flush all disk blocks out of the internal disk buffer cache. All modified buffers are rewritten to the database and then deleted from the cache. Unmodified buffers are deleted from the cache without being written to disk. Any subsequent references to routines or globals require the system to reread the routine or global disk blocks from disk rather than use the values in memory.

Associated Topics

Buffer Pool

Examples

Command	Explanation
ZFLUSH	Flushes all buffers from the cache.
ZF:X=1	Flushes all buffers from the cache if X=1.


ZGO

Resumes execution of a program that was suspended by a BREAK command.

Syntax

ZG{O}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The ZGO command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZGO command.

The ZGO command is used to resume execution of a routine that was suspended by a BREAK command. A BREAK command suspends execution of a routine only when the interactive debugger was used to invoke the routine. While the routine is suspended, enter any M commands or interactive debugger commands. Enter a question mark (?) to display a list of valid debugger commands. Changes made to the routine while it is suspended prevent the ZGO command from restarting the suspended routine.

Associated Topics

BREAK Command
Interactive Debugger

Examples

Command	Explanation
S X=^A(3) I X=0 B K ^A	When this statement is executed, the routine is suspended. This allows the programmer to examine the job's status before the KILL.
ZGO	Routine execution continues with the statement that caused the program to be suspended.
ZG:^A(0)=1	Execution of the routine proceeds only if ^A(0)=1.


ZHOROLOG

Adjusts the date, time, or both for the current job.

Syntax

ZHOROLOG{:Postcond}SP{{±}Date}:{±}Time}}

Definition

Postcond	Any post-conditional expression.
Date	A date value in $HOROLOG format.
Time	A time value in $HOROLOG format.
The ZHOROLOG command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZHOROLOG command.

The ZHOROLOG command is used to temporarily adjust the date, time, or date and time that are returned by the $HOROLOG function. When the Date operand is specified and is preceded by a plus sign (+) or minus sign (-), the value is added to or subtracted from the date portion of the actual system $HOROLOG. Otherwise, the actual value specified by the Date operand is returned by the $HOROLOG function.

Similarly, when the Time operand is specified and is preceded by a plus (+) or minus (-) sign, the value is added to or subtracted from the time portion of the actual system $HOROLOG. Otherwise, the actual value specified by the Time operand is returned by the $HOROLOG function.

If either operand is omitted, the $HOROLOG function returns the actual system date or time as appropriate. If no operands are specified, $HOROLOG is reset to the actual system date and time. The ZHOROLOG command affects the value of the $HOROLOG special variable only for the partition that issued the ZHOROLOG command. Other partitions get the unadjusted actual system $HOROLOG value. This command cannot be abbreviated.

Associated Topics

$HOROLOG Special Variable

Examples

Command	Explanation
ZHOROLOG:X=1 -10	The ZHOROLOG command sets the date back 10 days only if X=1.
ZHOROLOG -1:-3600	The ZHOROLOG command sets the date to yesterday and the time to one hour earlier.
ZHOROLOG @X	Indirection may be used with the ZHOROLOG command.


ZINSERT

Inserts a line of code into the current routine.

Syntax

ZI{NSERT}{:Postcond}SPExpression{:LineRef}

Definition

Postcond	Any post-conditional expression.
Expression	An expression that evaluates to the text of the line to be inserted.
LineRef	A line reference indicating the insert point.
The ZINSERT command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZINSERT command.

The ZINSERT command is used to insert a line of code into the routine that is currently loaded into the partition. The Expression argument denotes the line of text to be inserted. It must evaluate to a string that is in the proper format to be inserted into the routine. The format of the string must be one of the following:

labelSPcommand line

labelTABcommand line

SPcommand line

TAB command line

This is the same format returned by the $TEXT function. The LineRef argument specifies the location within the routine where the text is to be inserted. The LineRef expression must evaluate to a line label (for example: ABC), a line label plus an offset (for example: ABC+3), or simply an offset (for example: +3). The text specified by expression is inserted immediately following the line specified by LineRef.

If the LineRef argument is omitted, the current implicit line pointer location is used. The implicit line pointer location is set by the ZPRINT and ZREMOVE commands. ZINSERT does not alter the implicit line pointer location.

Considerations

The ZINSERT command can be issued only from within an XECUTE command or from the open command language (the > prompt). To prevent the loss of issued ZINSERT lines, issue a ZSAVE command to store the routine permanently in the database.

Associated Topics

Using the MSM System, MSM User's Guide
$TEXT Function
ZLOAD Command
ZPRINT Command
ZREMOVE Command
ZSAVE Command

Examples

Assume the following routine is loaded into the partition:

ABC	;SAMPLE
SET X=3 WRITE Y
READ X
Z	WRITE !,X line

Command	Explanation
ZINSERT "DEF READ X":ABC	This routine inserts a line after the line labeled ABC.
ZI " SET Y=X+4"	This routine inserts the line after the current insert point.
ZI " W !!,X+Y":+4	This routine inserts the line after the fourth line of the program.
ZI:X=1 Y:+T	The ZINSERT command may include a post-conditional expression.
ZI @X	Indirection may be used in the ZINSERT command.
ZI "HDR ;NEW LINE":+0	This routine inserts a line before the first line of the program.


ZLOAD

Loads a routine from the database or current device.

Syntax

ZL{OAD}

ZL{OAD}{:Postcond}SP{RoutName}

Definition

Postcond	Any post-conditional expression.
Routname	Any valid routine name.
The ZLOAD command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZLOAD command.

The ZLOAD command is used to load a routine into the partition from the current device or from the MSM database. In the argumentless form, the routine is loaded from a device. The device that contains the routine to be loaded must be OPEN, and it must be the current device. In this form, the input lines are entered in the same format returned by the $TEXT function, and each line is terminated with RETURN. End of input is signaled by a null line (a line that contains only RETURN).

In the form with an argument, the specified routine is loaded from the routine directory in the current UCI. The routine name begins with an alpha character or a percent sign (%) and is followed by alphanumeric characters. If the name is longer than eight characters, all characters after the eighth one are ignored. The name is not preceded by the circumflex (^) character.

Considerations

As the first step in executing a ZLOAD command, an implicit ZREMOVE command with no arguments is performed. This clears any existing routines from the partition. addition, because ZLOAD removes the current routine, it can only be used in direct mode or in an XECUTE command.

Associated Topics

$TEXT Function
$ZNAME Special Variable
ZINSERT Command
ZREMOVE Command
ZSAVE Command
Using the MSM System, MSM User's Guide

Examples

Command	Explanation
ZLOAD ABC	Loads routine ABC from the current UCI into the partition.
ZL	Loads a routine into the partition from the current device.
ZL:X=1 XYZ	Loads routine XYZ into the partition only if X=1.
ZL @X	Allows indirection to be used with the ZLOAD command.


ZMSM

Displays the sequence of program execution within a routine and from routine to routine.

Syntax

ZM{SM}{:Postcond}SPExpression{:Device}

Definition

Postcond	Any post-conditional expression.
Expression	An integer expression that indicates the type of trace to perform.
Device	A device designator indicating the output device for the trace.
The ZMSM command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZMSM command.

The ZMSM command is used to trace the flow of various types of events in MSM to aid in debugging. The Expression argument is used to indicate the type of function in MSM that is to be traced. If the value of the Expression is 0, the trace is disabled. If it is greater than 0, one or more functions within MSM are traced. The following table lists the events that can be traced.

Level	Event to be traced
0	Turns off trace
1	Traces DO, GOTO, XECUTE and QUIT
When trace is enabled, descriptive messages about the events are displayed on the current device. By specifying the Device argument, these messages can be directed to some other device. The device must be owned by the job (OPEN); otherwise, an error occurs.

Associated Topics

Using Peripheral Devices, MSM User's Guide

Examples

Command	Explanation
ZMSM 1	This routine enables the trace function to display the execution path.
ZM 1:3	The trace function is enabled and the output is directed to device 3.
ZM 0	The trace function is disabled.
ZM:X=1 1	The trace function is only be enabled if X=1.
ZM @X	Indirection may be used in the ZMSM command.


ZNEW

Stacks one or more local variables, allowing creation of a new copy.

Syntax

ZN{EW}{:Postcond}SPLocalVar{,...}

Definition

Postcond	Any post-conditional expression.
LocalVar	An unsubscripted local variable name.
The ZNEW command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZNEW command.

The ZNEW command is used to make temporary copies of unsubscripted local variables. When a temporary copy is created, the old variable, its value, and the values of all its descendants are copied onto a stack. When a QUIT command is encountered, the stacked values are restored (merged) to the local symbol table.

Only the local variables specifically named as arguments of the ZNEW command are stacked. Local variable names cannot include subscripts. If the name includes subscripts, an error occurs. Variables are not killed after they are stacked.

Considerations

The ZNEW command only works on local variables, not global variables. In direct (programmer) mode , the ZNEW command can be used to stack variables; however, after the command line is executed, an implicit QUIT is performed before returning to direct mode. This causes the stacked variables to be unstacked. Excessive use of the ZNEW command in a program can result in an out-of-space condition within the partition (STORAGE=0).

The ZNEW command differs from the NEW command in that the variable being stacked is not KILLed after the ZNEW command.

Associated Topics

KILL Command
MERGE Command
NEW Command
QUIT Command
$STORAGE Special Variable

Examples

Command	Explanation
ZNEW X	This routine stacks local variable X.
ZNEW A,B	This routine stacks A and B and their descendants. On a QUIT, the system unstacks the hidden A and B variables, in effect merging them with the current copy of A and B.
ZN:X=1 X	This routine stacks local variable X and all of its descendants if and only if X=1.
ZN @X ZN A,@B,C	Indirection may be used in the ZNEW command.


ZPRINT

Writes all or part of a routine to the current device.

Syntax

ZP{RINT}{:Postcond}

ZP{RINT}{:Postcond}SP{StartLine}{:EndLine}

Definition

Postcond	Any post-conditional expression.
StartLine	A line reference for the starting line.
EndLine	A line reference that indicates the ending line.
The ZPRINT command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZPRINT command.

The ZPRINT command is used to output one or more lines of a routine to the current device. In the argumentless form, the entire routine is written to the current device. The implicit line pointer that is used for data entry of routine lines is set to the end of the routine.

In the form with arguments, all lines from and including the StartLine, through and including the EndLine, are output to the current device. The format of the lines is the same as returned by the $TEXT function, and each line ends with a carriage return/line feed sequence.

The StartLine and EndLine expressions can evaluate to a line label (for example: ABC), a line label plus an offset (for example: ABC+3), or simply an offset (for example: +3). For simple offsets, the numeric value is the number of lines from the start of the routine. The first line is +1, the second is +2, and so on.

If only the StartLine is specified, then the single line indicated by the expression is output to the current device. If the EndLine is specified and it is null, all lines from and including the StartLine through the end of the routine are output to the current device. In both forms, the implicit line pointer used for data entry of routine lines is set to the last line output to the current device.

Associated Topics

$TEXT Function
ZINSERT Command

Examples

Command	Explanation
ZPRINT ABC	This routine writes the line labeled ABC to the current device.
ZP +1:+5	This routine writes the first five lines of the routine to the current device.
ZP START+1	This routine writes the single line that immediately follows the line labeled START.
ZP	This routine writes the entire routine.
ZP:X=1 +X:+Y	This routine only writes out the specified portion of the routine if X=1.
ZP X:	This routine writes out all lines from label X through the end of the routine.
ZP @A:@B	Indirection may be used in the ZPRINT command only if local variables contain line labels. Note that the indirection must evaluate to a pure LABEL. LABEL+offset is not supported in this context.


ZQUIT

Exits from an error processing routine and passes control to the next higher error processing routine that has been specified.

Syntax

ZQ{UIT}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The ZQUIT command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZQUIT command.

To understand the operation of the ZQUIT command, it is first necessary to understand how error trapping is implemented in MSM. When a DO or XECUTE command is processed, the MSM system creates a new execution level. This is done so that when a DO or XECUTE command terminates either through an implicit QUIT (end of routine encountered) or an explicit QUIT, the system can return to the point at which the command was initiated.

Each execution level created by a DO or XECUTE command is numbered. Programmer mode is considered to be execution level 1, the first DO or XECUTE command is level 2, the second is level 3, and so on. The execution level that is currently in control generally is referred to as the current execution level.

One $ZTRAP special variable can be set at each execution level (level 1, level 2, and so on). This means that each execution level in an application can establish its own error trapping routine and error recovery procedures.

When a ZQUIT command is issued from within an error handling routine, it returns to the next higher execution level that contains an error processing routine. If none exists, the system returns to the highest execution level (level 1, which generally is programmer mode).

Alternatively, a GOTO command can be used to transfer control to another program at the same level, or a QUIT command can be used to return to the command that follows the DO or XECUTE command at the next higher level.

Refer to the MSM User's Guide for a complete description of error handling and use of the ZQUIT command.

Associated Topics

DO Command
GOTO Command
QUIT Command
XECUTE Command
$ZERROR Special Variable
$ZTRAP Special Variable

Examples

Command	Explanation
ZQUIT	Exit from the error routine and return to the next higher error processing routine.
ZQ:X=1	Exit from error routine only if the value of X equals 1.
TEST	;NEW PROGRAM
S $ZT="ERR1" D ONE
Q
ONE	S $ZT="ERR2" D ONE
Q
TWO	W 1/0
Q
ERR1	W !,"JUMP FROM ZQUIT" Q
ERR2	W !,"ERROR IN LABEL TWO"
ZQ


ZREMOVE

Removes one or more lines from the current routine.

Syntax

ZR{EMOVE}{:Postcond}

ZR{EMOVE}{:Postcond}SP{StartLine}{:EndLine}

Definition

Postcond	Any post-conditional expression.
StartLine	A line reference for the starting line.
EndLine	A line reference that indicates the ending line.
The ZREMOVE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZREMOVE command.

The ZREMOVE command is used to delete one or more lines of a routine. In the argumentless form, the entire routine is deleted from the partition and $ZNAME is set to null. The implicit line pointer that is used for data entry is set to the beginning of the routine.

In the form with arguments, all lines from and including the StartLine, through and including the EndLine, are deleted from the partition. The StartLine and EndLine expressions can evaluate to a line label (for example: ABC), a line label plus an offset (for example: ABC+3), or simply an offset (for example: +3). For simple offsets, the numeric value is the number of lines from the start of the routine. The first line is +1, the second is +2, and so on.

If only the StartLine is specified, then the single line indicated by the expression is deleted from the current routine. If the EndLine is specified and it is null, an error occurs. When the EndLine appears in the routine before the StartLine, no action takes place (no lines are deleted). In the form with arguments, the implicit line pointer used for data entry of routine lines is set to the line that immediately precedes the first deleted line.

Note  If the partition is empty (no routine is loaded in the partition) and a ZSAVE command is entered, the named routine is deleted from the routine directory.

Associated Topics

Implicit Line Pointer
ZINSERT Command
ZLOAD Command
ZSAVE Command
$ZNAME Special Variable
Using the MSM System, MSM User's Guide

Examples

Command	Explanation
ZREMOVE +1	This routine removes the first line of the routine currently loaded into the partition.
ZR +10:+15	This routine removes the tenth line through the fifteenth line of the current routine.
ZR A:B	This routine removes all lines from label A through label B, inclusive.
ZR:Z=2 TEST	This routine removes the single line labeled TEST only if Z=2.
ZR @A:@B	Indirection may be used in the ZREMOVE command. The indirection must evaluate to a pure LABEL. LABEL+offset is not supported in this context.


ZSAVE

Saves the current routine on the database.

Syntax

ZS{AVE}{:Postcond}

ZS{AVE}{:Postcond}SPRoutName{:{Level}{:Expression}}

Definition

Postcond	Any post-conditional expression.
Routname	Any valid routine name.
Level	An integer expression that indicates the level of source code that is to be retained with the saved routine.
Expression	A numeric expression that prevents a routine from being saved if the compiler detects errors.
The ZSAVE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZSAVE command.

The ZSAVE command is used to write the routine currently loaded into the partition to the routine directory in the current UCI. In the argumentless form, a routine name must already be associated with the routine in the partition. The routine name can be accessed using the $TEXT function ($TEXT(+1) returns the name) or the $ZNAME special variable. If no name is associated with the routine and the argumentless form of ZSAVE is used, a <NOPGM> error occurs.

In the form with arguments, the routine is saved using the name specified by the Routname argument. After the save, the name associated with the routine is the name specified as the argument.

The Level argument is used to control how much of the source code is retained with the routine when it is saved. The argument must evaluate to an integer that has a value of 0 through 15, inclusive. If this argument is omitted, a value of 0 is assumed.

As part of the ZSAVE process, the MSM system compiles the routine lines to a pseudo-code format. All or part of the source code can be removed as part of this process. If $TEXT is used to reference a line whose source code has been removed, the function returns a single blank. The following table lists the available levels.

Level	Source Code Retained
0	All text lines
1	All comment lines (; or ;;)
2	First line comment and all ;; lines
3	First line comment and all ;; lines
4	All comment lines (; or ;;)
5	All comment lines (; or ;;)
6	All ;; comment lines
7	All ;; comment lines
8	All ; comment lines and first line if comment
9	All ; comment lines and first line if comment
10	First line if comment line
11	First line if comment line
12	All ; comment lines
13	All ; comment lines
14	Remove all text
15	Remove all text
The Expression argument is used to control whether or not the system saves the routine in the event that errors are detected. If the Expression has a value of 0 or is not present, the routine is saved even if it contains errors. If the Expression has a value of 1, the routine is not saved if errors are found. The system can detect only compile-type errors (for example: <SYNTX> error), and not runtime errors (for example: <UNDEF> error).

When an Expression Value of 1 has been specified, the $ZA special variable is updated as part of the routine save operation. If the compiler found no errors in the routine, $ZA contains a value of 0. Otherwise, $ZA contains the number of the line that contains the error, relative to the beginning of the program. The first line in the program is considered to be 1, the second is 2, and so on. The number returned in $ZA can be used as the argument to the $TEXT function to retrieve the line that contains the error.

When an error is detected, the $ZB special variable contains the relative displacement in the line in which the error was detected. The first character in the line is 1, the second is 2, and so on. By using a combination of $ZA and $ZB, the actual location of the error in the program can be displayed.

After a ZSAVE command with an Expression Value of 1, the values of $ZA and $ZB remain valid until another M command is processed that updates the values of these special variables. M commands that update the $ZA and $ZB special variables include OPEN, USE, READ, JOB, and so on. When the ZSAVE is done in programmer mode, MSM implicitly performs a USE $I command before issuing the command prompt. The programmer should save the value of $ZA as part of the ZSAVE command.

Note  If the partition is empty (no routine is loaded in the partition) when a ZSAVE command is entered, the named routine is deleted from the routine directory.

Considerations

Error conditions can result when changes are made to a routine that is being executed by a job or is executed by a job as it returns through its execution stack as a result of QUIT commands. Internally, MSM tries to determine whether the changes impact the job that is using the routine. If the system determines that the changes will affect the job, it marks the routine so that the job receives a <CLOBR> error when it tries to use the changed routine. Otherwise, the job is allowed to use the changed routine without generating an error. To prevent error conditions, care should be taken when changing a routine that is in use.

Associated Topics

ZINSERT Command
ZREMOVE Command
$TEXT Function
$ZA Special Variable
$ZB Special Variable
$ZNAME Special Variable

Examples

Command	Explanation
ZSAVE TEST	ZSAVE saves the routine currently loaded into the partition on disk under the name TEST.
ZS	ZSAVE saves the current routine using the name contained in the $ZNAME special variable.
ZS MYPROG:1	This routine saves the current routine with name MYPROG and removes all source code except comment lines.
ZR ZS INIT	This routine deletes the routine named INIT from the Routine Directory of the current UCI.
ZS:Z=1 ABC	The routine is saved only if Z=1.
ZS @X	Indirection may be used with the ZSAVE command.
S Y=X:1 ZS @Y	This routine saves X without the text.
ZS YOURPROG::1 S A=$ZA,B=$ZB	This routine saves the program if and only if no errors are detected during the compile. In addition, saves the value of $ZA and $ZB before the command prompt is issued.


ZSETOBJ

Assigns an object reference to a variable.

Syntax

ZSE{TOBJ}{:Postcond}SPVariable=Expression

ZSE{TOBJ}{:Postcond}SP(Variable{,...})=Expression

Definition

Postcond	Any post-conditional expression.
Variable	Either a local variable name or a property of an object.
Expression	Any expression that evaluates to an object reference.
The ZSETOBJ command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZSETOBJ command.

The ZSETOBJ command is used to assign the value of the Expression to one or more variables or object properties, including the default property. When multiple Variables are to be assigned the same value, their names are separated by commas and enclosed in parentheses. Execution of the ZSETOBJ command occurs in the following order:

Any indirection or subscripts that appear in the argument are evaluated in a left-to-right order.

The Expression is evaluated according to the specified rules.

The value of the Expression is assigned to each Variable, one at a time in a left-to-right order if there are several. If the Variable includes subscripts and the specified node does not exist, the system creates the node and the minimum number of ancestor nodes required to provide a path to the new node. When the ancestor nodes are created, they are defined so that they have a descendant but no data value (when the $DATA function is applied to a created ancestor node, its value is 10).

Considerations

The ZSETOBJ command is similar to the SET command, except that the Expression must evaluate to an object reference and only variables (including object properties) that can accept object references are allowed. Otherwise, an error occurs. The default property of that object will not be invoked; instead, the object reference is copied (duplicated) to the Variable. When two or more variables are assigned the same object reference, they become aliases for the same object. Either variable can be used subsequently to reference the object's properties or methods until either one is assigned a new value or is KILLed.

Associated Topics

Variables
Binary EQUALS Operator
SET Command
$ZCREATEOBJECT Function
$ZGETOBJECT Function
$ZOBJREFERENCE Function

Examples

Command	Explanation
ZSETOBJ X=Y	The value (which must be an object reference) of the unsubscripted variable Y is assigned to the unsubscripted local variable X. The previous value of X is discarded.
ZSE A(1,2)=Y(1)	This works similarly for subscripted variables.
ZSE A(1)=X,B(4)=D	This shows multiple arguments of ZSETOBJ.
ZSETOBJ:PC>5 (A,B,C)=MYOBJ	This is a "multiple" set. All variables in the parentheses are set to the same object reference value. Note the use of the post-conditional. The ZSETOBJ command is executed only if local variable PC has a value greater than 5.
SET ^A(1)=0 ZSE (A,B)=MYOBJ,A(3)=W,   (A(^(3,5),4),B(5))=XXX(^(4))	Multiple and single ZSETOBJs may be mixed in one command. When subscripts occur to the left of the equal sign, they are evaluated before the right-side expression. In this example, ^(3,5) evaluates to ^A(3,5), due to the setting of the naked by the "SET ^A(1)." Therefore, ^(4) becomes ^A(3,4). Even in a multiple set, the left subscripts are evaluated before the assignment is made, but each argument is completed before the next is begun.
ZSETOBJ @X,@A=B	Indirection is often used in the ZSETOBJ command.
ZSETOBJ myjob=system.apps($J) WRITE myjob.commands	This command uses a variable system to point to the object. Its "apps" method is invoked with "$J" as a parameter. The resulting object reference is assigned to local variable myjob. Subsequently, the "commands" property of the object referenced by local variable myjob is invoked. Its returned value is then written to the current device. The WRITE system.apps($j).commands generate the same output.


ZSYNC

Flushes network activity for the current job.

Syntax

ZSY{NC}{:Postcond}

Definition

Postcond 	Any post-conditional expression.

The ZSYNC command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZSYNC command.

In MSM, any global SET (update) or KILL operations performed over a network are buffered by the system to improve efficiency. They can be processed later by the system to which they are being sent. The ZSYNC command has been implemented to provide a mechanism for a job to ensure that all global transactions have been completed by the other system. When the ZSYNC command is issued, the current job is suspended until all in-progress network transactions are complete.

Considerations

The ZSYNC command can be used with remote volume group (RVG) support or with Distributed Data Processing (DDP) support. For systems in which RVG or DDP support are not active, the ZSYNC command is ignored.

Associated Topics

Configuring the System, MSM User's Guide
%DBSYNC and %MODESET Utilities

Examples

Command	Explanation
ZSYNCH	Flushes the network transactions for the current job.


ZTRAP

Forces an error condition during execution of a routine.

Syntax

ZT{RAP}{:Postcond}SPString

Definition

Postcond	Any post-conditional expression.
String	A string expression that specifies the text of the error to be displayed.
The ZTRAP command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZTRAP command.

The ZTRAP command is used to force an error condition during routine execution. When the error condition occurs, routine execution is terminated in the same manner as any other type of error condition. Any error traps set by the routine are honored.

The String argument is an expression that evaluates to a one-to four-character string that indicates the specified error type. The letter Z followed by the specified string is displayed as the error code in the standard MSM error message. If the expression is null or not specified, a default value of TRAP is used.

Associated Topics

QUIT Command
ZQUIT Command
$ZERROR Special Variable
$ZTRAP Special Variable
Error Processing

Examples

Command	Explanation
ZTRAP "1234"	<Z1234>+17^CUSINQ:::6:17
ZT "err1"	<Zerr1>+21^CUSLOG:::6:17
ZT	<ZTRAP>+45^CUSMAST:::6:17
ZT "A"	<ZA>+12^CUSSRCH:::6:17
ZT @X	Indirection can be used in the ZTRAP command.


ZUSE

Temporarily gains ownership of a device.

Syntax

ZU{SE}{:Postcond}SPDevice

 Definition

Postcond	Any post-conditional expression.
Device	Any valid terminal device designator.
The ZUSE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZUSE command.

The ZUSE command is used to temporarily gain ownership of a device that may already be owned by another job. The primary purpose of ZUSE is to allow messages to be broadcast to system users. The ZUSE command makes the device specified by the device argument the current device without using the OPEN and USE commands. The specified device must be a terminal type device that is currently active on the system. When a device is acquired through the ZUSE command, only the WRITE command can be used with the device. Any other input/output command causes an error.

MSM-UNIX only: Output that has been directed by the ZUSE command can be delayed for up to five seconds.

Associated Topics

USE Command
WRITE Command
Using Peripheral Devices, MSM User's Guide

Examples

Command	Explanation
ZUSE 4 W !,"SYSTEM AVAILABLE UNTIL   23:00 TONIGHT"	This routine sends a broadcast message to a specific terminal device.
ZU:X=1 64	The ZUSE command obtains the device only if X=1.
ZU @X	Indirection can be used with the ZUSE command.


ZWRITE

Writes the contents of the local symbol table.

Syntax

ZW{RITE}{:Postcond}

ZW{RITE}{:Postcond}SPVariable{,...}

Definition

Postcond	Any post-conditional expression.
Variable	Any subscripted or unsubscripted local variable name.
The ZWRITE command is executed if the Postcond expression is true or if it is not supplied on the command. If it is supplied and it is false, execution moves to the next command after the ZWRITE command.

The ZWRITE command is used to display the values of one or more local variables and their descendants on the current device. Variables are displayed in ASCII collating sequence.

In the argumentless form, all local variables are displayed. In the form with arguments, only the specified local variables are displayed. If the specified local variable has descendants, all descendants also are displayed.

Associated Topics

Variables

Examples

Command	Explanation
ZWRITE X=0 Y="23" CODE="" CODE(1)="R499" CODE(2)="MM88" CODE(3)="A1AA"	ZWRITE writes the contents of the local symbol table to the current device.
ZW CODE CODE= CODE(1)="R499" CODE(2)="MM88" CODE(3)="A1AA"	This routine writes the value of the variable CODE and all of its descendants.
S X=10 S Y="X" ZW @Y	Indirection may be used with the ZWRITE command, but the indirection must yield a local variable that was previously defined.


MSM Functions - Overview
Overview

This chapter describes the ANSI Standard M functions and the additional functions that are provided in the MSM implementation of M. It also explains how you can write your own functions.

In the MSM system, a function is an operation that returns a single numeric or string value. The ANSI-standard definition for the M language defines the following two function types.

Intrinsic	A built-in function defined by the system (for example $DATA or $PIECE).
Extrinsic	A user-defined function that has been implemented as an M routine.
The following sections describe both function types and how the M programmer can use them.

See Also:

Intrinsic Functions

Extrinsic Functions


Intrinsic Functions

The M language contains functions that the programmer can use to facilitate creation of programs or routines, as they are referred to in MSM. Functions supplied with the system as part of the M language are referred to as intrinsic functions. An intrinsic function is a directive to the compiler to perform a specific action and then return a single value that results from the action. Each function performs a specific action that is further defined by the arguments associated with it.

An intrinsic function is represented by a dollar sign ($), followed by the function name, followed by one or more parameters enclosed in parentheses.

The following illustrates the syntax of an intrinsic function:

$FuncName(ActualList)

FuncName	Any MSM-supplied function name.
ActualList	One or more arguments (expressions) separated by commas.
MSM provides all of the ANSI-standard functions and an extended set of functions specific to MSM. The ANSI Standard functions begin with a dollar sign ($), followed by any name that starts with the letters A through Y. The MSM-specific functions begin with a dollar sign, followed by any name that starts with the letter Z.

Functions either can be spelled completely or can be abbreviated to the minimum number of characters necessary to uniquely identify them. Function names can be specified in uppercase, lowercase, or a combination of uppercase and lowercase letters. For example, all of the following are valid abbreviations for functions:

$PIECE

$P

$pIeCe

$p

New intrinsic functions that specify both the full name and its abbreviation are continually being added to the ANSI standard. Generally, the abbreviation for a new function is the dollar sign and the minimum number of characters necessary to uniquely identify the function. The $TRANSLATE function is abbreviated to $TR because it conflicts with the $TEXT function that is abbreviated as $T. In all cases, a single-character abbreviation invokes the old function when a new function exists that begins with the same letter.

When an intrinsic function is specified, an argument list must be present. It can consist of a single argument (a single expression) or multiple arguments separated by commas (expression, ... ,expression).

The argument list must not contain spaces between the arguments or commas unless it is part of a quoted string. The parentheses around the argument list must immediately follow the function name (spaces between the function name and the opening parenthesis are not allowed).

The following sections provide information about the functions provided in MSM. For each function, information about syntax, a description of functionality, special considerations, associated topics, and examples are provided. For additional information about writing M programs, refer to the MSM User's Guide.


Extrinsic Functions

An extrinsic function is always a user-defined function written in M. It uses the parameter-passing mechanism of MSM to receive arguments and return values. An extrinsic function can be used anywhere in MSM where an expression is allowed.

Syntax

An extrinsic function is identified by two dollar signs ($$), followed by the function name (an EntryRef that identifies the M routine which performs the desired action), followed by zero or more parameters enclosed in parentheses. The syntax of an extrinsic function is as follows.

$$EntryRef(ActualList)

EntryRef	A reference which identifies the M routine that performs a specific function.
ActualList	An argument list that specifies the actual list of parameters to be passed to the function. It consists of zero or more arguments separated by commas.
The EntryRef can be a simple routine name (for example, ^CUSTOMER); or a label within a specified routine (COS^MATHRTN); or a label within the current routine (for example, SQUAROOT). Each argument in the ActualList can be any valid MSM expression. The specified ActualList is passed to the function using the parameter-passing capabilities available in MSM.

Call-by-value parameters

When an argument in the ActualList is an expression, it is first evaluated by MSM and the result (the value) is passed to the extrinsic function. This form of passing parameters is referred to as a call-by-value. When the argument being passed to the extrinsic function is a local or global variable, the same holds true. The value of the variable is passed to the function.

Call-by-reference parameters

For local variables only, MSM provides a mechanism that allows the pointer to the variable in the local symbol table to be passed to the function. This is referred to as a call-by-reference (a reference to the variable is passed rather than the value of the variable). If a local variable name in the ActualList is preceded by a period (.), the system passes the argument to the subroutine using call-by-reference. Call-by-reference is permitted only for unsubscripted local variables in the ActualList. If it is specified for an expression, a global variable, or a subscripted local variable, a <SYNTX> error occurs.

Formal parameters

When an extrinsic function is invoked, the label on the first line of the called subroutine must contain a list of variables that is used to receive the arguments from the caller. This list is referred to as a formal list (FormalList) of parameters. Refer to the section on the DO Command in "MSM Commands" in this manual for additional information on MSM's parameter-passing capabilities.

Parameter binding

To pass parameters to an extrinsic function, the system must match the arguments in the ActualList with the variables in the FormalList. This match is referred to as binding. To perform the binding, the system first creates a parameter list that contains, in the specified order, the address of variables for arguments that are call-by-reference and the actual values for arguments that are call-by-value.

The system then loads the specified EntryRef for the function. Before actually entering the subroutine, the system performs an implicit NEW command on all local variables in the FormalList. This is done so that when the extrinsic function terminates, these variables can be restored to their original form.

When an extrinsic function is called, the caller may supply all of the parameters that can be received by the subroutine. Any local variables that appear in the FormalList  but do not appear in the ActualList are undefined. If they are referenced by the subroutine, an <UNDEF> error occurs.

The ActualList cannot be longer than the FormalList; such a situation causes the system to generate a <DPARM> error. A null ActualList can be specified when calling an extrinsic function by omitting the ActualList from the call. Alternatively, the open and close parentheses can be specified with no value between them (that is, ( ) appears after the function name). A null FormalList also can be specified by using the open/close parentheses form. However, the FormalList cannot be omitted.

Finally, the variables in the FormalList are initialized. For a variable passed using call-by-value, the variable in the FormalList is assigned the value of the passed parameter. This variable then can be freely changed without any impact on the calling routine.

For call-by-reference variables, the FormalList variable is made to point (aliasing) to the data value of the local variable that corresponds to it positionally in the ActualList. This means that if the subroutine modifies the value of a call-by-reference variable in the FormalList, the value of the variable in the ActualList also is changed. Similarly, if the subroutine KILLs such a variable, the variable in the ActualList also is killed. In accordance with the ANSI M standard, the aliasing continues even after the KILL. If the subroutine assigns a value to such a variable after the KILL, the aliased variable (in the calling routine) also is set.

Although the variable in the ActualList must not contain any subscripts, subscripts  can exist for the specified variable name. When the KILL command is used on a variable in the FormalList that was passed using call-by-reference, it is possible to KILL the entire array.

Return values

After an extrinsic function is called, it must return a value to the caller. This is done by supplying an argument on the QUIT command. The argument can be any valid expression.

When an extrinsic function is called and an ActualList is not specified with it, then it is referred to as an extrinsic variable. It behaves exactly like an extrinsic function and can be used anywhere that an extrinsic function can be used. The only difference is that no arguments or parentheses are associated with it.

As with extrinsic functions, the line specified by the EntryRef must contain an empty FormalList of parameters. If it does not, a <DPARM> error occurs.

Other notes

Several other points should be remembered when using extrinsic functions. For example, the only way to invoke a subroutine that contains a FormalList is with a DO command or a reference to an extrinsic function. If a program falls through to a subroutine with a FormalList or reaches the subroutine with a GOTO command, a <DPARM> error occurs.

Because of the way that parameter passing works, indirection cannot be used when specifying a FormalList for a subroutine. In addition, call-by-reference can only be used for local variables. Expressions and globals cannot be used as arguments.

The value of the $TEST special variable is preserved across an extrinsic function call. MSM saves the value of $TEST before it evaluates the ActualList and calls the function. After the function completes, $TEST is restored to the value that existed before the call.

All of the variable names in the FormalList must be unique. This is not true for the ActualList. However, when the same name appears more than once and is passed using call-by-reference, more than one variable in the FormalList points to the same data value.

Examples

Consider the following routine:

VOL(R,H)	; Calculate volume of a cylinder
; R=radius, H=height
; V= pi * (radius squared) * height
Q 3.14159265*R*R*H

When the following is executed:

SET VOLUME=$$^VOL(RAD,H)

the variable VOLUME equals the volume of a cylinder of radius "RAD" and height "H." This is an example of call-by-value parameter passing.

Consider the following routine:

%EXP(INT,P) 	; Calculate INT to the P power
I P=0 S INT=1 Q 1
N I,X
S X=INT
F I=1:1:P-1 S INT=INT*X
Q INT

When the following is executed:

SET X=2,Y=8 W $$^%EXP(X,Y)

the number 256 is written to the current device. If the code is rewritten as follows:

SET X=2,Y=8 W $$^%EXP(.X,Y)

the output is the same, but the value of variable X is changed to 256. This is an example of call-by-reference parameter passing.

Consider the following routine:

%FMRD(H) 	; Convert $H date to FileMan date
S X=$ZDATE(H)
EXIT 	;
Q 2_$P(X,"/",3)_$P(X,"/")_$P(X,"/",2)
T() 	; Return FileMan date for today
S X=$ZD($H) G EXIT

When the following is executed:

SET FMRDAT=$$^%FMRD($H-10)

the variable FMRDAT contains the FileMan internal date for ten days before execution of the program. If the following code is executed:

S TODAY=$$T^%FMRD

the variable TODAY is set to the current FileMan date. In this case, $$T^%FMRD is called an extrinsic variable, because parameters are not passed to the subroutine. Note that label "T" must have at least a null formal list even when it is used as an extrinsic variable.


$ASCII

Returns the decimal value of a specified ASCII character.

Syntax

$A{SCII}(String{,Position})

Definition

String	Any string-type expression.
Position	An integer expression that indicates the relative position of a character within the String.
The $ASCII function returns an integer value that is the decimal equivalent of the ASCII code of the specified character. The decimal value is translated from the ASCII code in the String at the location specified by the Position argument. If Position is omitted, a value of 1 is assumed. The function returns a value of -1 if the String is null or if the location specified by Position is less than 1 or greater than the length of the String.

If an alternative character set (such as a double-byte character set) is in effect, $ASCII returns the value of the character in that character set.

Associated Topics

$CHAR Function
ASCII Character Set

Examples

Setup	Value of Function
S X="ABCDE"	$A(X)=65 $A(X,1)=65 $A(X,2)=66 $A(X,3)=67
S Y="4"	$A(X,Y)=68
S X="" (null)	$A(X)=-1 $A(X,n)=-1 for all n
S X="AB"	$A(X,0)=-1 $A(X,3)=-1 $A(X,-7)=-1 $A(X,1.92)=65 uses integer portion of the value


$CHAR

Translates a list of integers into a string of characters whose codes are those integers, using the programmer character set of the current process.

Syntax

$C{HAR}(Codepoint{,...})

Definition

Codepoint	An integer expression that is the decimal value of the desired ASCII character.
The $CHAR function returns a string of ASCII characters whose length is equal to the number of non-negative Codepoint arguments supplied to the function. If the Codepoint value is less than 0, it translates to a null value. If it is greater than 255, an error occurs unless a double-byte or wide character set is being used.

If an alternative character set (such as a double-byte character set) is in effect, $CHAR interprets the integers as character codes in that character set and returns characters of that character set.

Associated Topics

$ASCII Function
ASCII Character Set

Examples

Setup	Value of Function
S X=65,Y=66,Z="GOB"	$C(X)="A" $C(Y)="B" $C(X,Y)="AB" $C(X,Y,67)="ABC" $C(X,-1,Y)="AB" $C(-1)="" (null string) $C(65.7)="A"  uses integer portion of the value. $C(0)= the ASCII NUL character. $C($A(Z,1),$A(Z,2),$A(Z,3))="GOB"
WRITE $C(13,10)	Writes carriage return, linefeed to current device


$DATA

Returns a value that indicates whether a variable has data, has descendants, has both, or has neither.

Syntax

$D{ATA}(Variable)

Definition

Variable	An expression that evaluates to a local or global variable name.
The $DATA function returns a value that indicates whether the global or local variable specified by Variable is defined, has data, and has descendants. The following values are returned by the function.

0	The global or local variable is not defined, has no data, and has no descendants.
1	The global or local variable is defined, has data, but has no descendants.
10	The global or local variable is defined, has no data, and has descendants.
11	The global or local variable is defined, has data, and has descendants.
If the variable is specified using a naked reference, the naked indicator must have been previously set.

Examples

Setup	Value of Function
Y is not defined SET Y=100 S Y="AB" S A(1)="TEST" S B(1,2)="SAMPLE" S B(1)="SAMPLE1" KILL B(1,2)	$DATA(Y)=0 $D(Y)=1 $D(Y)=1 $D(A(1))=1 $D(A)=10 $D(B(1,2))=1 $D(B(1)=10 $D(B(1))=11 $D(B(1,2))=0 $D(B(1))=1


$EXTRACT

Returns a substring from a starting location to an ending location within a specified String.

Syntax

$E{XTRACT}(String{,Begin{,End}})

Definition

String	A string-type expression.
Begin	An integer expression that specifies the starting location of the substring within the String.
End	An integer expression that specifies the ending location of the substring within the String.
The $EXTRACT function returns a substring from the specified String starting at location Begin and ending at location End. When no Begin location is specified, a value of 1 is assumed. If no End location is specified, it is assumed to be the same as the starting location.

The function returns a null value under the following conditions: when the Begin value is greater than the length of the String; when the End value is less than 1; when the Begin value is greater than the End value; or when the End value is not specified and the Begin value is less than 1.

The $EXTRACT function can appear on either side of the equal sign (=) in the argument of the SET command. When it appears on the right side of the equal sign, it returns the specified substring. When it appears on the left side of the equal sign, the specified substring is replaced by the value to the right of the equal sign.

When SET $EXTRACT notation is used, the String being set must be a pure local or global variable name. Other expression types are not allowed. If the variable being SET is not long enough (Begin and/or End are beyond the length of the variable), the variable is padded with blanks, as needed. If the variable being SET does not exist, it is treated as if it was equal to the null string.

Example

Setup	Value of Function
SET X="ABCDE"	$E(X)="A" $E(X,1)="A" $E(X,2)="B" $E(X,1,2)="AB" $E(X,1,4)="ABCD" $E(X,0,100)="ABCDE" $E(X,3.9)="C" (uses 3 as begin) $E(x,-1,6)="ABCDE" $E(X,0)="" (null string) $E(X,99)="" (null string) $E(X,-3)="" (null string) $E(X,3,2)="" (null string) $E(X,-10,-5)="" (null string)
S A(1)="2BC"	$E(A(1),A(1))="B"
S X="ABCDE",$E(X,3,4)=12	X="AB12E"
S X="ABCDE",$E(X,2,4)=1	X="A1E"
S X="A",$E(X,3)=1	X="A 1"
K X S $E(X,3,4)=12	X=" 12"
S A="NAME",NAME="AB" S $E(@A)=1	NAME="1B"


$FIND

Returns an integer value that denotes the ending location of a Substring within a specified String.

Syntax

$F{IND}(String,Substring,{Begin})

Definition

String	Any string-type expression.
Substring	Any string-type expression that is to be located within String.
Begin	An integer expression that indicates the location where the search is to start.
The $FIND function searches a String to see if it contains a specified Substring. If it does, then the function returns an integer value that is the location of the character immediately to the right of the Substring's last character. The function returns 0 if the Substring is not contained in the String.

Although  the search generally begins with the first character of the String, the Begin argument can be used to specify a different starting location. If the starting location is less than 1, a value of 1 is assumed. When the Substring occurs more than once in the String, the function returns the location of the first occurrence found after the starting location. When the specified Substring is null, the function returns the starting location.

Associated Topics

$LENGTH Function
STRING CONTAINS Operator

Examples

Setup	Value of Function
SET X="ABCAX"	$FIND(X,"A")=2 $F(X,"B")=3 $F(X,"Z")=0 $F(X,"ABC")=4 $F(X,"A",1)=2 $F(X,"A",2)=5 $F(X,"A",4)=5 $F(X,"A",5)=0 $F(X,"A",100)=0 $F(X,"")=1 $F(X,"",4)=4 $F(X,"",10)=10
S Y="B"	$F(X,Y)=3
S Z="1.2W"	$F(X,Y,Z)=3 $F(X,"",-5)=1


$FNUMBER

Returns the value of an expression (Number), formatted according to a user-specified mask.

Syntax

$FN{UMBER}(Number,Format{,Fraction})

Definition

Number	Any numeric type expression.
Format	A string expression that specifies the formatting to be performed on the Number.
Fraction	An integer expression that specifies the number of digits to the right of the decimal point to display.
The $FNUMBER function returns the specified Number as a string, formatted according to a pattern specified by the Format codes. The Format codes are defined in the following table.

Format Codes for the $FNUMBER Function

PCodes	Function performed
+	Forces a plus sign on all positive values of Number.
-	Suppresses the minus sign on negative values of Number. This in effect produces the absolute value of the specified Number.
,	Inserts commas every third position to the left of the decimal point within the formatted Number. Note that no comma is inserted that would result in a leading comma character.
P or p	Represents negative values of Number in parentheses. If the specified Number is positive, blanks are inserted where the parentheses normally would be inserted.
T or t	Shows the Number with a trailing, rather than leading, "+" or "-" sign. If sign suppression is in force (positive number or "-" Format code), then a trailing space is added.
The order in which the Format codes are specified does not affect the processing. If a particular Format code is specified more than once, it is ignored. When the specified Format is null, the original value of Number is returned. An error condition results if the Format code "P" is specified along with "T," "+," or "-" in the string.

If Fraction is specified, it indicates the number of places to the right of the decimal point to display. When the Number is evaluated, the specified number of decimal places is calculated, with padding, truncation, or rounding, if appropriate. Trailing zeros are added, if needed to display the proper number of fraction places.  If
 -1 < Number < 1, a leading 0 is added to the left of the decimal point.

Examples

Setup	Value of Function
SET X=3.14159	$FNUMBER(X,"+")="+3.14159" $FN(X,"+T")="3.14159+" $FN(X,"+T",4)="3.1416+" $FN(X,"T",4)="3.1416 " $FN(X,"P",6)=" 3.141590 " $FN(X,"P",5)=" 3.14159 " $FN(X,"P",4)=" 3.1416 " $FN(X,"P",3)=" 3.142 " $FN(X,"P",2)=" 3.14 " $FN(X,"P",1)=" 3.1 " $FN(X,"P",0)=" 3 "
S X=1234567	$FN(X,",",2)="1,234,567.00"
S X=-15.406	$FN(X,"T")="15.406-" $FN(X,"T",2)="15.41-" $FN(X,"P")="(15.406)" $FN(X,"PT-")=error


$GET

Returns the data value of a variable if it exists.

Syntax

$G{ET}(Variable{,DefaultVal})

Definition

Variable	An expression that evaluates to a local or global variable name.
DefaultVal	An expression that specifies the data to be returned if the Variable is not defined.
The $GET function returns the data value of the Variable, if it exists ($DATA(Variable)=1 or 11). If it does not exist, the function returns the value specified by DefaultVal. If no DefaultVal is specified, a value of null is assumed. If a DefaultVal is specified, it is always evaluated by the function. This ensures that the state of the naked indicator always is predictable.

Associated Topics

Variables
$DATA Function

Examples

Setup	Value of Function
KILL ABC	$GET(ABC,"123")=123 $G(ABC(1,3))="" $G(ABC(1,3),"EMPTY")="EMPTY"
S ABC(1,3)=4	$G(ABC(1,3),"EMPTY")=4


$JUSTIFY

Returns the value of an expression, right-justified, in spaces within a field of specified size.

Syntax

$J{USTIFY}(String,Field{,Fraction})

Definition

String	Any string-type expression.
Field	An integer expression that specifies the size of the string to be returned.
Fraction	An integer expression that specifies the number of digits to the right of the decimal point to display.
The $JUSTIFY function returns the String right-justified in a string of blanks whose length is specified by Field. If the length of the String is greater than or equal to Field, the function returns the String. Otherwise, it returns the String with as many blank characters concatenated to the front as necessary to yield the length specified by Field. If Fraction is specified, it indicates the number of places to the right of the decimal point to display. When the String is evaluated, the specified number of decimal places is calculated, with rounding if appropriate. The length specified by Field includes the sign character (if present) and the decimal point (if present).

Examples

Setup	Value of Function
SET X=12.35	$JUSTIFY(X,6)=" 12.35" $J(X,5)="12.35" $J(X,4)="12.35" $J(X,3)="12.35" $J(X,7,4)="12.3500" $J(X,7,3)=" 12.350" $J(X,7,2)=" 12.35" $J(X,7,1)=" 12.4" $J(X,7,0)="  12"
S Y=197	$J(Y,7,2)=" 197.00"
S W=1.487	$J(W,7,2)=" 1.49" $J(W,7,1)="  1.5" $J(W,7,0)="   1"
S Z="123.4ABC"	$J(Z,10)=" 123.4ABC" $J(Z,10,2)=" 123.40" $J(Z,10,0)="   123"


$LENGTH

Returns the length of a String or the number of pieces delimited by a Substring that occur within a String.

Syntax

$L{ENGTH}(String{,Substring})

Definition

String	Any string-type expression.
Substring	Any string-type expression that is to be counted within String.
The $LENGTH function returns an integer value that indicates the number of characters in String. If String is null, the function returns 0. If a substring is specified, the function returns an integer value that is one greater than the number of non-overlapping times the Substring is contained in the String. If the Substring is specified and it is null, the function returns 0.

Examples

Setup	Value of Function
SET X="ABC"	$LENGTH(X)=3
S X="123456789"	$L(X)=9
S X="" (null string)	$L(X)=0
S X="ABCDBCABCABCD"	$L(X,"AB")=4 $L(X,"DC")=1 $L(X,"ABCD")=3 $L(X,"")=0
S X="AAAA"	$L(X,"AA")=3


$NAME

Returns the evaluated form of the specified Variable name.

Syntax

$NA{ME}(Variable{,Subscripts})

Definition

Variable	An expression that evaluates to a local or global variable name.
Subscripts	An expression that specifies the number of subscripts to be returned in the Variable name.
The $NAME function returns a string value that is a full local or global reference denoting all or part of the specified Variable. If the Subscript argument is not specified or is 0, the value returned is the Variable name. Otherwise, the function returns a full local or global reference that contains up to the specified number of subscripts.

Considerations

When naked references are used within the $NAME function, a string corresponding to the full reference is returned. However, the $NAME function does not affect the naked indicator.

Associated Topics

Variables
Naked References

Examples

Setup	Value of Function
$NAME(^A(3,"B",3+4))	^A(3,"B",7)
$NA(^A(3,"B",7),2)	^A(3,"B")
$NA(^A(3,"B",7),0)	^A
$NA(^A(3,"B",7),-1)	Error condition
S X=^A(3,"B",7) $NA(^(3))	Sets up a naked reference ^A(3,"B",3)


$NEXT

Identifies the next or previous subscript, in collating sequence, for a specified subscripted Variable.

Syntax

$N{EXT}(Variable{,Direction})

Definition

Variable	An expression that evaluates to a subscripted local or global variable name.
Direction	An expression that evaluates to either 1 or -1.
The $NEXT function is used to identify the next or previous subscript in sequence at a given level. The Variable name that is specified as an argument to the function may be subscripted, and naked references are allowed. If Direction is not specified or has a value of 1, then for the right-most subscript in the Variable, the system returns the next subscript value that follows it. If no subscript follows it, the function returns -1. If the right-most subscript in the reference is -1, the system returns the value of the first subscript or the last subscript at that level, depending on the value of Direction. If Direction is specified and evaluates to -1,  the function returns the previous subscript for the variable. If Direction is specified and has any value other than 1 or -1, an error condition occurs.

The $NEXT function returns the subscripts in the collating sequence defined for the global (string or numeric sequence). For local variables, the subscripts are always returned in numeric order. The $NEXT function has been retained to provide compatibility with applications developed on earlier M implementations. Although the $ORDER function performs the same function as $NEXT, it supports string subscripts and negative numeric subscripts. Therefore, the $ORDER function is the preferred choice.

$NEXT can be used to step through the local symbol table. If Variable evaluates to an unsubscripted local variable, $NEXT either returns the next or previous variable defined in the partition, or -1 if none exists. Because $NEXT has no starting point when it is used in this manner, one must start with $NEXT(), which returns the name of the first or last variable in the partition.

The $NEXT function also can be used to step through global and routine directories. When an unsubscripted global variable name is used as an argument to $NEXT, the system returns the name of the next or previous global in the directory. For routines, a global name that consists of a space character followed by the routine name as the subscript (^  (RoutName) for routines) is used. The Direction argument can be specified to scan the routine and global directories in reverse order.

Associated Topics

$ORDER Function
$QUERY Function
$ZNEXT Function
$ZORDER Function
$ZPREVIOUS Function
$ZSORT Function

Examples

Setup	Value of Function
SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3	$NEXT(^A)=name of next global in the local directory $N(^A(-1))="1" first node $N(^A(1))="2" second node $N(^A(2))="4" third node $N(^A(4))="-1" no descendants $N(^A(1,-1))="2" second-node level $N(^A(1,2,-1))="3" third-node level $N(^A(1,2,3,-1))="-1" no fourth level
SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3	$NEXT(^A(-1),-1)="4" last node  $N(^A(4),-1)="2" next-to-last node  $N(^A(2),-1)="1" first node $N(^A(1),-1)="-1" no descendants $N(^A(1,-1),-1)="2" second level $N(^A(1,2,-1),-1)="3" third level $N(^A(1,2,3,-1),-1)="-1" no fourth level
KILL  SET (%A(2),ABC,x)=""	$NEXT()="%A" $N(%A)="ABC" $N(ABC)="x"  $N(x)="-1"
$N(^CUST)	"HELP"


$ORDER

Identifies the next subscript, in collating sequence, for a specified subscripted Variable.

Syntax

$O{RDER}(Variable{,Direction})

Definition

Variable	An expression that evaluates to a local or global variable name.
Direction	An expression that evaluates to either 1 or -1.
The $ORDER function is used to identify the next or previous subscript in sequence at a given level. The Variable name that is specified as an argument to the function must be subscripted, and naked references are allowed. If Direction is not specified or has a value of 1, then for the right-most subscript in the Variable, the system returns the next subscript value that follows it. If no subscript follows it, the function returns a null value. If the right-most subscript in the reference is a null value, the system returns the value of the first or last subscript at that level, depending on the value of Direction. If Direction is specified and evaluates to -1, the function returns the previous subscript for the variable. If Direction is specified and has any value other than 1 or -1, an error condition occurs.

The $ORDER function returns the subscripts in the collating sequence that was defined for the global (string or numeric sequence). For local variables, the subscripts always are returned in numeric order. The $ZSORT function is identical to the $ORDER function, except that for local variables, it returns the subscripts in string-collating sequence.

$ORDER can be used to step through the local symbol table. If Variable evaluates to an unsubscripted local variable, $ORDER either returns the next local variable defined in the partition or null if none exists. Because $ORDER has no starting point when used in this manner, one must start with $ORDER() to obtain the name of the first or last local variable in the partition.

Although the $ORDER function performs the same function as $NEXT, it supports string subscripts and negative numeric subscripts. The $ORDER function thus is the preferred choice.

The $ORDER function can be used to step through global and routine directories. When an unsubscripted global variable name is used as an argument to $ORDER, the system returns the name of the next global in the directory. For routines, a global name that consists of a space character followed by the routine name as the subscript (^  (RoutName)) is used. The Direction argument can be specified to scan the routine and global directories in reverse order.

Associated Topics

$NEXT Function
$QUERY Function
$ZNEXT Function
$ZORDER Function
$ZPREVIOUS Function
$ZSORT Function

Examples

Setup	Value of Function
SET ^A(-1)=0,^A(1,2,3)=1,   ^A(2)=2,^A(4)=3	$ORDER(^A(""))="-1" first node $O(^A(-1))="1" second node $O(^A(1))="2" third node $O(^A(2))="4" fourth node $O(^A(4))="" no descendants $O(^A(1,""))="2" second-node level $O(^A(1,2,""))="3" third-node level  $O(^A(1,2,3,""))="" no fourth level
SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3	$ORDER(^A(""),-1)="4" last node $O(^A(4),-1)="2" next last node $O(^A(2),-1)="1" first node $O(^A(1),-1)="" no descendants $O(^A(1,""),-1)="2" second level $O(^A(1,2,""),-1)="3" third level $O(^A(1,2,3,""),-1)="" no fourth  level
KILL  SET (%A(2),ABC,x)=""	$ORDER()="%A" $O(%A)="ABC" $O(ABC)="x" $O(x)=""
$O(^CUST)	"HELP"
$O(^ ("%DI"))	"%DO"


$PIECE

Returns a substring between two occurrences of a specified Delimiter.

Syntax

$P{IECE}(String,Delimiter{,First{,Last}})

Definition

String	Any string-type expression.
Delimiter	One or more characters that are delimiters for the substring.
First	An integer expression that specifies the starting occurrence of the substring to retrieve.
Last	An integer expression that specifies the ending occurrence of the substring to retrieve.
The $PIECE function returns one or more substrings that are contained in the String. The substring may appear none, one, or more non-overlapping times in the String separated by the Delimiter. The Delimiter may be one or more characters that appear in the String. Each substring has a unique position relative to the Delimiter in the String. In the following example, the asterisk (*) character is used as the Delimiter.

ABC*DEF*GHI*JKL

In this case, ABC is the first substring, DEF is the second substring, GHI is the third substring, and so on. If the Delimiter is not found in the String, the function returns the entire String. The First argument is used to indicate which substring to retrieve. When the First argument is not specified, the function returns the first substring. When the Last argument is specified, all substrings from the First through the Last are returned. The function returns a null string if the Delimiter is null; the value of First is greater than the value of Last; the value of Last is less than 1; or there are less than First -1 non-overlapping occurrences of the Delimiter in the String.

The $PIECE function can appear on either side of the equal sign (=) in the argument of the SET command. When it appears on the right side of the equal sign, it returns the specified piece. If it appears on the left side of the equal sign, the specified piece is replaced by the value to the right of the equal sign. When SET $PIECE notation is used, the String being set must be a pure variable name. Other expression types are not allowed.

If the variable being SET does not have enough delimiters to update the appropriate piece, the $PIECE function pads the variable with additional delimiters as necessary. If the variable being SET does not exist, it is treated as if it was equal to the null string.

If the $PIECE function appears on the left side of the equal sign and the delimiter is null, the following situations occur.

•	If both First and Last are less than 1, the value of String remains unchanged.

•	If First is less than 1 and it is less than Last, the value of String is replaced by the value to the right of the equal sign.

•	When First is equal to one and Last is less than 1, the value of String remains unchanged. Otherwise, the value of String is replaced by the value to the right of the equal sign.

•	When First is greater than 1and Last is greater than or equal to First, the value to the right of the equal sign is appended to the value of String. Otherwise, the value of String remains unchanged.

Examples

Setup	Value of Function
SET X="ABC*DEF"	$PIECE(X,"*")="ABC" $P(X,"*",1)="ABC" $P(X,"*",2)="DEF" $P(X,"*",3)="" (null string) $P(X_1)="ABC*DEF"
S Y="B"	$P(X,Y,1)="A" $P(X,Y,2)="C*DEF"
S Z="A.B.C.D"	$P(Z,".",1)="A" $P(Z,".",2,3)="B.C" $P(Z,".",1,100)="A.B.C.D" $P(Z,".",0)="" (null string) $P(Z,".",3,2)="" (null string) $P(Z,"",1,100)="" (null string)
S Z="A.B.C.D",$P(Z,".",2,3)=123	Z="A.123.D"
S Z="A.",$P(Z,".",5)=123	Z="A....123"
K Z S $P(Z,".",5)=3	Z="....3"
S Z="ABC",$P(Z,"",1)=123	Z=123
S Z="ABC",$P(Z,"",2)=123	Z="ABC123"


$QLENGTH

Returns the number of subscripts in a specified Variable name.

Syntax

$QL{ENGTH}(Variable)

Definition

Variable	An expression that evaluates to a local or global variable name.

The $QLENGTH function returns an integer value that indicates the total number of subscripts in a local or global reference. If Variable contains no subscripts, the function returns zero; otherwise, the function returns the total number of subscripts.

Associated Topics

Variables
$QSUBSCRIPT Function

Examples

Setup	Value of Function
SET X="^A"	$QLENGTH(X)=0
S X="^A(3)"	$QL(X)=1
S X="^A(1,2,3)"	$QL(X)=3
S X=""	$QL(X)=0
S X="Y",Y="^A(3)"	$QL(@X)=1


$QSUBSCRIPT

Returns the value of a specified subscript within a Variable name.

Syntax

$QS{UBSCRIPT}(Variable,Position)

Definition

Variable	An expression that evaluates to a local or global variable name.
Position	An expression that specifies the position of the subscript in Variable that is to be returned.
The $QSUBSCRIPT function returns the value of a subscript within Variable that is specified by Position. If the value of Position is -1, the function returns environment information if provided in Variable. If the value of Position is 0, the function returns the local or global name unsubscripted and without environment information. If the value of Position is greater than the total number of subscripts in Variable, the function returns a null string.

Associated Topics

Variables
$QLENGTH Function

Examples

Setup	Value of Function
SET X="^A(3,5)"	$QSUBSCRIPT(X,1)=3 $QS(X,2)=5 $QS(X,-1)="" $QS(X,0)="^A" $QS(X,3)=""
S X="^|""MGR,FSA""|A(4,7)"	$QS(X,1)=4 $QS(X,2)=7 $QS(X,-1)="MGR,FSA" $QS(X,0)="^A"
S X="^A(3)",Y="X"	$QS(@Y,1)=3 $QS(@Y,-1)="" $QS(@Y,0)="^A"


$QUERY

Identifies the next or previous subscript, in collating sequence, for a specified subscripted Variable.

Syntax

$Q{UERY}(Variable{,Direction})

Definition

Variable	An expression that evaluates to a subscripted local or global variable name.
Direction	An expression that evaluates to either 1 or -1.
The $QUERY function is used to identify the next or previous node in a local or global variable that is defined and has data. The Variable name that is specified as an argument to the function must be a local or global variable, and naked references are allowed. If Direction is not specified, or if it evaluates to a value of 1, the system returns the full local or global reference (variable name and subscripts) of the first node that has data and follows the node specified by the Variable. If there is no node following the node specified by the Variable reference, the system returns a null value (""). If Direction is specified and has a value of -1, the system returns either the previous node or null if there is no previous node. If Direction is specified and has any value other than 1 or -1, an error condition occurs.

Associated Topics

Variables

Examples

Setup	Value of Function
SET ^A(-1)=0,^A(1,2,3)=1,   ^A(2)=2,^A(4)=3	$QUERY(^A)="^A(-1)" first node $Q(^A(-1))="^A(1,2,3)" second node  $Q(^A(1,2,3))="^A(2)" third node $Q(^A(2))="^A(4)" fourth node  $Q(^A(4))="" no following node  $Q(^A(4),-1)="^A(2)" previous


$RANDOM

Returns a pseudo-random number in a specified interval.

Syntax

$R{ANDOM}(Integer)

Definition

Integer	An integer expression that indicates the interval from which the random number is generated.
The $RANDOM function returns a random or pseudo-random integer value that is greater than or equal to 0 and strictly less than Integer. If the value of Integer is equal to 1, the function returns 0. If the value of Integer is less than 1, an error condition occurs.

Examples

Setup	Value of Function
SET X=$RANDOM(25)	X is between 0 and 24
SET X=$R(2)	X is either 0 or 1
SET X=$R(1)	X is always 0
SET X=$R(-1)	An error condition occurs


$REVERSE

Reverses the order of characters in a specified String.

Syntax

$RE{VERSE}(String)

Definition

String	A string-type expression.
The $REVERSE function returns a string whose characters are in reverse order of the characters contained in the specified String. The $REVERSE function is computationally equivalent to the $$REV(EXPR) extrinsic function that is defined by the following code.

REV(E) Q $S(E="":"",1:$$REV($E(E,2,$L(E)))_$E(E,1))

Computationally equivalent means that the result of the $REVERSE function is the same as if the code provided in the $$REV(EXPR) extrinsic function were to be successfully executed by an M process.

Examples

Setup	Value of Function
SET X="ABCDEF"	$REVERSE(X)="FEDCBA"
SET X=""	$RE(X)=""
SET X=2*64	$RE(X)=821


$SELECT

Returns the value of the first Expression whose truth-valued Condition is true.

Syntax

$S{ELECT}(Condition:Expression{,...})

Definition

Condition	A truth-valued expression.
Expression	Any type of expression.
The $SELECT function processes the arguments in a left-to-right sequence and evaluates each Condition until it finds one that is true (its truth-value is 1). If no true Condition is found, an error occurs. No evaluation of the Expression associated with the Condition occurs until a true Condition is found. The Expression associated with the true Condition is then evaluated and returned by the function. No other Condition or Expression following the true expression is evaluated.

Associated Topics

Truth-Valued Expressions

Examples

Setup	Value of Function
SET X=1	$SELECT(X=1:8,2=3:0)=8 $S(X=1:8,2=2:0)=8 $S(X=2:8,2=2:0)=0  $S(X=2:8,2=3:0) error; none true
S Y="B"	$S(X=3:8,Y="B":"MSM",X=1:9)="MSM" $S(X=Y:B(1),Y="A":^(2,3),1:3)=3 The naked indicator is not changed
S ^A(1)="TEST"	$S(X=1:^A(1),Y:S)="TEST" The naked indicator is set to ^A


MSM Functions - $STACK
$STACK

Returns information about the execution path leading to the current Level and about errors that may have occurred.

Syntax

$ST{ACK}(Level{,StackCode})

Definition

Level	An integer expression that specifies the execution level for which information should be returned.
StackCode	A string expression that specifies the type of information to be returned.
•	The single operand $STACK function provides the following information about the execution stack.

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

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

•	If the Level evaluates to a positive integer that is less than or equal to $STACK(-1), the function returns a value that indicates how the current 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, it was initiated by an extrinsic function or variable, and the function returns $$.

•	If the 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 which information to return. This operand can be in uppercase, lowercase, or mixed case.

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

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

•	If StackCode 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 label+offset^routine. If the location is an XECUTE command string, the function returns the at-sign character (@).

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

Associated Topics

$ECODE Special Variable
$ETRAP Special Variable
Error Processing

Examples

Setup	Value of Function
$STACK(-1)	10 The current nesting level is 10.
$ST(10,"ECODE")	,M9,Z<DIVER>:::5:2:,M6,Z<UNDEF>:::4:0:, Both a division by zero and a reference to an undefined local occurred at the same level. This can happen if the second error occurred inside the error trap itself.
$ST(10,"MCODE")	WRITE !!,A/B This reprints the line executing when the error occurred.
$ST(10,"PLACE")	ERR+5^ERRHAND The last error occurred five lines past the label ERR in routine ERRHAND.


$TEXT

Returns the text of a specified line within a routine.

Syntax

$T{EXT}(EntryRef)

Definition

EntryRef	A line label or a plus sign followed by a line number, optionally followed by a circumflex (^) and a routine name.
The $TEXT function returns the text of the line in the routine specified by the EntryRef argument. The EntryRef can be a line label (for example: ABC), a line label plus an offset (for example: ABC+5), or an offset of the form +line number (for example: +6). Optionally, any of these formats can be followed by a circumflex (^) and a routine name (for example: ABC^MYPROG, ABC+5^CUSTINV, +6^%STATUS). The returned text is in one of the following forms:

labelSP...SPtext

SP...SPtext

If the specified line reference does not exist or is beyond the last line of the routine, the function returns a null string. If a routine name is specified and it does not exist, the function returns a null string. The correct number of space characters is preserved to match the number entered when the line was created.

Examples

Assume that the following routine is loaded in the partition:

ABC  ;SAMPLE
     SET X=3 WRITE Y=3
     READ X Z
Z      WRITE !,X
     QUIT

Assume also that these lines are executed:

SET A="ABC"
S K=2
S B=3

The following illustrates the use of $TEXT:

$TEXT(+0)="ABC"
$T(ABC)="ABC ;SAMPLE"
$T(Z)="Z   WRITE !,X"
$T(ABC+1)=" SET X=3 WRITE Y=3
$T(ABC+2)=" READ X"
$T(+1)="ABC ;SAMPLE"
$T(+3)=" READ X"
$T(Z+2)="" (null string)
$T(@A+2)=" READ X"
$T(ABC+K)=" READ X"
$T(+B)=" READ X"

After executing the following, X is the first line of RTN:

XECUTE "ZLOAD RTN S X=$T(+1)"

This line of code writes out the entire routine contained in the partition to the current device:

F I=1:1 S X=$T(+I) Q:X=""  W X,!

Assume that the preceding routine was saved to disk with the name SAMPLE. The following then is valid:

$T(ABC^SAMPLE)="ABC ;SAMPLE"
$T(ABC+2^SAMPLE)=" READ X"
$T(+1^SAMPLE)="ABC ;SAMPLE"


$TRANSLATE

Returns a string that was translated according to the specified masks.

Syntax

$TR{ANSLATE}(String,From{,To})

Definition

String	Any string-type expression.
From	A string-type expression that specifies the characters to be replaced.
To	A string-type expression that specifies the replacement characters.
The $TRANSLATE function takes each character from left-to-right in the From string (the translate from character) and changes each occurrence of that character in the String to a new character. The first character in From is translated to the first character in To, the second to the second, the third to the third, and so on. If the length of the From string is greater than the To string, then any 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, the extra characters in the To string are ignored.

Associated Topics

$LENGTH Function

Examples

Setup	Value of Function
$TR("ABCDE","A","X")	XBCDE replaces A with X.
$TR("ABCDE","AB","X")	XCDE replaces A with X and removes B.
$TR("ABCDE","AB","ab")	abCDE replaces A with a and B with b.
S X="A",Y="B",Z="C" S A="ABCDE",B="AB",C="ab" $TR(@X,@Y,@Z)	Indirection can be used; the code returns the string "abCDE."


$VIEW

Returns the text, hexadecimal, decimal, or binary value of a specified memory location.

Syntax

$V{IEW}(Address{,Domain{,Length{,Type}}})

Definition

Address	An integer expression that is a memory address.
Domain	An integer expression that defines the logical type of memory from which the data is to be retrieved.
Length	An integer expression that indicates the number of contiguous memory locations to be retrieved.
Type	An integer expression that indicates the format of the data to be returned.
The $VIEW function is used to inspect the contents of system memory. The Domain argument specifies the logical area of memory to be inspected, and the Address argument specifies the offset into the area in bytes. A Domain of  -1, -2, or -3 indicates an absolute real memory address; -4 indicates the constant area within the Svector; -5 indicates the variable area within the Svector; 0 indicates the view buffer; and a number greater than 0 indicates a partition (1 is job 1, 2 is job 2, and so on). If the Domain is not specified, a value of -3 is assumed.

The Length argument specifies the number of bytes to retrieve. If it is omitted, a length that corresponds to the natural word size of the machine being used is assumed. The Type argument indicates the format in which the data is to be returned. A value of 0 indicates decimal, 1 indicates string, 2 indicates hexadecimal, and 3 indicates binary. If omitted, a decimal value is assumed.

Considerations

When the default values for Length are used, the code may not be portable between different implementations of MSM because the natural word sizes are different.

Associated Topics

Special Variables

Examples

Setup	Value of Function
SET X=$VIEW(100,-3,2,0)	Sets X to the decimal value of the two consecutive locations of memory starting at location 100.
W $V(1,0,1)	Writes the decimal value of the second byte of the View buffer to the current device.
I $V(44,2,2,2)="3DF0"	Tests location 44 of Job 2's partition vector for the hexadecimal value "3DF0".
S X=$V(108,$J,4)	Location 108 in the partition vector of the current job.
S X=$V(168,-4,2)	A two-byte field at offset 168 in the svector.
S X=$V(1022,0,2)	Last two bytes of the system View buffer in decimal.


$ZASCII

Returns the internal value (the Unicode character code) of a specified character. This differs from $ASCII, which returns the programmer character set value (the JIS90 character code).

Note  This function applies only to double-byte or wide character sets.

Syntax

$ZAS{CII}(String{,Position})

Definition

String	Any string-type expression.
Position	An integer expression that indicates the relative position of a character within the String.
The $ZASCII function returns an integer value that is the Unicode code of the specified character. The Position argument works the same as in $ASCII; it refers to a Position of a character in the String.

Examples

If you set X using the JIS90 code #2121 (double-byte space):

SET X=$CHAR(#2121)

Internally, a double-byte space is represented in Unicode as #3000 or decimal 12288:

WRITE $ZHEX($ZASCII(X))

3000

Associated Topics

$ASCII Function
$CHAR Function
$ZCHAR Function


$ZBN

Returns the starting block number for a routine or a global, allocates a disk block, or deallocates a disk block.

Syntax

$ZBN(Name)

$ZBN("",Block{,Owner{,VolNum}}})

Definition

Name	A routine name or a global variable name.
Block	An integer expression that indicates a disk block number.
Owner	An integer expression that specifies the UCI index number of the owner, 255 to indicate a system-owned block, or 254 to indicate a non-database block, and so on.
VolNum	An integer expression that specifies the index number of the volume group.
The $ZBN function returns the starting block number (the disk address of the highest level pointer block) for a specified global variable or the block number of a routine's header block. The global variable name must be unsubscripted and preceded by a circumflex (^). For routine names, a circumflex followed by a space and the name in parenthesis (for example, ^  ("MYPROG")) is used to indicate that the Name is a routine.

If the Name argument is "", the system allocates or deallocates the disk block. If Block is greater than zero, the system searches for a free disk block and allocates the first free block that is found. The search for a free block begins with the map block specified by the Block argument.

When the allocation is done within the current UCI (the Owner parameter is not specified on the $ZBN function), the block is allocated within the limits of the expansion pointers for the current UCI. If the VolNum parameter is specified, the system allocates the specified block within the specified volume group. Otherwise, it allocates the block within the current volume group.

If the Block number is less than zero, the system deallocates the specified block. When a block is deallocated, the Owner parameter is ignored. However, the VolNum parameter is honored. For both allocation and deallocation of blocks, the system always returns the number of the affected Block. For deallocation of blocks, this number is negative.

Associated Topics

MSM Structured System Variables

Examples

Setup	Value of Function
$ZBN(^SSN)	Returns block number of SSN global.
$ZBN(^ ("WP"))	Returns block number of WP routine.
$ZBN("",2)	Allocates a block, beginning the search from map number 2.
$ZBN("",2048,255,1)	Allocates a block as a system owned block on volume group 1, beginning the search from map number 2048.


$ZBname

A collection of functions that are used to perform logical operations on bit strings.

Syntax

$ZBname(BitParm{,BitParm{,BitParm}})

Definition

Name	The name of the bit function that is to be performed.
BitParm	An expression that evaluates to a function-specific parameter.
Each bit string function accepts from one to three BitParm parameters. The parameters specified for a function are specific to the function being performed. Each specified BitParm parameter must be one of the following.

BitStr	An expression that evaluates to a bit string. If the function accepts more than one BitStr as a parameter, the BitStr parameters are specified as BitStr1, BitStr2, etc.
BitVal	An expression that evaluates to a value of 0 or 1. Any other value is invalid.
BitPos	An expression that evaluates to a position within a bit string. The first position in a bit string is 1, the second is 2, and so on.
BitSize	An expression that evaluates to a number equal to the total number of 0 and 1 bits in a bit string.
The $ZBname function implements a variety of operations that work on bit strings. A bit string is defined as a string that contains any quantity of zeros and ones (any quantity of BitVals as defined above) concatenated together in any order. No other values can be present in the string. MSM packs each eight bits in a bit string into a one-byte character. All BitStrings are rounded up to multiples of eight BitVals (BitStrings are maintained internally as character strings).

$ZBA{ND}(BitStr1,BitStr2)

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

$ZBCO{UNT}(BitStr,{BitVal})

The $ZBCOUNT function returns a number that equals the number of times that the specified BitVal appears in the specified BitStr. If the BitVal parameter is not specified, a value of 1 is assumed.

$ZBF{IND}(BitStr,BitVal,{BitPos})

The $ZBFIND function returns a number that is one greater than the position of the first occurrence of the bit specified by BitVal. If the BitPos parameter is specified, the search for a matching bit begins at the location specified by BitPos. Otherwise, the search begins at position one in the string. This function is analogous to the $FIND function that operates on character strings.

$ZBG{ET}(BitStr,BitPos)

The $ZBGET function returns the value of the bit that appears in the BitStr at the location specified by the BitPos parameter. The returned value is either 0 or 1.

$ZBL{EN}(BitStr)

The $ZBLEN function returns a value that is a count of the number of bits in the specified BitStr. This function is analogous to the $LENGTH function that operates on character strings.

$ZBNO{T}(BitStr)

The $ZBNOT function returns a bit string that is the inverse (zeros are changed to ones and ones are changed to zeros) of the string specified by the BitStr parameter. The length of the returned string is the same as the length of the BitStr.

$ZBO{R}(BitStr1,BitStr2)

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

$ZBSE{T}(BitStr,BitPos,BitVal)

The $ZBSET function returns a string that is equal to the string specified by the BitStr parameter, except that the bit specified by the BitPos parameter is set to the value specified by the BitVal parameter. The length of the returned string is equal to the length of the string specified by the BitStr parameter.

$ZBST{R}(BitSize,{BitVal})

The $ZBSTR function returns a bit string that has a length equal to the length specified by the BitSize parameter, rounded up to a multiple of eight bits. If the BitVal parameter is omitted, a value of 0 is assumed. The system sets all of the bits in the returned string to the value specified by the BitVal parameter.

$ZBX{OR}(BitStr1,BitStr2)

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

Associated Topics

$EXTRACT Function
$FIND Function
$LENGTH Function

Examples

Setup	Value of Function
$ZBSTR(32,0)	Returns a string of 32 bits initialized to 0.
$ZBSET(X,16,1)	Sets the sixteenth bit in the X string to a 1.
$ZBCOUNT(X,1)	Counts the number of 1 bits in the string in X.
$ZBLEN(X)	Counts the number of bits in the string in X.
$ZBAND(X,Y)	ANDs the string in X with the string in Y.
$ZBNOT(X)	Inverts all of the bits in the string in X.
$ZBFIND(X,1)	Finds the first 1 bit in the string in X.
$ZBLEN($ZBSTR(31))	Returns a value of 32.


$ZBOOLEAN

Returns a value that is the result of a specified Boolean operation applied to two arguments.

Syntax

$ZB{OOLEAN}(Exp1,Exp2,Mask)

Definition

Exp1	Any expression.
Exp2	Any expression.
Mask	An integer expression that identifies the Boolean operation to be performed.
The $ZBOOLEAN function performs a bit-by-bit logical operation specified by the Mask on the Exp1 and Exp2 arguments. The Boolean operation is specified by a bit-mask that corresponds to the four possible states of two binary bits.  The following table shows the possible states and the corresponding Mask value that selects each state.

$ZBOOLEAN Mask Values

Bit in String1	Bit in String2	Value of Mask
0	0	8
0	1	4
1	0	2
1	1	1
By combining the values from the above table, the value of Mask can range from 0 to 15, inclusive.  If any of the states specified by the Mask is true, then the corresponding bit in the returned value is set to 1. Otherwise, the bit in the returned value is 0.  The following table illustrates all of the possible Mask settings and their associated logical operations.

$ZBOOLEAN Mask Settings

Mask	$ZBOOLEAN(A,B,Mask)
0	0
1	A ∧ B
2	A ∧ ¬B
3	A
4	¬A ∧ B
5	B
6	A ⊗ B
7	A ∨ B
8	¬A ∧ ¬B ≅ ¬ (A ∨ B)
9	¬ (A ⊗ B) ≅ ¬A ⊗ ¬B
10	¬B
11	A ∨ ¬B
12	¬A
13	¬A ∨ B
14	¬ (A ∧ B) ≅ ¬A ∨ ¬B
15	1
Logical AND	∧	Logical NOT	¬
Logical OR	∨	Identically Equal	≅
Exclusive OR	⊗
Although all data in MSM can be thought of as strings, the $ZBOOLEAN function is sensitive to the internal format used to store the values.  The operation of $ZBOOLEAN is only defined for the following two cases.

For operations on numeric values, both Expressions must be integers in the range 2147483648 through 2147483647, inclusive.  The result also is a numeric value within that range.  When either Expression is an MSM variable or an expression that evaluates to a string value (such as $PIECE or concatenation), the unary + operator should be used to ensure that the expression is interpreted as numeric.

For operations on strings, both Expressions must be strings.  The result will be a string whose length is equal to the length of Exp1. The operation is performed on the first character of Exp1 and the first character of Exp2, then the second characters, and so on for the entire length of Exp1. If Exp2 is shorter than Exp1, then Exp2 is reused from the first character as many times as necessary.  If Exp2 is longer than Exp1, then the extra characters are ignored.

For string operations on double-byte implementations of MSM, the $ZASCII values of the characters in the strings are used instead of the $ASCII values.  This usage is shown in example 9 below.

Associated Topics

$ZBname function
HEXADECIMAL operator
PLUS operator

Examples

All of the low-order bits are "ANDed" off:

SET X=#8F (or S X=143)

S X=$ZBOOLEAN(+X,#80,1)

Result: X=128, $ZHEX(X)="80"

All bits except for the four low-order bits are "ANDed" off:

S X=#9F

S X=$ZB(+X,1+2+4+8,1)

Result: X=15, $ZH(X)="F"

In the first case, because Exp1 is a string and Exp2 is a number, the result is not as expected.  To eliminate the ambiguity for numbers that might be stored internally as strings, always use the unary PLUS operator to force numeric interpretation of variables and other expressions:

S X="143"

S X=$ZB(X,#F,1)

Result: X=$CHAR(1,0,0)

S X=$ZB(+X,#F,1)

Result: X=15, $ZH(X)="F"

The OR operation is used to turn on the bits in Exp1 that are specified in Exp2:

S X=#40 (or S X=64)

S X=$ZB(X,#20,7)

Result: X=96, $ZHEX(X)="60"

Any bits that are on in both Exp1 and Exp2 are turned off in the result. This operation is used to turn off the bits in Exp1 that are specified in Exp2:

S X=#60 (or S X=96)

S X=$ZB(X,#20,2)

Result: X=64, $ZHEX(X)="40"

The Exclusive OR operation can be used to toggle a bit on and off:

S X=64

S Y=32 (or S Y=#20)

S X=$ZB(X,Y,6)

Result: X=96

S X=$ZB(X,Y,6)

Result: X=64

The following two examples illustrate the use of character strings.

In this code, a logical OR is used to turn on the high-order bit in each character of a three-character string:

S X=$C(1,2,3),Y=$C(128)

S X=$ZB(X,Y,7)

Result: X=$C(#81,#82,#83)

This example turns off all the bits in every second character of Exp1, and does not change the value of the other characters:

S X=$C(1,2,3,4,5,6),Y=$C(255,0)

S X=$ZB(X,Y,1)

Result: X=$C(1,0,3,0,5,0)

This example turns on the low-order bit of every character of Exp1. On a double-byte implementation of MSM, it uses the internal numeric value of each character without interpreting it as a character of the programmer character set:

S X=$ZCHAR(160,161,162,163)

S X=$ZB(X,$ZCH(1),7)

Result: X = $ZCH(161,161,163,163)


$ZCALL

Calls an external routine to perform a user-defined function.

Note   Although $ZCALL has been superseded by the ANSI standard External Call syntax, support for $ZCALL is still provided.

Syntax

$ZC{ALL}(Function{,Parm, ... , Parm})

Definition

Function	The name of the function to be called. This is the function's actual name without quotation marks.
Parm	One or more parameters to be passed to the function.
The $ZCALL function is used to call an external, user-supplied routine to perform an operation. This function is provided for backward compatibility. It has been superseded by the new external routine call syntax.

Examples

Setup	Value of Function
$ZCALL(CUBEROOT,9.75314)	Calls an external routine to compute a cube root.
$ZCALL(PORTIN,280)	Calls an external routine to READ a character.
$ZCALL(LIGHTPEN,30)	Calls an external routine to wait up to 30 seconds for the lightpen to be pressed.


$ZCHAR

Given a list of internal character-codes (Unicode codes), returns a string of characters.

Note  This function applies only to double-byte or wide character sets.

Syntax

$ZCH{AR}(Codepoint{,...})

Definition

Codepoint	An internal character-code (an integer).
The $ZCHAR function is similar to the $CHAR function except that the arguments are Unicode codes rather than the external (programmer) character set.

Associated Topics

$ASCII Function
$CHAR Function
$ZASCII Function

Examples

In the following examples, the symbol · represents a double-byte character where the internal code is #751F, corresponding to external code #4038.

WRITE $ZCHAR(#751F) →  · because #751F is the Unicode code point of · .

WRITE $CHAR(#4038) → · because #4038 is the external code point of · .


$ZCRC

Returns a computed checksum or cyclic redundancy check (CRC) of a string.

Syntax

$ZCR{C}(String{,Type{,Initvalue}})

Definition

String	Any string-type expression.
Type	An integer expression that indicates the type of checksum to be performed on the string.  The default value is 0 (Exclusive OR).
Initvalue	An integer expression that is added to the result of the CRC calculation (only valid for types 5, 6, and 32).
The $ZCRC function computes six types of checksums: two variations of exclusive OR, ASCII summation, two variations of 16-bit CRC, and 32-bit CRC.

Checksum Types

Type	Checksum
0	Exclusive OR
1	ASCII summation
5	16-bit CRC (DTM-compatible)
6	16-bit CRC (DSM-compatible)
7	XOR the internal byte-stream
32	32-bit CRC
Type 0 selects an Exclusive OR calculation which returns a value that is cumulative for the entire String. The second character is XORed to the first, then the third character is XORed to the result of the first operation, then the fourth character is XORed, and so on.

Type 1 selects an ASCII summation that is calculated by adding together the decimal values of each ASCII character in the String.

Types 5 and 6 select two different 16-bit CRC computations. The type 5 CRC is the same as the 16-bit CRC performed by the DTM function with the same syntax. The type 6 CRC is the same as the one performed by the VAX-DSM $ZCRC function. These options are useful for writing data transfer programs that must communicate with either of these M implementations.

Type 7 (like Type 0) selects an exclusive OR calculation which returns a value that is cumulative for the entire String, but unlike Type 0, this computation operates on the individual bytes of the string. For single-byte versions of  MSM, Types 0 and 7 are equivalent. For double-byte versions of MSM, Type 0 operates on the two-byte characters of the string, returning a value between 0 and 65,535 (0xFFFF), whereas Type 7 operates on individual bytes, returning a value between 0 and 255 (0xFF).

Type 32 selects a 32-bit CRC computation that is unique to MSM.

The parameter Initvalue, which defaults to 0, represents the starting value of the CRC. It is used when the CRC is generated on multiple pieces of a string. For example, if the string is too long to fit in a single variable, it can be segmented into multiple variables.  The Initvalue then can be used to calculate a CRC as if the segments were all concatenated. The last example illustrates this feature.

Associated Topics

$ASCII Function

Examples

Setup	Value of Function
SET X="ABCDE"	$ZCRC(X)=65 $ZCR(X,0)=65 $ZCR(X,1)=335 $ZCR(X,5)=14362 $ZCR(X,6)=20523 $ZCR(X,32)=-1907187440
S Y="123456"	$ZCRC(Y,0)=7 $ZCR(Y,1)=309 $ZCR(Y,5)=4605 $ZCR(Y,6)=10724 $ZCR(Y,32)=494219010
S X="ABCDE",Y="123456"	$ZCR(X_Y,6)=15906 $ZCR(Y,6,$ZCR(X,6))=15906


$ZCREATEOBJECT

Returns an object reference to a newly instantiated object.

Syntax

$ZCRE{ATEOBJECT}(ClassName)

Definition

ClassName	A string-type expression that specifies the class of the object to be instantiated.
This function is available only on platforms that support COM objects.

By convention, the format of the ClassName parameter is as follows:

AppName.ObjectType

Every application that supports OLE automation provides at least one type of object. For example, a word processing application may provide an application object, a document object, and a toolbar object.

$ZCREATEOBJECT is used when there is no current instance of the object. The $ZGETOBJECT function is used if there is a current instance or if the application is to be started and is then to load a file.

OLE note  If an object has registered itself as a single-instance object (for example: the Word.Basic object in Microsoft Word 6.0), only one instance of the object is created, no matter how many times $ZCREATEOBJECT is invoked.

Associated Topics

SET Command
ZSETOBJ Command
$ZGETOBJECT Function
$ZOBJREFERENCE Function

Examples

M Code	Description
ZSET X=$ZCRE("word.Basic") I $ZOBJREF(X)=0 G ERROR  D X.Insert="Hello World" D X.FileSaveAs="C:\hello.doc"	Creates a Word 6.0 document object. Ensures allocation succeeded. Inserts a line. Saves the file.


$ZDATE

Returns the external representation of a date by converting it from its internal $HOROLOG format.

Syntax

$ZD{ATE}(Integer{,Type{,Flag}})

Definition

Integer	An integer expression that is in $HOROLOG format.
Type	An integer expression that indicates the format for the external date.
Flag	An integer expression that indicates whether the century should always be included.
The $ZDATE function converts the Integer value, which is assumed to be the number of days since December 31, 1840, to an external date format. The external form is determined by the value of the Type argument. Type has the following meanings.

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 abbreviation for the month, and YY is the year.
3	DD/MM/YY is the European form of the date, where DD is the day, MM is the month, and YY is the year.
If the Type is omitted, a value of 1 is assumed. If the year is in the current century, the century is not included unless Flag has a value of 1.

Associated Topics

$HOROLOG Special Variable

Examples

Setup	Value of Function
SET X=2	$ZDATE(X)="01/02/1841" $ZD(X,1)="01/02/1841" $ZD(X,2)="02 JAN 1841" $ZD(X,3)="02/01/1841"
S X=53137	$ZD(X)="06/26/86" $ZD(X,1)="06/26/86" $ZD(X,2)="26 JUN 86" $ZD(X,3)="26/06/86" $ZD(X,3,1)="26/06/1986"


$ZDEVICE

Returns the external device name of a terminal device connected to the system.

Syntax

$ZDEV{ICE}(Integer)

Definition

Integer	An integer expression that evaluates to a device number.
The $ZDEVICE function returns the external name of a terminal port. The Integer value that is specified is the actual MSM device number. If the device does not have an external name, the device number is returned.

For LAT ports, the external name is the port name and the LAT server name in the form port@server. Note that for PC LAT emulating software, the port name is typically equal to the null string.

For Telnet ports (MSM-Server for Windows only), $ZDEVICE returns the IP host name, the IP port number, and the IP address, separated by the tilde (~) character. If the host name is not known, the IP address is returned in its place.

For UNIX ports, the external name is the UNIX tty name.

Associated Topics

$PRINCIPAL Special Variable
$IO Special Variable
Using Peripheral Devices, MSM User's Guide

Examples

Setup	Value of Function
WRITE $ZDEVICE(64)	PORT_1@LABSERVER
W $ZDEV($IO)	@PC_0204F83F100A
W $ZDEV($PRINICAL)	Fredspc~3087~161.201.2.3
W $ZDEV(3)	3


$ZGETOBJECT

Retrieves a COM object from a file and returns an object reference to the instantiated object.

Syntax

$ZGETO{BJECT}({PathName}{,ClassName})

Definition

PathName	A string-type expression that specifies the full pathname and filename of the file that contains the object to be instantiated.
ClassName	A string-type expression that specifies the class of the object to be instantiated.
This function is available on platforms that support COM objects.

If the PathName parameter is omitted, the ClassName parameter must be supplied.

If PathName is a zero-length string (""), $ZGETOBJECT returns a new object instance of the specified type. If the PathName argument is omitted entirely, $ZGETOBJECT returns a currently active object of the specified type. If an object of the specified type does not exist, an error occurs (no object is created). By convention, the path name can include a suffix of the form: !name. The name portion of the file is used to activate the object.

If the object's class is not specified, the filename determines the application to start and the object to activate. Some files can support more than one class of object. For example, a drawing might support three types of objects: an application object, a drawing object, and a toolbar object, all of which are part of the same file. The optional ClassName argument can be used to specify which object in a file is to be activated.

$ZGETOBJECT is used if there is a current instance of the object and if the object is to be created with a loaded file. If there is no current instance and the object is not to be started with a file loaded, the $ZCREATEOBJECT function is used.

OLE note  If an object has registered itself as a single-instance object (for example: the Word.Basic object in Microsoft Word 6.0), only one instance of the object is created, no matter how many times $ZGETOBJECT is invoked.

Associated Topics

SET Command
ZSETOBJ Command
$ZCREATEOBJECT Function
$ZOBJREFERENCE Function

Examples

Setup	Description
ZSET X=$ZGETO("c:\cad\schema.cad")	Instantiates an object in schema file.
ZSET X=$ZGETO("c:\cad\schema.cad!Layer3")	Activates layer 3 within the schema file.
ZSET X=$ZGETO("d:\drawings\   sample.drw","FIGMENT.DRAWING")	FIGMENT is the name of the drawing application, and DRAWINGS is one of the object types it supports.
ZSET X=$ZGETOBJECT(,"FIGMENT.DRAWING") G:$ZOBJREF(X) GOTOBJ	Locates an active object of the FIGMENT.DRAWING class.
ZSET X=$ZGETO("","FIGMENT.DRAWING")	Creates a new instance of a FIGMENT.DRAWING class.


$ZHEX

Returns the decimal value of a hexadecimal number or the hexadecimal value of a decimal number.

Syntax

$ZH{EX}(Expression)

Definition

Expression 	An expression that evaluates to a string or an integer.

The $ZHEX function converts a hexadecimal value to decimal or a decimal value to hexadecimal. If the Expression evaluates to a string, then the conversion is from hexadecimal to decimal. If the Expression evaluates to an integer, then the conversion is from decimal to hexadecimal.

Considerations

When converting from hexadecimal to decimal, the string may contain numbers from 0 through 9 and letters from A through F in uppercase, lowercase, or a mixture of the two; otherwise, the function returns 0.

Associated Topics

HEXADECIMAL Operator

Examples

Setup	Value of Function
$ZHEX("F")	Returns 15, the decimal value.
$ZH(15)	Returns "F", the hexadecimal value.
$ZH($ZH(20))	Returns 20, the original value.
$ZH(20)	Converts a decimal to a hexadecimal value of 14 (argument is evaluated as an integer).
$ZH("20")	Converts a hexadecimal to a decimal value of 32 (argument is evaluated as a string).


$ZHL

Converts M internal ($HOROLOG) format date or time numbers into external (ASCII text) values for the date or time.

Syntax

$ZHL (Type,Format_String,{$H_Value})

Definition

Type	Type of format to perform:  1 - date, 2 - time.
Format_String	Date or time formatting token. In this string, the replacement tokens listed in the following tables are used to specify the parts of the date or time to be returned. Any punctuation characters are copied to the result unchanged. The punctuation and tokens can be in any order. The tokens can be combined in any order in the format string and can be repeated. The string cannot contain other sequences of characters.
The $ZHL function allows the caller to control the format of the external date or time.  For each call, the function converts only a single date or time.

The following token strings apply to date formatting and are only valid when Type is one. Different cases produce different results.

Date Format Strings

Format	Resulting Value
yyyy	Year (four digits, including century)
yy	Year within century (two digits, zero-padded if necessary)
by	Year (two digits, padded with space)
y	Year (two digits if within current  century, otherwise four digits)
mm	Numeric month of year (zero-padded to two digits)
bm	Numeric month of year (blank-padded to two characters)
m	Numeric month of year (no padding)
dd	Day of month (zero-padded to two digits)
bd	Day of month (blank-padded to two characters)
d	Day of month (no padding)
ww	Week of year (zero-padded to two digits)
bw	Week of year (blank-padded to two characters)
w	Week of year (no padding)
jjj	Julian day of the year (zero-padded to three digits)
bjj	Julian day of the year (blank-padded to three characters)
j	Julian day of the year (no padding)
MONTH	Full spelling of month name (all uppercase)
Month	Full spelling of month name (leading uppercase)
month	Full spelling of month name (all lowercase)
MON	Three-letter month abbreviation (all uppercase)
Mon	Three-letter month abbreviation (leading uppercase)
mon	Three-letter month abbreviation (all lowercase)
DAY	Full spelling of day-of-week name (all uppercase)
Day	Full spelling of day-of-week name (leading uppercase)
day	Full spelling of day-of-week name (all lowercase)
DY	Three-letter abbreviation for day-of-week name (all uppercase)
Dy	Three-letter abbreviation for day-of-week name (leading uppercase)
dy	Three-letter abbreviation for day-of-week name (lowercase)
-1	Microsoft Windows NT only:  Date in long format
-2	Microsoft Windows NT only:  Date in short format
The following token strings apply to time formatting and are only valid when Type is two. Different cases produce different results.

Time Format Strings

Format	Resulting Value
HH	Hour of day, 24-hour clock (zero-padded to two digits)
bH	Hour of day, 24-hour clock (blank-padded to two characters)
H	Hour of day, 24-hour clock (no padding)
hh	Hour of day, 12-hour clock (zero-padded to two digits)
bh	Hour of day, 12-hour clock (blank-padded to two characters)
h	Hour of day, 12-hour clock (no padding)
mm	Minute of hour (zero-padded to two digits)
bm	Minute of hour (blank-padded to two characters)
m	Minute of hour (no padding)
ss	Second of minute (zero-padded to two digits)
bs	Second of minute (blank-padded to two characters)
s	Second of minute (no padding)
.nnn…	Fraction of second (the number of n characters specifies precision)
p	am or pm (lowercase)
P	AM or PM (uppercase)
-1	Microsoft Windows NT only:  Time format
-2	Microsoft Windows NT only:  Time format, without the seconds portion
$H_Value	The M internal $HOROLOG number for the date or time to be formatted. For a date, $H_Value is the first part of the $HOROLOG system variable; for a time, $H_Value is the second part of $HOROLOG. If no $H_Value is supplied, the system assumes the current date or time value of $HOROLOG when the function is executed.
Associated Topics

ZHOROLOG Command
$HOROLOG Special Variable
$ZDATE Function

Examples

Setup	Value of Function
Dates:
$ZHL(1,"dd-MON-yy",56690))	18-MAR-96
$ZHL(1,"Day, Month d, yyyy",   $P($H,",",1))	Monday, March 18, 1996 (today's date)
$ZHL(1,"dd-Mon-yyyy",56678)	06-Mar-1996
Times:
$ZHL(2,"h:mm P",70000)	7:26 PM
$ZHL(2,"H:mm",70000)	19:26
$ZHL(2,"hh:mm:ss p",67678)	06:47:58 pm
$ZHL(2,"bH:mm:ss.nn")	9:21:43.00 (current time)
$ZHL(2,"HH:mm",$P($H,",",2))	09:21 (current time)


$ZNEXT

Identifies the next or previous node, in collating sequence, for a specified subscripted variable.

Syntax

$ZN{EXT}(Variable{,Direction})

Definition

Variable	An expression that evaluates to a subscripted local or global variable name.
Direction	An expression that evaluates to either 1 or -1.
The $ZNEXT function is used to identify the next or previous node in a local or global variable that is defined and has data. The Variable name that is specified as an argument to the function must be a local or global variable, and it must be a full reference. If Direction is not specified or if it evaluates to a value of 1, the system returns the full local or global reference (variable name and subscripts) of the first node that has data and follows the node specified by the Variable. If there is no node following the node specified by the Variable reference, the system returns a value of -1. If Direction is specified and has a value of -1, the system either returns the previous node or -1 if there is no previous node. If Direction is specified and has any value other than 1 or -1, an error condition occurs.

The $ZNEXT and $ZORDER functions perform identical operations. The only difference is in the starting and ending values of the functions. In the case of $ZNEXT, the starting and ending value is -1. For $ZORDER, the null value is used to indicate the starting and ending points. The $ZNEXT and $QUERY also are identical except for the reason identified above.

Associated Topics

Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZORDER Function

Examples

Setup	Value of Function
SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3	$ZNEXT(^A(-1))="^A(1,2,3)" first node $ZN(^A(1,2,3))="^A(2)" second node $ZN(^A(2))="^A(4)" third node $ZN(^A(4))=-1 no descendants $ZN(^A(4),-1)="^A(2)" previous node $ZN(^A(-1),-1)="^A(4)" last node


$ZOBJREFERENCE

Identifies whether an expression refers to an object and whether two expressions refer to the same object.

Syntax

$ZOB{JREFERENCE} (Expression{,Expression})

Definition

Expression	Any M expression.
The $ZOBJREFERENCE function is used to test whether a local variable contains an object reference or a non-object value. It also can be used to test whether two local variables both contain a reference to the same object.

If only one variable is specified, the function returns a value as follows according to the type of data stored in the variable passed to it.  If the variable contains an object reference, it returns one (1).  If the variable contains a reference to the "null" or "nothing" object, it returns minus one (-1).  If the variable is a local or global node with data, the function returns zero (0). Otherwise, an <UNDEF> error is raised because $DATA(glvn)#10=0.

$ZOBJREFERENCE(glvn) is TRUE when glvn contains an object reference; otherwise, it is FALSE. The exact return value of $ZOBJREFERENCE(glvn) is relevant only if a null object reference can arise; for example, when an object's method enumerates other objects (similar to $ORDER on an M array). The end of the enumeration generally is signaled by the return of a null object reference.

The existence of an object reference in a variable does not guarantee the existence of the object. Attempts to manipulate its properties or perform its methods will fail if the object has ceased to exist.

Associated Topics

ZSETOBJ Command
$ZCREATEOBJECT Function
$ZGETOBJECT Function

Examples

Setup	Value of Function
ZSET A=$$FUNC(PARM) IF $ZOBJREF(A)	FUNC might return an object reference. Checks for object reference.
ZSET B=$$FUNC(parm) IF $ZOBJREF(A,B)	Checks whether or not A and B are both references to the same object.


MSM Functions - $ZORDER
$ZORDER

Identifies the next node, in collating sequence, for a specified subscripted variable.

Syntax

$ZO{RDER}(Variable{,Direction})

Definition

Variable	An expression that evaluates to a subscripted local or global variable name.
Direction	An expression that evaluates to either 1 or -1.
The $ZORDER function is used to identify the next or previous node in a local or global variable that is defined and has data. The Variable name that is specified as an argument to the function must be a local or global variable and it must be a full reference. If Direction is not specified or if it evaluates to a value of 1, the system returns the full local or global reference (variable name and subscripts) of the first node that has data and follows the node specified by the Variable. If no node follows the node specified by the Variable reference, the system returns a value of null (""). If Direction is specified and has a value of -1, the system either returns the previous node or null if there is no previous node. If Direction is specified and has a value other than 1 or -1, an error condition occurs.

The $ZORDER and $ZNEXT functions perform identical operations. The only difference is the functions' starting and ending values. For $ZORDER, the starting and ending value is null. For $ZNEXT, a -1 value specifies the starting and ending points. The $ZORDER and $QUERY functions are identical.

Associated Topics

Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZNEXT Function

Examples

Setup	Value of Function
SET ^A(-1)=0,^A(1,2,3)=1,   ^A(2)=2,^A(4)=3	$ZORDER(^A(""))="^A(-1)" first node $ZO(^A(-1))="^A(1,2,3)" second node $ZO(^A(1,2,3))="^A(2)" third node  $ZO(^A(2))="^A(4)" fourth node $ZO(^A(4))="" no descendants $ZO(^A(4),-1)="^A(2)" previous $ZO(^A(""),-1)="A(4)" last node


$ZOS

The $ZOS function allows the programmer to invoke the more commonly used Windows functions from within an M program. All $ZOS functions share a common format and similar behavior.

Syntax

$ZOS(OptNum{,Opt1{,Opt2{,Opt3}}})

Definition

OptNum	An integer expression that indicates the Windows function to be performed.
Opt1	An optional parameter whose format and contents are specific to the Windows function that the system is performing.
Opt2	An optional parameter whose format and contents are specific to the Windows function that the system is performing.
Opt3	An optional parameter whose format and contents are specific to the Windows function that the system is performing.
If the $ZOS function fails, it returns a negative error number, where the error number is the return code received from the corresponding Windows system function. Common error codes that can be received are described later in this section.

The following subsections describe the Windows functions that can be invoked from MSM, the parameters that must be supplied for each function, and the value returned upon successful completion of the function.

See Also:

Set Current Drive

Delete a File

Rename a File

Get Windows Version Number

Set File Attributes

Create a New Directory

Remove an Existing Directory

Change Current Directory

Get Drive Parameters

Get File Attributes

Get Current Directory for Drive

Begin Directory Search

Continue Directory Search

Get Current Drive

Close Directory Search

Get Available Drives

$ZOS Function Call Errors


Set Current Drive

This function sets the current drive in Windows. The value is changed in Windows so that future file references can use this drive as the default drive. This affects the Host File Server (HFS) in MSM as well as other $ZOS functions.

Syntax

$ZOS(1,DriveID)

DriveID is a single letter (uppercase or lowercase), optionally followed by a colon (:).

The following example illustrates this function.

$ZOS(1,"A")	Sets default drive to A
$ZOS(1,"a")	Sets default drive to A
$ZOS(1,"C:")	Sets default drive to C
If the function is successful, it returns 0; otherwise, it returns -errorno to indicate an error.


Delete a File

This function deletes a file from the Windows file system. File attributes are honored by the system so that read-only files cannot be deleted. This function is equivalent to the ERASE command in Windows.

Syntax

$ZOS(2,FileName)

FileName is the name of the file to be deleted and can include a DriveID and a directory path.

The following example illustrates this function.

$ZOS(2,"MYFILE")	Deletes MYFILE
$ZOS(2,"a:\myfile.dat")	Deletes myfile.dat on a:
$ZOS(2,"C:\UTL\XYZ")	Deletes \UTL\XYZ on C:
If the function is successful, it returns 0 to indicate the file was deleted. Otherwise, the function returns an error code of -2 to indicate file not found, -3 to indicate path not found, or -5 to indicate that access was denied.

Note  Unpredictable results can occur if the MSM database files that the system is using are deleted.


Rename a File

This function renames a file within the Windows file system. File attributes are honored by the system so that read-only files cannot be renamed. This function is equivalent to the RENAME command in Windows.

Syntax

$ZOS(3,OldFileName,NewFileName)

OldFileName is the name of the file to be renamed. OldFileName optionally can include a DriveID and a directory path.

NewFileName is the new name of the renamed file. NewFileName optionally can include a directory path. If a specified path is different than the path supplied or implied in the OldFileName, the file is moved to the new directory. If a DriveID is specified, it must be the same as the DriveID associated with OldFileName.

The following example illustrates this function.

$ZOS(3,"FILE.DAT","FILE.BAK")	Renames file to .BAK file
$ZOS(3,"\UTL\PROG","\OLD\PROG")	Moves PROG file
$ZOS(3,"C:\ABC","C:\XYZ")	Renames ABC on C:
If the function is successful, it returns 0 to indicate the file was renamed. Otherwise, the function returns an error code of -2 to indicate file not found, -3 to indicate path not found, -5 to indicate that access was denied, or -17 if files are not on the same device.

Note  Unpredictable results can occur if the MSM database files the system is using are renamed.


Get Windows Version Number

This function returns the internal version number of Windows that is currently running on the system. It returns a string in the form major.minor, in which major is the major release number, and minor is the minor sub-release number.  In MSM-PC/PLUS, it returns the Microsoft DOS version number.

Syntax

$ZOS(4)

This function does not require any parameters.

The following example illustrates this function.

$ZOS(4)	Returns 3.50 for Windows NT Version 3.5
$ZOS(4)	Returns 4.0 for Windows NT Version 4
The function is always successful and always returns a string value.


Set File Attributes

This function sets the attributes for a specified file. Any combination of valid attributes (read-only, hidden, system, or archive) can be specified on the function. No equivalent command exists in Windows.

Syntax

$ZOS(5,FileName,Attributes)

FileName is the name of the file whose attributes are to be changed. FileName optionally can include a DriveID and a directory path.

Attributes is a numeric expression that specifies the file's attributes. Acceptable values are 32 for archive, 4 for system, 2 for hidden, and 1 for read-only. These values can be added together to combine attributes (6 for hidden and system).

The following example illustrates this function.

$ZOS(5,"XYZ",32+1)	Makes XYZ read-only and archive
$ZOS(5,"A:\ABC",2+4)	Makes ABC a hidden and system file
$ZOS(5,"\UTL\COPY",1)	Makes \UTL\COPY read-only
If the function is successful, it returns a null string to indicate that the attributes were changed. Otherwise, the function returns an error code of -2 to indicate file not found, -3 to indicate path not found, or -5 to indicate that access was denied.


Create a New Directory

This function creates a directory node in Windows and is equivalent to the MKDIR command in Windows.

Syntax

$ZOS(6,DirectoryName)

DirectoryName is the name of the directory to be created. DirectoryName optionally can include a DriveID and a directory path.

The following example illustrates this function:

$ZOS(6,"UTL")	Creates UTL directory.
$ZOS(6,"A:\USR")	Creates USR directory on A.
$ZOS(6,"\TST\DIR")	Creates TST\DIR directory.
If the function is successful, it returns a null value to indicate that the directory was created. Otherwise, the function returns an error code of -3 to indicate path not found or -5 to indicate that access was denied.


Remove an Existing Directory

This function removes a directory node in the tree-structured file system of Windows. This function is equivalent to the RMDIR command in Windows.

Syntax

$ZOS(7,DirectoryName)

DirectoryName is the name of the directory to be removed. Optionally, it can include a DriveID and a directory path.

The following example illustrates this function.

$ZOS(7,"UTL")	Removes UTL directory $ZOS
$ZOS(7,"A:\USR")	Removes USR directory on drive A
$ZOS(7,"\TST\DIR")	Removes TST\DIR directory
If the function is successful, it returns 0 to indicate the directory was removed. Otherwise, the function returns an error code of -3 to indicate path not found, -5 to indicate that access was denied, or -16 to indicate that the specified DirectoryName is the current directory.


Change Current Directory

This function sets the current or default directory in Windows and is equivalent to the CD command in Windows.

Syntax

$ZOS(8,DirectoryName)

DirectoryName is the name of the directory to be changed. DirectoryName optionally can include a DriveID and a directory path.

The following example illustrates this function.

$ZOS(8,"TEST")	Makes TEST the current directory
$ZOS(8,"C:\A\B\C")	Makes C:A\B\C the current directory
$ZOS(8,"\OLD\DIR")	Makes \OLD\DIR the current directory
If the function is successful, it returns 0 to indicate that the directory was changed. Otherwise, the function returns an error code of -3 to indicate path not found, or -5 to indicate that access was denied.


Get Drive Parameters

This function retrieves selected information about the specified disk device.

Syntax

$ZOS(9,DriveId)

DriveId is a single letter (uppercase or lowercase), as an option followed by a colon (:). A null value may be specified to indicate the current default drive.

The following examples illustrate this function.

$ZOS(9,"")	Returns values for current drive
$ZOS(9,"a")	Returns values for drive A
$ZOS(9,"C:")	Returns values for drive C
If the function is successful, it returns a string in the form of N1^N2^N3^N4 where N1 is the number of sectors per cluster, N2 is the number of available allocation clusters, N3 is the number of bytes per sector, and N4 is the number of clusters per drive. Otherwise, the function returns an error code of -1 to indicate an invalid drive was specified.


Get File Attributes

This function returns the attributes for a specified file in Windows. There is no equivalent command in Windows.

Syntax

$ZOS(10,FileName)

FileName is the name of the file whose attributes are to be reported. FileName optionally can include a DriveID and a directory path.

The following examples illustrate this function.

$ZOS(10,"MYPROG")	Returns attributes for MYPROG
$ZOS(10,"A:\TEST")	Returns attributes for A:TEST
$ZOS(10,"\NEW\FILE")	Returns attributes for \NEW\FILE
If the function is successful, it returns a numeric value that corresponds to the file's attributes. Individual attributes are 2048 for compressed, 256 for temporary, 128 for normal (no other attributes), 32 for archive, 16 for directory, 4 for system, 2 for hidden, and 1 for read-only. These values are added together when more than one attribute exists for a file (6 for hidden and system). Otherwise, the function returns an error code of -2 to indicate file not found, -3 to indicate path not found, or -5 to indicate that access was denied.


Get Current Directory for Drive

This function returns the current default directory for the specified drive. There is no equivalent command in Windows.

Syntax

$ZOS(11[,DriveID])

DriveID is a single letter (uppercase or lower case), optionally followed by a colon (:). If DriveID is omitted, the complete current directory, including the drive ID, is returned.

The following example illustrates this function.

$ZOS(11,"C")	Returns the default directory for C
$ZOS(11,"C:")	Returns the default directory for C
$ZOS(11)	Returns the full current directory
If the function is successful, it returns a string that contains the full path name to the directory. If DriveID was specified, the string does not include the DriveID. If an invalid DriveID was specified, the function returns an error code of -15.


Begin Directory Search

This function searches a directory for a specified file in Windows and is used to find the first file that meets specified search criteria. The Continue Directory Search function, which is described in the following section, is used to find the second and subsequent files. There is no equivalent command in Windows.

Syntax

$ZOS(12,FileName,Attribute)

FileName is the name of the file to search for in a directory. It may include the ? and * wild card characters and optionally, a DriveID and a directory path.

Attribute is a numeric expression that indicates the attributes for the file search. Acceptable values are 32 for archive, 16 for subdirectory, 8 for volume label, 4 for system, 2 for hidden, and 1 for read-only. These values can be added together to combine attributes (6 for hidden and system). If a value of 0 or null is specified, only ordinary files are found.

The following example illustrates this function.

$ZOS(12,"*.*",4)	Finds all system files.
$ZOS(12,"PRO?.*","")	Finds "PRO?.*" ordinary files.
$ZOS(12,"C:\CN\*.EXE",1)	Finds "C:\CN\*.EXE" read-only.
If the function is successful, it returns a string in the form S1^S2, in which S1 is the FileName that was found and S2 is a character string that is used as input to the Continue Directory Search function. Otherwise, the function returns an error code of -2 to indicate invalid path or null to indicate no matching directory entry found. S2 also contains file information in the same format as MSM-PC/PLUS.

$A(S2,22) = File attributes

$E(S2,23,24) = File time in MS-DOS format

$E(S2,25,26) = File date in MS-DOS format

$E(S2,27,30) = File size, least significant byte first

There is a difference between MSM Windows implementations and MSM-PC/PLUS. The Begin Search function opens a search handle that uses Windows' resources and should be closed when it is no longer required.  There is no such requirement in MSM-PC/PLUS because searches are performed differently in MS-DOS. If this handle is open, it is closed in the following situations:

•	$ZOS(12) is issued to begin a new search.

•	$ZOS(8) is issued to change the current directory.

•	$ZOS(13) reaches the end of a search.

•	$ZOS(1) is issued to change the current drive.

•	$ZOS(16) is issued.

•	The job terminates.

•	If a search operation is not continued to the end, a $ZOS(16) call is issued to close the search handle.


Continue Directory Search

This function continues a directory search that was started using the Begin Directory Search function. There is no equivalent command in Windows.

Syntax

$ZOS(13,SearchParm)

SearchParm is the character string returned by the Begin directory function for the first file or by this function for the second and subsequent files.

The following example illustrates this function.

$ZOS(13,$ZOS(12,"*.BAK",0)))	    Gets second file

SET X=$ZOS(12,"PROG?.*",0) QUIT:$P(X,"^")=""
FOR  SET X=$ZOS(13,X) QUIT:$P(X,"^")=""

If the function is successful, it returns a string in the form S1^S2, where S1 is the FileName that was found and S2 is a character string that is used as the next SearchParm to this function. Otherwise, the function returns an error code of -2 to indicate invalid path or -12 to indicate no matching directory entry found.


Get Current Drive

This function returns the current default drive value in Windows. There is no equivalent command in Windows.

Syntax

$ZOS(14)

This function does not require any parameters. The following example illustrates this function.

$ZOS(14)	Returns current drive
If the function is successful, it returns the current drive as a single character (for example: A). Otherwise, it returns a negative error code.


Close Directory Search

This function releases system resources that were allocated to perform a directory search. This function is performed automatically by MSM at the end of a directory search when $ZOS(12) or $ZOS(13) returns a null string. However, it should be called explicitly if a directory search is abandoned before the end of the search is reached.

Syntax

$ZOS(16,SearchParm)

The following example illustrates this function.

S X=$ZOS(13,X)	X contains the desired file name
S I=$ZOS(16,X)	Abandons the search and releases resources
This function always returns 0.

Note    Not available in MSM-PC/PLUS.


Get Available Drives

This function returns a list of available drives.  The list contains the root directory for each drive, with each element separated by $C(0).

Syntax

$ZOS(17)

Note   Not available in MSM-PC/PLUS.


$ZOS Function Call Errors

The following table lists error codes that can be returned by the $ZOS function. The most commonly returned error codes in this table also are described with the $ZOS functions.

$ZOS Error Codes

Number	Description
-1	Invalid function
-2	File not found
-3	Path not found or invalid
-4	Too many open files
-5	Access denied
-6	Handle is invalid
-8	Insufficient memory
-11	Format invalid
-12	Access code invalid
-14	Unknown unit
-15	Disk drive invalid
-16	Attempt to remove the current directory
-17	Not same device
-18	No more files
-19	Disk write-protected
-20	Unit unknown
-21	Drive not ready
-23	CRC error
-24	Bad request structure length
-25	Seek error
-26	Unknown media type
-27	Sector not found
-29	Write fault
-30	Read fault
-31	General failure
-32	Sharing violation
-33	Lock violation
-80	File already exists
-82	Cannot make directory


$ZPOSITION

Returns the number of positions of a string that can fit in a field on an output device.

Note  This function applies only to double-byte or wide character sets.

Syntax

$ZPO{SITION}(String,Field{,Width})

Definition

String	Any string type expression.
Field	An integer expression that specifies the size of the output field.
Width	An expression that specifies the relative width of a double-byte character, when compared with a single-byte character.
The $ZPOSITION function is used to determine the number of characters of a String, beginning with the first, can fit into a fixed-length field of an output device. The Field argument specifies the size of the output field in single-byte character positions.

Considerations

The result of $ZPOSITION can be used in $EXTRACT to truncate a string so that it fits within a given field. For example, if $ZPO(string,20,2)=15, then $E(string,1,15) will fit in a field that is 20 positions long.

Associated Topics

$ZWIDTH Function

Examples

In the following examples, the symbol · is used to represent a double-byte character.

Setup	Value of Function
$ZPOSITION("",5,2)	0
$ZPO(" · abcde",20,2)	8
$ZPO(" · abcde",8,1.25)	7.25
$ZPO(" · abcde",8,1.5)	6.5
$ZPO(" · abcde",8,2)	5
$ZPO(" · ",7,1.25)	5.6
$ZPO(" · ",7,1.5)	4.6666666666666666
$ZPO(" · ",7,2)	3.5


$ZPREVIOUS

Identifies the previous subscript, in collating sequence, for a specified subscripted variable.

Syntax

$ZP{REVIOUS}(Variable)

Definition

Variable	An expression that evaluates to a subscripted local or global variable name.
The $ZPREVIOUS function is used to identify the previous subscript in sequence at a given level. The Variable name that is specified as an argument to the function can be subscripted, and naked references are allowed. For the right-most subscript in the Variable, the system returns the subscript value that precedes it. If no subscript precedes it, the function returns a null value. If the right-most subscript in the reference is a null value, then the system returns the value of the last subscript at that level. This function is identical to the $ORDER function with a second operand of -1 and is provided only for compatibility with other M implementations.

Associated Topics

Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZNEXT Function
$ZORDER Function
$ZSORT Function

Examples

Setup	Value of Function
SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3	$ZPREVIOUS(^)=last global $ZP(^A(""))="4" last node $ZP(^A(4))="2" next to last node $ZP(^A(2))="1" first node $ZP(^A(1))="" no descendants $ZP(^A(1,""))="2" second-node level $ZP(^A(1,2,""))="3" third level $ZP(^A(1,2,3,""))="" no fourth level


$ZSORT

Identifies the next subscript, in collating sequence, for a specified subscripted variable.

Syntax

$ZS{ORT}(Variable{,Direction})

Definition

Variable	An expression that evaluates to a local or global variable name.
Direction	An expression that evaluates to either 1 or -1.
The $ZSORT function is used to identify the next or previous subscript in sequence at a given level. The Variable name that is specified as an argument to the function must be subscripted, and naked references are allowed. If Direction is not specified or has a value of 1, then for the right-most subscript in the Variable, the system returns the next subscript value that follows it. If no subscript follows it, the function returns a null value. If the right-most subscript in the reference is a null value, the system returns the value of the first or last subscript at that level, depending on the value of Direction. If Direction is specified and evaluates to -1, the function returns the previous subscript for the variable. If Direction is specified and has any value other than 1 or -1, an error condition occurs.

The $ZSORT function returns the subscripts in the collating sequence defined for the global (string or numeric sequence). For local variables, the subscripts are always returned in string-collating sequence. The $ORDER function is identical to $ZSORT, except that for local variables, it returns the subscripts in numeric-collating sequence.

Associated Topics

Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZNEXT Function
$ZORDER Function

Examples

Setup	Value of Function
SET ^A(-1)=0,^A(1,2,3)=1, ^A(2)=2,^A(4)=3	$ZSORT(^)=first global $ZS(^A(""))=-1 first node $ZS(^A(-1))=1 second node $ZS(^A(1))=2 third node $ZS(^A(2))=4 fourth node $ZS(^A(4))="" no descendants $ZS(^A(1,""))=2 second-node level $ZS(^A(1,2,"")=3 third-node level $ZS(^A(1,2,3,""))="" no fourth level $ZS(^A(4),-1)=2 previous node


$ZUCI

Returns the user class identifier (UCI) internal number or external name.

Syntax

$ZU{CI}(UCIName{,VolName})

$ZU{CI}(UCINum{,VolNum})

Definition

UCIName	A string expression that is an external UCI name.
VolName	A string expression that specifies a three-character volume group name.
UCINum	A numeric expression that is an internal UCI number.
VolNum	A numeric expression that specifies an internal volume-group number.
In the first form, the $ZUCI function returns the internal reference number of the specified user-class identifier, followed by the internal reference number of the volume group containing the UCI. These fields are separated by a comma. If the VolName is passed to the function, that volume group is searched for the specified UCI; otherwise, the current volume group is searched. If the UCIName or the VolName is invalid or does not exist, the function returns the null string. If the UCIName is null, the current UCI is used.

In the second form, the $ZUCI function returns the external name of the specified UCI number followed by the external name of the volume group that contains the UCI. These fields are separated by a comma. If a VolNum is passed to the function, that volume group is searched for the specified UCI. Otherwise, the current volume group is searched. If the UCINum or the VolNum is invalid or does not exist, the function returns a null ("") value. If the UCINum is 0, then the current UCI is returned. If the UCINum is equal to the null string, then the numeric form of the current UCI is returned.

Associated Topics

Using Peripheral Devices, MSM User's Guide

Examples

Setup	Value of Function
$ZUCI(1)="MGR,SYS"	Returns the external name.
$ZU("MGR")="1,0"	Returns the internal number.
$ZU(0)="FMR,SYS"	Returns the external name of the current UCI.
$ZU("")="2,0"	Returns the internal number of the current UCI.


$ZVERIFY

Returns a string of errors, if any exist, in the logical structure of the database.

Syntax

$ZV{ERIFY}(Block{,Count{,VolNum}})

Definition

Block	An integer expression that indicates the starting disk block number.
Count	An integer expression that specifies the maximum number of errors to be reported.
VolNum	An integer expression that specifies an internal volume group number.
The $ZVERIFY function returns a string that contains a list of errors, if any, that exist within the MSM database. The Block argument indicates the disk block number where the verify operation is to begin. The function starts with the specified Block and verifies the internal structure and integrity of the Block and all descendants of the Block. If an error is detected, a string is returned that contains information about the error. This string is in the following form:

ErrCode,BlockNum,Offset

In the error string, ErrCode is an integer number that identifies the type of error; BlockNum is the block number of the error; and Offset is the offset into the block where the error was found. The Count argument is used to specify the maximum number of errors that are to be returned by the function. Any integer value can be specified. When multiple errors are returned, they are separated from each other by a circumflex ( ^ ). If the Count is omitted, a value of 1 is assumed.

The VolNum argument is used to specify the volume group that contains the Block that is to be verified. If this argument is omitted, the current volume group is assumed.

Considerations

The BlockNum returned by the function contains the entire path to the bad block. The format of BlockNum is #1:#2:#3:...:#n where #2 is the parent of #1, #3 is the parent of #2, and so on.

Associated Topics

%ERRCODE Utility
VALIDATE Utility
BLKDMP Utility

Examples

Setup	Value of Function
$ZVERIFY(2)=""	The manager's global directory is verified and no errors are found.
$ZV(2)="30,27,233"	The manager's global directory is verified and block 27 is found to have an error (keys not in ascending order) at offset 233 in the block.
$ZV(2,99)="30,27,233^ ...	The manager's global directory is verified and multiple errors are found.
$ZV(5000,100,4)=""	Block number 5000 in Volume Group 4 and all of its descendants are verified and no errors are found.
$ZV($ZBN(^CUST))=""	The ^CUST global is verified and no errors are found. This syntax does not have the desired result if the ^CUST global is translated.


$ZWIDTH

Returns the width that a string occupies when it is displayed on an output device.

Note  This function applies only to double-byte or wide character sets.

Syntax

$ZW{IDTH}(String{,Width})

Definition

String	Any string-type expression.
Width	An expression that specifies the relative width of a double-byte character compared to a single-byte character.
The $ZWIDTH function is used to calculate the number of character positions that a string occupies when it is displayed on a specific output device. A single-byte character is assumed to occupy one position on the output device. The Width argument specifies how many positions a double-byte character occupies on the output device. If Width is omitted, it is assumed to be two.

If n1 is the number of double-byte characters in String and n2 is the number of single-byte characters in String, then $ZWIDTH(String,Width)=n1*Width+n2.

Associated Topics

$ZPOSITION Function

Examples

In the following examples, the symbol · is used to represent a double-byte character.

Setup	Value of Function
$ZWIDTH("",2)	0
$ZW(" · abcde",1.25)	8.75
$ZW(" · abcde",1.5)	9.5
$ZW(" · abcde",2)	11
$ZW(" · abcd",2)	10


MSM Special Variables - Overview
Overview

The M language provides special variables that are maintained by MSM and can be accessed by the programmer. These special variables are designed to provide feedback information to executing programs as they interact with the system and specify system behavior. These variables can be examined by the program using M commands, and based on their values, decisions can be made within the program.

MSM provides all of the ANSI-standard special variables and an extended set of special variables that are specific to MSM. The ANSI-standard special variables begin with a dollar sign ($) followed by the letters A through Y, and the MSM-specific special variables begin with a dollar sign and the letter Z. Special variable names be spelled out or can be abbreviated as specified by the ANSI standard. Special variable names can be specified in uppercase, lowercase, or a combination of uppercase and lowercase. For example, the following are all valid abbreviations:

$STORAGE

$SToRAge

$S

$s

The following sections describe the special variables provided in the MSM system. For additional information about device-specific special variables, refer to "Using Peripheral Devices," in the MSM User's Guide.


$DEVICE

Contains a value that indicates if the last input/output (I/O) operation was successful.

Syntax

$D{EVICE}

Definition

The $DEVICE special variable contains a string that indicates whether the last device handling mnemonic input/output operation was successful. The string value of $DEVICE is in the following format:

MDC#,Implementor#,Descriptive Text

The MDC# is a value defined by the M Development Committee in an effort to standardize error conditions. The Implementor# is defined by Micronetics to further describe the nature of an error. The Descriptive Text is a brief description of the error that occurred. Refer to the information on mnemonic namespaces in "Using Peripheral Devices" in the MSM User's Guide for a list of the MDC# errors and the Implementor# errors.

Considerations

The value of $DEVICE, when interpreted as a truth value, is equal to zero if the operation is successful. A non-zero value indicates that the operation failed. This special variable has meaning only for devices that are associated with a mnemonic namespace.

Associated Topics

WRITE Command
Using Peripheral Devices, MSM User's Guide

Examples

This example attempts to move the cursor to the specified location and QUITs if the operation is not successful:

USE 5::"X3.64-1979" W /CUP(4,24) Q:$DEVICE


$ECODE

Contains a list of error codes encountered by the application.

Syntax

$EC{ODE}

Definition

The $ECODE special variable contains a string that identifies the errors encountered by the application. The string value of $ECODE is in the following format:

,ErrorCode1,ErrorCode2, ... ,

Note that a comma precedes and follows each error code. Error codes are in one of the following formats:

Mnn	where nn is an integer specified by the ANSI standard
Uxx	where xx is any user-defined string not containing a comma
Zxx	where xx is defined by the version of MSM (MSM-specific)

The M values are integer numbers specified by the 1994 ANSI M standard (and subsequent Type A amendments) issued by the M Development Committee in an attempt to standardize error conditions.

The U values are any user-defined strings that do not contain a comma. These are typically application-specific error codes managed by application-specific error handling routines that examine the value of $ECODE.

The Z values are implementation-specific error codes. For MSM, they are the same values that are assigned by MSM to the $ZERROR special system variable.

Refer to "Error Processing" in this manual for a list of the ANSI M error numbers and MSM-specific error codes.

Considerations

When the value of $ECODE is the empty string, normal routine execution rules are in effect.

Error processing is initiated when:

•	$ECODE transitions from an empty to a non-empty string. The value of $ECODE may change implicitly when MSM detects an error condition (such as an undefined variable), or when explicitly SET by the application.

•	A QUIT returns from an execution level with $ECODE non-empty to a level in which no error had occurred. For example, $STACK(new level,"ECODE") is the empty string.

•	When the value of $ECODE is changed via the SET command, the new value replaces the existing value. The replacement value must be in the correct format as described above; otherwise, an error occurs.

•	When a partition is initiated, $ECODE has the value of the empty string.

Associated Topics

QUIT Command
SET Command
$ETRAP Special Variable
$STACK Function
Error Processing

Examples

This code displays the individual error codes in $ECODE on individual lines:

FOR I=2:1:$L($ECODE,",")-1 WRITE !,$P($ECODE,",",I)!,$P($ECODE,",",I)

This command might display the following, which would result from an attempted division by zero:

WRITE $ECODE

,M9,Z<DIVER>*XECUTE*:::5:2:,


$ESTACK

Indicates the relative execution nesting level.

Syntax

$ES{TACK}

Definition

The $ESTACK special variable contains a non-negative integer specifying the relative nesting of the current execution level. The value is automatically incremented by the DO and XECUTE commands, and automatically decremented by the QUIT command. The NEW command may be used to stack the current value and reset $ESTACK to 0. A QUIT command (explicitly or implicitly at the end of a routine or an XECUTE string) restores the stacked value. A new partition begins with $ESTACK set to 0.

Refer to the MSM User's Guide for additional information.

Considerations

An application may stack the value of $ESTACK and reset it to 0 via the NEW command. Subsequent error handling routines may "pop" the execution levels until $ESTACK returns to 0, at which point execution returns to its initial starting level for the application. This is useful for nested applications. If $ESTACK is not stacked by the NEW command, it always equals $STACK.

Associated Topics

DO Command
JOB Command
NEW Command
SET Command
XECUTE Command
$STACK Special Variable
Using the MSM System, MSM User's Guide

Examples

This command pops the current execution level as long as $ESTACK is positive. Note that if $ECODE has not been reset to the empty string, returning from an execution level with $ECODE not null automatically invokes error handling for the returned-to execution level:

QUIT:$ES>0

This command stacks the current $ESTACK value; resets the current value of $ESTACK to zero; defines the error handling string; and invokes the application:

NEW $ESTACK SET $ETRAP="D ERROR^ROUTINE" DO APPL


$ETRAP

Specifies the string to be executed when an error condition is detected.

Syntax

$ET{RAP}

Definition

The $ETRAP special variable contains a string of M code to be executed when an error condition is detected. The code is executed at the same execution level at which the error occurs. Prior to execution of the string in $ETRAP, any active FOR loops and indirections in the current execution level are terminated. Execution behaves as if the contents of $ETRAP are appended to the current routine with a temporary but unique label, and an internal GOTO to the appended code is performed. Updating $ETRAP replaces its previous value.

The current value of $ETRAP can be stacked using the NEW command. The NEW command does not alter the value of $ETRAP; it merely stacks it. New partitions begin with $ETRAP set to the empty string. When $ETRAP is SET, the value of $ZTRAP also is reset to the empty string so that at any time, either $ETRAP or $ZTRAP defines the error handling environment, but not both.

Refer to the MSM User's Guide for additional information.

Considerations

Within an application, the NEW command can be used to stack the caller's $ETRAP until a QUIT command (implicit or explicit) is executed at the current execution level.

Unlike $ZTRAP, the value of $ETRAP is not tied to an execution level unless the NEW command is used. Therefore, the application can set $ETRAP at the start of the application. The same $ETRAP value is used at each nested level if an error condition is detected. When initiating error processing, MSM performs an explicit GOTO (without changing the execution level) to the following two lines of code.

...value of $ETRAP...
QUIT:$QUIT ""   QUIT

Associated Topics

DO Command
JOB Command
NEW Command
SET Command
XECUTE Command
$STACK Function
$ECODE Special Variables
$ZTRAP Special Variables
Using the MSM System, MSM User's Guide

Examples

This example stacks the current value in $ETRAP and establishes a new string to be executed if an error condition is detected.

NEW $ETRAP SET $ETRAP="D ERR^ROUTINE"


$HOROLOG

Contains the current date and time as integer values separated by a comma.

Syntax

$H{OROLOG}

Definition

The $HOROLOG special variable contains the current date and time in the following format.

Date,Time

The Date is the number of days since December 31, 1840, and the Time is the number of seconds since midnight. The Time may range from a value of 0 (midnight) to 86399 (11:59:59 PM).

Considerations

At midnight, the MSM system automatically increments the Date portion by one and resets the Time portion to 0.

Associated Topics

$ZDATE Function

Examples

The following converts $H to an external date such as 14-MAY-90:

%D	;BPS;CONVERTS $H TO DD-MMM-YY;
;COPYRIGHT MICRONETICS DESIGN CORP. @1990
S %H=+$H,%H=%H>21914+%H
S %LY=%H\1461,%R=%H#1461,%Y=%LY*4+1841+(%R\365),%D
..........=%R#365,%M=1
I %R=1460,%LY'=14 S %D=365,%Y=%Y-1
F %I=31,(%R>1154)&(%LY'=14)+28,31,30,31,30,31,31,3
..........0,31,30 Q:%I'<%D S %M=%M+1,%D=%D-%I
I %D=0 S %Y=%Y-1,%M=12,%D=31
S %DAT1=%D_"-"_$P("JAN FEB MAR APR MAY JUN JUL AUG
..........SEP OCT NOV DEC"," ",%M)_"-"_$E(%Y,3,4)
S %DAT=%M_"/"_%D_"/"_%Y
K %D,%H,%I,%LY,%M,%R,%Y,%NP Q

The following converts $H to an external time such as 3:42 PM:

%T	;DJM;FORMAT CURRENT TIME;
;COPYRIGHT MICRONETICS DESIGN CORP. @1984
S %M=$P($H,",",2)\60
S %TIM=%M\60_":"_(%M#60\10)_(%M#10)
S %N=" AM" S:%M'<720 %M=%M-720,%N=" PM" S:%M<60 %M
..........=%M+720
S %I=%M\600 S:'%I %I=" " S %TIM1=%I_(%M\60#10)_":"
.........._(%M#60\10)_(%M#10)_ %N
I '$D(%NP) W %TIM1 K %TIM,%TIM1
K %M,%N,%I,%NP Q


$IO

Contains the device number of the current I/O device.

Syntax

$I{O}

Definition

The $IO special variable contains the device number (designator) of the current device for the job. The value of $IO is uniquely identified for the current input/output device. The current input/output device is the device most recently referenced with the USE command. If a USE command has not been issued, the current device number corresponds to the principal device number (the device number assigned to the job when it logged onto MSM).

Associated Topics

OPEN Command
CLOSE Command
USE Command
ZUSE Command
$PRINCIPAL Special Variable

Examples

The local variable X is assigned a value of 3:

USE 3 S X=$I

 It is a common practice in some applications to store device-specific information using $I as an index because it is unique for each device:

S ^A($I,1)=X


$JOB

Contains the job number of the job that is currently executing.

Syntax

$J{OB}

Definition

The $JOB special variable contains the job number of the current job. When a user logs on to MSM, a job is created and a unique integer number is assigned to the job. In addition, whenever a job is started with the JOB command, a unique job number is assigned to the newly created job.

Associated Topics

JOB Command

Examples

It is a common practice to store application global data that is only needed for a short time in a "temporary" global, using $JOB as the first index:

S ^A($J,1)=X

Output from a job can be identified by printing the job number with the output:

WRITE #,DATE," ",$J


$KEY

Contains the control sequence that terminated the last READ command from the current device.

Syntax

$K{EY}

Definition

The $KEY special variable contains the sequence of control characters that terminated the last READ command from the current device. Before the first READ is issued to a device or when the READ terminates without receiving a terminator character (for example, as a result of a timeout, a fixed-length READ, or a single-character READ operation), the value of $KEY is the null string (empty). Otherwise, it is one of the control characters that can be specified in MSM as a READ terminator. When escape processing is enabled for terminal devices, $KEY can contain a string of characters, usually generated by a function key, which terminated the READ.

Considerations

This special variable has meaning only for devices that are associated with a mnemonic namespace.

Associated Topics

READ Command
USE Command
Using Peripheral Devices, MSM User's Guide

Examples

This example moves the cursor to the specified location; READs a value into variable X; and QUITs if the operation was not terminated by the RETURN key:

USE 5::"X3.64-1979" W /CUP(4,24) R X Q:$KEY'=$C(13)

When escape processing is turned on by the USE command, $KEY can contain a string of characters:

U $I:(::::64) R X GOTO:$KEY=($C(27)_"[A") UPARROW


$PRINCIPAL

Contains the number of the job's principal device.

Syntax

$P{RINCIPAL}

Definition

The $PRINCIPAL special variable contains the number of the device that was the principal device at the instant that the job was started. In other words, $PRINCIPAL is equal to the initial value of the $IO special variable.

In the case of a job that was created as a result of a user logging into MSM, it is the number of the device that initiated the logon. For a job created as a result of the JOB command, it is the device number of the principal device associated with the job that issued the command.

Considerations

The $PRINCIPAL special variable supersedes the old convention in MSM in which a USE 0 command indicates the principal device. This construct should be replaced with a USE $PRINCIPAL statement to ensure portability.

Associated Topics

JOB Command
$IO Special Variable

Examples

This example makes the initial device for the job (the principal device) the current device:

USE $PRINCIPAL

This example closes the current device if it is not the principal device:

C:$I'=$P $I


$QUIT

Contains a value that indicates whether an argument is required on a QUIT.

Syntax

$Q{UIT}

Definition

The $QUIT special variable indicates if an argument is required on a QUIT.  $QUIT returns 1 if the current execution level was invoked as an extrinsic and a QUIT therefore requires a value.  Otherwise, $QUIT returns 0. $QUIT is initialized to 0 when a process is started.

Associated Topics

Extrinsic Functions
Parameter Passing
$ECODE Special Variable
$ESTACK Special Variable
$ETRAP Special Variable
$QUIT Special Variable
$STACK Special Variable
$STACK Function

Examples

In the following  routine, error recovery is simplified by using the $QUIT variable. If an error occurs within the extrinsic function, the function can be terminated properly with a QUIT argument, depending on the value of $QUIT. This feature enables the user to avoid placing a second error trap within the extrinsic function.

TEST	;$QUIT example
SET $ETRAP="DO ER^TEST"
READ !,"Enter name: ",A
SET A=$$STRIP(A) Q:A=-1
A	READ !,"Enter phone number: ",B
IF B'?4.20NP WRITE *7 GOTO A
QUIT
STRIP(A)	; strip spaces at either end
FOR  QUIT:$ASCII(A)'=32  SET $EXTRACT(A)=""
FOR  QUIT:$A(A,$LENGTH(A))'=32  S $E(A,$L(A))=""
QUIT A
ER	W !,"Error: ",$ECODE S $ECODE=""
QUIT:$QUIT -1 ; end of extrinsic function
QUIT


MSM Special Variables - $STACK
$STACK

Indicates the current (absolute) execution nesting level.

Syntax

$ST{ACK}

Definition

The $STACK special variable contains a non-negative integer that specifies the absolute nesting of the current execution level. The value is automatically incremented by the DO and XECUTE commands and is automatically decremented by the QUIT command. A new partition begins with $STACK set to zero.

Refer to the MSM User's Guide for additional information.

Considerations

$STACK differs from $ESTACK in that the value is read-only and cannot be SET by the application, nor can it be stacked by using the NEW command. $STACK reflects the actual nesting level of the DO and XECUTE commands for the entire partition. $ESTACK reflects a relative nesting level because it is reset by the NEW command. If $ESTACK is not stacked by the NEW command, it always equals $STACK.

Associated Topics

DO Command
JOB Command
SET Command
XECUTE Command
$STACK Function
$ESTACK Special Variable
Using the MSM System, MSM User's Guide

Examples

This example displays the error code generated at the current execution level. It also displays the last line to generate an error in the current execution level:

WRITE !,$STACK($STACK,"ECODE"),!,$STACK($STACK,"MCODE")


$STORAGE

Contains a value equal to the number of bytes of memory remaining in the partition.

Syntax

$S{TORAGE}

Definition

Each job is assigned a partition that is a specified size. The space within the partition is used for the local symbol table of the job and the text of the routine, if any, that is currently loaded into the partition through use of the ZLOAD or ZINSERT commands. The $STORAGE special variable contains a decimal value, in bytes, that represents the amount of space left in the partition after subtracting the size of the local symbol table and the size of the routine text currently loaded into the partition.

Considerations

Refer to the MSM User's Guide for additional information on partition size.

Associated Topics

JOB Command
ZINSERT Command
ZLOAD Command
ZREMOVE Command
Variables

Examples

If the value of the $STORAGE variable falls below a specified minimum, then the FILETEMP routine is invoked to temporarily file information in the partition:

I $S<MINSIZE G ^FILETEMP

If the value of the $STORAGE variable falls below 1000 bytes, then the %PARTSIZ routine is invoked to increase the partition size:

IF $S<1000 SET %K=PSIZE+2 D INT^%PARTSIZEINT^%PARTSIZE


$SYSTEM

Contains an M User's Group-assigned vendor identification number and a Micronetics-assigned identifier.

Syntax

$SY{STEM}

Definition

The $SYSTEM special variable contains information that distinguishes in a unique manner the current MSM system from all other MSM and non-MSM systems. The $SYSTEM special variable contains two pieces separated by a comma. The first piece is the Micronetics vendor identification number assigned by the M User's Group. It will always be the value 43.

The second piece contains two numbers separated by a semicolon. The first number is the serial number from the current MSM license. The second number is a unique identifier for the current instance of MSM. This provides a unique value for $SYSTEM when two workstation clients using the same license information connect to a common server.

This special variable is formatted in such a way that it can be used directly as a subscript in a local or global variable. When used in conjunction with the $JOB special variable, network-unique nodes can be generated.

Associated Topics

Variables

Examples

This example writes the contents of $SYSTEM to the current device:

WRITE $SYSTEM
43,1001234;176034223

Temporary global nodes can be set up with data stored by the SYSTEM identifier and the JOB number:

S ^UTILITY($SY,$J)=X


$TEST

Contains the truth value of the most recently executed IF command or timeout.

Syntax

$T{EST}

Definition

The $TEST special variable contains a truth value that is either 0 (false) or 1 (true). $TEST is set by execution of an IF command with an argument, or by an OPEN, LOCK, JOB, READ, or ZALLOCATE command with a timeout. For the IF command, if the argument of IF generates a true value, then $TEST is set to true; otherwise, it is set to false. For timeouts, if the requested operation is completed before the timeout, $TEST is set to true; otherwise, it is set to false. For the JOB command, $TEST is set to true if the job was successfully started within the timeout period; otherwise, it is set to false.

Considerations

Execution of a post-conditional expression on a command does not set the $TEST special variable.

Associated Topics

ELSE Command
IF Command
JOB Command
LOCK Command
OPEN Command
READ Command
ZALLOCATE Command
Post-Conditionals Timeouts

Examples

This code:

I X=3 S Y=A
W:$T Y S Y=B

is equivalent to the following:

I X=3 S Y=A
I X=3 W Y
S Y=B

In this example, $T is used to test whether the input was explicitly terminated before the timeout expired. If there was no termination (if the input string is incomplete), execution continues at A:

R X:100 G A:'$T DO B

This is a similar example. If the OPEN is unsuccessful, execution transfers to label A. Otherwise, output is written to device 3:

O 3::10 G A:'$T U 3 W X


$TLEVEL

Indicates whether or not a transaction is currently in progress.

Syntax

$TL{EVEL}

Definition

The $TLEVEL special variable indicates whether or not a transaction is currently in progress. This variable is initialized to 0 when the job (process) is started. A value of 0 indicates that no transaction is in progress for the job. Any other value indicates that a transaction is in progress.

Whenever a TSTART command is performed, the system adds one to the current value of the $TLEVEL variable. Whenever a TCOMMIT command is performed and the value of $TLEVEL is greater then 0, the system subtracts one from the value of the $TLEVEL variable. Whenever a TROLLBACK command or transaction restart (an explicit TRESTART command or a system-initiated restart) is performed, the value of the $TLEVEL variable is set to 0.

Associated Topics

TCOMMIT Command
TRESTART Command
TROLLBACK Command
TSTART Command
$TRESTART Special Variable

Examples

This example writes the number of TSTART commands processed since the last TCOMMIT or transaction restart:

W $TLEVEL
4


$TRESTART

Indicates the number of transaction restarts that have occurred since the initiation of the transaction.

Syntax

$TR{ESTART}

Definition

The $TRESTART special variable contains a count of the number of transaction restarts that have occurred during the transaction. The restarts can be explicit (a TRESTART command) or implicit (a system-initiated restart). A value of 0 indicates that no restarts have occurred. Any other positive value indicates restarts have occurred. This variable is initialized to 0 when the job (process) is started. It is also set to 0 by the successful completion of the TCOMMIT or TROLLBACK command. During the transaction, each transaction restart adds one to the value of the $TRESTART variable.

Associated Topics

TCOMMIT Command
TRESTART Command
TROLLBACK Command
TSTART Command
$TLEVEL Special Variable

Examples

This example writes the number of transaction restarts that have occurred during the transaction:

W $TRESTART
3


$X

Contains the decimal value of the next output column for the current device.

Syntax

$X

Definition

The $X special variable is used to keep track of the X-coordinate of the last character output to the current device. The values may range from 0 to 255. Whenever a carriage return (the ! format character, the # format character, $C(13), or *13) is encountered, the value of $X is reset to 0. In addition, when the value is incremented beyond 255, it is reset to 0. The ?Val format sequence (horizontal tab) sets $X to the specified tab location (Val) if it is greater than the current value of $X. Otherwise, the value of $X remains unchanged. The value of $X may be changed by the user with a SET command.

Associated Topics

Format Characters

Examples

Y is given the value 3:

W !,"123" S Y=$X

Y is given the value 0:

W # S Y=$X

This code writes a carriage return and then line feeds if $X indicates that the next output character would be to the right of column 72:

W:$X>72 !

This code assigns a new value to $X:

S $X=27


$Y

Contains the decimal value of the next output row for the current device.

Syntax

$Y

Definition

The $Y special variable is used to keep track of the Y-coordinate of the last character output to the current device. The values may range from 0 to 255. Whenever a line feed (the ! format character, $C(10), or *10) is encountered, the value of $Y is incremented by one ($Y=$Y+1). On form-feed characters (the # format character, $C(12), or *12), the value of $Y is reset to 0. In addition, when the value is incremented beyond 255, it is reset to 0. Use the SET command to change the value of $Y.

Associated Topics

Format Characters

Examples

Y is given the value 0:

W # S Y=$Y

Y is given the value 3:

W #!!! S Y=$Y

This code writes a form feed, which includes a carriage return, if $Y indicates that the next output character would be below row 56 of the page:

W:$Y>56 #

This code assigns a new value to $Y:

S $Y=31


$ZA

Contains device-specific information for the current device.

Syntax

$ZA

Definition

The $ZA special variable contains an integer value that relates to error conditions, status indicators, and so on, for the current device.

Associated Topics

OPEN Command
USE Command

Examples

The HFS device is made the current device, and one record is read from the device. The status information associated with the READ operation is saved in the RC local variable:

U 51 R X S RC=$ZA RC=$ZA


$ZB

Contains device-specific information for the current device.

Syntax

$ZB

Definition

The $ZB special variable contains an integer value that relates to error conditions, status indicators, and so on, for the current device.

Associated Topics

OPEN Command
USE Command

Examples

The HFS device is made the current device, and one record is read from the device. The status information associated with the READ operation is saved in the RC local variable:

U 51 R X S RC=$ZB


$ZC

Contains device-specific information for the current device.

Syntax

$ZC

Definition

The $ZC special variable contains an integer value that relates to error conditions, status indicators, and so on, for the current device. Generally, a non-zero value indicates an error condition.

Associated Topics

OPEN Command
USE Command

Examples

The HFS device is made the current device, and one record is read from the device. The status information associated with the READ operation is saved in the RC local variable:

U 51 R X S RC=$ZC


$ZERROR

Contains the text of the error message most recently produced by the MSM system.

Syntax

$ZE{RROR}

Definition

The $ZERROR special variable contains the error message most recently issued by the MSM system. The message is in the format <ErrMsg> Detail. The ErrMsg portion is a five-character abbreviation for the error, and Detail is the detailed information about the error.

This variable is most commonly used in conjunction with the $ZTRAP variable to determine what type of condition caused the error trap to be entered. For additional information on error trapping and error messages, refer to the $ZTRAP special variable, and to "Error Processing" in this manual.

Associated Topics

$ECODE Special Variable
$ETRAP Special Variable
$ZTRAP Special Variable
Error Processing

Examples

This example writes out the current value of the $ZE variable. In this case, it indicates an <UNDEF> error in the CUSINQ routine (the 4:1 indicates that a reference was made to an undefined global):

W $ZE
<UNDEF>+17^CUSINQ:::4:1


$ZLEVEL

Contains a number that indicates the current nesting level.

Syntax

$ZL{EVEL}

Definition

The $ZLEVEL special variable contains a value that indicates the current nesting level. The value is initialized to 0 when the partition is created, and it is incremented each time a DO, FOR, or XECUTE command is processed. Each time an implicit or explicit QUIT command is processed, the value is decremented.

Note that the initial value of the variable can be different depending on the mode in which the user is operating and how the routine was entered. For example, when operating in direct mode, this variable has an initial value of 1. When the routine that is executing is entered as a result of a tied-terminal entry, this variable has an initial value of 2.

Associated Topics

DO Command
FOR Command
QUIT Command
XECUTE Command
Using the MSM System, MSM User's Guide
Configuring the System, MSM User's Guide

Examples

This example writes the number associated with the current nesting level:

W $ZLEVEL
4


$ZNAME

Contains the name of the routine currently loaded into memory.

Syntax

$ZN{AME}

Definition

The $ZNAME special variable contains the name of the routine that is currently loaded into the partition. The $ZNAME variable is equivalent to $TEXT(+0). If the routine currently loaded into the partition is unnamed or if there is no routine loaded into the partition, then $ZNAME contains a null value.

Associated Topics

DO Command
$TEXT Function
ZLOAD Command
ZREMOVE Command

Examples

This example writes the name of the routine that is currently loaded into the partition:

W $ZN
TESTPGM

This example writes the null string to the current device:

ZR   W $ZN


MSM Special Variables - $ZORDER
$ZORDER

Returns the data value of the next global node in sequence after the last global reference.

Syntax

$ZO{RDER}

Definition

The system maintains the fully qualified name (UCI, volume group, global name, and subscripts) of the last global referenced in the $ZREFERENCE special variable. The $ZORDER special variable returns the data value of the next global node that follows this last global reference in collating sequence. Accessing the $ZORDER variable is equivalent to the following statement:

S DATA=@($ZORDER(@$ZREFERENCE))

In the case where the last global reference is to the last defined node of a global, then the above reference results in an <UNDEF> error.

Associated Topics

$NEXT Function
$ORDER Function
$ZREFERENCE Special Variable

Examples

This example writes the data value 3 (the data value of the node that follows the last global reference that was made):

S ^X(1,1)=1,^X(1,2)=2,^X(1,3)=3
S X=^X(1,2)
W $ZORDER


$ZREFERENCE

Contains the full global reference, including name and subscripts of the last global referenced.

Syntax

$ZR{EFERENCE}

Definition

The $ZREFERENCE special variable contains the full global name (the global name and the subscripts) of the last global referenced or the extended global name (the UCI name and the volume group name in brackets followed by the global name and subscripts) if the global referenced is in a different UCI or in a different volume group. For additional information on referencing globals in a different UCI or volume group, refer to the MSM User's Guide.

Associated Topics

Global Variables

Examples

This example first sets a node in the CUS global and then writes out the value of $ZR. The global reference for the node that was accessed is displayed:

S ^CUS(1,2,3)="JONES^JOHN" W $ZR
^CUS(1,2,3)

This example first sets a node in the CUS global in the PRD UCI on the VGA volume group and then writes out the value of $ZR. The global reference for the accessed node is displayed, including UCI and volume group name:

S ^|"PRD","VGA"|CUS(1,2,3)="JONES^JOHN" W $ZR
^|"PRD,VGA"|CUS(1,2,3)


$ZTRAP

Contains the line label and the routine name of the program to receive control when an error occurs.

Syntax

$ZT{RAP}

Definition

The $ZTRAP special variable is used to set a trap that is invoked when an error condition occurs. The trap can be specified as a line label (ERROR), a routine name (^%ET), or a line label and routine name (ERR^MYPROG). Whenever an error occurs, execution automatically returns from any nested DO or XECUTE commands (which have not specified any error handling) and then a GOTO command is issued with the $ZTRAP variable as the argument. Indirection may be used in the trap specification.

Upon entry to the trap routine, the $ZTRAP special variable is set to the empty string, the $ZERROR special variable contains information about the error; and $ECODE is set to the empty string. Refer to the MSM User's Guide for additional information on trapping errors.

Considerations

When the error trap routine or label is invoked, the $ZTRAP variable is set to null. It is the responsibility of the error trap routine to re-establish the trap if appropriate.

One $ZTRAP special variable can be set at each execution level. This means that each execution level in an application can establish its own error trapping routine and error recovery procedures.

Setting $ZTRAP also performs the following action:

NEW $ETRAP SET $ETRAP=""

This is done to ensure that either $ZTRAP or $ETRAP, but not both, is used to trap the error condition.

Associated Topics

$ECODE Special Variable
$ETRAP Special Variable
$ZERROR Special Variable
Block Structured Subroutines
ZQUIT Command
ZTRAP Command
Error Processing

Examples

If an error is encountered, control is passed to the %ET routine:

S $ZTRAP="^%ET"

This example passes control to the ERR label of the MYPROG routine if an error is encountered:

S $ZT="ERR^MYPROG"

This examples disables error trapping:

S $ZT=""


$ZVERSION

Contains the name and release number of the MSM software in use.

Syntax

$ZV{ERSION}

Definition

The $ZVERSION special variable contains the name of the MSM system being used (for example:  MSM-PC/PLUS, MSM-UNIX) and the release number of the software (for example, Version 4.4.0).

Considerations

The $ZVERSION variable can be used to test the system type if the software contains implementation-specific or release-specific features of MSM.

Examples

This example prints the name and version number of the MSM system that is in use:

W $ZV
MSM-PC/PLUS, Version 4.4.0


MSM Structured System Variables - Overview
Overview

This chapter describes the ANSI-standard M structured system variables (SSVNs), and the additional vendor-specific structured system variables that exist in the MSM implementation of M.

The M language includes a number of structured system variables that are maintained by MSM and can be accessed by the programmer. The SSVNs are designed to provide information on various system resources. After these variables are examined by a program, decisions can be made within the program based on their values.

In MSM, all of the ANSI-standard structured system variables are provided, as are an extended set of structured system variables specific to MSM. The ANSI-standard structured system variables begin with ^$ (^ followed by a dollar sign) followed by the letters A through Y. No MSM-specific SSVNs currently are defined. SSVNs can be abbreviated or fully spelled out, and SSVN names can be specified in uppercase, lowercase, or a combination of uppercase and lowercase alpha characters. For example, all of the following are equivalent and valid abbreviations:

^$ROUTINE

^$routine

^$R

^$r

The following sections describe the structured system variables provided in the MSM system, including syntax, a description of the value, special considerations, associated topics, and examples. For additional information about writing M programs, refer to the MSM User's Guide.


^$DEVICE

Provides information on the existence, operational characteristics, and availability of a device.

Syntax

^$D{EVICE}(DeviceNum)

Definition

DeviceNum	An expression that evaluates to a device number.
The $DEVICE structured system variable provides information on the existence, operational characteristics, and availability of a specified device. If the device exists, $DATA of the ^$DEVICE variable returns a value of 10. Otherwise, $DATA returns a value of 0.

Defined Nodes

None

Associated Topics

Using Peripheral Devices, MSM User's Guide

Examples

$DATA(^$DEVICE(3))

This expression tests for the existence of device number 3.

$ORDER(^$D(3))

This expression returns the device number of the next device defined in the system after device number 3.


^$GLOBAL

Provides information on the existence, operational characteristics, and availability of a global.

Syntax

^$G{LOBAL}(GlobalVar)

Definition

GlobalVar	An expression that evaluates to a global variable name.
The $GLOBAL structured system variable provides information on the existence, operational characteristics, and availability of a specified global. If the global exists, $DATA  of the ^$GLOBAL structured system variable returns a value of 10. Otherwise, $DATA returns a value of 0.

Defined Nodes

None

Associated Topics

Global Variables

Examples

$DATA(^$GLOBAL("^A"))

This expression tests for the existence of global ^A (existence is defined as $D(^Global)>0).

$ORDER(^$G("^A"))

This expression returns the name of the global that follows the global named A in the global directory.

SET X=""
FOR  S X=$0(^$G(X)) Q:X=""  WRITE !,X

This code loops through the entire global directory, writing each global name to the current device.


^$JOB

Provides information on the existence and operational characteristics of a process.

Syntax

^$J{OB}(JobNum)

Definition

JobNum	An expression that evaluates to a job number.
The $JOB structured system variable provides information on the existence and operational characteristics of a specified job. If the specified job is active, $DATA  of the ^$JOB structured system variable returns a value of 10. Otherwise, $DATA returns a value of 0.

Defined Nodes

None

Associated Topics

JOB Command

Examples

$DATA(^$JOB(16))

This expression tests to see if job 16 is currently active.

$ORDER(^$J(16))

This expression returns the job number of the next job that is active in the system after job number 16.


^$LOCK

Provides information on the existence and operational characteristics of a locked resource.

Syntax

^$L{OCK}(Variable)

Definition

Variable 	An expression that evaluates to a local or a global variable name.

The $LOCK structured system variable provides information on the existence and operational characteristics of a specified locked resource. If the specified resource has been successfully LOCKed (and not yet unLOCKed), $DATA of the ^$LOCK structured system variable returns a value of 10. Otherwise, $DATA returns a value of 0.

Defined Nodes

None

Associated Topics

LOCK Command
ZALLOCATE Command
ZDEALLOCATE Command

Examples

$DATA(^$LOCK("^A"))

This expression tests to see if the global variable A is currently locked.

$ORDER(^$L("^A"))

This expression returns the name of the next resource that is locked.

$ORDER(^$L("^A"))
SET X=""
FOR  S X=$0(^$L(X)) Q:X=""  WRITE !,X

This code writes the entire contents of the lock table to the current device.


^$ROUTINE

Provides information on the existence, operational characteristics, and availability of a routine.

Syntax

^$R{OUTINE}(RoutineName)

Definition

RoutineName	An expression that evaluates to a routine name.
The $ROUTINE structured system variable provides information on the existence, operational characteristics, and availability of a specified routine. If the routine exists, $DATA  of the ^$ROUTINE structured system variable returns a value of 10. Otherwise, $DATA returns a value of 0.

Defined Nodes

zsdate	Returns the $HOROLOG date/time at which the routine was last ZSAVEd.
Associated Topics

Global Variables
ZSAVE Command
$HOROLOG Special Variable
$ZDATE Function

Examples

$DATA(^$ROUTINE("A"))

This expression tests for the existence of routine A.

$ORDER(^$R("A"))

This expression returns the name of the routine that follows the routine named A in the routine directory.

WRITE $ZDATE(^$R("A","zsdate"))

This expression formats the date last saved for routine A.


ASCII Collating Sequence - Overview
Overview

This appendix provides a list of the ASCII collating sequence values.

ASCII Collating Sequence

Decimal	Symbol	Pattern		Decimal	Symbol	Pattern
0	NULL	C,E		64	@	P,E
1	SOH	C,E		65	A	A,U,E
2	STX	C,E		66	B	A,U,E
3	ETX	C,E		67	C	A,U,E
4	EOT	C,E		68	D	A,U,E
5	ENQ	C,E		69	E	A,U,E
6	ACK	C,E		70	F	A,U,E
7	BELL	C,E		71	G	A,U,E
8	BS	C,E		72	H	A,U,E
9	HT	C,E		73	I	A,U,E
10	LINEFEED	C,E		74	J	A,U,E
11	VERT TAB	C,E		75	K	A,U,E
12	FORMFEED	C,E		76	L	A,U,E
13	RETURN	C,E		77	M	A,U,E
14	SO	C,E		78	N	A,U,E
15	SI	C,E		79	O	A,U,E
16	DLE	C,E		80	P	A,U,E
17	DC1	C,E		81	Q	A,U,E
18	DC2	C,E		82	R	A,U,E
19	DC3	C,E		83	S	A,U,E
20	DC4	C,E		84	T	A,U,E
21	NAK	C,E		85	U	A,U,E
22	SYN	C,E		86	V	A,U,E
23	ETB	C,E		87	W	A,U,E
24	CAN	C,E		88	X	A,U,E
25	EM	C,E		89	Y	A,U,E
26	SUB	C,E		90	Z	A,U,E
27	ESCAPE	C,E		91	[	P,E
28	FS	C,E		92	\	P,E
29	CS	C,E		93	]	P,E
30	RS	C,E		94	^	P,E
31	US	C,E		95	_	P,E
32	SPACE	P,E		96	`	P,E
33	!	P,E		97	a	A,L,E
34	"	P,E		98	b	A,L,E
35	#	P,E		99	c	A,L,E
36	$	P,E		100	d	A,L,E
37	%	P,E		101	e	A,L,E
38	&	P,E		102	f	A,L,E
39	'	P,E		103	g	A,L,E
40	(	P,E		104	h	A,L,E
41	)	P,E		105	i	A,L,E
42	*	P,E		106	j	A,L,E
43	+	P,E		107	k	A,L,E
44	,	P,E		108	l	A,L,E
45	-	P,E		109	m	A,L,E
46	.	P,E		110	n	A,L,E
47	/	P,E		111	o	A,L,E
48	0	P,E		112	p	A,L,E
49	1	P,E		113	q	A,L,E
50	2	P,E		114	r	A,L,E
51	3	P,E		115	s	A,L,E
52	4	P,E		116	t	A,L,E
53	5	P,E		117	u	A,L,E
54	6	P,E		118	v	A,L,E
55	7	P,E		119	w	A,L,E
56	8	P,E		120	x	A,L,E
57	9	P,E		121	y	A,L,E
58	:	P,E		122	z	A,L,E
59	;	P,E		123	{	P,E
60	<	P,E		124	|	P,E
61	=	P,E		125	}	P,E
62	>	P,E		126	~	P,E
63	?	P,E		127	DEL	C,E


Error Processing - Overview
Overview

This section describes methods of trapping errors during program execution, and lists error messages that may be generated during execution.


Error Processing - Error Processing
Error Processing

During program execution, unusual situations may occur that the MSM system cannot handle automatically, including: program errors (for example: arithmetic division by zero), hardware failures (for example: an error reading a disk block), and external interrupts to a routine (for example: a user pressing CTRL+C). Generally, MSM considers such situations to be fatal errors.

See Also:

Actions: When Error Condition is Detected

Actions: When Error-Handling is Specified

Default Error Processing

User-Defined Error Processing

Processing Trapped Errors

Using the System Error Trap

Using Downlevel Error Trapping

Interactive Debugging

Format of $ZERROR


Actions: When Error Condition is Detected

When an error condition is detected during program execution, MSM interrupts execution and performs the following actions:

•	Terminates any active FOR loops and indirections on the current line.

•	Sets $ZERROR to reflect the error.

•	Appends the appropriate error codes to the $ECODE  special variable. If $ECODE is updated via the SET command, the entire value of $ECODE is replaced.

•	Updates the $STACK system function array to reflect the error, setting the ECODE, MCODE, and PLACE sub-nodes of $STACK($STACK).

•	If no error handling is specified at any execution level ($ETRAP is null, all NEWed values of $ETRAP also are null at all execution levels, and there are no non-null $ZTRAPs at any execution level), generates an execution traceback and terminates all the execution levels. If the user is in programmer mode, MSM changes the current device to the principal device and issues a command prompt. If programmer mode is not enabled, the partition is terminated after invoking the MSM default error handler.


Actions: When Error-Handling is Specified

The following steps are performed if error handling is specified at the current or at an earlier execution level.

If $ETRAP is non-null, MSM performs an internal GOTO to the following two lines of M code:

... $ETRAP value ...

    QUIT:$QUIT ""  Q

The second line handles the case in which the $ETRAP code completes and execution then continues on the second line. The QUIT commands are set up so that the current execution level terminates correctly depending on whether or not it was invoked as an extrinsic.

If $ZTRAP is non-null, MSM internally performs the following line of M code:

SET $ECODE="" GOTO @($ZTRAP)

As part of the GOTO, the value of $ZTRAP is reset to the null string. If additional error handling is required at the current execution level, $ZTRAP must be reestablished. The value of $ECODE is cleared to ensure that when the current execution level terminates, $ECODE is null. Otherwise, a return to an execution level where $STACK ($STACK("ECODE")) is null and  $ECODE is not null would generate an error (in accordance with the 1994 ANSI M standard). Because $ZTRAP code presumably was written prior to the 1994 ANSI standard, it is not likely to contain code that explicitly resets $ECODE. To maintain compatibility with existing applications, MSM clears $ECODE prior to transferring to the $ZTRAP error handling code.

MSM terminates the current execution level. This includes restoring values stacked by the NEW command (possibly including $ESTACK and $ETRAP).

MSM terminates any active FOR loops and indirections in the current execution line. MSM continues with step 1 above until an execution level is reached that does specify error handling via $ETRAP or $ZTRAP.

To ensure that error handling is uniquely defined, MSM does not allow both $ETRAP and $ZTRAP to be non-null at the same time. When $ETRAP is established via the SET command, MSM internally resets $ZTRAP to the empty string. When $ZTRAP is established via the SET command, MSM internally performs a NEW command on $ETRAP and then sets its current value to the empty string (a QUIT from this execution level restores $ETRAP to its original value). This interaction between $ETRAP and $ZTRAP allows existing applications that rely on $ZTRAP to coexist (on the execution stack) with applications that rely on the ANSI standard method of error trapping.

Refer to "MSM Functions" and "Special Variables" in this document for additional information.


Default Error Processing

If error handling is not defined, the error processing action to be taken when an error occurs includes a display of the execution traceback on the principal device and an invocation of the MSM default error handler.

The execution traceback displays the current value of $ZERROR, a formatted display of each execution level (from the deepest to the initial), followed by a redisplay of $ZERROR (in case the initial value scrolled off the screen).  The formatted display of a level includes its nesting level ($STACK); the routine reference of the line being performed or '*XECUTE* if inside an XECUTE string; and a copy of the line of M code that is being performed, if available (p-code-only routines display null text lines).

Following the execution traceback, the ^%ET utility is invoked to store the partition's current status for later review. This includes saving a copy of all the local symbols for the partition, $IO, $PRINCIPAL, $ZREFERENCE, and so on. These values can be examined using the ^%ER utility.


User-Defined Error Processing

The programmer can specify the M code that is to be performed when MSM detects an error. The programmer can use either the 1994 ANSI Standard error processing features such as $ETRAP or $ECODE or the MSM-specific features, $ZERROR and $ZTRAP.

User-Defined Error Processing - $ETRAP

To use the $ETRAP mechanism, the value of $ETRAP is set to an M string that is executed when an error is detected. For example:

SET  $ETRAP="S X=$X,Y=$Y G ^ERROR"

When an error is detected, MSM sets locals X and Y to the current values of $X and $Y respectively, and then transfers control to the first line in routine ^ERROR. This routine can attempt to recover from the error, record the error and any application-specific information, or allow the error to propagate to the previous execution level where it can be handled, recorded, or continue to be propagated to earlier execution levels. If the error processing routine does not clear $ECODE before exiting from the execution level where an error occurred, error processing is still in effect in the new execution level. A common use for M error handling features is to NEW $ESTACK at the top menu level of the application and to continue in error processing mode until the $ESTACK returns to zero.

User-Defined Error Processing - $ZTRAP

To use the $ZTRAP mechanism, the value of $ZTRAP is set to an M entry reference to which control will be transferred when an error is detected. For example:

SET $ZTRAP="ENTRY^ERROR"

When an error is detected, MSM terminates execution levels one at a time until it reaches an execution level at which $ZTRAP is not null. MSM then performs a GOTO to the entry point contained in $ZTRAP and also resets $ZTRAP to the empty string. This routine can attempt to recover from the error, record the error and any application-specific information, or force the error to be propagated to an earlier execution level that has a non-null $ZTRAP where the error can be handled, recorded, or continue to be propagated to earlier execution levels.

Because MSM internally resets the $ZTRAP used to invoke the error handling routine, $ZTRAP must be explicitly SET to a new non-null value if additional errors are to be trapped at the current execution level.


Processing Trapped Errors

When a DO or XECUTE command is processed, the MSM system creates a new execution level. This is done so that on termination of the DO or XECUTE command, either through an implicit QUIT (end-of-routine encountered) or an explicit QUIT, the system can return to the point at which the command was initiated.

As a point of reference, each execution level created by a DO or XECUTE command is numbered. Programmer mode is considered to be execution level 0, the first DO or XECUTE command is level 1, the second is level 2, and so on. The execution level that is currently in control generally is referred to as the current execution level.

While there is only one $ETRAP special variable (there is not a different one at each execution level), it can be stacked using the NEW command. This provides  a separate $ETRAP for each level when stacking is performed via the NEW command. Each execution level can customize its error handler independent of other error handling on the execution stack.

Alternatively, the $ZTRAP special variable can be set at each execution level. This means that each execution level in an application can establish its own error trapping routine and error recovery procedures.

Each execution level in an application can establish its own error trapping routine and error recovery procedures using either $ETRAP or $ZTRAP.

After an error has been trapped and processed by the specified routine, several  techniques can be used to exit from the error trap routine. One method is to use a GOTO command; control passes to a new routine, and program processing remains at the same execution level. This is the most common form of error recovery.

Alternatively, a QUIT command can be used to return to the previous execution level. When the $ETRAP mechanism is used, execution continues at the next higher level (the current execution level minus one), based on the value of $ECODE. If $ECODE is null, QUIT returns control normally to the previous level, with no further error processing. If $ECODE is not null and $STACK($STACK,"ECODE") is null (returning from a level with an error to a level at which no error occurred), error processing continues at the new level.

When using the $ZTRAP mechanism, a QUIT command returns control normally to the previous level, with no additional error processing.  If the error condition has not been handled, a ZQUIT command can be used to continue error processing on the previous level.

The following figure illustrates how $ZTRAP and the QUIT and ZQUIT commands are used to control the processing flow during error recovery.

Processing Errors with $ZTRAP

The following figure illustrates error processing with $ETRAP and $ECODE and can be contrasted with the "Processing Errors with $ZTRAP" figure.

Processing Errors with $ETRAP and $ECODE


Using the System Error Trap

The standard error-trapping utility programs supplied with the system provide the programmer with an alternative to writing error-trapping routines. These standard utilities include a routine to trap errors (%ET) and a routine to report trapped errors (%ER). These routines are described in this section.

%ET

When an error occurs and the %ET utility is invoked, the routine stores the values of the $ZERROR, $HOROLOG, $JOB, $IO, and $STORAGE special variables; the key of the last global referenced ($ZREFERENCE); and the contents of the local symbol table. It also writes a message to the principal device indicating that a program error was encountered and displays the contents of the $ZERROR special variable.

%ER

This utility reports errors that were trapped using the %ET routine.  It allows you to display, print, delete, or summarize errors. As a powerful programming and debugging tool, the %ER utility allows the programmer to reload the local symbol table with the local variable values that existed when the error occurred. After loading the variables, the routine exits and returns you to programmer mode.


Using Downlevel Error Trapping

Prior to MSM Version 2.1, the system discarded the entire contents of the DO/XECUTE stack when an error occurred. This was done before the system passed control to the error-trap routine specified by the $ZTRAP special variable. In MSM Version 2.1 and subsequent MSM releases, the DO/XECUTE stack remains at the same level when an error occurs.

Applications that require the DO/XECUTE stack to be cleared using the error trapping techniques provided in earlier versions of MSM do not work properly. The recommended solution to this problem is to modify the error-trapping code so that it uses the new style of trapping. However, this may not be practical in all cases. As a convenience to our users, a compatibility mode has been provided that enables error processing to behave as it did in previous MSM releases.

The compatibility mode has been implemented as an extension to the BREAK command. Refer to "MSM Commands" in this document for additional information on the BREAK command. The following describes the implemented compatibility extensions:

BREAK 2	Error trapping prior to Version 2.1
BREAK -2	Restore error trapping to Version 2.1 mode
When a job is started, the default value is the Version 2.1 mode of error processing (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.


Interactive Debugging

An MSM facility allows users operating in programmer mode to interactively step through execution of a program either one line or one command at a time. This facility also includes the ability to set breakpoints in programs without modifying the source code for the routine, and to display and alter the contents of local variables.

This feature is most commonly used by the programmer to more efficiently trace error conditions and determine the cause of an error. The interactive debugger is invoked by entering the following command at the M programmer prompt.

DO ^%DEBUG

The system responds with a menu of options. The utility program includes complete online help information and is easy to use.


Format of $ZERROR

The $ZERROR special variable contains descriptive information about the most recent error. This information is also provided as a piece of the $ECODE special variable when the $ETRAP mechanism of error trapping is used. The format of this descriptive information is as follows.

<Code>Offset^RoutName:Cmnd:Arg:Major:Minor:AddInfo

In this display, Code is the error code; Offset is the location (relative line number or label+offset) within the routine; RoutName is the name of the routine; Cmnd is the relative number of the command in the line in error; Arg is the number of the argument within the command; Major and Minor are the MSM error numbers; and AddInfo contains additional information about the error. Refer to "MSM Error Codes" and "MSM Error Numbers" in this chapter for additional information.

The MSM system maintains the Cmd and Arg parameters only when the debugger (%DEBUG) is active. AddInfo is not maintained for all error types. For example, when a disk error (<DKHER>) occurs, AddInfo contains the block number that received the error.


MSM Error Codes

The following table lists the error codes that are produced by the MSM system and describes how the errors are caused.

MSM Error Codes

Code	Explanation
<ASYNC>	An error occurred during the asynchronous processing of a previous SET or KILL operation on a remote volume group. This error is suppressed unless it is specifically allowed by a mode flag set through the SYSGEN or %MODESET utilities. The type of error is indicated in the additional information field of $ZERROR. This number is formed by major*256*+minor.
<BADCH>	An invalid character was encountered.
<BKERR>	The interpreter encountered a BREAK command while executing a program. The BREAK command is used primarily for program debugging and allows the user to inspect the program, local variables, and global variables at a specified location within the program. Program execution can be resumed using the ZGO command.
<CLOBR>	An attempt was made to overlay the current routine by issuing a ZLOAD, ZREMOVE, or ZINSERT command from within the routine.
<CMMND>	The interpreter encountered an illegal or undefined command.
<DDPER>	A Distributed Data Processing (DDP) error occurred.
<DIVER>	An attempt was made to divide a number by zero.
<DKFUL>	No space is available on the disk within the expansion limits of the current UCI. Information that the system was trying to write to the disk was lost. Database corruption can result.
<DKHER>	The MSM system encountered an unrecoverable error while trying to read from or write to a disk-type device. This is caused by a hardware malfunction or an attempt to reference a block that is outside the physical bounds of the disk.
<DKRES>	An attempt was made to allocate a block in the reserved area at the end of the user's expansion area because the expansion area is nearly full. If the AddInfo field in $ZERROR is 0, the operation was suppressed; if 1, the operation was completed.
<DKSER>	A block read in from the disk was not the type expected by the system or the block's internal structure was invalid. This can occur if the database is corrupted by a hard system failure such as a power failure, or a hardware malfunction such as an unrecoverable disk error on a write operation.
<DPARM>	Invalid use of parameter passing.
<DSCON>	The current device has been disconnected from the system.
<DSTDB>	A network communications link failed during a Distributed Data Processing (DDP) data transfer.
<ECODE>	An attempt was made to set $ECODE to an invalid value, or error processing was initiated by changing $ECODE from null to a valid value.
<EXPER>	An exponentiation error was detected.
<FUNCT>	The interpreter encountered an undefined function or a function that was used improperly.
<INDER>	The interpreter encountered illegal or incorrect use of the indirection operator.
<INHIB>	Access to a database through the network failed because database reads or writes are inhibited on the specified machine.
<INRPT>	The operating system received an interrupt (BREAK) from the terminal while the BREAK function was enabled (a BREAK 1 command was in effect).
<ISYNT>	An attempt was  made to insert an illegal line of text or code into the routine buffer. This can occur if the line of code is too long, the line label is invalid, or if the character separating the line label and the line body is incorrect. When an insert is performed in direct mode, the separator character must be a tab. If ZINSERT is used, the separator character must be one or more spaces or tabs.
<KLJOB>	The job was killed or interrupted by the KILLJOB utility.
<LCNSE>	The attempted operation would exceed the license limit.
<LINER>	A reference was made to a line that does not exist within the body of the routine.
<MAPER>	A disk block that is being freed is already marked free in the corresponding MAP block.
<MERGE>	A MERGE command was issued in which one operand is a descendant of the other operand.
<MINUS>	The interpreter found a negative number or zero when it expected a positive number.
<MODER>	An attempt was made to access the device in a mode that is not consistent with the parameters specified when the device was opened.
<MTERR>	An error occurred during an input or output operation to a magnetic tape device.
<MWAPI>	An error occurred while the M Windowing API was in use.
<MXMEM>	A memory address specified as an argument to the VIEW command or $VIEW function is outside the limits allowed by MSM.
<MXNUM>	The value of a number is greater than the largest number allowed by the system.
<MXSTR>	The value of string exceeds the maximum length allowed by the system. The maximum is 255 characters (or 511 as an option) for global variables, and 4092 characters for local variables.
Code	Explanation
<NAKED>	Access to a global variable using the naked indicator is invalid. This can occur if the naked indicator was not previously set by a global reference or if the previous global reference did not include subscripts.
<NMSPC>	A reference was made to an undefined mnemonicspace.
<NODEV>	The system intercepted an attempt by the program to OPEN a device that has not been defined to the system.
<NOJRN>	An attempt was made to journal a global in single-user mode.
<NOPEN>	The system intercepted an attempt by the program to USE a device that was not previously OPENed by the program.
<NOPGM>	A reference was made to a program that does not exist in the job's routine search path.
<NOSYS>	A reference was made to a non-existent system through Distributed Data Processing (DDP) or to a non-existent volume group through an extended global notation.
<NOUCI>	A reference was made to a non-existent UCI through an extended global notation.
<OBJCT>	An error occurred while an object reference was in use.
<PCERR>	The interpreter found an illegal post-conditional or the post-conditional argument is invalid.
<PGMOV>	There is insufficient memory in a partition to complete the requested operation.
<PLDER>	The routine that is being loaded has down-level p-code or does not have the correct type of p-code for a remote volume group executing a routine.
<PROT>	An attempt was made to access a protected global that the user is not authorized to access. This error also can occur if an attempt is made to save a program with a name that begins with a percent sign (%) in any UCI other than the Manager's UCI.
<SBSCR>	The subscript used in a local or global variable reference is invalid. This can occur if the subscript is null; the subscript contains the ASCII NULL character; the length of a subscript is greater than 255 characters; or the combined length of the global reference (global name, parentheses, subscripts, and commas) is greater than 255.
<SPOOL>	The MSM spooling area is full.
<STKOV>	The system stack overflowed as a result of nested indirection or a program loop, or the system expression stack overflowed while evaluating a complex expression or saving a large routine.
<SYNTX>	The interpreter encountered a syntax error in the line that is being executed.
<SYSTM>	The MSM system encountered an internal error. The exact error message, including major/minor error numbers, should be reported to Micronetics.
<TXPER>	A transaction processing error occurred.
<UNDEF>	The operating system intercepted an attempt to reference a non-existent local, global, or structured system variable or a non-existent object method or property.
<VWERR>	An attempt was made to access a device in shared VIEW buffer mode without ownership of the VIEW device (device 63). This error also occurs if the VIEW device is closed before the device that was opened in shared VIEW buffer mode.
<XCALL>	The function name specified on an external routine reference does not exist, or the parameters specified are invalid.
<ZSAVE>	One of the lines in the routine that is being compiled is too large to fit in the disk buffer. The line should be split into two or more lines to correct the problem.
<ZSVGP>	A ZSAVE command was issued, but the volume group was not enabled for any p-code type.
<Zxxxx>	A ZTRAP command was issued with "xxxx" as the argument.


MSM Error Numbers

The following table lists the major and minor error numbers generated by MSM and describes how each error is caused.

MSM Error Numbers

Major	Minor	Explanation
1	-	Command type errors
	0	Unrecognized command
2	-	Argument type errors
	1	Missing parenthesis
	2	Missing or bad colon
	3	Missing or bad equals
	4	Missing or bad local variable
	5	Missing or bad global variable
	6	Missing or bad function
	7	Missing or bad routine name
	8	Missing or bad routine label
	9	Missing or bad routine offset
	10	Indirect argument error
	11	Argument condition error
	12	Bad argument delimiter
	13	Bad command
3	-	Expression type errors
	0	Bad special variable name
	1	Bad system function
	2	Bad local variable
	3	Bad global variable
	4	Bad string constant
	5	Bad numeric constant
	6	Unbalanced parenthesis
	7	Invalid syntax in term
	8	Bad operator
	9	Bad delimiter
4	-	Reference type errors
	0	Undefined local variable
	1	Undefined global variable
	2	Undefined label
	3	Undefined routine
	4	Invalid naked reference
	5	Non-existent device or no memory for window
	6	Unsubscripted local reference required
	7	Variable reference required (no expressions)
	8	ZLOAD usage error during routine execution
	9	Undefined UCI reference
	10	Attempted ZINSERT of an invalid line
	11	Unknown data type
	12	Missing function parameter
	13	Undefined system in cross-system reference
	14	Global access protection violation
	15	Volume group protection violation
	16	XCALL error
	17	Formal list not entered via DO command
	18	QUIT with argument inside FOR scope
	19	QUIT with argument, but routine not extrinsic
	20	Argumentless QUIT, but routine was extrinsic
	21	Extrinsic subroutine ended without Q parm
	22	Label requires a formal list
	23	Actual parms exceed parms in formal list
	24	Formal list parameter is subscripted variable
	25	Duplicate variable name in formal list
	26	Passing value by reference in JOB not allowed
	27	MERGE operand is descendant of other
	28	Nested mnemonic namespace request
	29	Undefined structured system variable
	30	FOR control variable was KILLed
	31	Unsupported OMI feature
	32	Object value is undefined
	33	Undefined object method or property
	34	VIEW restriction violation
	35	MWAPI reference to undefined element
	36	Required MWAPI attribute missing
	37	Mnemonicspace not in mnemonic list
	38	Undefined mnemonicspace
	39	Device does not support mnemonicspace
5	-	Value-type errors
	0	String exceeded maximum length
	1	$SELECT function error
	2	Divide by zero
	3	Negative number
	4	Maximum number
	5	Device not open
	6	Invalid memory address
	7	String value required
	8	Indirection resulted in null value
	9	Indirection included more than name
	10	Selected partition not active ($VIEW)
	11	Invalid VIEW or $VIEW argument
	12	Function parameter out of range
	13	Invalid subscript
	14	Device not open for access type attempted
	15	Invalid character
	16	Not allowed to write block 0
	17	Invalid use of shared mode on VIEW buffer
	18	Raised zero to non-positive power
	19	Raised negative number to non-integer power
	20	Invalid $ZBN usage
	21	Invalid $ECODE value
	22	Invalid $FNUMBER parameter
	23	Invalid $RANDOM parameter
	24	Invalid READ length
	25	Invalid $NAME parameter
	26	QUIT when $TLEVEL >0
	27	Invalid $X or $Y value
	28	Object reference required
	29	MSM spooling error
	30	Attempt to SET an object method
	31	Attempt to SET a read-only object property
	32	Error accessing object
	33	Invalid MWAPI attribute name
	34	Invalid MWAPI attribute value
	35	Invalid MWAPI focus
	36	Invalid MWAPI font parameter
	37	Invalid MWAPI window mode
	38	Invalid nested ESTART
	39	Character must be single byte
6	-	Environmental errors
	0	Break key pressed
	1	Attempt to exceed partition size
	2	HALT command executed
	3	LOCK table full
	4	BREAK command executed
	5	Expression stack overflow
	6	System stack overflow
	7	Old p-code needs to be saved
	8	Circuit error during DDP operation
	9	Reserved for DDP internal use
	10	DDP database access inhibited
	11	Reserved for future use
	12	I/O error on terminal operation
	13	I/O error on magnetic tape operation
	14	P-code too long to fit in one block
	15	ZQUIT error
	16	DDP circuit disabled
	17	ZTRAP command issued
	18	Expression stack overflow on READ command
	19	No p-code type for volume group on ZSAVE
	20	P-code type not available for this system
	21	Number of users exceeds license limit
	22	Asynchronous error on remote volume group
	23	Journal request in single-user mode
	24	Transaction processing error
	25	Routine is too large to load
	26	Host system is out of memory
	27	$ECODE has been SET
	28	Transaction is not restartable
	29	Job killed by KILLJOB
	30	ZSAVE license violation
	31	Socket license violation
	32	Window type is not MTERM
	33	KILL of open MTERM window
	34	ESTOP command executed
	35	TSTART nested too deeply
7	-	Disk-type errors
	0-32	Block type mismatch, number is expected type
	33	Hardware disk I/O error
	34	Database full condition
	35	Block number mismatch
	36	Key/data exceeds maximum length
	37	Cannot open requested database
	38	Block being freed is already free
	39	Invalid block number
	40	Attempt to allocate block in reserved area
	41	Block contains invalid key
	42	Block contains invalid data
	43	KILL found invalid key


$ECODE Errors

The following table lists the $ECODE errors generated by MSM and explains how the errors are caused.

$ECODE Errors

Code	Explanation	Equivalent $ZERROR value
M1	Naked indicator undefined	<NAKED>:::4:4
M2	Invalid "P" parameter in $FNUMBER	<SYNTX>:::5:22
M3	$RANDOM seed less than 1	<SYNTX>:::5:23
M4	No true condition in $SELECT	<SYNTX>:::5:1
M5	Line reference less than zero	<SYNTX>:::3:6
M6	Undefined local variable name	<UNDEF>:::4:0
M7	Undefined global variable name	<UNDEF>:::4:1
M8	Undefined subscripted system variable name	<UNDEF>:::4:29
M9	Divide by zero	<DIVER>:::5:2
M11	No parameters passed	<DPARM>:::4:17
M12	Negative offset in line reference	<LINER>:::2:8
M13	Line reference not found	<LINER>:::4:2
M15	Undefined index variable	<UNDEF>:::4:30
M16	QUIT argument not allowed	<DPARM>:::4:18
M17	QUIT argument required	<DPARM>:::4:20
M18	Fixed length READ not greater than zero	<SYNTX>:::5:24
M19	Cannot copy a tree or subtree into itself	<MERGE>:::4:27
M20	Formal argument list required	<DPARM>:::4:22
M26	Non-existent environment	<NOUCI>:::4:9
M27	Transaction is not restartable	<TXPER>:::6:28
M28	Mathematical function, parameter out of range	<DPARM>:::4:23
M35	Device does not support mnemonicspace	<NMSPC>:::4:39
M40	Call-by-reference in JOB actual	<DPARM>:::4:26
M42	Invalid QUIT within a TRANSACTION	<TXPER>:::5:26
M43	Invalid range value ($X,$Y)	<MINUS>:::5:27
M44	Invalid command outside of a TRANSACTION	<TXPER>:::6:24
M46	Invalid MWAPI attribute name	<MWAPI>:::5:33
M47	Invalid MWAPI attribute value	<MWAPI>:::5:34
M48	MWAPI object does not exist	<MWAPI>:::4:35
M49	Invalid MWAPI focus	<MWAPI>:::5:35
M50	Reference to non-MTERM window	<MWAPI>:::6:32
M51	KILL of open MTERM window	<MWAPI>:::6:33
M52	Required MWAPI attribute missing	<MWAPI>:::4:36
M53	Invalid MWAPI font parameter	<MWAPI>:::5:36
M54	Invalid MWAPI window mode	<MWAPI>:::5:37
M55	Invalid nested ESTART	<MWAPI>:::5:38
M58	Too many actual parameters	<DPARM>:::4:23


Mnemonic Namespaces - Overview
Overview

MSM's mnemonic namespaces feature allows users to develop M applications that are relatively device-independent in handling low-level device functions (for example: clearing a terminal screen or backspacing one block on a tape). Mnemonic namespaces can be used to access many of the device types supported by MSM.

The device types that can be supported through namespaces include: terminal devices, sequential block processor (SBP) devices, host file server (HFS) devices, interjob communication (IJC) devices, magnetic tape devices, the MSM spool device, and the host system spool device. For additional information about mnemonic namespaces, refer to "MSM Commands" in this manual, and "Using Peripheral Devices" in the MSM-Workstation Technical Reference documentation.

Two types of mnemonic namespaces are supported in MSM: built-in namespaces and user-defined namespaces. MSM's standard distribution includes two built-in namespaces and one user-defined namespace. The X3.64-1979 built-in namespace is commonly referred to as the ANSI terminal namespace. The ZWINTERM built-in namespace allows windowing capabilities on dumb terminals.

The user-defined namespace is called X3.64 TEMPLATE and is distributed in a DOS file called ANSI.NAM. The system manager can use this namespace as a template to create other namespaces. The X3.64 TEMPLATE namespace can be imported into the MSM database using the Import a Namespace option. The template then can be copied to a new name and edited. It includes the complete set of ANSI mnemonics.

Because ANSI terminals are the most frequently used terminal type in M applications, the namespace for this terminal type was directly built into the system. From a technical point of view, a built-in namespace is coded directly into the MSM system monitor rather than through user-supplied M code. As a result, overhead when using this namespace is significantly reduced.

Because the X3.64-1979 is built-in, it cannot be edited or deleted by the user. The mnemonics defined within the namespace cannot be listed through this option of the SYSGEN utility.


ANSI X3.64-1979 Namespace

The following table lists the mnemonic controls sequences that are available for the ANSI X3.64-1979 namespace. It also describes the operands that can be specified for each mnemonic control. When a mnemonic is used, it must be preceded by a slash (/).

ANSI X3.64-1979 Mnemonic Namespace

Mnemonic	Function and Esc sequence	Change in $X and $Y
/BEL	Rings bell Seq: *7	$X:None $Y:None
/BS	Backspaces cursor Seq: *8	$X:MAX(0,$X-1) $Y:None
/CBT(n)	Backs up n tab stops Minimum and default value is 1 Assumes eight-column tabbing Seq: *27 [ n z	$X: MAX(0,$X+7\8*8-(n*8)) $Y:None
/CHA(n)	Moves cursor to column n Minimum and default values are 1 Seq: *27 [ n g	$X:n-1 $Y:None
/CHT(n)	Moves forward n tab stops Minimum and default values are 1 Assumes eight-column tabbing Seq: *27 [ n i	$X: MIN(255,$X\8*8+(n*8) $Y:None
/CNL(n)	Moves cursor down n lines Moves cursor to column 1 Minimum and default values are 1 Seq: *27 [ n e	$X:0 $Y:MIN(255,$Y+n)
/CPL(n)	Moves cursor up n lines Moves cursor to column 1 Minimum and default values are 1 Seq: *27 [ n f	$X:0 $Y:MAX(0,$Y-n)
/CR	Moves cursor to column one, current line Seq: *13	$X:0 $Y:None
/CTC(a,b,...)	Sets tab stops Seq: *27 [ a ; b ; ... W	$X:None $Y:None
/CUB(n)	Moves cursor back n columns Minimum and default values are 1 Seq: *27 [ n d	$X:MAX(0,$X-n) $Y:None
/CUD(n)	Moves cursor down n rows Minimum and default value is 1 Seq: *27 [ n b	$X:None $Y:MIN(255,$Y+n)
/CUF(n)	Moves cursor forward n columns Minimum and default values are 1 Seq: *27 [ n c	$X:MIN(255,$X+n) $Y:None
/CUP(r,c)	Positions cursor to row r, column c Minimum for c and r is 1 Default for c and r is 1 Maximum for c and r is 256 Seq: *27 [ r ; c h	$X:c-1 $Y:r-1
/CUU(n)	Moves cursor up n lines Minimum and default values are 1 Seq: *27 [ n a	$X:None $Y:MAX(0,$Y-n)
/DA(a,b,...)	Sets device attributes Parameters are ANSI values for color, blink, etc. Seq: *27 [ a ; b ; ... m	$X:None $Y:None
/DAQ(a,b,...)	Defines area qualifications Parameters are ANSI values Seq: *27 [ a ; b ; ... O	$X:None $Y:None
/DCH(n)	Deletes n characters at cursor Moves remainder of lines left Minimum and default values are 1 Seq: *27 [ n p	$X:None $Y:None
/DL(n)	Deletes n lines at cursor Moves up remaining lines Minimum and default values are 1 Seq: *27 [ n m	$X:None $Y:None
/DSR(a,b,...)	Performs device status request Parameters are ANSI values Response must be read-in via READ command Seq: *27 [ a ; b ; ... N	$X:None $Y:None
/ECH(n)	Erases n characters at cursor Replaces with blanks Minimum and default values are 1 Seq: *27 [ n x	$X:None $Y:None
/ED(n)	Erases display N=0: cursor to end of display N=1: home to cursor N=2: entire display Seq: *27 [ n j	$X:None $Y:None
/EL(n)	Erases line N=0: cursor to end of line N=1: start of line to cursor N=2: entire line Seq: *27 [ n k	$X:None $Y:None
/FF	Moves cursor down one row Seq: *12	$X:None $Y:($Y+1)#256
/HPA(n)	Moves cursor to column n Minimum and default values are 1 Seq: *27 [ n `	$X:n-1 $Y:None
/HPR(n)	Moves cursor forward n columns Minimum and default values are 1 Seq: *27 [ n a	$X:MIN(255,$X+n) $Y:None
/HT	Horizontal tab Seq: *9	$X:MIN(255,$X\8*8+8) $Y:None
/HTS	Sets horizontal tab stop at cursor Seq: *27 h	$X:None $Y:None
/HVP(r,c)	Moves cursor to row r and column c Minimum and default values are 1 Maximum value is 256 Seq: *27 [ r ; c f	$X:c-1 $Y:r-1
/ICH(n)	Inserts n blanks at cursor Minimum and default values are 1 Seq: *27 [ n @	$X:None $Y:None
/IL(n)	Inserts n blank lines at cursor Minimum and default values are 1 Seq: *27 [ n l	$X:None $Y:None
/IND	Moves cursor one column down Seq: *27 d	$X:None $Y:MIN(255,$Y+1)
/LF	Moves cursor one line down Seq: *10	$X:None $Y:($Y+1)#256
/MSMRC(n)	Restores saved cursor position Seq: *27 8	$X:Saved value $Y:Saved value
/MSMRGN(n,m)	Sets up scrolling region Seq: *27 [ n ; m r	$X:None $Y:None
/MSMRM(a,b,...)	Reset modes Seq: *27 [ ? A ; b ... H	$X:None $Y:None
/MSMSC	Saves current cursor position Seq: *27 7	$X:None $Y:None
/MSMSM(a,b,...)	Sets modes Seq: *27 [ ? A ; b ... H	$X:None $Y:None
/NEL	Moves to column one of next line Seq: *27 e	$X:0 $Y:($Y+1)#256
/NP(n)	Advances n pages of terminal Displays memory Seq: *27 [ n u	$X:0 $Y:0
/PP(n)	Backs up n pages of terminal Displays memory Seq: *27 [ n v	$X:0 $Y:0
/RI	Reverses index (up one column) Seq: *27 m	$X:None $Y:MAX(0,$Y-1)
/RIS	Resets to initial state Seq: *27 c	$X:0 $Y:0
/RM(a,b,...)	Resets modes Values are ANSI-defined Seq: *27 [ a ; b ; ... L	$X:None $Y:None
/SGR(a,b,...)	Sets graphical rendition Seq: *27 [ a ; b ; ... m	$X:None $Y:None
/SM(a,b,...)	Sets modes Values are ANSI-defined Seq: *27 [ a ; b ; ... H	$X:None $Y:None
/TBC(a,b,...)	Clears tap stops Seq: *27 [ a ; b ; ... G	$X:None $Y:None
/VPA®	Moves to row r of same column Minimum and default values are 1 Seq: *27 [ r d	$X:None $Y:r-1
/VPR(n)	Moves cursor down n lines, same column Minimum and default values are 1  Seq: *27 [ n e	$X:None $Y:MIN(255,$Y+n)
/VT	Vertical tab (up one column) Seq: *11	$X:None $Y:MAX(0,$Y-1)


ZWINTERM Namespace

The ZWINTERM mnemonic namespace provides a mechanism for programmers to perform windowing functions on dumb terminals. These functions also are available on the console device of PC systems operating under MSM-PC/PLUS. Internally, when the user specifies the ZWINTERM mnemonic namespace through the USE command, the MSM system builds a copy of the user's terminal screen in memory. This includes both characters on the screen and attributes associated with each character. Subsequent updates to the screen are applied to the memory image, as well as to the physical screen.

When a window is opened in the ZWINTERM mnemonic namespace, the system makes a copy from the in-memory screen image of the area that will be overlaid by the new window. After the window is opened, the program can use the normal READ and WRITE commands to access the window. When the window is closed, the system automatically refreshes the area under the window. No additional action is required on the part of the program to restore the area.

The ZWINTERM mnemonic namespace also supports the built-in X3.64-1979 namespace for interpreting format controls within the window. The X3.64-1979 namespaces must be initialized using the /INIT format control after the ZWINTERM namespace has been invoked. User-defined namespaces are not supported with ZWINTERM.

See Also:

Attributes

Erase Operations

Error Codes


Attributes

The ZWINTERM mnemonic namespace supports attributes for setting text attributes (bold, blink, underline, reverse) and colors (background and foreground) within a window, within a border, and within a title. The following table describes the supported attributes.

ZWINTERM Display Attributes

Attribute	Description
0	Restores normal text attributes
1	Sets bold attribute for text
2	Sets underline attribute for text
5	Sets blink attribute for text
7	Sets reverse video attribute for text
22	Clears bold attribute for text
24	Clears underline attribute for text
25	Clears blink attribute for text
27	Clears reverse video attribute for text
30	Sets foreground color to black
31	Sets foreground color to red
32	Sets foreground color to green
33	Sets foreground color to yellow
34	Sets foreground color to blue
35	Sets foreground color to magenta
36	Sets foreground color to cyan
37	Sets foreground color to white
40	Sets background color to black
41	Sets background color to red
42	Sets background color to green
43	Sets background color to yellow
44	Sets background color to blue
45	Sets background color to magenta
46	Sets background color to cyan
47	Sets background color to white
The attribute values can be specified on the /SGR, /WBSGR, /WTSGR, /WDSGR, and /WCSGR functions. In addition, multiple attributes can be specified for a character location.

For example, the background color can be set to cyan, the foreground color to white, and the foreground text to blink. This is done by issuing multiple ZWINTERM control mnemonics that address the same character location. The following example illustrates how this is done.

W /CUP(10,40),/SGR(46),/SGR(37),/SGR(5)

All of the text attributes can be reset with a single operation by specifying a 0 attribute value. The background and foreground colors are not affected by a 0 attribute value, and the colors must be explicitly changed.


Erase Operations

The ZWINTERM mnemonic namespace supports several types of erase operations within a window. These erase operations are specified as an operand on several of the ZWINTERM control mnemonics. The following table describes the supported erase operations.

ZWINTERM Erase Attributes

Erase Type	Description
0	Erases the window in memory or the window on the screen, or both, from and including the current cursor position to the end of the line or the end of the window.
1	Erases the window in memory or the window on the screen, or both, from the beginning of the window or the line to and including the current cursor position.
2	Clears the entire window or line in memory, or the entire window or line on the screen, or both, and resets the blink, reverse, bold, and underline attributes.
The erase values can be specified on the /ED, /EL, /WCMD, and /WCML control mnemonics. The /ED and /EL functions clear the memory buffer and the screen. The /WCMD and /WCML functions only clear the memory buffer. If desired, the /WDSP function can be used after these functions to refresh the screen with the contents of the memory buffer. When multiple updates to a screen are required, the program can use functions that only update the memory buffer followed by a refresh. This approach prevents unnecessary repaints of the screen and improves performance.


Error Codes

After each mnemonic control operation, the system returns a value in the $DEVICE special variable that indicates the success or failure of the operation. The following table lists the values that can be returned by the system and provides a description of the error associated with each value.

ZWINTERM Error Codes

Error Code	Description
0	Must be 0, normal success completion
1	Window already exists
2	Bad parameter value
3	Nonexistent window
4	Mnemonic space not initialized
5	Terminal does not have windowing functionality
6	Undefined terminal mnemonic space
For additional information on the USE command, refer to "MSM Commands" in this manual. For additional information on the $DEVICE special variable, refer to "MSM Special Variables" also in this manual. The $DEVICE special variable is maintained for the current terminal device and not for each window in the ZWINTERM mnemonic namespace. The value contained in the $DEVICE special variable reflects the last error condition, regardless of the specific window in which it occurred.


ZWINTERM Namespace Commands

/INIT(TermSpace,Color) - Initialize Namespace

Color	A flag that indicates whether color attributes are supported for the window.  A value of 1 indicates that color attributes are supported.  A value of 0 (the default) indicates that color attributes will be ignored.
Attribute	An integer value that indicates the type of attribute to set. Refer to the "ZWINTERM Display Attributes" table in this chapter for a list of the attributes and their values. This parameter is optional. If it is omitted, a default value of 0 is assumed.
This function is used to initialize the ZWINTERM mnemonic namespace for the current terminal device. As part of the initialization process, a memory buffer is obtained, the terminal screen is erased, and the system internally issues an OPEN (/WOPEN) and USE (/WUSE) for window number 0 as a full screen window. The default values for scroll, auto-wrap, automatic display, and line drawing are used.

The ZWINTERM Namespace also can be used in conjunction with the X3.64-1979 Namespace.  If the first parameter of /INIT is X3.64-1979, then the full set of mnemonics for this built-in namespace is available within the ZWINTERM window.

This mnemonic control must be executed before any other ZWINTERM mnemonic control sequences can be used. If other mnemonic controls are executed before a /INIT function is performed, the system returns an error code of 1 in the $DEVICE special variable. If this mnemonic control is issued after a previously executed /INIT function and before a /END function is executed, the system implicitly performs the /END function before executing the /INIT function.

/END - Release Mnemonic Space

This function ends use of the ZWINTERM mnemonic namespace. The end process frees all of the memory buffers used by ZWINTERM for the current device. Any mnemonic control operation executed after a /END and before the next /INIT operation returns an error code of 12 in the $DEVICE special variable.

/WOPEN(Win,Row,Col,NumRows,NumCols,Flag) - Open Window

Win	A positive integer used to identify the window.
Row	An integer expression with a value between 0 and 23 that indicates the starting row for the window. If the specified value is invalid or omitted, the system assumes a value of 0.
Col	An integer expression with a value between 0 and 79 that indicates the starting column for the window. If the specified value is invalid or omitted, the system assumes a value of 0.
NumRows	An integer expression with a value between 1 and 24 that indicates the number of rows in the window.
NumCols	An integer expression with a value between 1 and 80 that indicates the number of columns in the window.
Frame	A string expression that indicates the characteristics of the window frame. A value of F indicates the window should have a frame, and a value of " " indicates that the window should have no frame.
This function creates a new window with identifier Win starting at the location specified by the Row and Col parameters. The window contains the number of rows and columns specified by the NumRows and NumCols parameters. The default attributes when a window is created are: scroll on, auto-wrap on, automatic display off, and line drawing off.

/WUSE(Win) - Use Window

Win	A positive integer that identifies the window to be used.
This function makes the specified window the current window. All READ and WRITE commands and mnemonic controls apply to this window until the next /WUSE function is performed.

/WCLOSE(Win) - Close Window

Win	A positive integer that identifies the window to be closed.
This function is used to CLOSE the window identified by the Win parameter. When a window is closed, any areas overlaid by the window are refreshed, and memory buffers associated with the window are freed.

/WSCRON - Enable Automatic Display

The automatic display attribute is set to "on" for the current window. When the automatic display attribute is on, any WRITE commands update the memory buffer and the updates are immediately displayed on-screen. The /WSCRON mnemonic also implicitly executes the /WDSP mnemonic.

/WSCROFF - Disable Automatic Display

The automatic display attribute is set to "off" for the current window. When the automatic display attribute is off, any WRITE commands only update the memory buffer (the updates are not immediately displayed on-screen). The /WDSP function can be used to update the screen with the contents of the memory buffer.

/WDSP - Display Window

This function is used to display on-screen the contents of the memory buffer associated with the current window.

/WUNDSP - Undisplay Window

This function is used to erase the current window from the screen. When the window is erased, the area of the screen that was hidden by the window is automatically refreshed. This function does not delete the current window. Its contents can be displayed again using the /WDSP function.

/WMOVE(Row,Col) - Move Window

Row	An integer expression with a value between 0 and 23 that indicates the row where the window is to be positioned. If this value is invalid or omitted, a value of 0 is assumed.
Col	An integer expression with a value between 0 and 79 that indicates the column where the window is to be positioned. If this value is invalid or omitted, a value of 0 is assumed.
This function is used to move the location of an existing window. If the current window is not window 0, the current window origin (the upper-left corner) is moved to the locations specified by the Row and Col parameters. As part of the move function, the screen is refreshed.

/WT(Title,Location,Alignment) - Window Title

Title	A string expression to be displayed as the title within the border of the current window. If this value is invalid or omitted, a title of null is assumed.
Location	An integer value from 0 to 1 that indicates where the title line is to be displayed within the border of the current window. If this value is invalid or omitted, a value of 0 is assumed.
	0	Displays title at top of window
	1	Displays title at bottom of window
Alignment	An integer value from 0 to 2 that indicates how the title is to be positioned within the border line of the current window. If this value is invalid or omitted, a value of 0 is assumed.
	0	Left-justifies the title
	1	Centers the title
	2	Right-justifies the title
This function is used to specify a title that appears in the border of the current window. The title can appear at the top or bottom of the window or can be left-justified, right-justified, or centered within the border.

/WTSGR(Attribute) - Window Title SGR

Attribute	An integer value that indicates the type of attribute to be set or cleared. Refer to the "ZWINTERM Display Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
This function is used to set the attributes for the title that appears in the border of the current window.

/WBSGR(Attribute) - Window Border SGR

Attribute	An integer value that indicates the type of attribute to be set or cleared. Refer to the "ZWINTERM Display Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
This function is used to set or clear attributes associated with the border of the current window.

/WDSGR(Attribute) - Window Default SGR

Attribute	An integer value that indicates the type of attribute to be set or cleared. Refer to the "ZWINTERM Display Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
This function is used to set or clear the default attributes associated with the current window. These default attributes are applied to new lines created at the bottom of a window when text is scrolled and erased with the /ED and /EL functions. This function affects the SGR for unused areas of the window.

/WGETCW - Get Current Window

This function returns the identifier (the Win value) for the current window. The identifier is returned in the $KEY special variable.

/WREFRESH - Refresh Screen

This function is used to refresh the screen. Window 0 and all other windows are repainted when the function is executed.

/WCMD(Type) - Clear Display

Type	An integer value from 0 to 2 that indicates how the erase function is to be performed. Refer to the "ZWINTERM Erase Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
This function is used to erase all or part of the current window. When this function is used, only the in-memory buffer is updated. The /WDSP function must be used to make the changes visible to the user.

/WCML(Type) - Clear Line

Type	An integer value from 0 to 2 that indicates how the erase function is to be performed. Refer to the "ZWINTERM Erase Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
This function is used to erase all or part of a line in the current window. When this function is used, only the in-memory buffer is updated. The /WDSP function must be used to make the changes visible to the user.

/WWR(Mode) - Change Wrap Mode

Mode	An integer value from 0 to 1 that indicates how lines of text are to be handled when the right margin is reached. If this value is invalid or omitted, a value of 0 is assumed.
	0	Sets autowrap on
	1	Sets autowrap off
This function is used to set the wrap mode for the current window. If autowrap is on, a carriage return/linefeed sequence is automatically inserted when a text line reaches the right margin. If autowrap is off, the line is truncated.

/ZXYMODE(Mode) - XY Mode

Mode	An integer value from 0 to 1 that indicates whether the X and Y coordinates for the CUP mnemonic are interpreted relative to 0 or relative to 1.
	0	X and Y coordinates are relative to 0
	1	X and Y coordinates are relative to 1 (the default mode)
In MSM Version 4.0.11, the /CUP mnemonic was corrected (for ZWINTERM windows only) so that the X and Y coordinates are relative to 1 rather than 0. In order to support application code that was developed under the old rule, this feature was implemented to enable the older mode. Using this feature, the coordinates of the upper left corner of a ZWINTERM window can be either "1,1" (the default mode) or "0,0".

/WSC(Scroll) - Change Scroll Mode

Scroll	An integer value from 0 to 1 that indicates how lines of text are to be handled when the bottom of the screen is reached. If this value is invalid or omitted, a value of 0 is assumed.
	0	Sets scroll mode on
	1	Sets scroll mode off
This function is used to set the scroll mode for the current window. If scroll mode is on, lines within the window are moved up when a carriage return/line feed is sent to the last line of the window. If scroll mode is off, the lines are not moved and text is written to the last line in the window.

/WCSGR(Attribute,Location) - Window Current SGR

Attribute	An integer value that indicates the type of attribute to set or clear. Refer to the "ZWINTERM Display Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
Location	An integer from 0 to 6 that indicates where in the current window the attribute is to be changed. If this value is invalid or omitted, a value of 4 is assumed.  0 Current character  1 From current cursor position to end of line  2 Entire line containing the cursor  3 From current cursor position to end of window  4 Entire window (default)  5 From current cursor position to end of column  6 Entire column containing the cursor
This function is used to change the attributes of text within the current window. The specified attributes are set or cleared according to the position of the cursor and the range of the change specified by the Location parameter.

/CUR(Display) - Cursor

Display	An integer value from 0 to 4 that indicates actions to be performed on the cursor within the window. If this value is invalid or omitted, a value of 0 is assumed.  0 Shows cursor  1 Hides cursor  2 Saves cursor and attributes  3 Restores cursor and attributes  4 Forces cursor and attributes
This function is used to perform cursor actions within the current window. It allows the programmer to show or hide the cursor, save the cursor location and attributes, and restore the cursor location and attributes.

/CUP(Row,Col) - Cursor Position

Row	An integer expression with a value from 0 to 23 that indicates the row where the cursor is to be positioned. If this value is invalid or omitted, a value of 0 is assumed.
Col	An integer expression with a value from 0 to 79 that indicates the column where the cursor is to be positioned. If this value is invalid or omitted, a value of 0 is assumed.
This function positions the cursor to the specified Row and Col position. Positions are relative to the upper-left corner (row 0, column 0) of the current window.

/ED(Type) - Erase Display

Type	An integer value from 0 to 2 that indicates how the erase function is to be performed. Refer to the "ZWINTERM Erase Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
This function is used to erase all or part of the current window. When this function is executed, both the memory buffer and the screen are updated.

/EL(Type) - Erase Line

Type	An integer value from 0 to 2 that indicates how the erase function is to be performed. Refer to the "ZWINTERM Erase Attributes" table in this chapter for a list of the attributes and their values. If this optional parameter is omitted, a default value of 0 is assumed.
This function is used to erase all or part of a line in the current window. When this function is executed, both the memory buffer and the screen are updated.

/?DR(Char,Repeat) - Line Drawing (optional)

Char	An integer from 0 to 12 that indicates which of the line drawing characters is to be displayed in the current window. If this value is invalid or omitted, a value of 0 is assumed.  0  Line drawing off  1  Line drawing on  2  Writes horizontal character (-)  3  Writes vertical character (|)  4  Writes character upper-left corner ()  5  Writes character upper-right corner ()  6  Writes character lower-left corner ()  7  Writes character lower-right corner ()  8  Writes intersection character (inverted T)  9  Writes intersection character (T)  10  Writes intersection character (left T)  11  Writes intersection character (right T)  12  Writes intersection character (+)
Repeat	An integer value that indicates the number of times the line-drawing character specified by the Char parameter is written. If this value is invalid or omitted, a value of 1 is assumed.
This function is used to perform line drawing functions; when it is executed, the specified character is written at the current cursor location the specified number of times.

/SGR(Attribute) - Change Character SGR

Attribute	An integer value that indicates the type of attribute to set or clear. Refer to the "ZWINTERM Display Attributes" table in this chapter for a list of the attributes and their values. If this optional  parameter is omitted, a default value of 0 is assumed.
This function is used to set or clear the specified attribute in the current window. The attributes are changed in memory and on the screen. This function affects the SGR of the characters and their cells in the window.


SYSGEN Mnemonic Namespaces

The mnemonic namespace option of the SYSGEN program is used to create, edit, and delete user-defined namespaces. To create a mnemonic namespace, the user must first assign it a unique name (an identifier). The name can be from one to 15 characters in length and can include any alpha, numeric, or special characters.

After a namespace is created, the user defines one or more mnemonics within the namespace. A mnemonic is a shorthand name associated with a specific device function. When a mnemonic is created, the user must specify the name of the mnemonic. The name can be from one to 15 characters in length, and must begin with an alpha character or the question mark (?) character. The remaining characters can be any valid alpha or numeric characters.

The user next indicates whether  the mnemonic function affects the values of the $X and $Y special variables. If the user indicates that the values are not updated by the function, the system ensures that $X and $Y contain the same values at the end of the function as they did at the start. If the user indicates that the values are affected, the user must supply the code necessary to ensure that $X and $Y are updated properly.

The user then specifies the number of parameters required by the function. This is done by specifying the minimum and the maximum number of parameters that can be supplied for the function. Both the minimum and maximum number of parameters can be from zero through nine. If zero is specified for both the minimum and maximum number of parameters, then no parameters are allowed when the mnemonic is invoked.

Finally, the user supplies the actual M code necessary to perform the device handling function associated with the mnemonic. Within this code, the user can obtain the parameters that were passed to the mnemonic by referencing a set of special variables maintained by MSM for mnemonic functions. The special variables $1 through $9 contain the parameters that were passed to the function, and the $0 special variable contains a count of the number of parameters that were passed by the function.

In the M code that is specified, the user can access the $0 through $9 special variables in the same manner that is used to access the standard MSM special variables (for example: $X, $Y, $ZA). The $DATA function returns a 1 (if defined) or 0 (if not) when used with $0 through $9. The M code associated with the mnemonic function cannot alter the value of these special variables.

The following example illustrates how an M program can use a mnemonic to position the cursor on the terminal screen. In the example, it is assumed that a user-defined mnemonic namespace of Q102 was previously defined, and within this namespace, a mnemonic of CUP was defined for cursor positioning. The following code positions the cursor to row 10 and column 55 on the screen before writing the specified text.

USE 0::"Q102"

WRITE /CUP(10,55),"Customer Number:"

In this example, two parameters are passed to the CUP mnemonic. The first parameter, 10, is contained in the $1 variable and the second parameter, 55, is contained in the $2 variable. The $0 variable contains 2 to indicate that two parameters were passed. In this example, the following M code is associated with the CUP mnemonic.

W *27,$C($1+31),$C($2+31) S $Y=$1,$X=$2

The WRITE command in this example outputs the actual escape sequence required by the terminal to position the cursor. The SET command updates the values of $X and $Y to match the new cursor position. Refer to "MSM Special Variables" in this manual for additional information on the $X and $Y special variables.

See Also:

SYSGEN Mnemonic Namespace Options

Delete Existing Namespace


SYSGEN Mnemonic Namespace Options

The following example illustrates how the mnemonic namespace option of the SYSGEN program is invoked. Detailed examples are provided to illustrate how to create, edit, and delete namespaces.

Select Option: 13 - Mnemonic Namespaces

Select Mnemonic Namespace Option:

1 - List All Defined Namespaces

2 - Add New Namespace

3 - Copy Namespace To New Name

4 - Edit Existing Namespace

5 - Delete Existing Namespace

6 - Rename Existing Namespace

7 - Export Namespaces

8 - Import Namespaces

Select Option:

List All Defined Namespaces

Use this option to list all of the mnemonic namespaces that are known to the system. It lists the names of the built-in namespaces as well as the names and  definitions of user-defined namespaces. Specify the output device where the listing is to take place. The following sample terminal session illustrates the List function.

Select Option: 1 - List All Defined Namespaces

Enter output device <76>: RETURN

Namespace names defined internally to MSM-PC/PLUS:

         'X3.64-1979'

         'ZWINTERM'

Namespace names defined by SYSGEN:

          None.

Select Option:

Add New Namespace

Use this option to create a new mnemonic namespace. Enter a unique identifier that is to be associated with the namespace, one or more mnemonic names, and the complete definition for the mnemonic. The following sample terminal session illustrates the Add function.

Select Option: 2 - Add New Namespace

Enter new Namespace name: ?

Enter the name of a Mnemonic Namespace to be defined. The name can consist of up to 15 alpha numeric characters.

Enter '^L' for a list of currently defined Namespaces.

Enter new Namespace name: QUME

Enter mnemonic name: ?

Enter name of mnemonic to be edited, added, or deleted.

To delete a mnemonic, prefix it with a '-'.

Enter '^L' for a display of defined mnemonics.

Mnemonic name format is:

1 to 15 characters,

Leading character is limited to a letter or '?'

Remaining characters may be a letter or numeric

Enter '^' to exit.

Enter mnemonic name: CLEAR

Does mnemonic change $X <N>: ?

Respond with Y if the mnemonic causes $X to change. If you answer yes, make sure the M code you enter for the mnemonic does a 'SET $X=value' after completing.

Respond with N if the mnemonic does not cause $X to change. If you answer no, the value of $X will be preserved during execution of the mnemonic.

Respond with '^' to backup to previous prompt

Does mnemonic change $X <N>: N

Does mnemonic change $Y <N>: ?

Respond with Y if the mnemonic causes $Y to change. If you answer yes, make sure the M code you enter for the mnemonic does a 'SET $Y=value' after completing.

Respond with N if the mnemonic does not cause $Y to change. If you answer no, the value of $Y will be preserved during execution of the mnemonic.

Respond with '^' to backup to previous prompt

Does mnemonic change $Y <N>: N

Enter minimum number of parameters <0>: ?

Enter the minimum number of parameters required for successful execution of the mnemonic.

The minimum acceptable value is 0.

Enter minimum number of parameters <0>: 0

Enter maximum number of parameters <0>: ?

Enter the maximum number of parameters required for successful execution of the mnemonic.

The minimum acceptable value is 0.

Enter maximum number of parameters <0>: 0

Enter M code for performing mnemonic function  > ?

Enter M code to perform the device specific function associated with the mnemonic. For example, the following code will move the cursor to row $1, and column $2 on an ANSI terminal. The $1 special variable contains the value of the first argument of the mnemonic, and the $2 variable contains the value of the second argument. Note that the code to update $X and $Y, if needed must be specified here as well.

W *27,"[",$1,";",$2,"H" S $Y=$1,$X=$2

Enter M code for performing mnemonic function

> W *27,"Y"

Mnemonic    Set    Parms

 name      $X/$Y  Min/Max    M Code

--------   -----  -------    ---------

CLEAR       ---     0,0      W *27,"Y"

 .

 .

 .

Additional Mnemonic Definitions

 .

 .

 .

Enter mnemonic name: CUP

Does mnemonic change $X <N>: Y

Does mnemonic change $Y <N>: Y

Enter minimum number of parameters <0>: 2

Enter maximum number of parameters <2>: 2

Enter M code for performing mnemonic function

     > W *27,$C($1+31),$C($2+31) S $Y=$1,$X=$2

Mnemonic    Set    Parms

 name      $X/$Y  Min/Max    M Code

--------   -----  -------    ----------------------------

CUP        $X,$Y    2,2      W *27,$C($1+31),$C($2+31)

                               S $Y=$1,$X=$2

Enter mnemonic name: ^L

Mnemonic    Set    Parms

 name      $X/$Y  Min/Max    M Code

--------   -----  -------    ----------------------------

BLINK       ---     0,0      W *27,"G2"

CLEAR       ---     0,0      W *27,"Y"

CUP        $X,$Y    2,2      W *27,$C($1+31),$C($2+31)

                               S $Y=$1,$X=$2

REVERSE     ---     0,0      W *27,"G4"

UNDERLINE   ---     0,0      W *27,"G8"

Enter mnemonic name: RETURN

Select Option:

Copy Namespace to New Name

Use this option to copy an existing mnemonic namespace to a new mnemonic namespace (that is, create a new namespace which is identical to an old namespace). This option generally is used when the new namespace is very similar to the old one. After the new namespace is created, it can be edited.

Enter the name of an existing namespace and for a unique identifier to be associated with the new namespace. The following sample terminal session illustrates the Copy function.

Select Option: 3 - Copy Namespace To New Name

Select Namespace to be copied: ?

Enter the name of the Mnemonic Namespace to be copied. The name you choose must be defined, but cannot be a built-in Namespace.

Enter '^L' for list of currently defined Namespaces.

Select Namespace to be copied: ^L

Namespace names defined internally to MSM-PC/PLUS:

          'X3.64-1979'

          'ZWINTERM'

Namespace names defined by SYSGEN:

         'Q102'

Select Namespace to be copied: Q102

Enter new Namespace name: Q105

.....! done.

Select Option:

Edit Existing Namespace

Use this option to edit one or more mnemonic definitions within an existing mnemonic namespace or to add new mnemonic definitions to an existing mnemonic namespace. Enter the name of an existing namespace and a mnemonic identifier. If the identifier exists, the system prompts you to enter editing information. If it does not exist, the system prompts you for the information necessary to create the entry. The following sample terminal session illustrates the Edit function.

Select Option: 4 - Edit Existing Namespace

Select Namespace to edit: ?

Enter the name of an existing Namespace to be edited. You will be allowed to create new mnemonics for this Namespace, or edit or delete existing ones.

Enter '^L' for list of currently defined Namespaces.

Select Namespace to edit: ^L

Namespaces defined internally to MSM-PC/PLUS:

          'X3.64-1979'

          'ZWINTERM'

Namespaces names defined by SYSGEN:

          'QUME'

Select Namespace to edit: QUME

Enter mnemonic name: ?

Enter name of mnemonic to be edited, added, or deleted.

To delete a mnemonic, prefix it with a '-'.

Enter '^L' for a display of defined mnemonics.

Mnemonic name format is:

1 to 15 characters,

Leading character is limited to a letter or '?'

Remaining characters may be a letter or numeric

Enter '^' to exit.

Enter mnemonic name: ^L

Mnemonic    Set    Parms

 name      $X/$Y  Min/Max    M Code

--------   -----  -------    ----------------------------

BLINK       ---     0,0      W *27,"G2"

CLEAR       ---     0,0      W *27,"Y"

CUP        $X,$Y    2,2      W *27,$C($1+31),$C($2+31)

                               S $Y=$1,$X=$2

REVERSE     ---     0,0      W *27,"G4"

UNDERLINE   ---     0,0      W *27,"G8"

Enter mnemonic name: EL

Does mnemonic change $X <N>: N

Does mnemonic change $Y <N>: N

Enter minimum number of parameters <0>: 0

Enter maximum number of parameters <0>: 0

Enter M code for performing mnemonic function

    > W *27,"[G1"

Mnemonic    Set    Parms

 name      $X/$Y  Min/Max    M Code

--------   -----  -------    --------------------

EL          ---     0,0      W *27,"[G1"

Enter mnemonic name: UNDERLINE

Does mnemonic change $X <N>: N

Does mnemonic change $Y <N>: N

Enter minimum number of parameters <0>: 0

Enter maximum number of parameters <0>: 0

Edit M code for mnemonic:

   > W *27,"G8"

   Replace: G8 With: G9 Replace: RETURN

   > W *27,"G9"

Replace: RETURN

Mnemonic    Set    Parms

 name      $X/$Y  Min/Max    M Code

--------   -----  -------    --------------------

UNDERLINE   ---    0,0       W *27,"G9"

Enter mnemonic name: RETURN

Select Option:


Delete Existing Namespace

Use this option to delete a user-defined namespace. The system does not allow built-in namespaces to be deleted. Enter the name of the namespace to be deleted. The following sample terminal session illustrates the Delete function:

Select Option: 5 - Delete Existing Namespace

Select Namespace to be deleted: ?

Enter the name of the Mnemonic Namespace to be deleted.

Enter '^L' for list of currently defined namespaces.

Select Namespace to be deleted: ^L

Namespace names defined internally to MSM-PC/PLUS:

         'X3.64-1979'

         'ZWINTERM'

Namespace names defined by SYSGEN:

         'Q102'

         'Q105'

Select Namespace to be deleted: Q105

Are you sure <N>: Y

Deleting........done.

Select Namespace to be deleted: RETURN

Select Option:

Rename Existing Namespace

Use this option to rename a user-defined namespace. The system does not allow built-in namespaces to be renamed. Enter the old and new names of the namespace. The following sample terminal session illustrates the Delete function.

Select Option: 6 - Rename Existing Namespace

Select Namespace to be renamed: ?

Enter the name of the Mnemonic Namespace to be renamed.

Enter '^L' for list of currently defined namespaces.

Select Namespace to be renamed: ^L

Namespace names defined internally to MSM-PC/PLUS:

         'X3.64-1979'

         'ZWINTERM'

Namespace names defined by SYSGEN:

         'Q102'

         'Q105'

Select Namespace to be renamed: Q102

Enter new Namespace name for 'Q102': QUME

.....! done.

Select Option:

Export Namespaces

Use this option to save a user-defined namespace to an external file so that it can be copied to another system. Enter an output device and  select the namespaces to be exported. The following sample terminal session illustrates the Export function.

Select Option: 7 - Export Namespaces

Enter output device <HFS>: RETURN

File Name: QUME.NAM

Enter size of save medium (if applicable): RETURN

Enter comment for dump header: Namespaces for QUME crts

Mnemonic namespace selector: Q102

Mnemonic namespace selector: Q105

Saving ...

^SYS

^SYS

Save complete.

Import Namespaces

Use this option to load user-defined namespaces from an external file that was created by the Export Namespaces option. Enter the input device. The following sample terminal session illustrates the Import function.

Select Option: 8 - Import Namespaces

Enter input device <HFS>: RETURN

File Name: ANSI.NAM

Mnemonic namespace(s) saved at 1:20 PM 27-JUL-97.

Header comment is: ANSI X3.64 Template Mnemonic Namespace

Selective restore <N>: ?

If you chose selective restore, you will be prompted for each Mnemonic Namespace. You must then respond to each prompt to restore the Namespace or skip to the next one.

Enter NO to restore all mnemonic Namespaces that were saved.

Enter ^ to exit without restoring any Mnemonic Namespaces.

Selective restore <N>: RETURN

Restoring...

Mnemonic Namespace: X3.64 TEMPLATE ... Restored

Restore Complete


User-Defined Commands - Overview
Overview

This chapter describes how to write user-defined commands, functions, and special variables in MSM.


Commands, Functions, and Special Variables

MSM provides a mechanism that allows system administrators to define their own commands, functions, and special variables. This enables the system administrator to extend the M language where special functionality is needed. This often is useful when converting from another dialect of M to MSM.

All user-defined commands, functions, and special variables must begin with a prefix of ZZ (for example: ZZMYCMD, ZZMYFUNC). The syntax for user-defined commands is as follows:

Commands	ZZUname{:Postcond}SP{{Parm1} ... {:Parmn}}
Functions	$ZZUname({Parm1}{,...{,Parmn}})
Variables	$ZZUname
In these examples, Uname is the user-defined name for the command, function, or special variable, and Parm1 through Parmn are parameters to be passed to the command or function. The entire name must be specified when the command or function is invoked or the special variable is referenced. Abbreviations are not allowed.

User-defined commands are stored in the %ZZCMNDS routine, functions are stored in the %ZZFUNCS routine, and special variables are stored in the %ZZSVARS routine. These routines reside in the Manager's UCI (MGR) on the system volume group (volume group 0). When the system encounters a user-defined command, function, or special variable, the appropriate routine is invoked at the Uname label (a label in the routine that exactly matches the user-defined name of the command, function, or special variable). If a match is not found, then the command, function, or special variable is considered undefined.

When a user-defined command is encountered, the system internally issues a DO command to the appropriate entry reference (Uname^%ZZCMNDS). The line labels for commands may not contain a formal list. For functions and special variables, the appropriate entry reference (Uname^%ZZFUNCS or Uname^%ZZSVARS) is invoked internally in a way that is similar to an extrinsic function or extrinsic variable. The line label for each user-defined function or variable must end in (). Note that no variables are required between the parentheses because parameters are passed using $ variables.


Passing Parameters to the Routine

When parameters are specified on user-defined commands or functions, they are passed to the M routine using special MSM internal variables. These variables are $0 through $9. The $0 variable contains a count of the number of parameters specified on the user-defined command or function; $1 corresponds to the first parameter, $2 corresponds to the second parameter, and so on. Omitted parameters are passed as the null string. These internal variables are read-only and cannot be modified by the user routine. For user-defined special variables, the value of $0 is always 0.

For user-defined commands, the colon (:) is used as the separator between parameters. The parameters are passed to the user routine as strings. No evaluation of the parameters is performed by the system. The user routine is responsible for performing indirection or XECUTE to evaluate any expressions contained in the parameters. For user-defined functions, the comma (,) is used as the separator between parameters. The parameters are evaluated as expressions, and the results of the evaluation are passed to the user routine. Although user-defined special variables behave like user-defined functions, parameters may not be specified.

Examples

The following examples illustrate, in sequence, a user-defined command, function, and special variable.

%ZZCMNDS ;User-Defined Commands

 ;

SHELL ;Syntax: ZZSHELL with no operands

 ZT:$0>0 "SHELL"

 N X

 I $ZV["PC" S X=$$TERMINAL^%HOSTCMD("COMMAND") Q

 I $ZV["UNIX" S X=$$TERMINAL^%HOSTCMD("sh") Q

 I $ZV["VX" S X=$$TERMINAL^%HOSTCMD("spawn") Q

%ZZFUNCS ;User-Defined Functions

 ;

ACIR() ; area of a circle of radius $1

 ;Syntax: $ZZACIR(radius)

 I $0'=1 Q -1 ; 1 parameter only

 Q $1*$1* 3.1415965 ; r*r*pi

%ZZSVARS ;User-Defined Variables

 ;

TIME() ; $ZZTIME=current time

 NEW

 D INT^%D,INT^%T

 Q %DAT1 " " %TIME

1


Macro Facility - Overview
Overview

The MSM development environment provides a preprocessor that compiles source-code documents, called sources, to produce standard executable M-code routines.

The preprocessor is controlled by preprocessor directives embedded in the source document, and replaces macro symbolic names with text from the macro definitions.

The preprocessor is invoked automatically when a source is saved using the %G editor or MSM-Workstation editor. Comprehensive cross-references may be maintained to track where names and source files are defined and used.

Source preprocessing can be used for the following:

•	Definition of simple macros as constants or expressions.

•	Definition of parameterized macros for more powerful capabilities.

•	Definition of libraries of macros.

•	Macro expansion.

•	Source file inclusion.

•	Conditional inclusion of source code lines.

Advantages of preprocessing include:

•	Hard-wired constant values and complex expressions can be replaced by simple meaningful names.

•	A single copy of a definitions can be reused many times.

•	A single copy of source code can be reused in many places.

•	Macro expansion results in very efficient in-line code.


Definitions

Directive

A directive is a command to the preprocessor. An equivalent term is preprocessor command. Refer to "Preprocessor Directives" in this chapter for a description of all directives.

Keyword

A keyword is a macro that expands to multiple lines of code. Because of its multiple-line definition, it has an alternative syntax and restrictions and is given its own conceptual category. However, it is essentially a multi-line macro.

Library

A library is a pre-constructed collection of macro definitions that can be incorporated together into a source code file by using a single directive. Directives that are related to libraries are described in "Advanced Capabilities" in this chapter.

Macro

A macro is a symbolic name for a string of text. The macro definition defines the symbolic name and its associated text string. The macro reference refers to the symbolic name, which the preprocessor replaces with a definition string. Parameterized macros allow substrings in the definition string to be substituted with corresponding arguments

Source

A source is an M routine or other document stored in a global.

Syntax

The elements of preprocessor syntax include macro names, special prefixes, case, and parameter names.

Macro Names

Macro names are composed of one or more alphanumeric characters.

Special Prefixes

Macro names are referenced by using a special introducer prefix that has a default value of %%. For example, a macro named Maximum is used by placing %%Maximum in M code. If parameterized, the string of actual arguments is parenthesized and passed positionally.

Preprocessor directives are recognized by the presence of the directive prefix as the first non-blank character of a line. This prefix is the character # (pound sign or hash sign). The primary preprocessor command, #define, is used to define macros.

Keywords can be referenced by using an alternative keyword prefix of #%.  If parameterized, the string of actual arguments is passed after a single space in a comma-delimited list, without using parentheses.

Case

Case is not significant for directives, but is significant for names.

Parameter Names

Parameterized macros are indicated by following the macro name in the #define with (parameter list). If the list is empty, formal names $1, $2, ... are used. Alternatively, the list can have any alphanumeric names, if meaningful names are desired.


Basic Usage

This section explains the fundamentals of using the preprocessor.

See Also:

Defining a Macro

Referencing a Macro

Using Parameters

Including a File

Debugging

Generated Comment


Defining a Macro

A macro is defined by placing a line with the following syntax in the source file:

#define MacroName Definition

For example:

#define MDC Micronetics Design Corporation

A macro definition can include other macros, for example:

#define copyright Copyright %%MDC

A macro can be parameterized, using $1, $2, ... as the arguments' formal names:

#define copyright() Copyright %%MDC $1

Alternatively, alphanumeric names can be used as the arguments' formal names:

#define copyright(from,to) Copyright %%MDC from-to

A definition can have multiple lines and include labels:

#define ErrorTrap

Trap	;

W "Error, $ZT=",$ZT

Q

#enddef


Referencing a Macro

Macros are referenced by using their name in a line of code, prefixed by the macro introducer string, which has a default value of %%. For example, the definition of %%copyright in "Defining a Macro" above can be used in the following:

W "Program ABC %%copyright(1997,1998)."

which expands to:

W "Program ABC Copyright Micronetics Design Corporation 1997-1998."

Most simple macros can appear in the middle of a line, surrounded by other code. However, macros that expand to multiple lines of code cannot appear in the middle of a line (for example, within the scope of a single-line If or For command; if they are used in this way, a comment is placed in the generated routine to indicate an error).

Macros on lines within block-structured subroutines retain the specified execution level (as indicated by leading dots), as do all generated lines if the macro expands to multiple lines.

An alternate keyword prefix #% may be used to refer to macros.  In this case, parameters are passed as comma-delimited arguments rather in a parenthesized parameter list.  This produces a "keyword" command with arguments.  The following are equivalent:

%%copyright(1995,1996)

and

#%copyright 1995,1996

The #% prefix is intended for use with macros which expand to multiple lines.  The syntax is a reminder that such a multi-line macro should not be embedded in another line, though there are also other safeguards which prevent this error.  Use of the #% syntax is a matter of preference; the %% prefix may be used everywhere.


Using Parameters

The number of actual parameters present when a macro is expanded is provided in $0. The default names for parameters are $1, $2, and so on, although alphanumeric names can be used. The full list of all the parameters supplied to the macro is provided in $*.

If alphanumeric names are used for formal parameters, the names must not conflict with real variable names that might be passed as parameters. The use of a naming convention prevents such conflicts.

The formal list can specify fewer parameters than in the definition, or none at all. However, the macro definition must have at least (); without the parentheses, a macro that takes no arguments is defined.

Arguments without formal names that are passed during macro use are assigned names in the $n form.

When a macro is used, if more actual arguments are specified than are used in the definition, the macro expansion generates an error in comment form.

The following illustrates using parameters in a macro:

#define EXAMPLE() W "No params=$0  Param 1=$1  All params=$*",!

Then the macro %%EXAMPLE("Test",1,2) expands to:

W "No params=3  Param1=""Test""  All params=""Test"",1,2",!

Using named parameters is just a case of specifying them on the macro definition, for example:

#define EXAMPLE2(one,two) W "First param=",one,!,"Second param=two",!

Then %%EXAMPLE2(1,2) expands to:

W "First param=",1,!,"Second param=2",!

Note that the 'two' parameter is replaced inside the quoted string so make sure any parameter names are not accidentally contained within part of a string in the definition.

For further details and advanced capabilities, see Additional Parameter Functions.


Including a File

The #include directive is used to include a source file in another file. The following example illustrates how to include common subroutines called UTILITY in another routine.

#include UTILITY

Frequently, common definitions or libraries for a package are combined into a header file. For example:

#include BLD.HDR

Although naming conventions can be used (for example, .HDR for headers, .LIB for libraries, .INC for include), they are arbitrary and are not required.


Debugging

Because debugging complicated macros can be challenging, it is best to avoid creating unnecessarily complex macros.

The pre-expansion form of lines that contain macros can be included in generated code as comments. These comments are placed at execution level 10 by preceding the line with ten dots so that structured subroutine logic is not damaged by the inclusion of comments. The generation of pre-expansion comments is activated by using the following:

#comment

Expansion at all intervening levels can be recorded in comments by using the following:

#comment all

Comments are turned off by using the following:

#nocomment


Generated Comment

The preprocessor inserts a comment line as the second line of generated routines. The following format is used:

;;GENERATED from <serial#> <uci> <sourcename> <version#> <date> <time>

For example:

;;GENERATED from 1111494 DEV,WDD Test v1 23Mar98 9:49pm


Advanced Capabilities

The preprocessor provides additional functionality, including libraries, special macros, parameter functions, multi-line and computed definitions, and special functions.

See Also:

Libraries

Conditional Compilation

Special Macros

Additional Parameter Functions

Multi-Line Definitions

Computed Definitions

System Functions

Changing the Prefix


Libraries

Libraries are used to store macro definitions.

Defining Libraries

The #makelib directive (re-)initializes a library.

A library is defined to create a group of macro definitions that are used together in several places and to avoid the small overhead of compiling macro definitions. After creation of a source document that contains a #makelib directive and a library name, any number of macro definitions can be placed in the library.

#makelib Standard

#define ...

Macro definitions are stored in a global other than the default global, ^ZMSMMAC, by including an additional argument, as illustrated in the following example.

#makelib Standard ^MYMACS(1)

When defining a library, the intention is to define macros, not to generate a routine.  A #noroutine directive appears at the top of a source which is a library definition.  See the section on #noroutine in "Preprocessor Directives."

Updating Libraries

The #updlib directive appends to an existing library. If no library exists, #updlib creates a library.

A single library can include groups of macros from different source files by using #updlib. For example, the following line appears at the top of a source that augments the Standard library.

#updlib Standard

Using Libraries

The #library command incorporates one or more libraries of macro definitions for use in a program.

A #library command, followed by the name(s) of one or more libraries, specifies the search path that is used to find macro definitions. The order of the names is significant because it defines the order of the search.

#library Custom,Standard

A pre-existing path is modified by placing new library names at the beginning or end of the path. A name followed by + (plus sign) is placed at the front of the path; a + followed by a name places the name at the end of the path. The following example illustrates the #library Custom,Standard path.

After #library MyOwn+, the search path is "MyOwn,Custom,Standard."

After #library +TheEnd, the search path is "MyOwn,Custom,Standard,TheEnd."

Libraries that are not in the standard global for macros must be identified by including the physical global name where the library resides. For example:

#library ^%BLDM("AL",1)

Macros that are defined in the source or in #include files take precedence over library macros of the same name.


Conditional Compilation

The #if, #ifdef, and #ifndef directives and the associated #elseif, #else, and #endif directives are used to include code conditionally in the generated routine. As the following example illustrates, debugging code is removed from a routine by commenting out the #define line.

#define Debug 1

#ifdef Debug

w "Debugging..." d ^Whatever

#endif

...

The #if blocks can be nested. Indentation of lines is used to clarify the blocks.


Special Macros

Array Macros

The #defarray variant of the #define directive is used to define arrays. For example:

#defarray tmp ^XSCRATCH($J)

can be used as:

K %%tmp      	generates      K ^XSCRATCH($J)

S %%tmp(1)=1	generates      S ^XSCRATCH($J,1)=1

Null Macro

Expressions can be evaluated at pre-processing time with the built-in null macro, whose name is identical to the current macro introducer prefix (by default, %%). For example, if the following definitions are present:

#define Green	2

#define Blue	4

#define Cyan1	%%Green+%%Blue

#define Cyan2	%%(%%Green+%%Blue)

Then:

%%Cyan1 	generates	2+4

%%Cyan2	generates	6

%%(%%Cyan1)	generates	6

ZMsmOffset

This macro expands to the label+offset^ routine of the line in which it appears. For example:

ROUT	;

...

LAB	;

I X="" S ERR="%%ZMsmOffset" Q

This macro expands to:

I X="" S ERR="LAB+1^ROUT" Q

ZMsmPreviousLabel

This macro expands to the label that precedes the current line. For example, if a routine contains the following:

FUNCA	;

...

S $ZE="q%%ZMsmPreviousLabel^"_$T(+0)

The macro expands to:

FUNCA	;

…

S $ZE="qFUNCA^"_$T(+0)

ZMsmTimestamp

This macro expands to a timestamp like the first line timestamp. For example:

W "Routine filed at %%ZMsmTimestamp"

can expand to:

W "Routine filed at [ 7/25/95  4:45pm ]"

Different date formats are available by supplying an optional parameter, %%ZMsmTimestamp(Format).

Format	Example

1	[ 7/25/95 4:45pm ]

2	19950725

3	199507251645

4	25Jul95 16:53

5	25Jul95 at 4:53pm


Additional Parameter Functions

In addition to the parameter capabilities discussed in "Using Parameters" in this chapter, the preprocessor provides the following advanced parameter functions.

Default Parameter Values

Default values can be given to parameters on macro definitions. These values are used if no actual argument is present when the macro is used. The default is specified after the parameter, which is followed by a colon (:). For example:

#define Lock(aName,aTimeout:0) L +^LOCKS(aName):aTimeout

%%Lock(Id)    generates    L +^LOCKS(Id):0

The $0 parameter can be used in conjunction with #if...#endif to generate different macro definitions, based on the number of arguments passed.

Quoted Parameters

If a formal parameter which is used in a quoted context in a macro definition is passed an actual argument that contains quotes, it automatically quotes the quotes in the following argument:

#define show(ref) write "ref"

%%show(Node is ^G("B"))    generates    W "Node is ^G(""B"")"

Empty Lists

A macro can be defined as having parameters, even if it has not been given parameters. Such a macro can be used to construct names because the empty "" that begins the empty argument list signals the macro's end.

For example, to assign one prefix to a group of names while allowing the prefix to be easily changed, a parameterized macro is defined for the prefix.

#define prefix() 	^%App

#define nam 	%%prefix()nam

#define id 	%%prefix()id

D %%nam,%%id    generates    D ^%Appnam,^%Appid

This system can be built entirely with non-% names by removing the % from the definition of %%prefix.

The same process can be used to build variables with unique names. For example, in routines that must deal with by-reference arguments (which refer to variables that potentially have any name), variable names that are unlikely to collide can be defined.

#define junk()	xYzZy

#define from	%%junk()1

#define to	%%junk()2

S (%%from,%%to)=""    generates    S (xYzZy1,xYzZy2)=""


Multi-Line Definitions

A multi-line macro definition is bracketed by #define and #enddef directives.

#define MultiLiner

w "line 1"

w "line 2"

#enddef

Multi-line macros are non-embeddable. They cannot be embedded in a line of code, because unpredictable consequences may result when part of a line is at the beginning of the code and a bit is at the end, several lines below. Even a single-line macro can be defined as non-embeddable (for example: a macro that contains an IF statement may cause problems). A #define...#enddef construct allows definition of a non-embeddable single-line macro.

Some macros have multi-line definitions, although the resulting definition expands into a simple statement that should be embeddable. For example, when #if...#else...#endif logic is used to compute a macro definition which has multiple alternatives, a #define...#enddef block is required to incorporate the #if logic. To allow inclusion of such a macro within a line of code (rather than making it non-embeddable), a switch is introduced. The /EMBED switch is used to make a macro with a multi-line definition embeddable. For example:

#define Disable(Obj) /EMBED

#if $L("Obj",".")<3

%%Set(Obj.ACTIVE,0)

#else

%%Enable(obj,0)

#endif

#enddef


Computed Definitions

A program can be used to build arbitrarily complex macro definitions. The program is invoked with the null macro and the result is returned in variable Val. For example:

#define Do(win,parms:"")	%%(D Do^UTL(win,parms))

UTL	;

Do(w,p)	; compute macro

...

S Val="whatever"

Q

If the default value "" for parameters is not included and if parameters are omitted in a 1- argument call, a syntax error results from D Do^UTL(win,). If the default value is used, such an error is impossible.


System Functions

The following functions are defined in the macro preprocessor and can be used by macros that compute their own definitions.

Function	Description
DEFINED(Name)	Returns True if macro Name is defined.
SS(X)	Strips leading spaces.*
STS(X)	Strips trailing spaces.*
QQ(X)	Quotes—double-up quotes.*
HQ(X)	Halves quotes.*
* May also be called as a procedure with parameter X passed by-reference.


Changing the Prefix

The prefix %% can be changed with the #prefix directive to any string that does not contain a #. For example:

#prefix $$$

The prefix in force is the prefix that is used to find macro references. If the prefix is changed, macros that use the previous prefix are not seen as macros and do not expand. This capability can be used by program generators to generate programs containing macros that are expanded only after the programs are constructed.

The default prefix can be reset using the directive as follows:

#prefix


Preprocessor Directives

A description of the use and syntax of all preprocessor directives follows.

See Also:

#comment

#defarray

#define

#deflabel

#if, #elseif, #else, #endif

#ifdef, #ifndef

#include

#library

#makelib

#nocomment

#noroutine

#prefix

#routine

#undefine

#updlib

#x


#comment

Turns on the insertion of pre-expansion lines of code that contain macros into the generated code as comments.

Syntax

#comment [all]

Definition

The comments are placed at execution level 10 (the lines have 10 leading dots) to avoid terminating structured subroutine blocks and . Lines that sequentially follow the #comment are treated in this manner.

The #comment all form shows all intermediate expansions. Without the "all," only the initial pre-expansion form is shown.

See also #nocomment.


#defarray

Defines a macro to be used for referencing an array.

Syntax

#defarray MacroName Definition

Definition

Parameter	Description
MacroName	An alphanumeric name beginning with an alpha, with no parameters.
Definition	The macro definition, a global or local variable name.
This directive defines a name to be used for constructing array references. The macro expansion depends on the context. When the macro is used, if the name is immediately followed by a "(", an array reference is constructed by adding the subscripts following the "(" to those (if any) in the Definition.

The directive may be abbreviated as #defarr.


#define

Defines a macro.

Syntax

#define MacroName[ParmList] Definition

or

#define MacroName[ParmList] [/Switch]...

Definition

...

#enddef

Definition

Parameter	Definition
MacroName	An alphanumeric name that begins with an alphabetic character; any reasonable length can be used.
ParmList	([Parm,...]) where Parm is an optional formal name for a parameter.
Definition	The macro definition; requires #endef form if null or multi-line.
Switch	One of the defined switches: /EMBED allows embedding of a multi-line definition.
The #define directive defines a simple text-replacement macro that is unaware of M syntax. It may be abbreviated as #def.

A macro can have either no parameters or a variable (one or more) number of parameters. If a macro is defined with no ParmList, it cannot take parameters. A ParmList with no parameters is allowed ("()"), which indicates that parameters are expected. Any parameter can be missing. Parameters are placed in $1, $2, and so on. The $0 always contains the number of parameters actually passed.

If the Definition contains macro names and preprocessor directives, they are not processed until the macro is used.

Meaningful formal names of parameters optionally can be specified for more self-documenting macros.

The same MacroName can be defined more than once. The definitions are stacked, and the most recently specified definition of a MacroName is used. As a result, specialized libraries and local definitions can override system definitions.

A macro name may be undefined using #undefine.

A multi-line macro definition requires use of a #def…#enddef block.  See "Multi-Line Definitions" for more information.


#deflabel

Defines a unique local label or variable, and is guaranteed to be unique in a routine as long as the prefix is not used directly.

Syntax

#deflabel LabelName[,...]

Definition

Parameter	Definition
LabelName	A valid macro name.
A macro definition that consists of a defined label prefix, followed by an integer, is computed for LabelName. The prefix defaults to zTmp and can be modified by setting system variable LabPref.


#if, #elseif, #else, #endif

Provides for conditionally included code, based on a preprocessing-time condition.

Syntax

#if Condition

Code

#elseif Condition

Code

#else

Code

#endif

Definition

 Parameter        Definition

Condition	A valid M expression

Code	Valid M code

During preprocessing, sections of code can be conditionally included or ignored. The #if...#endif pair brackets code that is included only if Condition is true. For example, a variable that is set by an earlier #x command can be tested by an #if.  Multiple alternatives are included by using multiple #elseifs, and a catch-all condition is included by using #else. Conditions can be nested.


#ifdef, #ifndef

Provides for conditionally included code, based on the presence or absence of a defined macro.

Syntax

#ifdef MacroName

or

 #ifndef MacroName

Code

#else

Code

#endif

Definition

Parameter	Description
MacroName	A valid M expression.
Code	Valid M code.
During preprocessing, sections of code can be conditionally included or ignored. The #ifdef...#endif pair brackets code that is included only if MacroName is defined. Alternatively, the #ifndef...#endif pair brackets code is included only if MacroName is not defined. Alternate code is included when #else is used.


#include

Includes source code; redirects input stream.

Syntax

#include FileName

Definition

Parameter	Description
FileName	The name of a file.
During preprocessing, a selected file is scanned and processed. A file can include other files by reference with the #include directive. The input stream comes from the included file until the end is reached; it then reverts to the line after the #include in the original file. The #includes can be nested.

FileName generally is a simple name that refers to the latest version of the source with that name (which is stored in the corresponding node of the source global). Alternatively, FileName can be a full global reference. If the last subscript of the global reference is * (asterisk), the greatest subscript is substituted, thereby simulating use of the latest version.


#library

Specifies the path to libraries.

Syntax

#library [+]LibraryFileName,...

or

#library LibraryFileName[+],...

Definition

Parameter	Description
LibraryFileName	The name of a libraryfile in ^ZMSMMACSRC, or a full global reference whose descendant nodes are the macros.
This command specifies libraries in the order which they are to be searched when a macro definition is looked up. The presence of [+] modifies the existing search path, so +LibraryFileName appends and LibraryFileName+ prepends the library to the existing path. If [+] is not present, the path is entirely respecified.

Libraries are constructed by sources using the #makelib or #updlib directives.


#makelib

Creates a macro library.

Syntax

#makelib LibraryName [GlobalReference]

Definition

Parameter	Description
LibraryName	The name of the macro library; the default is the current source name.
GlobalReference	The global in which to store the library; the default is ^ZMSMMAC.
The #makelib command initiates the creation of a macro library. Macro libraries are stored in GlobalReference(LibraryName,1).

The #makelib command first clears the indicated library of all references. During this process, if the system finds macro definitions that originate from sources other than the current source, warnings that identify the macro and its original source are logged.

Subsequent macro definitions then are added to the library. Different sources can contribute to the same library, but only if #updlib is used.


#nocomment

Stops the inclusion of unprocessed source code lines as comments.

Syntax

#nocomment

Definition

This command turns off the generation of comments that document the pre-expansion form of lines with macros. It also applies to lines that sequentially follow the #nocomment command. See also #comment.


#noroutine

Prevents generation of an M routine.

Syntax

#noroutine

Definition

The #noroutine command turns off the generation of an M routine by the preprocessor. This command is placed at the top of sources that are used as include files (such as header files) and files that are used to build macro libraries. See also #routine.


#prefix

Defines the prefix used to identify a macro reference.

Syntax

#prefix [Literal]

Definition

Parameter	Description
Literal	A character string to serve as the macro introducer. If omitted, the default prefix is reset.
This advanced command defines the prefix that is used to introduce macro references.

The user can override the default, "%%", if a different prefix is preferred. For example:

#prefix ~

#prefix $$$

#prefix {MACRO}

The #prefix command also can temporarily deactivate macro definitions (for example, if an application generates programs that include macro definitions and references which are to be preprocessed later, rather than during program generation). Each macro definition in a library must have access to the context of the prefix's definition. A library's default prefix is assumed to apply to every macro in the library that does not record an override of the prefix.


#routine

Specifies the name of a routine to be generated.

Syntax

#routine RoutineName

Definition

Parameter	Description
RoutineName	A valid M routine name.
This command names the routine to be generated when a source program is preprocessed. If the command is not present, the first-line label determines the routine name. This command primarily is used to generate a different routine than the one named by the first line. See also #noroutine.


#undefine

Removes a macro definition.

Syntax

#undefine MacroName

Definition

Parameter	Description
MacroName	A valid M expression.
This command removes the current definition of a macro name. This unstacking process can either uncover and reinstate an earlier definition of the same macro name, or reveal a library macro that was overlaid by a local definition.

This directive may be abbreviated as #undef.


#updlib

Updates a macro library.

Syntax

#updlib LibraryName [GlobalReference]

Definition

Parameter	Description
LibraryName	The name of the macro library; the default is the name of the current source.
GlobalReference	The global in which to store the library; the default is ^ZMSMMAC.
The #updlib command updates a macro library. Macro libraries are stored in GlobalReference(LibraryName,1).

The #updlib command first clears the indicated library of references that originates from the current source, leaving all libraries from other sources untouched. Subsequent macro definitions are then added to the library. Different sources can contribute to the same library when  #updlib is used. When a library is to be defined by a single source, consider using #makelib.


#x

Executes M code during preprocessing.

Syntax

#x Code

Definition

Code	Valid M code.

During preprocessing, lines of M code can be executed. This command is used to set and inspect variables or to generate code for output.


Technical Components

This section provides descriptions of macro routines and globals.

Routines

The following table provides a description of macro routines that are used by the preprocessor.

Routine	Description
%EDP	Performs macro lookup, expansion, parameter substitution.
%EDP1	Processes directives, has supplementary entry points.
Globals

The following table provides a description of macro globals that are used by the preprocessor.

Global	Description
^ZMSMSRC	The sources translated by the preprocessor are located, by default, in global ^ZMSMSRC: ^ZMSMSRC(SourceName,Version#,Line#) = Text
^ZMSMMAC	Macro definitions are stored, by default, in global ^ZMSMMAC, which has the following basic structure:  ^ZMSMMAC(Library,Version#,MacroName,Line#) = Text