MSM-Language Reference Manual v.1.0 (Micronetics) 1996

MSM
Language Reference Manual
Micronetics Design Corporation

Disclaimer
Micronetics Design Corporation makes no representations or warranties with respect
to this manual. Further, Micronetics Design Corporation reserves the right to make
changes in the specification of the product described within this manual and without
obligation of Micronetics Design Corporation to notify any person of such revision or
changes.
The software described in this document is furnished under a license by Micronetics
Design Corporation and may only be used or copied in accordance with the terms of
such license.
This document is copyrighted. Micronetics Design Corporation grants you the right
to download and copy this document only in conjunction with a validly licensed copy
of the software and subject to all provisions of the software license agreement.
Copyright  1996
Micronetics Design Corporation
1375 Piccard Drive
Rockville, Maryland 20850
Telephone: 301-258-2605
Fax: 301-840-8943
E-Mail: info@micronetics.com
WWW: www.micronetics.com
Contents
Preface i
Acknowledgment........................................................................................................................ i
Documentation Conventions ..................................................................................................... ii
Chapter 1 Language Syntax 1

Overview ....................................................................................................................................1
MSM Character Set....................................................................................................................2
Delimiters.....................................................................................................................2
Prefixes ........................................................................................................................2
Line Terminators..........................................................................................................3
Format Characters........................................................................................................3
Control Characters .......................................................................................................4
Language Components ...............................................................................................................5
Commands ...................................................................................................................5
Functions......................................................................................................................5
Special Variables .........................................................................................................5
Command Lines and Routines....................................................................................................6
Command and Command Line Syntax.........................................................................6
Routine Structure .........................................................................................................7
Entering Command Lines into a Routine .....................................................................8
Block Structured Subroutines ......................................................................................8
Data Types ..................................................................................................................... ..........10
Numbers and Strings..................................................................................................10
Literals ....................................................................................................................... 11
Constants....................................................................................................................11
Object References ......................................................................................................11
Variables ..................................................................................................................................12
Local Variables ..........................................................................................................12
Global Variables ........................................................................................................12
Arrays and Subscripts ................................................................................................13
Naked References ......................................................................................................14
Collating Sequence ....................................................................................................14
Extended Global References......................................................................................15
UCI Translation and Replication ...............................................................................16
External Program Calls ..............................................................................................16
Special Variables .......................................................................................................16
Objects .....................................................................................................................................17
Default Values ...........................................................................................................18
Chapter 2 Expression Elements 19

Overview ..................................................................................................................................19
Building Expressions................................................................................................................19
MSM Language Reference Manual Contents • iii

Evaluating Expressions ........................................................................................................... 20
Numeric Expressions............................................................................................................... 21
String Expressions................................................................................................................... 21
Truth-Valued Expressions ....................................................................................................... 21
Post-Conditional Expressions.................................................................................................. 21
Chapter 3 MSM Operators 23

Overview ................................................................................................................................. 23
ADDITION (+) ....................................................................................................................... 24
AND (&) ................................................................................................................................. 25
CONCATENATE ( _ )............................................................................................................ 26
DIVISION (/) .......................................................................................................................... 27
EQUAL TO (=) ....................................................................................................................... 28
EXPONENTIATION (**) ...................................................................................................... 29
GREATER THAN (>) ............................................................................................................ 30
HEXADECIMAL (#) .............................................................................................................. 31
INDIRECTION (@)................................................................................................................ 32
INTEGER DIVISION (\) ........................................................................................................ 34
LESS THAN (<)...................................................................................................................... 35
MINUS (-)............................................................................................................................... 36
MODULO DIVISION (#) ....................................................................................................... 37
MULTIPLICATION (*).......................................................................................................... 39
NOT (') .................................................................................................................................... 40
OR (!) ...................................................................................................................................... 41
PATTERN MATCH (?) .......................................................................................................... 42
PLUS (+) ................................................................................................................................. 44
STRING CONTAINS ([ ) ....................................................................................................... 45
STRING FOLLOWS (]).......................................................................................................... 46
STRING SORTS AFTER (]]) ................................................................................................. 47
SUBTRACTION () ................................................................................................................. 48
Chapter 4 MSM Commands 49

Overview ................................................................................................................................. 49
BREAK ................................................................................................................................... 50
CLOSE .................................................................................................................................... 52
DO........................................................................................................................................... 53
DO With Parameter Passing.................................................................................................... 55
ELSE ....................................................................................................................................... 57
FOR ......................................................................................................................................... 58
GOTO...................................................................................................................................... 62
HALT ...................................................................................................................................... 64
HANG ..................................................................................................................................... 65
IF ............................................................................................................................................. 66
JOB.......................................................................................................................................... 68
JOB With Parameter Passing................................................................................................... 71
KILL........................................................................................................................................ 73
LOCK...................................................................................................................................... 75
MERGE................................................................................................................................... 78
NEW........................................................................................................................................ 80
OPEN ...................................................................................................................................... 82
QUIT ....................................................................................................................................... 84
READ...................................................................................................................................... 86
SET.......................................................................................................................................... 90
iv • Contents MSM Language Reference Manual

TCOMMIT...............................................................................................................................94
TRESTART .............................................................................................................................95
TROLLBACK..........................................................................................................................96
TSTART ..................................................................................................................................97
USE ..........................................................................................................................................99
VIEW .....................................................................................................................................101
WRITE...................................................................................................................................103
XECUTE................................................................................................................................105
ZALLOCATE ........................................................................................................................107
ZDEALLOCATE ...................................................................................................................110
ZFLUSH.................................................................................................................................111
ZGO .......................................................................................................................................112
ZHOROLOG..........................................................................................................................113
ZINSERT ...............................................................................................................................115
ZLOAD ..................................................................................................................................117
ZMSM....................................................................................................................................119
ZNEW ....................................................................................................................................120
ZPRINT..................................................................................................................................122
ZQUIT....................................................................................................................................124
ZREMOVE ............................................................................................................................126
ZSAVE...................................................................................................................................128
ZSETOBJ ...............................................................................................................................131
ZSYNC...................................................................................................................................134
ZTRAP ...................................................................................................................................135
ZUSE......................................................................................................................................136
ZWRITE ................................................................................................................................137
Chapter 5 MSM Functions 139

Overview ................................................................................................................................139
Intrinsic Functions....................................................................................................139
Extrinsic Functions ..................................................................................................140
$ASCII ......................................................................................................................... ..........144
$CHAR...................................................................................................................................145
$DATA...................................................................................................................................146
$EXTRACT ...........................................................................................................................147
$FIND ....................................................................................................................................149
$FNUMBER ..........................................................................................................................151
$GET......................................................................................................................................153
$JUSTIFY ..............................................................................................................................154
$LENGTH..............................................................................................................................155
$NAME..................................................................................................................................156
$NEXT...................................................................................................................................157
$ORDER ................................................................................................................................159
$PIECE ..................................................................................................................................161
$QLENGTH...........................................................................................................................163
$QSUBSCRIPT .....................................................................................................................164
$QUERY................................................................................................................................165
$RANDOM ............................................................................................................................167
$REVERSE............................................................................................................................168
$SELECT ...............................................................................................................................169
$STACK.................................................................................................................................170
$TEXT ...................................................................................................................................172
$TRANSLATE ......................................................................................................................174
$VIEW ...................................................................................................................................175
MSM Language Reference Manual Contents • v

$ZBN..................................................................................................................................... 177
$ZBname ............................................................................................................................... 179
$ZBOOLEAN ....................................................................................................................... 182
$ZCALL ................................................................................................................................ 185
$ZCRC .................................................................................................................................. 186
$ZCREATEOBJECT ............................................................................................................ 188
$ZDATE................................................................................................................................ 189
$ZDEVICE............................................................................................................................ 191
$ZGETOBJECT.................................................................................................................... 192
$ZHEX .................................................................................................................................. 194
$ZHL ..................................................................................................................................... 195
$ZNEXT................................................................................................................................ 198
$ZOBJREFERENCE............................................................................................................. 200
$ZORDER............................................................................................................................. 201
$ZOS ..................................................................................................................................... 203
$ZPOSITION ........................................................................................................................ 212
$ZPREVIOUS....................................................................................................................... 213
$ZSORT ................................................................................................................................ 215
$ZUCI ................................................................................................................................... 217
$ZVERIFY ............................................................................................................................ 219
$ZWIDTH ............................................................................................................................. 221
Chapter 6 MSM Special Variables 223

Overview ............................................................................................................................... 223
$DEVICE .............................................................................................................................. 224
$ECODE ............................................................................................................................... 225
$ESTACK ............................................................................................................................. 227
$ETRAP ................................................................................................................................ 229
$HOROLOG ......................................................................................................................... 231
$IO ........................................................................................................................................ 232
$JOB...................................................................................................................................... 233
$KEY .................................................................................................................................... 234
$PRINCIPAL ........................................................................................................................ 235
$QUIT ................................................................................................................................... 236
$STACK................................................................................................................................ 237
$STORAGE .......................................................................................................................... 238
$SYSTEM ............................................................................................................................. 239
$TEST ................................................................................................................................... 240
$TLEVEL.............................................................................................................................. 241
$TRESTART......................................................................................................................... 242
$X.......................................................................................................................................... 243
$Y.......................................................................................................................................... 244
$ZA ....................................................................................................................................... 245
$ZB........................................................................................................................................ 246
$ZC........................................................................................................................................ 247
$ZERROR ............................................................................................................................. 248
$ZLEVEL.............................................................................................................................. 249
$ZNAME............................................................................................................................... 250
$ZORDER............................................................................................................................. 251
$ZREFERENCE.................................................................................................................... 252
$ZTRAP ................................................................................................................................ 253
$ZVERSION ......................................................................................................................... 255
vi • Contents MSM Language Reference Manual

Chapter 7 MSM Structured System Variables 257
Overview ................................................................................................................................257
^$DEVICE .............................................................................................................................258
^$GLOBAL............................................................................................................................259
^$JOB.....................................................................................................................................260
^$LOCK.................................................................................................................................261
^$ROUTINE ..........................................................................................................................262
Appendix A ASCII Collating Sequence 263

Overview ................................................................................................................................263
Appendix B Error Processing 265

Overview ................................................................................................................................265
Error Processing.....................................................................................................................266
Default Error Processing..........................................................................................267
User-Defined Error Processing ................................................................................268
Processing Trapped Errors.......................................................................................269
Using the System Error Trap....................................................................................271
Using Downlevel Error Trapping.............................................................................272
Interactive Debugging..............................................................................................272
Format of $ZERROR ...............................................................................................272
MSM Error Codes ..................................................................................................................274
MSM Error Numbers .............................................................................................................277
$ECODE Errors .....................................................................................................................281
Appendix C Mnemonic Namespaces 283

Overview ................................................................................................................................283
ANSI X3.64-1979 Namespace ...............................................................................................284
ZWINTERM Namespace.......................................................................................................288
Attributes .................................................................................................................288
Erase Operations ......................................................................................................289
Error Codes..............................................................................................................290
ZWINTERM Namespace Commands ....................................................................................291
/INIT(TermSpace,Attribute) - Initialize Namespace ................................................291
/END - Release Mnemonic Space............................................................................291
/WOPEN(Win,Row,Col,NumRows,NumCols,Flag) - Open Window ......................292
/WUSE(Win) - Use Window....................................................................................292
/WCLOSE(Win) - Close Window ............................................................................292
/WSCRON - Enable Automatic Display ..................................................................292
/WSCROFF - Disable Automatic Display ...............................................................293
/WDSP - Display Window .......................................................................................293
/WUNDSP - Undisplay Window .............................................................................293
/WMOVE(Row,Col) - Move Window .....................................................................293
/WT(Title,Location,Alignment) - Window Title ......................................................293
/WTSGR(Attribute) - Window Title SGR ...............................................................294
/WBSGR(Attribute) - Window Border SGR............................................................294
/WDSGR(Attribute) - Window Default SGR...........................................................294
/WGETCW - Get Current Window..........................................................................294
/WREFRESH - Refresh Screen................................................................................294
/WCMD(Type) - Clear Display................................................................................295
/WCML(Type) - Clear Line .....................................................................................295
MSM Language Reference Manual Contents • vii

/WWR(Mode) - Change Wrap Mode ...................................................................... 295
/WSC(Scroll) - Change Scroll Mode ...................................................................... 295
/WCSGR(Attribute,Location) - Window Current SGR........................................... 296
/CUR(Display) - Cursor .......................................................................................... 296
/CUP(Row,Col) - Cursor Position ........................................................................... 296
/ED(Type) - Erase Display ...................................................................................... 297
/EL(Type) - Erase Line............................................................................................ 297
/?DR(Char,Repeat) - Line Drawing (optional) ....................................................... 297
/SGR(Attribute) - Change Character SGR .............................................................. 298
SYSGEN Mnemonic Namespaces ........................................................................................ 299
SYSGEN Mnemonic Namespace Options .............................................................. 300
Delete Existing Namespace..................................................................................... 304
Appendix D User-Defined Commands 309

Overview ............................................................................................................................... 309
Commands, Functions, and Special Variables....................................................................... 310
Passing Parameters to the Routine......................................................................................... 311
Appendix E Macro Facility 313

Overview ............................................................................................................................... 313
Definitions............................................................................................................................. 315
Basic Usage ........................................................................................................................... 317
Defining a Macro .................................................................................................... 317
Referencing a Macro ............................................................................................... 317
Using Parameters .................................................................................................... 318
Including a File ....................................................................................................... 318
Debugging............................................................................................................... 319
Generated Comment................................................................................................ 319
Advanced Capabilities........................................................................................................... 320
Libraries .................................................................................................................. 320
Conditional Compilation ......................................................................................... 321
Special Macros........................................................................................................ 321
Additional Parameter Functions.............................................................................. 322
Multi-Line Definitions ............................................................................................ 323
Computed Definitions ............................................................................................. 324
System Functions .................................................................................................... 324
Changing the Prefix................................................................................................. 325
Preprocessor Directives......................................................................................................... 326
#comment................................................................................................................ 326
#defarray ................................................................................................................. 326
#define .................................................................................................................... 327
#deflabel.................................................................................................................. 328
#if, #elseif, #else, #endif ......................................................................................... 328
#ifdef, #ifndef.......................................................................................................... 329
#include................................................................................................................... 329
#library.................................................................................................................... 330
#makelib.................................................................................................................. 330
#nocomment............................................................................................................ 331
#noroutine ............................................................................................................... 331
#prefix..................................................................................................................... 331
#routine ................................................................................................................... 332
#undefine................................................................................................................. 332
viii • Contents MSM Language Reference Manual

#updlib .....................................................................................................................333
#x .............................................................................................................................333
Technical Components ...........................................................................................................334
Glossary of Terms 335
Index 345
MSM Language Reference Manual Contents • ix

x • Contents MSM Language Reference Manual
Preface
Acknowledgment
Micronetics Standard M (MSM) is a full implementation, with extensions, of the
ANSI Standard Specification (X11.1-1990) for the Massachusetts General Hospital
Utility Multi-Programming System. The M language 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. M is a trademark of Massachusetts General Hospital.
MSM Language Reference Manual Preface • xi

Documentation Conventions
The following describes the documentation conventions that are used throughout this
manual.
Convention Description
RET The carriage return key (normally labeled RETURN, RET,
ENTER, etc.).
CTRL/X The Control 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 dialogue are shown in bold to indicate a user
response.
xii • Preface MSM Language Reference Manual

Chapter 1 Language Syntax
Overview
Micronetics Standard M (MSM) is a complete, versatile, and extremely powerful
implementation of the ANSI standard (X11.1 - 1990) 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 Language Reference Manual Chapter 1 Language Syntax • 1

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 "Appendix A,
ASCII Collating Sequence," 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.
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.
'HOLPLWHU &KDUDFWHUV
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.
2 • Chapter 1 Language Syntax MSM Language Reference Manual

3UHIL[HV
^ 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.
/LQH 7HUPLQDWRUV
RET 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.
)RUPDW &KDUDFWHUV
# 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 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.
&RQWURO &KDUDFWHUV
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.
RET 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
The MSM system conforms to the M ANSI standard specification (X11.1 - 1990)
and includes Type A 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.
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.
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.
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" SP SP 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 two 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.
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 4092 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 chapter 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. Note that variable names are
case-sensitive. Variable names that differ only in uppercase or lowercase characters
are distinct.
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 4092 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 chapter 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 4092 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, the system 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> error code). 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 or unexpected results when using naked references. For
example:
I '$D(ÂBC(1)) S ^(1)=^XYZ(1,2) ;does not set ÂBC(1)
I '$D(ÂBC(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 the user to specify
the order in which the subscripts are to be collated. Either numeric sequence or string
sequence can be specified.
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.
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 OLE/2 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, i.e., 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. Thus, 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.
Default Values
OLE/2 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
OLE/2 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 OLE/2 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.

