060

/DQJXDJH5HIHUHQFH
0DQXDO

9HUVLRQ

0DUFK

0LFURQHWLFV'HVLJQ&RUSRUDWLRQ
 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  1998
Micronetics Design Corporation
1375 Piccard Drive
Rockville, Maryland 20850
Telephone: 301-258-2605
Fax: 301-840-8943
E-Mail: [email protected]
WWW: www.micronetics.com

ii
Contents
Preface ix
Acknowledgment.......................................................................................................................ix
Documentation Conventions .....................................................................................................ix

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

Expression Elements 19
Overview..................................................................................................................................19
Building Expressions................................................................................................................19
Evaluating Expressions ............................................................................................................20

MSM Language Reference Manual Contents • iii

 Numeric Expressions............................................................................................................ ... 21
String Expressions................................................................................................................... 21
Truth-Valued Expressions ....................................................................................................... 21
Post-Conditional Expressions.................................................................................................. 21

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

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.......................................................................................................................................... 89
TCOMMIT.............................................................................................................................. 93

iv • Contents MSM Language Reference Manual

 TRESTART .............................................................................................................................94
TROLLBACK..........................................................................................................................95
TSTART ..................................................................................................................................96
USE ..........................................................................................................................................98
VIEW .....................................................................................................................................100
WRITE...................................................................................................................................102
XECUTE................................................................................................................................104
ZALLOCATE ........................................................................................................................106
ZDEALLOCATE ...................................................................................................................109
ZFLUSH.................................................................................................................................110
ZGO .......................................................................................................................................111
ZHOROLOG..........................................................................................................................112
ZINSERT ...............................................................................................................................113
ZLOAD ..................................................................................................................................115
ZMSM....................................................................................................................................117
ZNEW ....................................................................................................................................118
ZPRINT..................................................................................................................................120
ZQUIT....................................................................................................................................122
ZREMOVE ............................................................................................................................124
ZSAVE...................................................................................................................................126
ZSETOBJ ...............................................................................................................................129
ZSYNC...................................................................................................................................131
ZTRAP ...................................................................................................................................132
ZUSE......................................................................................................................................133
ZWRITE ................................................................................................................................134

MSM Functions 135

Overview................................................................................................................................135
Intrinsic Functions....................................................................................................135
Extrinsic Functions ..................................................................................................136
$ASCII ...................................................................................................................................140
$CHAR...................................................................................................................................141
$DATA...................................................................................................................................142
$EXTRACT ...........................................................................................................................143
$FIND ....................................................................................................................................145
$FNUMBER ..........................................................................................................................146
$GET......................................................................................................................................148
$JUSTIFY ..............................................................................................................................149
$LENGTH..............................................................................................................................150
$NAME..................................................................................................................................151
$NEXT ...................................................................................................................................152
$ORDER ................................................................................................................................154
$PIECE ..................................................................................................................................156
$QLENGTH...........................................................................................................................158
$QSUBSCRIPT .....................................................................................................................159
$QUERY................................................................................................................................160
$RANDOM ............................................................................................................................161
$REVERSE ............................................................................................................................162
$SELECT ...............................................................................................................................163
$STACK.................................................................................................................................164
$TEXT ...................................................................................................................................166
$TRANSLATE ......................................................................................................................168
$VIEW ...................................................................................................................................169
$ZASCII.................................................................................................................................171

MSM Language Reference Manual Contents • v

 $ZBN..................................................................................................................................... 172
$ZBname ............................................................................................................................... 174
$ZBOOLEAN ....................................................................................................................... 177
$ZCALL ................................................................................................................................ 180
$ZCHAR ............................................................................................................................... 181
$ZCRC .................................................................................................................................. 182
$ZCREATEOBJECT ............................................................................................................ 184
$ZDATE................................................................................................................................ 185
$ZDEVICE............................................................................................................................ 186
$ZGETOBJECT .................................................................................................................... 187
$ZHEX .................................................................................................................................. 189
$ZHL ..................................................................................................................................... 190
$ZNEXT................................................................................................................................ 193
$ZOBJREFERENCE............................................................................................................. 194
$ZORDER............................................................................................................................. 195
$ZOS ..................................................................................................................................... 196
Set Current Drive .................................................................................................... 196
Delete a File ............................................................................................................ 197
Rename a File.......................................................................................................... 197
Get Windows Version Number ............................................................................... 198
Set File Attributes ................................................................................................... 198
Create a New Directory........................................................................................... 198
Remove an Existing Directory ................................................................................ 199
Change Current Directory ....................................................................................... 199
Get Drive Parameters .............................................................................................. 200
Get File Attributes................................................................................................... 200
Get Current Directory for Drive.............................................................................. 201
Begin Directory Search ........................................................................................... 201
Continue Directory Search ...................................................................................... 202
Get Current Drive.................................................................................................... 203
Close Directory Search ........................................................................................... 203
Get Available Drives............................................................................................... 203
$ZOS Function Call Errors ..................................................................................... 204
$ZPOSITION ........................................................................................................................ 205
$ZPREVIOUS....................................................................................................................... 206
$ZSORT ................................................................................................................................ 207
$ZUCI ................................................................................................................................... 209
$ZVERIFY ............................................................................................................................ 210
$ZWIDTH ............................................................................................................................. 212

MSM Special Variables 213

Overview ............................................................................................................................... 213
$DEVICE .............................................................................................................................. 214
$ECODE ............................................................................................................................... 215
$ESTACK ............................................................................................................................. 217
$ETRAP ................................................................................................................................ 219
$HOROLOG ......................................................................................................................... 221
$IO ........................................................................................................................................ 222
$JOB...................................................................................................................................... 223
$KEY .................................................................................................................................... 224
$PRINCIPAL ........................................................................................................................ 225
$QUIT ................................................................................................................................... 226
$STACK................................................................................................................................ 227
$STORAGE .......................................................................................................................... 228

vi • Contents MSM Language Reference Manual

 $SYSTEM..............................................................................................................................229
$TEST ....................................................................................................................................230
$TLEVEL...............................................................................................................................231
$TRESTART .........................................................................................................................232
$X...........................................................................................................................................233
$Y...........................................................................................................................................234
$ZA ........................................................................................................................................235
$ZB ........................................................................................................................................236
$ZC ........................................................................................................................................237
$ZERROR ..............................................................................................................................238
$ZLEVEL...............................................................................................................................239
$ZNAME ...............................................................................................................................240
$ZORDER..............................................................................................................................241
$ZREFERENCE ....................................................................................................................242
$ZTRAP .................................................................................................................................243
$ZVERSION ..........................................................................................................................245

MSM Structured System Variables 247

Overview....................................................................................................................... .........247
^$DEVICE .............................................................................................................................248
^$GLOBAL............................................................................................................................249
^$JOB.....................................................................................................................................250
^$LOCK.................................................................................................................................251
^$ROUTINE ..........................................................................................................................252

ASCII Collating Sequence 253

Overview................................................................................................................................253

Error Processing 255

Overview....................................................................................................................... .........255
Error Processing.....................................................................................................................255
Actions: When Error Condition is Detected ............................................................255
Actions: When Error-Handling is Specified ............................................................256
Default Error Processing..........................................................................................257
User-Defined Error Processing ................................................................................257
Processing Trapped Errors.......................................................................................258
Using the System Error Trap....................................................................................260
Using Downlevel Error Trapping.............................................................................261
Interactive Debugging..............................................................................................261
Format of $ZERROR ...............................................................................................261
MSM Error Codes..................................................................................................................263
MSM Error Numbers .............................................................................................................267
$ECODE Errors .....................................................................................................................271

Mnemonic Namespaces 273

Overview................................................................................................................................273
ANSI X3.64-1979 Namespace ...............................................................................................274
ZWINTERM Namespace.......................................................................................................278
Attributes .................................................................................................................278
Erase Operations ......................................................................................................279
Error Codes..............................................................................................................280
ZWINTERM Namespace Commands ....................................................................................281

MSM Language Reference Manual Contents • vii

 SYSGEN Mnemonic Namespaces ........................................................................................ 288
SYSGEN Mnemonic Namespace Options .............................................................. 289
Delete Existing Namespace..................................................................................... 293

User-Defined Commands 297

Overview ....................................................................................................................... ........ 297
Commands, Functions, and Special Variables....................................................................... 297
Passing Parameters to the Routine......................................................................................... 299

Macro Facility 301

Overview ............................................................................................................................... 301
Definitions............................................................................................................................. 302
Basic Usage ........................................................................................................................... 304
Defining a Macro .................................................................................................... 304
Referencing a Macro ............................................................................................... 304
Using Parameters .................................................................................................... 305
Including a File ....................................................................................................... 306
Debugging............................................................................................................... 306
Generated Comment................................................................................................ 306
Advanced Capabilities........................................................................................................... 307
Libraries .................................................................................................................. 307
Conditional Compilation ......................................................................................... 308
Special Macros........................................................................................................ 308
Additional Parameter Functions.............................................................................. 310
Multi-Line Definitions ............................................................................................ 311
Computed Definitions ............................................................................................. 311
System Functions .................................................................................................... 311
Changing the Prefix................................................................................................. 312
Preprocessor Directives......................................................................................................... 313
#comment................................................................................................................ 313
#defarray ................................................................................................................. 313
#define .................................................................................................................... 314
#deflabel.................................................................................................................. 315
#if, #elseif, #else, #endif ......................................................................................... 315
#ifdef, #ifndef.......................................................................................................... 316
#include................................................................................................................... 316
#library.................................................................................................................... 317
#makelib.................................................................................................................. 317
#nocomment............................................................................................................ 318
#noroutine ............................................................................................................... 318
#prefix..................................................................................................................... 318
#routine ................................................................................................................... 319
#undefine................................................................................................................. 319
#updlib .................................................................................................................... 320
#x ............................................................................................................................ 320
Technical Components .......................................................................................................... 321

Glossary 323

Index 333

viii • Contents MSM Language Reference Manual

Preface

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

Documentation Conventions
The following documentation conventions are used in this manual.

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

MSM Language Reference Manual Preface • ix

x • Preface MSM Language Reference Manual
Language Syntax

Overview
Micronetics Standard M (MSM) is an implementation, with extensions, of the ANSI
Standard (X11.1-1995) M programming language. The M language has been
implemented in MSM through a language compiler and a pseudo-code (p-code)
interpreter. The language compiler converts M code into pseudo-machine code that
can be processed by the p-code interpreter. The rapid interpretation of the p-code
during program execution allows applications to run in a stand-alone environment or
under a host operating system with exceptionally fast response time.
Even though MSM has been implemented as a compiler, it still provides all of the
flexibility of an interpreter. M code can be entered directly from the keyboard into
the compiler to provide instantaneous results without a separate compilation step.
The file system in MSM has been implemented using a compressed-key, B-tree
structure to ensure optimum performance. The system supports a disk buffer cache,
delayed write operations on modified buffers, and other performance features aimed
at maximizing throughput.

MSM Language Reference Manual 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 “ASCII
Collating Sequence” in this manual for a complete list of the ASCII character set.
The MSM system internally carries all characters as 8-bit values and expands the
accessible character set to 256 distinct combinations. Within the ASCII character set,
certain characters have special meaning to MSM, and are grouped as: delimiters,
prefixes, line terminators, format characters, and control characters.

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 • Language Syntax MSM Language Reference Manual

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

Line Terminators
Line terminators are recognized by the compiler to signal the end of data input to the
compiler or a program. The following table lists the default line terminators
recognized by the system.
/LQH 7HUPLQDWRUV
Character Description
RETURN Signals the end of input to the compiler or an executing routine.
ESC Signals the end of input unless escape processing is enabled.

Format Characters
Format characters can be used in READ or WRITE commands to send carriage
control commands to a device. The following table lists the format characters
recognized by MSM.
)RUPDW &KDUDFWHUV
Character Description
# A pound sign (#) instructs the system to send a carriage return and a
form-feed sequence to the device. The $X and $Y special variables are reset
to 0.
! An exclamation point (!) instructs the system to send a carriage return and a
line-feed sequence to the device. The $X special variable is reset to 0, and
the $Y special variable is incremented by 1.
? A question mark followed by an integer value (for example: ?2) indicates
the column where the next output is to take place. The $X special variable
is adjusted to reflect the new output position, and the $Y special variable is
not changed.
/ A slash (/) indicates the start of a mnemonic namespace request.

MSM Language Reference Manual Language Syntax • 3

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

Refer to “Using Peripheral Devices” in the MSM User’s Guide for information on
preventing or altering interpretation of these control characters by MSM.

4 • Language Syntax MSM Language Reference Manual

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

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.

MSM Language Reference Manual Language Syntax • 5

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” SPSP WRITE SP “BALL”

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

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

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

GOTO), or in the case of MSM-specific command names, two letters (such as ZI for
ZINSERT). In some cases, more than one command name in the M language has the
same first letter (for example, HALT and HANG). In this situation, the syntax of the
argument determines which command is specified.
In MSM, the following rules must be used when writing commands and command
lines:
• Every command line begins with a command.
• Arguments are separated from the command name by one space.
• A command can be followed by none, one, or several arguments.
• All commands are separated from other commands by at least one space.
Additional spaces can be used to enhance readability.
• When a command with no arguments appears in a command line, the absence of
the argument is indicated by a single space. Within a command line, a command
with no arguments is separated from the following command by two or more
spaces. The following example illustrates the format of MSM command lines:
Command SP Argument SP... SP Command SP Argument

6 • Language Syntax MSM Language Reference Manual

 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.

MSM Language Reference Manual Language Syntax • 7

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

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

Block Structured Subroutines

Often it is desirable to group several lines of code into a subroutine that will be
executed only once. This most frequently occurs because the scope of the FOR, IF,
and ELSE commands is limited to the amount of text that fits on the remainder of a
routine line. To facilitate the development of this limited-use subroutine, M supports
block structured code. This technique allows a subroutine to directly follow the code
that invokes it. Block-structured subroutines are used to create programs that have a
more consistent logical flow and are easier to read.
The key to understanding the operation of block structured subroutines is to become
familiar with the concept of execution levels. When an M program first is invoked, it
is considered to be at execution level 1. When a DO command is used in a routine to
invoke a subroutine, the subroutine is at execution level 2. If that subroutine then
invokes another subroutine using the DO command, the new subroutine is at
execution level 3, and so on.
When a subroutine terminates, it always returns to the previous execution level, and
execution continues with the command that immediately follows the DO command.
Generally, a subroutine starts with a routine line that contains a label and ends with a
QUIT command.
With a block structured subroutine, a slightly different approach is taken. Each
command line in the subroutine is preceded by one or more PERIOD characters to
indicate the execution level of the routine line. The following example illustrates the
format of a routine line in a block structured subroutine:
Label TAB PERIOD ... PERIOD Command Line
TAB PERIOD ... PERIOD Command Line

In a general sense, the execution level of a routine line is equal to the number of
PERIOD characters plus one. Thus, a routine line that is not preceded by any PERIOD
characters can be considered to be at execution level 1, a line that is preceded with
one PERIOD character is at execution level 2, and so on.
A block structured subroutine is invoked with a DO command that has no arguments.
The subroutine must immediately follow the routine line that contains the DO
command, and the execution level of the subroutine must be exactly one greater than
the level of the routine line that invoked it.

8 • Language Syntax MSM Language Reference Manual

 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.

MSM Language Reference Manual Language Syntax • 9

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 32764 characters in length when they are used with local
variables, and a maximum of 511 characters (the default is 255 characters) in length
when they are used with global variables.

10 • Language Syntax MSM Language Reference Manual

 Literals
In MSM, a literal is a string that is enclosed within quotation marks (“ ”). If the quote
character is to appear in the literal, it is indicated by two consecutive quotes. The
value of a literal can be acted upon by a command, but it cannot be changed by a
command. The following are examples of valid literals.
“THIS IS AN EXAMPLE OF A LITERAL”
“123.456”
“99+44”
“!#$%|& SPECIAL CHARACTERS”

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

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

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

commands (for example: SET X=2), and so on.

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

MSM Language Reference Manual Language Syntax • 11

Variables
In MSM, a variable is a symbolic name assigned to a data value that can be either
temporary or permanent. A local variable is a temporary data value that exists for the
duration of the terminal session or routine that creates it. A global variable is a data
value that exists permanently after the terminal session ends. Variables differ from
literals and constants because their values can be changed by commands.
The following sections describe variables within MSM. Variable names are
case-sensitive. Variable names that differ only in uppercase or lowercase characters
are distinct.

Local Variables
Local variables (locals) are temporary and exist only for the duration of a terminal
session. Locals are created by referencing them in a SET or READ command or
within parameter passing. They can be removed by referencing them in a KILL or
NEW command or a QUIT command when exiting a routine invoked with parameter
passing. When a local is created, it is assigned to the user who created it and is
known only by that user. Two users may have local variables that have the same
name but have different values.
A local variable name must begin with a percent sign (%) or an alpha character. It
can be followed by any combination of alpha-numeric characters. If the name
contains more than eight characters, MSM ignores all characters after the eighth
character. The following are examples of valid local variable names.
ABC
%123
X21

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

Global Variables
Global variables (globals) are permanent and continue to exist after a terminal
session ends. Globals are created by referencing them in a SET or READ command,
and they are removed by referencing them in a KILL command. When a global is
created, it is assigned a permanent location in the MSM database and can be known
to users other than the user who created it. Thus, two users can both reference one
global variable and obtain the same value.
A global variable name must begin with a circumflex (^) followed by a percent sign
(%) or an alpha character, followed, in turn, by any combination of alphanumeric
characters. If the name contains more than eight characters, MSM ignores all
characters after the eighth character. A global variable name can be distinguished
from a local variable name by the circumflex (^) that precedes it. The following are
examples of valid global variable names.
^CUSTFILE
^%999
^CTRL12

12 • Language Syntax MSM Language Reference Manual

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

Arrays and Subscripts

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

In the first example, customers are ordered into an array in which the first customer is
number 1, the second is number 2, and so on. Arrays can be more complex,
containing additional levels of information.
The following example illustrates a more complex array in which invoice and address
information is added to the array shown in the first example.
^CUSTOMER(1,1)
^CUSTOMER(1,3,2)
^CUSTOMER(2,99)
^CUSTOMER(2,”INVOICE”,18761)
.
.
.
^CUSTOMER(998,”ADDRESS”)
^CUSTOMER(999,”.01”)
^CUSTOMER(999,”.01”,”.997”,”TEST RESULT”)

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

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

MSM Language Reference Manual Language Syntax • 13

 Naked References
For each job, the system maintains a naked indicator, which is a value that is used to
evaluate a naked reference. The value of this indicator is either null or a subscripted
global variable name. The naked indicator is changed if one of the following
conditions is met:
• At the start of a job, the naked indicator is set to null.
• Execution of a reference to an unsubscripted global variable sets the indicator to
a null value.
• Except as above, a global reference or a naked reference to a global sets the
naked indicator to the immediate ascendant of the referenced global. That is, the
global reference less the right-most subscript of the reference is set into the
naked indicator.
Generally, a naked reference can be used wherever a global reference is allowed. In
any situation in which this is not true, MSM provides information about the
restrictions.
The syntax of a naked reference is as follows:
^(Subscript{, ... ,Subscript})

Execution of a naked reference when the naked indicator is null results in an error
condition (<NAKED>). When the naked indicator is defined, the subscripts specified
in the naked reference are appended to the right of the right-most subscript of the
naked indicator to form the full reference.
Because the right side of a SET statement is evaluated first, care should be exercised
to prevent unwanted results when using naked references. For example:
I ‘$D(^ABC(1)) S ^(1)=^XYZ(1,2) ;does not set ^ABC(1)
I ‘$D(^ABC(1)) S ^XYZ(1,1)=^XYZ(1,2) ;is equivalent to the above

Collating Sequence
Subscripted global variables can include numeric valued subscripts, string-valued
subscripts, or a combination of both. For this reason, MSM allows you to specify the
order (either numeric or string sequence) in which subscripts are to be collated.
For globals in which a collating sequence string type was specified, all subscripts
(numeric and non-numeric) are treated as character strings and stored in ASCII
collating sequence.
In the following example, global variable X has subscripts -10, -2, -1, 1, 0, 1.1, 2, 3,
10, 20, 30, and ABC defined. In string collating sequence, the subscripts of X are
stored in the following order:
^X(-1)
^X(-10)
^X(-2)
^X(0)
^X(1)
^X(1.1)
^X(10)
^X(2)
^X(20)
^X(3)
^X(30)
^X(“ABC”)

14 • Language Syntax MSM Language Reference Manual

 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.

MSM Language Reference Manual Language Syntax • 15

 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.

16 • Language Syntax MSM Language Reference Manual

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; that is,
two consecutive quotes used to represent a single embedded quote).
While the current maximum member length is 31 characters (MSM ignores any
characters after the thirty-first), it is good practice to limit names to 31 characters to
allow future expansion to longer names as object technology evolves.

MSM Language Reference Manual Language Syntax • 17

 An object exists as long as something references it. After the last reference to an
object is deleted (discarded), the object is no longer accessible and conceptually no
longer exists. The reference can be transitory as part of an expression evaluation, or
more permanent when it is assigned to a local variable.
M variables conceptually are considered objects with built-in methods and properties
defined by the M language. The “kill” method destroys objects, the “new” method
hides them, a “value” property provides the data value, and so on.
Refer to the MSM User’s Guide for additional information on objects.

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.

18 • Language Syntax MSM Language Reference Manual

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 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 • 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 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 • Expression Elements MSM Language Reference Manual

MSM Operators

Overview
The M language operators are used to specify an action that is to be performed. The
following table summarizes MSM operators and their characteristics.
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 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
Writes the value 4:
WRITE 2+2

Writes the value 3068.113:

W 986.513+2081.6

Writes the value 579 after evaluating the strings as numbers:

W "123XYZ"+"456ABC"

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

24 • 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
Truth-Valued Expressions

Examples
Writes the value 1 because both operands are non-zero:
WRITE 5&4

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

Sets X to the value 1 because operand1 evaluates to 123 and operand2 evaluates to
456:
SET X="123XYZ"&"456ABC"

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

S Y="123XYZ"&"ABC"

MSM Language Reference Manual MSM Operators • 25

CONCATENATE ( _ )
Appends the operand2 string to the end of the operand1 string.

Syntax
operand1_operand2

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

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

Associated Topics
String Expressions

Examples
Writes the string "BASKETBALL" to the current device:
WRITE "BASKET"_"BALL"

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

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

Writes the string "HELLO JIM, WELCOME TO MSM." to the current device:
SET X="JIM",Y="MSM" W "HELLO "_X_", WELCOME TO "_Y_"."

26 • MSM Operators MSM Language Reference Manual

DIVISION (/)
Performs an arithmetic division of operand1 by operand2.

Syntax
operand1/operand2

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

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

Associated Topics
Numeric Expressions

Examples
Writes the value 2 to the current device:
WRITE 4/2

Writes the value 39.317197452229299 to the current device:

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

Writes the value 2 because the first string evaluates to 246 and the second string
evaluates to 123:
W "246XYZ"/"123ABC"

MSM Language Reference Manual MSM Operators • 27

EQUAL TO (=)
Performs a Boolean EQUAL TO comparison of two string operands.

Syntax
operand1=operand2

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

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

Associated Topics
String Expressions

Examples
Writes the value 0 because operand2 has a trailing blank:
WRITE "ABC"="ABC "

Writes the value 0 because operand2 has leading zeroes:

W "123"="00123"

Writes the value 1 because the values are equivalent numeric literals:
W 123=00123

Writes the value 1 because numeric conversion is forced by the PLUS operator:
W +"123"=+"00123"

28 • MSM Operators MSM Language Reference Manual

EXPONENTIATION (**)
Raises operand1 to the power specified by operand2.

Syntax
operand1**operand2

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

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

Associated Topics
Numeric Expressions

Examples
Writes the value 64 to the current device:
WRITE 8**2

Writes the value 3692736.4489861373 to the current device:

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

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

W "16ABC"**"4XYZ"

MSM Language Reference Manual MSM Operators • 29

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

Examples
Writes the value 0 because operand1 is not greater than operand2:
WRITE "123">"456"

Writes the number 1 (true) because operand1 evaluated as a number is greater than
operand2 evaluated as a number:
W "123">"001"

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

W "DEF">"ABC"

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

30 • MSM Operators MSM Language Reference Manual

HEXADECIMAL (#)
Interprets a hexadecimal number as a numeric value.

Syntax
#operand

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

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

Associated Topics
Constant Values

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

Sets the local variable X to a value of 7933:

SET X=#1efd

Writes 60 to the current device. First, the two hexadecimal operands are evaluated,
and then the integer division is performed:
S Y=#3BFC\#FF W Y

MSM Language Reference Manual MSM Operators • 31

INDIRECTION (@)
Evaluates the argument of the operator and substitutes it into the command line.

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

Definition
The INDIRECTION operator is used to dynamically alter the M code within a
command. When indirection is encountered in a command, the indirection expression
is evaluated and the derived value is substituted for the indirection before the
command is executed. There are four types of indirection: name indirection,
argument indirection, pattern indirection, and subscript indirection. The indirection
types are described in the following paragraphs.
Name Indirection
When an indirection expression atom is evaluated, it must yield a valid MSM name.
The name derived from the expression atom may be a routine name, variable name,
or line label. Names can begin with a percent sign or an alpha character and can be
followed by any number of alphanumeric characters. For a variable name, subscripts
also can be specified as part of the indirection. This type of indirection can be used
with commands such as DO, GOTO, and SET.
Argument Indirection
When an indirection expression is evaluated, it must yield one or more complete
command arguments. The form of the derived argument or arguments is specific to
the command being used with indirection. The command detects any errors in the
argument structure. This type of indirection can be used on all commands unless
explicit restrictions are noted on the command.
Pattern Indirection
When the indirection expression is evaluated, it must yield a valid pattern for the
PATTERN MATCH operator. Refer to "Pattern Match" in this manual for
information on valid patterns. This type of indirection can be used only with the
PATTERN MATCH operator.
Subscript Indirection
When an indirection expression is evaluated, it must yield a valid subscripted local or
global variable name). This type of indirection is in the following form:
@Expression Atom@(Subscript{,...Subscript})
An expression atom must yield a valid variable name (with or without subscripts).
(Subscript{,...Subscript}) is a list of subscripts enclosed in parentheses and separated
by commas. The two pieces of the indirection are combined to form a complete
subscripted variable name by appending the explicit subscripts to the variable name
and subscripts obtained from the expression atom.

32 • MSM Operators MSM Language Reference Manual

 Associated Topics
Expression Atom

Examples
This form of name indirection sets variable Y to a value of 2:
SET X="Y",@X=2

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

This form of pattern indirection writes 1 to the current device because the string
conforms to the indicated pattern:
S X="3N1""-""2N1""-""4N" W "123-45-6789"?@X

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

The next line sets up the following three examples:

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

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

S @(X_"="_Z)

This command is equivalent to the previous command:

S ARG=X_"="_Z S @ARG

This command is a common misuse of indirection. It incurs an error because Z does

not evaluate to a name. This is an attempt to use name indirection with an expression:
S @X=@Z

MSM Language Reference Manual MSM Operators • 33

INTEGER DIVISION (\)
Performs an integer division of operand1 by operand2.

Syntax
operand1\operand2

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

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

Associated Topics
Numeric Expressions

Examples
Writes the value 2 to the current device:
WRITE 4\2

Writes the value 39 to the current device. The fractional part of the result
(.317197452229299) is discarded:
SET A=123.456,B=3.14 W A\B

Writes the value 3 because the first string evaluates to 456 and the second string
evaluates to 123. The remainder value is discarded:
W "456XYZ"\"123ABC"

34 • MSM Operators MSM Language Reference Manual

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
Writes the value 1 because operand1 is less than operand2:
WRITE "123"<"456"

Writes the number 0 ( false) because operand1 evaluated as a number is greater than
operand2 evaluated as a number:
W "123"<"001"

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

W "DEF"<"ABC"

Writes the value 1 because the numeric value of operand1 (123) is less than the
numeric value of operand2 (456):
W "123XYZ"<"456ABC"

MSM Language Reference Manual MSM Operators • 35

MINUS (-)
Inverts the numeric sign of the operand.

Syntax
-operand

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

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

Associated Topics
Expression Evaluation
Numeric Expressions

Examples
Writes the value -3 to the current device:
WRITE -3

Writes the value 579 to the current device because the MINUS operator inverts the
subtraction to addition:
W 123--456

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

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

36 • MSM Operators MSM Language Reference Manual

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

MSM Language Reference Manual MSM Operators • 37

 Examples
Writes the value 0 to the current device:
WRITE 4#2

Writes the value .996 (the remainder) to the current device. The integer portion of 39
is discarded:
SET A=123.456,B=3.14 W A#B

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

Writes the value -1 to the current device:

W 5#(-3)

Writes the value 1 to the current device:

W -5#3

Writes the value -2 to the current device:

W -5#(-3)

Writes the value 1 to the current device:

W 4#1.5

38 • MSM Operators MSM Language Reference Manual

MULTIPLICATION (*)
Performs a multiplication of operand1 by operand2.

Syntax
operand1*operand2

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

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

Associated Topics
Numeric Expressions

Examples
Writes the value 8 to the current device:
WRITE 4*2

Writes the value 387.65184 to the current device:

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

Writes the value 30258 because the first string evaluates to 246 and the second string
evaluates to 123:
W "246XYZ"*"123ABC"

MSM Language Reference Manual MSM Operators • 39

NOT (')
Inverts the value of an M operator or a Boolean truth value.

Syntax
'operand

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

Considerations
The value of a relational operation can be reversed using either of the following
methods:
operand1 'Relation operand2 '(operand1 Relation operand2)

Associated Topics
Truth-Valued Expressions

Examples
Writes the value 0 to the current device:
WRITE '1

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

Writes the value 0 to the current device because 123 is less than 456 and the inverse
of that is false:
W '(123<456)

40 • MSM Operators MSM Language Reference Manual

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

Syntax
operand1!operand2

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

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

Associated Topics
Truth-Valued Expressions

Examples
Writes the value 1 because both operands are non-zero:
WRITE 5!4

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

W 1!0

Sets X to the value 1 because operand1 evaluates to 123 and operand2 evaluates to
456:
SET X="123XYZ"!"456ABC"

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

SET Y="XYZ"!"ABC"

MSM Language Reference Manual MSM Operators • 41

PATTERN MATCH (?)
Tests whether a value conforms to a specified pattern.

Syntax
operand?pattern

Definition
The PATTERN MATCH operator tests to see if the string specified by the operand is
in the form indicated by the pattern that appears after the operator. If it is in the
correct form, the PATTERN MATCH operator returns a value of 1 (true). Otherwise,
it returns a value of 0 (false).
Combinations of the pattern characters listed in the following table can be used to
specify the pattern. Refer to “ASCII Collating Sequence” in this manual for
additional information on the ASCII character set.
&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 SPACE character
U or u The 26 uppercase alphabetic characters
( Indicates the start of a logical OR pattern group
) Indicates the end of a logical OR pattern group
, Used to separate individual patterns in a logical OR pattern group

A pattern is composed of one or more pattern elements. Multiple pattern elements

can be specified by placing them adjacent to each other. Pattern elements are in the
following general form.
Min.Max Code
Where:
Code Either of the allowable pattern match codes specified in the previous
section or a string literal (a string of characters enclosed in quotes).
Min The minimum number of occurrences required to successfully match
the pattern element (the minimum repetition count). It must be
specified as an integer value.
Max The maximum number of occurrences that is allowed to successfully
match the pattern element (the maximum repetition count). It must be
specified as an integer value.

42 • MSM Operators MSM Language Reference Manual

 The following valid combinations are allowed for the Min and Max elements.
Min This is equivalent to specifying a pattern element of Min.Min.
Min. The implied value of Max defaults to the largest possible number of
occurrences.
. This is equivalent to specifying a pattern element of 0. .
.Max This is equivalent to specifying a pattern element of 0.Max.
Min.Max When both a Min value and a Max value are specified, the value of
Max must not be less than the value of Min.
For example, a 3P pattern element is the same as a 3.3P pattern element. This same
pattern element also can be expressed as 2P1P, 1P2P, 2.2P1P, and so on.
As another example, a 1.3L pattern element is identical to 1L, 2L, or 3L. In other
words, the pattern matches from one to three lowercase alphabetic characters.
A notation is provided to allow a logical OR capability in the PATTERN MATCH
operator. Two or more patterns enclosed in parentheses and separated by commas
indicate that a match should be successful if either pattern matches. Indirection also
can be used to specify pattern arguments.

Considerations
Pattern match codes can be specified in uppercase, lowercase, or a combination of
uppercase and lowercase characters. If the PATTERN MATCH operator is preceded
by the NOT ( ' ) operator, the logic of the operation is inverted.
Pattern match codes A, C, N, L, P, and U are defined only for the standard 128
ASCII characters. The pattern match code E now is extended to match all 256
characters (128 ASCII and 128 Extended ASCII).

Associated Topics
ASCII Character Set
INDIRECTION Operator
Truth-Valued Expressions

Examples
This pattern match writes 1 to the current device because the specified string
conforms to the indicated pattern:
SET X="3N1""-""2N1""-""4N" WRITE "123-45-6789"?@X

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

This example shows how a logical OR condition can be specified within a

PATTERN MATCH operation:
IF X?2N1(3P2A,2P3A).E

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

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

MSM Language Reference Manual MSM Operators • 43

PLUS (+)
Forces numeric conversion of the operand.

Syntax
+operand

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

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

Associated Topics
Numeric Expressions

Examples
Writes the value 123 to the current device:
WRITE +"123XYZ"

Writes the value 1 to the current device because the PLUS operator forces numeric
conversion and the values are then equal:
W 123=+"123ABC"

Writes the value -123 to the current device because the string evaluates to the
negative number -123:
W +"-123XYZ"

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

44 • MSM Operators MSM Language Reference Manual

STRING CONTAINS ([ )
Tests whether or not one string is contained in another string.

Syntax
operand1[operand2

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

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

Associated Topics
String Expressions
Truth-Valued Expressions

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

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

"123456" :
W "123456"["246"

Writes 1 to the current device because the null string is contained in all strings:
W "TEST STRING"[""

Writes 1 to the current device because the zip code specified by operand2 is
contained in operand1:
SET X="ROCKVILLE, MD. 20850",Y="20850" W X[Y

MSM Language Reference Manual MSM Operators • 45

STRING FOLLOWS (])
Tests whether or not one string follows another string in the ASCII collating
sequence.

Syntax
operand1]operand2

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

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

Associated Topics
String Expressions
Truth-Valued Expressions

Examples
Writes 1 to the current device because "S" follows "J" in the ASCII collating
sequence:
WRITE "SMITH"]"JONES"

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

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

Writes 0 to the current device because the two strings are identical:
SET X="GOLF CLUBS",Y="GOLF CLUBS" W X]Y

Writes 0 to the current device. Although 10 is greater than 2, the STRING

FOLLOWS operator treats the value of all expressions as strings, and in a strict
character-by-character-by-character comparison, 2 follows 1 and the 0 is ignored:
W 10]2

46 • MSM Operators MSM Language Reference Manual

STRING SORTS AFTER (]])
Tests if one string follows another string in subscript ordering sequence.

Syntax
operand1]]operand2

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

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

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

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

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

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

sequence:
W 45]]23

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

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

MSM Language Reference Manual MSM Operators • 47

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

Syntax
operand1-operand2

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

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

Associated Topics
Numeric Expressions

Examples
Writes the value 2 to the current device:
WRITE 4-2

Writes the value 514:3893 to the current device.

W 617.343-102.9537

Writes the value 333 after evaluating the strings as numbers:

W "456ABC"-"123XYZ"

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

48 • MSM Operators MSM Language Reference Manual

MSM Commands

Overview
This chapter describes the ANSI Standard M commands and other commands that are
provided in MSM.
The M language contains commands that programmers can use to create programs or
routines, as they are referred to in MSM. A command is the method by which the
compiler is directed to perform a specific action. Each command performs a specific
action that is further defined by the operands or arguments associated with the
command.
MSM provides all of the ANSI Standard commands, as well as an extended set of
commands that are specific to MSM. The ANSI Standard commands begin with the
letters A through Y, and the MSM-specific commands begin with the letter Z. For
each command, a single, defined abbreviation for the command can be used in place
of the entire name. Each abbreviation consists of one or more letters of the name and
always begins with the first letter of the name. In the definition of each command, the
abbreviation is shown in bold, and the remainder of the name is shown within braces.
Command names can be specified in uppercase, lowercase, or a combination of
uppercase and lowercase characters.
The following examples illustrate valid abbreviations.
CLOSE
close
C
c
The following sections contain information about the commands provided in MSM.
For each command, the following information is provided: syntax, a description of
the command's function, special considerations, associated topics, and examples. For
additional information on writing M programs, refer to the MSM User's Guide.

MSM Language Reference Manual 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, you can enter the interactive debugger and
have full access to the M language for debugging purposes. When MSM enters direct
mode as a result of a BREAK command, a message is displayed indicating that a
break occurred, and the system prompts for input with the name of the program
displayed between < and > signs.
At this point, use the ZGO command to resume execution of the suspended routine;
enter QUIT to exit the debugging system and return to the current executing routine;
or enter any M command. To obtain a list of commands that can be used within the
interactive debugger, enter a question mark (?).
The BREAK command with an argument is used to control recognition of the break
key (CTRL+C). The break key is used to interrupt execution of a routine. If the value
of the expression is true (evaluates to 1), the break key is recognized. Otherwise, the
break key is treated like any other character. When a BREAK 0 command is issued,
15 (interrupt received) is turned off in $ZA for the current device, if it is a terminal.
Refer to “Using Peripheral Devices” in the MSM User's Guide for additional
information on this bit.
If the BREAK argument has a value of -2 or 2, it is used to control the mode of error
processing that is performed. A value of 2 indicates that the DO/XECUTE stack is to
be discarded before the error is processed. A value of -2 indicates that the
DO/XECUTE stack is preserved and that error processing is performed at the current
execution level. When the system is initialized, a default of -2 is in effect for the
BREAK command. The default setting can be configured through the MODE flags in
the SYSGEN utility.

50 • 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=^A(3) I X=0 B K ^A A BREAK is inserted before the global is deleted so that the
programmer may examine the job's status.
B 1 The BREAK character CTRL+C is recognized.
B 0 The BREAK character CTRL+C is not recognized.
B @X Indirection may be used in the BREAK command.