Chapter 2 Expression Elements
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.
MSM Language Reference Manual Chapter 2 Expression Elements • 19

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.
20 • Chapter 2 Expression Elements MSM Language Reference Manual

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.
MSM Language Reference Manual Chapter 2 Expression Elements • 21

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.
22 • Chapter 2 Expression Elements MSM Language Reference Manual

Chapter 3 MSM Operators
Overview
The M language provides operators that are used to specify an action that is to be
performed. The following table summarizes MSM operators and their characteristics.
060 2SHUDWRUV
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.
MSM Language Reference Manual Chapter 3 MSM Operators • 23

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
WRITE 2+2
Writes the value 4.
W 986.513+2081.6
Writes the value 3068.113.
W "123XYZ"+"456ABC"
Writes the value 579 after evaluating the strings as numbers.
W "123XYZ"+"ABC"
Writes the value 123 because the string "ABC" evaluates to zero as a number.
24 • Chapter 3 MSM Operators MSM Language Reference Manual

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
Examples
WRITE 5&4
Writes the value 1 because both operands are non-zero.
W 1&0
Writes the value 0 because the second operand is not true (0).
SET X="123XYZ"&"456ABC"
Sets X to the value 1 because operand1 evaluates to 123 and operand2 evaluates to 456.
S Y="123XYZ"&"ABC"
Sets Y to the value 0 because operand2 evaluates to 0.

CONCATENATE ( _ )
The CONCATENATE operator 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 4092 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
WRITE "BASKET"_"BALL"
Writes the string "BASKETBALL" to the current device.
W "1,"_"234"_",567."_89
Writes the string 1,234,567.89 to the current device.
SET X="JIM",Y="MSM" W "HELLO "_X_", WELCOME TO "_Y_"."
Writes the string "HELLO JIM, WELCOME TO MSM." to the current device.

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
WRITE 4/2
Writes the value 2 to the current device.
SET A=123.456,B=3.14 W A/B
Writes the value 39.317197452229299 to the current device.
W "246XYZ"/"123ABC"
Writes the value 2 because the first string evaluates to 246 and the second string evaluates to
123.

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 Truth-Valued Expressions
Examples
WRITE "ABC"="ABC "
Writes the value 0 because operand2 has a trailing blank.
W "123"="00123"
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.

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
WRITE 8**2
SET A=123.456,B=3.14 W A**B
W "16ABC"**"4XYZ"
Writes the value 65536 (evaluates to 16**4).

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
WRITE "123">"456"
Writes the value 0 because operand1 is not greater than operand2.
W "123">"001"
Writes the number 1 (true) because operand1 evaluated as a number is greater than operand2
evaluated as a number.
W "DEF">"ABC"
Writes the number 0 (false) because both operands evaluate to 0 as numbers.
W "123XYZ">"456ABC"
Writes the number 0 (false) because the numeric value of operand1 (123) is not greater than
the numeric value of operand2 (456).

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
WRITE +#3FD
Writes 1021 to the current device. The PLUS operator forces numeric conversion, thus
allowing the # operator to be recognized.
SET X=#1efd
Sets the local variable X to a value of 7933.
S Y=#3BFC\#FF W Y
Writes 60 to the current device. First, the two hexadecimal operands are evaluated, and then
the integer division is performed.

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 chapter 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 Operator