MSM Language Reference Manual MSM Commands • 51

CLOSE
Releases a device that is owned by a job.

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

Definition
Postcond Any post-conditional expression.
Device An integer expression that indicates which device is to be closed.
Parm One or more expressions separated by colons and enclosed in
parentheses that have meaning specific to the device being closed.
The CLOSE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the CLOSE command.
Use the CLOSE command to release ownership of a device. To close multiple
devices, specify a list of device number that are separated by commas on the CLOSE
command. If the job issuing the command does not own the specified device, no
action takes place. Use the OPEN command to achieve ownership of a device.
The device specified can be any valid MSM device, and its number can be specified
using indirection. When the device is closed, MSM makes the principal device the
current device. (The principal device is the device that was used to log on to MSM.)
However, the system does not attempt to OPEN the principal device. When a HALT
command is encountered, all devices owned by the job are closed and returned to the
pool of available devices.
In MSM, Device number 0 indicates the principal device. When a Device number of
0 is specified on a CLOSE command, it is ignored (no action takes place).

Associated Topics
Using Peripheral Devices, MSM User's Guide

Examples

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

52 • MSM Commands MSM Language Reference Manual

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

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

Definition
Postcond Any post-conditional expression.
EntryRef Any valid entry reference.
The DO command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the DO command. For post-conditional expressions on the argument
of the DO command, the argument is skipped if the expression is false.
The DO command is used to call a subroutine within the current routine or a
subroutine in another routine. If the EntryRef does not contain a routine name,
control passes to the label (or label + offset) in the routine containing the DO
command. When the EntryRef contains a routine name, control passes to the label (or
label + offset) in the named routine.
The EntryRef also can be specified as an extended reference. In an extended
reference, the routine name can be preceded with the UCI name, the volume group
name, or both. The format for the extended reference is the same format used for
extended global references. Refer to “Language Syntax” in this manual for additional
information on the format of the extended reference.
If no label (or label + offset) is specified with the routine name, control passes to the
first line of the named routine. The called subroutine terminates when a QUIT
command, which is not within the scope of a FOR command, is encountered or the
physical end of the routine is encountered. When the subroutine terminates, control
passes to the next argument on the DO command or the next command following the
DO command.
In the form without arguments, the DO command invokes a block structured
subroutine at the next higher execution level. The subroutine being invoked must
immediately follow the routine line that contains the argumentless DO command.
When a QUIT command or the end of the block structured subroutine is reached,
execution continues with the next command following the DO. If no commands
follow the DO command, execution continues with the next routine line following the
DO command that is at the same execution level as the DO command.
The value of the $TEST variable is never changed as a result of invoking a block
structured subroutine. This differs from a subroutine that is invoked by a DO with an
argument, which does not preserve the value of $TEST.

MSM Language Reference Manual MSM Commands • 53

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

Examples

Command Explanation
DO X WRITE Y The subroutine beginning at the line labeled X is
executed, and then the variable Y is written.
D X,Y This is equivalent to DO X DO Y.
D ^PGM W Y Routine PGM is invoked, and then Y is written.
D A,^PGM,^ROU Multiple routine names and labels may be listed as
arguments.
D INT^PROG Routine PROG is invoked beginning at the line labeled
INT.
D:X=1 A^PGM,B,^TEST The list of subroutines is invoked only if X=1.
D ^CEN:A=0,B Routine CEN is invoked if A=0, and then subroutine B is
invoked, regardless of the value of A.
D ^[TST,RMT]LABRSLT Routine LABRST, from the TST UCI in the RMT
volume group, is invoked.
D @X 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"

54 • MSM Commands MSM Language Reference Manual

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

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

Definition
Postcond Any post-conditional expression.
EntryRef Any valid entry reference.
ActualList A list of arguments to pass to the called routine.
This form of the DO command allows you to call a routine and pass it one or more
parameters using MSM’s parameter-passing mechanism. Arguments in the ActualList
can be passed to the routine using either call-by-value or call-by-reference parameter
passing.
Normally, all arguments in the ActualList are passed to the routine using
call-by-value. However, if the local variable name is preceded by a period,
call-by-reference is used for the argument. Refer to “MSM Functions” in this manual
for a description of how parameter passing is implemented in MSM.
The same general considerations and restrictions that exist for extrinsic functions
apply to the DO command with parameter passing. The first line of the routine or
subroutine specified by the EntryRef must contain a label reference with a formal list
(FormalList). If it does not, then a <DPARM> error occurs.
If the specified ActualList is shorter than the FormalList, any variables in the
FormalList that do not have a corresponding entry in the ActualList are undefined.
The converse of this situation is not allowed. If the FormalList is shorter than the
ActualList, a <DPARM> error occurs.

Associated Topics
DO Command
FOR Command
QUIT Command
Block Structured Subroutines
Extrinsic Functions

MSM Language Reference Manual MSM Commands • 55

 Examples

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

56 • MSM Commands MSM Language Reference Manual

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

MSM Language Reference Manual MSM Commands • 57

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.

58 • MSM Commands MSM Language Reference Manual

 Local=Expression
In this form, the local variable is assigned the value of the expression and the scope
of the FOR command is executed once. The next ForParm, if one exists, is then
processed. If none exists, then execution moves to the next line of M code.
Local=Begin:Incr
In this form, the following steps are performed.
1. Assign the value of Begin to the local variable.
2. Execute the Scope of the FOR command once.
3. Add the value of Incr to the value of the local variable.
4. Go to step 2.
This procedure specifies an endless loop. Termination of the loop must occur by
execution of a QUIT or GOTO within the scope of the FOR command. Additional
ForParms to the right of this type of ForParm are never performed.
Local=Begin:Incr:End
In this form, the following steps are performed if the value of Incr is 0 or greater than
0.
1. Assign the value of Begin to the local variable.
2. The system determines whether the value of the local variable is greater than the
value of End. If it is, execution of the current ForParm is complete. The next
ForParm, if one exists, is then processed. If none exists, execution moves to the
next line of M code.
3. Execute the scope of the FOR command once.
4. The system determines whether the value of the local variable is greater than the
value of End. If it is, execution of the current ForParm is complete. The next
ForParm, if one exists, is then processed. If none exists, execution moves to the
next line of M code.
5. Add the value of Incr to the value of the local variable.
6. Go to step 2.
If Incr is less than 0, the following steps are performed.
1. Assign the value of Begin to the local variable.
2. The system determines whether the value of the local variable is less than the
value of End. If it is, execution of the current ForParm is complete. The next
ForParm, if one exists, is then processed. If none exists, execution moves to the
next line of M code.
3. Execute the scope of the FOR command once.
4. The system determines whether the value of the local variable is less than the
value of End. If it is, execution of the current ForParm is complete. The next
ForParm, if one exists, is then processed. If none exists, execution moves to the
next line of M code.
5. Add the value of Incr to the value of the local variable.
6. Go to step 2.

MSM Language Reference Manual MSM Commands • 59

 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

60 • MSM Commands MSM Language Reference Manual

 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.

MSM Language Reference Manual MSM Commands • 61

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

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

Definition
Postcond Any post-conditional expression.
EntryRef Any valid entry reference.
The GOTO command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the GOTO command. For Postcond expressions on the arguments of
the GOTO command, the argument is skipped if the expression is false. In contrast to
the DO command, when arguments are listed, no more than one argument actually
transfers control.
The GOTO command is used to pass control to a line of code in the current routine
or to a line of code in a different routine. If the EntryRef does not contain a routine
name, control passes to the label (or label + offset) in the routine that contains the
GOTO command. When the EntryRef contains a routine name, control passes to the
label (or label + offset) in the named routine. If no label (or label + offset) is
specified with the routine name, control passes to the first line of the named routine.
The GOTO command can be used in a block structured subroutine, but only under
the following condition: there can be no routine lines at a lower execution level (with
fewer dots at the beginning of the line) between the GOTO command and the label
which is the GOTO argument. In other words, GOTO is valid only within its own
block structured subroutine. If this rule is violated, an error is not generated, but the
routine executes in an unpredictable manner.

Associated Topics
Entry Reference
Execution Level
Block Structure Subroutine

62 • MSM Commands MSM Language Reference Manual

 Examples

Command Explanation
GOTO XYZ Execution continues at the start of the line labeled
XYZ in the current routine.
GOTO ^PGM Execution switches from the routine containing
the GOTO to the first line of the routine PGM.
G CC+2^ABC Execution switches to the second line after the
line labeled CC in routine ABC.
G 13^GRAY:A=1 If and only if A=1, execution switches to the line
labeled 13 in routine GRAY.
G:A=1 13^GRAY This is equivalent to the previous example.
G ^ADM:A=0,X^CEN If A=0, then execution switches to the first line of
routine ADM; otherwise, execution switches to
the line labeled X in routine CEN.
G:A=1 AAA:B=2,13:D=4 This line is equivalent to G AAA:A=1&(B=2) G
13:A=1&(D=4).
G @X There are many opportunities to use indirection
G ^@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.
G @A^@B
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.

MSM Language Reference Manual MSM Commands • 63

HALT
Terminates the user's session.

Syntax
H{ALT}{:Postcond}

Definition
Postcond Any post-conditional expression.
The HALT command is executed if the Postcond expression is true, or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the HALT command.
The HALT command is used to terminate the job that issues the command. When the
job halts, all open devices are closed, all variables that are locked as a result of
LOCK or ZALLOCATE commands are unlocked, and the partition associated with
the job is released.

Examples

Command Explanation
HALT This is an unconditional HALT command.

H:A=1 WRITE "TEST" If A=1, the process HALTs. Otherwise, execution continues and
TEST is written to the current device. Note that there must be at
least two spaces after the HALT command in this example.

H:A=@B Indirection may be used in the post-conditional expression.

64 • MSM Commands MSM Language Reference Manual

HANG
Suspends program execution for a specified period of time.

Syntax
H{ANG}{:Postcond}SPExpression

Definition
Postcond Any post-conditional expression.
Expression A numeric expression.
The HANG command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the HANG command.
The HANG command is used to suspend execution of a job for a specified period of
time. The time interval is specified in whole seconds, fractions of a second, or a
combination of whole seconds and fractions of a second. After the time interval
expires, execution resumes with the next command following the HANG command.
If the time interval is 0 or less than 0, the HANG command has no effect.

Examples

Command Explanation
IF $PIECE($HOROLOG,",",2)<X HANG 3 If the number of seconds after midnight
is less than X, then execution hangs for
three seconds.

H:I=3 10 WRITE ! If I=3, a 10-second HANG is executed

before the WRITE.

H @X 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.

MSM Language Reference Manual MSM Commands • 65

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

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

Definition
TruthExp An expression that evaluates to either true or false.
In the argumentless form, the IF command executes the commands that follow it on
the same line, only if the value of the $TEST special variable is 1 (true). If the value
is 0 (false), all remaining commands on the line are ignored, and control passes to the
next line in the routine. The $TEST special variable is set by the IF command and by
a command that is used with a timeout (READ, LOCK, ZALLOCATE, OPEN, JOB).
Execution of an argumentless IF command does not affect the value of $TEST.
In the form of the IF command with an argument, the additional commands on the
line are executed only if the value of the TruthExp is 1. If the value is 0, all remaining
commands on the line are ignored and control is passed to the next line in the routine.
When this form of the IF command is used, the $TEST special variable is assigned
the value of the truth-valued expression.
When multiple arguments, separated by commas, are specified on the IF command,
they are evaluated in left-to-right order. If all of the arguments are true (truth value of
1), the remainder of the line is processed. If any of the arguments are false, the
remainder of the line is ignored.

Associated Topics
Truth-Valued Expressions

66 • MSM Commands MSM Language Reference Manual

 Examples

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

IF @X Indirection may be used in the IF command.

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

MSM Language Reference Manual MSM Commands • 67

JOB
Initiates execution of a new M process.

Syntax
J{OB}{:Postcond}SPJobParm{,...}
where JobParm is:
EntryRef{|UCI{,Vol{,Sys}}|}{:{({PartSiz}{:SymFlag})}{:TimeOut}}

Definition
Postcond Any post-conditional expression.
EntryRef Any valid entry reference.
UCI The name of the user class identifier (UCI) that contains the
program.
Vol The name of the volume grop that contains the UCI and program.
Sys The system or node name on which the program will be run.
PartSiz The partition size in 1-K blocks.
SymFlag A flag indicating whether or not the local symbol table of the
current job is to be copied to the new job.
TimeOut A timeout value.
The JOB command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the JOB command.
The JOB command is used to start a new M process (job), which is referred to as a
background job in MSM. When the JOB command is executed, MSM assigns a new
partition to the job if one is available. MSM then internally performs a DO command
with the specified EntryRef as its argument. The new process executes in parallel
with the process that contain the JOB command.
A user-class identifier (UCI), volume group (Vol), and system name (Sys) can be
appended to the EntryRef to indicate where the routine specified in the EntryRef is
stored. Alternatively, the UCI parameter can be an expression that evaluates to a
string containing the UCI, Vol, and Sys names separated by a comma. For backward
compatibility, the ANSI Standard vertical bars ( | ) can be used in place of the left
bracket ( [ ) and right bracket ( ] ) characters.
Although the Vol and Sys parameters are both optional, Sys can be used only if Vol
also is specified. The purpose of the Sys parameter is to resolve the ambiguity that
occurs when a remote volume group is mounted. If Sys is not specified in this case,
the job executes on the local system.

68 • MSM Commands MSM Language Reference Manual

 When the new process is started, it is assigned a unique job number and partition size
equal to the size specified through the SYSGEN program. You can override this
default value by including the PartSiz argument on the JOB command. The partition
size is specified in 1-K blocks. When the JOB command completes, the $ZB special
variable contains the job number of the job that was started. For networked systems,
an offset can be added to the job number to ensure unique numbers throughout the
network. If only PartSiz is specified in JobParm, parentheses are not required.
The SymFlag can be used to indicate whether the local symbol table of the job
issuing the JOB command should be copied into the partition of the new job. The
SymFlag is an expression that evaluates to a numeric value. A value of 1 indicates
that the symbol table should be copied. When the symbol table is copied, only those
variables that are visible (have not been hidden by the NEW command) are copied. A
value of 0 indicates that the symbol table should not be copied. If the SymFlag is not
specified, a value of 0 is assumed. SymFlag is ignored when the job is started on a
different system.
If no additional partitions are available in the system, then the process issuing the
JOB command is suspended until one becomes available. An indefinite suspension of
the process can be avoided by including the TimeOut parameter. When a timeout is
specified, execution is resumed after the specified interval, even if a partition is not
available. The $TEST special variable then can be interrogated to determine whether
a job was started. If the job was started successfully, the value of $TEST is 1 (true);
otherwise, it is 0 (false). If the timeout value is 0 or less then 0, no suspension occurs
and the value of the $TEST special variable is set to indicate the success or failure of
the JOB command. After a timeout, $ZB is 0, indicating that no job was started.

Associated Topics
JOB with Parameter Passing
Entry Reference
$ZB Special Variable

MSM Language Reference Manual MSM Commands • 69

 Examples

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

70 • MSM Commands MSM Language Reference Manual

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

Syntax
J{OB}{:Postcond}SPJobParm{,...}
where JobParm is:
EntryRef(ActualList){|UCI{,Vol{,Sys}}|}{:{({PartSiz} {:SymFlag})}{:TimeOut}}

Definition
Postcond Any post-conditional expression.
EntryRef Any valid entry reference.
ActualList A list of arguments to pass to the new job.
UCI The name of the user class identifier (UCI) that contains the program.
Vol The name of the volume group that contains the UCI and program.
Sys The system or node name on which the process is run.
PartSiz The partition size in 1-K blocks.
Sym Flag A flag that indicates whether or not the local symbol table of the
current job is to be copied to the new job.
TimeOut A timeout value.
This form of the JOB command allows you to pass one or more parameters to the
new job using the MSM parameter-passing facilities. All entries in the ActualList are
passed to the new job using call-by-value parameter passing. The M language does
not support call-by-reference parameter-passing for the Job command. If a period is
specified before a local variable name in the ActualList, a <DPARM> error occurs.
Refer to “MSM Functions” in this manual for additional information on parameter
passing.
The same general considerations and restrictions that exist for extrinsic functions also
apply to the JOB command with parameter passing. This means that the first line of
the routine or subroutine specified by the EntryRef must contain a label reference
with a Formal List (FormalList). If it does not, a <DPARM error occurs.
If the specified ActualList is shorter than the FormalList, any variables in the
FormalList that do not have a corresponding entry in the ActualList are undefined.
The converse is not allowed. If the FormalList is shorter than the ActualList, a
<DPARM> error occurs.

Associated Topics
Entry Reference
DO Command with Parameter Passing
JOB Command
Extrinsic Functions

MSM Language Reference Manual MSM Commands • 71

 Examples

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

72 • MSM Commands MSM Language Reference Manual

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

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

Definition
Postcond Any post-conditional expression.
Variable A local or global variable name.
LocalVar An unsubscripted local variable name.
The KILL command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the KILL command.
The KILL command is used to delete local variables, global variables, or a
combination of local and global variables.
There are three forms of the KILL command:
Argumentless form KILL ALL
Variable,... form Selective (inclusive) KILL
(LocalVar,...) form Non-selective (exclusive) KILL
In the KILL ALL (argumentless form), all local variables that have not been hidden
by the NEW command are deleted. After execution of this form, the local symbol
table is empty.
In the selective KILL form, only the local or global variables specifically named as
arguments of the KILL command are deleted. The local and global variable names
can include subscripts.
In the exclusive KILL form, all local variables are deleted except the named local
variables and their descendants. Global variable names and subscripted local variable
names may not be specified in an exclusive KILL.
When a variable is deleted, all of its descendants also are deleted. If the specified
variable does not exist, no action occurs. When arguments are listed, the selective
KILL form can be mixed with the exclusive KILL form.

Associated Topics
Variables
NEW Command

MSM Language Reference Manual MSM Commands • 73

 Examples

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

74 • MSM Commands MSM Language Reference Manual

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

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

Definition
Postcond Any post-conditional expression.
Variable A local or global variable name.
TimeOut A timeout value.
The LOCK command is executed if the Postcond expression is true or if it is not
supplied. If it is supplied and it is false, execution moves to the next command after
the LOCK command.
The LOCK command is used to lock both local and global variables. The MSM
system maintains a table of all locked variables, which is referred to as the LOCK
table. When a user attempts to lock a variable, the system searches the table to
determine if another user already locked the variable. If the variable is locked, the
new lock is not granted.
When a lock is requested for a local variable, the lock is known throughout the
system and no other system user can lock the variable. When the lock is for a global
variable, the lock is known only within the UCI, and only users in the same UCI are
prevented from locking the variable.
When a variable is unlocked, its name is removed from the LOCK table, thereby
allowing other users to lock the variable. LOCK is only a convention. Rather than
prevent users from accessing a locked variable, LOCK prevents them from locking
the same variable. MSM does not require the variable that is to be locked to actually
exist or have data. If all users follow the same conventions, simultaneous updates to
the same data can be prevented.
The LOCK command functions in either of the following ways:
• In the simple form, the user specifies one or more variables to lock, which
replace the entire list of previously locked variables. The LOCK command first
releases all existing locks that are owned by the job. Any jobs that were
suspended while waiting for a locked variable can be resumed. No new variables
are locked. The LOCK command then attempts to lock all of the variable names
in a left-to-right order. No variables are locked unless all of the variables in the
argument can be locked.
• In the other form, in which each variable name or the list of variables is preceded
by a plus sign (+) or minus sign (-), one or more variables are added to or
removed from the list of currently locked variables. This is known as an
incremental LOCK.

MSM Language Reference Manual MSM Commands • 75

 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

76 • MSM Commands MSM Language Reference Manual

 Examples

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

MSM Language Reference Manual MSM Commands • 77

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

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

Definition
Postcond Any post-conditional expression.
DestVar Either a local or global variable name, optionally with subscripts.
SourceVar Either a local or global variable name, optionally with subscripts.
The MERGE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the MERGE command.
The MERGE command copies a specified local or global variable (SourceVar) to a
specified local or global variable (DestVar). It also copies all of the descendants of
the specified SourceVar into corresponding descendants of the specified DestVar.
The copy operation can be defined as a series of rules.
For explanatory purposes, it is assumed that DestVar is represented as A(i1,i2, ... ,ix),
where x '< 0, and that SourceVar is represented as B(j1,j2, ... ,jy), where y '< 0. By
definition, if x or y is 0, the corresponding variable is unsubscripted. Similarly, if x or
y is greater than 0, the corresponding variable contains one or more subscripts. Given
these assumptions, the following rules determine the actual data that is copied by the
MERGE command.
If $DATA (B(j1,j2, ..., jy) has a value of 1 or 11, the value of SourceVar is given to
DestVar.
For every occurrence of z such that z > 0, and $DATA(B(j1,j2, ... ,jy+z) has a value of
1 or 11, the value of B(j1,j2, ... ,jy+z) is given to A(i1,i2, ... ,ix,jy+1,jy+2, ... ,jy+z)
The current value of the naked indicator is modified by the MERGE command. The
new value assigned to the naked indicator is the same as if
$DATA(SourceVar)#10=1 and the command SET DestVar=SourceVar were
executed (the naked indicator is determined by the value of DestVar).
It is erroneous for the DestVar to be a descendant of the SourceVar, or for the
SourceVar to be a descendant of the DestVar. If either occurs, MSM generates an
error.

Considerations
The duration of the MERGE command can be lengthy. If MSM is interrupted during
execution of the MERGE command (for example, if there is a system failure or the
break key is pressed), only part of the data may be merged.
If the SourceVar contains any OLE/2 automation object references then the object is
copied to the DestVar and not the default value of the object.

78 • MSM Commands MSM Language Reference Manual

 Associated Topics
SET Command
$DATA Function
$ORDER Function

Examples

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

MSM Language Reference Manual MSM Commands • 79

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

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

Definition
Postcond Any post-conditional expression.
Var Any unsubscripted local variable name or selected special
variables ($ETRAP, $ESTACK, $TEST, and $ZREFERENCE).
LocalVar An unsubscripted local variable name.
The NEW command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the NEW command.
The NEW command is used to make temporary copies of local variables. When a
temporary copy is created, the old variable, its value, and the values of all its
descendants are copied onto a stack. The original variable then is removed from the
local symbol table (KILLed). When a QUIT command is encountered on the same
execution level as the NEW command was executed, the stacked values are restored
to the local symbol table.
There are three forms of NEW:
Argumentless form NEW ALL
Var,... form Selective (inclusive) NEW
(LocalVar,...) form Non-selective (exclusive) NEW
In the NEW ALL (argumentless form), all local variables are stacked and a KILL
ALL (argumentless KILL) then is performed. After execution of this form, the local
symbol table is empty.
In the selective NEW form, only the local variables or selected special variables
specifically named as arguments of the NEW command are stacked. For local
variables, a selective KILL is performed using the same argument. Local variable
names may not include subscripts. If the name includes subscripts, an error occurs.
In the exclusive NEW form, all local variables are stacked except the named local
variables and their descendants. An exclusive KILL is performed using the same
argument. Subscripted local variable names cannot be specified in an exclusive
NEW.
An inclusive NEW on a selected special variable makes a copy of the special
variable. This copy is retrieved (unstacked) when the corresponding QUIT command
is encountered. In the case of $ESTACK, the new command also resets it to zero.

80 • MSM Commands MSM Language Reference Manual

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

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

Examples

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

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.

MSM Language Reference Manual MSM Commands • 81

OPEN
Obtains ownership of a device.

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

Definition
Postcond Any post-conditional expression.
Device An integer expression that indicates which device is to be
OPENed.
Parm One or more expressions separated by colons and enclosed in
parentheses that have meaning specific to the device being
opened.
TimeOut A timeout value.
The OPEN command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the OPEN command.
The OPEN command is used to acquire exclusive ownership of a device. For the
OPEN command to be successful, the device must not be owned by any other
partition. The device specified can be any valid MSM device number. The
parameters specified on the OPEN command are specific to the device being
OPENed. When a user logs on to MSM, the logon device is designated as the
principal device (its value is assigned to $PRINCIPAL). This device is OPENed by
the system and does not need to be OPENed by the user. All other devices must be
OPENed before they can be accessed with a USE command.
If the device is not available, then the process issuing the OPEN command is
suspended until it becomes available. An indefinite suspension of the process can be
avoided by including the TimeOut parameter. When a timeout is specified, execution
is resumed after the specified interval even if the device is not available. The $TEST
special variable then can be interrogated to determine whether a device was OPENed.
If the device was successfully OPENed, the value of $TEST is 1 (true); otherwise it
is 0 (false). If the timeout value is 0 or less then 0, no suspension occurs and the
value of the $TEST special variable is set to indicate the success or failure of the
OPEN command.

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

82 • MSM Commands MSM Language Reference Manual

 Examples

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

MSM Language Reference Manual MSM Commands • 83

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

Syntax
Q{UIT}{:Postcond}
Q{UIT}{:Postcond}SPExpression

Definition
Postcond Any post-conditional expression.
Expression Any expression used to return a value.
The QUIT command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the QUIT command.
The QUIT command is used to terminate execution of any of the following: a
subroutine that was invoked with a DO command, an XECUTE command, a FOR
command, or an extrinsic function. When a QUIT command is encountered that is
not on the same line as a FOR command, it causes an exit from the subroutine that
was initiated by a DO or XECUTE command or an extrinsic function call. An
XECUTE command can be thought of as a one-line subroutine. The QUIT returns to
the calling routine and continues execution with the next command that follows the
DO or XECUTE command or extrinsic function call that invoked the subroutine.
When the QUIT command is on the same line as a FOR command, it terminates the
innermost FOR command. If the line containing the QUIT has only one FOR,
execution of the QUIT terminates execution of the line. If the line has more than one
FOR, execution of the QUIT causes termination of the innermost FOR and causes
termination of the current repetition of the second-from-innermost FOR.
When a routine called as an extrinsic function terminates, the QUIT must include an
Expression as an operand. If it does not, an error occurs. If the Expression evaluates
to an object reference, the QUIT command returns the object reference rather than
the value associated with the default property. Extrinsic functions are permitted to
return object references, and the calling context decides whether to invoke the default
property. This differs from object references in most other contexts in which the
default property is invoked.
Upon termination, the system returns to the argument immediately following the one
that contains the extrinsic function reference. If the QUIT includes an expression and
the routine was not called as an extrinsic function, an error occurs.

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

84 • MSM Commands MSM Language Reference Manual

 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.

MSM Language Reference Manual MSM Commands • 85

READ
Reads information from the current device.

Syntax
R{EAD}{:Postcond}SPStringLit
R{EAD}{:Postcond}SPFormat
R{EAD}{:Postcond}SPVariable{#Length}{:TimeOut}
R{EAD}{:Postcond}SP*Variable{:TimeOut}

Definition
Postcond Any post-conditional expression.
StringLit A string literal.
Format A formatting character or mnemonic namespace value that
indicates the control characters to be sent to the device.
Variable A local or global variable name.
#Length An integer expression preceded by a # (pound sign) that
indicates the number of characters to read.
*Variable A local or global variable name preceded by an * (asterisk).
TimeOut A timeout value.
The READ command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the READ command.
The READ command is used to accept input characters from the current device.
Optionally, the READ command can send an output sequence to the device before
accepting input. The different types of argument forms can be listed on the READ
command to achieve the desired results. Each argument form is described below.
StringLit
The specified string literal is sent to the current device, and the value of the $X
special variable is adjusted accordingly. If the current device does not allow output,
an error occurs and the value of $X is not updated.
Format
The specified formatting characters or mnemonic namespace characters are sent to
the current device, and the values of $X and $Y are adjusted accordingly. Multiple
formatting characters can be specified in a single argument of the READ command.
If the current device does not allow output, an error occurs and the values of $X and
$Y are not updated.
Variable{#Length}{:TimeOut}
In this form, the system reads a string of characters from the current device and
assigns the string to the specified local or global variable. If the #Length field is
specified, the maximum length of the input string is the value specified by the Length
field. If the Length field is not specified, a length of 255 characters is assumed for
terminal devices. For non-terminal devices, no default value is assumed.

86 • MSM Commands MSM Language Reference Manual

 The READ operation terminates when a line terminator character is received (ESC
key, RETURN key, or a user-defined read terminator), when the maximum number of
characters have been read, or when a timeout occurs. When the READ operation
terminates, the value of $X is updated to reflect the characters that were read.
If a TimeOut value is not specified on the READ, the job issuing the command is
suspended until the READ command completes (a read terminator is received or the
maximum number of characters is received). When a timeout is specified, execution
resumes after the specified interval even if the READ command has not completed.
The $TEST special variable can then be interrogated to determine whether any
characters were received. If the READ terminated normally before the TimeOut
interval, the input string is assigned to the local or global variable, the value of $X is
updated, and the value of $TEST is 1 (true).
If the TimeOut occurs while the user is entering data, the received characters are
assigned to the local or global variable, the value of $X is updated, and the value of
$TEST is set to 0 (false). If no characters were received when the TimeOut occurred,
the local or global variable is set to null, the value of $X is not adjusted, and the
value of $TEST is 0 (false).
If the timeout value is 0 or less than 0, no suspension occurs and the value of the
$TEST special variable is set to indicate the success or failure of the READ
command. In this case, the READ can be satisfied only if there were characters in the
typeahead buffer.
*Variable{:TimeOut}
In this form, MSM accepts one character of input from the current device and
terminates the READ. The decimal equivalent of the received character is assigned to
the specified local or global variable. If a TimeOut value is not specified, MSM waits
until a character is received. The READ terminates when a single character is
received. MSM does not wait for a line terminator character.
If a TimeOut value is specified, MSM waits for the duration of the specified interval.
If the character is received before the TimeOut, the local or global variable is
assigned the decimal value of the character, $X is updated, and the value of $TEST is
true. If the character is not received, the local or global variable is assigned a value of
-1, $X is not updated, and the value of $TEST is false.

Considerations
The MSM system supports typeahead, a feature that allows the user to type
information into the system before the corresponding READ operation is performed.
Information that is received in this manner is stored in the typeahead buffer. The
typeahead buffer is discarded if the READ command includes a Format or StringLit
argument.
The $X special variable is updated not because input is received, but rather because
data is echoed back to the input device. The ECHO feature affects only terminal
devices and can be disabled via the USE command.

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

MSM Language Reference Manual MSM Commands • 87

 Examples

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

88 • MSM Commands MSM Language Reference Manual

SET
Assigns a value to a local or global variable.

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

Definition
Postcond Any post-conditional expression.
Variable A local or global variable name, or the $PIECE or
$EXTRACT function containing a local or global variable
name.
Expression Any expression.
The SET command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the SET command.
The SET command is used to assign the value of an expression to one or more local
variables. When multiple variables are to be assigned the same value, their names are
separated by commas and enclosed in parentheses. Execution of the SET command
occurs in the following order:
1. Any indirection or subscripts that appear in the argument are evaluated in a left-
to-right order.
2. The Expression is evaluated according to the specified rules.
3. Each Variable is evaluated one at a time in a left-to-right order ,and the value of
the Expression is assigned to it. When the value is assigned, any of the following
conditions can occur.
If a naked reference was used to specify the Variable to which the value is to be
assigned, the naked indicator is used to produce the full reference. In turn, the full
reference that is generated sets the naked indicator to a new value.
If the Variable includes subscripts and the specified node does not exist, the system
creates the node and the minimum number of ancestor nodes required to provide a
path to the new node. When the ancestor nodes are created, they are defined so that
they have descendants but no data value (when the $DATA function is applied to the
created ancestor node, its value is 10).

MSM Language Reference Manual MSM Commands • 89

 Considerations
The $PIECE and $EXTRACT functions can be used instead of the Variable name on
the left side of the equal sign on a SET command. When this form is used, the
appropriate piece or substring is assigned the value of the Expression. The string
specified in the $PIECE or $EXTRACT function can be extended if necessary to
satisfy the function. For $PIECE, the string is padded with empty pieces using the
specified delimiter. For $EXTRACT, the string is padded with blanks. Some special
variables in MSM can be assigned values using the SET command. In particular, the
values of $ECODE, $ETRAP, $X, $Y, $ZNAME, and $ZTRAP can be modified
with the SET command. SET $X and SET $Y do not move the cursor.
If the Expression evaluates to an object reference, the default property of that object
is invoked, and the returned value is used as the value of the Expression.

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

Examples

Command Explanation
SET ^X=Y The value of the unsubscripted variable Y is
assigned to the unsubscripted global variable
^X.
S ^A(1,2)=B(3,4) The value of the subscripted variable Y is
assigned to the subscripted global variable
^X.
S ^A(1)=X,B(4)=D,^C="TEST",Z=^D Multiple arguments of SET.
S ^(2)=^C(X,2)+1 Because the expression to the right of the
equal sign is evaluated before the variable
name to its left is determined, the naked
reference ^(2) denotes ^C(X,2). If the line had
been:
S ^C(X,2)=^(2)+1
the meaning of the naked reference would
depend on the state of the naked indicator
prior to execution of the SET.

90 • MSM Commands MSM Language Reference Manual

 Command Explanation
S (A,B,C)=123 This is a "multiple" set. All variables in the
parentheses are set to the same value.
S (A,B,C,D)=0,^A(3)=W,(^A(3,4), Multiple and single SETs may be mixed in
^B(5))=I one command.
S ^A(5)=10,B(^(3))=^C(4) When subscripts occur to the left of the equal
sign, they are evaluated before the right side
expression. Thus, this line is equivalent to:
S ^A(5)=10,B(^A(3))=^C(4)
S ^A(3)=10,^(^(3))=^C(4) This line is executed as follows:
a. ^A(3) is given the value 10.
b. The subscript ^(3), which is ^A(3), is
evaluated as 10.
c. ^C(4) is evaluated.
d. This value is given to ^(10), which is
^C(10).
This line is then the same as:
S ^A(3)=10,^C(^A(3))=^C(4)
The order is always:
a. First, evaluate left subscripts.
b. Then, evaluate right expression.
c. Then, evaluate left name.
S I=3,(I,I(4))=4 Even in a multiple set, the left-hand subscripts
are evaluated before the assignment is made;
however, each argument is completed before
the next is begun. Thus, this line is equivalent
to:
S I=3 S (I,I(4))=4
and I ends up with the value 4.
S:X=3 X=4.5 The SET command may include a post-
conditional expression. In this example, if X
has the value 3, then it is given the value 4.5.
S X=$S(X=3:4.5,1:X) The $SELECT function is valuable when
used in the right-hand expression of a SET
command. This line has the same effect as
example 10.
S X=X=3*1.5+X The expression to be evaluated can be quite
complex. In this example, the expression
X=3*1.5+X is evaluated, and the result is
given to the variable X.
S $PIECE(X,"^",3)=99 The third piece of the local variable X is
assigned a value of 99. It is valid for only one
$PIECE expression to the left of the equal
sign. For example:
S ($P(X,"^",3),$P(Y,"^",2))=Z is not allowed.
S $EXTRACT(X,7,20)=123 Positions 7 through 20 of the local variable X
are set to the string 123. If X was previously
longer than nine characters and shorter than
21 characters, its length will be nine after this
command.

MSM Language Reference Manual MSM Commands • 91

 Command Explanation
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 command.
S A=@B+C
S A=B+@(C_D)

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 While evaluating the right side of the equal
(jobnum).partsize*2 sign, MSM uses local variable system to point
to the object. Its apps method is invoked with
jobnum as a parameter. The resulting object
reference is used to invoke the partsize
property, which returns the partition size for
the job. That value is used to set the partsize
property of the object pointed to by method
apps(jobnum) of object system.
SET (A,B.,$P(C.D,"^",5),$X)= The extrinsic function $$VALUE is invoked
$$VALUE($H) 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.

92 • MSM Commands MSM Language Reference Manual

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

Syntax
TC{OMMIT}{:Postcond}

Definition
Postcond Any post-conditional expression.
The TCOMMIT command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the TCOMMIT command.
The TCOMMIT command indicates to the system that the current transaction or
subtransaction is complete. If the $TLEVEL special variable is 1, TCOMMIT
performs a commit of the transaction (applies all associated SETs and KILLs to the
database) and sets the $TRESTART special variable to 0.
If $TLEVEL is greater than 0, TCOMMIT subtracts 1 from $TLEVEL. If $TLEVEL
is 0, TCOMMIT generates an error.

Considerations
In MSM Version 4.3 and later, the commands and special variables associated with
the M Development Committee (MDC) Type A Standard for transactions are only
partially supported; however, the syntax is fully supported.
In addition, if the after-image journal is applied to the database (rolling forward a
bulletproof database after a system failure or applying the journal after a database
restore) the system attempts to apply only complete transactions (SETs and KILLs
bracketed by TSTART and TCOMMIT). A future release of MSM will fully support
transaction processing.

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

Examples

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

MSM Language Reference Manual MSM Commands • 93

TRESTART
Causes the current transaction to be restarted.

Syntax
TRE{START}{:Postcond}

Definition
Postcond Any post-conditional expression.
The TRESTART command is executed if the Postcond expression is true or if it is
not supplied on the command. If it is supplied and it is false, execution moves to the
next command after the TRESTART command.
The TRESTART command indicates to the system that the current transaction should
be restarted. If $TLEVEL is greater than 0 and the transaction is marked as
restartable (the TSTART command at $TLEVEL=1 indicates that it is restartable),
TRESTART performs a restart. As part of the restart, local variables specified on the
TSTART command (the TSTART issued with $TLEVEL=1) are restored to their
original value; the program stack is restored to its original location; the naked
indicator is restored; $TEST is restored; and any database updates performed by the
job are rolled back. If $TLEVEL is 0, TRESTART generates an error.

Considerations
In MSM Version 4.3 and later, the commands and special variables associated with
the M Development Committee (MDC) Type A Standard for transactions are only
partially supported; however, the syntax is fully supported.
In addition, if the after-image journal is applied to the database (rolling forward a
bulletproof database after a system failure or applying the journal after a database
restore) the system attempts to apply only complete transactions (SETs and KILLs
bracketed by TSTART and TCOMMIT). A future release of MSM will fully support
transaction processing.

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

Examples

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

94 • MSM Commands MSM Language Reference Manual

TROLLBACK
Indicates the unsuccessful end of the current transaction.

Syntax
TRO{LLBACK}{:Postcond}

Definition
Postcond Any post-conditional expression.
The TROLLBACK command is executed if the Postcond expression is true or if it is
not supplied on the command. If it is supplied and it is false, execution moves to the
next command after the TROLLBACK command.
The TROLLBACK command indicates to the system that the current transaction was
not successful. This means that any database changes initiated within the transaction
are not reflected in the database. If $TLEVEL is greater than 0, TROLLBACK
causes a rollback on the SETs and KILLs in the transaction; sets $TRESTART and
$TLEVEL to 0; and causes the naked indicator to become undefined. If $TLEVEL is
0, TROLLBACK generates an error.

Considerations
In MSM Version 4.3 and later, the commands and special variables associated with
the M Development Committee (MDC) Type A Standard for transactions are only
partially supported; however, the syntax is fully supported.
In addition, if the after-image journal is applied to the database (rolling forward a
bulletproof database after a system failure or applying the journal after a database
restore) the system attempts to apply only complete transactions (SETs and KILLs
bracketed by TSTART and TCOMMIT). A future release of MSM will fully support
transaction processing.

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

Examples

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

MSM Language Reference Manual MSM Commands • 95

TSTART
Indicates the beginning of a transaction or subtransaction.

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

Definition
Postcond Any post-conditional expression.
RestartVar One or more local variable names separated by commas and
enclosed in parentheses or asterisk (*).
TransParm One or more keywords or expressions separated by colons and
enclosed in parentheses. When a single keyword or expression
is specified, the parentheses can be omitted.
The TSTART command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the TSTART command.
The RestartVar parameter is used to specify one or more unsubscripted local
variables that are to be saved at the start of the transaction. The names of the local
variables to be saved are separated by commas and enclosed in parentheses. In place
of the local variable names, an asterisk can be specified to indicate that all of the
local variables are to be saved. When a single local variable name is specified, the
parentheses can be omitted. For a transaction to be restartable, one or more local
variables must be specified.
The TransParm parameter is used to specify information about the transaction. The
user can specify SERIAL (abbreviated S) to indicate that the transaction is to be
serialized relative to other transactions. The user also can specify
TRANSACTIONID=Expression (abbreviated T=Expression) to identify arbitrary
classes of transactions.
The TSTART command indicates to the system the beginning of a transaction or
subtransaction . The TSTART command adds 1 to the current value of the $TLEVEL
special variable. If, as a result, $TLEVEL is equal to 1, TSTART initiates a
transaction that is restartable if a RestartVar has been specified. Otherwise, TSTART
initiates a transaction that is not restartable. The transaction that is started is
serializable independently of LOCKs if the SERIAL parameter is present. Otherwise,
it is dependent upon LOCKs for serialization.
When a TSTART command is performed, the system places key information about
the transaction on the system stack. This includes the values of $TEST and the naked
indicator, the execution location of the TSTART command, a copy of the job’s
LOCK list, and the appropriate names and values of local variables specified by the
RestartVar parameter.

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

96 • MSM Commands MSM Language Reference Manual

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

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

Examples

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

MSM Language Reference Manual MSM Commands • 97

USE
Designates a specified device as the current device.

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

Definition
Postcond Any post-conditional expression.
Device An integer expression that indicates which device is to be used.
Parm One or more expressions separated by colons and enclosed in
parentheses that have meaning specific to the device being used.
Domain The name of the mnemonic namespace to be used with the device.
The USE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the USE command.
The USE command makes the specified device the current device. Unless the
specified device is the principal device, ownership of the device must have been
obtained previously with the OPEN command. All input/output operations are always
performed using the current device.
When a CLOSE command is executed for the current device, the system
automatically makes the principal device the current device. No attempt is made to
OPEN the principal device. If an error condition occurs and the $ZTRAP special
variable has not been set to trap the error, the system makes the principal device the
current device before issuing the error message.
The device specified on the USE command can be any valid MSM device. The Parm
specified for the device is specific to the device type. When arguments are listed, the
last argument in the list becomes the current device.
The MSM system maintains device-specific information separately for each device.
This includes the $DEVICE, $KEY, $X, $Y, $ZA , $ZB, and $ZC special variables,
as well as options specified through the Parm specified for a device.

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

98 • MSM Commands MSM Language Reference Manual

 Examples

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

MSM Language Reference Manual MSM Commands • 99

VIEW
Modifies specific memory or disk database locations.

Syntax
V{IEW}{:Postcond}SP{-}Block{:VolGroup}
V{IEW}{:Postcond}SPViewParm where ViewParm is of the form:
Address:{Domain}:Expression{:{ Length}{:Type}}

Definition
Postcond Any post-conditional expression.
Block An expression that identifies a disk block.
VolGroup A string value identifying a volume group.
Address An integer expression.
Domain An integer expression that indicates the area of memory to
modify.
Expression An expression that is to be assigned to the memory area.
Length An integer expression that specifies the length of the area in
memory to modify.
Type Indicates the data type of Expression.
The VIEW command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the VIEW command.
The VIEW command is used to modify the contents of memory and to read or write
disk blocks in the MSM database. In the first form, it is used to access the MSM
database.
The VolGroup specifies the name of the volume group, and the block number
specifies the relative block within the volume group. The VolGroup is specified using
the letter G followed by the volume group number from 0 through 31 (for example:
G0, G1, and so on).
The first block of a volume group is 0, the second block is 1, and so on. If the block
number is non-negative, the specified block is read into the VIEW buffer. If it is
negative, the specified block is written from the VIEW buffer to the database. When
this form of the VIEW command is used, the VIEW device (device 63) must be
owned.
In the second form, the VIEW command is used to modify the contents of system
memory. The user specifies a relative address within memory, the type of memory,
the replacement value, the length of memory to be replaced, and the replacement
type. It is not necessary to own the VIEW device to patch memory unless the area
being patched is within the VIEW buffer.

100 • MSM Commands MSM Language Reference Manual

 The Address argument is any positive integer, either odd or even (word boundary
alignment is not required). The range of the number is determined by the area of
memory being patched. When patching system memory, the value may be from 0
through the last byte address of the machine. For partitions, the range is from 0
through the last byte address in the partition vector. For the VIEW buffer, the range
is from 0 through the last byte address of the VIEW buffer (normally 1023).
The Domain argument is used to indicate which area of memory is to be patched.
Negative values indicate system memory. A value of 0 indicates the VIEW buffer.
When this area is specified, the user must own the VIEW device. A value greater
than 0 indicates a job’s partition, where 1 is the partition associated with job number
1, 2 is the partition associated with job number 2, and so on. If this argument is
omitted, a value of -3 is assumed.
The Expression argument specifies the new value that is to be patched into memory.
It must evaluate to the form indicated by the Type argument. If this argument is not
specified, a syntax error occurs.
The Length argument indicates the size of the memory area that is to be patched. For
integers, this is a maximum of four; for real numbers, it must be exactly eight. For
string values, this number can be any value up to 65536. Numbers of this size can
only be used to move areas within memory or to display areas of memory on the
current device. If this value is omitted, the natural word size of the machine is
assumed (two for 16-bit machines and four for 32-bit machines). A length of eight is
assumed if Type = 4. A length equal to $L(Expression) is assumed if Type = 1.
The Type argument is used to indicate the data type of value being patched into
memory. A value of 0 indicates an integer, a value of 1 indicates a character string,
and a value of 4 indicates a real (floating point) number. If this argument is omitted, a
value of 0 is assumed.

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

Examples

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

MSM Language Reference Manual MSM Commands • 101

WRITE
Writes constants and variables to the current device.

Syntax
W{RITE}{:Postcond}SPFormat
W{RITE}{:Postcond}SPExpression
W{RITE}{:Postcond}SP*Integer

Definition
Postcond Any post-conditional expression.
Format One or more format or mnemonic controls.
Expression Any valid expression.
*Integer Any valid integer expression.
The WRITE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the WRITE.
The WRITE command is used to output data to the current device. Arguments can be
listed on the WRITE command, and argument types can be intermixed in a single
command. If the current device does not allow output operations, an error occurs.
Format
The WRITE Format form is used to send control commands or mnemonic
namespace sequences to a device. One or more formatting characters can be specified
in each argument. The values of $X and $Y are adjusted accordingly.
Expression
The WRITE Expression form causes the value of the Expression to be written to the
output device, one character at a time, in left-to-right order. The effect of each
character sent to the device is defined by the ASCII Standard and conventions. The
values of the $X and $Y special variables are updated accordingly.
*Integer
The WRITE *Integer form is a one-character write operation that sends the ASCII
character whose decimal code is equal to the integer expression specified as the
argument. The expression is evaluated as modulo 256. This form allows the
programmer to send device-specific sequences to the current device (for example:
Escape sequences or ring the bell). Depending on the device type of the current
device, the value of Integer may be interpreted as a device control command rather
than a single character.

102 • MSM Commands MSM Language Reference Manual

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

Examples

Command Explanation
WRITE X This routine writes the contents of local variable X
to the current device.
W !,"Line Feed",#,"Form Feed", The arguments used on the WRITE command may
?20,"TAB",A(3) 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 WRITE.
W Z,@X,Y

MSM Language Reference Manual MSM Commands • 103

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

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

Definition
Postcond Any post-conditional expression.
Expression Any valid expression.
The XECUTE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the XECUTE command. For Postcond expressions on the argument
of the XECUTE command, the argument is skipped if the expression is false.
The XECUTE command is used to execute a line of M code that has been specified
as an argument to the command. Each argument of the command must evaluate to a
string, and the string must be a line of M code in the format returned by the $TEXT
function. In this form, it does not contain a leading TAB, does not end with RETURN,
and must not contain a label at the beginning of the string. When execution of the
argument terminates, it returns to process the next argument of the command or the
next command following the XECUTE command.

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

Associated Topics
DO Command
GOTO Command
QUIT Command

104 • MSM Commands MSM Language Reference Manual

 Examples

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

MSM Language Reference Manual MSM Commands • 105

ZALLOCATE
Incrementally LOCKs one or more local or global variables.

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

Definition
Postcond Any post-conditional expression.
Variable Any local or global variable name.
TimeOut A timeout value.
The ZALLOCATE command is executed if the Postcond expression is true or if it is
not supplied on the command. If it is supplied and it is false, execution moves to the
next command after the ZALLOCATE command.
The ZALLOCATE command is used to lock both local and global variables. The
MSM system maintains a table of all locked variables (the LOCK table). When a user
attempts to ZALLOCATE a variable, the table is searched to see if it is already
locked by another user. If so, the LOCK request is not granted.
When a lock is requested for a local variable, the lock is known throughout the
system and no other system user can lock the variable. When the lock is for a global
variable, the lock is known only within the UCI and only users running in the same
UCI are prevented from locking the variable.
When a variable is ZDEALLOCATEd, its name is removed from the LOCK table.
Other users then can lock the variable. ZALLOCATE is only a convention. Rather
than preventing users from accessing the locked variable, ZALLOCATE only
prevents them from issuing a LOCK or ZALLOCATE command for the same
variable. In fact, there is no requirement that the locked variable actually exist. The
goal is to have all users follow the same conventions so that simultaneous updates
can be prevented.
Unlike the simple form of the LOCK command, the ZALLOCATE command does
not automatically unlock previously locked variables before trying to lock the
variables specified in the argument. Because the ZALLOCATE command has a
cumulative effect, listing variable names on the command is equivalent to separating
the names with commas and enclosing them in parentheses.
The specified variable name must be a full reference. A naked reference is not
permitted. If the variable name is unsubscripted, the entire variable (including all
descendants) is locked. If a subscripted variable is used, the specified node and all
descendants of the node are locked. In addition, all ancestors of the node are made
unavailable for locking. The naked indicator is not updated for global references in
the LOCK or ZALLOCATE argument.

106 • MSM Commands MSM Language Reference Manual

 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)

MSM Language Reference Manual MSM Commands • 107

 Command Explanation
ZA D(1):3 G A:'$T An attempt is made for an interval of 3 seconds to ZALLOCATE
D(1). If it is successful, $T is Otherwise, $T is 0 and execution
continues with line A.
ZA D(1):3 ELSE G A This routine is equivalent to the previous example.
ZA:X=1 ^EF(^A(5)) The ZALLOCATE command can be post-conditionalized.
Appearance of a global name does not affect the naked indicator
unless, as in this example, it occurs in an evaluated expression.
Here it is a subscript; other such possibilities are in post-
conditionals and indirection.
ZA @A Indirection may be used in the ZALLOCATE command.
ZA:@B=C (X(@A),@B)

108 • MSM Commands MSM Language Reference Manual

ZDEALLOCATE
Incrementally unLOCKS one or more local or global variables.

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

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

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

Associated Topics
LOCK Command
ZALLOCATE Command

Examples

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

MSM Language Reference Manual MSM Commands • 109

ZFLUSH
Empties the disk buffer cache of all buffers.

Syntax
ZF{LUSH}{:Postcond}

Definition
Postcond Any post-conditional expression.
The ZFLUSH command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZFLUSH command.
The ZFLUSH command is used to flush all disk blocks out of the internal disk buffer
cache. All modified buffers are rewritten to the database and then deleted from the
cache. Unmodified buffers are deleted from the cache without being written to disk.
Any subsequent references to routines or globals require the system to reread the
routine or global disk blocks from disk rather than use the values in memory.

Associated Topics
Buffer Pool

Examples

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

110 • MSM Commands MSM Language Reference Manual

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

Syntax
ZG{O}{:Postcond}

Definition
Postcond Any post-conditional expression.
The ZGO command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZGO command.
The ZGO command is used to resume execution of a routine that was suspended by a
BREAK command. A BREAK command suspends execution of a routine only when
the interactive debugger was used to invoke the routine. While the routine is
suspended, enter any M commands or interactive debugger commands. Enter a
question mark (?) to display a list of valid debugger commands. Changes made to the
routine while it is suspended prevent the ZGO command from restarting the
suspended routine.

Associated Topics
BREAK Command
Interactive Debugger

Examples

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

MSM Language Reference Manual MSM Commands • 111

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

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

Definition
Postcond Any post-conditional expression.
Date A date value in $HOROLOG format.
Time A time value in $HOROLOG format.
The ZHOROLOG command is executed if the Postcond expression is true or if it is
not supplied on the command. If it is supplied and it is false, execution moves to the
next command after the ZHOROLOG command.
The ZHOROLOG command is used to temporarily adjust the date, time, or date and
time that are returned by the $HOROLOG function. When the Date operand is
specified and is preceded by a plus sign (+) or minus sign (-), the value is added to or
subtracted from the date portion of the actual system $HOROLOG. Otherwise, the
actual value specified by the Date operand is returned by the $HOROLOG function.
Similarly, when the Time operand is specified and is preceded by a plus (+) or minus
(-) sign, the value is added to or subtracted from the time portion of the actual system
$HOROLOG. Otherwise, the actual value specified by the Time operand is returned
by the $HOROLOG function.
If either operand is omitted, the $HOROLOG function returns the actual system date
or time as appropriate. If no operands are specified, $HOROLOG is reset to the
actual system date and time. The ZHOROLOG command affects the value of the
$HOROLOG special variable only for the partition that issued the ZHOROLOG
command. Other partitions get the unadjusted actual system $HOROLOG value. This
command cannot be abbreviated.

Associated Topics
$HOROLOG Special Variable

Examples

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

112 • MSM Commands MSM Language Reference Manual

ZINSERT
Inserts a line of code into the current routine.

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

Definition
Postcond Any post-conditional expression.
Expression An expression that evaluates to the text of the line to be inserted.
LineRef A line reference indicating the insert point.
The ZINSERT command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZINSERT command.
The ZINSERT command is used to insert a line of code into the routine that is
currently loaded into the partition. The Expression argument denotes the line of text
to be inserted. It must evaluate to a string that is in the proper format to be inserted
into the routine. The format of the string must be one of the following:
labelSPcommand line
labelTABcommand line
SPcommand line
TAB command line

This is the same format returned by the $TEXT function. The LineRef argument
specifies the location within the routine where the text is to be inserted. The LineRef
expression must evaluate to a line label (for example: ABC), a line label plus an
offset (for example: ABC+3), or simply an offset (for example: +3). The text
specified by expression is inserted immediately following the line specified by
LineRef.
If the LineRef argument is omitted, the current implicit line pointer location is used.
The implicit line pointer location is set by the ZPRINT and ZREMOVE commands.
ZINSERT does not alter the implicit line pointer location.

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

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

MSM Language Reference Manual MSM Commands • 113

 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.

114 • MSM Commands MSM Language Reference Manual

ZLOAD
Loads a routine from the database or current device.

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

Definition
Postcond Any post-conditional expression.
Routname Any valid routine name.
The ZLOAD command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZLOAD command.
The ZLOAD command is used to load a routine into the partition from the current
device or from the MSM database. In the argumentless form, the routine is loaded
from a device. The device that contains the routine to be loaded must be OPEN, and
it must be the current device. In this form, the input lines are entered in the same
format returned by the $TEXT function, and each line is terminated with RETURN.
End of input is signaled by a null line (a line that contains only RETURN).
In the form with an argument, the specified routine is loaded from the routine
directory in the current UCI. The routine name begins with an alpha character or a
percent sign (%) and is followed by alphanumeric characters. If the name is longer
than eight characters, all characters after the eighth one are ignored. The name is not
preceded by the circumflex (^) character.

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

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

MSM Language Reference Manual MSM Commands • 115

 Examples

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

116 • MSM Commands MSM Language Reference Manual

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

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

Definition
Postcond Any post-conditional expression.
Expression An integer expression that indicates the type of trace to perform.
Device A device designator indicating the output device for the trace.
The ZMSM command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZMSM command.
The ZMSM command is used to trace the flow of various types of events in MSM to
aid in debugging. The Expression argument is used to indicate the type of function in
MSM that is to be traced. If the value of the Expression is 0, the trace is disabled. If
it is greater than 0, one or more functions within MSM are traced. The following
table lists the events that can be traced.

Level Event to be traced

0 Turns off trace
1 Traces DO, GOTO, XECUTE and QUIT

When trace is enabled, descriptive messages about the events are displayed on the
current device. By specifying the Device argument, these messages can be directed to
some other device. The device must be owned by the job (OPEN); otherwise, an
error occurs.

Associated Topics
Using Peripheral Devices, MSM User's Guide

Examples

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

MSM Language Reference Manual MSM Commands • 117

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

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

Definition
Postcond Any post-conditional expression.
LocalVar An unsubscripted local variable name.
The ZNEW command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZNEW command.
The ZNEW command is used to make temporary copies of unsubscripted local
variables. When a temporary copy is created, the old variable, its value, and the
values of all its descendants are copied onto a stack. When a QUIT command is
encountered, the stacked values are restored (merged) to the local symbol table.
Only the local variables specifically named as arguments of the ZNEW command are
stacked. Local variable names cannot include subscripts. If the name includes
subscripts, an error occurs. Variables are not killed after they are stacked.

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

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

118 • MSM Commands MSM Language Reference Manual

 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.

MSM Language Reference Manual MSM Commands • 119

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

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

Definition
Postcond Any post-conditional expression.
StartLine A line reference for the starting line.
EndLine A line reference that indicates the ending line.
The ZPRINT command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZPRINT command.
The ZPRINT command is used to output one or more lines of a routine to the current
device. In the argumentless form, the entire routine is written to the current device.
The implicit line pointer that is used for data entry of routine lines is set to the end of
the routine.
In the form with arguments, all lines from and including the StartLine, through and
including the EndLine, are output to the current device. The format of the lines is the
same as returned by the $TEXT function, and each line ends with a carriage
return/line feed sequence.
The StartLine and EndLine expressions can evaluate to a line label (for example:
ABC), a line label plus an offset (for example: ABC+3), or simply an offset (for
example: +3). For simple offsets, the numeric value is the number of lines from the
start of the routine. The first line is +1, the second is +2, and so on.
If only the StartLine is specified, then the single line indicated by the expression is
output to the current device. If the EndLine is specified and it is null, all lines from
and including the StartLine through the end of the routine are output to the current
device. In both forms, the implicit line pointer used for data entry of routine lines is
set to the last line output to the current device.

Associated Topics
$TEXT Function
ZINSERT Command

120 • MSM Commands MSM Language Reference Manual

 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.

MSM Language Reference Manual MSM Commands • 121

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

Syntax
ZQ{UIT}{:Postcond}

Definition
Postcond Any post-conditional expression.
The ZQUIT command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZQUIT command.
To understand the operation of the ZQUIT command, it is first necessary to
understand how error trapping is implemented in MSM. When a DO or XECUTE
command is processed, the MSM system creates a new execution level. This is done
so that when a DO or XECUTE command terminates either through an implicit
QUIT (end of routine encountered) or an explicit QUIT, the system can return to the
point at which the command was initiated.
Each execution level created by a DO or XECUTE command is numbered.
Programmer mode is considered to be execution level 1, the first DO or XECUTE
command is level 2, the second is level 3, and so on. The execution level that is
currently in control generally is referred to as the current execution level.
One $ZTRAP special variable can be set at each execution level (level 1, level 2, and
so on). This means that each execution level in an application can establish its own
error trapping routine and error recovery procedures.
When a ZQUIT command is issued from within an error handling routine, it returns
to the next higher execution level that contains an error processing routine. If none
exists, the system returns to the highest execution level (level 1, which generally is
programmer mode).
Alternatively, a GOTO command can be used to transfer control to another program
at the same level, or a QUIT command can be used to return to the command that
follows the DO or XECUTE command at the next higher level.
Refer to the MSM User's Guide for a complete description of error handling and use
of the ZQUIT command.

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

122 • MSM Commands MSM Language Reference Manual

 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

MSM Language Reference Manual MSM Commands • 123

ZREMOVE
Removes one or more lines from the current routine.

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

Definition
Postcond Any post-conditional expression.
StartLine A line reference for the starting line.
EndLine A line reference that indicates the ending line.
The ZREMOVE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZREMOVE command.
The ZREMOVE command is used to delete one or more lines of a routine. In the
argumentless form, the entire routine is deleted from the partition and $ZNAME is
set to null. The implicit line pointer that is used for data entry is set to the beginning
of the routine.
In the form with arguments, all lines from and including the StartLine, through and
including the EndLine, are deleted from the partition. The StartLine and EndLine
expressions can evaluate to a line label (for example: ABC), a line label plus an
offset (for example: ABC+3), or simply an offset (for example: +3). For simple
offsets, the numeric value is the number of lines from the start of the routine. The
first line is +1, the second is +2, and so on.
If only the StartLine is specified, then the single line indicated by the expression is
deleted from the current routine. If the EndLine is specified and it is null, an error
occurs. When the EndLine appears in the routine before the StartLine, no action takes
place (no lines are deleted). In the form with arguments, the implicit line pointer used
for data entry of routine lines is set to the line that immediately precedes the first
deleted line.

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

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

124 • MSM Commands MSM Language Reference Manual

 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.

MSM Language Reference Manual MSM Commands • 125

ZSAVE
Saves the current routine on the database.

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

Definition
Postcond Any post-conditional expression.
Routname Any valid routine name.
Level An integer expression that indicates the level of source code that
is to be retained with the saved routine.
Expression A numeric expression that prevents a routine from being saved if
the compiler detects errors.
The ZSAVE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZSAVE command.
The ZSAVE command is used to write the routine currently loaded into the partition
to the routine directory in the current UCI. In the argumentless form, a routine name
must already be associated with the routine in the partition. The routine name can be
accessed using the $TEXT function ($TEXT(+1) returns the name) or the $ZNAME
special variable. If no name is associated with the routine and the argumentless form
of ZSAVE is used, a <NOPGM> error occurs.
In the form with arguments, the routine is saved using the name specified by the
Routname argument. After the save, the name associated with the routine is the name
specified as the argument.
The Level argument is used to control how much of the source code is retained with
the routine when it is saved. The argument must evaluate to an integer that has a
value of 0 through 15, inclusive. If this argument is omitted, a value of 0 is assumed.
As part of the ZSAVE process, the MSM system compiles the routine lines to a
pseudo-code format. All or part of the source code can be removed as part of this
process. If $TEXT is used to reference a line whose source code has been removed,
the function returns a single blank. The following table lists the available levels.

Level Source Code Retained

0 All text lines
1 All comment lines (; or ;;)
2 First line comment and all ;; lines
3 First line comment and all ;; lines
4 All comment lines (; or ;;)
5 All comment lines (; or ;;)
6 All ;; comment lines

126 • MSM Commands MSM Language Reference Manual

 Level Source Code Retained
7 All ;; comment lines
8 All ; comment lines and first line if comment
9 All ; comment lines and first line if comment
10 First line if comment line
11 First line if comment line
12 All ; comment lines
13 All ; comment lines
14 Remove all text
15 Remove all text

The Expression argument is used to control whether or not the system saves the
routine in the event that errors are detected. If the Expression has a value of 0 or is
not present, the routine is saved even if it contains errors. If the Expression has a
value of 1, the routine is not saved if errors are found. The system can detect only
compile-type errors (for example: <SYNTX> error), and not runtime errors (for
example: <UNDEF> error).
When an Expression Value of 1 has been specified, the $ZA special variable is
updated as part of the routine save operation. If the compiler found no errors in the
routine, $ZA contains a value of 0. Otherwise, $ZA contains the number of the line
that contains the error, relative to the beginning of the program. The first line in the
program is considered to be 1, the second is 2, and so on. The number returned in
$ZA can be used as the argument to the $TEXT function to retrieve the line that
contains the error.
When an error is detected, the $ZB special variable contains the relative
displacement in the line in which the error was detected. The first character in the
line is 1, the second is 2, and so on. By using a combination of $ZA and $ZB, the
actual location of the error in the program can be displayed.
After a ZSAVE command with an Expression Value of 1, the values of $ZA and $ZB
remain valid until another M command is processed that updates the values of these
special variables. M commands that update the $ZA and $ZB special variables
include OPEN, USE, READ, JOB, and so on. When the ZSAVE is done in
programmer mode, MSM implicitly performs a USE $I command before issuing the
command prompt. The programmer should save the value of $ZA as part of the
ZSAVE command.

1RWH 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.

MSM Language Reference Manual MSM Commands • 127

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

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

Examples

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

128 • MSM Commands MSM Language Reference Manual

ZSETOBJ
Assigns an object reference to a variable.

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

Definition
Postcond Any post-conditional expression.
Variable Either a local variable name or a property of an object.
Expression Any expression that evaluates to an object reference.
The ZSETOBJ command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZSETOBJ command.
The ZSETOBJ command is used to assign the value of the Expression to one or more
variables or object properties, including the default property. When multiple
Variables are to be assigned the same value, their names are separated by commas
and enclosed in parentheses. Execution of the ZSETOBJ command occurs in the
following order:
Any indirection or subscripts that appear in the argument are evaluated in a left-to-
right order.
The Expression is evaluated according to the specified rules.
The value of the Expression is assigned to each Variable, one at a time in a left-to-
right order if there are several. If the Variable includes subscripts and the specified
node does not exist, the system creates the node and the minimum number of ancestor
nodes required to provide a path to the new node. When the ancestor nodes are
created, they are defined so that they have a descendant but no data value (when the
$DATA function is applied to a created ancestor node, its value is 10).

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

MSM Language Reference Manual MSM Commands • 129

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

Examples

Command Explanation
ZSETOBJ X=Y The value (which must be an object
reference) of the unsubscripted variable
Y is assigned to the unsubscripted local
variable X. The previous value of X is
discarded.
ZSE A(1,2)=Y(1) This works similarly for subscripted
variables.
ZSE A(1)=X,B(4)=D This shows multiple arguments of
ZSETOBJ.
ZSETOBJ:PC>5 (A,B,C)=MYOBJ This is a "multiple" set. All variables in
the parentheses are set to the same object
reference value. Note the use of the
post-conditional. The ZSETOBJ
command is executed only if local
variable PC has a value greater than 5.
SET ^A(1)=0 ZSE (A,B)=MYOBJ,A(3)=W, 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, ^(3,5)
evaluates to ^A(3,5), due to the setting of
the naked by the "SET ^A(1)."
Therefore, ^(4) becomes ^A(3,4). Even
in a multiple set, the left subscripts are
evaluated before the assignment is made,
but each argument is completed before
the next is begun.
ZSETOBJ @X,@A=B Indirection is often used in the
ZSETOBJ command.
ZSETOBJ myjob=system.apps($J) WRITE This command uses a variable system to
myjob.commands 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.

130 • MSM Commands MSM Language Reference Manual

ZSYNC
Flushes network activity for the current job.

Syntax
ZSY{NC}{:Postcond}

Definition
Postcond Any post-conditional expression.
The ZSYNC command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZSYNC command.
In MSM, any global SET (update) or KILL operations performed over a network are
buffered by the system to improve efficiency. They can be processed later by the
system to which they are being sent. The ZSYNC command has been implemented to
provide a mechanism for a job to ensure that all global transactions have been
completed by the other system. When the ZSYNC command is issued, the current job
is suspended until all in-progress network transactions are complete.

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

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

Examples

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

MSM Language Reference Manual MSM Commands • 131

ZTRAP
Forces an error condition during execution of a routine.

Syntax
ZT{RAP}{:Postcond}SPString

Definition
Postcond Any post-conditional expression.
String A string expression that specifies the text of the error to be
displayed.
The ZTRAP command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZTRAP command.
The ZTRAP command is used to force an error condition during routine execution.
When the error condition occurs, routine execution is terminated in the same manner
as any other type of error condition. Any error traps set by the routine are honored.
The String argument is an expression that evaluates to a one-to four-character string
that indicates the specified error type. The letter Z followed by the specified string is
displayed as the error code in the standard MSM error message. If the expression is
null or not specified, a default value of TRAP is used.

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

Examples

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

132 • MSM Commands MSM Language Reference Manual

ZUSE
Temporarily gains ownership of a device.

Syntax
ZU{SE}{:Postcond}SPDevice

Definition
Postcond Any post-conditional expression.
Device Any valid terminal device designator.
The ZUSE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZUSE command.
The ZUSE command is used to temporarily gain ownership of a device that may
already be owned by another job. The primary purpose of ZUSE is to allow messages
to be broadcast to system users. The ZUSE command makes the device specified by
the device argument the current device without using the OPEN and USE commands.
The specified device must be a terminal type device that is currently active on the
system. When a device is acquired through the ZUSE command, only the WRITE
command can be used with the device. Any other input/output command causes an
error.
MSM-UNIX only: Output that has been directed by the ZUSE command can be
delayed for up to five seconds.

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

Examples

Command Explanation
ZUSE 4 W !,"SYSTEM AVAILABLE UNTIL This routine sends a broadcast message to a
23:00 TONIGHT" 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.

MSM Language Reference Manual MSM Commands • 133

ZWRITE
Writes the contents of the local symbol table.

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

Definition
Postcond Any post-conditional expression.
Variable Any subscripted or unsubscripted local variable name.
The ZWRITE command is executed if the Postcond expression is true or if it is not
supplied on the command. If it is supplied and it is false, execution moves to the next
command after the ZWRITE command.
The ZWRITE command is used to display the values of one or more local variables
and their descendants on the current device. Variables are displayed in ASCII
collating sequence.
In the argumentless form, all local variables are displayed. In the form with
arguments, only the specified local variables are displayed. If the specified local
variable has descendants, all descendants also are displayed.

Associated Topics
Variables

Examples

Command Explanation
ZWRITE ZWRITE writes the contents of the local symbol table to the
current device.
X=0
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 of
its descendants.
CODE=
CODE(1)="R499"
CODE(2)="MM88"
CODE(3)="A1AA"

S X=10 Indirection may be used with the ZWRITE command, but the
S Y="X" indirection must yield a local variable that was previously
ZW @Y defined.

134 • MSM Commands MSM Language Reference Manual

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 you can
write your own functions.
In the MSM system, a function is an operation that returns a single numeric or string
value. The ANSI-standard definition for the M language defines the following two
function types.
Intrinsic A built-in function defined by the system (for example $DATA or
$PIECE).
Extrinsic A user-defined function that has been implemented as an M routine.
The following sections describe both function types and how the M programmer can
use them.

Intrinsic Functions
The M language contains functions that the programmer can use to facilitate creation
of programs or routines, as they are referred to in MSM. Functions supplied with the
system as part of the M language are referred to as intrinsic functions. An intrinsic
function is a directive to the compiler to perform a specific action and then return a
single value that results from the action. Each function performs a specific action
that is further defined by the arguments associated with it.
An intrinsic function is represented by a dollar sign ($), followed by the function
name, followed by one or more parameters enclosed in parentheses.
The following illustrates the syntax of an intrinsic function:
$FuncName(ActualList)
FuncName Any MSM-supplied function name.
ActualList One or more arguments (expressions) separated by commas.
MSM provides all of the ANSI-standard functions and an extended set of functions
specific to MSM. The ANSI Standard functions begin with a dollar sign ($),
followed by any name that starts with the letters A through Y. The MSM-specific
functions begin with a dollar sign, followed by any name that starts with the letter Z.

MSM Language Reference Manual MSM Functions • 135

 Functions either can be spelled completely or can be abbreviated to the minimum
number of characters necessary to uniquely identify them. Function names can be
specified in uppercase, lowercase, or a combination of uppercase and lowercase
letters. For example, all of the following are valid abbreviations for functions:
$PIECE
$P
$pIeCe
$p
New intrinsic functions that specify both the full name and its abbreviation are
continually being added to the ANSI standard. Generally, the abbreviation for a new
function is the dollar sign and the minimum number of characters necessary to
uniquely identify the function. The $TRANSLATE function is abbreviated to $TR
because it conflicts with the $TEXT function that is abbreviated as $T. In all cases, a
single-character abbreviation invokes the old function when a new function exists
that begins with the same letter.
When an intrinsic function is specified, an argument list must be present. It can
consist of a single argument (a single expression) or multiple arguments separated by
commas (expression, ... ,expression).
The argument list must not contain spaces between the arguments or commas unless
it is part of a quoted string. The parentheses around the argument list must
immediately follow the function name (spaces between the function name and the
opening parenthesis are not allowed).
The following sections provide information about the functions provided in MSM.
For each function, information about syntax, a description of functionality, special
considerations, associated topics, and examples are provided. For additional
information about writing M programs, refer to the MSM User's Guide.

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

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

136 • MSM Functions MSM Language Reference Manual

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

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

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

Parameter binding
To pass parameters to an extrinsic function, the system must match the arguments in
the ActualList with the variables in the FormalList. This match is referred to as
binding. To perform the binding, the system first creates a parameter list that
contains, in the specified order, the address of variables for arguments that are call-
by-reference and the actual values for arguments that are call-by-value.
The system then loads the specified EntryRef for the function. Before actually
entering the subroutine, the system performs an implicit NEW command on all local
variables in the FormalList. This is done so that when the extrinsic function
terminates, these variables can be restored to their original form.
When an extrinsic function is called, the caller may supply all of the parameters that
can be received by the subroutine. Any local variables that appear in the FormalList
but do not appear in the ActualList are undefined. If they are referenced by the
subroutine, an <UNDEF> error occurs.
The ActualList cannot be longer than the FormalList; such a situation causes the
system to generate a <DPARM> error. A null ActualList can be specified when
calling an extrinsic function by omitting the ActualList from the call. Alternatively,
the open and close parentheses can be specified with no value between them (that is,
( ) appears after the function name). A null FormalList also can be specified by using
the open/close parentheses form. However, the FormalList cannot be omitted.
Finally, the variables in the FormalList are initialized. For a variable passed using
call-by-value, the variable in the FormalList is assigned the value of the passed
parameter. This variable then can be freely changed without any impact on the
calling routine.

MSM Language Reference Manual MSM Functions • 137

 For call-by-reference variables, the FormalList variable is made to point (aliasing) to
the data value of the local variable that corresponds to it positionally in the
ActualList. This means that if the subroutine modifies the value of a call-by-
reference variable in the FormalList, the value of the variable in the ActualList also
is changed. Similarly, if the subroutine KILLs such a variable, the variable in the
ActualList also is killed. In accordance with the ANSI M standard, the aliasing
continues even after the KILL. If the subroutine assigns a value to such a variable
after the KILL, the aliased variable (in the calling routine) also is set.
Although the variable in the ActualList must not contain any subscripts, subscripts
can exist for the specified variable name. When the KILL command is used on a
variable in the FormalList that was passed using call-by-reference, it is possible to
KILL the entire array.

Return values
After an extrinsic function is called, it must return a value to the caller. This is done
by supplying an argument on the QUIT command. The argument can be any valid
expression.
When an extrinsic function is called and an ActualList is not specified with it, then it
is referred to as an extrinsic variable. It behaves exactly like an extrinsic function
and can be used anywhere that an extrinsic function can be used. The only difference
is that no arguments or parentheses are associated with it.
As with extrinsic functions, the line specified by the EntryRef must contain an empty
FormalList of parameters. If it does not, a <DPARM> error occurs.

Other notes
Several other points should be remembered when using extrinsic functions. For
example, the only way to invoke a subroutine that contains a FormalList is with a
DO command or a reference to an extrinsic function. If a program falls through to a
subroutine with a FormalList or reaches the subroutine with a GOTO command, a
<DPARM> error occurs.
Because of the way that parameter passing works, indirection cannot be used when
specifying a FormalList for a subroutine. In addition, call-by-reference can only be
used for local variables. Expressions and globals cannot be used as arguments.
The value of the $TEST special variable is preserved across an extrinsic function
call. MSM saves the value of $TEST before it evaluates the ActualList and calls the
function. After the function completes, $TEST is restored to the value that existed
before the call.
All of the variable names in the FormalList must be unique. This is not true for the
ActualList. However, when the same name appears more than once and is passed
using call-by-reference, more than one variable in the FormalList points to the same
data value.

138 • MSM Functions MSM Language Reference Manual

 Examples
Consider the following routine:
VOL(R,H) ; Calculate volume of a cylinder
; R=radius, H=height
; V= pi * (radius squared) * height
Q 3.14159265*R*R*H

When the following is executed:

SET VOLUME=$$^VOL(RAD,H)
the variable VOLUME equals the volume of a cylinder of radius "RAD" and height "H." This
is an example of call-by-value parameter passing.
Consider the following routine:
%EXP(INT,P) ; Calculate INT to the P power
I P=0 S INT=1 Q 1
N I,X
S X=INT
F I=1:1:P-1 S INT=INT*X
Q INT

When the following is executed:

SET X=2,Y=8 W $$^%EXP(X,Y)
the number 256 is written to the current device. If the code is rewritten as follows:
SET X=2,Y=8 W $$^%EXP(.X,Y)
the output is the same, but the value of variable X is changed to 256. This is an example of
call-by-reference parameter passing.
Consider the following routine:
%FMRD(H) ; Convert $H date to FileMan date
S X=$ZDATE(H)
EXIT ;
Q 2_$P(X,"/",3)_$P(X,"/")_$P(X,"/",2)
T() ; Return FileMan date for today
S X=$ZD($H) G EXIT
When the following is executed:
SET FMRDAT=$$^%FMRD($H-10)
the variable FMRDAT contains the FileMan internal date for ten days before execution of the
program. If the following code is executed:
S TODAY=$$T^%FMRD
the variable TODAY is set to the current FileMan date. In this case, $$T^%FMRD is called an
extrinsic variable, because parameters are not passed to the subroutine. Note that label "T"
must have at least a null formal list even when it is used as an extrinsic variable.

MSM Language Reference Manual MSM Functions • 139

$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

140 • MSM Functions MSM Language Reference Manual

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

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

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

Associated Topics
$ASCII Function
ASCII Character Set

Examples

Setup Value of Function

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

MSM Language Reference Manual MSM Functions • 141

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

Syntax
$D{ATA}(Variable)

Definition
Variable An expression that evaluates to a local or global variable name.
The $DATA function returns a value that indicates whether the global or local
variable specified by Variable is defined, has data, and has descendants. The
following values are returned by the function.
0 The global or local variable is not defined, has no data, and has no
descendants.
1 The global or local variable is defined, has data, but has no descendants.
10 The global or local variable is defined, has no data, and has descendants.
11 The global or local variable is defined, has data, and has descendants.
If the variable is specified using a naked reference, the naked indicator must have
been previously set.

Examples

Setup Value of Function

Y is not defined $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

142 • MSM Functions MSM Language Reference Manual

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

MSM Language Reference Manual MSM Functions • 143

 Example

Setup Value of Function

SET X="ABCDE" $E(X)="A"
$E(X,1)="A"
$E(X,2)="B"
$E(X,1,2)="AB"
$E(X,1,4)="ABCD"
$E(X,0,100)="ABCDE"
$E(X,3.9)="C" (uses 3 as begin)
$E(x,-1,6)="ABCDE"
$E(X,0)="" (null string)
$E(X,99)="" (null string)
$E(X,-3)="" (null string)
$E(X,3,2)="" (null string)
$E(X,-10,-5)="" (null string)

S A(1)="2BC" $E(A(1),A(1))="B"

S X="ABCDE",$E(X,3,4)=12 X="AB12E"

S X="ABCDE",$E(X,2,4)=1 X="A1E"

S X="A",$E(X,3)=1 X="A 1"

K X S $E(X,3,4)=12 X=" 12"

S A="NAME",NAME="AB" NAME="1B"
S $E(@A)=1

144 • MSM Functions MSM Language Reference Manual

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

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

Definition
String Any string-type expression.
Substring Any string-type expression that is to be located within String.
Begin An integer expression that indicates the location where the search
is to start.
The $FIND function searches a String to see if it contains a specified Substring. If it
does, then the function returns an integer value that is the location of the character
immediately to the right of the Substring's last character. The function returns 0 if the
Substring is not contained in the String.
Although the search generally begins with the first character of the String, the Begin
argument can be used to specify a different starting location. If the starting location
is less than 1, a value of 1 is assumed. When the Substring occurs more than once in
the String, the function returns the location of the first occurrence found after the
starting location. When the specified Substring is null, the function returns the
starting location.

Associated Topics
$LENGTH Function
CONTAINS Operators

Examples

Setup Value of Function

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

MSM Language Reference Manual MSM Functions • 145

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

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

Definition
Number Any numeric type expression.
Format A string expression that specifies the formatting to be performed
on the Number.
Fraction An integer expression that specifies the number of digits to the
right of the decimal point to display.
The $FNUMBER function returns the specified Number as a string, formatted
according to a pattern specified by the Format codes. The Format codes are defined
in the following table.
)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.
P or p Represents negative values of Number in parentheses. If the specified
Number is positive, blanks are inserted where the parentheses normally
would be inserted.
T or t Shows the Number with a trailing, rather than leading, "+" or "-" sign. If sign
suppression is in force (positive number or "-" Format code), then a trailing
space is added.

The order in which the Format codes are specified does not affect the processing. If
a particular Format code is specified more than once, it is ignored. When the
specified Format is null, the original value of Number is returned. An error condition
results if the Format code "P" is specified along with "T," "+," or "-" in the string.
If Fraction is specified, it indicates the number of places to the right of the decimal
point to display. When the Number is evaluated, the specified number of decimal
places is calculated, with padding, truncation, or rounding, if appropriate. Trailing
zeros are added, if needed to display the proper number of fraction places. If
-1 < Number < 1, a leading 0 is added to the left of the decimal point.

146 • MSM Functions MSM Language Reference Manual

 Examples

Setup Value of Function

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

MSM Language Reference Manual MSM Functions • 147

$GET
Returns the data value of a variable if it exists.

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

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

Associated Topics
Variables
$DATA Function

Examples

Setup Value of Function

KILL ABC $GET(ABC,"123")=123
$G(ABC(1,3))=""
$G(ABC(1,3),"EMPTY")="EMPTY"

S ABC(1,3)=4 $G(ABC(1,3),"EMPTY")=4

148 • MSM Functions MSM Language Reference Manual

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

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

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

Examples

Setup Value of Function

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

MSM Language Reference Manual MSM Functions • 149

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

Syntax
$L{ENGTH}(String{,Substring})

Definition
String Any string-type expression.
Substring Any string-type expression that is to be counted within String.
The $LENGTH function returns an integer value that indicates the number of
characters in String. If String is null, the function returns 0. If a substring is
specified, the function returns an integer value that is one greater than the number of
non-overlapping times the Substring is contained in the String. If the Substring is
specified and it is null, the function returns 0.

Examples

Setup Value of Function

SET X="ABC" $LENGTH(X)=3
S X="123456789" $L(X)=9
S X="" (null string) $L(X)=0
S X="ABCDBCABCABCD" $L(X,"AB")=4
$L(X,"DC")=1
$L(X,"ABCD")=3
$L(X,"")=0
S X="AAAA" $L(X,"AA")=3

150 • MSM Functions MSM Language Reference Manual

$NAME
Returns the evaluated form of the specified Variable name.

Syntax
$NA{ME}(Variable{,Subscripts})

Definition
Variable An expression that evaluates to a local or global variable name.
Subscripts An expression that specifies the number of subscripts to be
returned in the Variable name.
The $NAME function returns a string value that is a full local or global reference
denoting all or part of the specified Variable. If the Subscript argument is not
specified or is 0, the value returned is the Variable name. Otherwise, the function
returns a full local or global reference that contains up to the specified number of
subscripts.

Considerations
When naked references are used within the $NAME function, a string corresponding
to the full reference is returned. However, the $NAME function does not affect the
naked indicator.

Associated Topics
Variables
Naked References

Examples

Setup Value of Function

$NAME(^A(3,"B",3+4)) ^A(3,"B",7)
$NA(^A(3,"B",7),2) ^A(3,"B")
$NA(^A(3,"B",7),0) ^A
$NA(^A(3,"B",7),-1) Error condition
S X=^A(3,"B",7) Sets up a naked reference
$NA(^(3)) ^A(3,"B",3)

MSM Language Reference Manual MSM Functions • 151

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

152 • MSM Functions MSM Language Reference Manual

 Associated Topics
$ORDER Function
$QUERY Function
$ZNEXT Function
$ZORDER Function
$ZPREVIOUS Function
$ZSORT Function

Examples

Setup Value of Function

SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3 $NEXT(^A)=name of next global
in the local directory
$N(^A(-1))="1" first node
$N(^A(1))="2" second node
$N(^A(2))="4" third node
$N(^A(4))="-1" no descendants
$N(^A(1,-1))="2" second-node
level
$N(^A(1,2,-1))="3" third-node
level
$N(^A(1,2,3,-1))="-1" no
fourth level
SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3 $NEXT(^A(-1),-1)="4" last node
$N(^A(4),-1)="2" next-to-last
node
$N(^A(2),-1)="1" first node
$N(^A(1),-1)="-1" no
descendants
$N(^A(1,-1),-1)="2" second
level
$N(^A(1,2,-1),-1)="3" third
level
$N(^A(1,2,3,-1),-1)="-1" no
fourth level
KILL SET (%A(2),ABC,x)="" $NEXT()="%A"
$N(%A)="ABC"
$N(ABC)="x"
$N(x)="-1"
$N(^CUST) "HELP"

MSM Language Reference Manual MSM Functions • 153

$ORDER
Identifies the next subscript, in collating sequence, for a specified subscripted
Variable.

Syntax
$O{RDER}(Variable{,Direction})

Definition
Variable An expression that evaluates to a local or global variable name.
Direction An expression that evaluates to either 1 or -1.
The $ORDER function is used to identify the next or previous subscript in sequence
at a given level. The Variable name that is specified as an argument to the function
must be subscripted, and naked references are allowed. If Direction is not specified
or has a value of 1, then for the right-most subscript in the Variable, the system
returns the next subscript value that follows it. If no subscript follows it, the function
returns a null value. If the right-most subscript in the reference is a null value, the
system returns the value of the first or last subscript at that level, depending on the
value of Direction. If Direction is specified and evaluates to -1, the function returns
the previous subscript for the variable. If Direction is specified and has any value
other than 1 or -1, an error condition occurs.
The $ORDER function returns the subscripts in the collating sequence that was
defined for the global (string or numeric sequence). For local variables, the
subscripts always are returned in numeric order. The $ZSORT function is identical to
the $ORDER function, except that for local variables, it returns the subscripts in
string-collating sequence.
$ORDER can be used to step through the local symbol table. If Variable evaluates to
an unsubscripted local variable, $ORDER either returns the next local variable
defined in the partition or null if none exists. Because $ORDER has no starting point
when used in this manner, one must start with $ORDER() to obtain the name of the
first or last local variable in the partition.
Although the $ORDER function performs the same function as $NEXT, it supports
string subscripts and negative numeric subscripts. The $ORDER function thus is the
preferred choice.
The $ORDER function can be used to step through global and routine directories.
When an unsubscripted global variable name is used as an argument to $ORDER,
the system returns the name of the next global in the directory. For routines, a global
name that consists of a space character followed by the routine name as the subscript
(^ (RoutName)) is used. The Direction argument can be specified to scan the routine
and global directories in reverse order.

154 • MSM Functions MSM Language Reference Manual

 Associated Topics
$NEXT Function
$QUERY Function
$ZNEXT Function
$ZORDER Function
$ZPREVIOUS Function
$ZSORT Function

Examples

Setup Value of Function

SET ^A(-1)=0,^A(1,2,3)=1, $ORDER(^A(""))="-1" first node
^A(2)=2,^A(4)=3 $O(^A(-1))="1" second node
$O(^A(1))="2" third node
$O(^A(2))="4" fourth node
$O(^A(4))="" no descendants
$O(^A(1,""))="2" second-node
level
$O(^A(1,2,""))="3" third-node
level
$O(^A(1,2,3,""))="" no fourth
level
SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3 $ORDER(^A(""),-1)="4" last node
$O(^A(4),-1)="2" next last node
$O(^A(2),-1)="1" first node
$O(^A(1),-1)="" no descendants
$O(^A(1,""),-1)="2" second
level
$O(^A(1,2,""),-1)="3" third
level
$O(^A(1,2,3,""),-1)="" no
fourth
level
KILL SET (%A(2),ABC,x)="" $ORDER()="%A"
$O(%A)="ABC"
$O(ABC)="x"
$O(x)=""
$O(^CUST) "HELP"
$O(^ ("%DI")) "%DO"

MSM Language Reference Manual MSM Functions • 155

$PIECE
Returns a substring between two occurrences of a specified Delimiter.

Syntax
$P{IECE}(String,Delimiter{,First{,Last}})

Definition
String Any string-type expression.
Delimiter One or more characters that are delimiters for the substring.
First An integer expression that specifies the starting occurrence of the
substring to retrieve.
Last An integer expression that specifies the ending occurrence of the
substring to retrieve.
The $PIECE function returns one or more substrings that are contained in the String.
The substring may appear none, one, or more non-overlapping times in the String
separated by the Delimiter. The Delimiter may be one or more characters that appear
in the String. Each substring has a unique position relative to the Delimiter in the
String. In the following example, the asterisk (*) character is used as the Delimiter.
ABC*DEF*GHI*JKL

In this case, ABC is the first substring, DEF is the second substring, GHI is the third
substring, and so on. If the Delimiter is not found in the String, the function returns
the entire String. The First argument is used to indicate which substring to retrieve.
When the First argument is not specified, the function returns the first substring.
When the Last argument is specified, all substrings from the First through the Last
are returned. The function returns a null string if the Delimiter is null; the value of
First is greater than the value of Last; the value of Last is less than 1; or there are
less than First -1 non-overlapping occurrences of the Delimiter in the String.
The $PIECE function can appear on either side of the equal sign (=) in the argument
of the SET command. When it appears on the right side of the equal sign, it returns
the specified piece. If it appears on the left side of the equal sign, the specified piece
is replaced by the value to the right of the equal sign. When SET $PIECE notation is
used, the String being set must be a pure variable name. Other expression types are
not allowed.
If the variable being SET does not have enough delimiters to update the appropriate
piece, the $PIECE function pads the variable with additional delimiters as necessary.
If the variable being SET does not exist, it is treated as if it was equal to the null
string.
If the $PIECE function appears on the left side of the equal sign and the delimiter is
null, the following situations occur.
• If both First and Last are less than 1, the value of String remains unchanged.
• If First is less than 1 and it is less than Last, the value of String is replaced by
the value to the right of the equal sign.
• When First is equal to one and Last is less than 1, the value of String remains
unchanged. Otherwise, the value of String is replaced by the value to the right of
the equal sign.

156 • MSM Functions MSM Language Reference Manual

 • When First is greater than 1and Last is greater than or equal to First, the value
to the right of the equal sign is appended to the value of String. Otherwise, the
value of String remains unchanged.

Examples

Setup Value of Function

SET X="ABC*DEF" $PIECE(X,"*")="ABC"
$P(X,"*",1)="ABC"
$P(X,"*",2)="DEF"
$P(X,"*",3)="" (null string)
$P(X_1)="ABC*DEF"
S Y="B" $P(X,Y,1)="A"
$P(X,Y,2)="C*DEF"
S Z="A.B.C.D" $P(Z,".",1)="A"
$P(Z,".",2,3)="B.C"
$P(Z,".",1,100)="A.B.C.D"
$P(Z,".",0)="" (null string)
$P(Z,".",3,2)="" (null string)
$P(Z,"",1,100)="" (null string)
S Z="A.B.C.D",$P(Z,".",2,3)=123 Z="A.123.D"
S Z="A.",$P(Z,".",5)=123 Z="A....123"
K Z S $P(Z,".",5)=3 Z="....3"
S Z="ABC",$P(Z,"",1)=123 Z=123
S Z="ABC",$P(Z,"",2)=123 Z="ABC123"

MSM Language Reference Manual MSM Functions • 157

$QLENGTH
Returns the number of subscripts in a specified Variable name.

Syntax
$QL{ENGTH}(Variable)

Definition
Variable An expression that evaluates to a local or global variable name.
The $QLENGTH function returns an integer value that indicates the total number of
subscripts in a local or global reference. If Variable contains no subscripts, the
function returns zero; otherwise, the function returns the total number of subscripts.

Associated Topics
Variables
$QSUBSCRIPT Function

Examples

Setup Value of Function

SET X="^A" $QLENGTH(X)=0

S X="^A(3)" $QL(X)=1

S X="^A(1,2,3)" $QL(X)=3

S X="" $QL(X)=0

S X="Y",Y="^A(3)" $QL(@X)=1

158 • MSM Functions MSM Language Reference Manual

$QSUBSCRIPT
Returns the value of a specified subscript within a Variable name.

Syntax
$QS{UBSCRIPT}(Variable,Position)

Definition
Variable An expression that evaluates to a local or global variable name.
Position An expression that specifies the position of the subscript in
Variable that is to be returned.
The $QSUBSCRIPT function returns the value of a subscript within Variable that is
specified by Position. If the value of Position is -1, the function returns environment
information if provided in Variable. If the value of Position is 0, the function returns
the local or global name unsubscripted and without environment information. If the
value of Position is greater than the total number of subscripts in Variable, the
function returns a null string.

Associated Topics
Variables
$QLENGTH Function

Examples

Setup Value of Function

SET X="^A(3,5)" $QSUBSCRIPT(X,1)=3
$QS(X,2)=5
$QS(X,-1)=""
$QS(X,0)="^A"
$QS(X,3)=""
S X="^|""MGR,FSA""|A(4,7)" $QS(X,1)=4
$QS(X,2)=7
$QS(X,-1)="MGR,FSA"
$QS(X,0)="^A"
S X="^A(3)",Y="X" $QS(@Y,1)=3
$QS(@Y,-1)=""
$QS(@Y,0)="^A"

MSM Language Reference Manual MSM Functions • 159

$QUERY
Identifies the next or previous subscript, in collating sequence, for a specified
subscripted Variable.

Syntax
$Q{UERY}(Variable{,Direction})

Definition
Variable An expression that evaluates to a subscripted local or global
variable name.
Direction An expression that evaluates to either 1 or -1.
The $QUERY function is used to identify the next or previous node in a local or
global variable that is defined and has data. The Variable name that is specified as an
argument to the function must be a local or global variable, and naked references are
allowed. If Direction is not specified, or if it evaluates to a value of 1, the system
returns the full local or global reference (variable name and subscripts) of the first
node that has data and follows the node specified by the Variable. If there is no node
following the node specified by the Variable reference, the system returns a null
value (""). If Direction is specified and has a value of -1, the system returns either
the previous node or null if there is no previous node. If Direction is specified and
has any value other than 1 or -1, an error condition occurs.

Associated Topics
Variables

Examples

Setup Value of Function

SET ^A(-1)=0,^A(1,2,3)=1, $QUERY(^A)="^A(-1)" first node
^A(2)=2,^A(4)=3 $Q(^A(-1))="^A(1,2,3)" second
node
$Q(^A(1,2,3))="^A(2)" third
node $Q(^A(2))="^A(4)" fourth
node
$Q(^A(4))="" no following node
$Q(^A(4),-1)="^A(2)" previous

160 • MSM Functions MSM Language Reference Manual

$RANDOM
Returns a pseudo-random number in a specified interval.

Syntax
$R{ANDOM}(Integer)

Definition
Integer An integer expression that indicates the interval from which the
random number is generated.
The $RANDOM function returns a random or pseudo-random integer value that is
greater than or equal to 0 and strictly less than Integer. If the value of Integer is
equal to 1, the function returns 0. If the value of Integer is less than 1, an error
condition occurs.

Examples

Setup Value of Function

SET X=$RANDOM(25) X is between 0 and 24
SET X=$R(2) X is either 0 or 1
SET X=$R(1) X is always 0
SET X=$R(-1) An error condition occurs

MSM Language Reference Manual MSM Functions • 161

$REVERSE
Reverses the order of characters in a specified String.

Syntax
$RE{VERSE}(String)

Definition
String A string-type expression.
The $REVERSE function returns a string whose characters are in reverse order of
the characters contained in the specified String. The $REVERSE function is
computationally equivalent to the $$REV(EXPR) extrinsic function that is defined
by the following code.
REV(E) Q $S(E="":"",1:$$REV($E(E,2,$L(E)))_$E(E,1))

Computationally equivalent means that the result of the $REVERSE function is the
same as if the code provided in the $$REV(EXPR) extrinsic function were to be
successfully executed by an M process.

Examples

Setup Value of Function

SET X="ABCDEF" $REVERSE(X)="FEDCBA"
SET X="" $RE(X)=""
SET X=2*64 $RE(X)=821

162 • MSM Functions MSM Language Reference Manual

$SELECT
Returns the value of the first Expression whose truth-valued Condition is true.

Syntax
$S{ELECT}(Condition:Expression{,...})

Definition
Condition A truth-valued expression.
Expression Any type of expression.
The $SELECT function processes the arguments in a left-to-right sequence and
evaluates each Condition until it finds one that is true (its truth-value is 1). If no true
Condition is found, an error occurs. No evaluation of the Expression associated with
the Condition occurs until a true Condition is found. The Expression associated with
the true Condition is then evaluated and returned by the function. No other Condition
or Expression following the true expression is evaluated.

Associated Topics
Truth-Valued Expressions

Examples

Setup Value of Function

SET X=1 $SELECT(X=1:8,2=3:0)=8
$S(X=1:8,2=2:0)=8
$S(X=2:8,2=2:0)=0
$S(X=2:8,2=3:0) error; none true
S Y="B" $S(X=3:8,Y="B":"MSM",X=1:9)="MSM"
$S(X=Y:B(1),Y="A":^(2,3),1:3)=3
The naked indicator is not changed
S ^A(1)="TEST" $S(X=1:^A(1),Y:S)="TEST"
The naked indicator is set to ^A

MSM Language Reference Manual MSM Functions • 163

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

164 • MSM Functions MSM Language Reference Manual

 Associated Topics
$ECODE Special Variable
$ETRAP Special Variable
Error Processing

Examples

Setup Value of Function

$STACK(-1) 10

The current nesting level is 10.

$ST(10,”ECODE") ,M9,Z<DIVER>:::5:2:,M6,Z<UNDEF>:::4:0:,

Both a division by zero and a reference to an undefined local

occurred at the same level. This can happen if the second error
occurred inside the error trap itself.
$ST(10,"MCODE") WRITE !!,A/B

This reprints the line executing when the error occurred.

$ST(10,"PLACE") ERR+5^ERRHAND

The last error occurred five lines past the label ERR in routine
ERRHAND.

MSM Language Reference Manual MSM Functions • 165

$TEXT
Returns the text of a specified line within a routine.

Syntax
$T{EXT}(EntryRef)

Definition
EntryRef A line label or a plus sign followed by a line number, optionally
followed by a circumflex (^) and a routine name.
The $TEXT function returns the text of the line in the routine specified by the
EntryRef argument. The EntryRef can be a line label (for example: ABC), a line label
plus an offset (for example: ABC+5), or an offset of the form +line number (for
example: +6). Optionally, any of these formats can be followed by a circumflex (^)
and a routine name (for example: ABC^MYPROG, ABC+5^CUSTINV,
+6^%STATUS). The returned text is in one of the following forms:
labelSP...SPtext

SP...SPtext
If the specified line reference does not exist or is beyond the last line of the routine,
the function returns a null string. If a routine name is specified and it does not exist,
the function returns a null string. The correct number of space characters is preserved
to match the number entered when the line was created.

Examples

Assume that the following routine is loaded in the partition:

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

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

166 • MSM Functions MSM Language Reference Manual

 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"

MSM Language Reference Manual MSM Functions • 167

$TRANSLATE
Returns a string that was translated according to the specified masks.

Syntax
$TR{ANSLATE}(String,From{,To})

Definition
String Any string-type expression.
From A string-type expression that specifies the characters to be replaced.
To A string-type expression that specifies the replacement characters.
The $TRANSLATE function takes each character from left-to-right in the From
string (the translate from character) and changes each occurrence of that character in
the String to a new character. The first character in From is translated to the first
character in To, the second to the second, the third to the third, and so on. If the
length of the From string is greater than the To string, then any characters in From
which have no corresponding character in To are removed from String. If To is not
specified, every character in From is removed from String. If the length of To is
greater than From, the extra characters in the To string are ignored.

Associated Topics
$LENGTH Function

Examples

Setup Value of Function

$TR("ABCDE","A","X") XBCDE replaces A with X.
$TR("ABCDE","AB","X") XCDE replaces A with X and removes B.
$TR("ABCDE","AB","ab") abCDE replaces A with a and B with b.
S X="A",Y="B",Z="C" Indirection can be used; the code
S A="ABCDE",B="AB",C="ab" returns the string "abCDE."
$TR(@X,@Y,@Z)

168 • MSM Functions MSM Language Reference Manual

$VIEW
Returns the text, hexadecimal, decimal, or binary value of a specified memory
location.

Syntax
$V{IEW}(Address{,Domain{,Length{,Type}}})

Definition
Address An integer expression that is a memory address.
Domain An integer expression that defines the logical type of memory from
which the data is to be retrieved.
Length An integer expression that indicates the number of contiguous
memory locations to be retrieved.
Type An integer expression that indicates the format of the data to be
returned.
The $VIEW function is used to inspect the contents of system memory. The Domain
argument specifies the logical area of memory to be inspected, and the Address
argument specifies the offset into the area in bytes. A Domain of -1, -2, or -3
indicates an absolute real memory address; -4 indicates the constant area within the
Svector; -5 indicates the variable area within the Svector; 0 indicates the view buffer;
and a number greater than 0 indicates a partition (1 is job 1, 2 is job 2, and so on). If
the Domain is not specified, a value of -3 is assumed.
The Length argument specifies the number of bytes to retrieve. If it is omitted, a
length that corresponds to the natural word size of the machine being used is
assumed. The Type argument indicates the format in which the data is to be returned.
A value of 0 indicates decimal, 1 indicates string, 2 indicates hexadecimal, and 3
indicates binary. If omitted, a decimal value is assumed.

Considerations
When the default values for Length are used, the code may not be portable between
different implementations of MSM because the natural word sizes are different.

Associated Topics
Special Variables

MSM Language Reference Manual MSM Functions • 169

 Examples

Setup Value of Function

SET X=$VIEW(100,-3,2,0) Sets X to the decimal value of the two consecutive
locations of memory starting at location 100.
W $V(1,0,1) Writes the decimal value of the second byte of the View
buffer to the current device.
I $V(44,2,2,2)="3DF0" Tests location 44 of Job 2's partition vector for the
hexadecimal value "3DF0".
S X=$V(108,$J,4) Location 108 in the partition vector of the current job.
S X=$V(168,-4,2) A two-byte field at offset 168 in the svector.
S X=$V(1022,0,2) Last two bytes of the system View buffer in decimal.

170 • MSM Functions MSM Language Reference Manual

$ZASCII
Returns the internal value (the Unicode character code) of a specified character. This
differs from $ASCII, which returns the programmer character set value (the JIS90
character code).

1RWH This function applies only to double-byte or wide character sets.

Syntax
$ZAS{CII}(String{,Position})

Definition
String Any string-type expression.
Position An integer expression that indicates the relative position of a character
within the String.
The $ZASCII function returns an integer value that is the Unicode code of the
specified character. The Position argument works the same as in $ASCII; it refers to
a Position of a character in the String.

Examples
If you set X using the JIS90 code #2121 (double-byte space):

SET X=$CHAR(#2121)

Internally, a double-byte space is represented in Unicode as #3000 or decimal 12288:

WRITE $ZHEX($ZASCII(X))
3000

Associated Topics
$ASCII Function
$CHAR Function
$ZCHAR Function

MSM Language Reference Manual MSM Functions • 171

$ZBN
Returns the starting block number for a routine or a global, allocates a disk block, or
deallocates a disk block.

Syntax
$ZBN(Name)
$ZBN("",Block{,Owner{,VolNum}}})

Definition
Name A routine name or a global variable name.
Block An integer expression that indicates a disk block number.
Owner An integer expression that specifies the UCI index number of the
owner, 255 to indicate a system-owned block, or 254 to indicate a
non-database block, and so on.
VolNum An integer expression that specifies the index number of the volume
group.
The $ZBN function returns the starting block number (the disk address of the highest
level pointer block) for a specified global variable or the block number of a routine's
header block. The global variable name must be unsubscripted and preceded by a
circumflex (^). For routine names, a circumflex followed by a space and the name in
parenthesis (for example, ^ ("MYPROG")) is used to indicate that the Name is a
routine.
If the Name argument is "", the system allocates or deallocates the disk block. If
Block is greater than zero, the system searches for a free disk block and allocates the
first free block that is found. The search for a free block begins with the map block
specified by the Block argument.
When the allocation is done within the current UCI (the Owner parameter is not
specified on the $ZBN function), the block is allocated within the limits of the
expansion pointers for the current UCI. If the VolNum parameter is specified, the
system allocates the specified block within the specified volume group. Otherwise, it
allocates the block within the current volume group.
If the Block number is less than zero, the system deallocates the specified block.
When a block is deallocated, the Owner parameter is ignored. However, the VolNum
parameter is honored. For both allocation and deallocation of blocks, the system
always returns the number of the affected Block. For deallocation of blocks, this
number is negative.

Associated Topics
MSM Structured System Variables

172 • MSM Functions MSM Language Reference Manual

 Examples

Setup Value of Function

$ZBN(^SSN) Returns block number of SSN global.
$ZBN(^ ("WP")) Returns block number of WP routine.
$ZBN("",2) Allocates a block, beginning the search from map number 2.
$ZBN("",2048,255,1) Allocates a block as a system owned block on volume group
1, beginning the search from map number 2048.

MSM Language Reference Manual MSM Functions • 173

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

174 • MSM Functions MSM Language Reference Manual

 $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

MSM Language Reference Manual MSM Functions • 175

 Examples

Setup Value of Function

$ZBSTR(32,0) Returns a string of 32 bits initialized to 0.
$ZBSET(X,16,1) Sets the sixteenth bit in the X string to a 1.
$ZBCOUNT(X,1) Counts the number of 1 bits in the string in X.
$ZBLEN(X) Counts the number of bits in the string in X.
$ZBAND(X,Y) ANDs the string in X with the string in Y.
$ZBNOT(X) Inverts all of the bits in the string in X.
$ZBFIND(X,1) Finds the first 1 bit in the string in X.
$ZBLEN($ZBSTR(31)) Returns a value of 32.

176 • MSM Functions MSM Language Reference Manual

$ZBOOLEAN
Returns a value that is the result of a specified Boolean operation applied to two
arguments.

Syntax
$ZB{OOLEAN}(Exp1,Exp2,Mask)

Definition
Exp1 Any expression.
Exp2 Any expression.
Mask An integer expression that identifies the Boolean operation to be
performed.
The $ZBOOLEAN function performs a bit-by-bit logical operation specified by the
Mask on the Exp1 and Exp2 arguments. The Boolean operation is specified by a
bit-mask that corresponds to the four possible states of two binary bits. The
following table shows the possible states and the corresponding Mask value that
selects each state.
=%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 the values from the above table, the value of Mask can range from 0 to
15, inclusive. If any of the states specified by the Mask is true, then the
corresponding bit in the returned value is set to 1. Otherwise, the bit in the returned
value is 0. The following table illustrates all of the possible Mask settings and their
associated logical operations.
=%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)

MSM Language Reference Manual MSM Functions • 177

 Mask $ZBOOLEAN(A,B,Mask)
9 ¬ (A ⊗ B) ≅ ¬A ⊗ ¬B
10 ¬B
11 A ∨ ¬B
12 ¬A
13 ¬A ∨ B
14 ¬ (A ∧ B) ≅ ¬A ∨ ¬B
15 1

Logical AND ∧ Logical NOT ¬

Logical OR ∨ Identically Equal ≅
Exclusive OR ⊗
Although all data in MSM can be thought of as strings, the $ZBOOLEAN function is
sensitive to the internal format used to store the values. The operation of
$ZBOOLEAN is only defined for the following two cases.
For operations on numeric values, both Expressions must be integers in the range
2147483648 through 2147483647, inclusive. The result also is a numeric value
within that range. When either Expression is an MSM variable or an expression that
evaluates to a string value (such as $PIECE or concatenation), the unary + operator
should be used to ensure that the expression is interpreted as numeric.
For operations on strings, both Expressions must be strings. The result will be a
string whose length is equal to the length of Exp1. The operation is performed on the
first character of Exp1 and the first character of Exp2, then the second characters,
and so on for the entire length of Exp1. If Exp2 is shorter than Exp1, then Exp2 is
reused from the first character as many times as necessary. If Exp2 is longer than
Exp1, then the extra characters are ignored.
For string operations on double-byte implementations of MSM, the $ZASCII values
of the characters in the strings are used instead of the $ASCII values. This usage is
shown in example 9 below.

Associated Topics
$ZBname function
Hexadecimal operator
PLUS operator

Examples
1. SET X=#8F (or S X=143)
S X=$ZBOOLEAN(+X,#80,1)
Result: X=128, $ZHEX(X)="80"

All of the low-order bits are "ANDed" off.

2. S X=#9F
S X=$ZB(+X,1+2+4+8,1)
Result: X=15, $ZH(X)="F"

All bits except for the four low-order bits are "ANDed" off.

178 • MSM Functions MSM Language Reference Manual

 3. S X="143"
S X=$ZB(X,#F,1)
Result: X=$CHAR(1,0,0)
S X=$ZB(+X,#F,1)
Result: X=15, $ZH(X)="F"

In the first case, because Exp1 is a string and Exp2 is a number, the result is not
as expected. To eliminate the ambiguity for numbers that might be stored
internally as strings, always use the unary PLUS operator to force numeric
interpretation of variables and other expressions.

4. S X=#40 (or S X=64)

S X=$ZB(X,#20,7)
Result: X=96, $ZHEX(X)="60"

The OR operation is used to turn on the bits in Exp1 that are specified in Exp2.

5. S X=#60 (or S X=96)

S X=$ZB(X,#20,2)
Result: X=64, $ZHEX(X)="40"

Any bits that are on in both Exp1 and Exp2 are turned off in the result. This
operation is used to turn off the bits in Exp1 that are specified in Exp2.

6. S X=64
S Y=32 (or S Y=#20)
S X=$ZB(X,Y,6)
Result: X=96
S X=$ZB(X,Y,6)
Result: X=64

The Exclusive OR operation can be used to toggle a bit on and off.

The following two examples illustrate the use of character strings.

7. S X=$C(1,2,3),Y=$C(128)
S X=$ZB(X,Y,7)
Result: X=$C(#81,#82,#83)

In this code, a logical OR is used to turn on the high-order bit in each character
of a three-character string.

8. S X=$C(1,2,3,4,5,6),Y=$C(255,0)
S X=$ZB(X,Y,1)
Result: X=$C(1,0,3,0,5,0)

This example turns off all the bits in every second character of Exp1, and does
not change the value of the other characters.

9. S X=$ZCHAR(160,161,162,163)
S X=$ZB(X,$ZCH(1),7)
Result: X = $ZCH(161,161,163,163)

This example turns on the low-order bit of every character of Exp1. On a

double-byte implementation of MSM, it uses the internal numeric value of each
character without interpreting it as a character of the programmer character set.

MSM Language Reference Manual MSM Functions • 179

$ZCALL
Calls an external routine to perform a user-defined function.

1RWH Although $ZCALL has been superseded by the ANSI standard External Call
syntax, support for $ZCALL is still provided.

Syntax
$ZC{ALL}(Function{,Parm, ... , Parm})

Definition
Function The name of the function to be called. This is the function’s actual
name without quotation marks.
Parm One or more parameters to be passed to the function.
The $ZCALL function is used to call an external, user-supplied routine to perform an
operation. This function is provided for backward compatibility. It has been
superseded by the new external routine call syntax.

Examples

Setup Value of Function

$ZCALL(CUBEROOT,9.75314) Calls an external routine to compute a cube root.

$ZCALL(PORTIN,280) Calls an external routine to READ a character.

$ZCALL(LIGHTPEN,30) Calls an external routine to wait up to 30 seconds for the

lightpen to be pressed.

180 • MSM Functions MSM Language Reference Manual

$ZCHAR
Given a list of internal character-codes (Unicode codes), returns a string of
characters.

1RWH This function applies only to double-byte or wide character sets.

Syntax
$ZCH{AR}(Codepoint{,...})

Definition
Codepoint An internal character-code (an integer).
The $ZCHAR function is similar to the $CHAR function except that the arguments
are Unicode codes rather than the external (programmer) character set.

Associated Topics
$ASCII Function
$CHAR Function
$ZASCII Function

Examples
In the following examples, the symbol ❖ represents a double-byte character where
the internal code is #751F, corresponding to external code #4038.
WRITE $ZCHAR(#751F) → ❖ because #751F is the Unicode code point of ❖.
WRITE $CHAR(#4038) → ❖ because #4038 is the external code point of ❖.

MSM Language Reference Manual MSM Functions • 181

$ZCRC
Returns a computed checksum or cyclic redundancy check (CRC) of a string.

Syntax
$ZCR{C}(String{,Type{,Initvalue}})

Definition
String Any string-type expression.
Type An integer expression that indicates the type of checksum to be
performed on the string. The default value is 0 (Exclusive OR).
Initvalue An integer expression that is added to the result of the CRC
calculation (only valid for types 5, 6, and 32).
The $ZCRC function computes six types of checksums: two variations of exclusive
OR, ASCII summation, two variations of 16-bit CRC, and 32-bit CRC.
&KHFNVXP 7\SHV

Type Checksum
0 Exclusive OR
1 ASCII summation
5 16-bit CRC (DTM-compatible)
6 16-bit CRC (DSM-compatible)
7 XOR the internal byte-stream
32 32-bit CRC

Type 0 selects an Exclusive OR calculation which returns a value that is cumulative

for the entire String. The second character is XORed to the first, then the third
character is XORed to the result of the first operation, then the fourth character is
XORed, and so on.
Type 1 selects an ASCII summation that is calculated by adding together the decimal
values of each ASCII character in the String.
Types 5 and 6 select two different 16-bit CRC computations. The type 5 CRC is the
same as the 16-bit CRC performed by the DTM function with the same syntax. The
type 6 CRC is the same as the one performed by the VAX-DSM $ZCRC function.
These options are useful for writing data transfer programs that must communicate
with either of these M implementations.
Type 7 (like Type 0) selects an exclusive OR calculation which returns a value that is
cumulative for the entire String, but unlike Type 0, this computation operates on the
individual bytes of the string. For single-byte versions of MSM, Types 0 and 7 are
equivalent. For double-byte versions of MSM, Type 0 operates on the two-byte
characters of the string, returning a value between 0 and 65,535 (0xFFFF), whereas
Type 7 operates on individual bytes, returning a value between 0 and 255 (0xFF).
Type 32 selects a 32-bit CRC computation that is unique to MSM.

182 • MSM Functions MSM Language Reference Manual

 The parameter Initvalue, which defaults to 0, represents the starting value of the
CRC. It is used when the CRC is generated on multiple pieces of a string. For
example, if the string is too long to fit in a single variable, it can be segmented into
multiple variables. The Initvalue then can be used to calculate a CRC as if the
segments were all concatenated. The last example illustrates this feature.

Associated Topics
$ASCII Function

Examples

Setup Value of Function

SET X="ABCDE" $ZCRC(X)=65
$ZCR(X,0)=65
$ZCR(X,1)=335
$ZCR(X,5)=14362
$ZCR(X,6)=20523
$ZCR(X,32)=-1907187440
S Y="123456" $ZCRC(Y,0)=7
$ZCR(Y,1)=309
$ZCR(Y,5)=4605
$ZCR(Y,6)=10724
$ZCR(Y,32)=494219010
S X="ABCDE",Y="123456" $ZCR(X_Y,6)=15906
$ZCR(Y,6,$ZCR(X,6))=15906

MSM Language Reference Manual MSM Functions • 183

$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.
2/( QRWH If an object has registered itself as a single-instance object (for example:
the Word.Basic object in Microsoft Word 6.0), only one instance of the object is
created, no matter how many times $ZCREATEOBJECT is invoked.

Associated Topics
SET Command
ZSETOBJ Command
$ZGETOBJECT Function
$ZOBJREFERENCE Function

Examples

M Code Description
ZSET X=$ZCRE("word.Basic") Creates a Word 6.0 document object.
I $ZOBJREF(X)=0 G ERROR Ensures allocation succeeded.
D X.Insert="Hello World" Inserts a line.
D X.FileSaveAs="C:\hello.doc" Saves the file.

184 • MSM Functions MSM Language Reference Manual

$ZDATE
Returns the external representation of a date by converting it from its internal
$HOROLOG format.

Syntax
$ZD{ATE}(Integer{,Type{,Flag}})

Definition
Integer An integer expression that is in $HOROLOG format.
Type An integer expression that indicates the format for the external date.
Flag An integer expression that indicates whether the century should always be
included.
The $ZDATE function converts the Integer value, which is assumed to be the
number of days since December 31, 1840, to an external date format. The external
form is determined by the value of the Type argument. Type has the following
meanings.
1 MM/DD/YY where MM is the month, DD is the day, and YY is the year.
2 DD MMM YY where DD is the day, MMM is the three-character
abbreviation for the month, and YY is the year.
3 DD/MM/YY is the European form of the date, where DD is the day, MM
is the month, and YY is the year.
If the Type is omitted, a value of 1 is assumed. If the year is in the current century,
the century is not included unless Flag has a value of 1.

Associated Topics
$HOROLOG Special Variable

Examples

Setup Value of Function

SET X=2 $ZDATE(X)="01/02/1841"
$ZD(X,1)="01/02/1841"
$ZD(X,2)="02 JAN 1841"
$ZD(X,3)="02/01/1841"
S X=53137 $ZD(X)="06/26/86"
$ZD(X,1)="06/26/86"
$ZD(X,2)="26 JUN 86"
$ZD(X,3)="26/06/86"
$ZD(X,3,1)="26/06/1986"

MSM Language Reference Manual MSM Functions • 185

$ZDEVICE
Returns the external device name of a terminal device connected to the system.

Syntax
$ZDEV{ICE}(Integer)

Definition
Integer An integer expression that evaluates to a device number.
The $ZDEVICE function returns the external name of a terminal port. The Integer
value that is specified is the actual MSM device number. If the device does not have
an external name, the device number is returned.
For LAT ports, the external name is the port name and the LAT server name in the
form port@server. Note that for PC LAT emulating software, the port name is
typically equal to the null string.
For Telnet ports (MSM-Server for Windows only), $ZDEVICE returns the IP host
name, the IP port number, and the IP address, separated by the tilde (~) character. If
the host name is not known, the IP address is returned in its place.
For UNIX ports, the external name is the UNIX tty name.

Associated Topics
$PRINCIPAL Special Variable
$IO Special Variable
Using Peripheral Devices, MSM User's Guide

Examples

Setup Value of Function

WRITE $ZDEVICE(64) PORT_1@LABSERVER

W $ZDEV($IO) @PC_0204F83F100A

W $ZDEV($PRINICAL) Fredspc~3087~161.201.2.3

W $ZDEV(3) 3

186 • MSM Functions MSM Language Reference Manual

$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.
2/( QRWH If an object has registered itself as a single-instance object (for example:
the Word.Basic object in Microsoft Word 6.0), only one instance of the object is
created, no matter how many times $ZGETOBJECT is invoked.

Associated Topics
SET Command
ZSETOBJ Command
$ZCREATEOBJECT Function
$ZOBJREFERENCE Function

MSM Language Reference Manual MSM Functions • 187

 Examples

Setup Description
ZSET X=$ZGETO("c:\cad\schema.cad") Instantiates an object in schema
file.
ZSET X=$ZGETO("c:\cad\schema.cad!Layer3") Activates layer 3 within the schema
file.
ZSET X=$ZGETO("d:\drawings\ 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.

188 • MSM Functions MSM Language Reference Manual

$ZHEX
Returns the decimal value of a hexadecimal number or the hexadecimal value of a
decimal number.

Syntax
$ZH{EX}(Expression)

Definition
Expression An expression that evaluates to a string or an integer.
The $ZHEX function converts a hexadecimal value to decimal or a decimal value to
hexadecimal. If the Expression evaluates to a string, then the conversion is from
hexadecimal to decimal. If the Expression evaluates to an integer, then the
conversion is from decimal to hexadecimal.

Considerations
When converting from hexadecimal to decimal, the string may contain numbers from
0 through 9 and letters from A through F in uppercase, lowercase, or a mixture of the
two; otherwise, the function returns 0.

Associated Topics
HEXADECIMAL Operator

Examples

Setup Value of Function

$ZHEX("F") Returns 15, the decimal value.
$ZH(15) Returns "F", the hexadecimal value.
$ZH($ZH(20)) Returns 20, the original value.
$ZH(20) Converts a decimal to a hexadecimal value of 14 (argument is
evaluated as an integer).
$ZH("20") Converts a hexadecimal to a decimal value of 32 (argument is
evaluated as a string).

MSM Language Reference Manual MSM Functions • 189

$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)
by Year (two digits, padded with space)
y Year (two digits if within current century, otherwise four digits)
mm Numeric month of year (zero-padded to two digits)
bm Numeric month of year (blank-padded to two characters)
m Numeric month of year (no padding)
dd Day of month (zero-padded to two digits)
bd Day of month (blank-padded to two characters)
d Day of month (no padding)
ww Week of year (zero-padded to two digits)
bw Week of year (blank-padded to two characters)
w Week of year (no padding)
jjj Julian day of the year (zero-padded to three digits)
bjj Julian day of the year (blank-padded to three characters)
j Julian day of the year (no padding)
MONTH Full spelling of month name (all uppercase)
Month Full spelling of month name (leading uppercase)
month Full spelling of month name (all lowercase)
MON Three-letter month abbreviation (all uppercase)

190 • MSM Functions MSM Language Reference Manual

 Format Resulting Value
Mon Three-letter month abbreviation (leading uppercase)
mon Three-letter month abbreviation (all lowercase)
DAY Full spelling of day-of-week name (all uppercase)
Day Full spelling of day-of-week name (leading uppercase)
day Full spelling of day-of-week name (all lowercase)
DY Three-letter abbreviation for day-of-week name (all uppercase)
Dy Three-letter abbreviation for day-of-week name (leading uppercase)
dy Three-letter abbreviation for day-of-week name (lowercase)
-1 Microsoft Windows NT only: Date in long format
-2 Microsoft Windows NT only: Date in short format

The following token strings apply to time formatting and are only valid when Type is
two. Different cases produce different results.
7LPH )RUPDW 6WULQJV

Format Resulting Value

HH Hour of day, 24-hour clock (zero-padded to two digits)
bH Hour of day, 24-hour clock (blank-padded to two characters)
H Hour of day, 24-hour clock (no padding)
hh Hour of day, 12-hour clock (zero-padded to two digits)
bh Hour of day, 12-hour clock (blank-padded to two characters)
h Hour of day, 12-hour clock (no padding)
mm Minute of hour (zero-padded to two digits)
bm Minute of hour (blank-padded to two characters)
m Minute of hour (no padding)
ss Second of minute (zero-padded to two digits)
bs Second of minute (blank-padded to two characters)
s Second of minute (no padding)
.nnn… Fraction of second (the number of n characters specifies
precision)
p am or pm (lowercase)
P AM or PM (uppercase)
-1 Microsoft Windows NT only: Time format
-2 Microsoft Windows NT only: Time format, without the
seconds portion

$H_Value The M internal $HOROLOG number for the date or time to be

formatted. For a date, $H_Value is the first part of the $HOROLOG
system variable; for a time, $H_Value is the second part of
$HOROLOG. If no $H_Value is supplied, the system assumes the
current date or time value of $HOROLOG when the function is
executed.

MSM Language Reference Manual MSM Functions • 191

 Associated Topics
ZHOROLOG Command
$HOROLOG Special Variable
$ZDATE Function

Examples

Setup Value of Function

Dates:
$ZHL(1,”dd-MON-yy”,56690)) 18-MAR-96

$ZHL(1,”Day, Month d, yyyy”, Monday, March 18, 1996

$P($H,”,”,1)) (today’s date)

$ZHL(1,”dd-Mon-yyyy”,56678) 06-Mar-1996

Times:
$ZHL(2,"h:mm P",70000) 7:26 PM

$ZHL(2,"H:mm",70000) 19:26

$ZHL(2,"hh:mm:ss p",67678) 06:47:58 pm

$ZHL(2,"bH:mm:ss.nn") 9:21:43.00
(current time)

$ZHL(2,"HH:mm",$P($H,",",2)) 09:21 (current time)

192 • MSM Functions MSM Language Reference Manual

$ZNEXT
Identifies the next or previous node, in collating sequence, for a specified subscripted
variable.

Syntax
$ZN{EXT}(Variable{,Direction})

Definition
Variable An expression that evaluates to a subscripted local or global variable
name.
Direction An expression that evaluates to either 1 or -1.
The $ZNEXT function is used to identify the next or previous node in a local or
global variable that is defined and has data. The Variable name that is specified as an
argument to the function must be a local or global variable, and it must be a full
reference. If Direction is not specified or if it evaluates to a value of 1, the system
returns the full local or global reference (variable name and subscripts) of the first
node that has data and follows the node specified by the Variable. If there is no node
following the node specified by the Variable reference, the system returns a value of
-1. If Direction is specified and has a value of -1, the system either returns the
previous node or -1 if there is no previous node. If Direction is specified and has any
value other than 1 or -1, an error condition occurs.
The $ZNEXT and $ZORDER functions perform identical operations. The only
difference is in the starting and ending values of the functions. In the case of
$ZNEXT, the starting and ending value is -1. For $ZORDER, the null value is used
to indicate the starting and ending points. The $ZNEXT and $QUERY also are
identical except for the reason identified above.

Associated Topics
Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZORDER Function

Examples

Setup Value of Function

SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3 $ZNEXT(^A(-1))="^A(1,2,3)" first
node
$ZN(^A(1,2,3))="^A(2)" second node
$ZN(^A(2))="^A(4)" third node
$ZN(^A(4))=-1 no descendants
$ZN(^A(4),-1)="^A(2)" previous node
$ZN(^A(-1),-1)="^A(4)" last node

MSM Language Reference Manual MSM Functions • 193

$ZOBJREFERENCE
Identifies whether an expression refers to an object and whether two expressions
refer to the same object.

Syntax
$ZOB{JREFERENCE} (Expression{,Expression})

Definition
Expression Any M expression.
The $ZOBJREFERENCE function is used to test whether a local variable contains
an object reference or a non-object value. It also can be used to test whether two
local variables both contain a reference to the same object.
If only one variable is specified, the function returns a value as follows according to
the type of data stored in the variable passed to it. If the variable contains an object
reference, it returns one (1). If the variable contains a reference to the "null" or
"nothing" object, it returns minus one (-1). If the variable is a local or global node
with data, the function returns zero (0). Otherwise, an <UNDEF> error is raised
because $DATA(glvn)#10=0.
$ZOBJREFERENCE(glvn) is TRUE when glvn contains an object reference;
otherwise, it is FALSE. The exact return value of $ZOBJREFERENCE(glvn) is
relevant only if a null object reference can arise; for example, when an object's
method enumerates other objects (similar to $ORDER on an M array). The end of
the enumeration generally is signaled by the return of a null object reference.
The existence of an object reference in a variable does not guarantee the existence of
the object. Attempts to manipulate its properties or perform its methods will fail if
the object has ceased to exist.

Associated Topics
ZSETOBJ Command
$ZCREATEOBJECT Function
$ZGETOBJECT Function

Examples

Setup Value of Function

ZSET A=$$FUNC(PARM) 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.

194 • MSM Functions MSM Language Reference Manual

$ZORDER
Identifies the next node, in collating sequence, for a specified subscripted variable.

Syntax
$ZO{RDER}(Variable{,Direction})

Definition
Variable An expression that evaluates to a subscripted local or global
variable name.
Direction An expression that evaluates to either 1 or -1.
The $ZORDER function is used to identify the next or previous node in a local or
global variable that is defined and has data. The Variable name that is specified as an
argument to the function must be a local or global variable and it must be a full
reference. If Direction is not specified or if it evaluates to a value of 1, the system
returns the full local or global reference (variable name and subscripts) of the first
node that has data and follows the node specified by the Variable. If no node follows
the node specified by the Variable reference, the system returns a value of null ("").
If Direction is specified and has a value of -1, the system either returns the previous
node or null if there is no previous node. If Direction is specified and has a value
other than 1 or -1, an error condition occurs.
The $ZORDER and $ZNEXT functions perform identical operations. The only
difference is the functions' starting and ending values. For $ZORDER, the starting
and ending value is null. For $ZNEXT, a -1 value specifies the starting and ending
points. The $ZORDER and $QUERY functions are identical.

Associated Topics
Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZNEXT Function

Examples

Setup Value of Function

SET ^A(-1)=0,^A(1,2,3)=1, $ZORDER(^A(""))="^A(-1)" first
^A(2)=2,^A(4)=3 node
$ZO(^A(-1))="^A(1,2,3)" second
node
$ZO(^A(1,2,3))="^A(2)" third node
$ZO(^A(2))="^A(4)" fourth node
$ZO(^A(4))="" no descendants
$ZO(^A(4),-1)="^A(2)" previous
$ZO(^A(""),-1)="A(4)" last node

MSM Language Reference Manual MSM Functions • 195

$ZOS
The $ZOS function allows the programmer to invoke the more commonly used
Windows functions from within an M program. All $ZOS functions share a common
format and similar behavior.

Syntax
$ZOS(OptNum{,Opt1{,Opt2{,Opt3}}})

Definition
OptNum An integer expression that indicates the Windows function to be
performed.
Opt1 An optional parameter whose format and contents are specific to the
Windows function that the system is performing.
Opt2 An optional parameter whose format and contents are specific to the
Windows function that the system is performing.
Opt3 An optional parameter whose format and contents are specific to the
Windows function that the system is performing.
If the $ZOS function fails, it returns a negative error number, where the error number
is the return code received from the corresponding Windows system function.
Common error codes that can be received are described later in this section.
The following subsections describe the Windows functions that can be invoked from
MSM, the parameters that must be supplied for each function, and the value returned
upon successful completion of the function.

Set Current Drive

This function sets the current drive in Windows. The value is changed in Windows
so that future file references can use this drive as the default drive. This affects the
Host File Server (HFS) in MSM as well as other $ZOS functions.

Syntax
$ZOS(1,DriveID)
DriveID is a single letter (uppercase or lowercase), optionally followed by a colon
(:).
The following example illustrates this function.
$ZOS(1,"A") Sets default drive to A
$ZOS(1,"a") Sets default drive to A
$ZOS(1,"C:") Sets default drive to C
If the function is successful, it returns 0; otherwise, it returns -errorno to indicate an
error.

196 • MSM Functions MSM Language Reference Manual

 Delete a File
This function deletes a file from the Windows file system. File attributes are honored
by the system so that read-only files cannot be deleted. This function is equivalent to
the ERASE command in Windows.

Syntax
$ZOS(2,FileName)
FileName is the name of the file to be deleted and can include a DriveID and a
directory path.
The following example illustrates this function.
$ZOS(2,"MYFILE") Deletes MYFILE
$ZOS(2,"a:\myfile.dat") Deletes myfile.dat on a:
$ZOS(2,"C:\UTL\XYZ") Deletes \UTL\XYZ on C:
If the function is successful, it returns 0 to indicate the file was deleted. Otherwise,
the function returns an error code of -2 to indicate file not found, -3 to indicate path
not found, or -5 to indicate that access was denied.

1RWH Unpredictable results can occur if the MSM database files that the system is
using are deleted.

Rename a File
This function renames a file within the Windows file system. File attributes are
honored by the system so that read-only files cannot be renamed. This function is
equivalent to the RENAME command in Windows.

Syntax
$ZOS(3,OldFileName,NewFileName)
OldFileName is the name of the file to be renamed. OldFileName optionally can
include a DriveID and a directory path.
NewFileName is the new name of the renamed file. NewFileName optionally can
include a directory path. If a specified path is different than the path supplied or
implied in the OldFileName, the file is moved to the new directory. If a DriveID is
specified, it must be the same as the DriveID associated with OldFileName.
The following example illustrates this function.
$ZOS(3,"FILE.DAT","FILE.BAK") Renames file to .BAK file
$ZOS(3,"\UTL\PROG","\OLD\PROG") Moves PROG file
$ZOS(3,"C:\ABC","C:\XYZ") Renames ABC on C:
If the function is successful, it returns 0 to indicate the file was renamed. Otherwise,
the function returns an error code of -2 to indicate file not found, -3 to indicate path
not found, -5 to indicate that access was denied, or -17 if files are not on the same
device.

1RWH Unpredictable results can occur if the MSM database files the system is using
are renamed.

MSM Language Reference Manual MSM Functions • 197

 Get Windows Version Number
This function returns the internal version number of Windows that is currently
running on the system. It returns a string in the form major.minor, in which major is
the major release number, and minor is the minor sub-release number. In
MSM-PC/PLUS, it returns the Microsoft DOS version number.

Syntax
$ZOS(4)
This function does not require any parameters.
The following example illustrates this function.
$ZOS(4) Returns 3.50 for Windows NT Version 3.5
$ZOS(4) Returns 4.0 for Windows NT Version 4
The function is always successful and always returns a string value.

Set File Attributes

This function sets the attributes for a specified file. Any combination of valid
attributes (read-only, hidden, system, or archive) can be specified on the function.
No equivalent command exists in Windows.

Syntax
$ZOS(5,FileName,Attributes)
FileName is the name of the file whose attributes are to be changed. FileName
optionally can include a DriveID and a directory path.
Attributes is a numeric expression that specifies the file's attributes. Acceptable
values are 32 for archive, 4 for system, 2 for hidden, and 1 for read-only. These
values can be added together to combine attributes (6 for hidden and system).
The following example illustrates this function.
$ZOS(5,"XYZ",32+1) Makes XYZ read-only and archive
$ZOS(5,"A:\ABC",2+4) Makes ABC a hidden and system file
$ZOS(5,"\UTL\COPY",1) Makes \UTL\COPY read-only
If the function is successful, it returns a null string to indicate that the attributes were
changed. Otherwise, the function returns an error code of -2 to indicate file not
found, -3 to indicate path not found, or -5 to indicate that access was denied.

Create a New Directory

This function creates a directory node in Windows and is equivalent to the MKDIR
command in Windows.

Syntax
$ZOS(6,DirectoryName)
DirectoryName is the name of the directory to be created. DirectoryName optionally
can include a DriveID and a directory path.

198 • MSM Functions MSM Language Reference Manual

 The following example illustrates this function:
$ZOS(6,"UTL") Creates UTL directory.
$ZOS(6,"A:\USR") Creates USR directory on A.
$ZOS(6,"\TST\DIR") Creates TST\DIR directory.
If the function is successful, it returns a null value to indicate that the directory was
created. Otherwise, the function returns an error code of -3 to indicate path not found
or -5 to indicate that access was denied.

Remove an Existing Directory

This function removes a directory node in the tree-structured file system of
Windows. This function is equivalent to the RMDIR command in Windows.

Syntax
$ZOS(7,DirectoryName)
DirectoryName is the name of the directory to be removed. Optionally, it can include
a DriveID and a directory path.
The following example illustrates this function.
$ZOS(7,"UTL") Removes UTL directory $ZOS
$ZOS(7,"A:\USR") Removes USR directory on drive A
$ZOS(7,"\TST\DIR") Removes TST\DIR directory
If the function is successful, it returns 0 to indicate the directory was removed.
Otherwise, the function returns an error code of -3 to indicate path not found, -5 to
indicate that access was denied, or -16 to indicate that the specified DirectoryName
is the current directory.

Change Current Directory

This function sets the current or default directory in Windows and is equivalent to
the CD command in Windows.

Syntax
$ZOS(8,DirectoryName)
DirectoryName is the name of the directory to be changed. DirectoryName
optionally can include a DriveID and a directory path.
The following example illustrates this function.
$ZOS(8,"TEST") Makes TEST the current directory
$ZOS(8,"C:\A\B\C") Makes C:A\B\C the current directory
$ZOS(8,"\OLD\DIR") Makes \OLD\DIR the current directory
If the function is successful, it returns 0 to indicate that the directory was changed.
Otherwise, the function returns an error code of -3 to indicate path not found, or -5 to
indicate that access was denied.

MSM Language Reference Manual MSM Functions • 199

 Get Drive Parameters
This function retrieves selected information about the specified disk device.

Syntax
$ZOS(9,DriveId)
DriveId is a single letter (uppercase or lowercase), as an option followed by a colon
(:). A null value may be specified to indicate the current default drive.
The following examples illustrate this function.
$ZOS(9,"") Returns values for current drive
$ZOS(9,"a") Returns values for drive A
$ZOS(9,"C:") Returns values for drive C
If the function is successful, it returns a string in the form of N1^N2^N3^N4 where
N1 is the number of sectors per cluster, N2 is the number of available allocation
clusters, N3 is the number of bytes per sector, and N4 is the number of clusters per
drive. Otherwise, the function returns an error code of -1 to indicate an invalid drive
was specified.

Get File Attributes

This function returns the attributes for a specified file in Windows. There is no
equivalent command in Windows.

Syntax
$ZOS(10,FileName)
FileName is the name of the file whose attributes are to be reported. FileName
optionally can include a DriveID and a directory path.
The following examples illustrate this function.
$ZOS(10,"MYPROG") Returns attributes for MYPROG
$ZOS(10,"A:\TEST") Returns attributes for A:TEST
$ZOS(10,"\NEW\FILE") Returns attributes for \NEW\FILE
If the function is successful, it returns a numeric value that corresponds to the file's
attributes. Individual attributes are 2048 for compressed, 256 for temporary, 128 for
normal (no other attributes), 32 for archive, 16 for directory, 4 for system, 2 for
hidden, and 1 for read-only. These values are added together when more than one
attribute exists for a file (6 for hidden and system). Otherwise, the function returns
an error code of -2 to indicate file not found, -3 to indicate path not found, or -5 to
indicate that access was denied.

200 • MSM Functions MSM Language Reference Manual

 Get Current Directory for Drive
This function returns the current default directory for the specified drive. There is no
equivalent command in Windows.

Syntax
$ZOS(11[,DriveID])
DriveID is a single letter (uppercase or lower case), optionally followed by a colon
(:). If DriveID is omitted, the complete current directory, including the drive ID, is
returned.
The following example illustrates this function.
$ZOS(11,"C") Returns the default directory for C
$ZOS(11,"C:") Returns the default directory for C
$ZOS(11) Returns the full current directory
If the function is successful, it returns a string that contains the full path name to the
directory. If DriveID was specified, the string does not include the DriveID. If an
invalid DriveID was specified, the function returns an error code of -15.

Begin Directory Search

This function searches a directory for a specified file in Windows and is used to find
the first file that meets specified search criteria. The Continue Directory Search
function, which is described in the following section, is used to find the second and
subsequent files. There is no equivalent command in Windows.

Syntax
$ZOS(12,FileName,Attribute)
FileName is the name of the file to search for in a directory. It may include the ? and
* wild card characters and optionally, a DriveID and a directory path.
Attribute is a numeric expression that indicates the attributes for the file search.
Acceptable values are 32 for archive, 16 for subdirectory, 8 for volume label, 4 for
system, 2 for hidden, and 1 for read-only. These values can be added together to
combine attributes (6 for hidden and system). If a value of 0 or null is specified, only
ordinary files are found.
The following example illustrates this function.
$ZOS(12,"*.*",4) Finds all system files.
$ZOS(12,"PRO?.*","") Finds "PRO?.*" ordinary files.
$ZOS(12,"C:\CN\*.EXE",1) Finds "C:\CN\*.EXE" read-only.
If the function is successful, it returns a string in the form S1^S2, in which S1 is the
FileName that was found and S2 is a character string that is used as input to the
Continue Directory Search function. Otherwise, the function returns an error code of
-2 to indicate invalid path or null to indicate no matching directory entry found. S2
also contains file information in the same format as MSM-PC/PLUS.

MSM Language Reference Manual MSM Functions • 201

 $A(S2,22) = File attributes
$E(S2,23,24) = File time in MS-DOS format
$E(S2,25,26) = File date in MS-DOS format
$E(S2,27,30) = File size, least significant byte first

There is a difference between MSM Windows implementations and MSM-

PC/PLUS. The Begin Search function opens a search handle that uses Windows’
resources and should be closed when it is no longer required. There is no such
requirement in MSM-PC/PLUS because searches are performed differently in MS-
DOS. If this handle is open, it is closed in the following situations:
• $ZOS(12) is issued to begin a new search.
• $ZOS(8) is issued to change the current directory.
• $ZOS(13) reaches the end of a search.
• $ZOS(1) is issued to change the current drive.
• $ZOS(16) is issued.
• The job terminates.
• If a search operation is not continued to the end, a $ZOS(16) call is issued to
close the search handle.

Continue Directory Search

This function continues a directory search that was started using the Begin Directory
Search function. There is no equivalent command in Windows.

Syntax
$ZOS(13,SearchParm)
SearchParm is the character string returned by the Begin directory function for the
first file or by this function for the second and subsequent files.
The following example illustrates this function.
$ZOS(13,$ZOS(12,"*.BAK",0))) Gets second file

SET X=$ZOS(12,"PROG?.*",0) QUIT:$P(X,"^")=""

FOR SET X=$ZOS(13,X) QUIT:$P(X,"^")=""

If the function is successful, it returns a string in the form S1^S2, where S1 is the
FileName that was found and S2 is a character string that is used as the next
SearchParm to this function. Otherwise, the function returns an error code of -2 to
indicate invalid path or -12 to indicate no matching directory entry found.

202 • MSM Functions MSM Language Reference Manual

 Get Current Drive
This function returns the current default drive value in Windows. There is no
equivalent command in Windows.

Syntax
$ZOS(14)
This function does not require any parameters. The following example illustrates this
function.
$ZOS(14) Returns current drive
If the function is successful, it returns the current drive as a single character (for
example: A). Otherwise, it returns a negative error code.

Close Directory Search

This function releases system resources that were allocated to perform a directory
search. This function is performed automatically by MSM at the end of a directory
search when $ZOS(12) or $ZOS(13) returns a null string. However, it should be
called explicitly if a directory search is abandoned before the end of the search is
reached.

Syntax
$ZOS(16,SearchParm)
The following example illustrates this function.
S X=$ZOS(13,X) X contains the desired file name
S I=$ZOS(16,X) Abandons the search and releases resources
This function always returns 0.

1RWH Not available in MSM-PC/PLUS.

Get Available Drives

This function returns a list of available drives. The list contains the root directory for
each drive, with each element separated by $C(0).

Syntax
$ZOS(17)

1RWH Not available in MSM-PC/PLUS.

MSM Language Reference Manual MSM Functions • 203

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

204 • MSM Functions MSM Language Reference Manual

$ZPOSITION
Returns the number of positions of a string that can fit in a field on an output device.

1RWH This function applies only to double-byte or wide character sets.

Syntax
$ZPO{SITION}(String,Field{,Width})

Definition
String Any string type expression.
Field An integer expression that specifies the size of the output field.
Width An expression that specifies the relative width of a double-byte
character, when compared with a single-byte character.
The $ZPOSITION function is used to determine the number of characters of a
String, beginning with the first, can fit into a fixed-length field of an output device.
The Field argument specifies the size of the output field in single-byte character
positions.

Considerations
The result of $ZPOSITION can be used in $EXTRACT to truncate a string so that it
fits within a given field. For example, if $ZPO(string,20,2)=15, then $E(string,1,15)
will fit in a field that is 20 positions long.

Associated Topics
$ZWIDTH Function

Examples
In the following examples, the symbol ❖ is used to represent a double-byte
character.

Setup Value of Function

$ZPOSITION("",5,2) 0

$ZPO("❖❖❖abcde",20,2) 8

$ZPO("❖❖❖abcde",8,1.25) 7.25

$ZPO("❖❖❖abcde",8,1.5) 6.5

$ZPO("❖❖❖abcde",8,2) 5

$ZPO("❖❖❖❖❖❖❖",7,1.25) 5.6

$ZPO("❖❖❖❖❖❖❖",7,1.5) 4.6666666666666666

$ZPO("❖❖❖❖❖❖❖",7,2) 3.5

MSM Language Reference Manual MSM Functions • 205

$ZPREVIOUS
Identifies the previous subscript, in collating sequence, for a specified subscripted
variable.

Syntax
$ZP{REVIOUS}(Variable)

Definition
Variable An expression that evaluates to a subscripted local or global variable name.
The $ZPREVIOUS function is used to identify the previous subscript in sequence at
a given level. The Variable name that is specified as an argument to the function can
be subscripted, and naked references are allowed. For the right-most subscript in the
Variable, the system returns the subscript value that precedes it. If no subscript
precedes it, the function returns a null value. If the right-most subscript in the
reference is a null value, then the system returns the value of the last subscript at that
level. This function is identical to the $ORDER function with a second operand of -1
and is provided only for compatibility with other M implementations.

Associated Topics
Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZNEXT Function
$ZORDER Function
$ZSORT Function

Examples

Setup Value of Function

SET ^A(1,2,3)=1,^A(2)=2,^A(4)=3 $ZPREVIOUS(^)=last global
$ZP(^A(""))="4" last node
$ZP(^A(4))="2" next to last node
$ZP(^A(2))="1" first node
$ZP(^A(1))="" no descendants
$ZP(^A(1,""))="2" second-node
level
$ZP(^A(1,2,""))="3" third level
$ZP(^A(1,2,3,""))="" no fourth
level

206 • MSM Functions MSM Language Reference Manual

$ZSORT
Identifies the next subscript, in collating sequence, for a specified subscripted
variable.

Syntax
$ZS{ORT}(Variable{,Direction})

Definition
Variable An expression that evaluates to a local or global variable
name.
Direction An expression that evaluates to either 1 or -1.
The $ZSORT function is used to identify the next or previous subscript in sequence
at a given level. The Variable name that is specified as an argument to the function
must be subscripted, and naked references are allowed. If Direction is not specified
or has a value of 1, then for the right-most subscript in the Variable, the system
returns the next subscript value that follows it. If no subscript follows it, the function
returns a null value. If the right-most subscript in the reference is a null value, the
system returns the value of the first or last subscript at that level, depending on the
value of Direction. If Direction is specified and evaluates to -1, the function returns
the previous subscript for the variable. If Direction is specified and has any value
other than 1 or -1, an error condition occurs.
The $ZSORT function returns the subscripts in the collating sequence defined for the
global (string or numeric sequence). For local variables, the subscripts are always
returned in string-collating sequence. The $ORDER function is identical to
$ZSORT, except that for local variables, it returns the subscripts in numeric-collating
sequence.

Associated Topics
Variables
$NEXT Function
$ORDER Function
$QUERY Function
$ZNEXT Function
$ZORDER Function

MSM Language Reference Manual MSM Functions • 207

 Examples

Setup Value of Function

SET ^A(-1)=0,^A(1,2,3)=1, $ZSORT(^)=first global
^A(2)=2,^A(4)=3 $ZS(^A(""))=-1 first node
$ZS(^A(-1))=1 second node
$ZS(^A(1))=2 third node
$ZS(^A(2))=4 fourth node
$ZS(^A(4))="" no descendants
$ZS(^A(1,""))=2 second-node
level
$ZS(^A(1,2,"")=3 third-node
level
$ZS(^A(1,2,3,""))="" no fourth
level
$ZS(^A(4),-1)=2 previous node

208 • MSM Functions MSM Language Reference Manual

$ZUCI
Returns the user class identifier (UCI) internal number or external name.

Syntax
$ZU{CI}(UCIName{,VolName})
$ZU{CI}(UCINum{,VolNum})

Definition
UCIName A string expression that is an external UCI name.
VolName A string expression that specifies a three-character volume group
name.
UCINum A numeric expression that is an internal UCI number.
VolNum A numeric expression that specifies an internal volume-group
number.
In the first form, the $ZUCI function returns the internal reference number of the
specified user-class identifier, followed by the internal reference number of the
volume group containing the UCI. These fields are separated by a comma. If the
VolName is passed to the function, that volume group is searched for the specified
UCI; otherwise, the current volume group is searched. If the UCIName or the
VolName is invalid or does not exist, the function returns the null string. If the
UCIName is null, the current UCI is used.
In the second form, the $ZUCI function returns the external name of the specified
UCI number followed by the external name of the volume group that contains the
UCI. These fields are separated by a comma. If a VolNum is passed to the function,
that volume group is searched for the specified UCI. Otherwise, the current volume
group is searched. If the UCINum or the VolNum is invalid or does not exist, the
function returns a null ("") value. If the UCINum is 0, then the current UCI is
returned. If the UCINum is equal to the null string, then the numeric form of the
current UCI is returned.

Associated Topics
Using Peripheral Devices, MSM User's Guide

Examples

Setup Value of Function

$ZUCI(1)="MGR,SYS" Returns the external name.
$ZU("MGR")="1,0" Returns the internal number.
$ZU(0)="FMR,SYS" Returns the external name of the current UCI.
$ZU("")="2,0" Returns the internal number of the current UCI.

MSM Language Reference Manual MSM Functions • 209

$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

210 • MSM Functions MSM Language Reference Manual

 Examples

Setup Value of Function

$ZVERIFY(2)="" The manager's global directory is verified and no errors
are found.
$ZV(2)="30,27,233" The manager's global directory is verified and block 27 is
found to have an error (keys not in ascending order) at
offset 233 in the block.
$ZV(2,99)="30,27,233^ ... The manager's global directory is verified and multiple
errors are found.
$ZV(5000,100,4)="" Block number 5000 in Volume Group 4 and all of its
descendants are verified and no errors are found.
$ZV($ZBN(^CUST))="" The ^CUST global is verified and no errors are found.
This syntax does not have the desired result if the ^CUST
global is translated.

MSM Language Reference Manual MSM Functions • 211

$ZWIDTH
Returns the width that a string occupies when it is displayed on an output device.
1RWH This function applies only to double-byte or wide character sets.

Syntax
$ZW{IDTH}(String{,Width})

Definition
String Any string-type expression.
Width An expression that specifies the relative width of a double-byte
character compared to a single-byte character.
The $ZWIDTH function is used to calculate the number of character positions that a
string occupies when it is displayed on a specific output device. A single-byte
character is assumed to occupy one position on the output device. The Width
argument specifies how many positions a double-byte character occupies on the
output device. If Width is omitted, it is assumed to be two.
If n1 is the number of double-byte characters in String and n2 is the number of
single-byte characters in String, then $ZWIDTH(String,Width)=n1*Width+n2.

Associated Topics
$ZPOSITION Function

Examples
In the following examples, the symbol ❖ is used to represent a double-byte
character.

Setup Value of Function

$ZWIDTH("",2) 0

$ZW("❖❖❖abcde",1.25) 8.75

$ZW("❖❖❖abcde",1.5) 9.5

$ZW("❖❖❖abcde",2) 11

$ZW("❖❖❖abcd",2) 10

212 • MSM Functions MSM Language Reference Manual

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 MSM Special Variables • 213

$DEVICE
Contains a value that indicates if the last input/output (I/O) operation was successful.

Syntax
$D{EVICE}

Definition
The $DEVICE special variable contains a string that indicates whether the last device
handling mnemonic input/output operation was successful. The string value of
$DEVICE is in the following format:
MDC#,Implementor#,Descriptive Text
The MDC# is a value defined by the M Development Committee in an effort to
standardize error conditions. The Implementor# is defined by Micronetics to further
describe the nature of an error. The Descriptive Text is a brief description of the error
that occurred. Refer to the information on mnemonic namespaces in “Using
Peripheral Devices” in the MSM User's Guide for a list of the MDC# errors and the
Implementor# errors.

Considerations
The value of $DEVICE, when interpreted as a truth value, is equal to zero if the
operation is successful. A non-zero value indicates that the operation failed. This
special variable has meaning only for devices that are associated with a mnemonic
namespace.

Associated Topics
WRITE Command
Using Peripheral Devices, MSM User's Guide

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

214 • 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 “Error Processing” in this manual for a list of the ANSI M error numbers
and MSM-specific error codes.

Considerations
When the value of $ECODE is the empty string, normal routine execution rules are in
effect.
Error processing is initiated when:
• $ECODE transitions from an empty to a non-empty string. The value of
$ECODE may change implicitly when MSM detects an error condition (such as
an undefined variable), or when explicitly SET by the application.
• A QUIT returns from an execution level with $ECODE non-empty to a level in
which no error had occurred. For example, $STACK(new level,"ECODE") is the
empty string.
• When the value of $ECODE is changed via the SET command, the new value
replaces the existing value. The replacement value must be in the correct format
as described above; otherwise, an error occurs.
• When a partition is initiated, $ECODE has the value of the empty string.

MSM Language Reference Manual MSM Special Variables • 215

 Associated Topics
QUIT Command
SET Command
$ETRAP Special Variable
$STACK Function
Error Processing

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.

216 • MSM Special Variables MSM Language Reference Manual

$ESTACK
Indicates the relative execution nesting level.

Syntax
$ES{TACK}

Definition
The $ESTACK special variable contains a non-negative integer specifying the
relative nesting of the current execution level. The value is automatically incremented
by the DO and XECUTE commands, and automatically decremented by the QUIT
command. The NEW command may be used to stack the current value and reset
$ESTACK to 0. A QUIT command (explicitly or implicitly at the end of a routine or
an XECUTE string) restores the stacked value. A new partition begins with
$ESTACK set to 0.
Refer to the MSM User's Guide for additional information.

Considerations
An application may stack the value of $ESTACK and reset it to 0 via the NEW
command. Subsequent error handling routines may “pop” the execution levels until
$ESTACK returns to 0, at which point execution returns to its initial starting level for
the application. This is useful for nested applications. If $ESTACK is not stacked by
the NEW command, it always equals $STACK.

Associated Topics
DO Command
JOB Command
NEW Command
SET Command
XECUTE Command
$STACK Special Variable
Using the MSM System, MSM User's Guide

MSM Language Reference Manual MSM Special Variables • 217

 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.

218 • MSM Special Variables MSM Language Reference Manual

$ETRAP
Specifies the string to be executed when an error condition is detected.

Syntax
$ET{RAP}

Definition
The $ETRAP special variable contains a string of M code to be executed when an
error condition is detected. The code is executed at the same execution level at which
the error occurs. Prior to execution of the string in $ETRAP, any active FOR loops
and indirections in the current execution level are terminated. Execution behaves as if
the contents of $ETRAP are appended to the current routine with a temporary but
unique label, and an internal GOTO to the appended code is performed. Updating
$ETRAP replaces its previous value.
The current value of $ETRAP can be stacked using the NEW command. The NEW
command does not alter the value of $ETRAP; it merely stacks it. New partitions
begin with $ETRAP set to the empty string. When $ETRAP is SET, the value of
$ZTRAP also is reset to the empty string so that at any time, either $ETRAP or
$ZTRAP defines the error handling environment, but not both.
Refer to the MSM User's Guide for additional information.

Considerations
Within an application, the NEW command can be used to stack the caller’s $ETRAP
until a QUIT command (implicit or explicit) is executed at the current execution
level.
Unlike $ZTRAP, the value of $ETRAP is not tied to an execution level unless the
NEW command is used. Therefore, the application can set $ETRAP at the start of the
application. The same $ETRAP value is used at each nested level if an error
condition is detected. When initiating error processing, MSM performs an explicit
GOTO (without changing the execution level) to the following two lines of code.
...value of $ETRAP...
QUIT:$QUIT "" QUIT

MSM Language Reference Manual MSM Special Variables • 219

 Associated Topics
DO Command
JOB Command
NEW Command
SET Command
XECUTE Command
$STACK Function
$ECODE Special Variables
$ZTRAP Special Variables
Using the MSM System, MSM User's Guide

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

220 • MSM Special Variables MSM Language Reference Manual

$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

MSM Language Reference Manual MSM Special Variables • 221

$IO
Contains the device number of the current I/O device.

Syntax
$I{O}

Definition
The $IO special variable contains the device number (designator) of the current
device for the job. The value of $IO is uniquely identified for the current input/output
device. The current input/output device is the device most recently referenced with
the USE command. If a USE command has not been issued, the current device
number corresponds to the principal device number (the device number assigned to
the job when it logged onto MSM).

Associated Topics
OPEN Command
CLOSE Command
USE Command
ZUSE Command
$PRINCIPAL Special Variable

Examples
USE 3 S X=$I

The local variable X is assigned a value of 3.

S ^A($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.

222 • MSM Special Variables MSM Language Reference Manual

$JOB
Contains the job number of the job that is currently executing.

Syntax
$J{OB}

Definition
The $JOB special variable contains the job number of the current job. When a user
logs on to MSM, a job is created and a unique integer number is assigned to the job.
In addition, whenever a job is started with the JOB command, a unique job number is
assigned to the newly created job.

Associated Topics
JOB Command

Examples
S ^A($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.

MSM Language Reference Manual MSM Special Variables • 223

$KEY
Contains the control sequence that terminated the last READ command from the
current device.

Syntax
$K{EY}

Definition
The $KEY special variable contains the sequence of control characters that
terminated the last READ command from the current device. Before the first READ
is issued to a device or when the READ terminates without receiving a terminator
character (for example, as a result of a timeout, a fixed-length READ, or a
single-character READ operation), the value of $KEY is the null string (empty).
Otherwise, it is one of the control characters that can be specified in MSM as a
READ terminator. When escape processing is enabled for terminal devices, $KEY
can contain a string of characters, usually generated by a function key, which
terminated the READ.

Considerations
This special variable has meaning only for devices that are associated with a
mnemonic namespace.

Associated Topics
READ Command
USE Command
Using Peripheral Devices, MSM User's Guide

Examples
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 RETURN 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.

224 • MSM Special Variables MSM Language Reference Manual

$PRINCIPAL
Contains the number of the job’s principal device.

Syntax
$P{RINCIPAL}

Definition
The $PRINCIPAL special variable contains the number of the device that was the
principal device at the instant that the job was started. In other words, $PRINCIPAL
is equal to the initial value of the $IO special variable.
In the case of a job that was created as a result of a user logging into MSM, it is the
number of the device that initiated the logon. For a job created as a result of the JOB
command, it is the device number of the principal device associated with the job that
issued the command.

Considerations
The $PRINCIPAL special variable supersedes the old convention in MSM in which a
USE 0 command indicates the principal device. This construct should be replaced
with a USE $PRINCIPAL statement to ensure portability.

Associated Topics
JOB Command
$IO Special Variable

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

MSM Language Reference Manual MSM Special Variables • 225

$QUIT
Contains a value that indicates whether an argument is required on a QUIT.

Syntax
$Q{UIT}

Definition
The $QUIT special variable indicates if an argument is required on a QUIT. $QUIT
returns 1 if the current execution level was invoked as an extrinsic and a QUIT
therefore requires a value. Otherwise, $QUIT returns 0. $QUIT is initialized to 0
when a process is started.

Associated Topics
Extrinsic Functions
Parameter Passing
$ECODE Special Variable
$ESTACK Special Variable
$ETRAP Special Variable
$QUIT Special Variable
$STACK Special Variable
$STACK Function

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

226 • MSM Special Variables MSM Language Reference Manual

$STACK
Indicates the current (absolute) execution nesting level.

Syntax
$ST{ACK}

Definition
The $STACK special variable contains a non-negative integer that specifies the
absolute nesting of the current execution level. The value is automatically
incremented by the DO and XECUTE commands and is automatically decremented
by the QUIT command. A new partition begins with $STACK set to zero.
Refer to the MSM User's Guide for additional information.

Considerations
$STACK differs from $ESTACK in that the value is read-only and cannot be SET by
the application, nor can it be stacked by using the NEW command. $STACK reflects
the actual nesting level of the DO and XECUTE commands for the entire partition.
$ESTACK reflects a relative nesting level because it is reset by the NEW command.
If $ESTACK is not stacked by the NEW command, it always equals $STACK.

Associated Topics
DO Command
JOB Command
SET Command
XECUTE Command
$STACK Function
$ESTACK Special Variable
Using the MSM System, MSM User's Guide

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

MSM Language Reference Manual MSM Special Variables • 227

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

228 • MSM Special Variables MSM Language Reference Manual

$SYSTEM
Contains an M User’s Group-assigned vendor identification number and a
Micronetics-assigned identifier.

Syntax
$SY{STEM}

Definition
The $SYSTEM special variable contains information that distinguishes in a unique
manner the current MSM system from all other MSM and non-MSM systems. The
$SYSTEM special variable contains two pieces separated by a comma. The first
piece is the Micronetics vendor identification number assigned by the M User’s
Group. It will always be the value 43.
The second piece contains two numbers separated by a semicolon. The first number
is the serial number from the current MSM license. The second number is a unique
identifier for the current instance of MSM. This provides a unique value for
$SYSTEM when two workstation clients using the same license information connect
to a common server.
This special variable is formatted in such a way that it can be used directly as a
subscript in a local or global variable. When used in conjunction with the $JOB
special variable, network-unique nodes can be generated.

Associated Topics
Variables

Examples
WRITE $SYSTEM
43,1001234;176034223

This example writes the contents of $SYSTEM to the current device.

S ^UTILITY($SY,$J)=X

Temporary global nodes can be set up with data stored by the SYSTEM identifier and the JOB
number.

MSM Language Reference Manual MSM Special Variables • 229

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

230 • MSM Special Variables MSM Language Reference Manual

$TLEVEL
Indicates whether or not a transaction is currently in progress.

Syntax
$TL{EVEL}

Definition
The $TLEVEL special variable indicates whether or not a transaction is currently in
progress. This variable is initialized to 0 when the job (process) is started. A value of
0 indicates that no transaction is in progress for the job. Any other value indicates
that a transaction is in progress.
Whenever a TSTART command is performed, the system adds one to the current
value of the $TLEVEL variable. Whenever a TCOMMIT command is performed and
the value of $TLEVEL is greater then 0, the system subtracts one from the value of
the $TLEVEL variable. Whenever a TROLLBACK command or transaction restart
(an explicit TRESTART command or a system-initiated restart) is performed, the
value of the $TLEVEL variable is set to 0.

Associated Topics
TCOMMIT Command
TRESTART Command
TROLLBACK Command
TSTART Command
$TRESTART Special Variable

Examples
W $TLEVEL
4

This example writes the number of TSTART commands processed since the last TCOMMIT
or transaction restart.

MSM Language Reference Manual MSM Special Variables • 231

$TRESTART
Indicates the number of transaction restarts that have occurred since the initiation of
the transaction.

Syntax
$TR{ESTART}

Definition
The $TRESTART special variable contains a count of the number of transaction
restarts that have occurred during the transaction. The restarts can be explicit (a
TRESTART command) or implicit (a system-initiated restart). A value of 0 indicates
that no restarts have occurred. Any other positive value indicates restarts have
occurred. This variable is initialized to 0 when the job (process) is started. It is also
set to 0 by the successful completion of the TCOMMIT or TROLLBACK command.
During the transaction, each transaction restart adds one to the value of the
$TRESTART variable.

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

Examples
W $TRESTART
3

This example writes the number of transaction restarts that have occurred during the
transaction.

232 • MSM Special Variables MSM Language Reference Manual

$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

Y is given the value 0.

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.

MSM Language Reference Manual MSM Special Variables • 233

$Y
Contains the decimal value of the next output row for the current device.

Syntax
$Y

Definition
The $Y special variable is used to keep track of the Y-coordinate of the last character
output to the current device. The values may range from 0 to 255. Whenever a line
feed (the ! format character, $C(10), or *10) is encountered, the value of $Y is
incremented by one ($Y=$Y+1). On form-feed characters (the # format character,
$C(12), or *12), the value of $Y is reset to 0. In addition, when the value is
incremented beyond 255, it is reset to 0. Use the SET command to change the value
of $Y.

Associated Topics
Format Characters

Examples
W # S Y=$Y

Y is given the value 0.

W #!!! S Y=$Y

Y is given the value 3.

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.

234 • MSM Special Variables MSM Language Reference Manual

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

MSM Language Reference Manual MSM Special Variables • 235

$ZB
Contains device-specific information for the current device.

Syntax
$ZB

Definition
The $ZB special variable contains an integer value that relates to error conditions,
status indicators, and so on, for the current device.

Associated Topics
OPEN Command
USE Command

Examples
U 51 R X S RC=$ZB

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.

236 • MSM Special Variables MSM Language Reference Manual

$ZC
Contains device-specific information for the current device.

Syntax
$ZC

Definition
The $ZC special variable contains an integer value that relates to error conditions,
status indicators, and so on, for the current device. Generally, a non-zero value
indicates an error condition.

Associated Topics
OPEN Command
USE Command

Examples
U 51 R X S RC=$ZC

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.

MSM Language Reference Manual MSM Special Variables • 237

$ZERROR
Contains the text of the error message most recently produced by the MSM system.

Syntax
$ZE{RROR}

Definition
The $ZERROR special variable contains the error message most recently issued by
the MSM system. The message is in the format <ErrMsg> Detail. The ErrMsg
portion is a five-character abbreviation for the error, and Detail is the detailed
information about the error.
This variable is most commonly used in conjunction with the $ZTRAP variable to
determine what type of condition caused the error trap to be entered. For additional
information on error trapping and error messages, refer to the $ZTRAP special
variable, and to “Error Processing” in this manual.

Associated Topics
$ECODE Special Variable
$ETRAP Special Variable
$ZTRAP Special Variable
Error Processing

Examples
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).

238 • MSM Special Variables MSM Language Reference Manual

$ZLEVEL
Contains a number that indicates the current nesting level.

Syntax
$ZL{EVEL}

Definition
The $ZLEVEL special variable contains a value that indicates the current nesting
level. The value is initialized to 0 when the partition is created, and it is incremented
each time a DO, FOR, or XECUTE command is processed. Each time an implicit or
explicit QUIT command is processed, the value is decremented.
Note that the initial value of the variable can be different depending on the mode in
which the user is operating and how the routine was entered. For example, when
operating in direct mode, this variable has an initial value of 1. When the routine that
is executing is entered as a result of a tied-terminal entry, this variable has an initial
value of 2.

Associated Topics
DO Command
FOR Command
QUIT Command
XECUTE Command
Using the MSM System, MSM User's Guide
Configuring the System, MSM User's Guide

Examples
W $ZLEVEL
4

This example writes the number associated with the current nesting level.

MSM Language Reference Manual MSM Special Variables • 239

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

240 • MSM Special Variables MSM Language Reference Manual

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

MSM Language Reference Manual MSM Special Variables • 241

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

242 • MSM Special Variables MSM Language Reference Manual

$ZTRAP
Contains the line label and the routine name of the program to receive control when
an error occurs.

Syntax
$ZT{RAP}

Definition
The $ZTRAP special variable is used to set a trap that is invoked when an error
condition occurs. The trap can be specified as a line label (ERROR), a routine name
(^%ET), or a line label and routine name (ERR^MYPROG). Whenever an error
occurs, execution automatically returns from any nested DO or XECUTE commands
(which have not specified any error handling) and then a GOTO command is issued
with the $ZTRAP variable as the argument. Indirection may be used in the trap
specification.
Upon entry to the trap routine, the $ZTRAP special variable is set to the empty
string, the $ZERROR special variable contains information about the error; and
$ECODE is set to the empty string. Refer to the MSM User's Guide for additional
information on trapping errors.

Considerations
When the error trap routine or label is invoked, the $ZTRAP variable is set to null. It
is the responsibility of the error trap routine to re-establish the trap if appropriate.
One $ZTRAP special variable can be set at each execution level. This means that
each execution level in an application can establish its own error trapping routine and
error recovery procedures.
Setting $ZTRAP also performs the following action:
NEW $ETRAP SET $ETRAP=""

This is done to ensure that either $ZTRAP or $ETRAP, but not both, is used to trap
the error condition.

Associated Topics
$ECODE Special Variable
$ETRAP Special Variable
$ZERROR Special Variable
Block Structured Subroutines
ZQUIT Command
ZTRAP Command
Error Processing

MSM Language Reference Manual MSM Special Variables • 243

 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.

244 • MSM Special Variables MSM Language Reference Manual

$ZVERSION
Contains the name and release number of the MSM software in use.

Syntax
$ZV{ERSION}

Definition
The $ZVERSION special variable contains the name of the MSM system being used
(for example: MSM-PC/PLUS, MSM-UNIX) and the release number of the software
(for example, Version 4.4.0).

Considerations
The $ZVERSION variable can be used to test the system type if the software
contains implementation-specific or release-specific features of MSM.

Examples
W $ZV

MSM-PC/PLUS, Version 4.4.0

This example prints the name and version number of the MSM system that is in use.

MSM Language Reference Manual MSM Special Variables • 245

246 • MSM Special Variables MSM Language Reference Manual
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 MSM Structured System Variables • 247

^$DEVICE
Provides information on the existence, operational characteristics, and availability of
a device.

Syntax
^$D{EVICE}(DeviceNum)

Definition
DeviceNum An expression that evaluates to a device number.
The $DEVICE structured system variable provides information on the existence,
operational characteristics, and availability of a specified device. If the device exists,
$DATA of the ^$DEVICE variable returns a value of 10. Otherwise, $DATA returns
a value of 0.

Defined Nodes
None

Associated Topics
Using Peripheral Devices, MSM User's Guide

Examples
$DATA(^$DEVICE(3))

This expression tests for the existence of device number 3.

$ORDER(^$D(3))

This expression returns the device number of the next device defined in the system after
device number 3.

248 • MSM Structured System Variables MSM Language Reference Manual

^$GLOBAL
Provides information on the existence, operational characteristics, and availability of
a global.

Syntax
^$G{LOBAL}(GlobalVar)

Definition
GlobalVar An expression that evaluates to a global variable name.
The $GLOBAL structured system variable provides information on the existence,
operational characteristics, and availability of a specified global. If the global exists,
$DATA of the ^$GLOBAL structured system variable returns a value of 10.
Otherwise, $DATA returns a value of 0.

Defined Nodes
None

Associated Topics
Global Variables

Examples
$DATA(^$GLOBAL("^A"))

This expression tests for the existence of global ^A (existence is defined as $D(^Global)>0).

$ORDER(^$G("^A"))

This expression returns the name of the global that follows the global named A in the global
directory.

SET X=""
FOR S X=$0(^$G(X)) Q:X="" WRITE !,X

This code loops through the entire global directory, writing each global name to the current
device.

MSM Language Reference Manual MSM Structured System Variables • 249

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

250 • MSM Structured System Variables MSM Language Reference Manual

^$LOCK
Provides information on the existence and operational characteristics of a locked
resource.

Syntax
^$L{OCK}(Variable)

Definition
Variable An expression that evaluates to a local or a global variable name.
The $LOCK structured system variable provides information on the existence and
operational characteristics of a specified locked resource. If the specified resource
has been successfully LOCKed (and not yet unLOCKed), $DATA of the ^$LOCK
structured system variable returns a value of 10. Otherwise, $DATA returns a value
of 0.

Defined Nodes
None

Associated Topics
LOCK Command
ZALLOCATE Command
ZDEALLOCATE Command

Examples
$DATA(^$LOCK("^A"))

This expression tests to see if the global variable A is currently locked.

$ORDER(^$L("^A"))

This expression returns the name of the next resource that is locked.

$ORDER(^$L("^A"))
SET X=""
FOR S X=$0(^$L(X)) Q:X="" WRITE !,X

This code writes the entire contents of the lock table to the current device.

MSM Language Reference Manual MSM Structured System Variables • 251

^$ROUTINE
Provides information on the existence, operational characteristics, and availability of
a routine.

Syntax
^$R{OUTINE}(RoutineName)

Definition
RoutineName An expression that evaluates to a routine name.
The $ROUTINE structured system variable provides information on the existence,
operational characteristics, and availability of a specified routine. If the routine
exists, $DATA of the ^$ROUTINE structured system variable returns a value of 10.
Otherwise, $DATA returns a value of 0.

Defined Nodes
zsdate Returns the $HOROLOG date/time at which the routine was last
ZSAVEd.

Associated Topics
Global Variables
ZSAVE Command
$HOROLOG Special Variable
$ZDATE Function

Examples
$DATA(^$ROUTINE("A"))

This expression tests for the existence of routine A.

$ORDER(^$R("A"))

This expression returns the name of the routine that follows the routine named A in the routine
directory.

WRITE $ZDATE(^$R(“A”,”zsdate”))

This expression formats the date last saved for routine A.

252 • MSM Structured System Variables MSM Language Reference Manual

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

MSM Language Reference Manual ASCII Collating Sequence • 253

 Decimal Symbol Pattern Decimal Symbol Pattern
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

254 • ASCII Collating Sequence MSM Language Reference Manual

Error Processing

Overview
This section describes methods of trapping errors during program execution, and lists
error messages that may be generated during execution.

Error Processing
During program execution, unusual situations may occur that the MSM system
cannot handle automatically, including: program errors (for example: arithmetic
division by zero), hardware failures (for example: an error reading a disk block), and
external interrupts to a routine (for example: a user pressing CTRL+C). Generally,
MSM considers such situations to be fatal errors.

Actions: When Error Condition is Detected

When an error condition is detected during program execution, MSM interrupts
execution and performs the following actions:
• Terminates any active FOR loops and indirections on the current line.
• Sets $ZERROR to reflect the error.
• Appends the appropriate error codes to the $ECODE special variable. If
$ECODE is updated via the SET command, the entire value of $ECODE is
replaced.
• Updates the $STACK system function array to reflect the error, setting the
ECODE, MCODE, and PLACE sub-nodes of $STACK($STACK).
• If no error handling is specified at any execution level ($ETRAP is null, all
NEWed values of $ETRAP also are null at all execution levels, and there are no
non-null $ZTRAPs at any execution level), generates an execution traceback and
terminates all the execution levels. If the user is in programmer mode, MSM
changes the current device to the principal device and issues a command prompt.
If programmer mode is not enabled, the partition is terminated after invoking the
MSM default error handler.

MSM Language Reference Manual Error Processing • 255

 Actions: When Error-Handling is Specified
The following steps are performed if error handling is specified at the current or at an
earlier execution level.
If $ETRAP is non-null, MSM performs an internal GOTO to the following two lines
of M code:
... $ETRAP value ...
QUIT:$QUIT "" Q

The second line handles the case in which the $ETRAP code completes and
execution then continues on the second line. The QUIT commands are set up so that
the current execution level terminates correctly depending on whether or not it was
invoked as an extrinsic.
If $ZTRAP is non-null, MSM internally performs the following line of M code:
SET $ECODE="" GOTO @($ZTRAP)

As part of the GOTO, the value of $ZTRAP is reset to the null string. If additional
error handling is required at the current execution level, $ZTRAP must be
reestablished. The value of $ECODE is cleared to ensure that when the current
execution level terminates, $ECODE is null. Otherwise, a return to an execution level
where $STACK ($STACK("ECODE")) is null and $ECODE is not null would
generate an error (in accordance with the 1994 ANSI M standard). Because $ZTRAP
code presumably was written prior to the 1994 ANSI standard, it is not likely to
contain code that explicitly resets $ECODE. To maintain compatibility with existing
applications, MSM clears $ECODE prior to transferring to the $ZTRAP error
handling code.
MSM terminates the current execution level. This includes restoring values stacked
by the NEW command (possibly including $ESTACK and $ETRAP).
MSM terminates any active FOR loops and indirections in the current execution line.
MSM continues with step 1 above until an execution level is reached that does
specify error handling via $ETRAP or $ZTRAP.
To ensure that error handling is uniquely defined, MSM does not allow both
$ETRAP and $ZTRAP to be non-null at the same time. When $ETRAP is
established via the SET command, MSM internally resets $ZTRAP to the empty
string. When $ZTRAP is established via the SET command, MSM internally
performs a NEW command on $ETRAP and then sets its current value to the empty
string (a QUIT from this execution level restores $ETRAP to its original value). This
interaction between $ETRAP and $ZTRAP allows existing applications that rely on
$ZTRAP to coexist (on the execution stack) with applications that rely on the ANSI
standard method of error trapping.
Refer to “MSM Functions” and “Special Variables” in this document for additional
information.

256 • Error Processing MSM Language Reference Manual

 Default Error Processing
If error handling is not defined, the error processing action to be taken when an error
occurs includes a display of the execution traceback on the principal device and an
invocation of the MSM default error handler.
The execution traceback displays the current value of $ZERROR, a formatted display
of each execution level (from the deepest to the initial), followed by a redisplay of
$ZERROR (in case the initial value scrolled off the screen). The formatted display
of a level includes its nesting level ($STACK); the routine reference of the line being
performed or '*XECUTE* if inside an XECUTE string; and a copy of the line of M
code that is being performed, if available (p-code-only routines display null text
lines).
Following the execution traceback, the ^%ET utility is invoked to store the partition's
current status for later review. This includes saving a copy of all the local symbols
for the partition, $IO, $PRINCIPAL, $ZREFERENCE, and so on. These values can
be examined using the ^%ER utility.

User-Defined Error Processing

The programmer can specify the M code that is to be performed when MSM detects
an error. The programmer can use either the 1994 ANSI Standard error processing
features such as $ETRAP or $ECODE or the MSM-specific features, $ZERROR and
$ZTRAP.

User-Defined Error Processing - $ETRAP

To use the $ETRAP mechanism, the value of $ETRAP is set to an M string that is
executed when an error is detected. For example:
SET $ETRAP="S X=$X,Y=$Y G ^ERROR"

When an error is detected, MSM sets locals X and Y to the current values of $X and
$Y respectively, and then transfers control to the first line in routine ^ERROR. This
routine can attempt to recover from the error, record the error and any application-
specific information, or allow the error to propagate to the previous execution level
where it can be handled, recorded, or continue to be propagated to earlier execution
levels. If the error processing routine does not clear $ECODE before exiting from the
execution level where an error occurred, error processing is still in effect in the new
execution level. A common use for M error handling features is to NEW $ESTACK
at the top menu level of the application and to continue in error processing mode
until the $ESTACK returns to zero.

MSM Language Reference Manual Error Processing • 257

 User-Defined Error Processing - $ZTRAP
To use the $ZTRAP mechanism, the value of $ZTRAP is set to an M entry reference
to which control will be transferred when an error is detected. For example:
SET $ZTRAP="ENTRY^ERROR"

When an error is detected, MSM terminates execution levels one at a time until it
reaches an execution level at which $ZTRAP is not null. MSM then performs a
GOTO to the entry point contained in $ZTRAP and also resets $ZTRAP to the empty
string. This routine can attempt to recover from the error, record the error and any
application-specific information, or force the error to be propagated to an earlier
execution level that has a non-null $ZTRAP where the error can be handled,
recorded, or continue to be propagated to earlier execution levels.
Because MSM internally resets the $ZTRAP used to invoke the error handling
routine, $ZTRAP must be explicitly SET to a new non-null value if additional errors
are to be trapped at the current execution level.

Processing Trapped Errors

When a DO or XECUTE command is processed, the MSM system creates a new
execution level. This is done so that on termination of the DO or XECUTE
command, either through an implicit QUIT (end-of-routine encountered) or an
explicit QUIT, the system can return to the point at which the command was initiated.
As a point of reference, each execution level created by a DO or XECUTE command
is numbered. Programmer mode is considered to be execution level 0, the first DO or
XECUTE command is level 1, the second is level 2, and so on. The execution level
that is currently in control generally is referred to as the current execution level.
While there is only one $ETRAP special variable (there is not a different one at each
execution level), it can be stacked using the NEW command. This provides a
separate $ETRAP for each level when stacking is performed via the NEW command.
Each execution level can customize its error handler independent of other error
handling on the execution stack.
Alternatively, the $ZTRAP special variable can be set at each execution level. This
means that each execution level in an application can establish its own error trapping
routine and error recovery procedures.
Each execution level in an application can establish its own error trapping routine
and error recovery procedures using either $ETRAP or $ZTRAP.
After an error has been trapped and processed by the specified routine, several
techniques can be used to exit from the error trap routine. One method is to use a
GOTO command; control passes to a new routine, and program processing remains
at the same execution level. This is the most common form of error recovery.
Alternatively, a QUIT command can be used to return to the previous execution
level. When the $ETRAP mechanism is used, execution continues at the next higher
level (the current execution level minus one), based on the value of $ECODE. If
$ECODE is null, QUIT returns control normally to the previous level, with no further
error processing. If $ECODE is not null and $STACK($STACK,"ECODE") is null
(returning from a level with an error to a level at which no error occurred), error
processing continues at the new level.

258 • Error Processing MSM Language Reference Manual

 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

MSM Language Reference Manual Error Processing • 259

 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 this section.

%ET
When an error occurs and the %ET utility is invoked, the routine stores the values of
the $ZERROR, $HOROLOG, $JOB, $IO, and $STORAGE special variables; the key
of the last global referenced ($ZREFERENCE); and the contents of the local symbol
table. It also writes a message to the principal device indicating that a program error
was encountered and displays the contents of the $ZERROR special variable.

%ER
This utility reports errors that were trapped using the %ET routine. It allows you to
display, print, delete, or summarize errors. As a powerful programming and
debugging tool, the %ER utility allows the programmer to reload the local symbol
table with the local variable values that existed when the error occurred. After
loading the variables, the routine exits and returns you to programmer mode.

260 • Error Processing MSM Language Reference Manual

 Using Downlevel Error Trapping
Prior to MSM Version 2.1, the system discarded the entire contents of the
DO/XECUTE stack when an error occurred. This was done before the system passed
control to the error-trap routine specified by the $ZTRAP special variable. In MSM
Version 2.1 and subsequent MSM releases, the DO/XECUTE stack remains at the
same level when an error occurs.
Applications that require the DO/XECUTE stack to be cleared using the error
trapping techniques provided in earlier versions of MSM do not work properly. The
recommended solution to this problem is to modify the error-trapping code so that it
uses the new style of trapping. However, this may not be practical in all cases. As a
convenience to our users, a compatibility mode has been provided that enables error
processing to behave as it did in previous MSM releases.
The compatibility mode has been implemented as an extension to the BREAK
command. Refer to "MSM Commands" in this document for additional information
on the BREAK command. The following describes the implemented compatibility
extensions:
BREAK 2 Error trapping prior to Version 2.1
BREAK -2 Restore error trapping to Version 2.1 mode
When a job is started, the default value is the Version 2.1 mode of error processing
(BREAK -2). To enable the old style of error trapping, a BREAK command with an
argument 2 (BREAK 2) is inserted at the beginning of the application before any
other code is executed. It is strongly recommended that applications be modified to
take advantage of the new error processing capabilities.

Interactive Debugging
An MSM facility allows users operating in programmer mode to interactively step
through execution of a program either one line or one command at a time. This
facility also includes the ability to set breakpoints in programs without modifying the
source code for the routine, and to display and alter the contents of local variables.
This feature is most commonly used by the programmer to more efficiently trace
error conditions and determine the cause of an error. The interactive debugger is
invoked by entering the following command at the M programmer prompt.
DO ^%DEBUG

The system responds with a menu of options. The utility program includes complete
online help information and is easy to use.

Format of $ZERROR
The $ZERROR special variable contains descriptive information about the most
recent error. This information is also provided as a piece of the $ECODE special
variable when the $ETRAP mechanism of error trapping is used. The format of this
descriptive information is as follows.
<Code>Offset^RoutName:Cmnd:Arg:Major:Minor:AddInfo

MSM Language Reference Manual Error Processing • 261

 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.

262 • Error Processing MSM Language Reference Manual

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.

MSM Language Reference Manual Error Processing • 263

 Code Explanation

<ECODE> An attempt was made to set $ECODE to an invalid value, or error

processing was initiated by changing $ECODE from null to a valid
value.
<EXPER> An exponentiation error was detected.
<FUNCT> The interpreter encountered an undefined function or a function that
was used improperly.
<INDER> The interpreter encountered illegal or incorrect use of the indirection
operator.
<INHIB> Access to a database through the network failed because database
reads or writes are inhibited on the specified machine.
<INRPT> The operating system received an interrupt (BREAK) from the
terminal while the BREAK function was enabled (a BREAK 1
command was in effect).
<ISYNT> An attempt was made to insert an illegal line of text or code into the
routine buffer. This can occur if the line of code is too long, the line
label is invalid, or if the character separating the line label and the line
body is incorrect. When an insert is performed in direct mode, the
separator character must be a tab. If ZINSERT is used, the separator
character must be one or more spaces or tabs.
<KLJOB> The job was killed or interrupted by the KILLJOB utility.
<LCNSE> The attempted operation would exceed the license limit.
<LINER> A reference was made to a line that does not exist within the body of
the routine.
<MAPER> A disk block that is being freed is already marked free in the
corresponding MAP block.
<MERGE> A MERGE command was issued in which one operand is a
descendant of the other operand.
<MINUS> The interpreter found a negative number or zero when it expected a
positive number.
<MODER> An attempt was made to access the device in a mode that is not
consistent with the parameters specified when the device was opened.
<MTERR> An error occurred during an input or output operation to a magnetic
tape device.
<MWAPI> An error occurred while the M Windowing API was in use.
<MXMEM> A memory address specified as an argument to the VIEW command or
$VIEW function is outside the limits allowed by MSM.
<MXNUM> The value of a number is greater than the largest number allowed by
the system.
<MXSTR> The value of string exceeds the maximum length allowed by the
system. The maximum is 255 characters (or 511 as an option) for
global variables, and 4092 characters for local variables.

264 • Error Processing MSM Language Reference Manual

 Code Explanation

<NAKED> Access to a global variable using the naked indicator is invalid. This
can occur if the naked indicator was not previously set by a global
reference or if the previous global reference did not include
subscripts.
<NMSPC> A reference was made to an undefined mnemonicspace.
<NODEV> The system intercepted an attempt by the program to OPEN a device
that has not been defined to the system.
<NOJRN> An attempt was made to journal a global in single-user mode.
<NOPEN> The system intercepted an attempt by the program to USE a device
that was not previously OPENed by the program.
<NOPGM> A reference was made to a program that does not exist in the job's
routine search path.
<NOSYS> A reference was made to a non-existent system through Distributed
Data Processing (DDP) or to a non-existent volume group through an
extended global notation.
<NOUCI> A reference was made to a non-existent UCI through an extended
global notation.
<OBJCT> An error occurred while an object reference was in use.
<PCERR> The interpreter found an illegal post-conditional or the post-
conditional argument is invalid.
<PGMOV> There is insufficient memory in a partition to complete the requested
operation.
<PLDER> The routine that is being loaded has down-level p-code or does not
have the correct type of p-code for a remote volume group executing a
routine.
<PROT> An attempt was made to access a protected global that the user is not
authorized to access. This error also can occur if an attempt is made to
save a program with a name that begins with a percent sign (%) in any
UCI other than the Manager’s UCI.
<SBSCR> The subscript used in a local or global variable reference is invalid.
This can occur if the subscript is null; the subscript contains the ASCII
NULL character; the length of a subscript is greater than 255
characters; or the combined length of the global reference (global
name, parentheses, subscripts, and commas) is greater than 255.
<SPOOL> The MSM spooling area is full.
<STKOV> The system stack overflowed as a result of nested indirection or a
program loop, or the system expression stack overflowed while
evaluating a complex expression or saving a large routine.
<SYNTX> The interpreter encountered a syntax error in the line that is being
executed.
<SYSTM> The MSM system encountered an internal error. The exact error
message, including major/minor error numbers, should be reported to
Micronetics.

MSM Language Reference Manual Error Processing • 265

 Code Explanation

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

266 • Error Processing MSM Language Reference Manual

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)

MSM Language Reference Manual Error Processing • 267

 Major Minor Explanation
8 ZLOAD usage error during routine execution
9 Undefined UCI reference
10 Attempted ZINSERT of an invalid line
11 Unknown data type
12 Missing function parameter
13 Undefined system in cross-system reference
14 Global access protection violation
15 Volume group protection violation
16 XCALL error
17 Formal list not entered via DO command
18 QUIT with argument inside FOR scope
19 QUIT with argument, but routine not extrinsic
20 Argumentless QUIT, but routine was extrinsic
21 Extrinsic subroutine ended without Q parm
22 Label requires a formal list
23 Actual parms exceed parms in formal list
24 Formal list parameter is subscripted variable
25 Duplicate variable name in formal list
26 Passing value by reference in JOB not allowed
27 MERGE operand is descendant of other
28 Nested mnemonic namespace request
29 Undefined structured system variable
30 FOR control variable was KILLed
31 Unsupported OMI feature
32 Object value is undefined
33 Undefined object method or property
34 VIEW restriction violation
35 MWAPI reference to undefined element
36 Required MWAPI attribute missing
37 Mnemonicspace not in mnemonic list
38 Undefined mnemonicspace
39 Device does not support mnemonicspace
5 - Value-type errors
0 String exceeded maximum length
1 $SELECT function error
2 Divide by zero
3 Negative number
4 Maximum number
5 Device not open
6 Invalid memory address
7 String value required
8 Indirection resulted in null value

268 • Error Processing MSM Language Reference Manual

 Major Minor Explanation
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

MSM Language Reference Manual Error Processing • 269

 Major Minor Explanation
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

270 • Error Processing MSM Language Reference Manual

$ECODE Errors
The following table lists the $ECODE errors generated by MSM and explains how
the errors are caused.
(&2'( (UURUV

Equivalent
Code Explanation $ZERROR value
M1 Naked indicator undefined <NAKED>:::4:4
M2 Invalid "P" parameter in <SYNTX>:::5:22
$FNUMBER
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 <UNDEF>:::4:29
variable name
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 <SYNTX>:::5:24
than zero
M19 Cannot copy a tree or subtree <MERGE>:::4:27
into itself
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, <DPARM>:::4:23
parameter out of range
M35 Device does not support <NMSPC>:::4:39
mnemonicspace
M40 Call-by-reference in JOB actual <DPARM>:::4:26
M42 Invalid QUIT within a <TXPER>:::5:26
TRANSACTION
M43 Invalid range value ($X,$Y) <MINUS>:::5:27
M44 Invalid command outside of a <TXPER>:::6:24
TRANSACTION
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

MSM Language Reference Manual Error Processing • 271

 Equivalent
Code Explanation $ZERROR value
M49 Invalid MWAPI focus <MWAPI>:::5:35
M50 Reference to non-MTERM <MWAPI>:::6:32
window
M51 KILL of open MTERM window <MWAPI>:::6:33
M52 Required MWAPI attribute <MWAPI>:::4:36
missing
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

272 • Error Processing MSM Language Reference Manual

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 “MSM Commands” in this manual, and “Using Peripheral
Devices” in the MSM-Workstation Technical Reference documentation.
Two types of mnemonic namespaces are supported in MSM: built-in namespaces and
user-defined namespaces. MSM's standard distribution includes two built-in
namespaces and one user-defined namespace. The X3.64-1979 built-in namespace is
commonly referred to as the ANSI terminal namespace. The ZWINTERM built-in
namespace allows windowing capabilities on dumb terminals.
The user-defined namespace is called X3.64 TEMPLATE and is distributed in a
DOS file called ANSI.NAM. The system manager can use this namespace as a
template to create other namespaces. The X3.64 TEMPLATE namespace can be
imported into the MSM database using the Import a Namespace option. The template
then can be copied to a new name and edited. It includes the complete set of ANSI
mnemonics.
Because ANSI terminals are the most frequently used terminal type in M
applications, the namespace for this terminal type was directly built into the system.
From a technical point of view, a built-in namespace is coded directly into the MSM
system monitor rather than through user-supplied M code. As a result, overhead when
using this namespace is significantly reduced.
Because the X3.64-1979 is built-in, it cannot be edited or deleted by the user. The
mnemonics defined within the namespace cannot be listed through this option of the
SYSGEN utility.

MSM Language Reference Manual Mnemonic Namespaces • 273

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 Rings bell $X:None
Seq: *7 $Y:None
/BS Backspaces cursor $X:MAX(0,$X-1)
Seq: *8 $Y:None
/CBT(n) Backs up 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) Moves cursor to column n $X:n-1
Minimum and default values are 1 $Y:None
Seq: *27 [ n g
/CHT(n) Moves forward n tab stops $X:
Minimum and default values are 1 MIN(255,$X\8*8+(n*8)
Assumes eight-column tabbing $Y:None
Seq: *27 [ n i
/CNL(n) Moves cursor down n lines $X:0
Moves cursor to column 1 $Y:MIN(255,$Y+n)
Minimum and default values are 1
Seq: *27 [ n e
/CPL(n) Moves cursor up n lines $X:0
Moves cursor to column 1 $Y:MAX(0,$Y-n)
Minimum and default values are 1
Seq: *27 [ n f
/CR Moves cursor to column one, current line $X:0
Seq: *13 $Y:None
/CTC(a,b,...) Sets tab stops $X:None
Seq: *27 [ a ; b ; ... W $Y:None
/CUB(n) Moves cursor back n columns $X:MAX(0,$X-n)
Minimum and default values are 1 $Y:None
Seq: *27 [ n d
/CUD(n) Moves cursor down n rows $X:None
Minimum and default value is 1 $Y:MIN(255,$Y+n)
Seq: *27 [ n b

274 • Mnemonic Namespaces MSM Language Reference Manual

 Mnemonic Function and Esc sequence Change in $X and $Y
/CUF(n) Moves cursor forward n columns $X:MIN(255,$X+n)
Minimum and default values are 1 $Y:None
Seq: *27 [ n c
/CUP(r,c) Positions 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) Moves cursor up n lines $X:None
Minimum and default values are 1 $Y:MAX(0,$Y-n)
Seq: *27 [ n a
/DA(a,b,...) Sets device attributes $X:None
Parameters are ANSI values for color, $Y:None
blink, etc.
Seq: *27 [ a ; b ; ... m
/DAQ(a,b,...) Defines area qualifications $X:None
Parameters are ANSI values $Y:None
Seq: *27 [ a ; b ; ... O
/DCH(n) Deletes n characters at cursor $X:None
Moves remainder of lines left $Y:None
Minimum and default values are 1
Seq: *27 [ n p
/DL(n) Deletes n lines at cursor $X:None
Moves up remaining lines $Y:None
Minimum and default values are 1
Seq: *27 [ n m
/DSR(a,b,...) Performs device status request $X:None
Parameters are ANSI values $Y:None
Response must be read-in via READ
command
Seq: *27 [ a ; b ; ... N
/ECH(n) Erases n characters at cursor $X:None
Replaces with blanks $Y:None
Minimum and default values are 1
Seq: *27 [ n x
/ED(n) Erases 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

MSM Language Reference Manual Mnemonic Namespaces • 275

 Mnemonic Function and Esc sequence Change in $X and $Y
/EL(n) Erases 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 Moves cursor down one row $X:None
Seq: *12 $Y:($Y+1)#256
/HPA(n) Moves cursor to column n $X:n-1
Minimum and default values are 1 $Y:None
Seq: *27 [ n `
/HPR(n) Moves cursor forward n columns $X:MIN(255,$X+n)
Minimum and default values are 1 $Y:None
Seq: *27 [ n a
/HT Horizontal tab $X:MIN(255,$X\8*8+8)
Seq: *9 $Y:None
/HTS Sets horizontal tab stop at cursor $X:None
Seq: *27 h $Y:None
/HVP(r,c) Moves cursor to row r and column c $X:c-1
Minimum and default values are 1 $Y:r-1
Maximum value is 256
Seq: *27 [ r ; c f
/ICH(n) Inserts n blanks at cursor $X:None
Minimum and default values are 1 $Y:None
Seq: *27 [ n @
/IL(n) Inserts n blank lines at cursor $X:None
Minimum and default values are 1 $Y:None
Seq: *27 [ n l
/IND Moves cursor one column down $X:None
Seq: *27 d $Y:MIN(255,$Y+1)
/LF Moves cursor one line down $X:None
Seq: *10 $Y:($Y+1)#256
/MSMRC(n) Restores saved cursor position $X:Saved value
Seq: *27 8 $Y:Saved value
/MSMRGN(n,m) Sets up 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 Saves current cursor position $X:None
Seq: *27 7 $Y:None
/MSMSM(a,b,...) Sets modes $X:None
Seq: *27 [ ? A ; b ... H $Y:None

276 • Mnemonic Namespaces MSM Language Reference Manual

 Mnemonic Function and Esc sequence Change in $X and $Y
/NEL Moves to column one of next line $X:0
Seq: *27 e $Y:($Y+1)#256
/NP(n) Advances n pages of terminal $X:0
Displays memory $Y:0
Seq: *27 [ n u
/PP(n) Backs up n pages of terminal $X:0
Displays memory $Y:0
Seq: *27 [ n v
/RI Reverses index (up one column) $X:None
Seq: *27 m $Y:MAX(0,$Y-1)
/RIS Resets to initial state $X:0
Seq: *27 c $Y:0
/RM(a,b,...) Resets modes $X:None
Values are ANSI-defined $Y:None
Seq: *27 [ a ; b ; ... L
/SGR(a,b,...) Sets graphical rendition $X:None
Seq: *27 [ a ; b ; ... m $Y:None
/SM(a,b,...) Sets modes $X:None
Values are ANSI-defined $Y:None
Seq: *27 [ a ; b ; ... H
/TBC(a,b,...) Clears tap stops $X:None
Seq: *27 [ a ; b ; ... G $Y:None
/VPA® Moves to row r of same column $X:None
Minimum and default values are 1 $Y:r-1
Seq: *27 [ r d
/VPR(n) Moves cursor down n lines, same column $X:None
Minimum and default values are 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)

MSM Language Reference Manual Mnemonic Namespaces • 277

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

278 • Mnemonic Namespaces MSM Language Reference Manual

 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.

MSM Language Reference Manual Mnemonic Namespaces • 279

 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 Nonexistent window
4 Mnemonic space not initialized
5 Terminal does not have windowing
functionality
6 Undefined terminal mnemonic space

For additional information on the USE command, refer to “MSM Commands” in this
manual. For additional information on the $DEVICE special variable, refer to “MSM
Special Variables” also in this manual. The $DEVICE special variable is maintained
for the current terminal device and not for each window in the ZWINTERM
mnemonic namespace. The value contained in the $DEVICE special variable reflects
the last error condition, regardless of the specific window in which it occurred.

280 • Mnemonic Namespaces MSM Language Reference Manual

ZWINTERM Namespace Commands
/INIT(TermSpace,Color) - Initialize Namespace
Color A flag that indicates whether color attributes are supported for
the window. A value of 1 indicates that color attributes are
supported. A value of 0 (the default) indicates that color
attributes will be ignored.
Attribute An integer value that indicates the type of attribute to set. Refer
to the “ZWINTERM Display Attributes” table in this chapter for
a list of the attributes and their values. This parameter is
optional. If it is omitted, a default value of 0 is assumed.
This function is used to initialize the ZWINTERM mnemonic namespace for the
current terminal device. As part of the initialization process, a memory buffer is
obtained, the terminal screen is erased, and the system internally issues an OPEN
(/WOPEN) and USE (/WUSE) for window number 0 as a full screen window. The
default values for scroll, auto-wrap, automatic display, and line drawing are used.
The ZWINTERM Namespace also can be used in conjunction with the X3.64-1979
Namespace. If the first parameter of /INIT is X3.64-1979, then the full set of
mnemonics for this built-in namespace is available within the ZWINTERM window.
This mnemonic control must be executed before any other ZWINTERM mnemonic
control sequences can be used. If other mnemonic controls are executed before a
/INIT function is performed, the system returns an error code of 1 in the $DEVICE
special variable. If this mnemonic control is issued after a previously executed /INIT
function and before a /END function is executed, the system implicitly performs the
/END function before executing the /INIT function.

/END - Release Mnemonic Space

This function ends use of the ZWINTERM mnemonic namespace. The end process
frees all of the memory buffers used by ZWINTERM for the current device. Any
mnemonic control operation executed after a /END and before the next /INIT
operation returns an error code of 12 in the $DEVICE special variable.

/WOPEN(Win,Row,Col,NumRows,NumCols,Flag) - Open
Window
Win A positive integer used to identify the window.
Row An integer expression with a value between 0 and 23 that indicates
the starting row for the window. If the specified value is invalid or
omitted, the system assumes a value of 0.
Col An integer expression with a value between 0 and 79 that indicates
the starting column for the window. If the specified value is invalid
or omitted, the system assumes a value of 0.
NumRows An integer expression with a value between 1 and 24 that indicates
the number of rows in the window.
NumCols An integer expression with a value between 1 and 80 that indicates
the number of columns in the window.

MSM Language Reference Manual Mnemonic Namespaces • 281

 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.

282 • Mnemonic Namespaces MSM Language Reference Manual

 /WMOVE(Row,Col) - Move Window
Row An integer expression with a value between 0 and 23 that indicates the
row where the window is to be positioned. If this value is invalid or
omitted, a value of 0 is assumed.
Col An integer expression with a value between 0 and 79 that indicates the
column where the window is to be positioned. If this value is invalid or
omitted, a value of 0 is assumed.
This function is used to move the location of an existing window. If the current
window is not window 0, the current window origin (the upper-left corner) is moved
to the locations specified by the Row and Col parameters. As part of the move
function, the screen is refreshed.

/WT(Title,Location,Alignment) - Window Title

Title A string expression to be displayed as the title within the border of
the current window. If this value is invalid or omitted, a title of null is
assumed.
Location An integer value from 0 to 1 that indicates where the title line is to be
displayed within the border of the current window. If this value is
invalid or omitted, a value of 0 is assumed.
0 Displays title at top of window
1 Displays title at bottom of window
Alignment An integer value from 0 to 2 that indicates how the title is to be
positioned within the border line of the current window. If this value
is invalid or omitted, a value of 0 is assumed.
0 Left-justifies the title
1 Centers the title
2 Right-justifies the title
This function is used to specify a title that appears in the border of the current
window. The title can appear at the top or bottom of the window or can be
left-justified, right-justified, or centered within the border.

/WTSGR(Attribute) - Window Title SGR

Attribute An integer value that indicates the type of attribute to be set or cleared.
Refer to the “ZWINTERM Display Attributes” table in this chapter for a
list of the attributes and their values. If this optional parameter is
omitted, a default value of 0 is assumed.
This function is used to set the attributes for the title that appears in the border of the
current window.

MSM Language Reference Manual Mnemonic Namespaces • 283

 /WBSGR(Attribute) - Window Border SGR
Attribute An integer value that indicates the type of attribute to be set or cleared.
Refer to the “ZWINTERM Display Attributes” table in this chapter for a
list of the attributes and their values. If this optional parameter is
omitted, a default value of 0 is assumed.
This function is used to set or clear attributes associated with the border of the
current window.

/WDSGR(Attribute) - Window Default SGR

Attribute An integer value that indicates the type of attribute to be set or cleared.
Refer to the “ZWINTERM Display Attributes” table in this chapter for a
list of the attributes and their values. If this optional parameter is
omitted, a default value of 0 is assumed.
This function is used to set or clear the default attributes associated with the current
window. These default attributes are applied to new lines created at the bottom of a
window when text is scrolled and erased with the /ED and /EL functions. This
function affects the SGR for unused areas of the window.

/WGETCW - Get Current Window

This function returns the identifier (the Win value) for the current window. The
identifier is returned in the $KEY special variable.

/WREFRESH - Refresh Screen

This function is used to refresh the screen. Window 0 and all other windows are
repainted when the function is executed.

/WCMD(Type) - Clear Display

Type An integer value from 0 to 2 that indicates how the erase function is to be
performed. Refer to the “ZWINTERM Erase Attributes” table in this
chapter for a list of the attributes and their values. If this optional
parameter is omitted, a default value of 0 is assumed.
This function is used to erase all or part of the current window. When this function is
used, only the in-memory buffer is updated. The /WDSP function must be used to
make the changes visible to the user.

/WCML(Type) - Clear Line

Type An integer value from 0 to 2 that indicates how the erase function is to be
performed. Refer to the “ZWINTERM Erase Attributes” table in this
chapter for a list of the attributes and their values. If this optional
parameter is omitted, a default value of 0 is assumed.
This function is used to erase all or part of a line in the current window. When this
function is used, only the in-memory buffer is updated. The /WDSP function must be
used to make the changes visible to the user.

284 • Mnemonic Namespaces MSM Language Reference Manual

 /WWR(Mode) - Change Wrap Mode
Mode An integer value from 0 to 1 that indicates how lines of text are to be
handled when the right margin is reached. If this value is invalid or
omitted, a value of 0 is assumed.
0 Sets autowrap on
1 Sets autowrap off
This function is used to set the wrap mode for the current window. If autowrap is on,
a carriage return/linefeed sequence is automatically inserted when a text line reaches
the right margin. If autowrap is off, the line is truncated.

/ZXYMODE(Mode) - XY Mode
Mode An integer value from 0 to 1 that indicates whether the X and Y
coordinates for the CUP mnemonic are interpreted relative to 0 or
relative to 1.
0 X and Y coordinates are relative to 0
1 X and Y coordinates are relative to 1 (the default mode)
In MSM Version 4.0.11, the /CUP mnemonic was corrected (for ZWINTERM
windows only) so that the X and Y coordinates are relative to 1 rather than 0. In
order to support application code that was developed under the old rule, this feature
was implemented to enable the older mode. Using this feature, the coordinates of the
upper left corner of a ZWINTERM window can be either “1,1” (the default mode) or
“0,0”.

/WSC(Scroll) - Change Scroll Mode

Scroll An integer value from 0 to 1 that indicates how lines of text are to be
handled when the bottom of the screen is reached. If this value is
invalid or omitted, a value of 0 is assumed.
0 Sets scroll mode on
1 Sets scroll mode off
This function is used to set the scroll mode for the current window. If scroll mode is
on, lines within the window are moved up when a carriage return/line feed is sent to
the last line of the window. If scroll mode is off, the lines are not moved and text is
written to the last line in the window.

/WCSGR(Attribute,Location) - Window Current SGR

Attribute An integer value that indicates the type of attribute to set or clear. Refer
to the “ZWINTERM Display Attributes” table in this chapter for a list of
the attributes and their values. If this optional parameter is omitted, a
default value of 0 is assumed.

MSM Language Reference Manual Mnemonic Namespaces • 285

 Location An integer from 0 to 6 that indicates where in the current window the
attribute is to be changed. If this value is invalid or omitted, a value of 4
is assumed.
0 Current character
1 From current cursor position to end of line
2 Entire line containing the cursor
3 From current cursor position to end of window
4 Entire window (default)
5 From current cursor position to end of column
6 Entire column containing the cursor
This function is used to change the attributes of text within the current window. The
specified attributes are set or cleared according to the position of the cursor and the
range of the change specified by the Location parameter.

/CUR(Display) - Cursor
Display An integer value from 0 to 4 that indicates actions to be performed on the
cursor within the window. If this value is invalid or omitted, a value of 0 is
assumed.
0 Shows cursor
1 Hides cursor
2 Saves cursor and attributes
3 Restores cursor and attributes
4 Forces cursor and attributes
This function is used to perform cursor actions within the current window. It allows
the programmer to show or hide the cursor, save the cursor location and attributes,
and restore the cursor location and attributes.

/CUP(Row,Col) - Cursor Position

Row An integer expression with a value from 0 to 23 that indicates the row where
the cursor is to be positioned. If this value is invalid or omitted, a value of 0
is assumed.
Col An integer expression with a value from 0 to 79 that indicates the column
where the cursor is to be positioned. If this value is invalid or omitted, a
value of 0 is assumed.
This function positions the cursor to the specified Row and Col position. Positions
are relative to the upper-left corner (row 0, column 0) of the current window.

/ED(Type) - Erase Display

Type An integer value from 0 to 2 that indicates how the erase function is to be
performed. Refer to the “ZWINTERM Erase Attributes” table in this
chapter for a list of the attributes and their values. If this optional parameter
is omitted, a default value of 0 is assumed.
This function is used to erase all or part of the current window. When this function is
executed, both the memory buffer and the screen are updated.

286 • Mnemonic Namespaces MSM Language Reference Manual

 /EL(Type) - Erase Line
Type An integer value from 0 to 2 that indicates how the erase function is to be
performed. Refer to the “ZWINTERM Erase Attributes” table in this
chapter for a list of the attributes and their values. If this optional parameter
is omitted, a default value of 0 is assumed.
This function is used to erase all or part of a line in the current window. When this
function is executed, both the memory buffer and the screen are updated.

/?DR(Char,Repeat) - Line Drawing (optional)

Char An integer from 0 to 12 that indicates which of the line drawing characters
is to be displayed in the current window. If this value is invalid or omitted,
a value of 0 is assumed.
0 Line drawing off
1 Line drawing on
2 Writes horizontal character (-)
3 Writes vertical character (|)
4 Writes character upper-left corner ()
5 Writes character upper-right corner ()
6 Writes character lower-left corner ()
7 Writes character lower-right corner ()
8 Writes intersection character (inverted T)
9 Writes intersection character (T)
10 Writes intersection character (left T)
11 Writes intersection character (right T)
12 Writes intersection character (+)
Repeat An integer value that indicates the number of times the line-drawing
character specified by the Char parameter is written. If this value is invalid
or omitted, a value of 1 is assumed.
This function is used to perform line drawing functions; when it is executed, the
specified character is written at the current cursor location the specified number of
times.

/SGR(Attribute) - Change Character SGR

Attribute An integer value that indicates the type of attribute to set or clear. Refer
to the “ZWINTERM Display Attributes” table in this chapter for a list of
the attributes and their values. If this optional parameter is omitted, a
default value of 0 is assumed.
This function is used to set or clear the specified attribute in the current window. The
attributes are changed in memory and on the screen. This function affects the SGR of
the characters and their cells in the window.

MSM Language Reference Manual Mnemonic Namespaces • 287

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

288 • Mnemonic Namespaces MSM Language Reference Manual

 The WRITE command in this example outputs the actual escape sequence required
by the terminal to position the cursor. The SET command updates the values of $X
and $Y to match the new cursor position. Refer to “MSM Special Variables” in this
manual for additional information on the $X and $Y special variables.

SYSGEN Mnemonic Namespace Options

The following example illustrates how the mnemonic namespace option of the
SYSGEN program is invoked. Detailed examples are provided to illustrate how to
create, edit, and delete namespaces.
Select Option: 13 - Mnemonic Namespaces

Select Mnemonic Namespace Option:

1 - List All Defined Namespaces

2 - Add New Namespace
3 - Copy Namespace To New Name
4 - Edit Existing Namespace
5 - Delete Existing Namespace
6 - Rename Existing Namespace
7 - Export Namespaces
8 - Import Namespaces

Select Option:

List All Defined Namespaces

Use this option to list all of the mnemonic namespaces that are known to the system.
It lists the names of the built-in namespaces as well as the names and definitions of
user-defined namespaces. Specify the output device where the listing is to take place.
The following sample terminal session illustrates the List function.
Select Option: 1 - List All Defined Namespaces

Enter output device <76>: RETURN

Namespace names defined internally to MSM-PC/PLUS:

'X3.64-1979'
'ZWINTERM'

Namespace names defined by SYSGEN:

None.

Select Option:

Add New Namespace

Use this option to create a new mnemonic namespace. Enter a unique identifier that is
to be associated with the namespace, one or more mnemonic names, and the
complete definition for the mnemonic. The following sample terminal session
illustrates the Add function.
Select Option: 2 - Add New Namespace

Enter new Namespace name: ?

Enter the name of a Mnemonic Namespace to be defined. The name can

consist of up to 15 alpha numeric characters.
Enter '^L' for a list of currently defined Namespaces.

Enter new Namespace name: QUME

MSM Language Reference Manual Mnemonic Namespaces • 289

 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"

290 • Mnemonic Namespaces MSM Language Reference Manual

 Mnemonic Set Parms
name $X/$Y Min/Max M Code
-------- ----- ------- ---------
CLEAR --- 0,0 W *27,"Y"
.
.
.

Additional Mnemonic Definitions

.
.
.

Enter mnemonic name: CUP

Does mnemonic change $X <N>: Y
Does mnemonic change $Y <N>: Y
Enter minimum number of parameters <0>: 2
Enter maximum number of parameters <2>: 2
Enter M code for performing mnemonic function
> W *27,$C($1+31),$C($2+31) S $Y=$1,$X=$2

Mnemonic Set Parms

name $X/$Y Min/Max M Code
-------- ----- ------- ----------------------------
CUP $X,$Y 2,2 W *27,$C($1+31),$C($2+31)
S $Y=$1,$X=$2
Enter mnemonic name: ^L

Mnemonic Set Parms

name $X/$Y Min/Max M Code
-------- ----- ------- ----------------------------
BLINK --- 0,0 W *27,"G2"
CLEAR --- 0,0 W *27,"Y"
CUP $X,$Y 2,2 W *27,$C($1+31),$C($2+31)
S $Y=$1,$X=$2
REVERSE --- 0,0 W *27,"G4"
UNDERLINE --- 0,0 W *27,"G8"

Enter mnemonic name: RETURN

Select Option:

Copy Namespace to New Name

Use this option to copy an existing mnemonic namespace to a new mnemonic
namespace (that is, create a new namespace which is identical to an old namespace).
This option generally is used when the new namespace is very similar to the old one.
After the new namespace is created, it can be edited.
Enter the name of an existing namespace and for a unique identifier to be associated
with the new namespace. The following sample terminal session illustrates the Copy
function.
Select Option: 3 - Copy Namespace To New Name

Select Namespace to be copied: ?

Enter the name of the Mnemonic Namespace to be copied. The name you
choose must be defined, but cannot be a built-in Namespace.
Enter '^L' for list of currently defined Namespaces.

Select Namespace to be copied: ^L

Namespace names defined internally to MSM-PC/PLUS:

'X3.64-1979'
'ZWINTERM'

MSM Language Reference Manual Mnemonic Namespaces • 291

 Namespace names defined by SYSGEN:
'Q102'

Select Namespace to be copied: Q102

Enter new Namespace name: Q105

.....! done.

Select Option:

Edit Existing Namespace

Use this option to edit one or more mnemonic definitions within an existing
mnemonic namespace or to add new mnemonic definitions to an existing mnemonic
namespace. Enter the name of an existing namespace and a mnemonic identifier. If
the identifier exists, the system prompts you to enter editing information. If it does
not exist, the system prompts you for the information necessary to create the entry.
The following sample terminal session illustrates the Edit function.
Select Option: 4 - Edit Existing Namespace

Select Namespace to edit: ?

Enter the name of an existing Namespace to be edited. You will be

allowed to create new mnemonics for this Namespace, or edit or
delete existing ones.
Enter '^L' for list of currently defined Namespaces.

Select Namespace to edit: ^L

Namespaces defined internally to MSM-PC/PLUS:

'X3.64-1979'
'ZWINTERM'

Namespaces names defined by SYSGEN:

'QUME'

Select Namespace to edit: QUME

Enter mnemonic name: ?

Enter name of mnemonic to be edited, added, or deleted.

To delete a mnemonic, prefix it with a '-'.
Enter '^L' for a display of defined mnemonics.
Mnemonic name format is:
1 to 15 characters,
Leading character is limited to a letter or '?'
Remaining characters may be a letter or numeric
Enter '^' to exit.

Enter mnemonic name: ^L

Mnemonic Set Parms

name $X/$Y Min/Max M Code
-------- ----- ------- ----------------------------
BLINK --- 0,0 W *27,"G2"
CLEAR --- 0,0 W *27,"Y"
CUP $X,$Y 2,2 W *27,$C($1+31),$C($2+31)
S $Y=$1,$X=$2
REVERSE --- 0,0 W *27,"G4"
UNDERLINE --- 0,0 W *27,"G8"

292 • Mnemonic Namespaces MSM Language Reference Manual

 Enter mnemonic name: EL
Does mnemonic change $X <N>: N
Does mnemonic change $Y <N>: N
Enter minimum number of parameters <0>: 0
Enter maximum number of parameters <0>: 0
Enter M code for performing mnemonic function
> W *27,"[G1"

Mnemonic Set Parms

name $X/$Y Min/Max M Code
-------- ----- ------- --------------------
EL --- 0,0 W *27,"[G1"

Enter mnemonic name: UNDERLINE

Does mnemonic change $X <N>: N
Does mnemonic change $Y <N>: N
Enter minimum number of parameters <0>: 0
Enter maximum number of parameters <0>: 0

Edit M code for mnemonic:

> W *27,"G8"
Replace: G8 With: G9 Replace: RETURN
> W *27,"G9"
Replace: RETURN

Mnemonic Set Parms

name $X/$Y Min/Max M Code
-------- ----- ------- --------------------
UNDERLINE --- 0,0 W *27,"G9"

Enter mnemonic name: RETURN

Select Option:

Delete Existing Namespace

Use this option to delete a user-defined namespace. The system does not allow
built-in namespaces to be deleted. Enter the name of the namespace to be deleted.
The following sample terminal session illustrates the Delete function:
Select Option: 5 - Delete Existing Namespace

Select Namespace to be deleted: ?

Enter the name of the Mnemonic Namespace to be deleted.

Enter '^L' for list of currently defined namespaces.

Select Namespace to be deleted: ^L

Namespace names defined internally to MSM-PC/PLUS:

'X3.64-1979'
'ZWINTERM'

Namespace names defined by SYSGEN:

'Q102'
'Q105'

Select Namespace to be deleted: Q105

Are you sure <N>: Y

Deleting........done.

Select Namespace to be deleted: RETURN

Select Option:

MSM Language Reference Manual Mnemonic Namespaces • 293

 Rename Existing Namespace
Use this option to rename a user-defined namespace. The system does not allow
built-in namespaces to be renamed. Enter the old and new names of the namespace.
The following sample terminal session illustrates the Delete function.
Select Option: 6 - Rename Existing Namespace

Select Namespace to be renamed: ?

Enter the name of the Mnemonic Namespace to be renamed.

Enter '^L' for list of currently defined namespaces.

Select Namespace to be renamed: ^L

Namespace names defined internally to MSM-PC/PLUS:

'X3.64-1979'
'ZWINTERM'

Namespace names defined by SYSGEN:

'Q102'
'Q105'

Select Namespace to be renamed: Q102

Enter new Namespace name for 'Q102': QUME

.....! done.

Select Option:

Export Namespaces
Use this option to save a user-defined namespace to an external file so that it can be
copied to another system. Enter an output device and select the namespaces to be
exported. The following sample terminal session illustrates the Export function.
Select Option: 7 - Export Namespaces

Enter output device <HFS>: RETURN

File Name: QUME.NAM
Enter size of save medium (if applicable): RETURN
Enter comment for dump header: Namespaces for QUME crts

Mnemonic namespace selector: Q102

Mnemonic namespace selector: Q105

Saving ...

^SYS
^SYS

Save complete.

294 • Mnemonic Namespaces MSM Language Reference Manual

 Import Namespaces
Use this option to load user-defined namespaces from an external file that was
created by the Export Namespaces option. Enter the input device. The following
sample terminal session illustrates the Import function.
Select Option: 8 - Import Namespaces

Enter input device <HFS>: RETURN

File Name: ANSI.NAM
Mnemonic namespace(s) saved at 1:20 PM 27-JUL-97.
Header comment is: ANSI X3.64 Template Mnemonic Namespace

Selective restore <N>: ?

If you chose selective restore, you will be prompted for each

Mnemonic Namespace. You must then respond to each prompt to restore
the Namespace or skip to the next one.
Enter NO to restore all mnemonic Namespaces that were saved.
Enter ^ to exit without restoring any Mnemonic Namespaces.

Selective restore <N>: RETURN

Restoring...
Mnemonic Namespace: X3.64 TEMPLATE ... Restored
Restore Complete

MSM Language Reference Manual Mnemonic Namespaces • 295

296 • Mnemonic Namespaces MSM Language Reference Manual
User-Defined Commands

Overview
This chapter describes how to write user-defined commands, functions, and special
variables in MSM.

Commands, Functions, and Special Variables

MSM provides a mechanism that allows system administrators to define their own
commands, functions, and special variables. This enables the system administrator to
extend the M language where special functionality is needed. This often is useful
when converting from another dialect of M to MSM.
All user-defined commands, functions, and special variables must begin with a prefix
of ZZ (for example: ZZMYCMD, ZZMYFUNC). The syntax for user-defined
commands is as follows:
Commands ZZUname{:Postcond}SP{{Parm1} ... {:Parmn}}
Functions $ZZUname({Parm1}{,...{,Parmn}})
Variables $ZZUname
In these examples, Uname is the user-defined name for the command, function, or
special variable, and Parm1 through Parmn are parameters to be passed to the
command or function. The entire name must be specified when the command or
function is invoked or the special variable is referenced. Abbreviations are not
allowed.
User-defined commands are stored in the %ZZCMNDS routine, functions are stored
in the %ZZFUNCS routine, and special variables are stored in the %ZZSVARS
routine. These routines reside in the manager's UCI (MGR) on the system volume
group (volume group 0). When the system encounters a user-defined command,
function, or special variable, the appropriate routine is invoked at the Uname label (a
label in the routine that exactly matches the user-defined name of the command,
function, or special variable). If a match is not found, then the command, function, or
special variable is considered undefined.

MSM Language Reference Manual User-Defined Commands • 297

 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.

298 • User-Defined Commands MSM Language Reference Manual

Passing Parameters to the Routine
When parameters are specified on user-defined commands or functions, they are
passed to the M routine using special MSM internal variables. These variables are $0
through $9. The $0 variable contains a count of the number of parameters specified
on the user-defined command or function; $1 corresponds to the first parameter, $2
corresponds to the second parameter, and so on. Omitted parameters are passed as
the null string. These internal variables are read-only and cannot be modified by the
user routine. For user-defined special variables, the value of $0 is always 0.
For user-defined commands, the colon (:) is used as the separator between
parameters. The parameters are passed to the user routine as strings. No evaluation of
the parameters is performed by the system. The user routine is responsible for
performing indirection or XECUTE to evaluate any expressions contained in the
parameters. For user-defined functions, the comma (,) is used as the separator
between parameters. The parameters are evaluated as expressions, and the results of
the evaluation are passed to the user routine. Although user-defined special variables
behave like user-defined functions, parameters may not be specified.

Examples
The following examples illustrate, in sequence, a user-defined command, function,
and special variable.
%ZZCMNDS ;User-Defined Commands
;
SHELL ;Syntax: ZZSHELL with no operands
ZT:$0>0 "SHELL"
N X
I $ZV["PC" S X=$$TERMINAL^%HOSTCMD("COMMAND") Q
I $ZV["UNIX" S X=$$TERMINAL^%HOSTCMD("sh") Q
I $ZV["VX" S X=$$TERMINAL^%HOSTCMD("spawn") Q

%ZZFUNCS ;User-Defined Functions

;
ACIR() ; area of a circle of radius $1
;Syntax: $ZZACIR(radius)
I $0'=1 Q -1 ; 1 parameter only
Q $1*$1* 3.1415965 ; r*r*pi

%ZZSVARS ;User-Defined Variables

;
TIME() ; $ZZTIME=current time
NEW
D INT^%D,INT^%T
Q %DAT1 " " %TIME
1

MSM Language Reference Manual User-Defined Commands • 299

300 • User-Defined Commands MSM Language Reference Manual
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 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.
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.

MSM Language Reference Manual Macro Facility • 301

Definitions
Directive
A directive is a command to the preprocessor. An equivalent term is preprocessor
command. Refer to “Preprocessor Directives” in this chapter for a description of all
directives.

Keyword
A keyword is a macro that expands to multiple lines of code. Because of its multiple-
line definition, it has an alternative syntax and restrictions and is given its own
conceptual category. However, it is essentially a multi-line macro.

Library
A library is a pre-constructed collection of macro definitions that can be incorporated
together into a source code file by using a single directive. Directives that are related
to libraries are described in “Advanced Capabilities” in this chapter.

Macro
A macro is a symbolic name for a string of text. The macro definition defines the
symbolic name and its associated text string. The macro reference refers to the
symbolic name, which the preprocessor replaces with a definition string.
Parameterized macros allow substrings in the definition string to be substituted with
corresponding arguments

Source
A source is an M routine or other document stored in a global.

Syntax
The elements of preprocessor syntax include macro names, special prefixes, case, and
parameter names.

Macro Names
Macro names are composed of one or more alphanumeric characters.

Special Prefixes
Macro names are referenced by using a special introducer prefix that has a default
value of %%. For example, a macro named Maximum is used by placing
%%Maximum in M code. If parameterized, the string of actual arguments is
parenthesized and passed positionally.
Preprocessor directives are recognized by the presence of the directive prefix as the
first non-blank character of a line. This prefix is the character # (pound sign or hash
sign). The primary preprocessor command, #define, is used to define macros.

302 • Macro Facility MSM Language Reference Manual

 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.

MSM Language Reference Manual Macro Facility • 303

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(1997,1998)."

which expands to:

W "Program ABC Copyright Micronetics Design Corporation 1997-1998."

Most simple macros can appear in the middle of a line, surrounded by other code.
However, macros that expand to multiple lines of code cannot appear in the middle
of a line (for example, within the scope of a single-line If or For command; if they are
used in this way, a comment is placed in the generated routine to indicate an error).
Macros on lines within block-structured subroutines retain the specified execution
level (as indicated by leading dots), as do all generated lines if the macro expands to
multiple lines.

304 • Macro Facility MSM Language Reference Manual

 An alternate keyword prefix #% may be used to refer to macros. In this case,
parameters are passed as comma-delimited arguments rather in a parenthesized
parameter list. This produces a "keyword" command with arguments. The following
are equivalent:
%%copyright(1995,1996)

and
#%copyright 1995,1996

The #% prefix is intended for use with macros which expand to multiple lines. The
syntax is a reminder that such a multi-line macro should not be embedded in another
line, though there are also other safeguards which prevent this error. Use of the #%
syntax is a matter of preference; the %% prefix may be used everywhere.

Using Parameters
The number of actual parameters present when a macro is expanded is provided in
$0. The default names for parameters are $1, $2, and so on, although alphanumeric
names can be used. The full list of all the parameters supplied to the macro is
provided in $*.
If alphanumeric names are used for formal parameters, the names must not conflict
with real variable names that might be passed as parameters. The use of a naming
convention prevents such conflicts.
The formal list can specify fewer parameters than in the definition, or none at all.
However, the macro definition must have at least (); without the parentheses, a macro
that takes no arguments is defined.
Arguments without formal names that are passed during macro use are assigned
names in the $n form.
When a macro is used, if more actual arguments are specified than are used in the
definition, the macro expansion generates an error in comment form.
The following illustrates using parameters in a macro:
#define EXAMPLE() W "No params=$0 Param 1=$1 All params=$*",!

Then the macro %%EXAMPLE("Test",1,2) expands to:

W "No params=3 Param1=""Test"" All params=""Test"",1,2",!

Using named parameters is just a case of specifying them on the macro definition, for
example:
#define EXAMPLE2(one,two) W "First param=",one,!,"Second param=two",!

Then %%EXAMPLE2(1,2) expands to:

W "First param=",1,!,"Second param=2",!

Note that the 'two' parameter is replaced inside the quoted string so make sure any
parameter names are not accidentally contained within part of a string in the
definition.

MSM Language Reference Manual Macro Facility • 305

 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 23Mar98 9:49pm

306 • Macro Facility MSM Language Reference Manual

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

MSM Language Reference Manual Macro Facility • 307

 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

308 • Macro Facility MSM Language Reference Manual

 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

MSM Language Reference Manual Macro Facility • 309

 Additional Parameter Functions
In addition to the parameter capabilities discussed in “Using Parameters” in this
chapter, the preprocessor provides the following advanced parameter functions.

Default Parameter Values

Default values can be given to parameters on macro definitions. These values are
used if no actual argument is present when the macro is used. The default is specified
after the parameter, which is followed by a colon (:). For example:
#define Lock(aName,aTimeout:0) L +^LOCKS(aName):aTimeout
%%Lock(Id) generates L +^LOCKS(Id):0

The $0 parameter can be used in conjunction with #if...#endif to generate different

macro definitions, based on the number of arguments passed.

Quoted Parameters
If a formal parameter which is used in a quoted context in a macro definition is
passed an actual argument that contains quotes, it automatically quotes the quotes in
the following argument:
#define show(ref) write "ref"
%%show(Node is ^G("B")) generates W "Node is ^G(""B"")"

Empty Lists
A macro can be defined as having parameters, even if it has not been given
parameters. Such a macro can be used to construct names because the empty "" that
begins the empty argument list signals the macro's end.
For example, to assign one prefix to a group of names while allowing the prefix to be
easily changed, a parameterized macro is defined for the prefix.
#define prefix() ^%App
#define nam %%prefix()nam
#define id %%prefix()id
D %%nam,%%id generates D ^%Appnam,^%Appid

This system can be built entirely with non-% names by removing the % from the
definition of %%prefix.
The same process can be used to build variables with unique names. For example, in
routines that must deal with by-reference arguments (which refer to variables that
potentially have any name), variable names that are unlikely to collide can be
defined.
#define junk() xYzZy
#define from %%junk()1
#define to %%junk()2
S (%%from,%%to)="" generates S (xYzZy1,xYzZy2)=""

310 • Macro Facility MSM Language Reference Manual

 Multi-Line Definitions
A multi-line macro definition is bracketed by #define and #enddef directives.
#define MultiLiner
w "line 1"
w "line 2"
#enddef

Multi-line macros are non-embeddable. They cannot be embedded in a line of code,

because unpredictable consequences may result when part of a line is at the
beginning of the code and a bit is at the end, several lines below. Even a single-line
macro can be defined as non-embeddable (for example: a macro that contains an IF
statement may cause problems). A #define...#enddef construct allows definition of a
non-embeddable single-line macro.
Some macros have multi-line definitions, although the resulting definition expands
into a simple statement that should be embeddable. For example, when
#if...#else...#endif logic is used to compute a macro definition which has multiple
alternatives, a #define...#enddef block is required to incorporate the #if logic. To
allow inclusion of such a macro within a line of code (rather than making it non-
embeddable), a switch is introduced. The /EMBED switch is used to make a macro
with a multi-line definition embeddable. For example:
#define Disable(Obj) /EMBED
#if $L("Obj",".")<3
%%Set(Obj.ACTIVE,0)
#else
%%Enable(obj,0)
#endif
#enddef

Computed Definitions
A program can be used to build arbitrarily complex macro definitions. The program
is invoked with the null macro and the result is returned in variable Val. For example:
#define Do(win,parms:"") %%(D Do^UTL(win,parms))
UTL ;
Do(w,p) ; compute macro
...
S Val="whatever"
Q

If the default value "" for parameters is not included and if parameters are omitted in
a 1- argument call, a syntax error results from D Do^UTL(win,). If the default value is
used, such an error is impossible.

System Functions
The following functions are defined in the macro preprocessor and can be used by
macros that compute their own definitions.

Function Description
DEFINED(Name) Returns True if macro Name is defined.
SS(X) Strips leading spaces.*
STS(X) Strips trailing spaces.*
QQ(X) Quotes—double-up quotes.*
HQ(X) Halves quotes.*

* May also be called as a procedure with parameter X passed by-reference.

MSM Language Reference Manual Macro Facility • 311

 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

312 • Macro Facility MSM Language Reference Manual

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.

MSM Language Reference Manual Macro Facility • 313

 #define
Defines a macro.

Syntax
#define MacroName[ParmList] Definition
or
#define MacroName[ParmList] [/Switch]...
Definition
...
#enddef

Definition
Parameter Definition
MacroName An alphanumeric name that begins with an alphabetic character; any
reasonable length can be used.
ParmList ([Parm,...]) where Parm is an optional formal name for a parameter.
Definition The macro definition; requires #endef form if null or multi-line.
Switch One of the defined switches:
/EMBED allows embedding of a multi-line definition.

The #define directive defines a simple text-replacement macro that is unaware of M

syntax. It may be abbreviated as #def.
A macro can have either no parameters or a variable (one or more) number of
parameters. If a macro is defined with no ParmList, it cannot take parameters. A
ParmList with no parameters is allowed ("()"), which indicates that parameters are
expected. Any parameter can be missing. Parameters are placed in $1, $2, and so on.
The $0 always contains the number of parameters actually passed.
If the Definition contains macro names and preprocessor directives, they are not
processed until the macro is used.
Meaningful formal names of parameters optionally can be specified for more
self-documenting macros.
The same MacroName can be defined more than once. The definitions are stacked,
and the most recently specified definition of a MacroName is used. As a result,
specialized libraries and local definitions can override system definitions.
A multi-line macro definition requires use of a #def…#enddef block. See
“Multi-Line Definitions” for more information.

314 • Macro Facility MSM Language Reference Manual

 #deflabel
Defines a unique local label or variable, and is guaranteed to be unique in a routine
as long as the prefix is not used directly.

Syntax
#deflabel LabelName[,...]

Definition
Parameter Definition
LabelName A valid macro name.

A macro definition that consists of a defined label prefix, followed by an integer, is

computed for LabelName. The prefix defaults to zTmp and can be modified by
setting system variable LabPref.

#if, #elseif, #else, #endif

Provides for conditionally included code, based on a preprocessing-time condition.

Syntax
#if Condition
Code
#elseif Condition
Code
#else
Code
#endif

Definition

Parameter Definition
Condition A valid M expression
Code Valid M code

During preprocessing, sections of code can be conditionally included or ignored. The

#if...#endif pair brackets code that is included only if Condition is true. For example,
a variable that is set by an earlier #x command can be tested by an #if. Multiple
alternatives are included by using multiple #elseifs, and a catch-all condition is
included by using #else. Conditions can be nested.

MSM Language Reference Manual Macro Facility • 315

 #ifdef, #ifndef
Provides for conditionally included code, based on the presence or absence of a
defined macro.

Syntax
#ifdef MacroName
or
#ifndef MacroName
Code
#else
Code
#endif

Definition
Parameter Description
MacroName A valid M expression.
Code Valid M code.

During preprocessing, sections of code can be conditionally included or ignored. The

#ifdef...#endif pair brackets code that is included only if MacroName is defined.
Alternatively, the #ifndef...#endif pair brackets code is included only if MacroName
is not defined. Alternate code is included when #else is used.

#include
Includes source code; redirects input stream.

Syntax
#include FileName

Definition
Parameter Description
FileName The name of a file.

During preprocessing, a selected file is scanned and processed. A file can include
other files by reference with the #include directive. The input stream comes from the
included file until the end is reached; it then reverts to the line after the #include in
the original file. The #includes can be nested.
FileName generally is a simple name that refers to the latest version of the source
with that name (which is stored in the corresponding node of the source global).
Alternatively, FileName can be a full global reference. If the last subscript of the
global reference is * (asterisk), the greatest subscript is substituted, thereby
simulating use of the latest version.

316 • Macro Facility MSM Language Reference Manual

 #library
Specifies the path to libraries.

Syntax
#library [+]LibraryFileName,...
or
#library LibraryFileName[+],...

Definition
Parameter Description
LibraryFileName The name of a libraryfile in ^ZMSMMACSRC, or a full global
reference whose descendant nodes are the macros.

This command specifies libraries in the order which they are to be searched when a
macro definition is looked up. The presence of [+] modifies the existing search path,
so +LibraryFileName appends and LibraryFileName+ prepends the library to the
existing path. If [+] is not present, the path is entirely respecified.
Libraries are constructed by sources using the #makelib or #updlib directives.

#makelib
Creates a macro library.

Syntax
#makelib LibraryName [GlobalReference]

Definition
Parameter Description
LibraryName The name of the macro library; the default is the current source
name.
GlobalReference The global in which to store the library; the default is
^ZMSMMAC.

The #makelib command initiates the creation of a macro library. Macro libraries are
stored in GlobalReference(LibraryName,1).
The #makelib command first clears the indicated library of all references. During this
process, if the system finds macro definitions that originate from sources other than
the current source, warnings that identify the macro and its original source are
logged.
Subsequent macro definitions then are added to the library. Different sources can
contribute to the same library, but only if #updlib is used.

MSM Language Reference Manual Macro Facility • 317

 #nocomment
Stops the inclusion of unprocessed source code lines as comments.

Syntax
#nocomment

Definition
This command turns off the generation of comments that document the pre-expansion
form of lines with macros. It also applies to lines that sequentially follow the
#nocomment command. See also #comment.

#noroutine
Prevents generation of an M routine.

Syntax
#noroutine

Definition
The #noroutine command turns off the generation of an M routine by the
preprocessor. This command is placed at the top of sources that are used as include
files (such as header files) and files that are used to build macro libraries. See also
#routine.

#prefix
Defines the prefix used to identify a macro reference.

Syntax
#prefix [Literal]

Definition
Parameter Description
Literal A character string to serve as the macro introducer. If omitted, the
default prefix is reset.

This advanced command defines the prefix that is used to introduce macro
references.
The user can override the default, "%%", if a different prefix is preferred. For
example:
#prefix ~
#prefix $$$
#prefix {MACRO}

318 • Macro Facility MSM Language Reference Manual

 The #prefix command also can temporarily deactivate macro definitions (for
example, if an application generates programs that include macro definitions and
references which are to be preprocessed later, rather than during program
generation). Each macro definition in a library must have access to the context of the
prefix's definition. A library's default prefix is assumed to apply to every macro in the
library that does not record an override of the prefix.

#routine
Specifies the name of a routine to be generated.

Syntax
#routine RoutineName

Definition
Parameter Description
RoutineName A valid M routine name.

This command names the routine to be generated when a source program is

preprocessed. If the command is not present, the first-line label determines the
routine name. This command primarily is used to generate a different routine than the
one named by the first line. See also #noroutine.

#undefine
Removes a macro definition.

Syntax
#undefine MacroName

Definition
Parameter Description
MacroName A valid M expression.

This command removes the current definition of a macro name. This unstacking
process can either uncover and reinstate an earlier definition of the same macro
name, or reveal a library macro that was overlaid by a local definition.
This directive may be abbreviated as #undef.

MSM Language Reference Manual Macro Facility • 319

 #updlib
Updates a macro library.

Syntax
#updlib LibraryName [GlobalReference]

Definition
Parameter Description
LibraryName The name of the macro library; the default is the name of the current
source.
GlobalReference The global in which to store the library; the default is ^ZMSMMAC.

The #updlib command updates a macro library. Macro libraries are stored in
GlobalReference(LibraryName,1).
The #updlib command first clears the indicated library of references that originates
from the current source, leaving all libraries from other sources untouched.
Subsequent macro definitions are then added to the library. Different sources can
contribute to the same library when #updlib is used. When a library is to be defined
by a single source, consider using #makelib.

#x
Executes M code during preprocessing.

Syntax
#x Code

Definition
Code Valid M code.
During preprocessing, lines of M code can be executed. This command is used to set
and inspect variables or to generate code for output.

320 • Macro Facility MSM Language Reference Manual

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

MSM Language Reference Manual Macro Facility • 321

322 • Macro Facility MSM Language Reference Manual
Glossary

ANSI
The $merican 1ational 6tandard ,nstitute.

argument
An expression that controls the type of action that is to occur in the function or
command with which it is used.

array
An organized set containing local or global elements that are referenced by
subscripts and a common variable name.

ASCII
The $merican 6tandard &ode for ,nformation ,nterchange. This code consists of 128
characters which comprise the standardized character set.

background job
A job started by the JOB command. This process runs in parallel with the process
that contained the JOB command.

baud
The data transmission rate between two devices.

Big-Endian
A term that identifies 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 used to interrupt program execution so that debugging can occur.

MSM Language Reference Manual Glossary • 323

 Canonic number
A numeric value that 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 or ENTER.

collating sequence
An order that is assigned to a group of subscripts, sorted in either string or numeric
sequence.
string - All subscripts are treated as character strings and are stored in ASCII
sequence.
numeric - 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 a routine that describes when the routine was written, its purpose,
and similar information. A comment is a non-executable line of code that begins
with a semicolon (;).

compiler
A 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.

concatenation
The process of joining two operands together to form a new string. This is
accomplished by appending operand 2 to the end of operand1 by using the underscore
(_) symbol.

CONFIG.MSM
A file in the root or 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.

324 • Glossary MSM Language Reference Manual

 control characters
Standard ASCII characters that have special meaning to MSM. These characters are
obtained by pressing the CTRL key while simultaneously pressing the associated
control character.

cursor
The on-screen marker, usually a box or an underline, that indicates the location
where the next data entry is to occur.

data
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 is installed (database 0).

default
A value that is assumed as the entry to a prompt if the carriage return is pressed. In
MSM, default values are displayed within greater than (>) and less than (<) signs
(for example: <DEFAULT>).

descendant
Any array node on a lower subscript level that is can be reached from the 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 that yields a value upon execution.

function
An action that streamlines routine operations. In MSM, a function begins with a
dollar sign ($), or with a dollar sign and the letter Z ($Z) for specialized M functions.

global
A permanent storage medium used by M. Information is stored in a global array or a
simple global variable and generally is placed on a disk system.

MSM Language Reference Manual Glossary • 325

 global variable
A reference name for data stored in a global on the disk. Any user with the proper
protection level can access or change these variables.

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.

increment
An amount by which an incremental process (such as a FOR loop) is increased.

indirection
A method of using the value of an expression rather than the expression itself.
Indirection is symbolized by the at-sign (@), followed by the value that represents
the expression.

integer
Any expression that evaluates to an integer value.

interpreter
A component of MSM system that processes the pseudo-machine code generated by
the compiler.

intrinsic function
An action that streamlines routine operations. In MSM, an intrinsic function begins
with a dollar sign ($), or with a dollar sign and the letter Z ($Z) for specialized M
functions.

job
Any use of the MSM system that requires a partitioned work space.

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. This option does not apply to single-user versions of MSM.

last
An integer expression that specifies the ending occurrence of the substring to
retrieve.

326 • Glossary MSM Language Reference Manual

 length
An indicator that specifies the size of memory area to be accessed.

level
An integer expression that specifies the level of source code to be retained when
performing a ZSAVE.

line
A string of characters that end with a specified READ terminator (carriage
return/line feed).

line label
An optional name at the beginning of a routine line that identifies that line to MSM.
This label is limited to eight characters and must begin with an alphabetic or percent
(%) character.

line reference (LineRef)

A reference that specifies the location within the routine where insertion is to occur
when using ZINSERT.

literal
A string, enclosed in quotations, that can be acted upon but not changed by a
command. Although the literal may contain any valid ASCII character, some ASCII
characters may be excluded because they have special meaning to MSM.

local variable (LocalVar)

A symbolic name assigned to a data value that exists only for the duration of the
terminal session or routine that creates it. Local variables are unique to each
partition.

map block (map)

A disk block that contains a list of block ownership. Each map governs 512 blocks
(each 1024 bytes in size).

mask
An integer expression that identifies the Boolean operation to be performed on one
or more strings. It is used in $ZBOOLEAN.

mnemonic namespace
Mnemonic values that are used to control various functions. Each namespace
generally is associated with a device or class of device.

MSM Language Reference Manual Glossary • 327

 M(UMPS)
The 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.

name
A routine, local, or global variable name.

naked reference
A shortcut method for referring to a global node. The naked reference generally can
be used wherever a global reference is permitted. To specify a naked reference for a
previously referenced node, use a circumflex (^), followed by the unique portion of
the descendant's subscript.

node
A global or local array component addressed by a common name and a unique
subscript.

operating system monitor

A system that provides an interface between the host operating system and MSM.
The monitor also 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 must be entered in order to access programmer mode.
One PAC can be specified for each configuration on the system.

parameters
A collection of guidelines for using a particular device.

partition
An area of memory that 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 expands and shrinks based on the requirements of the current job.

peripherals
Physical and logical devices that are associated with the MSM system. They are used
to access printers, terminals, and sequential devices, and to examine or modify
memory contents or alternate disk storage.

328 • Glossary MSM Language Reference Manual

 programmer mode
A system mode that enables you to directly enter M commands to the interpreter.
You must enter a valid UCI and programmer access code (PAC) in order to access
programmer mode.

prompt
A system-generated message that requires user input.

remote volume group (RVG)

A volume group that belongs to a remote system, but is mounted for use on the local
system. Use Distributed Data Processing (DDP) to access the volume group.

routines
library routines - Utility programs that are accessible to all system users.
system manager routines - Utility programs that can be accessed only via the
Manager’s UCI (MGR).

run mode
A method of directly accessing a routine in a specific UCI. To access run mode, you
must enter a valid UCI and the name of a routine that is stored in the UCI.

sparse
An array that contains space only for defined elements.

special variables
A group of variables ($ZA, $ZB, and $ZC) hat has special meaning to MSM and is
used to specifiy 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.

MSM Language Reference Manual Glossary • 329

 subroutine
A collection of commands that allow control to pass from a routine to a subroutine
and back to the main routine. Subroutines generally are used when multiple recurring
tasks are required to execute the main routine.

subscript
A numeric-interpreted or string-interpreted value which is appended to a local or
global variable and which identifies a specific element or node in an array.
Subscripts must be enclosed in parentheses. Multiple subscripts are separated by
commas.

SYSGEN
The system generation utility that is used to define configurations to MSM. At
system startup, MSM uses the configurations to initialize the system with the
specified parameters.

terminator
A set of control characters that is used to terminate a READ operation. MSM uses a
default value of line feed, carriage return ($C(10,13), but allows you to modify this
value by using proper parameters associated with the current device.

tied terminal
A system mode that forces a selected terminal to automatically start up a specified
routine in a UCI.

timeout
A convention that allows you to specify the amount of time MSM should attempt to
perform a given command before continuing. Timeout is expressed in the format of a
colon (:), followed by an integer which then is appended to a READ, OPEN, or JOB
command.

user class identifier (UCI)

A three-letter designation (uppercase) for a work area within MSM. Each UCI has a
unique routine and global directory.

utilities
library utilities - A group of utilities that supply commonly performed functions.
system manager utilities - Utilities that are intended for use by the system manager to
ensure proper system performance. These utilities can be accessed only from the
Manager’s UCI (MGR).

330 • Glossary MSM Language Reference Manual

 variable
A symbolic name for a location where data is stored. MSM uses the following types
of variables:
global variable - A variable that is stored in arrays for permanent storage on disk.
local variable - A variable that is stored only in memory.
special variable - A variable that holds special meaning to the MSM system.

volume group (VolGroup)

A string value (consisting of threee uppercase characters) that specifies a volume
group name.

volume number (VolNum)

A numeric expression that specifies an internal volume group number.

MSM Language Reference Manual Glossary • 331

332 • Glossary MSM Language Reference Manual
Index

$ $STORAGE special variable, 81, 228

$SYSTEM special variable, 229
$ASCII Function, 140 $TEST special variable, 53, 57, 66, 69, 76, 80, 82, 94,
$CHAR function, 141 96, 107, 230
$DATA function, 89, 129, 142, 248, 249, 250, 251, 252 $TEXT function, 104, 113, 115, 120, 126, 127, 166
$DEVICE special variable, 98, 214, 280 $TLEVEL special variable, 93, 94, 95, 96, 231
$DEVICE structured system variable, 248 $TRANSLATE function, 168
$ECODE special variable, 215, 243, 255 $TRESTART special variable, 93, 95, 232
$ESTACK special variable, 80, 217, 256 $VIEW function, 169
$ETRAP special variable, 80, 219, 255, 256, 257, 260 $X special variable, 86, 98, 102, 233
$EXTRACT function, 89, 90, 143 $Y special variable, 86, 98, 102, 234
$FIND function, 145 $ZA special variable, 50, 98, 127, 235
$FNUMBER function, 146 $ZASCII function, 171
$GET function, 148 $ZB special variable, 69, 98, 127, 236
$GLOBAL structured system variable, 249 $ZBN function, 172
$HOROLOG special variable, 112, 221 $ZBname function, 174
$IO special variable, 222 $ZBOOLEAN function, 177
$JOB special variable, 223 $ZC special variable, 98, 237
$JOB structured system variable, 250 $ZCALL function, 180
$JUSTIFY function, 103, 149 $ZCHAR function, 181
$KEY special variable, 98, 224 $ZCRC function, 182
$LENGTH function, 150 $ZCREATEOBJECT function, 184
$LOCK structured system variable, 251 $ZDATE function, 185
$NAME function, 151 $ZDEVICE function, 186
$NEXT function, 152 $ZERROR special variable, 215, 238, 243, 261
$ORDER function, 154 $ZGETOBJECT function, 187
$PIECE function, 89, 90, 91, 156 $ZHEX function, 189
$PRINCIPAL special variable, 225 $ZHL function, 190
$QLENGTH function, 158 $ZLEVEL special variable, 239
$QSUBSCRIPT function, 159 $ZNAME special variable, 124, 126, 240
$QUERY function, 160 $ZNEXT function, 193
$QUIT function, 226 $ZOBJREFERENCE function, 194
$RANDOM function, 161 $ZORDER function, 195
$REVERSE function, 162 $ZORDER special variable, 241
$ROUTINE structured system variable, 252 $ZOS function, 196
$SELECT function, 57, 91, 163 Error codes, 204
$STACK function, 164, 255 $ZPOSITION function, 205
$STACK special variable, 227 $ZPREVIOUS function, 206

MSM Language Reference Manual Index • 333

$ZREFERENCE special variable, 80, 241, 242 Automation
$ZSORT function, 207 Object, 187
$ZTRAP special variable, 92, 98, 122, 219, 238, 243,
256, 258, 259 B
$ZUCI function, 209
$ZVERIFY function, 210 Background
$ZVERSION special variable, 245 Job, 68
$ZWIDTH function, 212 Binary
Operators, 23
ADDITION, 23, 24
%
AND, 25
%ER utility, 260 CONCATENATE, 23, 26
%ET utility, 260 DIVIDE, 23
DIVISION, 27
: EXPONENTIATION, 23, 29
GREATER THAN, 30
:STRING SORTS AFTER, 47 INTEGER DIVISION, 23, 34
LESS THAN, 35
^ Logical, 21
MODULO DIVISION, 23, 37
^$JOB, 250 MULTIPLICATION, 23, 39
NAND, 25
< NOR, 41
NOT EQUAL TO, 28
<DKHER>, 262 NOT GREATER THAN, 30
<DPARM>, 71 NOT LESS THAN, 35
<UNDEF>, 241 OR, 41
PATTERN MATCH, 23, 42
A Relational, 21
STRING CONTAINS, 23, 45
Acknowledgment, ix STRING FOLLOWS, 23, 46
Actual List, 55, 71, 135, 136, 137, 138 STRING SORTS AFTER, 23, 47
ADDITION operator, 23, 24 SUBTRACTION, 23, 48
Algebraic Bit
Difference, 48 Function, 174
Sum, 24 Manipulation, 177
Ancestor, 76, 89 String, 174
Global, 106 Block
Nodes, 129 Disk, 100
AND operator, 23, 25 Number, 210
ANSI Standard M Boolean
Commands, 49 Operators, 21, 177
Functions, 135 AND, 23
Structured system variable, 247 EQUAL TO, 23
ANSI X3.64-1979 Namespace, 274 GREATER THAN, 23
Argument, 32, 43, 49 LESS THAN, 23
Indirection, 32 NOT, 23
List, 71, 136 OR, 23
Post-conditional, 21 Truth-valued, 21
Arithmetic Bracket symbols, 68
Operators, 21 BREAK command, 50, 111
ASCII Break key, 50, 78
Collating sequence, 253 Buffe
Asterisk, 96, 156 Cache, 110
Atom Building
Expression, 19 Expressions, 19

334 • Index MSM Language Reference Manual

C ZGO, 50, 111
ZHOROLOG, 112
Call-by-reference, 55, 71, 137 ZINSERT, 113, 228
Call-by-value, 55, 71, 136 ZLOAD, 115, 228
Canonic numbers, 47 ZMSM, 117
Character ZNEW, 118
Alphabetic, 42 ZPRINT, 120
ASCII, 140, 141 ZQUIT, 122
Control, 42 ZREMOVE, 124
Format, 86, 102 ZSAVE, 124, 126
Reverse order, 162 ZSETOBJ, 129
Checksum, 182 ZSYNC, 131
Circumflex, 115 ZTRAP, 132
CLOSE command, 52, 98 ZUSE, 133
Code point, 181 ZWRITE, 134
Collating sequence Concatenate, 21
ASCII, 253 Maximum string size, 26
Comma, 146 CONCATENATE operator, 23, 26
Command Constants, 102
BREAK, 50, 111 Conventions
CLOSE, 52, 98 Special variables, 213
Definition, 49 Structured system variable, 247
DO, 53, 68, 217, 227, 239, 243 Copy data. See MERGE command
DO with parameter passing, 55 Cursor
ELSE, 57 Position
FOR, 53, 58, 59, 239 Current horizontal, 233
GOTO, 58, 62, 122, 219, 243 Current vertical, 234
HALT, 52, 64 Cyclic redundancy check, 182
HANG, 65
IF, 57, 66, 230
JOB, 57, 66, 68, 223, 225, 230 D
JOB with parameter passing, 71 Database
KILL, 73 Bullet-proof, 93, 94, 95, 97
LOCK, 57, 64, 66, 75, 230 Restore, 93, 94, 95, 97
MERGE, 78 Date
Naming conventions, 49 And time, 221
NEW, 73, 80, 217, 219 External, 185
OPEN, 52, 57, 66, 82, 230 Debugging, 50, 111
Overview, 49 Interactive, 261
Post-conditional, 21, 22 Device
QUIT, 50, 53, 58, 80, 84, 104, 217, 227, 239 Name, 186
READ, 57, 66, 86, 224, 230 Numbers
SET, 89, 90, 219 Current device, 222
TCOMMIT, 93, 97, 231, 232 Ownership, 82, 98, 133
TRESTART, 94, 232 Principal, 52, 82, 98
TROLLBACK, 95, 231, 232 Read from, 86
TSTART, 94, 96, 97, 231 Release, 52
USE, 98, 222 Directive, 302
User-defined, 297 Disk
VIEW, 100 Block, 100
WRITE, 102 Allocate, 172
XECUTE, 104, 217, 227, 239, 243 Deallocate, 172
ZALLOCATE, 57, 66, 106, 230 Buffer cache, 110
ZALLOCATE, 64 DIVIDE operator, 23
ZDEALLOCATE, 109 DIVISION operator, 27
ZFLUSH, 110

MSM Language Reference Manual Index • 335

DO command, 22, 53, 68, 217, 227, 239, 243 Post-conditional, 21, 57, 230
Argumentless, 53 String, 21
Parameter passing, 55 Truth-valued, 21, 66, 163
Structured subroutine, 53 Types, 20, 21
DO/XECUTE command Numeric, 20
Stack, 50 Post-conditional, 20
Dollar sign, 135, 136 String, 20
Special variables, 213 Truth-valued, 20
External
E Routine calls, 180
Extrinsic
ECHO, 87 Functions, 84, 135
Edit Definition, 136
ZSAVE, 126 Syntax, 136
Editing
ZINSERT, 113
F
ZLOAD, 115
Elements Floating point numbers, 101
Expression, 19 FOR command, 22, 53, 58, 59, 239
ELSE command, 22, 57 Nesting, 60
Endless loop, 59 Scope, 58
Entry With QUIT, 84
Reference, 55, 71, 137, 138 Formal List, 55, 71, 137, 138
Equal sign, 156 Format
EQUAL TO operator, 23, 28 Characters, 87, 103
Error Free space, 228
Codes, 263 Function
$ECODE, 271 $ASCII, 140
ZWINTERM, 280 $CHAR, 141
Messages, 55, 93, 98, 128, 137, 138, 210, 238 $DATA, 89, 129, 142, 248, 249, 250, 251, 252
Numbers, 267 $EXTRACT, 89, 90, 143
Processing, 50, 117, 132, 255 $FIND, 145
Trapped errors, 258 $FNUMBER, 146
User-defined, 257 $GET, 148
Trace, 50, 111, 117 $JUSTIFY, 103, 149
Trapping, 98, 122, 127, 132, 238, 243 $LENGTH, 150
Downlevel, 261 $NAME, 151
ESTACK special variable, 227 $NEXT, 152
Execution $ORDER, 154
Stack, 164 $PIECE, 89, 90, 91, 156
Suspend, 50, 65 $QLENGTH, 158
EXPONENTIATION operator, 23, 29 $QSUBSCRIPT, 159
Expression, 19, 20, 135, 136, 137, 138 $QUERY, 160
Atom, 19 $QUIT, 226
Building, 19 $RANDOM, 161
Elements, 19 $REVERSE, 162
Evaluation, 20, 163, 168 $SELECT, 57, 91, 163
Indirection, 52, 58, 89 $STACK, 164, 255
Left-to-right, 89 $TEXT, 104, 113, 115, 120, 126, 127, 166
Numeric values, 20 $TRANSLATE, 168
Post-conditional, 20 $VIEW, 169
String values, 20 $ZASCII, 171
Truth-valued, 20 $ZB Bit, 174, 175
Integer, 21 $ZBAND, 174
Numeric, 21 $ZBLEN, 175
Conversion, 21 $ZBN, 172

336 • Index MSM Language Reference Manual

 $ZBname, 174 Expression atom, 32
$ZBNOT, 175 Name, 32
$ZBOOLEAN, 177 Pattern, 32
$ZBOR, 175 Subscript, 32
$ZBSET, 175 INDIRECTION operator, 23, 32
$ZBSTR, 175 Input/Output, 214, 222
$ZBXOR, 175 Integer, 21, 140, 141, 145, 150, 210
$ZCALL, 180 Division, 34
$ZCHAR, 181 Expressions, 21
$ZCOUNT, 174 INTEGER DIVISION operator, 23, 34
$ZCRC, 182 Interrupt execution, 50
$ZCREATEOBJECT, 184 Intrinsic
$ZDATE, 185 Functions, 135
$ZDEVICE, 186 Syntax, 135
$ZFIND, 174 Iteration, 60
$ZGET, 175
$ZGETOBJECT, 187 J
$ZHEX, 189
$ZHL, 190 Job
$ZNEXT, 193 Background, 68
$ZOBJREFERENCE, 194 Number, 69, 223, 225, 250
$ZORDER, 195 JOB command, 57, 66, 68, 223, 225, 230
$ZOS, 196 Parameter passing, 71
$ZPOSITION, 205 Journal
$ZPREVIOUS, 206 After-image, 93, 94, 95, 97
$ZSORT, 207
$ZUCI, 209 K
$ZVERIFY, 210
$ZWIDTH, 212 Keyword, 96, 302
Definition, 135 KILL command, 73
Name, 135
User-defined, 297 L
LESS THAN operator, 23, 35
G LESS THAN OR EQUAL TO operator, 30
Global List
Availability, 249 Argument, 136
Reference, 241, 242 Literal
GOTO command, 22, 58, 62, 122, 219, 243 Numeric, 19, 28
GREATER THAN operator, 23, 30 Lock
GREATER THAN OR EQUAL TO operator, 35 Variable, 106
LOCK command, 57, 64, 66, 75, 230
Incremental, 75
H
LOCK table, 75
HALT command, 52, 64 Logoff, 64
HANG command, 65 Loops, 58
Hexadecimal, 169
HEXADECIMAL operator, 23, 31 M
Macro
I
Debugging, 306
IF command, 22, 57, 66, 230 Defining, 304
Indicators Definition, 302
Naked, 142, 148 Facility, 301
Indirection, 32, 54, 129 Library, 302
Argument, 32 Globals, 321

MSM Language Reference Manual Index • 337

 Names, 302 O
Reference, 302
Referencing, 304 Object
Routines, 321 Automation, 187
Special, 308 OLE/2, 187
Mask OPEN command, 52, 57, 66, 82, 230
Value, 146, 168, 177 Operand
Memory As part of command, 49
Access, 100 Operator
Location, 169 ADDITION, 24
MERGE command, 78 AND, 25
MINUS operator, 23, 36 Arithmetic, 21
Minus sign, 146 Binary, 19, 20, 23
Mnemonic controls, 274 Binary logical, 21
Mnemonic namespace, 86, 98, 273 Binary relational, 21
Add, 289 Boolean, 21, 25
ANSI X3.64-1979, 274 CONCATENATE, 21, 26
Copy, 291 DIVISION, 27
Delete, 293 EQUAL TO, 28
Edit, 292 EXPONENTIATION, 29
Export, 294 GREATER THAN, 30
Import, 295 GREATER THAN OR EQUAL TO, 35
Invoking SYSGEN, 289 HEXADECIMAL, 31
List, 289 Indirection, 20
Rename, 294 INDIRECTION, 32
WRITE command, 102 INTEGER DIVISION, 34
ZWINTERM, 278 LESS THAN, 35
MODE flags, 50 LESS THAN OR EQUAL TO, 30
MODULO DIVISION operator, 23, 37 MINUS, 36
MULTIPLICATION operator, 23, 39 MODULO DIVISION, 37
MULTIPLICATION, 39
NAND, 25
N NOR, 41
Naked NOT, 25, 28, 30, 35, 40, 41, 43, 45, 46, 47
Indicators, 76, 78, 89, 95, 96, 106 NOT EQUAL TO, 28
Reference, 142, 160 NOT GREATER THAN, 30
Name NOT LESS THAN, 35
Indirection, 32 NOT OR, 41
NAND operator, 25 OR, 41
Nesting level, 239 PATTERN MATCH, 42
Network PLUS, 44
Flush. See ZSYNC command Relational, 23
NEW command, 73, 80, 217, 219 String, 23
NOR operator, 41 STRING CONTAINS, 45
NOT, 35 STRING DOES NOT CONTAIN, 45
NOT EQUAL TO operator, 28 STRING DOES NOT FOLLOW, 46
NOT GREATER THAN operator, 30 STRING DOES NOT SORT AFTER, 47
NOT LESS THAN operator, 35 STRING FOLLOWS, 46
NOT operator, 23, 25, 28, 30, 40, 41, 43, 45, 46, 47 SUBTRACTION, 48
NOT OR operator, 41 Summary, 23
Null line, 115 Unary, 19, 20, 23
Number Operators
Canonic, 47 Unary, 19
Numeric OR operator, 23, 41, 182
Expressions, 21 Output, 102
Literal, 19, 28

338 • Index MSM Language Reference Manual

P S
Parameter Serialization, 96
Passing, 299 Session
Call-by-value, 136 Terminate, 64
With DO, 55 SET command, 89, 90, 219
With JOB, 71 Source, 302
Parentheses, 96 Special variable
Partition $DEVICE, 98, 214, 280
Size, 69, 228 $ECODE, 215, 243, 255
Passing parameters, 299 $ESTACK, 80, 217, 227, 256
Pattern $ETRAP, 80, 219, 255, 256, 257, 260
Indirection, 32 $HOROLOG, 112, 221
Match, 42, 43 $IO, 222
PATTERN MATCH operator, 23, 32, 42 $JOB, 223
P-code, 126 $KEY, 98, 224
Percent sign, 32 $LEVEL, 239
PLUS operator, 23, 44 $PRINCIPAL, 225
Plus sign, 146 $STACK, 227
Post-conditional $STORAGE, 81, 228
Command, 21, 22 $SYSTEM, 229
Definition, 21 $TEST, 53, 57, 66, 69, 76, 80, 82, 94, 96, 107, 230
Precision, 24, 27, 29, 34, 37, 39 $TLEVEL, 93, 94, 95, 96, 231
Preprocessor $TRESTART, 93, 95, 232
Directives, 301, 313 $X, 86, 98, 102, 233
PRINCIPAL special variable, 82 $Y, 86, 98, 102, 234
Processes. See JOB command $ZA, 50, 98, 127, 235
Program control, 53, 62 $ZB, 98, 127, 236
Programmer character set, 171 $ZB, 69
Pseudo-random, 161 $ZC, 98, 237
$ZERROR, 215, 238, 243, 261
Q $ZNAME, 124, 126, 240
$ZORDER, 241
QUIT command, 50, 53, 58, 80, 84, 104, 217, 227, 239 $ZREFERENCE, 80, 241, 242
Quotient, 27, 34, 37 $ZTRAP, 92, 98, 122, 219, 238, 243, 256, 258, 259
$ZVERSION, 245
R Conventions, 213
Definition, 213
READ command, 57, 66, 86, 224, 230 TEST, 57
Reference User-defined, 297
Entry, 62 SSVN. See Structured System Variable
Extended, 53 Stack
Full, 76, 106 DO/XECUTE, 50
Naked, 89, 151, 160, 206, 207 String
Relational Expressions, 21
Operators, 23 Literal, 86
Resources Operators, 23
Synchronizing, 75 STRING CONTAINS operator, 23, 45
Restarts STRING DOES NOT CONTAIN operator, 45
Transaction, 231, 232 STRING DOES NOT FOLLOW operator, 46
Routine STRING DOES NOT SORT AFTER operator, 47
Availability, 252 STRING FOLLOWS operator, 23, 46
Calling, 53 STRING SORTS AFTER operator, 23, 47
Interruption, 50 Structured system variable, 247
Name, 240 $DEVICE, 248
Save, 126 $GLOBAL, 249

MSM Language Reference Manual Index • 339

 $JOB, 250 User Class Identifer. See UCI
$LOCK, 251
$ROUTINE, 252 V
Conventions, 247
Definition, 247 Value
Subexpressions, 20 Negative, 146
Subroutine Variable, 102
Block structured, 53 Delete, 73
Calling, 53 Global, 78, 89, 106, 109
Subscript, 206, 207 Local, 19, 78, 80, 89, 106, 109
Indirection, 32 Lock, 75, 109
SUBTRACTION operator, 23, 48 Save, 55, 80, 118
Subtransaction, 96 Special, 80, 213
Suspend Stacked, 80
Execution, 50, 65 VIEW command, 100
Symbol Volume
Table, 69, 70, 73, 80, 137 Group, 68, 71, 100, 172, 209, 210, 242
SYSGEN utility, 50, 69 Name, 209
Mnemonic namespace, 289, 291, 292, 293, 294, 295 Number, 209, 210
Add, 289
List, 289 W
SYSGEN, 288
System WRITE command, 102
Error trap, 260
X
T XECUTE command, 22, 104, 217, 227, 239, 243
TCOMMIT command, 93, 97, 231, 232 With QUIT, 84
Terminate
Session, 64 Z
Timeout, 69, 76, 87, 107, 224, 230
Transaction, 93, 94, 95, 96, 131, 231 ZALLOCATE command, 57, 64, 66, 106, 230
Restarts, 231, 232 ZDEALLOCATE command, 109
Trapping Errors, 238 ZFLUSH command, 110
TRESTART command, 94, 232 ZGO command, 50, 111
TROLLBACK command, 95, 231, 232 ZHOROLOG command, 112
Truth value, 230 ZINSERT command, 113, 228
Truth-valued expression, 163 ZLOAD command, 115, 228
TSTART command, 94, 96, 97, 231 ZMSM command, 117
Typeahead, 87 ZNEW command, 118
ZPRINT command, 120
ZQUIT command, 122
U ZREMOVE command, 124
UCI, 53, 68, 71, 75, 115, 126 ZSAVE command, 124, 126
Unary ZSETOBJ command, 129
Operators, 23 ZSYNC command, 131
EQUAL TO, 28 ZTRAP command, 132
HEXADECIMAL, 23, 31 ZUSE command, 133
INDIRECTION, 23, 32 ZWINTERM mnemonic namespace, 278
MINUS, 23, 36 Attributes, 278
NOT, 40 Commands, 281
PLUS, 23, 44 Erase operations, 279
Unicode, 171, 181 Error codes, 280
Unlock, 106, 109 ZWRITE command, 134
USE command, 98, 222

340 • Index MSM Language Reference Manual