Examples
SET X="Y",@X=2
This form of name indirection sets variable Y to a value of 2.
S X="""YOU ARE NOW LOGGED ON AS "",USRNAME" WRITE @X
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="3N1""-""2N1""-""4N" W "123-45-6789"?@X
This form of pattern indirection writes 1 to the current device because the string conforms to
the indicated pattern.
S X="^CUS(ID)",ID="JONES",Y=@X@(1,100,0)
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)
S X="A",y="1^2^3",Z="$PIECE(Y,""^"",2)"
This command sets up the following three commands:
A",y="1^2^3",Z="$PIECE( commands:
Y,""^"",2)"
S @(X_"="_Z)
An example of argument indirection; this command sets variable A=2.
S @(X_" A=2.="_Z)
S ARG=X_"="_Z S @ARG@ARG
This command is equivalent to the previous command.
S @X=@Z
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.

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
WRITE 4\2
SET A=123.456,B=3.14 W A\B
Writes the value 39 to the current device. The fractional part of the result
(.317197452229299) is discarded.
W "456XYZ"\"123ABC"
123. The remainder value is discarded.

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
WRITE "123"<"456"
Writes the value 1 because operand1 is less than operand2.
W "123"<"001"
Writes the number 0 ( false) because operand1 evaluated as a number is greater than operand2
evaluated as a number.
W "DEF"<"ABC"
Writes the value 0 because both operands evaluate to 0 as numbers.
W "123XYZ"<"456ABC"
Writes the value 1 because the numeric value of operand1 (123) is less than the numeric value
of operand2 (456).

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
WRITE -3
Writes the value -3 to the current device.
W 123--456
Writes the value 579 to the current device because the MINUS operator inverts the subtraction
to addition.
W -"123XYZ"
Writes the value -123 to the current device because the string evaluates to the positive number
123, and the inverse is -123.
W -"ABC"
Writes the value 0 to the current device because the string "ABC" has a numeric value of 0.

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
WRITE 4#2
SET A=123.456,B=3.14 W A#B
Writes the value .996 (the remainder) to the current device. The integer portion of 39 is
discarded.
W "456XYZ"#"123ABC"
123. The integer portion of 3 is discarded.
W 5#(-3)
W -5#3
W -5#(-3)
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
WRITE 4*2
SET A=123.456,B=3.14 W A*B
W "246XYZ"*"123ABC"
Writes the value 30258 because the first string evaluates to 246 and the second string
evaluates to 123.

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 (!,
=, >, etc.) 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
Examples
WRITE '1
W 123'<456
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.

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
Examples
WRITE 5!4
Writes the value 1 because both operands are non-zero.
W 1!0
Writes the value 1 because the value of operand1 is true (1).
SET X="123XYZ"!"456ABC"
Sets X to the value 1 because operand1 evaluates to 123 and operand2 evaluates to 456.
SET Y="XYZ"!"ABC"
Sets Y to the value 0 because both operand1 and operand2 evaluate to 0.

PATTERN MATCH (?)
Tests if 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 Appendix A, "ASCII Collating Sequence," in this
document for additional information on the ASCII character set.
&RGH 'HVFULSWLRQ
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 SP 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 is either one of the allowable pattern match codes specified in the
previous section or a string literal (a string of characters enclosed in
quotes).
Min is the minimum number of occurrences required to successfully match
the pattern element (the minimum repetition count). This must be
specified as an integer value.
Max is the maximum number of occurrences that is allowed to successfully
match the pattern element (the maximum repetition count). This 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 3 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
SET X="3N1""-""2N1""-""4N" WRITE "123-45-6789"?@X
This pattern match writes 1 to the current device because the specified string conforms to the
indicated pattern.
WRITE "JONES,JOHN"?1A.A1","1A.A
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.
IF X?2N1(3P2A,2P3A).E
This example shows how a logical OR condition can be specified within a PATTERN
MATCH operation. The pattern shown in this 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
WRITE +"123XYZ"
W 123=+"123ABC"
Writes the value 1 to the current device because the PLUS operator forces numeric conversion
and the values are then equal.
W +"-123XYZ"
Writes the value -123 to the current device because the string evaluates to the negative number
-123.
W +"ABC"
Writes the value 0 to the current device because the string "ABC" has a numeric value of 0.

STRING CONTAINS ([ )
Tests if 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 operand 2
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
Examples
WRITE "ABCDEFGHI"["DEF"
Writes 1 to the current device because "DEF" is contained in "ABCDEFGHI"
W "123456"["246"
Writes 0 to the current device because "246" is not contained as a substring in "123456"
W "TEST STRING"[""
Writes 1 to the current device because the null string is contained in all strings.
SET X="ROCKVILLE, MD. 20850",Y="20850" W X[Y
Writes 1 to the current device because the zip code specified by operand2 is contained in
operand1.

STRING FOLLOWS (])
Tests if 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. Also, 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
Examples
WRITE "SMITH"]"JONES"
Writes 1 to the current device because "S" follows "J" in the ASCII collating sequence.
W "APPLES"]"APPLE"
Writes 1 to the current device because "S" (the sixth character of operand 1) follows the null
string (the sixth character of operand2) in ASCII collating sequence.
W "AAA"]"AAB"
Writes 0 to the current device because the "A" in the third position of operand1 comes before
"B" in the third position of operand2.
SET X="GOLF CLUBS",Y="GOLF CLUBS" W X]Y
Writes 0 to the current device because the two strings are identical.
W 10]2
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.

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 FOLLOWS Operator
String Expressions
$ORDER Function
Examples
WRITE "SMITH"]]"JONES"
Writes 1 to the current device because "SMITH" follows "JONES" in the subscript ordering
sequence.
W 45]]23
Writes 1 to the current device because 45 follows 23 in the subscript ordering sequence.
W 9]]10
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]]"05"
Writes 0 to the current device because 9 does not follow the string "05" in the subscript
ordering sequence.

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
WRITE 4-2
W 617.343-102.9537
W "456ABC"-"123XYZ"
Writes the value 333 after evaluating the strings as numbers.
W "123XYZ"-"ABC"
Writes the value 123 because the string "ABC" evaluates to zero as a number.

Chapter 4 MSM Commands
Overview
This chapter describes the ANSI-standard M commands and the additional
commands that are provided in the MSM implementation of M.
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.
MSM Language Reference Manual Chapter 4 MSM Commands • 49

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, the user can enter the interactive debugger
and have full access to the M language for debugging purposes. When the system
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, execution of the suspended routine can be resumed using the ZGO
command; QUIT can be entered to exit from the debugging system and return to the
current executing routine; or any M command can be entered. In addition, a question
mark (?) can be entered to obtain a list of commands that can be used within the
interactive debugger.
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.
50 • Chapter 4 MSM Commands MSM Language Reference Manual

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=Â(3) I X=0 B K Â 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
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
command after the CLOSE command.
The CLOSE command is used to release ownership of a device. Multiple devices can
be closed by specifying 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. Ownership of a device is achieved through the OPEN
command.
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 logon 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
EntryRef Any valid entry reference.
The DO command is executed if the Postcond expression is true or if it is not
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 Chapter 1, "Language Syntax," in this document
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
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 Indirection may be used in the DO command.
D @X^PGM
D ^@XYZ
D @A^@B
D:@A=B @C^@D:@E=@F
S R="^RTN:X=1" D @R
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
ActualList A list of arguments to pass to the called routine.
This form of the DO command allows the user 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 Chapter 5, "MSM Functions," in
this document for a description of how parameter passing has been implemented in
the MSM system.
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
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ÎNVOICE(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.
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
6. Go to step 2.
If Incr is less than 0, the following steps are performed.
2. The system determines whether the value of the local variable is less than the
3. Execute the scope of the FOR command once.
4. The system determines whether the value of the local variable is less than the
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 The output is the string:
I,"@",J,"*"
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
The GOTO command is executed if the Postcond expression is true or if it is not
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ÂBC 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 example 4.
G ÂDM: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 There are many opportunities to use indirection
G ^@B
G A^@B
within the GOTO command. The first and last
G @A^B examples are using argument indirection. The
G @A^@B others illustrate name indirection
S A="^RTN:X=1" G @A
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
The HALT command is executed if the Postcond expression is true, or if it is not
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
Expression A numeric expression.
The HANG command is executed if the Postcond expression is true or if it is not
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 3 seconds.
H:I=3 10 WRITE ! If I=3, a 10-second HANG is
executed before the WRITE.
H @X Indirection may be used in the HANG
H:$E(@A,B,@C) X+@Y+Z
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

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,Â(Y) GOTO 3 The following code is similar: IF X&(Â(Y)) G 3.
However, the side effects are different because the
latter always evaluates Â(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" If X=1, this code writes TEST ARGUMENTLESS.
ELSE W !,"EXAM"
IF W "ARGUMENTLESS"
Otherwise, it writes EXAM.
IF @X Indirection may be used in the IF command.

IF A,@B,C
IF A=@B,@C=D,E=F+@G+H

JOB
Initiates execution of a new M process.
Syntax
J{OB}{:Postcond}SPJobParm{,...}
where JobParm is:
EntryRef{|UCI{,Vol{,Sys}}|}{:{({PartSiz}{:SymFlag})}{:TimeOut}}
Definition
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 program will be run.
PartSiz The partition size in 1K 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
command after the JOB command.
The JOB command is used to start a new M process (a job). The process that is
started is referred to as a background job in MSM. When the JOB command is
executed, the system assigns a new partition to the job if one is available. The system
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 backwards
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. The user can override this
default value by including the PartSiz argument on the JOB command. The partition
size is specified in 1K 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 Â,^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 Â 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 example 3.
J:N>6 ^TEST Post-conditionals may be used.
J START^CUSLOOK:(24) A new process is initiated with a 24K
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 KB 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
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 1K blocks.
Sym Flag A flag that indicates whether the local symbol table of the current job
is to be copied to the new job.
This form of the JOB command allows the user 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 Chapter 5, "MSM Functions," in this document 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ÎNV(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 ÛPDATE(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
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
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,Â(3,4) Local variables X and Y and global variable
Â(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 Indirection may be used in the KILL command.
K X,@Y,Z
K:@Y=Z CUS(NUM,@NODE)

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
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. The system 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 two 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 3 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 2 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 example 4.
L:X=1 ÊF(Â(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 Â(.
L +^TST,-^Q(3),+A This command adds ^TST to the list of variables that
are locked, 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
variables that are locked, and then removes ^Q(3)
from the list.
L @A Indirection may be used in the LOCK command.
L:@B=C (X(@A),@B)

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
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
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 the MSM system 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.
Associated Topics
SET Command
$DATA Function
$ORDER Function

Examples
Command Explanation
MERGE Â=^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) are 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) Indirection is often used in the MERGE
M A(4,5,6)=@B
M @A@(1,2)=B
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
Var Any unsubscripted local variable name or selected special
variables ($ETRAP, $ESTACK, $TEST, and $ZREFERENCE).
The NEW command is executed if the Postcond expression is true or if it is not
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
$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 Indirection can be used in the NEW
N A,@B,C
N:@B=C (A,@B)
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
Device An integer expression that indicates which device is to be
OPENed.
parentheses that have meaning specific to the device being
opened.
The OPEN command is executed if the Postcond expression is true or if it is not
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 onto 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

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 3 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 example 3.
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
Expression Any expression used to return a value.
The QUIT command is executed if the Postcond expression is true or if it is not
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
StringLit A string literal.
Format A formatting character or mnemonic namespace value that
indicates the control characters to be sent to the device.
#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).
The READ command is executed if the Postcond expression is true or if it is not
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, RET 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, the system 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, the system
waits until a character is received. The READ terminates when a single character is
received. The system does not wait for a line terminator character.
If a TimeOut value is specified, the system 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
$X Special Variable
$Y Special Variable
Format Characters

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 then 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
the RET key is pressed during that time
period, $T is set to 1. Otherwise, $T is
0, X may contain partial input, and
execution continues at A. If no
characters have been entered, X
contains the empty string.
R "TIMING?",X:10 ELSE G A This is equivalent to the preceding
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 RET 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 a RET or
ESC is entered.

Command Explanation
R:$D(Â) !!,"TEST",X:12,*Y, The READ command may include a
*Z:10,#,"SAMPLE",!,A:9
post-conditional expression. All of the
various argument forms may appear in
one argument list. When 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 Indirection can be used with the READ
R X:@Y
R:@C @X:@Y
command.
R *@A

SET
Assigns a value to a local or global variable.
Syntax
S{ET}{:Postcond}SPVariable=Expression
S{ET}{:Postcond}SP(Variable{,...})=Expression
Definition
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
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 in place 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. The 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
$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 Â(1,2)=B(3,4) The value of the subscripted variable Y is
assigned to the subscripted global variable
^X.
S Â(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 =
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.
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,Â(3)=W,(Â(3,4), Multiple and single SETs may be mixed in
^B(5))=I
one command.
S Â(5)=10,B(^(3))=^C(4) When subscripts occur to the left of the =,
they are evaluated before the right side
expression. Thus, this line is equivalent to:
S Â(5)=10,B(Â(3))=^C(4)

Command Explanation
S Â(3)=10,^(^(3))=^C(4) This line is executed as follows:
a. Â(3) is given the value 10.
b. The subscript ^(3), which is Â(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 Â(3)=10,^C(Â(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 Indirection is often used in the SET
S @A=B+C
S A=@B+C
command.
S A=B+@(C_D)

Command Explanation
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) Doubles the partition size for job jobnum.
.partsize=system.apps
(jobnum).partsize*2
While evaluating the right side of the =,
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)= The extrinsic function $$VALUE is
$$VALUE($H)
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
The TCOMMIT command is executed if the Postcond expression is true or if it is not
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, 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 This routine indicates to the system that the current transaction
should be committed.
TC:UPDATE=1 This routine 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
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
Associated Topics
TCOMMIT Command
TROLLBACK Command
TSTART Command
Examples
Command Explanation
TRESTART This routine indicates to the system that the current
transaction should be restarted.
TRE:ABORT=1 This routine 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
The TROLLBACK command is executed if the Postcond expression is true or if it is
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
Associated Topics
TCOMMIT Command
TRESTART Command
TROLLBACK Command
TSTART Command
Examples
Command Explanation
TROLLBACK This routine indicates to the system that the current transaction
should be rolled back.
TRO:ROLLBK=1 This routine 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
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
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

Associated Topics
LOCK Command
TCOMMIT Command
TRESTART Command
TROLLBACK Command
TSTART Command
Examples
Command Explanation
TSTART This routine indicates to the system the start of a transaction.
TS:$TLEVEL=0 This routine starts a transaction if and only if $TLEVEL is equal
to 0.
TS *:S This routine starts a serializable transaction after saving all of the
local variables for the job.
TS (A,B,C):T=2 This routine 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
Device An integer expression that indicates which device is to be used.
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
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
$ZA, $ZB, and $ZC Special Variables

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- Device 64 is assigned the ANSI X3.64-1979 mnemonic
1979"
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
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
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, etc.).
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 4; for real numbers, it must be exactly 8. 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 (2 for
16-bit machines and 4 for 32-bit machines). A length of 8 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
Examples
Command Explanation
VIEW 20 Read block 20 from the MSM database.
V 1:0:255:1 Replace the second location in the VIEW buffer with 255.
V-20 Write the VIEW buffer to the MSM database at block
number 20.
V 120:0:"TEST":4:1 Move the character string TEST into location 120 of the
VIEW buffer.
V 5:"G1" Read 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
Format One or more format or mnemonic controls.
*Integer Any valid integer expression.
The WRITE command is executed if the Postcond expression is true or if it is not
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
$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", The arguments used on the WRITE
?20,"TAB",A(3)
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 Indirection may be used in arguments of
W Z,@X,Y
WRITE.

XECUTE
Allows interpretation and execution of commands that were stored as data.
Syntax
X{ECUTE}{:Postcond}SP{Expression}{:Postcond}{,...}
Definition
The XECUTE command is executed if the Postcond expression is true or if it is not
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 character, and it does not end
with a RET character. In addition, it 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 also
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
Variable Any local or global variable name.
The ZALLOCATE command is executed if the Postcond expression is true or if it is
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 example 3.

ZA:X=1 ÊF(Â(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 Indirection may be used in the ZALLOCATE command.

ZA:@B=C (X(@A),@B)

ZDEALLOCATE
Incrementally unLOCKS one or more local or global variables.
Syntax
ZD{EALLOCATE}{:Postcond}
ZD{EALLOCATE}{:Postcond}SPVariable
ZD{EALLOCATE}{:Postcond}SP(Variable{,...})
Definition
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 (Â,^B,^C) Removes Â from the list of variables LOCKed by the
ZDEALLOCATE Â
process. The variables ^B and ^C remain LOCKed by the
process.
ZA (Â,^B,^C) Removes Â and ^B from the list of variables LOCKed by
ZD (Â,^B)
ZA (^D,Ê)
the process and adds ^D and Ê to the list.
ZD:X=1 ÊF(Â(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 Indirection may be used in the ZDEALLOCATE command
ZD:@B=C X(@A),@B
and arguments may be listed.

ZFLUSH
Empties the disk buffer cache of all buffers.
Syntax
ZF{LUSH}{:Postcond}
Definition
The ZFLUSH command is executed if the Postcond expression is true or if it is not
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 This routine flushes all buffers from the cache.
ZF:X=1 This routine 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
The ZGO command is executed if the Postcond expression is true or if it is not
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, the user can enter any M commands or interactive debugger commands.
By entering a question mark (?), a list of valid debugger commands can be displayed.
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=Â(3) I X=0 B K Â 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:Â(0)=1 Execution of the routine proceeds only if Â(0)=1.

ZHOROLOG
Adjusts the date, time, or both for the current job.
Syntax
ZHOROLOG{:Postcond}SP{{±}Date}:{±}Time}}
Definition
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
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
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
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 > programmer prompt). To prevent the loss of
issued ZINSERT lines, the routine can be stored permanently in the database by
issuing a ZSAVE command.
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
Routname Any valid routine name.
The ZLOAD command is executed if the Postcond expression is true or if it is not
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 the RET
character. End of input is signaled by a null line (a line containing only the RET
character).
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
ZINSERT Command
ZREMOVE Command
ZSAVE Command

Examples
Command Explanation
ZLOAD ABC This routine loads routine ABC from the current UCI into the
partition.
ZL This routine loads a routine into the partition from the current
device.
ZL:X=1 XYZ This routine loads routine XYZ into the partition only if X=1.
ZL @X Indirection may 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
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
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 Turn off trace
1 Trace 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
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
The ZNEW command is executed if the Postcond expression is true or if it is not
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
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
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
The ZQUIT command is executed if the Postcond expression is true or if it is not
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

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

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
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
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 if comment line
3 First line comment and all ;; lines
6 All ;; comment lines
7 All ;; comment lines

Level Source Code Retained
8 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, etc. When the ZSAVE is done in programmer
mode, the MSM system implicitly performs a USE $I command before issuing the
command prompt. Therefore, 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
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
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
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 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
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 Â(1)=0 ZSE (A,B)=MYOBJ,A(3)=W, Multiple and single ZSETOBJs may be
(A(^(3,5),4),B(5))=XXX(^(4))
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,
the ^(3,5) evaluates to Â(3,5) due to
the setting of the naked by the "SET
Â(1)." Therefore, ^(4) becomes
Â(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.

Command Explanation
ZSETOBJ @X,@A=B Indirection is often used in the
ZSETOBJ command.
ZSETOBJ myjob=system.apps($J) WRITE This command uses a variable system
myjob.commands
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
The ZSYNC command is executed if the Postcond expression is true or if it is not
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
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
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
Appendix B, 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
Device Any valid terminal device designator.
The ZUSE command is executed if the Postcond expression is true or if it is not
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.
Associated Topics
USE Command
WRITE Command
Examples
Command Explanation
ZUSE 4 W !,"SYSTEM AVAILABLE UNTIL This routine sends a broadcast message
23:00 TONIGHT"
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
Variable Any subscripted or unsubscripted local variable name.
The ZWRITE command is executed if the Postcond expression is true or if it is not
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 ZWRITE writes the contents of the local symbol table to the
X=0 current device.
Y="23"
CODE=""
CODE(1)="R499"
CODE(2)="MM88"
CODE(3)="A1AA"
ZW CODE This routine writes the value of the variable CODE and all
CODE= of its descendants.
CODE(1)="R499"
CODE(2)="MM88"
CODE(3)="A1AA"
S X=10 Indirection may be used with the ZWRITE command, but
S Y="X"
ZW @Y
the indirection must yield a local variable that was
previously defined.
1.

Chapter 5 MSM Functions
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 users can
write their 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.
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 Language Reference Manual Chapter 5 MSM Functions • 139

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 that was 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.
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.
140 • Chapter 5 MSM Functions MSM Language Reference Manual

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.
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.
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.
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 Chapter 4, "MSM Commands," in this document
for additional information on MSM's parameter-passing capabilities.
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.
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.
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
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.

%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

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.
%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
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.
Syntax
$C{HAR}(Decimal{,...})
Definition
Decimal 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 Decimal arguments supplied to the function. If the
Decimal 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

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

Y is not defined $DATA(Y)=0
SET Y=100 $D(Y)=1
S Y="AB" $D(Y)=1
S A(1)="TEST" $D(A(1))=1
$D(A)=10
S B(1,2)="SAMPLE" $D(B(1,2))=1
$D(B(1)=10
S B(1)="SAMPLE1" $D(B(1))=11
KILL B(1,2) $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.

Examples

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" NAME="1B"
S $E(@A)=1

$FIND
Returns an integer value that denotes the ending location of a substring within a
specified string.
Syntax
$F{IND}(String,Substring,{Begin})
Definition
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
CONTAINS Operators

Examples

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, 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.
)RUPDW &RGHV IRU WKH )180%(5 )XQFWLRQ
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.
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.
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.
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

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

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

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

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

$NAME(Â(3,"B",3+4)) Â(3,"B",7)
$NA(Â(3,"B",7),2) Â(3,"B")
$NA(Â(3,"B",7),0) Â
$NA(Â(3,"B",7),-1) Error condition
S X=Â(3,"B",7) Sets up a naked reference
$NA(^(3)) Â(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

SET Â(1,2,3)=1,Â(2)=2,Â(4)=3 $NEXT(Â)=name of next global
in the local directory
$N(Â(-1))="1" first node
$N(Â(1))="2" second node
$N(Â(2))="4" third node
$N(Â(4))="-1" no descendants
$N(Â(1,-1))="2" second-node
level
$N(Â(1,2,-1))="3" third-node
level
$N(Â(1,2,3,-1))="-1" no
fourth level
SET Â(1,2,3)=1,Â(2)=2,Â(4)=3 $NEXT(Â(-1),-1)="4" last node
$N(Â(4),-1)="2" next-to-last
node
$N(Â(2),-1)="1" first node
$N(Â(1),-1)="-1" no
descendants
$N(Â(1,-1),-1)="2" second
level
$N(Â(1,2,-1),-1)="3" third
level
$N(Â(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
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 Functions
$QUERY Function
$ZNEXT Function
$ZORDER Function
$ZPREVIOUS Function
$ZSORT Function
Examples

SET Â(-1)=0,Â(1,2,3)=1, $ORDER(Â(""))="-1" first node
Â(2)=2,Â(4)=3 $O(Â(-1))="1" second node
$O(Â(1))="2" third node
$O(Â(2))="4" fourth node
$O(Â(4))="" no descendants
$O(Â(1,""))="2" second-node
level
$O(Â(1,2,""))="3" third-node
level
$O(Â(1,2,3,""))="" no fourth
level
SET Â(1,2,3)=1,Â(2)=2,Â(4)=3 $ORDER(Â(""),-1)="4" last node
$O(Â(4),-1)="2" next last node
$O(Â(2),-1)="1" first node
$O(Â(1),-1)="" no descendants
$O(Â(1,""),-1)="2" second
level
$O(Â(1,2,""),-1)="3" third
level
$O(Â(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
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

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

SET X="Â" $QLENGTH(X)=0
S X="Â(3)" $QL(X)=1
S X="Â(1,2,3)" $QL(X)=3
S X="" $QL(X)=0
S X="Y",Y="Â(3)" $QL(@X)=1

$QSUBSCRIPT
Returns the value of a specified subscript within a variable name.
Syntax
$QS{UBSCRIPT}(Variable,Position)
Definition
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

SET X="Â(3,5)" $QSUBSCRIPT(X,1)=3
$QS(X,2)=5
$QS(X,-1)=""
$QS(X,0)="Â"
$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)="Â"
S X="Â(3)",Y="X" $QS(@Y,1)=3
$QS(@Y,-1)=""
$QS(@Y,0)="Â"

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

SET Â(-1)=0,Â(1,2,3)=1, $QUERY(Â)="Â(-1)" first node
Â(2)=2,Â(4)=3 $Q(Â(-1))="Â(1,2,3)" second node
$Q(Â(1,2,3))="Â(2)" third node
$Q(Â(2))="Â(4)" fourth node
$Q(Â(4))="" no following node
$Q(Â(4),-1)="Â(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

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

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
Examples

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 Â(1)="TEST" $S(X=1:Â(1),Y:S)="TEST"
The naked indicator is set to Â

$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

Examples

$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ÊRRHAND
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 either 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
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)
SET A="ABC" $T(@A+2)=" READ X"
S K=2 $T(ABC+K)=" READ X"
S B=3 $T(+B)=" READ X"

XECUTE "ZLOAD RTN S X=$T(+1)" X=first line of RTN
The following 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
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

$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" Indirection can be used; the code
S A="ABCDE",B="AB",C="ab" returns the string "abCDE."
$TR(@X,@Y,@Z)

$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
Chapter 6, Special Variables

Examples

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.

$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
Chapter 7, Structured Variables

Examples

$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

$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}(String1,String2,Mask)
Definition
String1 Any string-type expression.
String2 Any string-type 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 String1 and String2 arguments. The specified Boolean operation is a bit
mask that corresponds to the four possible states of two binary bits. The following
table lists the possible combinations and the corresponding Mask value.
=%22/($1 0DVN 9DOXHV
Bit in String1 Bit in String2 Value of Mask

0 0 8
0 1 4
1 0 2
1 1 1
By combining values from the above table, the value of the Mask can range from 0 to
15, inclusive. If any of the conditions specified by the Mask are true, then the
corresponding bit in the string that is returned is set to 1. The length of the string that
is returned is always equal to the length of String1. If the length of String2 is less than
the length of String1, String2 is repeatedly applied to String1. The following table
illustrates all of the possible Mask settings and their associated logical operations.

=%22/($1 0DVN 6HWWLQJV
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 ⊗
Associated Topics
$LENGTH Function

Examples

$ZB("a","_",1)="A" Converts lowercase to uppercase. The value
returned is the same type as the first operand.
The value given can be string or numeric.
S X=$ZB($A("a"),95,1) X=65 $C(X)="A"

S X=$ZB("a",$C(95),1) X="A"
$ZB(1,0,7)=1 Logical OR operation.
$ZB(64,255,6)=191 Exclusive OR operation.

$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 backwards compatibility. It has been
superseded by the new external routine call syntax.
Examples

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

$ZCRC
Returns a computed checksum or cyclic redundancy check (CRC) of a string.
Syntax
$ZCR{C}(String{,Type{,Initvalue}})
Definition
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 four types of checksums: Exclusive OR, ASCII
summation, 16-bit CRC, and 32-bit CRC.
&KHFNVXP 7\SHV
Type Checksum
0 Exclusive OR
1 ASCII summation
5 16-bit CRC (DTM-compatible)
6 16-bit CRC (DSM-compatible)
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 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. Because
the maximum string length in MSM is 4092, it is not possible to calculate a CRC on a
longer String. If a String can be stored in multiple segments, each of which is no
longer than 4092 in length, the Initvalue can be used to calculate a CRC as if the
segments were all concatenated. The following examples illustrate this feature.
Associated Topics
$ASCII Function
Examples

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 OLE/2 objects.
By convention, the format of the ClassName parameter is as follows.
AppName.ObjectType
Every application that supports OLE/2 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/2 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
Example
M Code Description
SET X=$ZCRE("word.Basic") Creates a Word 6.0 document object.
I $ZOBJREF(X)=0 G ERROR Ensures allocation succeeded.
S X.Insert="Hello World" Inserts a line.
S X.FileSaveAs="C:\hello.doc" Saves the file.

$ZDATE
Returns the external representation of a date by converting it from its internal
$HOROLOG format.
Syntax
$ZD{ATE}(Integer{,Type})
Definition
Integer An integer expression that is in $HOROLOG format.
Type An integer expression that indicates the format for the external date.
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 displayed.
Associated Topics
$HOROLOG

Examples

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"

$ZDEVICE
Returns the device name of a terminal device connected to the system.
Syntax
$ZDE{VICE}(Integer)
Definition
Integer An integer expression that evaluates to a device number.
The $ZDEVICE function returns the full name of a terminal device. 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.
Associated Topics
Examples

WRITE $ZDEVICE(64) PORT_1@LABSERVER
WRITE $ZDE(3) 3

$ZGETOBJECT
Retrieves an OLE/2 automation 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 OLE/2 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, OLE/2 uses the filename provided to determine
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/2 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
ZSETOBJECT Command
$ZCREATEOBJECT Function

Examples
Setup Description
ZSET X=$ZGETO("c:\cad\schema.cad") Instantiates an object in schema
file.
ZSET Activates layer 3 within the
X=$ZGETO("c:\cad\schema.cad!Layer3")
schema file.
ZSET X=$ZGETO("d:\drawings\ FIGMENT is the name of the
sample.drw","FIGMENT.DRAWING")
drawing application, and
DRAWINGS is one of the object
types it supports.
ZSET X=$ZGETOBJECT(,"FIGMENT.DRAWING") Locates an active object of the
G:$ZOBJREF(X) GOTOBJ
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

$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.
'DWH )RUPDW 6WULQJV
Format Resulting Value

yyyy Year (four digits, including century).
yy Year within century (two digits, zero-padded if necessary).
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).
The following token strings apply to time formatting and are only valid when Type is
two. Different cases produce different results.
7LPH )RUPDW 6WULQJV

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).
$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
$ZDATE Function

Examples

Dates:
$ZHL(1,”dd-MON-yy”,56690)) 18-MAR-96
$ZHL(1,”Day, Month d, Monday, March 18, 1996
yyyy”,$P($H,”,”,1)) (today’s date)
$ZHL(1,”dd-Mon-yyyy”,56678) 06-Mar-1996
Times:
$ZHL(2,"hh:mm",$P($H,",",2)) 09:51
$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.
The $ZNEXT function is used to identify the next or previous node in a local or
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
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
$QUERY Function
$ORDER Function
$ZORDER Function

Examples

SET Â(1,2,3)=1,Â(2)=2,Â(4)=3 $ZNEXT(Â(-1))="Â(1,2,3)" first
node
$ZN(Â(1,2,3))="Â(2)" second node
$ZN(Â(2))="Â(4)" third node
$ZN(Â(4))=-1 no descendants
$ZN(Â(4),-1)="Â(2)" previous
node
$ZN(Â(-1),-1)="Â(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.
If only one argument is specified, $ZOBJREFERENCE returns 1 if the Expression
evaluates to an object reference or returns 0 if it does not. If two arguments are
specified, $ZOBJREFERENCE returns 1 if both Expressions evaluate to references
to the same object; otherwise, it returns 0.
Examples

ZSET A=$$FUNC(PARM) FUNC might return an object reference.
IF $ZOBJREF(A)
Checks for object reference.
ZSET B=$$FUNC(parm) Checks whether or not A and B are both references to the
IF $ZOBJREF(A,B)
same object.

$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.
The $ZORDER function is used to identify the next or previous node in a local or
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
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
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

SET Â(-1)=0,Â(1,2,3)=1, $ZORDER(Â(""))="Â(-1)" first
Â(2)=2,Â(4)=3 node
$ZO(Â(-1))="Â(1,2,3)" second
node
$ZO(Â(1,2,3))="Â(2)" third node
$ZO(Â(2))="Â(4)" fourth node
$ZO(Â(4))="" no descendants
$ZO(Â(4),-1)="Â(2)" previous
$ZO(Â(""),-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.
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.
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. The following is the
syntax for the Set Current Drive function:
$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. The following is the syntax for the Delete a File
function.
$ZOS(2,FileName)
FileName is the name of the file to be deleted and can include a DriveID and a
directory path.
$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. The following is the syntax for
the Rename a File function.
$ZOS(3,OldFile,NewFile)
OldFile is the name of the file to be renamed. OldFile optionally can include a
DriveID and a directory path.
NewFile is the new name of the renamed file. NewFile optionally can include a
directory path. If a specified path is different than the path supplied or implied in the
OldFile, the file is moved to the new directory. If a DriveID is specified, it must be
the same as the DriveID associated with the OldFile name.
$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. The following
is the syntax for the Get Windows Version Number function.
$ZOS(4)
This function does not require any parameters.
$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. The following is the syntax for the Set File
Attributes function.
$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).
$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. The following is the syntax for the Create a New Directory
function:
$ZOS(6,DirName)
DirName is the name of the directory to be created. DirName 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. The following is
the syntax for the Remove an Existing Directory function.
$ZOS(7,DirName)
DirName is the name of the directory to be removed. Optionally, it can include a
DriveID and a directory path.
$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 DirName 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. The following is the syntax for the Change Current
Directory function.
$ZOS(8,DirName)
DirName is the name of the directory to be changed. DirName optionally can include
a DriveID and a directory path.
$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 File Attributes

This function returns the attributes for a specified file in Windows. There is no
equivalent command in Windows. The following is the syntax for the Get File
Attributes function.
$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.

$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. The following is the syntax for the Get Current
Directory for Drive function.
$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.
$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. The following is the
syntax for the Begin Directory Search function.
$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.
Attributes 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.

$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
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. The syntax for the
Continue Directory Search function is as follows.
$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.
$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. The following is the syntax for the Get Current
Drive function.
$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. The following is the syntax for the Close Directory Search function.
$ZOS(16,SearchParm)
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.
$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.
=26 (UURU &RGHV
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

Number Description
-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
Examples
In the following examples, the symbol ❖ is used to represent a double-byte character.

$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

SET Â(1,2,3)=1,Â(2)=2,Â(4)=3 $ZPREVIOUS(^)=last global
$ZP(Â(""))="4" last node
$ZP(Â(4))="2" next to last
node
$ZP(Â(2))="1" first node
$ZP(Â(1))="" no descendants
$ZP(Â(1,""))="2" second-node
level
$ZP(Â(1,2,""))="3" third level
$ZP(Â(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.
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
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

SET Â(-1)=0,Â(1,2,3)=1, $ZSORT(^)=first global
Â(2)=2,Â(4)=3 $ZS(Â(""))=-1 first node
$ZS(Â(-1))=1 second node
$ZS(Â(1))=2 third node
$ZS(Â(2))=4 fourth node
$ZS(Â(4))="" no descendants
$ZS(Â(1,""))=2 second-node
level
$ZS(Â(1,2,"")=3 third-node
level
$ZS(Â(1,2,3,""))="" no fourth
level
$ZS(Â(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

Examples

$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

$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
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
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

Chapter 6 MSM Special Variables
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.
MSM Language Reference Manual Chapter 6 MSM Special Variables • 223

$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
Examples
USE 5::"X3.64-1979" W /CUP(4,24) Q:$DEVICE
This example attempts to move the cursor to the specified location and QUITs if the operation
is not successful.
224 • Chapter 6 MSM Special Variables MSM Language Reference Manual

$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 Appendix B, "Error Processing," in this document 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
$STACK Function
Examples
FOR I=2:1:$L($ECODE,”,”)-1 WRITE !,$P($ECODE,”,”,I)!,$P($ECODE,”,”,I)
This code displays the individual error codes in $ECODE on individual lines.
WRITE $ECODE
This command might display the following:

,M9,Z<DIVER>*XECUTE*:::5:2:,
which would result from an attempted division by zero.

$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

Examples
QUIT:$ES>0
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.
NEW $ESTACK SET $ETRAP=“D ERROR^ROUTINE” DO APPL
This command stacks the current $ESTACK value; resets the current value of $ESTACK to
zero; defines the error handling string; and invokes the application.

$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.
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
Examples
NEW $ETRAP SET $ETRAP=“D ERR^ROUTINE”$ETRAP=“ERR^ROUTINE”
This example stacks the current value in $ETRAP and establishes a new string to be executed
if an error condition is detected.

$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
Examples
USE 3 S X=$I
The local variable X is assigned a value of 3.
S Â($I,1)=X
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.

$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 onto 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
S Â($J,1)=X
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.
WRITE #,DATE," ",$J
Output from a job can be identified by printing the job number with the output.

$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
Examples
USE 5::"X3.64-1979" W /CUP(4,24) R X Q:$KEY'=$C(13)
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 RET key.
U $I:(::::64) R X GOTO:$KEY=($C(27)_"[A") UPARROW
When escape processing is turned on by the USE command, $KEY can contain a string of
characters.

$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 where 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
USE $PRINCIPAL
This example makes the initial device for the job (the principal device) the current device.
C:$I'=$P $I
This example closes the current device if it is not the principal device.

$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
$QUIT Special Variable
$STACK Special Variable
$STACK Function
Examples
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
In the preceding 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.

$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.
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
Examples
WRITE !,$STACK($STACK,”ECODE”),!,$STACK($STACK,”MCODE”)
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.

$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
I $S<MINSIZE G ^FILETEMP
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.
IF $S<1000 SET %K=PSIZE+2 D INT^%PARTSIZEINT^%PARTSIZE
If the value of the $STORAGE variable falls below 1000 bytes, then the %PARTSIZ routine
is invoked to increase the partition size.

$SYSTEM
Contains a 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
WRITE $SYSTEM
43,1001234;176034223
This example writes the contents of $SYSTEM to the current device.
S ÛTILITY($SY,$J)=X
Temporary global nodes can be set up with data stored by the SYSTEM identifier and the JOB
number.

$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
I X=3 S Y=A
W:$T Y S Y=B
This code is equivalent to the following:
I X=3 S Y=A
I X=3 W Y
S Y=B
R X:100 G A:'$T DO 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.
O 3::10 G A:'$T U 3 W X
This example is similar to example 2. If the OPEN is unsuccessful, execution transfers to label
A. Otherwise, output is written to device 3.

$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
Examples
W $TLEVEL
4
This example writes the number of TSTART commands processed since the last TCOMMIT
or transaction restart.

$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
Examples
W $TRESTART
3
This example writes the number of transaction restarts that have occurred during the
transaction.

$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
W !,"123" S Y=$X
Y is given the value 3.
W # S Y=$X
W:$X>72 !
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.
S $X=27
This code assigns a new value to $X.

$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. The value of $Y may be changed by the user
with a SET command.
Associated Topics
Format Characters
Examples
W # S Y=$Y
W #!!! S Y=$Y
W:$Y>56 #
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.
S $Y=31
This code assigns a new value to $Y.

$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
U 51 R X S RC=$ZA RC=$ZA
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.

$ZB
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
U 51 R X S RC=$ZB

$ZC
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. In general, a non-zero value
indicates an error condition.
Associated Topics
OPEN Command
USE Command
Examples
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 of <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 Appendix B, "Error Processing" in this document.
Associated Topics
Examples
W $ZE
<UNDEF>+17^CUSINQ:::4:1
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).

$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
Configuring the System, MSM User's Guide
Examples
W $ZLEVEL
4
This example writes the number associated with the current nesting level.

$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
W $ZN
TESTPGM
This example writes the name of the routine that is currently loaded into the partition.
ZR W $ZN
This example writes the null string to the current device.

$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
S ^X(1,1)=1,^X(1,2)=2,^X(1,3)=3
S X=^X(1,2)
W $ZORDER
This example writes the data value 3 (the data value of the node that follows the last global
reference that was made).

$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
S ^CUS(1,2,3)="JONES^JOHN" W $ZR
^CUS(1,2,3)
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 ^|"PRD","VGA"|CUS(1,2,3)="JONES^JOHN" W $ZR
^|"PRD,VGA"|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.

$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
ZQUIT Command
ZTRAP Command
Examples
S $ZTRAP="^%ET"
If an error is encountered, control is passed to the %ET routine.
S $ZT="ERR^MYPROG"
This example passes control to the ERR label of the MYPROG routine if an error is
encountered.
S $ZT=""
This examples disables error trapping.

$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, MSM for Windows NT) and the
release number of the software (for example, Version 4.3.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
W $ZV
MSM-PC/PLUS, Version 4.3.0
This example prints the name and version number of the MSM system that is in use.

Chapter 7 MSM Structured System
Variables
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.
MSM Language Reference Manual Chapter 7 MSM Structured System Variables • 257
^$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
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.
258 • Chapter 7 MSM Structured System Variables MSM Language Reference Manual
^$GLOBAL
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("Â"))
This expression tests for the existence of global Â (existence is defined as $D(^Global)>0).
$ORDER(^$G("Â"))
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("Â"))
This expression tests to see if the global variable A is currently locked.
$ORDER(^$L("Â"))
This expression returns the name of the next resource that is locked.
$ORDER(^$L("Â"))
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
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
$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.
Appendix A ASCII Collating
Sequence
Overview
This appendix provides a list of the ASCII collating sequence values.
$6&,, &ROODWLQJ 6HTXHQFH

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
MSM Language Reference Manual Appendix A ASCII Collating Sequence • 263

Decimal Symbol Pattern Decimal Symbol Pattern
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
264 • Appendix A ASCII Collating Sequence MSM Language Reference Manual

Appendix B Error Processing
Overview
This appendix describes methods of trapping errors during program execution, and
lists error messages that may be generated during execution.
MSM Language Reference Manual Appendix B Error Processing • 265

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, the
MSM system considers such situations to be fatal errors.
Actions when an 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.
266 • Appendix B Error Processing MSM Language Reference Manual

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 Chapter 5, “MSM Functions,” and Chapter 6, “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 ÊRROR"
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 ÊRROR. 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ÊRROR"
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.

3URFHVVLQJ (UURUV ZLWK =75$3
A ;Routine A T1 ;Error Trap 1

... ...
SET $ZTRAP="T1" Q ; return to caller of A
... ...
DO ^B ZQ ; the error will occur
...
...
B ;Routine B
...
;NO $ZTRAP SET
...
DO ^C
...
...
C ;Routine C T3 ;Error Trap 3

... ...
SET $ZTRAP="T3" ...
... QUIT
DO ^D ...
... ...
... ZQUIT
D ;Routine D T4 ;Error Trap 4

... ...
SET $ZTRAP="T4" ...
... QUIT
Error condition ...
... ...
... ZQUIT

The following figure illustrates error processing with $ETRAP and $ECODE and can
be contrasted with the “Processing Errors with $ZTRAP” figure.
3URFHVVLQJ (UURUV ZLWK (75$3 DQG (&2'(
A ;Routine A T1 ;Error Trap 1

NEW $ETRAP, $ESTACK IF $ESTACK QUIT; not executed
SET $ETRAP="G T1" ...
... if recovered, SET $ECODE="" QUIT;
DO ^B normal return to caller of A
... QUIT ; initiate error processing for
... caller of A
B ;Routine B T1 ;Error Trap 1

; no $ETRAP set IF $ESTACK QUIT
... ...
DO ^C
...
...
C ;Routine C T3 ;Error Trap 3

NEW $ETRAP ...
SET $ETRAP="G T3" if recovered, SET $ECODE="" QUIT
... QUIT
DO ^D
...
...
D ;Routine D T4 ;Error Trap 4

NEW $ETRAP ...
SET $ETRAP="G T4" if recovered, SET $ECODE="" QUIT
... QUIT
Error condition
...
...
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 the following paragraphs.
%ET
When an error occurs and this 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 the user
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 the user 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 Chapter 4, “MSM Commands,” in this document for additional
information on the BREAK command. The following list 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.
060 (UURU &RGHV
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.

Code Explanation
<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.
<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.
<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.

Code Explanation
<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.
060 (UURU 1XPEHUV
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
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.
(&2'( (UURUV
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 sub-tree 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
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

Code Explanation Equivalent
$ZERROR value
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

Appendix C Mnemonic Namespaces
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 Chapter 4, "MSM Commands", in this document, and Chapter
7, "Using Peripheral Devices," in the MSM User's Guide.
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.
MSM Language Reference Manual Appendix C Mnemonic Namespaces • 283

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
(/).
$16, ; 0QHPRQLF 1DPHVSDFH
Mnemonic Function and Esc sequence Change in $X and $Y

/BEL Ring bell $X:None
Seq: *7 $Y:None
/BS Backspace cursor $X:MAX(0,$X-1)
Seq: *8 $Y:None
/CBT(n) Backup n tab stops $X:
Minimum and default value is 1 MAX(0,$X+7\8*8-(n*8))
Assumes eight-column tabbing $Y:None
Seq: *27 [ n z
/CHA(n) Move cursor to column n $X:n-1
Minimum and default value is 1 $Y:None
Seq: *27 [ n g
/CHT(n) Forward n tab stops $X:
Minimum and default value is 1 MIN(255,$X\8*8+(n*8)
Assumes eight-column tabbing $Y:None
Seq: *27 [ n i
/CNL(n) Cursor down n lines $X:0
Cursor to column 1 $Y:MIN(255,$Y+n)
Minimum and default value is 1
Seq: *27 [ n e
/CPL(n) Cursor up n lines $X:0
Cursor to column 1 $Y:MAX(0,$Y-n)
Seq: *27 [ n f
/CR Column 1 of current line $X:0
Seq: *13 $Y:None
/CTC(a,b,...) Set tab stops $X:None
Seq: *27 [ a ; b ; ... W $Y:None
/CUB(n) Cursor back n columns $X:MAX(0,$X-n)
Seq: *27 [ n d
/CUD(n) Cursor down n rows $X:None
Minimum and default value is 1 $Y:MIN(255,$Y+n)
Seq: *27 [ n b
284 • Appendix C Mnemonic Namespaces MSM Language Reference Manual

/CUF(n) Cursor forward n columns $X:MIN(255,$X+n)
Seq: *27 [ n c
/CUP(r,c) Position cursor to row r column c $X:c-1
Minimum for c and r is 1 $Y:r-1
Default for c and r is 1
Maximum for c and r is 256
Seq: *27 [ r ; c h
/CUU(n) Cursor up n lines $X:None
Minimum and default value is 1 $Y:MAX(0,$Y-n)
Seq: *27 [ n a
/DA(a,b,...) Set device attributes $X:None
Parameters are ANSI values $Y:None
for color, blink, etc.
Seq: *27 [ a ; b ; ... C
/DAQ(a,b,...) Define area qualification $X:None
Seq: *27 [ a ; b ; ... O
/DCH(n) Delete n characters at cursor $X:None
Rest of line slides left $Y:None
Seq: *27 [ n p
/DL(n) Delete n lines at cursor $X:None
Rest of lines slide up $Y:None
Seq: *27 [ n m
/DSR(a,b,...) Device status request $X:None
Response needs to be read in via READ
command
Seq: *27 [ a ; b ; ... N
/ECH(n) Erase n characters at cursor $X:None
Replace with blanks $Y:None
Seq: *27 [ n x
/ED(n) Erase display $X:None
N=0: cursor to end of display $Y:None
N=1: home to cursor
N=2: entire display
Seq: *27 [ n j

/EL(n) Erase line $X:None
N=0: cursor to end of line $Y:None
N=1: start of line to cursor
N=2: entire line
Seq: *27 [ n k
/FF Cursor down 1 row $X:None
Seq: *12 $Y:($Y+1)#256
/HPA(n) Cursor to column n $X:n-1
Seq: *27 [ n `
/HPR(n) Cursor forward n columns $X:MIN(255,$X+n)
Seq: *27 [ n a
/HT Horizontal tab $X:MIN(255,$X\8*8+8)
Seq: *9 $Y:None
/HTS Set horizontal tab stop at cursor $X:None
Seq: *27 h $Y:None
/HVP(r,c) Cursor to row r and column c $X:c-1
Minimum and default value is 1 $Y:r-1
Maximum value is 256
Seq: *27 [ r ; c f
/ICH(n) Insert n blanks at cursor $X:None
Seq: *27 [ n @
/IL(n) Insert n blank lines at cursor $X:None
Seq: *27 [ n l
/IND Move cursor one column down $X:None
Seq: *27 d $Y:MIN(255,$Y+1)
/LF Move cursor one line down $X:None
Seq: *10 $Y:($Y+1)#256
/MSMRC(n) Restore saved cursor position $X:Saved value
Seq: *27 8 $Y:Saved value
/MSMRGN(n,m) Setup scrolling region $X:None
Seq: *27 [ n ; m r $Y:None
/MSMRM(a,b,...) Reset modes $X:None
Seq: *27 [ ? A ; b ... H $Y:None
/MSMSC Save current cursor position $X:None
Seq: *27 7 $Y:None
/MSMSM(a,b,...) Set modes $X:None
Seq: *27 [ ? A ; b ... H $Y:None

/NEL Move to column 1 of next line $X:0
Seq: *27 e $Y:($Y+1)#256
/NP(n) Advance n pages of terminal $X:0
Display memory $Y:0
Seq: *27 [ n u
/PP(n) Backup n pages of terminal $X:0
Display memory $Y:0
Seq: *27 [ n v
/RI Reverse index (up one column) $X:None
Seq: *27 m $Y:MAX(0,$Y-1)
/RIS Reset to initial state $X:0
Seq: *27 c $Y:0
/RM(a,b,...) Reset modes $X:None
Values are ANSI defined $Y:None
Seq: *27 [ a ; b ; ... L
/SGR(a,b,...) Set graphical rendition $X:None
Seq: *27 [ a ; b ; ... M $Y:None
/SM(a,b,...) Set modes $X:None
Values are ANSI defined $Y:None
Seq: *27 [ a ; b ; ... H
/TBC(a,b,...) Clear tap stops $X:None
Seq: *27 [ a ; b ; ... G $Y:None
/VPA® Move to row r at same column $X:None
Minimum and default value is 1 $Y:r-1
Seq: *27 [ r d
/VPR(n) Cursor down n lines at same column $X:None
Minimum and default value is 1 $Y:MIN(255,$Y+n)
Seq: *27 [ n e
/VT Vertical tab (up one column) $X:None
Seq: *11 $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.
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.
=:,17(50 'LVSOD\ $WWULEXWHV
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

Attribute Description
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.
=:,17(50 (UDVH $WWULEXWHV
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.
=:,17(50 (UURU &RGHV
Error Code Description

0 Must be 0, normal success completion
1 Window already exists
2 Bad parameter value
3 Non-existent 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 Chapter 4, "MSM

Commands," in this document. For additional information on the $DEVICE special
variable, refer to Chapter 6, "MSM Special Variables," also in this document. 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,Attribute) - Initialize Namespace

TermSpace A string expression that specifies the name of a system or
user-defined terminal mnemonic namespace. Only X3.64-1979 is
supported.
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 can be used in conjunction with the X3.64-1979
mnemonic namespaces. The TermSpace parameter on the /INIT function is used to
associate the X3.64-1979 namespace with the ZWINTERM window. This feature
enables applications that rely on mnemonic namespaces for terminal control to be
easily adapted to use the windowing capabilities of the ZWINTERM mnemonic
namespace.
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
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

This function is used to set or clear attributes associated with the border of the
current window.
/WDSGR(Attribute) - Window Default SGR

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

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

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
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 Chapter 6, "MSM Special
Variables," in this document for additional information on the $X and $Y special
variables.
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

This option is used 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. Upon entry, the user is prompted for 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>: RET
Namespace names defined internally to MSM-PC/PLUS:

'X3.64-1979'
'ZWINTERM'
Namespace names defined by SYSGEN:

None.
Select Option:

Add New Namespace
This option is used to create a new mnemonic namespace. The user is prompted for a
unique identifier 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
> W *27,$C($1+31),$C($2+31) S $Y=$1,$X=$2
Mnemonic Set Parms

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

-------- ----- ------- ----------------------------
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: RET
Select Option:
Copy Namespace to New Name

This option is used 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.
When this option is selected, the user is prompted for 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

'X3.64-1979'
'ZWINTERM'

'Q102'
Select Namespace to be copied: Q102
Enter new Namespace name: Q105
.....! done.
Select Option:
Edit Existing Namespace

This option is used to edit one or more mnemonic definitions within an existing
mnemonic namespace. It also is used to add new mnemonic definitions to an existing
mnemonic namespace. The user is prompted for the name of an existing namespace
and a mnemonic identifier. If the identifier exists, the user is prompted for editing
information. If it does not exist, the user is prompted 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
-------- ----- ------- ----------------------------
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

> W *27,"[G1"
Mnemonic Set Parms

-------- ----- ------- --------------------
EL --- 0,0 W *27,"[G1"
Enter mnemonic name: UNDERLINE

Edit M code for mnemonic:

> W *27,"G8"
Replace: G8 With: G9 Replace: RET
> W *27,"G9"
Replace: RET
Mnemonic Set Parms

-------- ----- ------- --------------------
UNDERLINE --- 0,0 W *27,"G9"
Enter mnemonic name: RET
Select Option:
Delete Existing Namespace

This option is used to delete a user-defined namespace. The system does not allow
built-in namespaces to be deleted. When this option is selected, the user is prompted
for 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

'X3.64-1979'
'ZWINTERM'

'Q102'
'Q105'
Select Namespace to be deleted: Q105

Are you sure <N>: Y
Deleting........done.
Select Namespace to be deleted: RET
Select Option:
Rename Existing Namespace

This option is used to rename a user-defined namespace. The system does not allow
built-in namespaces to be renamed. When this option is selected, the user is prompted
for 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

'X3.64-1979'
'ZWINTERM'

'Q102'
'Q105'
Select Namespace to be renamed: Q102
Enter new Namespace name for 'Q102': QUME
.....! done.
Select Option:
Export Namespaces
This option is used to save a user-defined namespace to an external file so that it can
be copied to another system. When this option is selected, the user is prompted for an
output device in a dialogue similar to the one used by the %GS (Global Save) Utility.
The user is prompted to select the namespaces to be exported. The following sample
terminal session illustrates the Export function.
Select Option: 7 - Export Namespaces
Enter output device <HFS>: RET

File Name: QUME.NAM
Enter size of save medium (if applicable): RET
Enter comment for dump header: Namespaces for QUME crts
Mnemonic namespace selector: Q102
Mnemonic namespace selector: Q105
Saving ...
^SYS
^SYS
Save complete.

Import Namespaces
This option is used to load user-defined namespaces from an external file that was
created by the Export Namespaces option. When this option is selected, the user is
prompted for the input device, using the same dialogue that is used by the %GR
(Global Restore) Utility. The following sample terminal session illustrates the Import
function.
Select Option: 8 - Import Namespaces
Enter input device <HFS>: RET

File Name: ANSI.NAM
Mnemonic namespace(s) saved at 1:20 PM 27-JUL-92.
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>: RET
Restoring...
Mnemonic Namespace: X3.64 TEMPLATE ... Restored
Restore Complete

Appendix D User-Defined
Commands
Overview
This appendix describes how to write user-defined commands, functions, and special
variables in MSM.
Appendix D User-Defined Commands • 309

Commands, Functions, and Special Variables
The MSM system 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 a user-defined command, function, or special variable
is encountered by the system, 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.
310 • Appendix D User-Defined Commands

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 " " %TIME1
Appendix D User-Defined Commands • 311

312 • Appendix D User-Defined Commands
Appendix E Macro Facility
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 for Windows editor, restored from a host file, or copied
between UCIs. 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.
MSM Language Reference Manual Appendix E Macro Facility • 313

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.
314 • Appendix E Macro Facility MSM Language Reference Manual

Definitions
Directive
A directive is a command to the preprocessor. An equivalent term is preprocessor
command. Refer to "Preprocessor Directives" in this appendix 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 appendix.
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 a 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.
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(1995,1996)."
which expands to:

W "Program ABC Copyright Micronetics Design Corporation 1995-1996."
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.
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.
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
See the sections on #comment and #nocomment in "Preprocessor Directives".
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 23Mar95 9:49pm

Advanced Capabilities
The preprocessor provides additional functionality, including libraries, special
macros, parameter functions, multi-line and computed definitions, and special
functions.
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
appendix, 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ÛTL(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ÛTL(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.
#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.
#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 (i.e. "()"), which indicates that parameters
are expected. Any parameter can be missing. Parameters are placed in $1, $2, etc.
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 multi-line macro definition requires use of a #def…#enddef block. See the section
"Multi-Line Definitions" for more details.

#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
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
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
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
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. See
page 99 for additional information on libraries.
#makelib
Creates a macro library.
Syntax
#makelib LibraryName [GlobalReference]
Definition
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
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
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
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
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

Glossary
ANSI
The $merican 1ational 6tandard ,nstitute.
argument
An expression which controls what action will occur in the function or command with
which it is used.
array
An organized set of local or global elements or nodes which are referenced by
subscripts and a common variable name.
ASCII
The American Standard Code for Information Interchange. This code consists of 128
characters which comprise the standardized character set.
background job
A job that was started by the JOB command. This process runs in parallel with the
process which contained the JOB command.
baud
A term which describes the data transmission rate between two devices.
MSM Language Reference Manual Glossary • 335

Big-Endian
Describes the bit ordering of integer values when they are stored in memory. In Big-
Endian format, the most significant digits precede the least significant digits.
break
A command that interrupts program execution so that debugging can be performed.
Canonic number
A numeric value which has no leading or trailing zeros after the decimal point.
carriage return
A keyboard instruction, often used to indicate the end of a command. This key is
commonly marked RETURN, ENTER, or CR.
collating sequence
An order that is assigned to a grouping of subscripts. This sorting can be done in
either string or numeric sequence.
string sequence - All subscripts are treated as character strings and are stored in
ASCII sequence.
numeric sequence - Storage is in the order of Canonic numbers first, followed by the
non-numeric values in ASCII sequence.
command
The method by which the compiler is directed to perform a specific action.
comment
A brief phrase in the body of a routine which describes when the routine was written,
what the routine does, and so on. This is a non-executable line of code that begins
with a semicolon (;).
compiler
The language compiler is a highly sophisticated system program that scans each line
of M code, divides it into basic components, analyzes each component to ensure that
it is syntactically correct, and generates pseudo-machine code that can be processed
by the p-code interpreter.
336 • Glossary MSM Language Reference Manual

concatenation
The process of joining two operands together to form a new string. This is
accomplished by appending operand 2 to the end of operand 1 by use of the
underline (_) symbol.
CONFIG.MSM
A file found in the root directory or the local directory which contains information
about the MSM system you are running. When MSM is started, this file is read to
determine how MSM is to be set up.
configuration
The collection of hardware and software that comprises the entire computer system.
control characters
Characters from the standard ASCII set which have special meaning to the MSM
system. These characters are obtained by depressing the control key (usually marked
CTRL) at the same time that the associated control character is pressed.
cursor
The on-screen marker, usually a box or an underline, which indicates the location
where the next data entry will occur.
data
The information (letters, numbers, symbols) that is entered into the system for
processing or storage.
database
The location where storage of the data takes place in global arrays. In MSM, this is
where the MSM system was installed (database 0).
default
The value which is assumed as the entry to a prompt if the carriage return is
depressed. In MSM, default values are displayed between greater than ( > )and less
than ( < ) signs, for example: (<DEFAULT>).
descendant
Any array node on a lower subscript level which is reachable from that node and
shares the first 'x' subscripts in common. For example, the nodes R(3,4,5) and
R(3,6,4,7) are descendants of R(3).

device
Any part of the computer other than the CPU, the memory, or any associated
architectural part; for example: a printer, terminal, or modem.
expression
A character string which yields a value upon execution.
function
An action which gives users the ability to perform routine operations in a more
efficient manner. In MSM, a function begins with a dollar sign ($) or with a dollar
sign and the letter Z ($Z) for specialized M functions.
global
The permanent storage medium used by M. Data is stored in a global array or a
simple global variable and generally is placed on a disk system.
global variable
A reference name for data stored in a global on disk. These variables can be accessed
or changed by any user on the system with the proper protection level.
hardware
The physical components of the computer system other than the software; for
example, the computer itself (monitor, disk drive, and so on), the tape drive, and the
printer.
indirection
A method of using the value of an expression rather than the expression itself. The
symbol used to indicate that indirection is being used is the at-sign (@), followed by
the value that represents the expression.

I/O supervisor
The facility of MSM which is responsible for the input, error detection, error
correction, and output operation of each device attached to the system. For each
device type, the I/O supervisor coordinates all data transfers and synchronizes them
with job execution.
interpreter
That part of the MSM system that processes the pseudo-machine code which has
been generated by the compiler.
job
A M partition separately managed by MSM with respect to execution and I/O.
journaling
A method of recording global SETs and KILLs while the system is in use. All
information is recorded in a journal entry which can be used to reconstruct the
database if necessary.
line
A string of characters ending with a specified read terminator (carriage return/line
feed).
line label
The optional name at the beginning of a routine line which identifies that line to the
system. This label is limited to eight characters and must begin with an alphabetic or
percent (%) character. Optionally, the label may contain parameter passing variables.
literal
A string, enclosed in quotations, which can be acted upon but not changed by a
command. The literal may contain any valid ASCII character; however, some of
these characters may be excluded because they have special meaning to the MSM
system.
local variable
Any variable that exists within memory only. These variables are unique to a
particular job and are valid only for the duration of the job's execution.
map
The space allocated for disk storage. Each map consists of 512 blocks (each 1024
bytes in size).

modem
Acronym for MOdulator DEModulator. This device is used to convert data to a
form which can be transmitted via a phone line to a remote site, and then
reconverted to a form usable by the remote site processing system.
M
Acronym for Massachusetts General Hospital Utility Multi-Programming System.
This system was developed in the late 1960s to handle storage, retrieval, and
manipulation of large amounts of medical data. It is one of only four ANSI standard
languages.
naked reference
A shortcut method for referring to a particular global node. The naked reference can
generally be used wherever a global reference is permitted. The naked reference can
be specified for a previously referenced node by using a circumflex (^), followed by
the unique portion of the descendant's subscript.
node
That element of a global array addressed by the name common to all members of the
array and a unique subscript.
operating system monitor

A system that provides an interface between the host operating system and MSM.
The monitor ensures that all system resources are properly allocated among users and
maintains system efficiency and throughput.
programmer access code (PAC)

A three-letter designation that the user must enter in order to gain access to
programmer mode. One PAC can be specified for each configuration on the system.
parameters
The collection of guidelines for the usage of a particular device.

partition
The area of memory which consists of a logical grouping of the local symbol table,
the current routine edit buffer, and the work areas used by the system and the job.
This space grows and shrinks based on the requirements of the current job.
peripherals
A collection of devices, both physical and logical, which are associated with the
MSM system. These devices are used to gain access to printers, terminals, and
sequential devices, and to examine or modify memory contents or alternate disk
storage.
programmer mode
The mode which permits the user to directly enter M commands to the interpreter.
Access is gained through entry of a valid UCI and PAC.
prompt
A system message which requires user input in response.
remote volume group

A volume group which belongs to a remote system, but is mounted for use on the
local system. The volume group is accessed through DDP.
routine name (RoutName)

A name for a grouping of one or more command lines.
routine types
library routines - A group of utility programs that is accessible to all users on the
system.
system manager routines - Routines that can be accessed only by entering the
Manager's UCI (MGR).
run mode
The method used to directly access a routine in a particular UCI. Access is obtained
by entering a valid UCI and routine name stored in that UCI.

S
sparse array
An array that contains space only for those elements which are actually defined.
special variables
A group of variables ($ZA, $ZB, and $ZC) which have special meaning to the MSM
system. These variables are used to indicate status information about the results of
the last operation performed.
stack
An area of the MSM system that is set aside for nesting of subroutines resulting from
execution commands.
stap
An area of the MSM system that is set aside for complex expression nesting.
string
Any set of ASCII characters with a maximum length of 255 characters.
string literal
A string of characters enclosed in double quotes within the context of a line.
subroutine
A collection of commands which together allow control to pass from the routine to
the subroutine and back to the main routine. Subroutines generally are used when
multiple recurring tasks are required for execution of the main routine.
subscript
A numeric or string interpreted value appended to a local or global variable used to
identify a specific element or node in an array. Subscripts must be enclosed in
parentheses and are separated by commas when more than one is indicated.
SYSGEN
The system generation utility used to specify one or more configurations to the MSM
system. These configurations are used by the system at startup to initialize the system
with the defined parameters. This is done via an interactive dialogue with MSM
which supports on-screen help for any prompted value.

T
terminators
The specified set of control characters which are used to terminate a read operation.
MSM uses a default value of line feed, carriage return ($C(10,13), but permits the
user to alter this value through use of proper parameters associated with the current
device.
tied terminal
A mode which is used to force a terminal to automatically start up a specific routine
in a UCI.
timeout
A timing convention which allows the user to specify how long the system should
attempt to perform a given command before proceeding. It is expressed in the format
of a colon (:), followed by an integer which is appended to a READ, OPEN, or JOB
command.
user class identifier (UCI)

The three-letter (uppercase) designation for a work area in the MSM system. Each
UCI has an unique routine and global directory.
utilities
library utilities - A group of utilities that are used to develop application programs
which require commonly performed functions.
system manager utilities - Utilities that are designed for use by the system manager
and that ensure proper system performance. These routines can be accessed only
from the Manager's UCI (MGR).
variable
A symbolic name for a location where data is stored. In MSM, there are three type of
variables:
local variables - Variables that are stored only in memory.
global variables - Variables that are stored in arrays for permanent storage on disk.
special variables - Variables that hold special meaning to the MSM system.

volume group (VolGroup)
A string value that specifies a three-character (uppercase) volume group name.
volume number (VolNum)

A numeric expression that specifies an internal volume group number.

Index
$ $SYSTEM Special Variable 239
$TEST
$ASCII Function 144
Function 172
$CHAR Function 145
Special Variable 54, 57, 66, 69, 76, 82, 95, 97, 108,
$DATA Function 90, 131, 146, 258, 259, 260, 261, 262
240
$DEVICE
$TEXT Function 105, 115, 117, 122, 128, 129, 172
Special Variable 99, 224
$TLEVEL Special Variable 94, 95, 96, 97, 241
$Structured System Variable 258
$TRANSLATE Function 174
$ECODE Special Variable 225, 253
$TRESTART Special Variable 94, 96, 242
$ESTACK Special Variable 80, 227
$VIEW Function 275
$ETEST Special Variables 80
$X Special Variable 86, 99, 103, 243
$ETRAP Special Variable 80, 229, 269
$Y Special Variable 86, 99, 103, 244
$EXTRACT Function 90, 147
$ZA Special Variable 50, 99, 129, 245
$FIND Function 149
$ZB Special Variable 69, 99, 129, 246
$FNUMBER Function 151
$ZBN Function 177
$GET Function 153
$ZBname Function 179
$GLOBAL Structured System Variable 259
$ZBOOLEAN Function 182
$HOROLOG Special Variable 113, 231, 271
$ZC 99, 247
$IO Special Variable 232, 271
$ZCALL 185, 276
$JOB
$ZCODE 266
$ZCRC 186
Structured System Variable 260
$ZCREATEOBJECT 188
$JUSTIFY Function 104, 154
$ZDATE 189
$KEY Special Variable 99, 234
$ZDEVICE 191
$LENGTH Function 155
$ZERROR 225, 248, 253, 266, 271, 274
$LEVEL Special Variable 249
$ZGETOBJECT 192
$LOCK Structured System Variable 261
$ZHEX 194
$NAME Function 156
$ZHL 195
$NEXT Function 157
$ZLEVEL 249
$ORDER Function 47, 159
$ZNAME 126, 128, 250
$PIECE Function 90, 92, 161
$ZNEXT 198
$PRINCIPAL Special Variable 235
$ZOBJREFERENCE 200
$QLENGTH Function 163
$ZORDER 201, 251
$QSUBSCRIPT Function 164
$ZOS 203
$QUERY Function 165
$ZPOSITION 212
$QUIT Function 236
$ZPREVIOUS 213
$RANDOM Function 167
$ZREFERENCE 251, 252, 271
$REVERSE Function 168
$ZSORT 215
$ROUTINE Structured System Variable 262
$ZTRAP 92, 99, 124, 229, 248, 253, 269, 272
$SELECT Function 57, 92, 169
$ZUCI 217
$STACK
$ZVERIFY 219
Function 170, 237
$ZVERSION 255
$ZWIDTH 221
$STORAGE Special Variable 81, 238, 271
MSM Language Reference Manual Index • 345

% LESS THAN 35
Logical 21
%ER Utility 271 MODULO DIVISION 23, 37
%ET Utility 271 MULTIPLICATION 23, 39
%MODESET Utility 274 NAND 25
NOR 41
^ NOT EQUAL TO 28
NOT GREATER THAN 30
^$DEVICE 258
NOT LESS THAN 35
^$GLOBAL 259
OR 41
^$JOB 260
PATTERN MATCH 23, 42
^$LOCK 261
Relational 21
^$ROUTINE 262
STRING CONTAINS 23
STRING CONTAINS Operator 45
A STRING FOLLOWS 23, 46
STRING SORTS AFTER 23, 47
Acknowledgment i
SUBTRACTION 23, 48
Actual List 55, 71, 139, 140, 141, 142
Bit
ADDITION 23, 24, 36
Functions 179
Algebraic
Manipulation 182
Difference 48
Strings 179
Sum 24
Block
Ancestor 76, 90
Disk 101
Global 107
Number 219
Nodes 131
Boolean Operators 21, 182
AND Operator 23, 25
AND 23
ANSI Standard M
EQUAL TO 23
Commands 49
GREATER THAN 23
Functions 139, 140
LESS THAN 23
Structured System Variables 257
NOT 23
ANSI X3.64-1979 Namespace 284
OR 23
Argument 32, 43, 49
Truth-Value 21, 40
Indirection, 32
Bracket Symbols 68
List 71, 140
BREAK
Post-Conditional 21
Command 50, 112, 272, 274
Arithmetic
Error 274
Operators 21
Function 275
ASCII Collating Sequence 43
Break Key 50, 78
Asterisk 97, 161
Buffer Cache 111
Asynchronous Error 274
Building, Expressions 19
Atom, Expression 19, 32
Automation Object 192
C
B Call-By-Reference 55, 71, 141
Call-By-Value 55, 71, 141
Background Job 68
Calling a Subroutine 53
Binary Operators 23
Canonic Numbers 47
ADDITION 23, 24
Carriage return ii
AND 25
Characters
CONCATENATE 23, 26
Alphabetic 42
DIVIDE 23
ASCII 144, 145
DIVISION 27
Control 42
EXPONENTIATION 23, 29
Format 86, 103
GREATER THAN 30
Reverse Order 168
INTEGER DIVISION 23, 34
Checksum 186
346 • Index MSM Language Reference Manual

Circumflex 117, 172, 177, 219 ZSYNC 134
Clobber Error 274 ZTRAP 135
CLOSE Command 52, 99 ZUSE 136
Collating Sequence 47 ZWRITE 137
Comma 151 Concatenate 21
Commands Maximum String Size 26
BREAK 50, 112, 272, 274 CONCATENATE Operator 23, 26
CLOSE 52, 99 Constant Values 31
Definition 49 Constants 103
DO 53, 68, 227, 237, 249, 253, 269 Conventions
DO With Parameter Passing 55 documentation ii
ELSE 57 Special Variables 223
Error 274 Structured System Variables 257
FOR 53, 58, 59, 249 Copy Data See MERGE Command
GOTO 58, 62, 124, 229, 253, 267 Cursor Position
HALT 52, 64 Current Horizontal 243
HANG 65 Current Vertical 244
IF 57, 66, 240 Cyclic Redundancy Check 186
JOB 57, 66, 68, 233, 235, 240
JOB With Parameter Passing 71 D
KILL 73
LOCK 57, 64, 66, 75, 240 Database
MERGE 78, 275 Bullet-Proof 94, 95, 96, 98
Naming Conventions 49 Restore 94, 95, 96, 98
NEW 73, 80, 227, 229, 269 Date
OPEN 52, 57, 66, 82, 240, 275 External 189
Overview 49 Date and Time 231
Post-Conditional 21, 22 DDP Link Failure 274
QUIT 50, 53, 54, 58, 80, 84, 105, 227, 237, 249, 267, DDP Server Error 274
269 Debugging 50, 112
READ 57, 66, 86, 234, 240 Interactive 272
SET 90, 229 Device
TCOMMIT 94, 98, 241, 242 Name 191
TRESTART 95, 242 Numbers
TROLLBACK 96, 241, 242 Current Device 232
TSTART 95, 97, 98, 241 Ownership 82, 99, 136
USE 99, 232 Principal 52, 82, 99
User-Defined 310 Read from 86
VIEW 101, 275 Releasing 52
WRITE 103 Device Not Open Error 275
XECUTE 105, 227, 237, 249, 253, 269 Disconnect Error 274
ZALLOCATE 57, 64, 66, 107, 240 Disk
ZDEALLOCATE 110 Blocks 101
ZFLUSH 111 Allocation 177
ZGO 50, 112, 274 Deallocation 177
ZHOROLOG 113 Buffer Cache 111
ZINSERT 115, 238, 274, 275 Full Error 274
ZLOAD 117, 274 Hard Error 274
ZMSM 119 Distributed Data Processing 274, 275
ZNEW 120 Divide Error 274
ZPRINT 122 DIVIDE Operator 23
ZQUIT 124, 269 DIVISION Operator 27
ZREMOVE 126, 274 DO Command 22, 53, 68, 227, 237, 249, 253, 269
ZSAVE 126, 128, 276 Argumentless 53
ZSETOBJ 131 Parameter Passing 55

Structured Subroutines 53 <MXMEM> 275
DO/XECUTE Command <MXNUM> 275
Stack 50, 272 <MXSTR> 275
Documentation conventions ii <NAKED> 275
Dollar Sign 139, 140 <NODEV> 275
Special Variables 223 <NOJRN> 275
<NOPEN> 275
E <NOPGM> 275
<NOSYS> 275
ECHO 87 <NOUCI> 275
Editing <PCERR> 276
ZINSERT 115 <PGMOV> 276
ZLOAD 117 <PLDER> 276
ZSAVE 128 <PROT> 276
Elements, Expression 19 <SBSCR> 276
ELSE Command 22, 57 <STKOV> 276
Endless Loop 59 <SYNTX> 276
Entry Reference 55, 71, 141, 142 <SYSTM> 276
Equal Sign 147, 161 <TPROC> 276
EQUAL TO Operator 23, 28 <UNDEF> 276
Error <VWERR> 276
Messages 55, 71, 94, 99, 129, 141, 142, 219, 248 <ZCALL> 276
Processing 50, 119, 135 <ZSAVE> 276
Trapping 99, 124, 129, 135, 248, 253, 266 <ZSVGP> 276
Downlevel 272 Internal 276
Format 272 ESC Key 87
Interactive Debugging 272 ESTACK Special Variable 237
Errors Execution
< BADCH > 274 Stack 170
< BKERR > 274 Suspend 50, 65
< CLOBR > 274 Exponentiation Error 274
< CMMND > 274 EXPONENTIATION Operator 23, 29
< DDPER > 274 Expression 19, 20, 139, 140, 141, 142
< DIVER > 274 Atom 19, 32
< DKFUL > 274 Elements 19
< DKHER > 274 Evaluation 36, 44
< DKRES > 274 Indirection 52, 58, 90
< DKSER > 274 Left-to-Right 20, 90, 169, 174
< DPARM > 274 Numeric Values 20
< DSCON > 274 Post-Conditional 20
< DSTDB > 274 String Values 20
< EXPER > 274 Truth-Valued 20
< FUNCT > 274 Integer 21
< INDER > 274 Numeric 21, 24, 25, 27, 29, 30, 34, 35, 36, 37, 39, 48
< INHIB > 275 Post-Conditional 21, 57, 240
< INRPT > 275 Rules for Building 19
< ISYNT > 275 String 21, 26, 28, 45, 46, 47
<ASYNC> 274 Types 20
<LCNSE> 275 Numeric 20
<LINER> 275 Post-Conditional 20
<MAPER> 275 String 20
<MERGE> 275 Truth-Valued 20, 21, 28, 30, 35, 40, 41, 43, 45, 46,
<MINUS> 275 47, 66, 169
<MODER> 275 External Routine Calls 185
<MTERR> 275 Extrinsic Functions 84, 139

Definition 140 $ZCREATEOBJECT 188
Syntax 140 $ZDATE 189
$ZDEVICE 191
F $ZFIND 180
$ZGET 180
Floating Point $ZGETOBJECT 192
Numbers 102 $ZHEX 194
FOR Command 22, 53, 58, 59, 249 $ZNEXT 198
Loops 266 $ZORDER 201
Nesting 60 $ZOS 203
Scope 58 $ZPREVIOUS 213
With QUIT 84 $ZSORT 215
Formal List 55, 71, 141, 142 $ZUCI 217
Format Characters 87, 104 $ZVERIFY 219
Free Space 238 BREAK 275
Functions Definition 139
$ASCII 144 Name 140
$CHAR 145 User-Defined 310
$DATA 90, 131, 146, 258, 259, 260, 261, 262
$EXTRACT 90, 147
G
$FIND 149
$FNUMBER 151 Global
$GET 153 Availability 259
$HOROLOG 189 Global Reference 251, 252
$JUSTIFY 104, 154 GOTO Command 22, 58, 124, 229, 253, 267
$LENGTH 155 GREATER THAN Operator 23, 30
$NAME 156 GREATER THAN OR EQUAL TO 35
$NEXT 157
$ORDER 47, 159 H
$PIECE 90, 92, 161
$QLENGTH 163 HALT Command 52, 64
$QSUBSCRIPT 164 HANG Command 65
$QUERY 165 Hexadecimal 175
$QUIT 236 HEXADECIMAL Operator 23, 31
$RANDOM 167
$REVERSE 168 I
$SELECT 57, 92, 169
$STACK 170 IF Command 22, 57, 66, 240
$TEXT 105, 115, 117, 122, 128, 129, 172 Indicators
$TRANSLATE 174 Naked 146, 153
$VIEW 175, 275 Indirection 32, 43, 54, 131
$ZB Bit 179, 180, 181 Argument 32
$ZBAND 179 Error 274
$ZBLEN 180 Name 32
$ZBN 177 Pattern 32
$ZBname 179 Subscript 32
$ZBNOT 180 Expression Atom 32
$ZBOOLEAN 182 INDIRECTION Operator 23, 32
$ZBOR 180 Input/Output 224, 232
$ZBSET 180 Insert Error 275
$ZBSTR 181 Integer 21,144, 145, 149, 155, 219
$ZBXOR 181 Division 34
$ZCALL 185, 276 Expressions 21
$ZCOUNT 180 INTEGER DIVISION Operator 23, 34
$ZCRC 186 Interactive Debugging 272

Internal Errors 276 MERGE Command 78, 275
Interrupt Error 275
Error 275 Messages to Other Users 136
Execution 50 Minor Number 273
Intrinsic Functions 139 MINUS Operator 23, 36
Syntax 139 Minus Sign 151
Invalid Negative Number 275 Mnemonic
Invalid P-Code Error 276 Controls 284
Iteration 60 Namespaces 86, 99, 299
Add 301
J ANSI X3.64-1979 284
Copy 302
JOB Command 57, 66, 68, 233, 235, 240 Delete 304
Background 68 Edit 303
Number 69 Export 305
Parameter Passing 71 Import 306
Job Number 233, 235, 260 Invoking Utility 300
Journal, After-Image 94, 95, 96, 98 List 300
Rename 305
K WRITE Command 103
ZWINTERM 288
Keywords 97 Mode Error 275
KILL Command 73 MODE Flags 50
MODULO DIVISION Operator 23, 37
L MULTIPLICATION Operator 23, 39
LESS THAN Operator 23, 35

LESS THAN OR EQUAL TO 30 N
License Error 275 Naked
Line Error 275 Indicator 76, 90, 96, 97, 107
List, Argument 140 Error 274, 275
Literal, Numeric 19, 28 References 146, 165
LOCK Name Indirection 32
Command 57, 64, 66, 75, 240 NAND 25
Incremental 75 Nesting
Table 75 Level 249
Locking Variables 75, 107, 110 Network Flush See ZSYNC Command
Logging Out 64 NEW Command 73, 80, 229, 269
Loops 58 No Device Error 275
No Journal Allowed Error 275
M No Program Error 275
No System Error 275
Magnetic Tape Error 275 No UCI Error 275
Major Number 273 NOR 41
Map Block Error 275 NOT 25, 28, 30, 35, 41, 43, 45, 46, 47
Mask Values 151, 174, 182 NOT EQUAL TO 28
Maximum NOT GREATER THAN 30
Memory Error 275 NOT LESS THAN 35
Number Error 275 NOT Operator 23, 40
String Error 275 NOT OR 41
Memory Null Line 117
Access 101 Numbers, Canonic 47
Insufficient 276
Location 175

Numeric Output 103
Expression 21, 24, 25, 27, 29, 30, 34, 35, 36, 37, 39,
48 P
Literal 19, 28
Parameter Passing
Call-By-Value 141
O
Error 274
Object Automation 192 With DO 55
OPEN Command 52, 57, 66, 82, 275 With JOB 71
Operands Parentheses 97, 177
As Part of Command 49 Partition Size 69, 238
Operators See Binary Operators. See Unary Operators Pattern
ADDITION 24 Indirection 32
AND 25 Match 23, 42, 43
Arithmetic 21 Percent Sign 32
Binary 19, 20, 23 Period 141
Binary Logical 21 PLUS Operator 23, 44
Binary Relational 21 Plus Sign 151, 172
Boolean 21, 25 Post-Conditional
CONCATENATE 21, 26 Argument
DIVISION 27 Invalid 276
EQUAL TO 28 Command 21, 22
EXPONENTIATION 29 Definition 21
GREATER THAN 30 Error 276
GREATER THAN OR EQUAL TO 35 Illegal 276
HEXADECIMAL 31 Precision 24, 27, 29, 34, 37, 39
Indirection 20, 32, 43 PRINCIPAL Special Variable 82
INTEGER DIVISION 34 Processes See JOB Command
LESS THAN 35 Program
LESS THAN OR EQUAL TO 30 Control 53, 62
MINUS 36 Overflow Error 276
MODULO DIVISION 37 Protection Error 276
MULTIPLICATION 39 Pseudo Random 167
NAND 25 Pseudo-Code 128
NOR 41
NOT 25, 28, 30, 35, 40, 41, 43, 45, 46, 47 Q
NOT EQUAL TO 28
NOT GREATER THAN 30 QUIT Command 50, 53, 54, 58, 80, 84, 227, 237, 249,
NOT LESS THAN 35 267, 269
NOT OR 41 Quotient 27, 34, 37
OR 41
PATTERN MATCH 32, 42 R
PLUS 44
Relational 23 READ Command 57, 66, 86, 240
String 23 Reference
STRING CONTAINS 45 Entry 62
STRING DOES NOT CONTAIN 45 Extended 53
STRING DOES NOT FOLLOW 46 Full 76, 107
STRING DOES NOT SORT AFTER 47 Naked 90, 156, 165, 213, 215
STRING FOLLOWS 46, 47 Relational Operators 23
STRING SORTS AFTER 47 Restarts
SUBTRACTION 48 Transaction 241, 242
Summary of 23 Return Key 87, 105, 117
Unary 19, 20, 23
OR Operator 23, 41, 186

Routine STRING CONTAINS 45
Availability 262 Operator 23
Calling 53 STRING DOES NOT CONTAIN 45
Interruption 50 STRING DOES NOT FOLLOW 46
Name 250 STRING DOES NOT SORT AFTER 47
String Expressions 26, 28, 45, 46, 47
S STRING FOLLOWS 46, 47
Operator 23, 46
Saving String Literal 86
Routines 128 String Operators 23
Variables 55, 80, 120 STRING SORTS AFTER Operator 23, 47
Serialization 97 Structured System Variables 257
Session, Terminate 64 $DEVICE 258
SET Command 90, 229 $GLOBAL 259
Slash Commands 284 $JOB 260
Special Variables $LOCK 261
$DEVICE 99, 224 $ROUTINE 262
$ECODE 225, 253 Conventions 257
$ESTACK 80, 227, 237 Definition 257
$ETEST 80 Subexpressions 20
$ETRAP 80, 229, 269 Subroutine
$HOROLOG 113, 231, 271 Block Structured 54
$IO 232, 271 Subscript 213, 215
$JOB 233, 271 Error 276
$KEY 99, 234 Indirection 32
$LEVEL 249 Subtraction 36
$PRINCIPAL 235 SUBTRACTION Operator 23, 48
$STACK 237, 266 Subtransaction 97
$STORAGE 81, 238, 271 Suspend Execution 50, 65
$SYSTEM 239 Symbol Table 69, 70, 73, 80, 141
$TEST 54, 57, 66, 69, 76, 82, 95, 108, 240 Synchronizing Resources 75
$TLEVEL 94, 95, 97, 241 Syntax Error 276
$TRESTART 94, 96, 242 SYSGEN Utility 50, 69
$X 86, 99, 103, 243 Mnemonic Namespaces 299, 300, 301, 302, 303, 304,
$Y 86, 99, 103, 244 305, 306
$ZA 50, 99, 129, 245 System Error 276
$ZB 69, 99, 129, 246
$ZC 99, 247
T
$ZCODE 266
$ZERROR 225, 248, 253, 266, 271, 274 Tab Character 105
$ZNAME 126, 128, 250 TCOMMIT Command 94, 98, 241, 242
$ZORDER 251 Terminate Session 64
$ZREFERENCE 80, 251, 271 Time and Date 231
$ZTRAP 92, 99, 124, 229, 248, 253, 269, 272 Timeout 69, 76, 87, 108, 234, 240
$ZVERSION 255 Tracing Errors 50, 112, 119
Conventions 223 Transaction 94, 95, 96, 97, 134, 241
Definition 223 Processing Error 276
TEST 57, 66 Restarts 241, 242
User-Defined 310 Trapping Errors 248, 253
SSVNs See Structured System Variables TRESTART Command 95, 242
Stack TROLLBACK Command 96, 241, 242
DO/XECUTE 50 Truth-Valued Expressions 28, 30, 35, 40, 41, 43, 45,
Overflow Error 276 46, 47, 169, 240
String TSTART Command 95, 97, 241
Expressions 21 Typeahead 87

U ZMSM Command 119
ZNEW Command 120
Unary Operators 23 ZPRINT Command 122
EQUAL TO 28 ZQUIT Command 124, 269
HEXADECIMAL 23, 31 ZREMOVE Command 126, 274
INDIRECTION 23, 32 ZSAVE Command 126, 128, 276
MINUS 23, 36 ZSETOBJ Command 131
NOT 40 ZSYNC Command 134
PLUS 23, 44 ZTRAP Command 135
Undefined ZUSE Command 136
Function Error 274 ZWINTERM Mnemonic Namespace 288
Variable Error 276 ZWRITE Command 137
Unlock 107, 110
USE Command 99,
User-Class Identifier 53, 68, 71, 75, 107, 117, 128
Utilities
%ER 271
%ET 271
%MODESET 274
V
Values
Negative 151
Variables 103
Deletion 73
Global 78, 90, 107, 110
Local 19, 78, 80, 90, 107, 110
Special 80, 223
Stacked 80
VIEW Command 101, 105
View Device Error 276
Volume
Group 68, 71, 101, 177, 217, 219, 252
Name 217
Number 217, 219
W
WRITE Command 103
X
XECUTE Command 22, 105, 227, 237, 249, 253, 269
With QUIT 84
Z
ZALLOCATE Command 57, 64, 66, 107, 240
ZDEALLOCATE Command 110
ZFLUSH Command 111
ZGO Command 50, 112, 274
ZHOROLOG Command 113
ZINSERT Command 115, 238, 274, 275
ZLOAD Command 117, 238, 274


MSM-Language Reference Manual v.1.0 (Micronetics) 1996

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MSM-Language Reference Manual v.1.0 (Micronetics) 1996

Uploaded by

Copyright:

Available Formats

MSM

Language Reference Manual

Micronetics Design Corporation

Chapter 1 Language Syntax 1

Chapter 2 Expression Elements 19

MSM Language Reference Manual Contents • iii

Chapter 3 MSM Operators 23

Chapter 4 MSM Commands 49

iv • Contents MSM Language Reference Manual

Chapter 5 MSM Functions 139

MSM Language Reference Manual Contents • v

Chapter 6 MSM Special Variables 223

vi • Contents MSM Language Reference Manual

Appendix A ASCII Collating Sequence 263

Appendix B Error Processing 265

Appendix C Mnemonic Namespaces 283

MSM Language Reference Manual Contents • vii

Appendix D User-Defined Commands 309

Appendix E Macro Facility 313

viii • Contents MSM Language Reference Manual

Glossary of Terms 335

MSM Language Reference Manual Contents • ix

MSM Language Reference Manual Preface • xi

xii • Preface MSM Language Reference Manual

MSM Language Reference Manual Chapter 1 Language Syntax • 1

2 • Chapter 1 Language Syntax MSM Language Reference Manual

. A period indicates that a variable in a parameter list should be passed by

MSM Language Reference Manual Chapter 1 Language Syntax • 3

4 • Chapter 1 Language Syntax MSM Language Reference Manual

MSM Language Reference Manual Chapter 1 Language Syntax • 5

Command and Command Line Syntax

WRITE SP "BASKET" SP SP WRITE SP "BALL"

Generally, command names can be abbreviated to a single letter (such as G for

6 • Chapter 1 Language Syntax MSM Language Reference Manual

When a routine is created, it can be assigned a unique name (referred to as

MSM Language Reference Manual Chapter 1 Language Syntax • 7

Block Structured Subroutines

8 • Chapter 1 Language Syntax MSM Language Reference Manual

MSM Language Reference Manual Chapter 1 Language Syntax • 9

Numbers and Strings

10 • Chapter 1 Language Syntax MSM Language Reference Manual

When a computation is performed, MSM automatically converts mixed-mode

Constants can be used in numeric expressions (for example, 2+2), in assignment

MSM Language Reference Manual Chapter 1 Language Syntax • 11

12 • Chapter 1 Language Syntax MSM Language Reference Manual

Arrays and Subscripts

In a local array, individual subscripts can be a maximum of 2044 characters in

MSM Language Reference Manual Chapter 1 Language Syntax • 13

14 • Chapter 1 Language Syntax MSM Language Reference Manual

A newly created global is assumed to be in numeric collating sequence. A global's

Extended Global References

MSM Language Reference Manual Chapter 1 Language Syntax • 15

UCI Translation and Replication

External Program Calls

In these formats, Variable is a local or global variable, PackageName is the name of

16 • Chapter 1 Language Syntax MSM Language Reference Manual

ObjectExpression is either a local variable whose value is an object reference or an

Parameters optionally can be passed to members. In the above example, local

MSM Language Reference Manual Chapter 1 Language Syntax • 17

18 • Chapter 1 Language Syntax MSM Language Reference Manual

MSM Language Reference Manual Chapter 2 Expression Elements • 19

20 • Chapter 2 Expression Elements MSM Language Reference Manual

MSM Language Reference Manual Chapter 2 Expression Elements • 21

22 • Chapter 2 Expression Elements MSM Language Reference Manual