MSM-Micronetics Standart Mumps - User's Guide v.4.0 (Micronetics) 1997 Revised

MSM
MICRONETICS STANDARD MUMPS
USER’S GUIDE
Revised
January 1997
Version 4.0
COPYRIGHT  1984-1997
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 manual is copyrighted. All rights are reserved. This document

may not, in whole or part, be copied, photocopied, reproduced, translated
or reduced to any electronic medium or machine readable form without
prior consent, in writing, from Micronetics Design Corporation.
Copyright  1984-1997
Micronetics Design Corporation
1375 Piccard Drive
Rockville, Maryland 20850
Phone: 301-258-2605
Fax: 301-840-8943
E-Mail: info@micronetics.com
WWW: www.micronetics.com
TABLE OF CONTENTS
CHAPTER 1 THE MSM SYSTEM
1.1 System Overview ..................................................... 1-1

1.2 Functional Description ............................................. 1-2
1.2.1 The Language Compiler ........................... 1-3
1.2.2 The Database Management System .......... 1-3
1.2.3 The Operating System Monitor ................ 1-4
1.2.4 The I/O Supervisor ................................... 1-5
1.2.5 The Utility Program Library ..................... 1-5
CHAPTER 2 USING THE MSM SYSTEM
2.1 Supported Terminals ................................................ 2-1

2.2 Terminal Control Characters .................................... 2-1
2.3 Logging onto the System ......................................... 2-4
2.3.1 The User Class Identifier .......................... 2-5
2.3.2 Programmer Mode .................................... 2-5
2.3.3 Run Mode ................................................. 2-6
2.3.4 Tied Terminal Mode ................................. 2-6
2.3.5 Partition Size ............................................. 2-7
2.3.6 Changing UCIs ......................................... 2-7
2.3.7 Remote Volume Group UCIs ................... 2-7
2.4 Logging Off the System ........................................... 2-8
2.5 Creating Routines ..................................................... 2-8
2.6 Editing Routines ....................................................... 2-9
2.6.1 Inserting Lines into a Routine .................. 2-10
2.6.2 Editing Specific Lines .............................. 2-11
2.6.3 Full Screen Routine Editing ..................... 2-11
2.6.4 CUA Style Full Screen Editor .................. 2-12
2.7 Deleting Routines from Disk ................................... 2-12
2.8 Executing Routines .................................................. 2-13
2.8.1 Error Processing ....................................... 2-13
2.8.2 Default Error Processing ........................... 2-14
2.8.3 User Defined Error Processing ................. 2-15
2.8.4 Processing Trapped Errors......................... 2-15
2.8.5 Using the System Error Trap ..................... 2-18
2.8.6 Using Downlevel Error Trapping .............. 2-18
2.8.7 Interactive Debugging .............................. 2-19
iii
TABLE OF CONTENTS
2.9 Programmer Shell ..................................................... 2-19

2.9.1 Obtaining HELP Information ................... 2-20
2.9.2 Command Line Editing ............................ 2-21
2.9.3 Command History ..................................... 2-22
2.9.4 Miscellaneous Shell Commands ............... 2-24
CHAPTER 3 USING PERIPHERAL DEVICES
3.1 Overview .................................................................. 3-1

3.2 Device Designators .................................................. 3-3
3.3 Accessing Peripheral Devices .................................. 3-4
3.4 Input and Output Commands ................................... 3-5
3.5 Special Variables ...................................................... 3-6
3.6 Mnemonic Namespaces ........................................... 3-7
3.7 Terminal Devices ..................................................... 3-8
3.7.1 OPEN, USE, And CLOSE Parameters ..... 3-8
3.7.2 Escape Processing ..................................... 3-18
3.7.3 $ZA, $ZB, and $ZC Information .............. 3-20
3.7.4 Terminal Device Examples ....................... 3-22
3.8 Sequential Block Processor ...................................... 3-23
3.8.3 Sequential Block Processor Examples ..... 3-27
3.9 VIEW Device ........................................................... 3-28
3.9.3 VIEW Device Examples ........................... 3-30
3.10 Host File Server ........................................................ 3-31
3.10.3 HFS Device Examples .............................. 3-36
3.11 Interjob Communication .......................................... 3-37
3.11.3 Interjob Communication Examples .......... 3-40
3.12 Routine Interlocks .................................................... 3-41
iv
TABLE OF CONTENTS
3.13 Magnetic Tape .......................................................... 3-42

3.13.2 Write Commands ...................................... 3-47
3.13.4 Magnetic Tape Device Examples ............. 3-52
3.14 Spool Device ............................................................ 3-53
3.14.1 OPEN, USE, and CLOSE Parameters ...... 3-54
3.14.3 Spool Device Examples ............................ 3-58
3.15 Host System Spool Device ....................................... 3-59
3.15.1 OPEN, USE, and CLOSE Parameters ...... 3-60
3.15.3 Host System Spool Device Examples ...... 3-62
CHAPTER 4 MSM UTILITY PROGRAMS
4.1 Using the MSM Utility Programs ............................ 4-1

4.2 The %HELP Utility .................................................. 4-3
4.3 Library Utilities ........................................................ 4-3
4.4 System Manager Utilities ......................................... 4-3
4.5 Common Utility Routines ........................................ 4-4
4.6 Utility Routines Supplied with MSM ...................... 4-4
CHAPTER 5 SYSTEM TABLES
5.1 Overview .................................................................. 5-1

5.2 The System Vector ................................................... 5-2
5.3 The Partition Vector ................................................. 5-4
5.4 The Lock Table ........................................................ 5-6
5.5 The Volume Group Table ........................................ 5-8
5.6 The UCI Table .......................................................... 5-10
5.7 The Device Descriptor Block ................................... 5-12
CHAPTER 6 GLOBALS
6.1 Global Variables ....................................................... 6-1

6.1.1 Global Usage ............................................ 6-1
6.1.2 Collating Sequence ................................... 6-2
v
TABLE OF CONTENTS
6.2 The Disk Database ................................................... 6-3

6.2.1 Disk Buffers .............................................. 6-5
6.2.2 Map Blocks ............................................... 6-6
6.2.3 Global Directory Blocks ........................... 6-7
6.2.4 Pointer Blocks ........................................... 6-9
6.2.5 Data Blocks ............................................... 6-10
6.3 Global Expansion Areas ........................................... 6-12
6.4 Global Organization ................................................. 6-13
6.5 Cross-UCI Global References .................................. 6-14
6.6 Cross-Volume Global References ............................ 6-14
6.7 Cross-System Global References ............................. 6-15
6.8 UCI Translation and Replication ............................. 6-15
6.9 Remote Volume Groups ........................................... 6-15
6.10 High Availability Databases .................................... 6-16
6.11 Global Protection ..................................................... 6-16
CHAPTER 7 ROUTINE DATA STRUCTURE
7.1 Overview .................................................................. 7-1

7.2 Routine Data Structure ............................................. 7-2
7.3 Routine Data Block Format ..................................... 7-2
CHAPTER 8 RESILIENT SYSTEMS
8.1 Overview .................................................................. 8-1

8.2 Before-Image Journaling .......................................... 8-2
8.2.1 Before-Image Journaling Concepts .......... 8-2
8.2.2 The BIJ Utility .......................................... 8-3
8.3 After-Image Journaling ............................................ 8-4
8.3.1 After-Image Journaling Concepts ............. 8-4
8.3.2 The JRNL Utility ...................................... 8-5
8.4 Cross-System Journaling .......................................... 8-6
8.4.1 Cross-System Journaling Concepts .......... 8-6
8.4.2 Controlling Cross-System Journaling ....... 8-7
8.5 On-Line Backup of a Database ................................ 8-8
8.5.1 On-Line Backup Concepts ........................ 8-8
8.5.2 The OLB Utility ........................................ 8-9
8.6 Summary .................................................................. 8-9
vi
TABLE OF CONTENTS
APPENDIX A ERROR CONDITIONS
A.1 Trapping MSM Errors .............................................. A-1

A.2 MSM Error Messages .............................................. A-3
A.3 MSM Error Numbers ............................................... A-9
APPENDIX B THE MSM PROGRAM EDITOR
B.1 Overview of the Program Editor .............................. B-1

B.2 Editing a Specific Program Line .............................. B-2
B.3 Special Functions ..................................................... B-4
APPENDIX C LOADING APPLICATIONS
C.1 Overview .................................................................. C-1

C.2 Loading The Application Into A UCI ...................... C-1
C.3 Initializing the Application ...................................... C-2
C.4 Sample Installation ................................................... C-2
APPENDIX D FULL SCREEN EDITOR
D.1 Invoking the Editor .................................................. D-1

D.2 Editor Commands ..................................................... D-2
D.3 Cursor Movement Commands ................................. D-2
D.4 Scrolling Commands ................................................ D-5
D.5 Editing Commands ................................................... D-7
D.6 Mark Commands ...................................................... D-9
D.7 Delete Commands .................................................... D-10
D.8 Search Commands .................................................... D-11
D.9 Transfer/Copy Commands ....................................... D-12
D.10 Miscellaneous Commands ....................................... D-13
APPENDIX E CUA FULL SCREEN EDITOR
E.1 Invoking the Editor .................................................. E-1

E.2 Editor Screen Layout ................................................ E-2
E.3 Using The Workspace .............................................. E-3
E.4 Dialog Boxes ............................................................ E-7
E.5 File Menu ................................................................. E-7
E.6 Edit Menu ................................................................. E-9
vii
TABLE OF CONTENTS
E.7 Search Menu ............................................................. E-10

E.8 Options Menu ........................................................... E-11
E.9 Window Menu .......................................................... E-12
E.10 HELP Menu ............................................................. E-13
APPENDIX F MNEMONIC NAMESPACES
F.1 X3.64-1979 Namespace ........................................... F-1

F.2 ZWINTERM Namespace ......................................... F-5
APPENDIX G USER DEFINED COMMANDS
G.1 Commands, Functions, and Special Variables ......... G-1

G.2 Passing Parameters to the Routine ........................... G-2
G.3 Sample User Defined Command .............................. G-2
GLOSSARY .................................................................... Glossary-1
INDEX ............................................................................. Index-1
viii
LIST OF TABLES
Table 2-1 Control Characters .......................................... 2-2

Table 2-2 Command Line Edit Keys .............................. 2-21
Table 2-3 History File Commands ................................. 2-22
Table 2-4 Miscellaneous Shell Commands .................... 2-24
Table 3-1 Device Designators ........................................ 3-3
Table 3-2 Options Controlling Terminal Functions ....... 3-10
Table 3-3 Initialization Parameters ................................. 3-16
Table 3-4 VT100/VT220 Function Keys ........................ 3-19
Table 3-5 Terminal Device Examples ............................ 3-22
Table 3-6 Sequential Block Processor Examples ........... 3-27
Table 3-7 VIEW Device Examples ................................ 3-30
Table 3-8 Host File Server Device Examples ................. 3-36
Table 3-9 Interjob Communication Device Examples ... 3-40
Table 3-10 Routine Interlock Device Examples ............... 3-41
Table 3-11 Magnetic Tape Access Modes ........................ 3-44
Table 3-12 Magnetic Tape Write Commands .................. 3-48
Table 3-13 Magnetic Tape Device Examples ................... 3-52
Table 3-14 Spool Device Command Examples ................ 3-58
Table 3-15 Host System Spool Device Examples ............ 3-62
Table 4-1 Library Utility Programs ................................ 4-4
Table 4-2 System Utility Programs ................................ 4-11
Table 5-1 MSM Tables and Control Blocks ................... 5-1
Table 5-2 System Vector Constants ............................... 5-3
Table 5-3 System Vector Addresses ............................... 5-3
Table 5-4 The Partition Vector ....................................... 5-5
Table 5-5 The Lock Table .............................................. 5-6
Table 5-6 The Volume Group Table .............................. 5-8
Table 5-7 The UCI Table ................................................ 5-10
Table 5-8 The Device Descriptor Block ......................... 5-12
Table 6-1 MSM Block Types ......................................... 6-4
Table 6-2 Disk Buffer ..................................................... 6-5
Table 6-3 Map Block ...................................................... 6-6
Table 6-4 Global Directory Element .............................. 6-8
Table 6-5 Pointer Element .............................................. 6-10
Table 6-6 Data Element .................................................. 6-11
Table 7-1 Routine Header Block Structure .................... 7-3
Table 7-2 Routine Data Block Structure ........................ 7-4
Table A-1 MSM Error Messages ..................................... A-3
Table A-2 MSM Error Numbers ..................................... A-9
ix
LIST OF TABLES
Table B-1 Program Editor Functions .............................. B-4

Table D-1 Cursor Movement Commands ....................... D-2
Table D-2 Scrolling Commands ...................................... D-5
Table D-3 Editing Commands ......................................... D-7
Table D-4 Mark Commands ............................................ D-9
Table D-5 Delete Commands .......................................... D-10
Table D-6 Search Commands .......................................... D-11
Table D-7 Transfer/Copy Commands ............................. D-12
Table D-8 Miscellaneous Commands .............................. D-13
Table D-9 Summary of Editor Commands ...................... D-15
Table E-1 Cursor Movement Keys ................................. E-4
Table E-2 Function Keys ................................................ E-5
Table E-3 Accelerator Keys ............................................ E-6
Table F-1 ANSI X3.64-1979 Mnemonic Namespace ..... F-1
Table F-2 ZWINTERM Display Attributes .................... F-5
Table F-3 ZWINTERM Erase Attributes ....................... F-7
Table F-4 ZWINTERM Error Codes .............................. F-8
LIST OF FIGURES
Figure 1-1 MSM System Components ............................. 1-2

Figure 2-1 Processing Errors With $ZTRAP ................... 2-17
Figure 2-2 Programmer Shell HELP Text ....................... 2-20
Figure 2-3 Programmer Shell Command History ............ 2-23
Figure 6-1 Global Organization ....................................... 6-13
Figure E-1 CUA Editor - Main Screen ............................. E-1
x
Acknowledgment
Micronetics Standard MUMPS (MSM) is a full implementation, with

extensions, of the ANSI Standard Specification (X11.1-1990) 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 is a trademark of Massachusetts General
Hospital.
xi
DOCUMENTATION CONVENTIONS
The following describes the various documentation conventions that are

used throughout this manual.
Convention Description
RET The Carriage Return Key (normally labeled
RETURN, RET, ENTER, etc.).
CTRL/x The Control key pressed at the same time as

the x key where x is any valid key used in
combination with the Control key.
<ERROR> An MSM error message.
’val’ In HELP messages, ’val’ is used to indicate

that the user can enter the indicated value.
The value is entered without the quotes.
> The MSM Programmer prompt.
••• The series of items repeats a user-specified

number of times.
• Shows a break in a list where consecutive

• lines have been omitted.
•
BOLD Items in a dialogue are shown in bold to

indicate a user response.
xii
CHAPTER 1
THE MSM SYSTEM
This chapter provides a general overview of the MSM system as it has
been implemented for Personal Computers (e.g., IBM-PC, and
compatibles) operating under MS-DOS, most Unix, Xenix, and Ultrix
based systems, and VAX systems operating under VMS. It includes
information about the basic components that make up the system.
1.1 System Overview

Micronetics Standard MUMPS (MSM) is an extremely versatile
programming system that includes a high-level programming language,
a comprehensive database management facility, and a flexible operating
system. The high-level programming language used in the system is a
fast and powerful implementation of the ANSI standard MUMPS
programming language. MUMPS is an acronym for Massachusetts
General Hospital Utility Multi-Programming System. This language
was developed in the late 1960’s to meet the demanding requirements
associated with the storage, retrieval, and manipulation of large volumes
of medical information. Since that time, use of the MUMPS language
has spread well beyond the medical community and it is now used in
general business, financial management, process control, order entry,
and many other areas of information processing. Some of the main
features of MSM include:
• Conformance to the 1990 ANSI standard and incorporates
all of the approved Type A extensions to the language.
• Implementations that coexist with PC-DOS, MS-DOS,

Unix, Xenix, Ultrix, and VMS operating systems.
• Comprehensive package of utility, reporting, and database
integrity routines.
• User transparent pre-compilation of code for increased
performance.
• Includes Networking, Journaling, Interjob Communication,

Sequential Block Processor, and Host operating system File
Server.
The MSM System 1-1

This versatile and powerful programming language is one of only a
handful of ANSI standard languages (others being FORTRAN, COBOL,
and PL/1). The language’s basic orientation is procedural, like
FORTRAN and COBOL, and the list of capabilities it includes is
extensive. While no single feature in the language is unique, the overall
combination of these many different features into a single language does
make MUMPS unique. The flexibility and unique combination of
features in MUMPS makes it an ideal language for the development of
interactive applications to meet diverse information processing
demands.
1.2 Functional Description

The MSM system is composed of five primary components: the language
compiler, the database management system, the operating system
monitor, the I/O supervisor, and the utility program library. Each of
these components plays a key role in the execution of a MUMPS
program.
Figure 1-1 - MSM System Components
MSM System Components
Languge
Compiler
Operating System Database
Monitor Management
Micronetics
Input/Output
Standard Utility Program
Supervisor Library
MUMPS
1-2 The MSM System

1.2.1 The Language Compiler
The MUMPS language has been implemented in MSM through the use
of a language compiler and a pseudo-code (p-code) interpreter. The
language compiler is a highly sophisticated system program that scans
each line of MUMPS code, divides it into its basic components, analyzes
each component to insure that it is syntactically correct, and generates
pseudo machine code that can be processed by the p-code interpreter.
This compilation process is repeated for each line of MUMPS code in
a program. The interpretation of the p-code during program execution
is significantly faster than with a pure interpreter. However, since
compilation and interpretation can be combined into a single operation,
MSM still appears to the user as an interpreter. That means that code
can be entered directly from a terminal into the compiler to provide
immediate results without a separate compilation step.
Since MSM acts like an interpretive language, it provides the user with
several distinct advantages. Most notable among these is the ability to
easily analyze and correct errors that occur during execution of a
program. Whenever an error occurs, a message is displayed on the
terminal and execution is terminated (unless the error is explicitly
trapped by the program).
The programmer then has all of the features and capabilities of the
MUMPS language available to debug the problem. Once the cause of
the error has been determined, the necessary modification can be made
and execution of the program restarted. This technique allows new
applications to be developed more rapidly and modifications to existing
applications to be integrated more easily.
1.2.2 The Database Management System

The MSM system allows data to be referenced symbolically through
specification of user-defined labels. These symbolic references, or
variables as they are known in MSM, may represent numeric values or
alphanumeric strings of information. MSM permits two types of variable
references: local variables and global variables or, simply locals and
globals, respectively. Local variables exist for the duration of a terminal
session and are stored in the local memory of the job that creates them.
These temporary variables are accessible only within the same terminal
session and are discarded at logoff.
The MSM System 1-3

By contrast, globals are created and maintained on external disk storage
and continue to exist after a terminal session has ended (i.e., after the
user has logged off). The method for symbolically referencing globals
is the same as for referencing local variables with the exception that
global names are preceded with a circumflex (^). Globals form the basis
for a common database that can be shared by multiple users.
Implementation of globals, as well as local variables, is achieved through
the use of subscripted sparse arrays.
An array is a collection of data stored under a common name. Subscripts

are numeric or string values, separated by commas, enclosed in
parentheses, and appended to the local or global name to qualify which
item in the array is being referenced. Finally, a sparse array is one which
only contains space for those elements actually defined. The entire local
and global variable structure in MSM is completely managed by the
system. Space is automatically added to, or removed from, these
structures if necessary and the user need not be concerned with
pre-allocation of space, specifying the maximum size of a local or global,
or reclaiming space when data is deleted.
1.2.3 The Operating System Monitor

The primary purpose of the operating system monitor is to provide an
interface between the host operating system and MSM. The main
functions performed by the monitor include translating MSM terminal
requests to the appropriate host system calls, interfacing to the disk file
structure maintained by the host system, and responding to the dynamic
memory requirements of MSM. In a multi-user environment, the
monitor also ensures that all of the available system resources are
properly allocated among users and the overall efficiency and throughput
of the system is maximized.
Resource usage by competing jobs is constantly monitored by the MSM
system, and if necessary, the allotment of resources is adjusted to provide
uniform levels of service to each user. Other functions performed by
the monitor in a multi-user environment include initiating new jobs,
dynamically expanding and contracting partitions, logging new users
onto the system, and interfacing to the I/O supervisor to service requests
for disk and terminal information.
1-4 The MSM System

1.2.4 The I/O Supervisor
The I/O supervisor is responsible for the input, error detection, error
correction, and output operations of each peripheral device attached to
the system. These devices fall into three primary categories; terminal
devices, disk devices, and tape devices. For each of these device types,
the I/O supervisor coordinates all data transfers and synchronizes them
with job execution.
In a multi-user environment, the I/O supervisor is entirely interrupt
driven so that it is only active when there is actually work to be
performed. For terminal devices, the system maintains both an input
buffer and an output buffer, each capable of storing 255 characters. This
allows programs to output information at rates faster than the terminal
can accept and allows the user to input more information before the job
is ready to process it.
For disk devices, the I/O supervisor maintains a large number of buffers
to hold incoming and outgoing information. This collection of buffers,
known as the buffer pool, often allows logical requests for information
to be satisfied without the need to perform a physical I/O operation.
Whenever a request is made for information, the I/O supervisor scans
the buffer pool to see if the requested data is contained in one of the
buffers. If it is, then the request is satisfied immediately. This approach
greatly reduces the number of physical I/O operations that take place in
the system.
1.2.5 The Utility Program Library

One of the major strengths of the MSM system is the comprehensive
library of utility programs that is available to assist the user in developing
programs as well as maintaining the system. These utility programs,
which are all written entirely in MUMPS, can be easily modified by the
system manager to meet any unique or installation-specific requirements
that might exist.
The program development routines perform general functions that are
often needed in MUMPS programs such as date and time conversions.
In addition, there are utilities to edit programs, debug programs, list
globals, edit globals, and search routines. All of these utilities can help
reduce the time required to develop programs.
The MSM System 1-5

The system maintenance routines allow the system manager at an
installation to configure the MSM system to the precise operating
environment that exists at the site. This includes defining the hardware
configuration, user areas, device types, port assignments, and many other
system features. Also included are routines to report on system status,
verify the integrity of routines and globals, make backup images of the
information stored on disk, and startup and shutdown the system. These
routines allow the system manager to monitor and control the MSM
environment and lessen the task of maintaining the system.
1-6 The MSM System

CHAPTER 2
USING THE MSM SYSTEM
This chapter describes the procedure for logging onto the system,
entering commands, building programs, saving programs, editing
programs, executing programs, error handling, and debugging programs.
2.1 Supported Terminals

MSM supports most of the popular hardcopy and display terminals that
are available on the market today. The support provided by MSM is
independent of the manner in which they are connected to the system.
Terminals may be connected through RS-232, RS-422, Modem, Local
Area Transport (LAT) and TCP/IP type servers, etc.
In addition, MSM supports most printer type devices, including dot

matrix printers, line printers, laser printers, etc. The range of support
services provided by MSM is independent of the type of equipment used.
MSM allows special purpose devices to be connected to the system using
standard interfaces. These special devices can include laboratory
instruments, bar code readers, and any other equipment that provides a
standard computer interface.
2.2 Terminal Control Characters

As input to the system, a terminal can transmit any one of the standard
set of 128 ASCII characters plus the 128 extended ASCII characters.
However, certain characters from this set have special meaning to the
MSM system. These include standard keys on the keyboard, as well as
control sequences that can be generated by the terminal. Generally,
control sequences are formed by depressing the Control key (abbreviated
as the CTRL key on most terminals) at the same time that the associated
control character is depressed.
For example, pressing the CTRL key at the same time as the C key
generates a CTRL/C sequence. The CTRL key behaves in much the
same way as the SHIFT key. Table 2-1 below lists the special characters
and the control characters that are supported by MSM.
Using The MSM System 2-1

Table 2-1 - Control Characters
Control Key Action Performed by MSM

Backspace Deletes the last character entered from the terminal
and backspaces the cursor one position. Refer to the
appropriate MSM System Manager’s Guide
(Generating the System) for additional information
on changing this value via the SYSGEN utility. 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 or more
characters are read from the terminal and the input
operation is terminated. Refer to Chapter 3 (Using
Peripheral Devices) for additional information on
ESCAPE processing.
RET Terminates the current input operation. This is

equivalent to the CTRL/M sequence.
TAB The tab function moves the cursor to the next tab
position (tabs stops are every 8 positions). It is also
used as the separator between the line label and the
line body when entering MUMPS code into a
program. This key is equivalent to entering the
CTRL/I sequence.
CTRL/C Interrupts execution of the current routine if break

recognition is enabled. If break recognition is not
enabled, the interrupt is ignored.
CTRL/H Deletes the last character entered from the terminal

and backspaces the cursor one position. This is
equivalent to the BACKSPACE key.
2-2 Using The MSM System

Control Key Action Performed by MSM
CTRL/I This 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 MUMPS code into a program. This is
equivalent to entering the TAB character.
CTRL/J Performs the same function as entering the line feed

character. This character is echoed back to the
terminal, and the exact action taken depends on the
terminal connected to the system.
CTRL/L Performs the same function as entering the form feed

character. This character is echoed back to the
terminal, and the exact action taken depends on the
terminal connected to the system.
CTRL/M Terminates the current input operation. This is

equivalent to the RET key.
CTRL/O Causes all output to the terminal to be discarded until

another CTRL-O is entered.
CTRL/Q Resumes output to the terminal that has been

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. No information

is lost in this case, and output is resumed when a
CTRL/Q is received.
CTRL/U Deletes the current input line (i.e., erases all

characters typed so far) and re-prompts for the input.
CTRL/X Deletes the current input line (i.e., erases all

characters typed so far) and reprompts for the input.

2.3 Logging onto the System
To gain access to the system, a user must first logon. The logon procedure
verifies that the user is authorized for system access and also obtains
information about the requested access mode. On multi-user MSM-PC
and MSM-PC/PLUS systems, automatically enter the logon procedure
after startup, unless overridden by parameters on the MSM startup
command. During login, the system prompts the user with the following:
MSM Version 4.0 Line #nn UCI:
The system then waits for the user to enter the required information. If
the user does not respond in 180 seconds, the system terminates the
logon. When this occurs, an Exit message is displayed to indicate that
the logon was not successful. In the single-user version of MSM-PC
and all versions of MSM-UNIX and MSM-VX, this returns the user to
the host operating system (i.e., MS-DOS, Unix, and VMS). In the
multi-user version of MSM-PC, the terminal is returned to an inactive
state and the system waits for the next terminal interrupt. In both cases,
the system behaves as it would if a HALT command had been entered.
To complete the logon procedure, the user must enter a valid User Class
Identifier (UCI) code, a valid volume group identifier as an option, and
either the correct Programmer Access Code (PAC) to enter Programmer
mode or the name of a routine stored in the UCI to enter Run mode. In
addition, the user can enter the size of the partition required for the
program. If entered, the partition size is an integer value specifying the
maximum number of 1K byte blocks that can be used by the program.
As each character is entered, the system echoes an asterisk (*) character.
This is done for security reasons.
If any of the information that has been entered is not correct, the system
terminates the logon and displays an ERROR message. The user is given
a total of three attempts to complete the logon. After the third invalid
attempt, the user is logged off the MSM system. In the single-user
version of MSM-PC and all versions of MSM-UNIX and MSM-VX,
this returns the user to the host operating system (i.e., MS-DOS, Unix,
and VMS). In the multi-user version of MSM-PC, the terminal is
returned to an inactive state and the system waits for the next terminal
interrupt. In both cases, the system behaves as it would if a HALT
command had been entered.

2.3.1 The User Class Identifier
The User Class Identifier (UCI) designates a unique area within a volume
group of the MSM system. Up to 30 separate UCIs can be defined within
each volume group on the system. Each UCI created has its own unique
routine directory and global directory. The UCI code consists of three
upper-case alphabetic characters. As an option, the UCI code can include
a volume group specification. The volume group is specified as three
upper-case alphabetic characters, and is separated from the UCI by a
comma (i.e., UCI,VGP). Refer to the appropriate MSM System
Manager’s Guide (Generating the System) for additional information
about defining UCI codes.
In all of the following examples, whenever UCI appears it can be entered
as either a UCI name (e.g., MGR, TST, FMR) or a UCI name and volume
group specification (e.g., MGR,SYS or TST,VAH or FMR,SYB). In
general, throughout this manual whenever UCI is used it implies a simple
UCI name or the full UCI name/volume group name combination.
2.3.2 Programmer Mode

Programmer mode in MSM allows the user to enter MUMPS commands
directly into the interpreter. To gain access to the system in Programmer
mode, the user must specify a valid UCI and the correct Programmer
Access Code (PAC) that was defined during the SYSGEN process. This
code can be up to 12 characters in length, and can contain alpha, numeric,
control, and special characters, excluding the colon (:) character. One
PAC can be specified for each configuration that is defined to the system.
When logging on in programmer mode, the user enters the information
in the following format:
MSM Version 4.0 Line #n UCI: UCI:PAC:PartSize

Note that the UCI name is separated from the PAC by a colon (:)
character. If any of the information is invalid or incorrect, the system
terminates the logon and display an ERROR message. The user is
allowed three attempts to complete the logon.
If the partition size is not specified, the default partition size defined for
the system is used. After the logon is complete, the system responds
with a right angle bracket (>) which is the programming prompt symbol.
At this point, the user can enter MUMPS commands or interact with the
programmer shell. For additional information on the programmer shell,
refer to Section 2.9 (Programmer Shell) in this chapter.

2.3.3 Run Mode
Run mode in MSM is used to directly access a routine in a particular
UCI. To logon to the system in run mode, the user must enter a valid
UCI and the name of a routine stored in that UCI. The name of the
routine must be from 1 to 8 alphanumeric characters with the first
character alphabetic or a percent sign (%). The name must not include
the circumflex (^) character or any other special characters. When
logging on to the system in run mode, the user enters the information in
the following format:
MSM Version 4.0 Line #n UCI: UCI:RTN:PartSize

Note that the specified UCI name is separated from the routine name by
a colon (:). If any of the information is invalid or incorrect, the system
terminates the logon and display an ERROR message. The user is
allowed three attempts to complete the logon. After the third attempt,
the user is logged off the system.
In the single-user version of MSM-PC and all versions of MSM-UNIX

and MSM-VX, this returns the user to the host operating system (i.e.,
MS-DOS, Unix, and VMS). In the multi-user version of MSM-PC, the
terminal is returned to an inactive state and the system waits for the next
terminal interrupt. In both cases, the system behaves as it would if a
HALT command had been entered.
If partition size is not specified, the default system partition size is used.
After the logon, additional information, if any, is solicited by the routine
selected for execution.
2.3.4 Tied Terminal Mode

Tied terminal mode is used to force a particular terminal to automatically
start up a particular routine in a specified UCI. Whenever a user attempts
to logon to the system from a port that has been tied to a particular
application, the specified application is directly entered. Therefore, the
logon procedure to be followed for tied terminals is specific to the
installation that defined the tied terminal table. Refer to the appropriate
MSM System Manager’s Guide (Generating the System) for additional
information on setting up the tied terminal table.

2.3.5 Partition Size
When logging onto the system in Programmer mode or Run mode, you
can specify the partition size that is required. The partition size is
specified as an integer value indicating the maximum number of 1K
blocks that can be in use by the partition at any time. If the partition
size is not specified, the default partition size defined for the system is
used. Refer to the appropriate MSM System Manager’s Guide
(Generating the System) for additional information about the default
partition size.
2.3.6 Changing UCIs

When a user logs onto the system, a UCI is specified to indicate where
the programs and data that are to be accessed can be found. Once the
user has finished working in the specified UCI, it may be necessary or
desirable to logon to another UCI. To do this, the user must be logged
onto the system in programmer mode. Then, in response to the
programmer prompt (i.e., >) enter the following command.
DO ^%LOGON
The system responds with the standard logon prompt as described in the
previous sections. The user can logon to any of the UCIs that are defined
in the system using any of the valid logon modes (i.e., programmer mode
or run mode). All of the normal rules and conventions for logging onto
the system apply when a user changes UCIs in this manner.
2.3.7 Remote Volume Group UCIs

At logon, the specified UCI can reside on a Remote Volume Group
(RVG). A UCI accessed through the RVG support in MSM behaves
exactly the same as a UCI on a local Volume Group. The user can logon
to a remote UCI in programmer or run mode, programs can be loaded,
saved, or executed, and globals can be fetched or set. For additional
information on Remote Volume Groups, refer to the MSM-NET
Services chapter in the appropriate MSM System Manager’s Guide.

2.4 Logging Off the System
When the user has finished accessing the system, the terminal should be
logged off. To logoff in programmer mode, the user enters the following
command in response to the programmer prompt symbol (>):
HALT
The system responds with the Exit message and disconnects the terminal.
If you are logged onto the system in Run mode, and BREAK recognition
is enabled, you may enter a CTRL/C to interrupt the routine that is
executing. The system terminates execution of the program, displays
the Exit message, and disconnects the terminal from the computer. If
BREAK recognition is not enabled, the routine cannot be interrupted
and the user has to wait for execution of the routine to complete.
When execution has completed, the user is automatically logged off the
system. In the single-user version of MSM-PC and all versions of
MSM-UNIX and MSM-VX, this returns the user to the host operating
system (i.e., MS-DOS, Unix, and VMS). In the multi-user version of
MSM-PC, the terminal is returned to an inactive state and the system
waits for the next terminal interrupt. Note that powering off the terminal
does not always log the user off the system when a routine is executing.
2.5 Creating Routines

In order to create a routine, you must be logged onto the system in
programmer mode. In programmer mode, you can enter any MUMPS
command in response to the program mode prompt symbol (>). All of
the commands that are entered may contain upper-case letters,
lower-case letters, or a mixture of the two. All input to the interpreter
must be terminated with the RET key. When commands are entered in
this fashion, they are immediately processed by the interpreter and the
results are displayed back at the terminal.
You can enter command lines that are not immediately processed by the
interpreter by using the following format:
label TAB command or TAB command

In this example, the command may be null; however, the line must be
terminated with the RET key. The TAB character is entered using the
tab key on the terminal if present, or the CTRL/I character. Commands
that are entered this way are stored in the routine edit buffer within the
partition. Internally, the tab character is stored as a space character.
The number of lines that can be stored in the partition is limited only by
the size of the partition. The default size of a partition is determined
from the value specified by the SYSGEN procedure. However, this can
be overridden when a user logs onto the system. Refer to the appropriate
MSM System Manager’s Guide for additional information on the
SYSGEN program. Refer to Section 2.3 (Logging onto the System) for
additional information on specifying the partition size during logon.
If you try to enter more lines into the partition after reaching the limit,
a program overflow (<PGMOV>) error will occur. Once a routine has
been created, it can be permanently saved using the following command:
ZSAVE RoutineName
In this example, RoutineName is the name to be associated with the
stored routine. The name must be from 1 to 8 alphanumeric characters
with the first character alphabetic, or a % character if the command is
entered in the manager’s UCI (i.e., MGR).
If the routine name is omitted, the name currently assigned to the routine
in the partition is used. If no name is assigned to the routine, a no program
(<NOPGM>) error will occur. When a routine is saved in this manner,
it does not get erased from the partition. A routine is only erased if
explicitly directed by the ZREMOVE command, or if a new routine is
loaded into the partition, or the terminal is logged off the system.
2.6 Editing Routines

Once a routine has been created, you can edit it in several different ways.
In each case, the routine must reside in the routine edit buffer of the
partition. To load a routine into the buffer, enter the following command:
ZLOAD RoutineName
In this example, RoutineName is the 1 to 8 character name that was used

when the routine was saved. This command loads the routine from disk
into the partition. In the process of loading the routine, any routine
previously resident in the partition will be replaced.

2.6.1 Inserting Lines into a Routine
Additional lines of code can be inserted into a routine using the ZINSERT
command or by simply typing in the new line with an imbedded tab at
the appropriate spot. To insert a new line into a routine using the
ZINSERT command, enter the following:
ZINSERT "text of new line":InsertPoint
The new line of code to be inserted must be enclosed in double quotes

(e.g.,"line of code"). If the line of code contains a label, then the label
must be separated from the first command in the line by one or more
tabs or spaces. If no label is present, the first command in the line must
be preceded by one or more tabs or spaces.
The insert point, if present, is a line label or a line label plus (+) an offset,
or simply an offset into the routine. It must be separated from the text
of the new line by a colon (:). If the insert point is omitted, the line is
stored after the current insert point in the routine.
Whenever lines are entered into a routine, the system maintains an
implied insert point. The insert point is always after the last line directly
typed in, or the last line inserted using the ZINSERT command, or the
last line removed using the ZREMOVE command, or the last line
displayed using the ZPRINT command, whichever occurred more
recently. Therefore, you can enter lines into a routine by using the direct
entry method described above once the insert point has been set.
Deleting Lines From a Routine

A specific line or range of lines within a routine can be deleted using
the ZREMOVE command. To delete lines from the routine enter the
following command:
ZREMOVE StartLine:EndLine
The starting line and ending line arguments are labels (e.g., ABC), labels
plus (+) an offset (e.g., ABC+3), or simply an offset (e.g., +7) within
the routine. All lines beginning with the line specified by StartLine
through and including the line specified by EndLine are removed. If the
ending line number is not specified, only the starting line is removed.
If either the starting line or the ending line does not exist, no lines are
removed and a line error (ie., a <LINER> error) is produced.

If no starting and ending lines are specified, the entire routine is removed
from the partition. When the entire routine is removed, the name of the
routine stored within the partition is also removed. Note, however, that
the routine is not removed from the disk.
2.6.2 Editing Specific Lines

An alternate method to directly editing routines with the ZINSERT and
ZREMOVE commands is to use the MSM program editor. The editor
allows the user to change specific text contained in individual lines
within a routine or text contained within all lines of a routine. You can
also insert lines, delete lines, and perform many additional functions.
All changes are affected through an interactive dialogue with the editor.
HELP information can be obtained by entering a question mark (?) in
response to editor prompts. To invoke the editor, first load the routine
to be edited into your partition and then enter the following command:
XECUTE ^%
In response to this, the editor prompts with the following:
Edit line:
The editor then waits for the user to enter the label of the line to be edited,
an editor command, a question mark (?) to obtain HELP information, or
a period (.) to exit the editor. Refer to Appendix B (MSM Program
Editor) for complete information on how to use the MSM program editor.
2.6.3 Full Screen Routine Editing

In addition to the line-by-line editor described above, the MSM system
includes a full screen editor that can be used on ASCII terminals that
conform to the ANSI 3.64 display terminal specification (i.e., VT100,
VT220). To invoke the full screen editor, enter the following command:
XECUTE ^%E
A full screen editor allows the user to view large portions of the program
at one time rather than one line at a time. The program can be paged
forwards or backwards to expose new sections. It also allows the user
to insert or delete characters and lines in a visually informative manner.

Upon entry, the full screen editor checks to see if a program is currently
loaded in the user’s partition. If not, the editor prompts you for the name
of the program. After the program is loaded by the editor or if one was
already loaded, the editor displays the first part of the program (as many
lines as fit on the screen). The editor then waits for a command. Please
refer to Appendix D (Full Screen Editor) of this manual for a complete
description of the full screen editor.
2.6.4 CUA Style Full Screen Editor

In addition to the full screen editor described above, the MSM system
includes a CUA style full screen editor which can be used on ASCII
terminals that conform to the ANSI 3.64 display terminal specificatio
(e.g., VT100, VT220). The CUA style editor is non-modal, includes
pull-down menus, and pop-up dialogue boxes, supports color or
monochrome devices, and allows multiple programs to be edited at the
same time: To invoke the CUA full screen editor, enter the following
command:
XECUTE ^ %G
Upon entry, the full screen editor checks to see if a program is currently
loaded in the user’s partition. If not, the editor creates an empty work
area where a new program can be created. Please refer to Appendix E
(CUA Full Screen Editor) of this manual for a complete description of
the CUA full screen editor.
2.7 Deleting Routines from Disk

Once a routine has been saved on disk, it remains there permanently
until it is explicitly deleted by the user. The procedure for deleting a
routine involves clearing the partition of all program lines and then
saving the empty partition using the name of the routine that is to be
deleted. The MSM system recognizes this special condition as a signal
to delete the specified routine. Therefore, to delete a routine, enter the
following two commands:
ZREMOVE
ZSAVE RoutineName
In this example, RoutineName is the 1 to 8 character name of the routine
to be deleted. Note that the ZREMOVE command does not specify a
specific line or range of lines, so the entire routine is removed.

2.8 Executing Routines
After a routine has been created, either of two methods can be used to
initiate execution of the routine. In the first case, you can use the DO
command to invoke the routine. The format for invoking a routine using
the DO command is the following:
DO LineReference^RoutineName
If the line reference is omitted, execution begins at the first line within
the routine. If the circumflex (^) and the routine name are omitted, the
routine must have been previously loaded into the partition.
It is important to note that when you enter a routine and do not save it
on disk, if you then execute the program and it executes a different
program, the original program is lost. To avoid this situation, be sure
to save your routine if you intend to run it repeatedly.
Once execution of a program is started, it continues to execute until a

QUIT command is issued by the routine named in the DO command. It
also is terminated if a HALT command is issued by the program or any
programs that it may call, or the program is interrupted using the
CTRL/C key when BREAK recognition is enabled. If the compiler
encounters the last line in a routine and no QUIT command is present,
the interpreter assumes a QUIT command to be present. When the
program execution is complete, the terminal is returned to programmer
mode.
As an alternative to using the DO command to initiate execution of a

routine in programmer mode, the user can logon to the system in run
mode. In this mode, the specified routine is automatically invoked at
logon, and execution continues following the same rules described above
concerning termination of execution. When program execution is
complete, the terminal is automatically logged off the system.
2.8.1 Error Processing

During program execution, several types of unusual situations can arise
that cannot be handled automatically by the MSM system. These types
of occurrences can include program errors (e.g., arithmetic divide by
zero), hardware failures (e.g., an error reading a disk block), and external
interrupts to a routine (e.g., a user pressing the CTRL/C key). In general,
these situations are considered to be fatal errors by the MSM system.

Normally, when one of these fatal error conditions occurs while a
program is running, the system interrupts execution and the $ZERROR
Special Variable is set to the appropriate error message code, routine
name, and if debugging is active, line reference within routine, command
reference within line, and argument reference within command. Refer
to Appendix A (Error Conditions) for a description of the error message
codes and the format of $ZERROR. Refer to the MSM Reference Manual
for additional information on the $ZERROR Special Variable.
A facility exists within MSM to allow programs to recover from the

error in whatever manner is appropriate for the application. This is done
using the $ZTRAP Special Variable. Refer to the MSM Reference
Manual for additional information on the $ZTRAP Special Variable.
The following sections describe how the $ZTRAP Special Variable is
used in error processing and the actions that occur depending on the
value of this variable.
2.8.2 Default Error Processing

When the $ZTRAP Special Variable contains a null value, it indicates
that user-supplied error trapping has not been specified. In this case, the
standard system error processing takes place. When any type of error
condition occurs, it is considered a fatal error and the following actions
take place in the order shown.
• The $ZERROR Special Variable is set to the error message code

and the location of the error (i.e., routine, line, command, and
argument).
• If the Job that is executing when the error occurs is operating in

RUN mode or has no principal device, then the system-supplied
error processing routine (i.e., %ET) is invoked. Otherwise, the
$IO Special Variable is set to the principal device number and an
error message is displayed. The error message includes a
traceback of the execution stack (i.e., all DO and XECUTE
commands in the path to the routine) and the exact contents of the
$ZERROR Special Variable.
• If the routine that encountered the error was initiated from
programmer mode, then the terminal is returned to programmer
mode. Otherwise, the user is logged off and the terminal is
disconnected from the system.

2.8.3 User-Defined Error Processing
As an alternative to the default error processing performed by the system,
the programmer can specify that errors are to be handled by a
user-defined error processing routine. This is done by specifying a
routine that is to receive control when an error condition occurs. To set
the error trap, the routine must issue the following command:
SET $ZTRAP="LineRef^RoutName"
In this example, routine name is the name of the routine and line reference
is the location within the routine to receive control when an error occurs.
The line reference, or the routine name, or both can be specified.
The error processing routine can examine the $ZERROR Special

Variable to determine the type of error that occurred. Based on the
information contained in this variable, the routine can decide what
corrective action, if any, is required.
It is important to point out that an error trap routine can be specified for
each DO/XECUTE level. When an error occurs, the error trap routine
executes at the same DO/XECUTE level that was in effect at the time
the $ZTRAP was set. The following sections describe in detail the
manner in which this is accomplished.
2.8.4 Processing Trapped Errors

Whenever a DO or XECUTE command is processed, the MSM system
creates a new execution level. This is done so that upon termination of
the DO or XECUTE command, either through an implicit QUIT (i.e.,
end of routine encountered) or an explicit QUIT, the system can return
to the point where 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 level 2, and so on. The execution level that is currently in control
is generally referred to as the current execution level.
One $ZTRAP Special Variable can be set at each execution level (i.e.,
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 the $ZTRAP Special Variable begins with a non-null value, it
indicates that a user-supplied error trapping routine has been specified.
One $ZTRAP Special Variable can be set at each execution level (i.e.,
level 1, level 2, and so on). Each execution level in an application can
establish its own error trapping routine and error recovery procedures.
When any type of error occurs, it is considered to be a non-fatal error
and the following actions take place in the order shown.
• The $ZERROR Special Variable is set to the error message and
location of the error (i.e., routine, line, command, and argument).
• The value of $ZTRAP at the current level is tested to see if an
error trap has been specified. If so, the system does an internal
GOTO to the error trap routine specified in $ZTRAP and normal
execution continues at the current level. If no error trap has been
specified, then the system terminates the current execution level
and pops up to the next higher level (i.e., the current level minus
1). Any variables saved by the NEW command are restored and
this higher execution level becomes the current execution level.
• This procedure described above is then repeated. It will continue
to be repeated until an execution level that contains an error trap
is found.
• If the system reaches the highest execution level (i.e., level 0)

without finding an error trap, then it handles the error using the
standard error processing described above.
After an error has been trapped and processed by the specified routine,
a number of different techniques can be used to exit from the error trap
routine. For example, one method is to use a GOTO command; when
it is used, control passes to a new routine and program processing remains
at the same execution level. This is the most common form of error
recovery used.
Another method is to use a QUIT command. When a QUIT command
is used, program execution continues at the next higher execution level
(i.e., the current execution level minus 1). This behaves the same as if
the DO or XECUTE terminated normally with a QUIT command.
Alternately, the ZQUIT command can be used to back up to the next
higher execution level that contains an error trap. Figure 2-1 below
illustrates how the QUIT and ZQUIT commands can be used in
conjunction with the error trapping mechanism to control the processing
flow during error recovery.

Figure 2-1 - Processing Errors with $ZTRAP
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

2.8.5 Using the System Error Trap
As an alternative to writing your own error trapping routines, you can
use the standard error trapping utility programs supplied with the system.
These standard utilities include a routine to trap errors (%ET) and a
routine to report errors (%ER) that have been trapped. Following is a
description of these routines.
• %ET - When an error occurs, and this utility is invoked, the routine
stores the values of the $ZERROR, $HOROLOG, $JOB, $IO, and
$STORAGE Special Variables, the key of the last global
referenced ($ZREFERENCE), and the contents of the local
symbol table. In addition, it writes a message to the principal
device indicating that a program error was encountered, and it
displays the contents of the $ZERROR Special Variable.
• %ER - This utility reports errors that have been trapped using the
%ET routine. It allows the user to display, print, delete, or
summarize errors. In addition, as a very powerful programming
and debugging tool, it allows the programmer to reload the local
symbol table with the values of the local variables as they existed
at the time of the error. After loading the variables, the routine
exits and leaves the user in programmer mode.
Refer to the MSM Utility Manual for additional information about the
system error trapping and reporting routines.
2.8.6 Using Downlevel Error Trapping

Prior to Version 2.1 of MSM, whenever an error occurred, the system
would discard the entire contents of the DO/XECUTE stack. This was
done before the system passed control to the error trap routine specified
by the $ZTRAP Special Variable. With the release of Version 2.1 and
subsequent MSM releases, the DO/XECUTE stack remains at the same
level when an error occurs.
Any applications that depend upon the DO/XECUTE stack being cleared
as it was in previous versions of MSM will not work properly. The
recommended solution to this problem is to modify the error trapping
code to use the new style of trapping. However, this may not be practical
is all cases. As a convenience to our users, a compatibility mode has
been provided to allow error processing to behave just as it did in previous
MSM releases.

The compatibility mode has been implemented as an extension to the
BREAK command. Refer to the MSM Reference Manual for additional
information on the BREAK command. The following shows the
compatibility extensions that have been implemented:
BREAK 2 Error trapping as it was before Version 2.1
BREAK -2 Restore error trapping to Version 2.1 mode
The default value in effect when a job is started is the Version 2.1 mode
of error processing (i.e., BREAK -2). If the old style of error trapping
is desired, a BREAK command with an argument 2 (i.e., BREAK 2)
should be 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.
2.8.7 Interactive Debugging

The MSM system includes a facility that allows a user operating in
programmer mode to interactively step through execution of a program
one line or one command at a time. It also includes that 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 trace error

conditions and determine the cause of the error. It significantly increases
the productivity of the programmer in this type of situation. To invoke
the interactive debugger, enter the following command at the MUMPS
programmer prompt:
DO ^%DEBUG
The system responds with a menu of options that are available. The
utility program includes complete on-line help information and is
extremely easy to use. Refer to the MSM Utility Manual for additional
information.
2.9 Programmer Shell

To faciliate program development, the MSM system provides a
programmer shell. This shell routine is automatically invoked by the
system whenever a user logs onto MSM in direct mode or when the
interactive debugger (i.e., the %DEBUG routine) is invoked. The shell
allows the programmer to enter and execute commands, load and save
programs, enter lines into a program, delete lines from a program, etc.

The shell also maintains a command line history. This file is used to
keep track of every command that has been entered by the programmer.
Special shell commands have been provided to allow the programmer
to display, recall, and edit commands from the history file. In addition,
the line editor that works on the history file can also be used to modify
command lines as they are entered into the shell.
2.9.1 Obtaining HELP Information

MSM provides complete on-line documentation about operation of the
shell. The HELP text includes information on displaying the command
history, retrieving commands from the history, editing command lines,
etc. To obtain HELP information, enter the ? or the F1 key (PC console
or ANSI 3.64 terminal) at the programmer prompt (i.e., the > prompt).
The following shows the HELP information that is displayed.
Figure 2-2 - Programmer Shell HELP Text
Enter a MUMPS command or a shell command.
Shell commands and editing keys are:

? or F1 - Display this help
?? - Display last 10 lines of command history
?n - Display 10 lines of command history from line n
<PGUP> or Ctrl-P - Display previous 10 lines of history
<PGDN> or Ctrl-N - Display next 10 lines of history
!n - Recall line n from the command history

F2 or Ctrl-Z - Recall the original (unedited) line
F3 - Recall last line of command history
<UP> or Ctrl-K - Recall previous line of command history
<DOWN> or Ctrl-J - Recall next line of command history
<LEFT> or Ctrl-L - Move cursor left one character
<RIGHT> or Ctrl-R - Move cursor right one character
<HOME> or Ctrl-B - Move cursor to beginning of line
<END> or Ctrl-E - Move cursor to end of line
<BS> or Ctrl-H - Delete the character before the cursor
<DEL> - Delete the character under the cursor
Ctrl-D - Delete from cursor to end of the line
Ctrl-U or Ctrl-X - Delete entire command line
F4 or Ctrl-V - Toggle Volume Group/UCI display
>

2.9.2 Command Line Editing
When entering commands or routine lines in direct mode, it is not
uncommon for typing mistakes to occur. When this happens, the normal
solution is for the programmer to reenter the line containing the error.
However, this can become extremely frustrating when the line is lengthy.
As an alternative, the programmer can edit the line containing the error.
If the error is detected before entry of the line is complete (i.e., before
the RET is entered), then the editing keys can be used to correct the
error. If the line entry has been completed, then the line can be recalled
from the command history and the editing keys can be used to correct
the error. Table 2-2 below defines the command line editing keys.
Table 2-2 - Command Line Edit Keys
PC Console Other Description of Action Performed

ANSI 3.64 Terminals By the MSM Programmer Shell
CTRL-L Move cursor left one character.
CTRL-R Move cursor right one character.
HOME CTRL-B Move cursor to beginning of line.

END CTRL-E Move cursor to the end of line.
BACKSPACE BACKSPACE Delete character before cursor.
DEL DEL Delete character under cursor.
CTRL-D CTRL-D Delete from cursor to end of line.
CTRL-U CTRL-U Delete entire command line.
CTRL-Z CTRL-Z Recall original line from history.
Note that the command line editor is always in insert mode. Whenever
a character is entered, it will be inserted before the character that is under
the cursor. When the cursor is at the end of the input line, this has the
effect of adding a character at the end of the line.

2.9.3 Command History
The MSM system maintains a history of commands that have been
entered since the user last logged onto the system in direct mode. The
shell includes commands to display the command history and to recall
individual commands from the history file. Once a command has been
recalled, it behaves exactly as if it was directly entered by the
programmer. Table 2-3 below shows the commands that are available
to access the command history file.
Table 2-3 - History File Commands

? ? ? ? Display the last 10 lines of the
command history file.
? n ? n Display 10 lines of the command
history file starting at line n.
PgUp CTRL-P Display the previous 10 lines of
the command history file.
PgDn CTRL-N Display the next 10 lines of the

! n ! n Recall line n from the command
history file.
CTRL-K Recall the previous line from the
CTRL-J Recall the next line from the

Normally, any command that is three or more characters in length will

automatically be appended to the command history file when it is entered.
However, there is one exception to this rule. If the command that is
entered identically matches the previous command that was entered, then
it will not be added to the command history file.

The commands that access the history file are entered at the programmer
prompt. Shell commands cannot be entered on the same input line with
non-shell commands. The following example shows a typical sequence
of user inputs that access the command history file.
Figure 2-3 - Programmer Shell Command History
>?? Command History:

5 W ^SYS("VERSION")
6 D ^SYSGEN
7 D ^DISKMAP
8 W 32456\512*512
9 W 32256/512
10 D ^%LOGON
11 D ^%GCH
12 D ^%GDE
13 D ^%LOGON
14 D ^%SS
>?1 Command History:
1 D ^%GD
2 D ^%RD
3 D ^%SP
4 D ^%SS
5 W ^SYS("VERSION")
6 D ^SYSGEN
7 D ^DISKMAP
8 W 32456\512*512
9 W 32256/512
10 D ^%LOGON
>

2.9.4 Miscellaneous Shell Commands
In addition to the commands described above, several function keys
invoke actions within the shell. Table 2-4 below describes each of these
function keys.
Table 2-4 - Miscellaneous Shell Commands

F1 ESC 1 Display the HELP text.
F2 ESC 2 Recall original unmodified line.
F3 Esc 3 Recall last line in command
history.
F4 Esc 4 Re-display the current line.

CHAPTER 3
USING PERIPHERAL DEVICES
This chapter describes the peripheral devices, both physical and logical,
that are supported by the MSM system. It includes information on how
to use each type of device and how to control the features and functions
associated with each device.
3.1 Overview
The MSM system includes support for a wide assortment of physical as
well as logical devices. The physical devices include terminals, modems,
printers, and sequential devices such as floppy disks, cartridge disks and
tape drives. The logical devices can be used to examine or modify the
contents of main memory and auxiliary disk storage, and exchange data
between active partitions.
Every user of the system (i.e., every job on the system) can access any
of these devices. In order to access a device, the job must first gain
ownership of the device. This is done by issuing an OPEN command
directed to the device. If the device is available, it is immediately added
to the list of devices owned by the job. In a multi-user environment, if
the device is not available, execution of the job is suspended until the
device becomes available.
When a device is OPENed, the user can also specify the amount of time
to wait if the device is not immediately available. After the specified
time interval, the OPEN command is terminated if the device is still not
available. The OPEN mechanism permits a job to gain ownership of
more than one device at a time.
The system provides a facility to specify which device is to be used for
input and output operations since each job can access only one device
at a time. Each job directs input and output to a specific device with the
USE command. The USE command makes the specified device the
current device. The current device is used for all subsequent input or
output operations until explicitly changed by another USE command or
until the user logs off the system.
Using Peripheral Devices 3-1

Once ownership and use of a device have been established, the job can
read from or write to the device using extended ASCII character strings.
When a device is no longer required by a job, it should be returned to
the system and made available for other jobs. This is done by issuing a
CLOSE command to the particular device. Once a device is returned to
the system with a CLOSE command, it must be acquired with the OPEN
command before it can be USEd again. Note that when a terminal type
device is OPENed, device characteristics established through previous
OPEN or USE commands are automatically reset to the default values
designated by the SYSGEN program.
3-2 Using Peripheral Devices

3.2 Device Designators
Every device in MSM is assigned a unique device designator. This
designator is used as an argument on the OPEN, USE and CLOSE
commands to identify a specific device. Table 3-1 below lists the device
designators.
Table 3-1 - Device Designators
Number Device Description

1 Primary Console Device
2 MSM Spooling/Despooling Device
3-19 Terminal Devices (Serial or Parallel)
20 Routine Interlock Device 1
• • • •
47 Magnetic Tape Drive 0
• • • •
50 Magnetic Tape Drive 3
51 Host File Server Unit 0
• • • •
54 Host File Server Unit 3
55 Host Spooling Device
56 Reserved for Specialized Device Drivers
• • • •
58 Reserved for Specialized Device Drivers
59 Sequential Block Processor 0
• • • •
62 Sequential Block Processor 3
63 VIEW Device for Disk and Memory Operations
64-199 Terminal Devices (Serial or Parallel)
• • • •
224 In-Memory Job Communication, Receiver 0
225 In-Memory Job Communication, Transmitter 0
• • • •
254 In-Memory Job Communication, Receiver 15
255 In-Memory Job Communication, Transmitter 15
256+ Terminal Devices (Serial or Parallel)

3.3 Accessing Peripheral Devices
Whenever a user logs onto the system, a new job is created and a unique
number is assigned to the job. This number is stored in the $JOB Special
Variable. As part of the process of creating a new job, the system assigns
ownership of the terminal (i.e., the device used to logon) to the job. The
device designator that corresponds to the terminal is stored in the $IO
Special Variable.
The $IO Special Variable always contains the device designator of the
current device. All input or output operations (e.g., READ, WRITE,
ZPRINT, etc.) are always directed to the current device. The initial value
assigned to the $IO Special Variable at logon is referred to as the
Principal device. By definition, any reference to a device designator of
0 (zero) is interpreted to mean the Principal device.
As previously discussed in section 3.1 (Overview), a job can own more
than one device. Ownership of a device is obtained by issuing an OPEN
command with one or more device designators as the operand of the
command. Once ownership of a device has been obtained by a job, the
device is no longer available to other jobs except for output through the
ZUSE command. The two exceptions to this rule are the spooling device
and the host file server devices. The job can then direct input and output
operations to a specified device by issuing USE commands.
The operand of the USE command is the designator of the device that
is to be used as the current device. The designator for the device, which
must have been previously opened, becomes the new value for the $IO
Special Variable. This device remains the current device until changed
by another USE command. The $IO Special Variable can be referenced
in any expression to determine the current device, but it can only be
changed with the USE command.
In addition, if MSM detects an error during processing, it internally

issues an OPEN and USE command with a value of 0 (zero) as the
operand before displaying the error message. This redirects the output
to the Principal device to ensure that the error message is displayed at
the terminal that initiated execution of the job. This also occurs when
a program terminates normally and returns to programmer mode (i.e.,
before issuing the programmer prompt).

After a job has finished using a device, it should issue a CLOSE
command to the device. This returns the device to the system and allows
it to be reassigned to other jobs. If a job terminates execution with a
HALT command, any devices that are still open are automatically
CLOSEd by the system.
3.4 Input And Output Commands

In MSM all of the peripheral devices, with the exception of the VIEW
device and Routine Interlock, look like sequential devices. Because of
this, the same input and output commands can be used regardless of the
type of device being accessed. The input and output commands
supported by MSM are:
READ The READ command is used to request input

from a device. The information returned by the
device is stored in a local variable. As an
option, the command can include a prompt
string and formatting characters.
WRITE The WRITE command is used to send

information to a device. It can include format
characters, ASCII values, literals, and local or
global variables.
ZLOAD The ZLOAD command (with no operands)
transfers a routine from the current device to
the partition. If an operand is specified, the
system searches the routine directory of the
current UCI for a routine name that matches
the operand. If it finds a match, the routine is
loaded into the partition.
ZPRINT The ZPRINT command writes the routine
loaded in the partition to the current device.
ZWRITE The ZWRITE command writes the contents of
all or part of the local symbol table to the
current device.

3.5 Special Variables
For each device, the system maintains a set of special variables that
provide feedback information. These variables are:
$X The $X variable represents the cursor position

relative to the left margin. The system only
counts printable characters (i.e., ASCII
characters between the decimal values of 32
and 126, inclusive, and all 8 bit ASCII values).
If terminal-specific control sequences are used
to move the cursor, then $X no longer
represents the true cursor position unless it is
explicitly updated via the SET or USE
command. If the value of $X exceeds 255
characters, the system resets it to 0.
$Y The $Y variable contains the number of line
feed characters that have been written to the
device since the last form feed. If the value of
$Y exceeds 255 characters, the system resets it
to 0.
$ZA The $ZA variable contains information

specific to the device being accessed. It can
contain error indicators, status information, or
other information.
$ZB The $ZB variable contains additional
information specific to the device being
accessed. It may contain block numbers, buffer
offsets, or other information.
$ZC The $ZC variable contains additional
information that is common to all devices in
MSM. It indicates whether an end-of-file
condition or error condition occurred.

3.6 Mnemonic Namespaces
In MSM, a feature referred to as Mnemonic Namespaces has been
implemented to allow users to develop MUMPS applications that are
implementation independent. Mnemonic Namespaces can be used for
accessing many of the different device types supported by MSM. This
includes: Terminal Devices, Sequential Block Processor, Host File
Server, Interjob Communication, Magnetic Tape, Spool Device, and the
Host System Spool Device.
In particular, any device supported by MSM that allows the WRITE
command to be used can take advantage of Mnemonic Namespace
support. In the same way that format arguments are specified on the
WRITE command, Mnemonic controls can be specified. Mnemonic
Controls are specified in the following format:
/MnemonicName(Operand1,Operand2, ... ,Operandn)
Note that in this example, the slash (i.e., /) is required, but the operands
are optional. Within a READ or WRITE command, a Mnemonic Control
can be used anywhere that a Format character can be used. In fact, by
definition, Mnemonic Controls are considered to be Format characters.
The MSM system can support multiple Mnemonic Namespaces. The
supported Namespaces can be system-supplied (e.g., ANSI X3.64-1979
for terminals, ZWINTERM for windows on dumb terminals, etc.) or
user-defined. Through the USE command, the application identifies the
namespace associated with the device. Finally, MSM also provides
$DEVICE and $KEY Special Variables to further enhance the
capabilities of Mnemonic Namespaces. Refer to the MSM Language
Reference Manual for additional information on the USE command, the
READ and WRITE commands, Format characters, and the $DEVICE
and $KEY Special Variables.
As previously stated, Mnemonic Namespaces fall into two separate
categories: system-supplied Namespaces and user-defined Namespaces.
System-supplied Namespaces and user-defined Namespaces function
identically. They only differ in the way that they are created. Refer to
Appendix F (Mnemonic Namespaces) for a list of the Namespaces
supplied with the system. User-defined Namespaces are created and
maintained using the SYSGEN utility. Refer to the appropriate MSM
System Manager’s Guide (Generating the System) for additional
information on the SYSGEN utility and user-defined Namespaces.

3.7 Terminal Devices
In MSM, all terminal devices such as printers, hardcopy, and CRTs are
handled in the same manner. These devices may be serial (i.e.,
RS-232C), parallel, Local Area Transport (LAT), TCP/IP, etc. They are
defined to the system through the SYSGEN process. Refer to Chapter
9 (Generating the System) for additional information on how to define
terminal devices.
Device numbers for terminals are 1, 3 through 19, and 64 through 199.
Device 1 is always the main console; however, it can be used for other
functions as well. Device 3 is usually assigned as the primary printer.
Although many of the utilities assume this, they still function properly
if another device is used. In that case, the user has to specify the desired
output device. The following commands are valid for terminal devices:
OPEN WRITE READ
CLOSE ZPRINT ZLOAD
USE ZWRITE ZUSE
You cannot use all of these commands with all types of terminals. For
example, issuing a READ or ZLOAD command to a printer would not
make sense since printers are output only devices.
3.7.1 OPEN, USE, And CLOSE Parameters

When a terminal device is opened, or when output is directed to the
device with the USE command, additional information can be specified
with the command to alter options in effect for the terminal. Options
specified for the terminal remain in effect until they are changed by a
subsequent OPEN or USE command, or until the device is CLOSEd.
The format of the OPEN, USE, and CLOSE commands is:
OPEN{:Cond} Dev{:(Opt1:Opt2:...:Opt13)} {:Time}

USE{:Cond} Dev{:(Opt1:Opt2::...:Opt13)}
CLOSE{:Cond} Dev
In each of these commands, the Cond operand is a post-conditional
statement used to control execution of the command. If the
post-conditional is true, then the command is executed. If it is false, the
command is not executed. The Time operand on the OPEN command
indicates the amount of time (in seconds) to wait for the specified device
to become available.

Upon completion of the OPEN command, when the time has been
specified, the $TEST Special Variable contains a 1 if the OPEN was
successful; otherwise, it contains a 0. If the timeout option is not
specified, $TEST remains unchanged.
The options on the OPEN and USE commands are evaluated in
left-to-right order with one exception; option 6 is evaluated before option
5. In other words, the device characteristics specified by option 6 are
reset first, then the characteristics specified by option 5 are set.
Right Margin - (Opt1)

The right margin specification controls when a carriage return/line feed
sequence automatically is inserted by MSM during output operations.
Whenever the value of the $X Special Variable is equal to the right
margin, the system inserts a carriage return/line feed before it outputs
the next character to the device. Insertion of the carriage return/line feed
is suppressed if the character being output is a carriage return. If the
right margin is set to 0, then automatic insertion of a carriage return/line
feed sequence is suppressed.
Reserved For Future Use - (Opt2)

This option is reserved for future use; if present, the value is ignored.
For compatibility with future releases of the MSM system, this option
should not be used.
Fixed Length Read - (Opt3)

This option is used to set the maximum number of characters to be
accepted on the next read operation. The READ command is
automatically terminated when the specified number of characters have
been entered, even if no carriage return has been received. After
completion of each READ command, the system resets this value to 255.
Note that the syntax USE PORT:(::3) READ X is equivalent to USE
PORT READ X#3.
Reserved for Future Use - (Opt4)

This option is reserved for future use. If present, the value is ignored.
For compatibility with future releases of the MSM system, this option
should not be used.

Device Characteristics to be Set - (Opt5)
This option is used to turn on various functions for the terminal device.
The value of this option when treated in binary, represents a bit string,
where each bit specifies a particular characteristic. If the bit is on, then
the characteristic is set. If the bit is off, then the characteristic is left
unchanged.
Table 3-2 below contains a list of the bit numbers and a description of
the functions associated with each bit. It also includes the decimal values
that correspond to the bit value. Note that the characteristics associated
with Opt6 are applied before the Opt5 values.
Table 3-2 - Options Controlling Terminal Functions
Bit# Description of Characteristics

31 RESERVED - Reserved for future use.
26 PROMPTED READ - If this bit is set, a prompted READ

operation does not flush (i.e., discard) the characters in the
input buffer. If this bit is not set, the system flushes the
characters in the input buffer each time a prompted read is
issued. (Decimal value = 67108864)
25 TYPEAHEAD - If this bit is set, at the start of each READ,

the system flushes the input buffer of all characters that have
been received. If this bit is not set, the system uses any
characters in the input buffer as a result of typeahead. (Decimal
value = 33554432)

24 ZUSE - If this bit is set, all WRITE commands directed to this
terminal by a ZUSE command are ignored. The ZUSE
command itself can still be used to check the value of $ZA or
any of the other Special Variables. If this bit is not set, the
system allows ZUSE commands to write data to the terminal.
(Decimal value = 16777216)
23 PASS ALL - If this bit is set, the system does not interpret any
characters received other than user-specified READ
terminators (see Opt9) or ESC if ESCAPE processing is
enabled. If this bit is not set, the system-defined control
characters are interpreted. (Decimal value = 8388608)
21 CTRL/O - If this bit is set, CTRL/O is treated as a normal data

character. If this bit is not set, CTRL/O signals the system to
discard output data until another CTRL/O is received by the
system. (Decimal value = 2097152)
20 CONTROL CHARACTERS - If this bit is set, control

characters not supported by MSM are ignored (i.e., not passed
to program and not echoed). If this bit is not set, they are
treated as normal input characters. (Decimal value = 1048576)
19 EMPTY LINE DELETE - When this bit is set, if the system

BACKSPACE character (Backspace or Delete, or Both) is
received and the input buffer is empty, then the READ
operation is terminated and the low order byte of $ZB is set to
a value of 127. If this bit is not set, the BACKSPACE character
that is received when the input buffer is empty is ignored.
18 DATA LENGTH - If this bit is set, the system allows input of

full 8 bit characters. If this bit is not set, the high-order bit of
each character is set to 0 as it is read. By not setting this bit,
input is restricted to the 7-bit ASCII character set. (Decimal
value = 262144)

17 $X and $Y UPDATE - If this bit is set, the system does not
update the values of the $X and $Y variables on a WRITE *N
type of operation. If this bit is not set, the values of $X and
$Y are updated when a WRITE *N sequence is used. (Decimal
value = 131072)
16 TYPE OF CRT - If this bit is set, it indicates that the terminal

supports ANSI type escape sequences to position the cursor.
If this bit is not set, it indicates that the terminal accepts VT52
type escape sequences to position the cursor. On output, this
bit only has meaning if bit 7 is also on. On input, if this bit is
set, it indicates that the system is to recognize VT220 extended
function keys for Escape processing. Otherwise, only the
standard VT100 function keys are recognized. (Decimal value
= 65536)
15 INTERRUPT - If this bit is set, it indicates that an interrupt

has been received from the terminal. If this bit is not set, it
indicates that a break has not been received from the terminal.
The bit is reset using Opt6 or when Break 0 is executed.
14 LOWERCASE - If this bit is set, all lower-case characters sent

by the terminal are converted to upper-case. If this bit is not
set, lower-case characters are passed through as they are
received. (Decimal value = 16384)
13 LINEFEED - If this bit is set, the system sends a carriage return

in place of the carriage return/line feed sequence for the
exclamation point (!) format character in WRITE commands.
This also applies to the right margin if the output exceeds the
margin. If this bit is not set, a carriage return/line feed sequence
is sent. (Decimal value = 8192)
12 TAB CONTROL - If this bit is set, the tab character ($C(9))

is passed directly through to the port; otherwise, the tab
character is translated to the number of spaces necessary to
move the cursor to the next tab position. Tabs are multiples
of 8 positions on output. (Decimal value = 4096)

11 LINE CARRIER - If this bit is set, it indicates that the line
carrier signal is present. If the bit is not set, then either the
line is not modem-controlled or if the line is
modem-controlled, then the line carrier is not present. This
bit cannot be set by the user; it can only be referenced via $ZA.
10 PRINTER - If this bit is set, it indicates that the device is a

printer. If this bit is not set, the device is not a printer. The
bit is reserved for system use and cannot be set by the user.
9 CONNECT - If this bit is set, the DTR signal is asserted for

the device. If this bit is turned off, the DTR signal is turned
off. If the device is modem-controlled, this bit is turned on by
the system when a modem is connected and off when the
modem disconnects. (Decimal value = 512)
8 LOGON - If this bit is set, the device is not permitted to logon

to the system. If the bit is not set, the device is allowed to
logon. (Decimal value = 256)
7 CURSOR POSITIONING - If this bit is set, it indicates that a

cursor positioning escape sequence should be sent when the
value of $X or $Y is altered or if Opt7 is specified on an OPEN
or USE command. If the bit is not set, cursor positioning
sequences are not sent. The actual cursor positioning sequence
that is sent is determined by the value of bit 16, Type of CRT.
6 ESCAPE - If this bit is set, the ESCAPE processing feature is

enabled. If this bit is not set, ESCAPE processing is disabled,
and the escape character is interpreted as a carriage return.
Refer to the section below titled Escape Processing for a
complete description of this option. (Decimal value = 64)

5 CTRL/S - This bit is only supported in MSM-PC/PLUS. If
the bit is set, it indicates that a CTRL/S has been received from
the terminal. All output to the terminal is suppressed until a
CTRL/Q is received from the terminal. If this bit is not set,
the terminal is in a normal state and can receive output. This
bit cannot be set by the user; it is reserved for system use.
4 CTRL/O - If this bit is set, it indicates that a CTRL/O has been

received from the terminal. All output to the terminal is
discarded until another CTRL/O is received from the terminal.
If this bit is not set, the terminal is in a normal state and can
receive output. This bit cannot be set by the user; it is reserved
for system use. (Decimal value = 16)
3 MODEM CONTROL - If this bit is set, it indicates that the

line is modem-controlled. If this bit is not set, it indicates that
the line is not modem-controlled. (Decimal value = 8)
2 CRT - If this bit is set, it indicates that the terminal being used
is a CRT and characters are to be erased from the screen on
backspace. If this bit is not set, it indicates that the terminal
is a hardcopy device and \ is echoed on backspace. (Decimal
value = 4)
1 OUTPUT ONLY - If this bit is set, it indicates that the terminal

is an output-only device. If the bit is not set, it indicates that
the device supports READ operations. (Decimal value = 2)
0 ECHO - If this bit is set, it indicates that characters received

from the terminal are not to be echoed back to the terminal. If
this bit is not set, printable characters received from the
terminal are written back to the terminal. (Decimal value = 1)
To enable functions, the appropriate bit or bits as indicated by this option

field must be turned on with the OPEN or USE command. To do this,
specify the decimal value whose binary representation contains the bits
to be turned on. A decimal value or an expression that evaluates to a
decimal value can be specified.

Device Characteristics to be Cleared - (Opt6)
This option allows the bits associated with various terminal functions to
be turned off. The definition for the bits is the same as described for the
Device Characteristics to be Set - (Opt5). To disable functions, the
appropriate bit or bits as indicated by this option field must be turned
off with the OPEN or USE command.
To do this, specify the decimal value whose binary representation
contains the bits to be turned off. A decimal value or an expression that
evaluates to a decimal value can be specified.
Value of $X and $Y Special Variables - (Opt7)

This option is used to set the value of the $X and $Y special variables.
The new values are specified as a single number that is equal to the new
value of $Y times 256 plus the new value of $X. For example, assume
that $X is to be set to column 40 and $Y is to be set to row 12. Then a
value of 3112 would be specified.
As an alternative, the values of $X and $Y can be set directly by the

user. Using a normal set command, the user can assign new values to
the $X and $Y special variables. For more information, refer to the MSM
Reference Manual (Special Variables).
Initialization Parameters - (Opt8)

This option is used to specify the baud rate, parity, data bits, stop bits,
and flow control characteristics for the device. The table on the following
page shows the value for each of these functions.

Table 3-3 - Initialization Parameters
Option Parity Flow Data Bits Baud

Value Check Control Stop Bits Rate
0 - XON/XOFF - -
1 - - - 50
2 NONE - - 75
3 - CTS/RTS - 110
4 - - - 134.5
5 ODD - 7 Bit 1 Stop 150
6 - - 7 Bit 2 Stop 200
7 - - - 300
8 - - - 600
9 EVEN - 8 Bit 1 Stop 1200
10 - - 8 Bit 2 Stop 1800
11 - - - 2400
12 - - - 4800
13 - - - 9600
14 - - - 19200
15 - - - 38400
The value is a 16 bit number where the first 4 bits specify the parity, the
second 4 bits specify flow control, the third 4 bits specify the number
of data bits and stop bits, and the fourth 4 bits specify the baud rate. The
initialization value must be specified using the full 16 bits. For example,
if the baud rate is changed, the parity, data bits, and stop bit values must
be specified again.
To determine the option value, use the indicated parity check value times
4096, plus the indicated value for data bits and stop bits times 16, plus
the indicated value for the baud rate. Stated differently:
(Parity*4096)+(Flow*256)+((Data & Stop)*16)+Baud
If this option is omitted or a 0 (zero) is used for any of the values of

parity, data bits or baud rate, the device values for parity, data bits, stop
bits, and baud rate are not changed.

READ Terminators - (Opt9)
This option specifies which ASCII control characters (i.e., values 0
through 31, and 127) should be recognized as READ terminators.
Whenever a READ command is issued to the device and one of the
specified characters is encountered, the READ terminates. The value
of the termination character is stored in the low byte of $ZB. When the
device is opened, the RET and ESC are set as the default terminators
(i.e., $C(13,27)).
Up to 32 different READ terminator characters can be specified for each
terminal device. It is important to point out that when the null string is
specified as the only terminator, there are no READ terminator
characters in effect for the device. When this occurs, the program is
required to use either fixed length READs (e.g., READ X#80) or single
character READs (e.g., READ *X) to process terminal input. Also, if
the CTRL/S character (i.e., $C(19)) is specified as one of the
terminators, it is interpreted to mean the DEL character (i.e., $C(127))
instead. Therefore, the 32 possible READ terminator characters consist
of ASCII values 0 through 18, 20 through 31, and 127.
Device Name - (Opt10)

This option specifies the name of the device that is connected to the port.
It is used by the MSM system utilities to configure the device during
system startup and should not be accessed directly by the user. With
this parameter, the connection between the logical device and the
physical device can be made dynamically. This option is only valid for
MSM-PC and MSM-PC/PLUS systems.
Text Buffer Size - (Opt11)

This option is used to specify the size of the text buffer for a window
device. The size of the text buffer is specified as the number of rows
times 256, plus the number of columns. Therefore, for a text buffer of
15 rows by 60 columns, a value of 3900 (i.e., 15 times 256 plus 60)
would be specified. Note that the size of the text buffer is limited to
8188 characters (i.e., the number of rows times the number of columns
must be less than or equal to 8188). Refer to the MSM-PC System
Manager’s Guide, Chapter 6 (Window Manager) for additional
information on windows. This option is only valid for MSM-PC and
MSM-PC/PLUS systems.

Window Size - (Opt12)
This option is used to specify the size of the Window on the console
device. The size of the window is specified as the number of rows times
256, plus the number of columns. Therefore, for a window of 12 rows
by 40 columns, a value of 3112 (i.e., 12 times 256 plus 40) would be
specified. Note that the size of the window cannot exceed the size of
the text buffer that is associated with the window. Also, the upper left
hand corner of the window is placed over the upper left corner of the
text buffer. Refer to the MSM-PC System Manager’s Guide, Chapter 6
(Window Manager) for additional information on windows. This option
is only valid for MSM-PC and MSM-PC/PLUS systems.
Window Placement - (Opt13)

This option is used to specify the location of the Window on the console
device. The location of the window is defined as the row and column
where the upper left hand corner of the window is to appear. The location
is specified as a single value computed from the row number times 256
plus the column number. Therefore, to place the upper left hand corner
of the window in column 9 of row 3, a value of 777 (i.e., 3 times 256
plus 9) would be specified. The location of the window must be within
the physical bounds of the console display (i.e., column 1 to 80 and row
1 to 25, inclusive). Refer to the MSM-PC System Manager’s Guide,
Chapter 6 (Window Manager) for additional information on windows.
This option is valid only for MSM-PC and MSM-PC/PLUS systems.
3.7.2 Escape Processing

Escape processing in MSM is a feature that allows the programmer to
handle input escape sequences generated by a terminal with a minimum
amount of actual coding in the program. Most terminals transmit an
escape sequence whenever a program function key or arrow key is
pressed. The escape sequence usually consists of an escape character
(i.e., $C(27)) followed by one or more additional characters.
When ESCAPE processing is enabled, the system reads one additional

character after the escape character is received and terminates the READ.
If the character received is another escape (ESC), a question mark (?),
a left bracket ([), or a letter O, it is ignored and one more character is
read and similarly examined. This character is stored in the high-order
byte of the $ZB Special Variable, (i.e., $ZB\256).

MSM supports both standard VT100 function keys and VT220 extended
function keys. The function key codes are as follows:
Table 3-4 - VT100/VT220 Function Key
Function Key Escape Sequence $ZB\256

PF1 EscOP 32
PF2 EscOQ 33
PF3 EscOR 34
PF4 EscOS 35
F1-F5 Local Use Only -
F6 Esc[17~ 37
F7 Esc[18~ 38
F8 Esc[19~ 39
F9 Esc[20~ 40
F10 Esc[21~ 41
F11 Esc[23~ 43
F12 Esc[24~ 44
F13 Esc[25~ 45
F14 Esc[26~ 46
HELP Esc[28~ 48
DO Esc[29~ 49
F17 Esc[31~ 51
F18 Esc[32~ 52
F19 Esc[33~ 53
F20 Esc[34~ 54
UP ARROW Esc[A 17
DOWN ARROW Esc[B 18
RIGHT ARROW Esc[C 19
LEFT ARROW Esc[D 20
FIND Esc[1~ 21
INSERT HERE Esc[2~ 22
REMOVE Esc[3~ 23
SELECT Esc[4~ 24
PREVIOUS SCREEN Esc[5~ 25
NEXT SCREEN Esc[6~ 26

If the escape sequence was received while a single-character READ
command was active, the value of the variable specified on the READ
is 0. If the READ was not terminated with an escape sequence, then the
high-order byte of the $ZB Special Variable is 0. In either case, the
low-order byte of $ZB contains the ASCII value of the character that
terminated the READ (i.e., $ZB#256 is RETURN or ESCAPE).
3.7.3 $ZA, $ZB, And $ZC Feedback Information

After each terminal input or output command, status information about
the terminal and the last operation that was performed is stored in the
$ZA, $ZB, and $ZC Special Variables. The routine that issued the input
or output command can interrogate these variables and take different
programming paths depending on their contents. For terminal devices,
the meaning of these variables is:
$ZA is the 32-bit value of the device characteristics for the
terminal. The individual bit values are defined in
Section 3.7.1 (OPEN, USE, And CLOSE Parameters)
OPEN and USE Parameters, Device Characteristics to
be Set (Opt 5).
$ZB contains information describing how the input

command was terminated. If ESCAPE processing is
disabled, then the value of $ZB is:
$ZB=13 if the READ command was terminated

with a carriage return.
by an escape character.
$ZB=nn if the READ command was terminated

because one of the user-specified
termination characters was received
(where $C(nn) is the termination
character).

because the number of characters
specified by the field length option was
received.

If ESCAPE processing is enabled, then $ZB contains
a two byte value with the low-order byte containing
the same information described above. The high-order
byte contains the escape sequence value as shown in
Table 3-4.
$ZC contains 0 (zero) if the operation completed normally,
-1 if end-of-file was reached, or 1 if a device error
occurred.
It is important to remember that the values of $ZA, $ZB, and $ZC are
always returned for the current device. A USE command must be issued
to make the desired device the current device. Also, if a USE command
is issued for a device that you do not own, a <NOPEN> error message
is generated by the system.

3.7.4 Terminal Device Examples
The following examples show how to access terminal type devices via
the OPEN, USE, and CLOSE commands. The use of the # (number
sign) indicates the value given is in hexadecimal format.
Table 3-5 - Terminal Device Examples
OPEN/USE Command Description

U 0:(0::::64) Turn on ESCAPE processing for
principal device and disable
automatic line wrap.
U $I:(::::::::$C(13,27,0)) Set READ terminators to carriage

return, escape, and null.
O 4:(::::#840001):5 OPEN device 4, turn on pass-all and

8-bit modes, turn off echo, and wait
up to 5 seconds for the device to
become available.
U 0:(:::::::9*4096+(5*16)+9) Set current device to 7 data bits,

even parity, 1 stop bit, 1200 baud.
U $I:(::::33554432) Disable type-ahead for current

device.
U $I:(:::::512) Turn off DTR signal for current

device (forces modem to hangup).
U 0:(::::P:$ZA) Turn off all Device Characteristics

bits, then turn on the bits specified
by the value of variable P.
U $P(::::16385) Turn off echo and turn on lowercase

processing on current device.
U 3:132 Set line width to 132 characters.

Parentheses are optional if only
Opt1 is specified.

3.8 Sequential Block Processor
The Sequential Block Processor (SBP) allows all types of disk devices
to be accessed as either sequential devices or as random-access devices.
The SBP space must have been previously allocated using the SBP utility
program. If an attempt is made to access space which has not been
allocated, then a null value is returned and the $ZA Special Variable is
set to a value of -1.
Internally, SBP always transfers information to and from the device in
blocks of 1024 characters, which is the standard block size for all MSM
disk resident data. The system automatically blocks and unblocks the
data for the user. The system reserves the last 12 bytes of each block
(i.e., byte 1012 through byte 1023) for SBP control information. If the
data being written to the SBP does not fit into the available space
remaining in a block, the system automatically splits the data across two
blocks. This ensures that no data space is wasted in the SBP area.
The SBP devices are assigned device designators of 59 through 62. The
commands which are valid for the SBP device are:
OPEN WRITE READ

CLOSE ZPRINT ZLOAD
USE ZWRITE
To access the SBP device, OPEN the device and specify the starting
block number where processing is to begin. An offset within the block
can also be specified, with 0 being the first byte in the block. All
subsequent accesses to the device are in sequential order. That is, the
next input or output operation begins at the byte immediately following
the last byte of the previous input or output operation.
When accessing the SBP device, input and output operations can be
intermixed. Also, the device can be accessed in random-access mode.
If the device is being used as a random-access device, then prior to each
access you must specify the location from which data is to be retrieved.
This is done by specifying the new block location with the USE
command. As was the case with the OPEN command, an offset into the
block where the transfer is to begin can be specified. When the SBP
device is CLOSEd, all modified blocks are written back to the disk device
at the appropriate locations.

Information is stored as a stream of logical data. Lines are terminated
with the specified delimiter, and null lines are stored simply as the
delimiter. Whenever a READ command is issued, the system begins to
transfer data starting at the current location. The transfer continues until
the delimiter character is encountered or until the maximum number of
characters specified by the READ has been transferred. Blocks are
automatically spanned if necessary to satisfy the READ request.

When the SBP device is opened, and when input or output is directed
to the device with the USE command, additional information can be
specified to the system. This information is used to position the device
at a specified location. The format of the OPEN, USE, and CLOSE
commands is:
OPEN{:Cond} Dev{:(Opt1:Opt2:Opt3:Opt4:Opt5)}{:Time}
USE{:Cond} Dev{:(Opt1:Opt2:Opt3:Opt4:Opt5)}
CLOSE{:Cond} Dev

post-conditional is true, then the command is executed. If it is false,
then the command is not executed.
The Time operand on the OPEN command indicates the amount of time
to wait for the specified device to become available. When the OPEN
completes, the $TEST Special Variable contains 1 if the open was
successful, otherwise, it contains 0.
Block Offset - (Opt1)

The block offset indicates the starting location (i.e., byte) within the
block where the SBP device is to be positioned. The number must be
between 0 and 1011, where 0 is the first byte, 1 is the second byte, etc.
The remaining bytes within the block (i.e., bytes 1012 through 1023)
are used by the system to store control information. If this option is
omitted, processing begins with the first byte of the block.

Disk Block Number - (Opt2)
The disk block number indicates where the SBP device is to be
positioned. It is the relative block number from the beginning of the
volume group. Refer to Chapter 5 (Volume Groups) in the appropriate
MSM System Manager’s Guide for information on how to compute the
block number. When issuing an OPEN command, this option must be
specified; otherwise, a <SYNTX> error is generated. If negative block
number is specified, a journal area is indicated. Note that the block
number of a Map block within an SBP area can not be specified with
this parameter.
Volume Group Number - (Opt3)

The volume group number is used to identify which volume group
contains the SBP area to be accessed. The system may contain up to 2
independent volume groups numbered 0 through 1. The specified
volume group must be mounted prior to issuing an OPEN for the desired
SBP area. If it is not, the system generates a <DKHER> error. If the
volume group is not specified, volume group 0 is assumed.
It is important to note that block numbers are incremented sequentially
across volumes within a volume group. For additional information on
block numbers, refer to Chapter 5 (Volume Groups) in the appropriate
MSM System Manager’s Guide. For additional information on MSM
volume groups and how to define them, refer to Chapter 4 (Generating
the System) in the appropriate MSM System Manager’s Guide.
READ Terminator - (Opt4)

The READ terminator option specifies the sequence that separates
records recorded in stream format. Whenever a WRITE ! is issued, the
specified sequence is inserted. Whenever a READ is issued and the
specified sequence is encountered, the READ terminates.
The sequence can be only 1 character in length and may contain any
ASCII value. If this option is omitted, a default value of $C(255) is
assumed.

Record Format - (Opt5)
The record format option is used to specify the method of recording the
data within a block. Valid record formats are S for stream mode and V
for variable length mode. The value of this option can be upper-case or
lower-case and must be enclosed in quotation marks (e.g., "S"). In stream
mode, the system uses the READ terminator sequence specified in Opt4
above, to separate records. Whenever a WRITE ! is issued, the READ
terminator sequence is inserted.
In variable length mode, the system prefixes each record with a two byte
field that contains the length. If the length field is zero, it indicates an
end-of-file condition. If the SBP is opened in variable length mode and
it is improperly positioned through the USE command, unpredictable
results may occur. If this option is omitted, stream format is assumed.

After each SBP input or output command, status information about the
results of the command is stored in the $ZA, $ZB, and $ZC Special
Variables. The routine that issued the input or output command can
interrogate these variables and take different programming paths
depending on their contents. For the SBP device, the meaning of each
variable is as follows:
$ZA contains the relative block number of the disk buffer
currently being processed by the SBP.
$ZB contains the offset in the block to the next byte to be
processed. This is 1 byte past the last byte processed
by the previous READ or WRITE operation.
occurred.
to make the SBP device the current device. Also, if the block number
that is specified is invalid (i.e., outside the physical bounds of the disk
or specifies a non-existent disk) the system generates a <DKHER> error
message. If an offset into the block greater than 1011 is specified, the
value of $ZA is set to -1.

3.8.3 Sequential Block Processor Device Examples
The following examples show how to access the Sequential Block
Processor devices via the OPEN, USE, and CLOSE commands.
Table 3-6 - Sequential Block Processor Device Examples

O 59:(100:30:1) OPEN SBP device to byte 100 of
block 30 on Volume group 1.
O 59:(:::$C(0)) OPEN SBP device with a READ

terminator of 0.
O 59:(::::"V") OPEN the SBP area using variable

length records.
U 59:(120:350) Position the SBP device to byte 120

of block 350 in volume group 0.

3.9 VIEW Device
The MSM system includes one VIEW device. This device is used to
read or modify information stored on disk. The VIEW device is assigned
a designator of 63. The following commands and functions are valid
for the VIEW device:
OPEN CLOSE USE

CLOSE $VIEW
The VIEW device does not need to be the current device in order to use
the VIEW command or $VIEW function.

Prior to issuing the VIEW command or using the $VIEW function in an
expression, you must obtain ownership of the VIEW device. This is
done by issuing an OPEN command to the device. The format of the
OPEN, USE, and CLOSE commands is:
OPEN{:Cond} 63{:(Opt1:Opt2:Opt3:Opt4)}{:Time}
USE{:Cond} 63{:(Opt1:Opt2:Opt3:Opt4)}
CLOSE{:Cond} 63
In this command, the Cond operand is a post-conditional statement used

to control execution of the command. If the post-conditional is true,
then the command is executed. If it is false, then the command is not
executed. The Time operand on the OPEN command indicates the
amount of time (in seconds) to wait for the specified device to become
available. Upon completion of the OPEN command, when the time has
been specified, the $TEST Special Variable contains a 1 if the OPEN
was successful, otherwise, it contains a 0. $TEST remains unchanged
if a timeout value is not specified.
To inspect memory resident data, it is not necessary to own the VIEW
device. To modify disk data, the VIEW device must be owned. When
the VIEW device is opened, a buffer is assigned to the device. This area
in memory is called the VIEW buffer. The size of the VIEW buffer is
set by Opt1, the default being 1K bytes. Disk data is then read into or
written from this area. When device 63 is CLOSEd, modified data in
the VIEW buffer is NOT automatically written to disk.

This option is reserved for future use. Any value specified for this option
is ignored.

Any value specified for this option is ignored; the option is reserved for
future use.

Any value specified for this option is ignored; the option is reserved for
future use.
Mode Switches - (Opt4)

This option is used to specify the mode in which the VIEW device is
used. Valid options are A for absolute mode, F for format mode, V for
verify mode, S for scan mode (scan for HFS; internal to utilities), P for
protected mode access (exclusive access to blocks that are referenced),
T for test mode (inhibits <DKHER> errors), C for clear mode (reset all
switches), and Z for block zero access (allows block 0 to be written).
The value of this option can be upper-case or lower-case and must be
enclosed in quotation marks (e.g., "P").

After each input or output operation using the VIEW device to disk, the
$ZA Special Variable contains the block number of the disk block
contained in the VIEW buffer. The $ZB and $ZC Special Variables are
not used with the VIEW device; therefore, their contents are
unpredictable.

3.9.3 VIEW Device Examples
The following examples show how to access the VIEW device via the
OPEN, USE, and CLOSE commands.
Table 3-7 - VIEW Device Examples

O 63::60 OPENs the VIEW device and waits
up to 60 seconds for it to become
available.
O 63:(:::"Z") Allow the user to WRITE block 0

(zero) of volume group 0 (zero). If
this switch is not set, block 0 can
only be read.

3.10 Host File Server
The Host File Server (HFS) allows the user to create, read, write and
modify files stored by the host operating system (i.e., MS-DOS, Unix,
and VMS). This device can also be used to access devices such as
printers, floppy disks, cartridge disks, streaming tapes, and industry
standard magnetic tapes from MSM. The files created by the HFS are
fully compatible with the host operating system file structure.
The HFS transfers information to and from the file on a logical record
basis. That means every time a WRITE command is issued, information
is put into the file and every time a READ command is issued,
information up to the next line delimiter (or until a fixed length READ
is satisfied) is taken out of the file.
HFS devices are assigned device designators of 51 through 54.

Whenever an HFS device is opened, users are assigned their own private
copy of the device. This means more than one user can have the same
HFS device open (e.g., two users can have device 51 open at the same
time). Also, a single device can be used to access more than one file at
a time.
The combination of multiple devices per user and multiple files per
device allows a virtually unlimited number of files to be accessed
concurrently. The only restriction on the number of open files is the
limit imposed by the host operating system. The commands that are
valid for the HFS devices are:
OPEN WRITE READ

CLOSE ZPRINT ZLOAD
USE ZWRITE
To access an HFS device, OPEN the device specifying the name of the
file and the mode in which the file is to accessed (i.e., read, write, both
read and write, or append). As an option, a byte offset into the file can
be specified. All subsequent accesses to the file are in sequential order.
That is, each input or output operation begins at the byte immediately
following the last byte of the previous input or output operation. If
necessary, the byte location within the file for the next read or write
operation can be altered by specifying an optional parameter on the USE
command before accessing the file.

When accessing HFS devices, input/output operations can be intermixed
if the file was opened for both READ and WRITE. Also, data can be
addressed in random-access mode. If data is being accessed randomly,
then prior to each I/O operation the location (i.e., offset) of the next data
transfer must be specified. This is done by specifying a new byte location
on the USE command. When an HFS device is CLOSEd, all modified
data is written back to the file at the appropriate locations.
Information sent to HFS devices is stored as a stream of logical data.
Lines are terminated with an operating system-specific delimiter (i.e.,
Carriage Return/Line Feed for MS-DOS, Line Feed for Unix, and Line
Feed for VMS). Null lines are stored simply as the delimiter. Whenever
a READ is issued to an HFS device, the system transfers information
starting at the current location. The transfer continues until a delimiter
character is encountered or the maximum number of characters specified
on the READ command has been reached. The system will span blocks
if necessary to satisfy the READ operation.

When an HFS device is opened, or when input or output is directed to
the device with the USE command, additional information can be
specified to the system. This information is used to specify which file
is to be accessed or to position the device at a specified location. The
format of the OPEN, USE, and CLOSE commands is:
OPEN{:Cond} Dev{:(Opt1:Opt2:...:Opt6)}{:Time}
USE{:Cond} Dev{:(Opt1:Opt2:...:Opt6)}
CLOSE{:Cond} Dev{:Opt1}
The Time operand on the OPEN command indicates the maximum
amount of time, in seconds, to wait for the specified device to become
available. Upon completion of the OPEN command, when the time has
been specified, the $TEST Special Variable contains a 1 if the OPEN
was successful; otherwise, it contains a 0. $TEST remains unchanged
if a timeout value is not specified. The remaining OPEN and USE
parameters are described in the following sections.

File Name - (Opt1)
The fully-qualified name of the host operating system file to be accessed.
It includes an optional path specification (e.g., \MDC\MSM in MS-DOS,
/mdc/msm in Unix, or [MDC.MSM] in VMS), a file name (e.g.,
MYFILE), and an optional extension (e.g., .TXT). When OPENing a
file, if the name is omitted, the job will own the device, but no file will
be opened until Opt1 is specified in a subsequent USE command.
When a OPEN command is issued, the system tests to see if the HFS
device is already open. If so, the open file is CLOSEd before the new
file is OPENed. However, with the Opt2 parameter, the user can specify
that the old file is not to be closed. This way, a single HFS device can
have more than one file open. Then, by issuing USE commands with
the appropriate file name, the user can switch between the open files.
Access Mode - (Opt2)

The access mode indicates how the file is used. Valid modes are R for
READ only, W for WRITE only, M for Mixed access (i.e., both READ
and WRITE), B for Buffer mode (i.e., shares View buffer), C for Control
mode (i.e., block read and write commands), and A to append to the end
of the file. Also, N can be specified in combination with any other access
mode to indicate that any previously opened files are not to be closed.
The value of this option can be upper-case or lower-case and must be
enclosed in quotation marks (e.g., "R", "WN", etc.). If the file is opened
for READ, it must already exist. This option is ignored on the USE
command (i.e., the access mode of an open file can not be changed). If
this option is omitted, READ is assumed.
In buffer mode, the HFS shares the buffer with the View device (i.e.,
device 63). It also assumes control mode so that only block READ and
WRITE commands are allowed. In control mode, you can use either of
the following WRITE commands:
W *4 = write buffer to current block location
W *6 = read block at current location into view buffer
An attempt to use block mode commands when the device is not opened
for block mode, results in a <MODER> error. A <NOPEN> error occurs
if you try to open the device in block mode without first opening the
View device. In other words, in buffer mode, the VIEW device must
already be owned by the job attempting to open the HFS device.

File Offset - (Opt3)
The file offset indicates the starting byte within the file where the HFS
is to be positioned. The value is relative to the location specified by
option 4. A signed value (i.e., -5) can be specified on the USE command
to move forward or backward from the current position in the file. The
value does not need to be within the physical bounds of the file. For
READ operations, a null is returned if the offset is not within the file.
For WRITE operations, the file is expanded to the offset using the ASCII
NULL character ($C(0)) as a filler. If this option is omitted, an offset
of 0 is assumed.
Block Number/Offset Type - (Opt4)

The block number/offset type is used to provide further positioning
information to the system. When the file is opened in block mode or
control mode, the file is treated as logically contiguous 1K blocks. Each
block is 1K in length and the first block is block 0. If this option is
omitted, block 0 is assumed.
In any other mode, this field specifies the type of offset used in option
3. Valid types are 0 to indicate offsets from the beginning of the file, 1
to indicate offsets from the current position in the file, and 2 to indicate
offsets from the end of the file. If this option is omitted, a value of 0 is
assumed.
Record Format - (Opt5)

The record format option is used to specify the method of recording the
data within a block. Valid record formats are S for stream mode and V
for variable length mode and must be enclosed in quotes (e.g., "S"). In
stream mode, the system uses the READ terminator character specified
by Opt6 below, to separate records. Whenever a WRITE ! is issued to
the device, the READ terminator character is inserted.
In variable length mode, the system prefixes each record with a four byte
ASCII character field that contains the length. For null records, the value
of the length field is four. If the length field is zero, it indicates an
end-of-file condition. If a file recorded in variable length format is
incorrectly positioned through the USE command, unpredictable results
may occur. If this option is omitted, stream format is assumed.

READ Terminator - (Opt6)
The READ terminator is used to specify the sequence of characters that
is used to separate records recorded in stream format. Whenever a
WRITE ! is issued to the device, this sequence is inserted. Whenever a
READ is issued and the sequence is encountered, an end-of-record
condition occurs.
A READ terminator sequence is from 1 to 3 characters in length and
may contain any ASCII character. If no READ terminator is desired,
specify this parameter as null(""). If this option is omitted, a READ
terminator of carriage return, line feed is assumed for MSM-PC,
MSM-PC/PLUS, and MSM-VX, or just line feed (i.e., $C(w)).

After each HFS input or output command, status information about the
results of the command are stored in the $ZA, $ZB, and $ZC Special
Variables. The routine that issued the command can interrogate these
variables and take different programming paths depending on their
contents. For the HFS device, the meaning of each variable is:
$ZA contains the number of bytes transferred to or from the

file. This can be used to test for an end-of-file
condition by comparing it to the number of bytes that
should have been transferred. If they differ, then the
end of file has been reached. If an error occurs on the
transfer, this field contains a -1. Also, immediately
after opening the HFS device to a file, $ZA contains
a -1 if the open failed (i.e., the file was not found or
access was denied). Otherwise, it contains a zero (0).
$ZB contains the current block number if the file was
opened in buffer or control mode. In any other mode,
this field contains the current byte offset into the file.
occurred.
to make the HFS device the current device.

3.10.3 Host File Server Device Examples
The following examples show how to access the Host File Server devices
via the OPEN, USE, and CLOSE commands.
Table 3-8 - Host File Server Device Examples

O 51:("A:\GLOBAL.SAV") Open file GLOBAL.SAV on drive
A in READ mode under MS-DOS.
O 51:("/msm/data":"R") Open file DATA in MSM directory

for read-only under Unix or Xenix.
O 51:("[SYS]DUMP":"B") Open file DUMP in SYS directory

and use VIEW buffer under VMS.
O 51:("TEXT":::::$C(127)) Open file TEXT in current directory

with read terminator of $C(127).
O 51:("CUSTOMER":"RN") Open file CUSTOMER and do not

close any previously open files.
U 51:(::2048) Position the file to byte 2048.
U 51:(:::3) WRITE *6 Read block 3 (the 4th 1K block

beginning with zero) from the
currently OPENed file and place the
data in the VIEW buffer.
U 52:(::2048) Position HFS device 52 to byte 2048

(the 2049th byte beginning with
zero) in the currently OPENed file.
U 51:("text":"w") Reopen with file text in current

directory for write only.

3.11 Interjob Communication
The Interjob Communication (IJC) facility of MSM allows two or more
jobs in execution to pass messages between them without going through
the disk. The transfer is accomplished using paired communications
devices. Each pair of devices includes a transmitter device and a receiver
device. The even- numbered devices are the receivers and odd-numbered
devices are the transmitters.
The Interjob Communication devices are assigned device designators
of 224 through 255. The commands which are valid for the Interjob
Communication devices are:
OPEN WRITE READ

CLOSE ZPRINT ZLOAD
USE ZWRITE
To use the Interjob Communication facility, a job opens and uses one
of the transmitters and then writes one or more messages. To receive
messages, a job opens and uses the corresponding receiver and reads
each message that has been sent. All transmissions are fully buffered
which means that the receiving job does not need to have the device
open at the time the sending job writes to the device.
Also, the sending job can continue putting information into the device
until the buffer becomes full. Once the buffer is full, execution of the
sending job is suspended until information is removed from the buffer
by the receiving job. Similarly, the receiving job can retrieve information
from the buffer after the sending job has CLOSEd the transmitter. This
allows multiple jobs to send messages to a single job by opening the
device, sending a message, and then closing the device.
Care should be taken when using the Interjob Communication device
since there is no way to predict the order in which multiple jobs execute.
If a job reads from an Interjob Communication device and never receives
a message, it waits indefinitely unless a timeout value is specified on
the READ.

Unlike other devices, whenever a WRITE command with multiple
operands is issued to an Interjob Communication device, each operand
is a separate record in the buffer. This means that the receiving job must
issue a READ command for each record in the buffer. Fixed length
reads are not supported for this device.
It is possible to generate errors through incorrect use of the Interjob
Communication devices. For example, if a READ command is issued
to a transmitter, then the system will generate a <NODEV> error.
Similarly, if a WRITE command is issued to a receiver, then the system
generates an error.

The MSM system includes a total of sixteen (16) Interjob
Communication devices. They are grouped in pairs with the Receivers
having even device numbers and the Transmitters having odd device
numbers. These devices are assigned device numbers 224 through 255.
The format of the OPEN, USE, and CLOSE commands is:
OPEN{:Cond} Dev{::Time}
USE{:Cond} Dev
CLOSE{:Cond} Dev
available. If Time is specified, then after the command completes, the
$TEST Special Variable contains 1 if the OPEN was successful,
otherwise it contains a 0. $TEST remains unchanged if a timeout value
is not specified.

After each Interjob Communication input or output command, status
information about the results of the command is stored in the $ZA, $ZB,
and $ZC special variables. The routine that issued the input or output
command can interrogate these variables and take different
programming paths depending on their contents. For the Interjob
Communication devices, the meaning of each variable is:
$ZA contains the number of bytes remaining in the device
buffer. If the buffer is empty, the $ZA Special Variable
contains a value of zero (0).
$ZB contains the number of bytes that have been used in
the buffer.
$ZC contains a value of 0 (zero) if the operation completed
normally or a value of 1 if a device error occurred.
The size of the Interjob Communication buffer is 256 bytes. Therefore,
after an input or output operation, $ZA + $ZB equals 256. However, if
the buffer is empty, then both $ZA and $ZB are 0 (zero). Also, it is
important to remember that the values of $ZA, $ZB, and $ZC are always
returned for the current device. A USE command must be issued to
make the Interjob Communication device the current device.

3.11.3 Interjob Communication Device Examples
The following examples show how to access the Interjob
Communication devices via the OPEN, USE, and CLOSE commands.
Table 3-9 - Interjob Communication Device Examples

O 224::60 Open an IJC Receiver and wait up
to 60 seconds for it to become
available.
U 225 Make an IJC Transmitter the current

device.
O 224,225 Open the Receiver and the

Transmitter of an IJC device.

3.12 Routine Interlocks
The MSM system includes a series of logical devices that can be used
to synchronize functions between routines while they are executing.
These devices are assigned device numbers 20 to 46 and 200 to 223.
The only valid commands that can be issued to these devices are OPEN
and CLOSE. The format of the OPEN and CLOSE commands is:
OPEN{:Cond} Dev{::Time}
CLOSE{:Cond} Dev
then the command is not excuted.
available. If Time is specified, then after the command completes, the
$TEST Special Variable contains 1 if the OPEN was successful;
otherwise, it contains a 0. $TEST remains unchanged if a timeout value
is not specified.
The function associated with these devices is left up to the application
program that uses them. Use of these devices has no defined meaning
in the MSM system. Usually an application uses these devices in place
of the LOCK command to synchronize events.
The following examples show how to access the Routine Interlock

devices via the OPEN and CLOSE commands.
Table 3-10 - Routine Interlock Device Examples
OPEN/CLOSE Command Description

O 20::60 Open a Routine Interlock device and
wait up to 60 seconds for it to
become available.
C 20 Close a Routine Interlock device.

3.13 Magnetic Tape
The Magnetic Tape driver allows the user to access a magnetic tape
device in sequential mode or random access mode. It is designed for
use with industry standard nine-track tape drives. Certain types of
cartridge tape drives are supported, although not all of the tape modes
and commands are available for these devices. The system can support
up to four magnetic tape devices. These devices can be used to create
files that are transferred to other systems, to read files created by another
system, as a temporary storage device, to backup the MSM database, or
as a journaling device.
The system transfers information to and from these devices in physical
blocks and automatically deblocks the information into logical records
if appropriate. Note that for cartridge tape devices, the physical block
size must be a multiple of 512K. The system automatically blocks and
unblocks data for the user. It also allows the user to access the tape in
buffer mode, which bypasses the blocking and unblocking operations.
The tape devices are assigned device designators of 47 through 50. None,
one, or more tape devices may be present on the system. The commands
which are valid for the Magnetic Tape devices are:
OPEN WRITE READ

CLOSE ZPRINT ZLOAD
USE ZWRITE
To access a Magnetic Tape device, OPEN the device and specify any
appropriate parameters such as Access Mode, logical record size, or
physical block size. All READ and WRITE accesses to the device are
in sequential order unless the device is repositioned with a WRITE
*Code command (where Code is a positioning command). That is, the
next input or output operation begins at the byte immediately following
the last byte of the previous input or output operation.
When accessing the Magnetic Tape device, input and output operations
cannot be intermixed. The first READ or WRITE operation sets the
mode. Once it is set, it cannot be changed except by repositioning the
tape or closing and re-opening the tape. When the Magnetic Tape device
is CLOSEd, any unwritten data is written to the tape and then a tape
mark (i.e., an end-of-file indicator) is written.

When the Magnetic Tape device is opened, and when input or output is
directed to the device with the USE command, additional information
can be specified to the system. This information is used to set the device
Access Mode, the logical record size, and the physical block size. The
format of the OPEN, USE, and CLOSE commands is:
OPEN{:Cond} Dev{:(Opt1:Opt2:Opt3:Opt4:Opt5)}{:Time}
USE{:Cond} Dev{:(Opt1:Opt2:Opt3:Opt4:Opt5)}
CLOSE{:Cond} Dev

The time operand on the OPEN command indicates the amount of time
to wait for the specified device to become available. Upon completion
of the OPEN command, the $TEST Special Variable contains a 1 if the
open was successful, otherwise, it contains a 0. $TEST remains
unchanged if a timeout value is not specified. The remaining options
are defined below.
Access Mode - (Opt1)

The access mode indicates to the system the method that should be used
to process the tape. The access modes are single character identifiers
that specify characteristics about the format of the physical data, the
character set used to record the data, type of tape labels, recording
density, and allowable I/O operations. The following is a list of the valid
access modes that can be specified by the user along with a description
of each of the modes.

Table 3-11 - Magnetic Tape Access Modes
Mode Description
A ASCII Character Set - The ASCII character set is used for
all input and output operations.
B Buffer Mode - In this mode, all tape transfers are done

using the VIEW buffer. When this mode is specified, all
other access modes except T, C, 3, 4, and 5 are ignored and
only WRITE * type commands are allowed.
C Continuous Mode - In this mode, all tape transfers are done

asynchronously (i.e., the user does not wait for the
operation to complete) using double buffering.
E EBCDIC Character Set - The EBCDIC character set is used

for all input and output operations. On output, ASCII
characters are translated to EBCDIC and on input,
EBCDIC characters are translated to ASCII.
F Fixed Length Records - All input operations assume a fixed

length for the data and all output operations are done in
stream mode. When this mode is specified, the Opt2
parameter (logical record length) must be specified and the
Opt3 parameter (physical block size) may be specified.
L Standard Labels - The system processes standard labels for

the tape. In ASCII mode, it processes ANSI labels and in
EBCDIC mode, it processes IBM labels. When accessing
cartridge tapes in a UNIX operating environment, label
processing is not supported.
N Null Data - This indicates to the system that the null

character (X’00’) may appear as part of the data in stream
mode. If this mode is not specified, a null character
indicates the end of a block and processing continues with
the next block.

Mode Description
R READ Only - This option is used to indicate to the system
that only input type commands are allowed for the tape. If
an output command is attempted, the system generates a
<MODER> error. If this option is omitted, the system
assumes that both READ and WRITE operations are
allowed.
S Stream Format - In stream mode, on output the system

automatically blocks information into the buffer up to the
specified size of the buffer (i.e., Opt3 parameter). If
necessary, the system splits the logical record across a
block boundary. If the complete record does not fit in the
buffer, the system stores as much of the record as possible
in the current block and the remainder of the record in the
next block.
T Inhibit Tape Mark Errors - Normally, MSM generates an

error condition (i.e., <MTERR>) when a tape mark is
encountered. This can be suppressed by including this code
in the OPEN command, and $ZA can then be interrogated
to determine if an error occurred.
U Unlabeled - This indicates that label processing is not to

be performed by the system.
V Variable Length Records - When this format is specified,

the ANSI variable format is used when the character set is
ASCII, and the IBM variable length format is used when
the EBCDIC character set is used. Each operand on a
WRITE command is treated as a separate logical record.
3 800 BPI - This indicates that the tape drive is to be accessed

at 800 bits per inch. This access mode is ignored for
Cartridge Tape devices.

Mode Description
4 1600 BPI - This indicates that the tape drive is to be
accessed at 1600 bits per inch. This access mode is ignored
for Cartridge Tape devices.
5 6250 BPI - This indicates that the tape drive is to be

accessed at 6250 bits per inch. This access mode is ignored
for Cartridge Tape devices.
The value of this option can be any combination of characters enclosed

in quotation marks (i.e., "ASU"), and upper-case or lower-case
characters may be used. This option is ignored on the USE command
since the access mode can only be set when the device is first opened.
To change the access mode, the device must be CLOSEd and then opened
with the new values. If this option is omitted, a value of "ASU" is
assumed by MSM.
Logical Record Length - (Opt2)

The logical record length parameter allows the user to specify the fixed
size of each record that is read from or written to the tape device. If the
access mode is not F (i.e., fixed length records), then this option must
not be specified or must be zero if it is specified. Fixed length records
may have a length of 1 to 32760 characters.
Physical Block Size - (Opt3)

The physical block size parameter allows the user to specify the actual
size of each physical block that is read from or written to the tape device.
The physical block size may be from 14 to 32767 characters in length.
For cartridge tape devices, this value must be a multiple of 512K. When
using fixed length records, the block size must be a multiple of the record
length.
Delimiter String - (Opt4)

The delimiter string is used to separate logical records on the Magnetic
Tape device in stream mode. The user can specify a string of from 1 to
3 ASCII characters (e.g., $C(13,10)) as the delimiter. If this option is
specified, it is the only string that is recognized as the delimiter.

If this option is not specified, then all Carriage Returns ($C(13)) are
ignored and Line Feeds ($C(10)), Vertical Tabs ($C(11)), and Form
Feeds ($C(12)) will terminate a READ operation. If this option is
specified with a null value, then there is no delimiter and fixed length
READs must be used (e.g., READ X#100) to process the data.
Care should be taken when selecting a delimiter character other than the
default character. If the specified delimiter character appears normally
as part of the data, then unexpected results occur when the data is read
from the Magnetic Tape device.
Buffer Offset - (Opt5)

This option indicates the location within the buffer where the next READ
or WRITE operation is to occur. This option is only valid when the tape
device is opened in buffer mode. The value of this option can be from
0 up to the size of the VIEW buffer.
3.13.2 WRITE Commands

A special series of WRITE commands can be used to control tape
processing. This includes tape motion, reading and writing labels, and
determining tape status. These commands are issued using the WRITE
*Code notation of MSM where Code is the action to be performed.
Some commands can only be used in Shared Buffer mode where the
tape device shares the buffer with the View device (i.e., device 63). In
this mode, only block type READ and WRITE operations are allowed.
The block type operations are issued in the same manner as described
above using the WRITE *Code commands where Code is the action to
be performed.
The following table defines all of the *Code commands that can be used
for Magnetic Tape from within MSM. Except for those commands that
are specifically identified as block mode-only commands, all of the
commands can be used regardless of the tape mode that was specified
when the device was OPENed.

Table 3-12 - Magnetic Tape Write Commands
Code Description of Action

1 Backspace - The tape is backspaced one physical block and
the READ/WRITE switch is reset.
2 Forward Space - The tape is forward-spaced one physical

block and the READ/WRITE switch is reset. When the
tape is positioned at the beginning, the tape label, if present,
is skipped before the forward space.
3 Write Tape Mark - This writes a tape mark after flushing

the buffer if the last operation was an output operation.
4 Write Block - If the tape is at the beginning and label

processing is enabled, the label is written before the block
is written; otherwise, the block is just written. This
operation is valid only if the device was opened in buffer
mode.
5 Rewind Tape - If the last operation was a write, then the

system performs an implicit WRITE *9 operation before
rewinding the tape.
6 Read Block - If the tape is at the beginning and label

processing is enabled, the label is read first, and then the
block is read. This operation is valid only if the device was
opened in buffer mode.
7 Read Label - If the tape is positioned at a label, the label

is read; otherwise, the next block is read. Label processing
is not supported for cartridge tape devices in MSM-UNIX.
8 Write Header Labels - If the tape was opened with label

processing enabled, this operation writes out the ANSI or
EBCDIC label. For EBCDIC labels, if the tape is
positioned at the beginning, the system also writes out a
volume label. If label processing is not enabled, this
operation is ignored. Label processing is not supported for
cartridge tape devices in MSM-UNIX.

Code Description of Action
9 Write EOF Label - If label processing is enabled, the system
writes out the ASCII or EBCDIC end-of-file label as
appropriate. If label processing is not enabled, this
operation is ignored.
10 Tape Status - This updates the contents of the $ZA Special

Variable with the actual tape status, and should be used
after a successful operation before examining the status
flags.
11 Backward Space - The tape is backward-spaced to the last

tape mark, and the READ/WRITE switch is reset.
12 Forward Space - The tape is forward-spaced to the next

tape mark, and the READ/WRITE switch is reset.
13 Erase Tape - The tape is erased and the READ/WRITE

switch is reset. This operation is valid only for Cartridge
Tape devices; it is ignored for other types of tape devices.
14 Retension Tape - The tape is retensioned and the

READ/WRITE switch is reset. This operation is valid only
for Cartridge Tape devices; it is ignored for other types of
tape devices.
15 Forward Space - The tape is forward-spaced to the end of

the last data written on the tape (i.e., tape marks are
skipped), and the READ/WRITE switch is reset (Cartridge
Tape Devices only).
16 Rewind and Unload Tape - If the last operation was a write,

then the system performs an implicit WRITE *9 operation
before rewinding the tape. After the tape has completed
the rewind operation, it is unloaded from the device.
Any attempt to issue a block mode Read command (i.e., *6) or Write
command (i.e., *4) when the device was not opened for buffer mode,
results in a <MODER> error. A <VWERR> error occurs if you attempt
to open the device in block mode without first opening the View device.

Normally, when a tape error occurs, the system updates the status
information contained in the $ZA Special Variable and continues
processing. However, if the $ZTRAP Special Variable is set to an error
trapping routine, then MSM takes the trap with $ZERROR set to
<MTERR>. Errors that occur when a tape mark is encountered can be
suppressed by opening the device with the T option. This can be specified
in conjunction with the other options (e.g., ASUT).

After each Magnetic Tape input or output command, status information
about the results of the command is stored in the $ZA, $ZB, and $ZC
Special Variables. The routine that issued the input or output command
can interrogate these variables and take different programming paths
depending on their contents. For the Magnetic Tape device, the meaning
of each variable is:
$ZA contains the status information about the last operation

to the device. It is updated when the device is opened,
when an error occurs, or on a successful operation
when the previous operation had an error. It is a 2 byte
number (i.e., 16 bits where the bits from left-to-right
are 15, 14, ... 1, 0). The bits are defined as follows:
0 Beginning of tape (not valid for cartridge tape)
1 End of tape (physical)
2 End of recorded data
3 Tape positioning in progress
4 Tape unit is on-line
5 Tape unit is ready
6 Tape media has been changed
7 Tape mark detected
8 Logical tape error
9 Block length error
10 Tape media error
11 Tape is write-protected
12 Bus error
13 Data overrun
14 Hardware error
15 Reserved for future use

$ZB contains a value that indicates the number of physical
bytes transferred on the last READ or WRITE
operation. This usually is the same as the block size
specified by Opt3 on the OPEN command, although
MSM processes short blocks correctly.
-1 if end-of-file (tape mark) was reached, or 1 if a
device error occurred.
The status conditions associated with bits 0 through 6 of $ZA do not
cause an error condition when they are set, and the error trap (i.e.,
$ZTRAP) is not invoked. The error conditions associated with bits 7
through 15 of $ZA do cause the error trap to be invoked. If the tape is
opened with an access mode of T (i.e., Tape Mark Inhibit), then the error
condition associated with bit 7 of $ZA does not cause the error trap to
be invoked.
It is important to remember that the values of $ZA $ZB, and $ZC are
to make the Tape device the current device.

3.13.4 Magnetic Tape Device Examples
The following examples show how to access the Magnetic Tape devices
via the OPEN, USE, and CLOSE commands.
Table 3-13 - Magnetic Tape Device Examples

O 47:("ASU4"):60 OPEN Magnetic Tape device in
ASCII, Stream format, unlabeled, at
1600BPI and wait up to 60 seconds
for the device to become available.
O 47:("EFL5":80:4000) OPEN Magnetic Tape device in

EBCDIC format, fixed block
format, IBM standard labels, 6250
BPI, with 80 byte logical records
and 4000 byte physical blocks.
O 47:("B") OPEN Magnetic Tape device in

Buffer mode. All operations to tape
will be done from the VIEW buffer.
U 47:(:::$C(127)) Change stream delimiter to the DEL

character.
U 47:(::::980) Position the Magnetic Tape device

to location 980 of the VIEW buffer.
U 47:("T") Inhibit tape mark errors on the

Magnetic Tape device.

3.14 Spool Device
The Spool device provides a mechanism whereby contention for physical
printer devices within the system can be avoided. The Spool device
allows concurrent users to create multiple print files that are stored
separately in a designated spool area within the MSM database. A
system-supplied de-spool utility can be used to retrieve the individual
files and route them to the appropriate output device.
When a spool file is created, MSM automatically assigns it a unique file
number. The file number, which can have a value of 1 through 252, is
used to identify which file is to be accessed since a user may have
multiple spool files open at the same time. On MSM-PC and
MSM-PC/PLUS systems, there can be 16 open files and on MSM-UNIX
and MSM-VX systems, there can be 128 open files. The assigned file
number is returned to the user upon successful completion of the OPEN
command.
When output is created by a program, it is usually destined for a particular
printer device or print form. It is desirable to group together all print
files that must be printed on the same device or the same form so that
they can be printed at the same time. To accommodate this, the MSM
system allows the user to specify a destination code that is associated
with the print file. The destination code, which has a value of 1 through
255, can be a symbolic device (e.g., 3 for printer 3) or an arbitrary
designation associated with a form (e.g., 242 for 2-part lined paper).
Files can then be retrieved as a group, and within the group, they can be
accessed sequentially by file number.
The MSM system includes a spool maintenance utility (i.e., the SPL
Utility) that allows the system manager to control various spooling
functions. This utility allows the manager to create a spool area within
the MSM database, initialize the spool area, delete the spool area, display
the spool area, enable or disable spooling, start or stop the despooler,
delete spool files, and assign an alternate Spool device. Refer to the
MSM Utility Manual for additional information.
Also included with the system is a generalized de-spooling utility (i.e.,
the DESPOOL Utility) that can be used in most installations without
modification. Or, it can be used as a model to create a site-specific
de-spooling utility that is tailored to meet the user’s unique requirements.

The primary Spool device is always assigned the device designator of
2. However, through use of the SPL utility, one additional device
designator may be specified as an alternate Spool device. The specified
device must be a valid terminal device. The alternate Spool device
functions exactly like device 2; however, OPEN, USE, and CLOSE
parameters are ignored for this device. Both the primary and the alternate
Spool device may be owned by more than one job concurrently. The
following commands are valid for the Spool device:
OPEN WRITE READ

CLOSE ZPRINT ZLOAD
USE ZWRITE
To access a Spooling device, OPEN the device and specify any

appropriate parameters such as Destination Code or File Number. When
the alternate Spool device is opened, a destination code equal to the
device number is automatically assigned. When accessing the Spool
device, input and output operations may not be intermixed.
The USE command can be used to switch between destination codes

and files within the spool area, and the CLOSE command can be used
to delete files from the spool. When the file is CLOSEd, any unwritten
data is written to the spool area as part of the CLOSE operation. When
the file is re-opened, it is in read-only mode (i.e., no new data may be
written to it).

When the Spool device is opened, or input or output is directed to the
device with the USE command, additional information can be specified
to the system. This information indicates the Destination Code and the
File Number to be processed. The format of the OPEN, USE, and
CLOSE commands is:
OPEN{:Cond} Dev{:Opt1}{:Time}
USE{:Cond} Dev{:Opt1}

The Time operand on the OPEN command indicates the amount of time
to wait for the specified device to become available. Upon completion
of the OPEN command, the $TEST Special Variable contains a 1 if the
open was successful, otherwise, it contains a 0. $TEST remains
unchanged if a timeout value is not specified. The remaining options
are defined below.
File Designator - (Opt1)

The File Designator indicates to the system what Destination Number
and File Number are to be accessed. The File Designator is specified
as a single numeric value between 0 and 768, or a null value can be
specified. For OPEN commands, the value of this option can be in any
one of the following forms:
null A null value indicates that the default

destination code is to be used. The default
destination code is equal to the default
despooling device, if defined. If there is
no default despooling device, or if this
parameter is omitted, a destination code of
0 is used.
DestNum A destination number from 1 through 255

that specifies the group with which the file
is to be included. The group may or may
not already exist.
256+FileNum This form opens the file number specified
by FileNum independent of the destination
code that was used to create the file. This
form cannot be used when creating a spool
file. If the specified file does not exist,
then an error is indicated in the $ZA
Special Variable.

512+DestNum This form opens the first file that exists
within the group of files whose destination
code is specified by DestNum. This form
cannot be used when creating a spool file.
If no files exist within the specified
destination code, then an error is indicated
in the $ZA Special Variable.
512 This form opens the first file in the spool
space regardless of the destination code
associated with the file. $ZA indicates the
status of the open.
For USE commands, the value of this option can only be in the following
form:
FileNum This form is used to make the specified file
the current file on the Spool device. This
is used when a job has more than one spool
file opened at a time. When switching
between devices, this parameter can be
omitted if only one spool file has been
opened. The value of FileNum must be
between 1 and 255 inclusive.
For CLOSE commands, the value of this option can be in any one of the
following forms:
null This form CLOSEs the spool file that is

associated with the current Spool device.
Care should be taken when this form is
used, and more than one spool file is open
to insure that the proper file is CLOSEd.
FileNum The file specified by FileNum is CLOSEd

but not deleted (i.e., it can be re-opened).
256+FileNum The file specified by FileNum is CLOSEd

and it is deleted (i.e., it cannot be
re-opened).
256 The current spool file is CLOSEd and it is
deleted (i.e., it cannot be re-opened).

After each Spool device input or output command, status information
about the results of the command is stored in the $ZA and $ZB Special
Variables. The routine that issued the input or output command can
interrogate these variables and take different programming paths
depending on their contents. For the Spool device, the meaning of each
variable is:
$ZA contains the destination number and file number of the
current spool file. This composite number has a format
of DestNum*256+FileNum if the last operation (i.e.,
OPEN, READ, or WRITE) was successful. If the last
operation was not successful, $ZA contains an error
indicator. The error indicator is one of the following:
-1 An end-of-file has occurred on the operation.
-2 No spool file exists.
-3 On OPEN, the internal file table was full and
the new spool file could not be added.
-4 Spool file structure contains errors and should
be re-initialized.
-5 The spool space is full and the record could
not be added.
-6 Spooling is not active.
When interrogating $ZA, the file number can be

distinguished from error codes since the error codes
are always negative values.
$ZB contains the number of the physical disk block being

processed by the Spool device. It is updated each time
a new block is accessed.
occurred.
always returned for the current device. However, after an OPEN
command, $ZA is set even though a USE is not issued.

3.14.3 Spool Device Examples
Assume that a spool area has already been defined within the MSM
database and that an alternate Spool device of 3 has been defined. The
following examples show how various files can then be accessed with
the Spool device.
Table 3-14 - Spool Device Command Examples

OPEN 2 S FN=$ZA Create a spool file and retrieve file
number in $ZA Special Variable.
OPEN 3:80 Open the alternate Spool device; the

right margin of 80 is ignored.
OPEN 2:20 Open a spool file with an output

destination code of 20.
OPEN 2:260 Open spool file number 4 (i.e.,

256+4=260) for input.
OPEN 2:512 Open the next available spool file,

regardless of destination, for input.
OPEN 2:532 Open the next available spool file with a

destination code of 20 for input.
USE 2:FN Set the current spool file being used to

the file number contained in FN.
CLOSE 2 Close the current spool file but do not

delete it from the spool area.
CLOSE 2:256 Close the current spool file and delete it

from the spool area.

3.15 Host System Spool Device
The Host System Spool device provides a mechanism whereby
contention for physical printers managed by the Host Operating System
(i.e., Unix, Xenix, or VMS) can be avoided. The Spool device allows
concurrent users to create multiple print files that are stored separately
by the Host Operating System using its standard print spooler.
Actual printing of the data is managed by the print spooling feature
provided by the Host Operating System. In Unix and Xenix, this is done
through the lp spooling facility. In VMS, this is done through the PRINT
spooling facility. This feature is not available under the MSM-PC and
MSM-PC/PLUS systems.
The primary Host System Spool device is always assigned the device
designator 55. Device 55 can be owned by more than one job
concurrently. The commands which are valid for the Spool device are:
OPEN USE WRITE

CLOSE ZPRINT ZWRITE
To access the Host System Spool device, OPEN the device and specify
any appropriate parameters for the print spooler within the Host
Operating System. When accessing the Spool device, only output
operations are permitted. When a new spool file is opened, data may be
written to the file until it is CLOSEd. When the file is CLOSEd, any
unwritten data will be written to the spool area as part of the CLOSE
operation.

When the Host System Spool device is opened, or output is directed to
the device with the USE command, additional information can be
specified to the system. This information supplied is specific to the type
of Host Operating System spooling facility being used. The format of
the OPEN, USE, and CLOSE commands is:
OPEN{:Cond} Dev{:Opt1}{:Time}
USE{:Cond} Dev

The Time operand on the OPEN command indicates the amount of time,
in seconds, to wait for the specified device to become available. Upon
completion of the OPEN command, the $TEST Special Variable will
contain a 1 if the open was successful, otherwise, it will contain a 0. If
no timeout value is specified, the value of $TEST remains unchanged.
The remaining options are defined below.
Spooler Parameters - (Opt1)

The Spooler Parameters option is a string of text that will be passed to
the Host Operating System spooler as part of the invocation command
(i.e., lp parameters in Unix and Xenix and PRINT parameters in VMS).
The text string is passed to the Host Operating system exactly as supplied
on the OPEN or CLOSE command. No editing or syntax checking is
performed by the MSM system.
The actual parameters supported by the spooler are specific to the Host
Operating System implementation being used. Consult the appropriate
Unix, Xenix, or VMS documentation for additional information on the
parameters that are supported. Note that these parameters are likely to
be different between different implementations of Unix and Xenix. Also,
they may change from release to release of Unix, Xenix, and VMS.

After each Host System Spool Device command, status information
about the results are stored in the $ZA, $ZB, and $ZC Special Variables.
The routine that issued the command can interrogate these variables and
take different actions depending upon their contents. For the Host
System Spool device, the meaning of the each variable is:
$ZA After an OPEN command, $ZA contains a value of
zero if the open was successful. Otherwise, it contains
a minus one (-1) to indicate that the open failed. The
open can fail if spooling is not active within the Host
Operating System or if there are no internal Host
System Spool devices available. The maximum
number of Host System Spool devices that may be
opened concurrently is configured through the
SYSGEN utility.
After a USE command, $ZA always contains a zero.
Finally, after a CLOSE command, $ZA contains the
spool file number that was assigned by the Host
Operating System.
$ZB always contains a zero. The $ZB Special Variable is

not used for Host System Spool device.

1 if an error occurred.
always returned for the current device. However, after an OPEN
command, $ZA is set even though a USE is not issued. $ZA must be
interrogated before any subsequent USE, since a USE command will
cause $ZA to come from the USEd device.

3.15.3 Host System Spool Device Examples
The following examples show how to access the Host System Spooling
device via the OPEN, USE, and CLOSE commands.
Table 3-15 - Host System Spool Device Examples

O 55:("-dlp1") Instructs the Unix spooler to
print on queue lp1 instead of
the default print queue.
O 55("-n2") Instructs the Unix spooler to

print 2 copies of the file
being transmitted.
O 55:(:"-tLIST -n3") Instructs the Unix spooler to

print a separator page with a
title of LIST and 3 copies of
the file.
O 55:("-c") Instructs the Unix spooler to

make a copy of the file being
printed.
O 55:("/QUEUE=SYS$PRINT2") Instructs the VMS spooler to

print on the SYS$PRINT2
queue instead of the default
system print queue.
O 55:("/COPIES=2/HEADER") Instructs the VMS spooler to

print two copies of the file
with a header page.
O 55:("/NAME=LIST/COPIES=3") Instructs the VMS spooler to

print three copies of the file
with a job name of LIST.
O 55:("/SPACE") Instructs the VMS spooler to

print the file double spaced.

CHAPTER 4
MSM UTILITY PROGRAMS
This chapter describes the standard set of utility programs that is supplied
with the MSM system, conventions supported by the utilities, and
instructions for accessing them.
4.1 Using the MSM Utility Programs

All of the utility programs supplied with the MSM system are stored in
the manager’s UCI (i.e., the first UCI in the system). In general, these
programs fall into two classes: Library routines that are accessible by
all users of the system from any UCI, and System Manager routines that
are only accessible from the manager’s UCI. Routines that can be
accessed from all UCIs begin with a percent sign (%).
These routines facilitate program development and system maintenance

by performing the most common tasks associated with these functions.
To provide consistency and to make them easier to use, all of the utility
routines follow a standard set of conventions. The following conventions
apply to all of the utility routines that are stored in the manager’s UCI.
1. In response to any prompt issued by a utility program, a
question mark (?) can be entered to obtain additional
information about the required response.
2. In response to any prompt, a circumflex (^) can be entered
to go back to the previous question. If the system is
prompting for data where the value can be any of the ASCII
characters, then the ^ is treated as data.
3. Many of the utility programs supply a menu of options that
consists of a number followed by an option. To select an
option, enter the number of the option or enough characters
of the option name to distinguish it from all other options
that are listed. A question mark followed by the option
number (e.g., ?3) can be entered to obtain additional help
information about a specific option.
MSM Utility Programs 4-1

4. If a default value exists for the prompt, it is displayed in
angle brackets (i.e., <value>). If a RET is entered, the
default value is used. To enter a null response when a default
value is present, enter a minus sign (-).
5. All responses to prompts are terminated with the RET key

unless otherwise indicated by the prompt.
6. Whenever a numeric value is requested by a utility, the
response is to be given in decimal.
7. Whenever the utility prompts you to select an item from a

predefined list of items, you can enter a circumflex followed
by the letter L (e.g., ^L) to obtain a list of the items.
8. Execution of a utility program can be interrupted by entering
a CTRL/C at any time. The routine displays ’...Aborted’
and terminates execution.
The utility routines can be invoked in either of two ways. First, when
logged onto the system in programmer mode, use the DO command to
initiate execution of the utility. When the utility completes, the system
returns to programmer mode. In the other case, logon to the system in
run mode and specify the name of the utility to be executed as part of
the logon sequence. The following example shows how to invoke the
%GD utility in the system manager’s UCI in run mode.
MSM, Version 4.0 Line#1 UCI: MGR:%GD
When the utility completes, the job is automatically logged off the
system.
4-2 MSM Utility Programs

4.2 The %HELP Utility
A general purpose HELP facility is supplied with MSM to provide
assistance in using the utility programs. This routine provides
instructions for using each utility program supplied with the system. To
invoke the HELP facility, enter the following command from any UCI:
DO ^%HELP
The system responds with the following prompt:

Enter Routine Name:
In response to this prompt, enter the name of the routine for which you
want help information, ^L to obtain a list of all routine names, or a
question mark (?) to access information about the %HELP utility itself.
This routine also allows you to print a hardcopy listing of the help
information for each routine. When you specify that you want a list, the
system prompts you for an output device. Enter a device number, or
enter a null response to direct the report to your terminal.
4.3 Library Utilities

The Library utilities assist in developing application programs by
performing functions commonly required by the programmer. These
routines begin with a percent sign (i.e., %) and can be accessed from
any UCI. These routines provide services in the areas of date and time
conversion, communications, development and maintenance of
programs, global files, system status, job execution, and arithmetic
functions.
4.4 System Manager Utilities

Use of the System Manager utilities is intended for those individuals
responsible for ensuring correct operation of the system. Information
on how to use these utility programs can be obtained by invoking the
%HELP utility while logged onto the manager’s UCI. Information about
the System Manager utilities is not available from any other UCI.
Routines contained in the manager’s UCI which are not documented in
the %HELP utility are subroutines called by other utilities and should
not be directly executed. You should have a thorough understanding of
the MSM system before using any of these routines. If you modify any
of the System Manager utilities, you should exercise extreme care in
testing them before actually using them on the system.

4.5 Common Utility Routines
Three common utility routines are used as sub-routines to many of the
MSM utility programs. These routines provide a general selection
mechanism for globals (i.e., %GSEL), for routines (i.e., %RSEL), and
for input/output devices (i.e., %SDEV). These routines are fully
described in the MSM Utility Manual and should be reviewed completely
before using the other utilities. Because it is assumed that you have
familiarized yourself with sub-routine functions prior to incorporating
a routine into a utility, no further explanation is provided in the following
description.
4.6 Utility Routines Supplied with MSM

Table 4-1 below lists the Library utility routines that are supplied with
MSM and a brief description of the function each performs. The table
lists the System Manager utilities supplied with the system. Where
appropriate, the intended use of the program is also included.
Table 4-1 - Library Utility Routines
Routine Description
Name
%ACTJOB Returns a string containing the job numbers,
separated by circumflexes (^), of all jobs that are
currently executing on the system.
%CHKSUM Computes a checksum (i.e., ASCII summation)

of one or more routines.
%D Displays the date contained in $HOROLOG on

the current device in the form DD-MMM-YY
where DD is the day of the month, MMM is the
three character abbreviation for the month, and
YY is the year. An internal entry point is provided
to return the date in a local variable.
%DEBUG Invokes the interactive program debugging

facility.

Routine Description
Name
%DEVUSE Displays a list of all OPENed devices and the
number of the job that owns each one.
%DH Converts a decimal value to hexadecimal.
%DI Converts a date from external form (e.g.,

8-SEP-83) to internal $HOROLOG format.
%DO Converts a date from internal $HOROLOG

format to external format.
%ECHO Allows the program to control the ECHOing of

characters at the terminal. Entry points are
provided to turn ECHO on and off.
%ER Allows the user to display the error code and

values of local symbols for errors that have been
trapped using the %ET routine.
%ERRCODE Provides an explanation of MSM error codes.
%ET Records the $ZERROR Special Variable and

contents of the local symbol table in the
ÛTILITY("%ER") global in the user’s UCI.
%FGR Restores the low-level data blocks and rebuilds

the pointer blocks for one or more globals stored
on an external device.
%FGS Saves the low-level data blocks for one or more

globals to an external device.
%FL Displays the first line of one or more routines

stored on disk in the current UCI.
%FLIST Lists a file stored in the MS-DOS, Unix, Xenix,

or VMS file system.

Routine Description
Name
%G Lists all or selected portions of a global file.
Supports specification of partial subscript values,
subscript ranges, and variables as subscripts.
%GCH Allows the user to change the attributes of a

global. This includes collating sequence (numeric
or string), protection values (Read, Write, and
Delete), whether or not the global is to be
journaled, and growth values.
%GCHANGE Changes all occurrences of a string in one or more

globals. The user is able to verify the changes
before they are made.
%GCOPY Copies one or more globals from one UCI to

another. The UCI may be on the same or on a
different volume group.
%GD Lists the contents of the global directory for the

current UCI.
%GDE Provides an extended list of global directories for

the current UCI.
%GDEL Deletes one or more globals from a UCI.
%GE Displays the amount and percentage of space used

for one or more globals.
%GEDIT Allows the user to edit all or selected portions of

a global file. Supports specification of partial
subscript values and ranges.
%GL Lists all or selected portions of a global file.

Supports specification of partial subscript values
and ranges.

Routine Description
Name
%GR Restores all or selected globals from an external
device and, as an option, allows them to be
renamed.
%GS Saves all or selected portions of one or more

global files on external storage.
%GSE Searches one or more globals for one or more user-

specified strings. A match occurs if a global
contains any of the user-specified strings.
%GSEL Allows the user to select one or more globals from

the current UCI. Full selection criteria can be
specified, such as ranges or all globals beginning
with certain characters.
%GSIZE Displays the size of a global variable.
%GUCI Returns the three character name and internal UCI

number for the current UCI.
%HD Converts a hexadecimal number to decimal.
%HELP Provides HELP information about the library of

MSM utility programs.
%HL Allows the user to change the priority of a job

from high to low or from low to high.
%HOSTCMD Allows the user to make background and

foreground calls directly to Unix, Xenix, or VMS
from within a MUMPS program (MSM-UNIX
and MSM-VX only).
%INDEX Provides a cross-reference listing of one or more

routines and optionally, provides a structured
program listing of selected routines.

Routine Description
Name
%INDSTR Produces a structured program listing of one or
more routines.
%LOGON Allows the user to change from one UCI to

another.
%MDMP Provides a display in hexadecimal format,

character format, or both for selected memory
locations or for the VIEW buffer.
%MFUNC Performs mathematical functions, including E,

PI, SIN, COS, etc.
%MODESET Allows the user to change environmental mode

flags such as global data lengths up to 511
characters or length of routine lines.
%MOUSE Allows the user to access the Microsoft mouse

device on PC systems.
%MTCHK Allows the user to interrogate the status of a

magnetic tape drive.
%NEWED Lists routines that have been filed by the program

editor between a range of dates.
%OS Performs operating system-specific tasks such as

listing a directory, renaming a file, etc., (MSM-PC
and MSM-PC/PLUS only).
%PACKAGE Loads application packages (e.g., VA FileMan,

DMS) into a UCI.
%PARTSIZ Allows the user to dynamically change the size of

the partition. An internal entry point is provided
to allow routines to change the partition size while
they are executing.

Routine Description
Name
%RCHANGE Changes all occurrences of a string in one or more
routines.
%RCMP Compares two routines in the current UCI or a

group of routines in two different UCIs.
%RCOPY Copies one or more routines from one UCI to

another.
%RD Displays a list of all routines saved in the current

UCI.
%RDEL Deletes one or more routines from the current

UCI.
%RELOAD Re-compiles all routines in a UCI after a system

upgrade.
%RPRT Prints a listing of one or more routines stored in

the UCI.
%RR Restores all or selected routines from an external

device and, as an option, allows them to be
renamed.
%RS Allows one or more routines to be saved on an

external device.
%RSAND Searches one or more routines for occurrences of

one or more character strings. If more than one
string is specified, each string must be present in
a line to satisfy the search.
%RSE Searches one or more routines for any occurrence

of one or more character strings. If more than one
string is specified, any one of the strings found
satisfies the search.

Routine Description
Name
%RSEL Allows the user to select one or more routines
from the current UCI. Full selection criteria can
be specified, such as ranges or all routines
beginning with or containing a string of
characters.
%RSIZE Displays the size of one or more MUMPS

routines.
%SBP Displays the current status, block location, and

buffer offsets for the Sequential Block Processor
device.
%SDEV Allows the user to select a device, open the device,

and specify the OPEN parameters.
%SP Displays the total amount of disk space that exists

within a volume group and the amount of free
space remaining.
%SQRT Computes the approximate square root value of a

number.
%SS Displays status information about each of the jobs

that are currently active on the system.
%T Displays the time stored in $HOROLOG in the

form HH:MM where HH is the hour and MM is
the minutes past the hour. An internal entry point
is provided to return the time in a local variable.
%TI Converts a time value in external format (e.g.,

1:05 PM) to an internal $HOROLOG format.
%TO Converts a time value from internal $HOROLOG

format to external format.

Routine Description
Name
%TRANS Allows transfer of routines and globals between
machines. Includes all necessary controls (i.e.,
checksums) to ensure proper transmission of the
routines and globals.
%UTL Provides examples of all utilities available on the

MSM system.
%VIDEO Saves and restores the contents of the video buffer

(MSM-PC and MSM-PC/PLUS only).
%XMIT Allows communication with another port on the

system. It is useful for transferring information
between machines.
Table 4-2 - System Utility Routines
Routine Description
Name
BCS Broadcasts a message to any or all active users.
BIJ Allows the system manager to configure and

maintain Before-Image Journaling (i.e.,
Bulletproofing for Volume Groups).
BLKDMP Displays the contents of any disk block stored on

the system.
COUNTERS Displays various counters that measure system

activity.

Routine Description
Name
DBFIX Allows the system manager to display and modify
the internal structure of disk blocks. This is used
to repair the routine and global structures if they
become corrupted.
DBMAINT Allows the system manager to create, expand,

display, mount, and dismount volume groups.
DDP Allows the system manager to start, stop, display,

and configure the DDP network.
DEVRESET Allows the system manager to reset a terminal

device (MSM-PC and MSM-PC/PLUS only).
DISKMAP Displays by UCI the amount of disk space

allocated in one or more map blocks.
GBMAINT Allows globals within the database to be

compressed in place or repaired.
GLBPLACE Allows the system manager to specify the UCI,

volume group, volume, and relative block number
where a global is to be placed.
JOBEXAM Allows the system manager to examine the local

symbol table of a job in execution.
JRNL Allows the system manager to start/stop

journaling, allocate or deallocate journal space,
initialize journal space on disk, display journal
space, switch journal spaces, dejournal, and
display map status.
KILLJOB Terminates execution of a specified job and

returns its devices to the system for subsequent
re-use.

Routine Description
Name
LOCKTAB Displays LOCK table information including job
number, variable that is LOCKed, and command
used to obtain the LOCK.
MAPnnn Maps the structure and contents of various system

control blocks.
MSMDR Allows the system manager to make a backup

copy of one or more volume groups. It supports
Full (i.e., all blocks) and Allocated (i.e., in-use
blocks).
OLB Allows the system manager to configure and

perform On-line Backups of the database.
PEEK Allows the system manager to monitor the input

and output taking place on another terminal
device.
RECOVER Recovers blocks within the database that are

marked Allocated, but are not in use.
RECOVLK Removes an entry in the LOCK table.
RTHIST Produces a histogram report of activity within a

MUMPS routine.
SBP Allows the system manager to allocate and

deallocate sequential disk space within an MSM
volume group.
SETBAUD Allows the system manager to alter baud rates for

terminals while the system is running.

Routine Description
Name
SPL Allows the system manager to start, stop, display,
and manage the spooling facility.
SSD Enables shutdown of the MSM system in an

orderly manner. All system shutdowns should be
performed using this utility.
STU Functions as part of the system boot procedure to

dynamically configure the system according to
the parameters specified in the SYSGEN.
STUSER Functions as part of the system boot procedure;

this is a user-defined routine.
STUIRQ Alters interrupt options for a terminal or printer

device (MSM-PC and MSM-PC/PLUS only).
SWREG Allows the system manager to control system

functions through a software switch register.
SYSGEN Allows the system manager to define the

environment used to run the MSM system.
TRANSLAT Allows the system manager to edit, display,

enable, disable, and manage the
Translation/Replication tables.
UCIMGR Allows the system manager to create, modify or

list the User Class Identifiers (UCIs) on the
system.
VALIDATE Inspects routines and globals in one or more UCIs

and provides detailed information about any
internal problems that may exist.
VERIFY Verifies that free space counters in the map blocks

agree with actual free space in maps.

CHAPTER 5
SYSTEM TABLES
This chapter describes the structure and use of various internal tables
and control blocks maintained by the MSM system.
5.1 Overview
The operating system component of MSM is responsible for initiation
and termination of jobs, allocation and de-allocation of devices, memory
management, and task management (i.e., evenly dividing CPU resources
between jobs). In order to carry out these functions, the operating system
maintains several internal tables and control blocks. These tables and
control blocks contain status information relative to the function being
controlled by the operating system. Table 5-1 below lists the primary
control blocks used in the MSM operating system.
Table 5-1 - MSM Tables and Control Blocks
Control Block Description

System Vector The System Vector (SVECTOR) is the
primary control block in MSM. It contains
information about the system and points to
other control blocks.
Partition Vector The Partition Vector (PVECTOR) contains

job-specific information.
Lock Table The Lock Table contains entries that

correspond to local and global variables that
have been locked using the LOCK command
or ZALLOCATE command.
Volume Group The Volume Group Table contains

information about each currently mounted
volume group on the system.
System Tables 5-1

Control Block Description
UCI Table The UCI Table contains information about
each UCI, including addresses of the routine
and global directories, and growth areas.
Device Descriptor The Device Descriptor Block (DDB)

contains status and use information about
each device on the system.
The information contained in these tables and control blocks can be used
to determine the status of individual system components, as well as the
status of the entire system. The $VIEW function can be used to read
the contents of these tables and the VIEW command can be used to
modify their contents. Since these tables are critical to the operation of
the system, modifying their contents with incorrect information may
cause unpredictable results, including database corruption.
5.2 The System Vector

The System Vector (SVECTOR) is the primary control table in the MSM
operating system. The information contained in the SVECTOR can be
broken into two distinct categories. They are:
• System constants, flags, and counters
• Addresses of system routines and operating system tables

Within each of these two sections of the SVECTOR, the relative position
of each entry remains constant from release to release. To facilitate
access to these two sections, special values of the Domain operand on
the $VIEW function and VIEW command have been created.
When used as an operand on the VIEW command or $VIEW function,

a Domain value of -4 indicates that an entry in the constants section of
the SVECTOR is being accessed and a Domain value of -5 indicates
that an entry in the address section of the SVECTOR is being accessed.
When using a Domain value of -4 or -5, the Offset value that is specified
is a relative offset from the start of the constants section or the address
section. This means that the first entry in the section is 1, the second
entry is 2, etc. The old form of the VIEW command and the $VIEW
function that used an absolute byte offset from the start of the SVECTOR
should no longer be used.
5-2 System Tables

When SVECTOR constants are accessed, a Domain value of -4 should
be used. When SVECTOR addresses are accessed, a Domain value of
-5 should be used. Table 5-2 below describes SVECTOR constant entries
and Table 5-3 describes SVECTOR address entries.
Table 5-2 - System Vector Constants
Relative Field Description of Field

Offset Length
2 4 The address of the system LOCK Table.
12 2 A count of the maximum number of UCI

entries in each Volume Group Table.
14 2 The length of each UCI entry.
38 2 A count of the number of terminal DDBs

defined in the system.
Table 5-3 - System Vector Addresses
Relative Field Description of Field

Offset Length
2 4 The address of the system LOCK Table.
4 4 The address of a table containing counters

with information about system performance.
7 4 The address of the table containing the

address of each Device Descriptor Block.
Each entry is 4 bytes.
10 4 The address of the table containing the

address of each Volume Group Entry. Each
entry is 4 bytes.
14 4 The address of the system Pattern Match table

(i.e., defines pattern code of each character).
86 4 Reserved for use by application routines.
System Tables 5-3

5.3 The Partition Vector
A partition in MSM consists of a logical grouping of the local symbol
table, the current routine edit buffer (i.e., the text of the routine), and
work areas used by the system and the job. The actual amount of memory
in use at any time grows and shrinks based on the current requirements
of the job.
Because the memory management process is handled entirely by the
MSM system, the user need not be concerned with the space being used.
The storage is dynamic (up to the maximum amount allowed for the job)
and is not pre-allocated for the job. In general, when a routine is loaded,
when the symbol table expands, or when the interpreter stack overflows,
additional space is assigned to the partition.
Because of the dynamic nature of MSM, partition size is defined to be

the maximum amount of memory that can be assigned to a job at any
one time. This arbitrary limitation on size can be changed when a user
logs on the system, when a job is started with the JOB command, or by
the job itself during execution. Unlike fixed-partition systems, MSM
uses only the actual memory required by a job.
The PVECTOR contains job-specific control information, status
indicators, and other flags. Table 5-4 below lists entries in the
PVECTOR that are useful to the system manager.
5-4 System Tables

Table 5-4 - The Partition Vector
Decimal Field Description of Field

Offset Length
2 2 The UCI index number for the job.
4 2 The $JOB number for the job being executed.
6 2 The number of the current I/O device.
8 2 The number of the principal I/O device.
96 4 The total number of commands executed by

the job since it was created.
100 4 The total number of commands executed by

the job since the last terminal READ.
104 4 The current number of bytes used by the

partition.
108 4 The maximum number of bytes that can be

used by the job (i.e., the partition size).
868 4 Reserved for use by application routines.
System Tables 5-5

5.4 The Lock Table
The Lock Table contains entries for every variable that has been locked
using the LOCK command or the ZALLOCATE command. Once a
variable has been locked by a job, no other job can lock the variable. If
a job attempts to lock a variable that has been previously locked by
another job, it waits until the variable is unlocked, unless a timeout value
is specified.
Entries in the Lock Table are of variable length. Each entry describes
one locked variable. Table 5-5 below describes the format of each entry.
Table 5-5 - The Lock Table

Offset Length
0 4 The pointer to the first lock table entry.
4 2 The current number of bytes in use in the

Lock table.
- - The following is a description of each entry.

The offsets are relative to the beginning of
each entry.
0 4 The pointer to the next lock table entry.
4 2 The job number of the job that issued the

LOCK or ZALLOCATE command.
6 2 The compressed system name of the machine

on which the Lock was issued.
8 2 The incremental LOCK counter.
10 1 A flag indicating the type of entry. The value

of this flag is 1 if the entry was generated by
the LOCK command. The value is 2 if the
entry was generated by the ZALLOCATE
command.
5-6 System Tables

Offset Length
11 1 A flag indicating the type of entry. A value
of 1 indicates a global entry name. A
cross-system entry created through DDP has
a value of 2. A cross-system entry created
through a Remote Volume Group has a value
of 4.
12 1 Contains the hashed value of the locked entry.
13 1 The length of the LOCKed variable name.

The length does not include the length field
itself.
14 1 The name of the variable that is locked. For

global references, the name is prefixed by the
name of the UCI in brackets (e.g., [MGR]).
The parentheses and commas are replaced
with hexadecimal zero (i.e., "00").
A utility program (i.e., LOCKTAB) is supplied with MSM to format the

contents of the LOCK Table. Refer to Chapter 4 (MSM Utility
Programs) for additional information on this utility.
System Tables 5-7

5.5 The Volume Group Table
The Volume Group Table contains an entry for each volume group that
is currently mounted on the system. Each volume group entry in turn
describes each of the individual volumes contained in the volume group.
The SVECTOR contains a pointer to a table of volume group entry
addresses. To find the address of a specific volume group, this table of
addresses can be indexed by volume group number. The table of
addresses is terminated by an entry that contains an address of zero (0).
Table 5-6 below lists entries in the Volume Group Table that are useful
to the system manager.
Table 5-6 - The Volume Group Table

Offset Length
0 3 The external name of the volume group.
8 2 The internal name of the volume group.
10 1 Bit flags indicating the volume group type.

The value 4 indicates the entry is for a remote
volume group.
11 1 Indicates the state of the volume group. A

value of 3 indicates the volume group is
mounted and ready for use.
12 2 A flag indicating the local status of the

volume group.
14 2 Flags indicating whether the volume group

can be mounted by a remote system.
20 4 A pointer to the UCI table associated with the

volume group.
30 2 Maximum global data length allowed for the

volume.
5-8 System Tables

Offset Length
40 2 The number of volumes contained in the
volume group.
42 2 The maximum number of map blocks in the

volume group.
44 4 The maximum number of blocks contained

in the volume group.
56 4 A pointer to the Storage Allocation Table

associated with the volume group.
68 2 An index to the first free bit in the Storage

Allocation Table.
70 2 Number of remote systems that have

mounted this volume group.
Note that in the tables above, all fields beginning at offset 40 are only
valid for local volume groups. For remote volume groups, the fields are
maintained on the system where the volume group exists as a local
volume group.
The following fields are repeated for each volume within the volume
group. In the section that follows, the value of n is calculated as 8 times
the volume number. Volumes are relative to zero (i.e., the first volume
is 0, the second volume is 1, etc.).

Offset Length
72+n 4 Total number of blocks contained on the
volume.
76+n 1 Disk controller unit number.
77+n 1 Disk drive number within disk controller.
78+n 2 The actual number of maps on the volume.
System Tables 5-9

5.6 The UCI Table
The User Class Identifier (UCI) Table contains a list of the UCIs that
have been defined through the SYSGEN process. Up to thirty-two (32)
entries can be defined for each volume group mounted on the system.
Entries in the table are assigned index numbers sequentially,
corresponding to their relative position in the table. The first entry in
the first UCI table is defined to be the system UCI (i.e., the manager’s
UCI) and has an index value of 1.
Each entry in the UCI Table contains information describing the location
of the routine directory, the global directory, the global expansion
attributes, and the routine expansion attributes. Table 5-7 below
describes the format of each UCI entry.
Table 5-7 - The UCI Table

Offset Length
0 2 The UCI name in compressed format.
2 2 Reserved for future use.
4 4 The block number specifying the location of

the global directory. This number is relative
to the start of the volume group that contains
the UCI.
8 4 The block number specifying the location of

the routine directory. This number is relative
to the start of the volume group that contains
the UCI.
12 2 The relative map number indicating the

starting location to begin the search for free
space when allocating global pointer blocks.

ending location to search for free space when
allocating global pointer blocks.
5-10 System Tables

Offset Length
space when allocating global data blocks.

allocating global data blocks.

space when allocating routine blocks.

allocating routine data blocks.
24 4 Reserved for future use.
28 2 An index into the UCI translation table.
30 1 A flag byte that specifies various options for

the UCI. A value of Hex ’80’ indicates that
the entire UCI is to be journaled and a value
of Hex ’40’ indicates that database write
operations are suspended for the UCI.
31 1 The UCI index to be used as the Library UCI

(i.e., location of % routines and %globals).
A value of zero (0) indicates the Manager’s
UCI on volume group 0.
Note that the expansion/limit fields in the UCI table are not supported
for Remote Volume Groups. A utility program (UCIMGR) is supplied
with MSM to format the contents of the UCI Table. Refer to Chapter 4
(Utility Programs) for additional information on this utility.
System Tables 5-11

5.7 The Device Descriptor Block
The Device Descriptor Block (DDB) is used to store status and control
information about a specific device. One DDB is initialized for every
terminal, printer, VIEW device, and Sequential Block Processor (SBP)
device during system startup.
The SVECTOR contains a pointer to a table of DDB addresses. Each
entry in the table is 4 bytes in length and contains the absolute address
of the DDB. The first four bytes in the DDB address table are reserved.
Device 1 is the first entry (i.e., offset 4), device 2 the second entry, and
so on. Table 5-8 below lists entries in the Terminal DDB that are useful
to the system manager.
Table 5-8 - The Device Descriptor Block

Offset Length
0 4 The number of the device associated with the
DDB.
4 2 The device type associated with the DDB. A

value of 0 indicates a standard DDB with no
extensions, 1 an HFS device, 2 a Terminal
device, 3 an SBP device, 4 an Interjob
Communications device, 5 a View device, 6
a special journal device, 7 a spooling device,
8 a tape device, and 9 a host spooling device.
6 1 The current value of the $X Special Variable

(i.e., the current column number) for the
device.
7 1 The current value of the $Y Special Variable

(i.e., the current row number) for the device.
A utility program (MAPDDB) is supplied to format the contents of the

DDB Table. Refer to Chapter 4 (MSM Utility Programs) for additional
information on this utility.
5-12 System Tables

CHAPTER 6
GLOBALS
This chapter describes the mechanism used by MSM to implement global
variables. It provides information on how to create, reference, and
protect globals, as well as information about their internal structure and
how they are organized on disk.
6.1 Global Variables

Within MSM, a hierarchical database structure has been implemented
to provide users a fast and efficient method for creating, storing and
retrieving data. This structure, which can be thought of as a pyramid,
consists of one or more levels of indices, which can be searched to find
the location of a specific data element, and a single level of data elements.
Multiple index values are grouped together to form a block.
At the top of the pyramid, there is one block of indices. Below that there
may be one or more blocks of second level indices. This can continue
on for as many levels as necessary to describe the actual data. Below
the last index level, there is one layer of blocks that contain the actual
data being stored. This level of data blocks represents the bottom of the
pyramid.
The internal structure of the database is maintained entirely by the

system. The user does not need to be concerned with the physical
structure, location of the data, or the amount of space occupied by the
data. The system dynamically expands and contracts the structure to
meet the data storage requirements.
6.1.1 Global Usage

While the internal structure of the database is somewhat complex, the
method used to store and retrieve information in the database is
extremely simple. To the programmer, each database that has been
defined appears as an array. An array is simply a collection of elements
grouped under the same name. Individual elements within the array are
distinguished from other elements by subscripts. Thus, a global
reference consists of the following:
Global Name(subscript1,subscript2, ... ,subscript-n)
Globals 6-1
The Global Name consists of a circumflex (^) followed by one to eight
characters. The first character must be alphabetic or a percent sign (%).
Following the name, the reference may include zero, one, or more
subscripts. Subscripts may be alphabetic or numeric and may include
punctuation and control characters. If the subscript is not a canonic
number, it must be enclosed in quotes. A canonic number has no leading
zeros before the decimal point and no trailing zeros after the decimal
point. Also, it does not contain a decimal point if one is not required.
When subscripts are included, they are appended to the global name,
enclosed in parentheses, and separated by commas. The total length of
the global reference (i.e., name and subscripts) cannot exceed 255
characters. Each subscript may be up to 252 characters when using string
collation and 251 characters when using numeric collation and may
contain any value except ASCII null (i.e., decimal 0).
6.1.2 Collating Sequence

Subscripted global variables may include numeric valued subscripts,
string valued subscripts, or the two types can be intermixed. For this
reason, MSM allows the user to specify the order in which the subscripts
are to be collated. The user can specify either numeric sequence or string
sequence.
For globals where a collating sequence type of string has been specified,
all subscripts (numeric and non-numeric) are treated as character strings
and stored in ASCII collating sequence. Assume that a global variable
X has subscripts of -10, -2, -1, 1, 0, 1.1, 2, 3, 10, 20, 30, and "ABC"
defined. In string collating sequence, the subscripts of X would be 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")
6-2 Globals
In globals where the collating sequence is numeric, the system stores
canonic numbers (i.e., numeric values with no leading zeroes or trailing
zeroes after the decimal point) first, followed by the non-numeric values
in ASCII collating sequence. Assuming that global variable X has the
same subscripts as before and that it has been assigned numeric collating
sequence, then the subscript values would be 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")
When a global is created, it is assumed to be in numeric collating

sequence. The %GCH utility program can be used to modify the
collating sequence for any global. In order to change the sequence, the
global must exist, but must not have any subscripts defined. For
additional information on the %GCH utility, refer to the MSM Utility
Manual. Also, the default collating sequence for newly created globals
can be changed using the SYSGEN utility. Refer to the appropriate
MSM System Manager’s Guide (Generating The System) for additional
information.
6.2 The Disk Database

The primary external storage device in MSM is the disk. The entire disk
is divided into logical 1024-byte (i.e., 1K) blocks. The first block on
the disk is block zero, the second is block one, and so on. These numbers
are referred to as relative block numbers. In addition to its block number,
each block is assigned one of 16 different block types. The block type
is used to indicate how the block is being used by the system. The table
below describes the block types that are used in MSM.
Globals 6-3
Table 6-1 - MSM Block Types
Type of Block Description

Map Block Controls allocation/deallocation of disk
blocks and records UCI ownership.
Global Directory Tracks each global defined in a UCI. For each

UCI, one Global Directory exists.
Pointer Block Contains global keys and pointers to other

pointer blocks or data blocks.
Routine Directory Has the same format as a pointer block, and

keeps track of routines stored in a UCI.
Data Block Contains the name, subscripts, and actual

data values for a global.
Routine Header Stores control information and executable

code for a routine.
Routine Data Stores executable programs. One or more

blocks may exist for each routine.
SBP Block Stores data for SBP.
Journal Block Contains system Journal entries.
Label Block Contains system label for a volume.
Spool Directory Lists spooled files.
Spool Data Contains data for spooled files.
UCI Directory Lists UCIs for a Volume Group.
BIJ Status Block Maintains status about before-image

journaling of a Volume Group.
OLB Status Block Maintains status during on-line backup of a

Volume Group.
6-4 Globals
The following sections contain descriptions of the commonly used block
types including the Map Block, Global Directory, Pointer Blocks, and
Data Blocks. For a description of the Routine Header Block and the
Routine Data Block, refer to Chapter 7 (Routine Data Structure).
6.2.1 Disk Buffers

All disk resident information in MSM is read from or written to the disk
using a temporary storage area called a buffer. The number of disk
buffers defined for a given system varies depending upon the amount of
memory that is available on the system. During system initialization,
MSM dynamically allocates a pool of disk buffers (i.e., the buffer cache).
Each buffer in the cache is 1024 bytes in length. This corresponds to

the logical block size of the information stored on disk. The first 1012
bytes of each buffer is used to store information that is specific to the
block type (i.e., directory entries, pointers). The remainder of the space
is used by the system to control the overall global database structure.
The table below describes the format and contents of a disk buffer.
Table 6-2 - Disk Buffer
Decimal Field Description of Field Offset

Offset Length
0 1011 Contains information specific to block type.
1012 4 Contains the block number of the right-hand

link and points to the next block in the chain.
For routine blocks, it points to a continuation
block.
1016 4 Contains the block number of the block (self

pointer).
1020 1 Contains a block type indicator. A value of

1 indicates global directory, 2 pointer block,
3 and 4 global data, 5 routine directory, 6
routine header, 7 routine data, 8 map block,
9 journal block, 10 SBP block, 11 spool
directory block, 12 spool data, 13 a label
block, 14 a UCI directory, 15 BIJ status block,
and 16 OLB status block.
Globals 6-5
Offset Length
1021 1 Contains the secondary block type. The
high-order bit (i.e., hex ’80’) indicates a
bottom-level pointer block.
1022 2 Contains the offset of the next free byte in the

block. The system uses this field to determine
where to insert data in the block. For Map
blocks, this field contains a count of the
number of free blocks described by the map.
6.2.2 Map Blocks

Map Blocks control which disk blocks are assigned to a UCI (i.e., in-use
blocks) and which blocks are free. Every 512 consecutive disk blocks
are defined by a Map Block. The map is stored as the second block
within the group. Using this scheme, the size of a volume is limited to
the number of 512-block groups that fit on the disk. The last map block
in a volume does not need to be complete. Blocks in the map that would
spill off the end of the disk are marked as non-database blocks.
Since a Map block describes 512 blocks and is the second block in the
group, the Map Block location can be computed. The first Map is block
1 (i.e., describes block 0 to 511), the second is 513, etc. The internal
format and contents of a Map Block are described in Table 6-3 below.
Table 6-3 - Map Block

Offset Length
0 512 Indicates the status of the corresponding
block in the map group. If the block is free,
it contains zero. If it is allocated, it contains
an index to the UCI that owns the block, or
one of the following: 250 - Spool, 251 -
Journal, 252 - SBP, 254 - Non-Database or
Bad Block, 255 - System.
6-6 Globals
Offset Length
512 2 Contains the offset of the first free block
within the map.
1020 1 Contains the block type indicator. A value

of 8 indicates the block is a system map block.
If the block type field does not contain a value
of 8, the system generates a disk software
error (<DKSER>) when it is accessed.
1022 2 Contains a count of the free blocks available

in the Map Block group.
Within the Map Block, there is a block type indicator to identify the Map
Block to the system. The system can also determine a block is a Map
Block by its relative position on the disk. The VERIFY utility may be
used to validate map blocks. Refer to the MSM Utility Manual for
additional information on the VERIFY utility.
6.2.3 Global Directory Blocks

A Global Directory keeps track of globals that have been created within
a UCI. There is a Global Directory for each defined UCI. The address
of the Global Directory is stored in the UCI Table. For additional
information on the UCI Table, refer to Chapter 5 (System Tables).
When a global is created, an entry is added to the appropriate Global

Directory block. Entries are stored in the directory in alphabetical order
rather than the order they were created. Each entry includes the name
of the global, collating sequence, protection attributes, and growth
information. Global names are variable length and may contain from
one to eight characters. If the name is specified with more than 8
characters, all characters after the 8th are ignored.
To improve access efficiency, globals names are stored in compressed

format. Name compression eliminates leading characters that are in
common with the preceding global name. Global Directory blocks use
the same compression technique as Pointer and Data blocks. Following
each global name, a fixed length Global Directory Element provides
information about the global. Table 6-4 below describes this field.
Globals 6-7
Table 6-4 - Global Directory Element

Offset Length
0 3 Contains the block number for the top-level
Pointer block assigned to the global.
3 1 Contains flags that control the collating

sequence and journaling attributes. If bit
X’01’ is off, the global’s collating sequence
is numeric. If it is on, the collating sequence
is string. If bit X’80’ is on, the global is to
be journaled. If bit X’40’ is on, the global is
never journaled.
4 1 Specifies the protection attributes for the

global. It is broken down into four sub-fields,
each two-bits in length, that specify the
system, world, group, and user protection
attributes. In each sub-field, a value of 0
indicates no access, 1 indicates read-only
access, 2 indicates read and write access, and
3 indicates read, write, and delete access.
5 3 Reserved for future use; this field should

contain a zero.
8 3 Contains the block number to begin searching

for free space to expand the global. No new
blocks are allocated with block numbers less
than this value. If this field is zero, the system
uses the value in the UCI Table. This is
referred to as the global growth pointer.
6-8 Globals
When all space in the Global Directory block is exhausted and an attempt
is made to create a new global, the system automatically creates two
new bottom-level Global Directory blocks, each containing about half
of the globals from, and using the same format as, the original. The
original Global Directory block is converted to a top-level Global
Directory block which has the same format as a Pointer block (described
below). The information contained in the UCI Table relating to pointer
growth is used to determine where the new blocks should be allocated.
6.2.4 Pointer Blocks

Pointer blocks are used as indices into the hierarchical database structure
of MSM. Within the system, two types of Pointer blocks are maintained:
Pointer blocks and Bottom-Level Pointer blocks. The indices stored in
these blocks consist of a global reference and a block number (i.e., the
pointer) that specifies the location of some other block of information
stored on the disk.
For any given global, the block number of the Top-Level Pointer block
is contained in the Global Directory. Each Pointer block in the global
then points to either a Bottom-Level Pointer block or to another Pointer
block. Every Bottom-Level Pointer block points to Data blocks. Thus,
by searching the Global Directory and Pointer blocks, the system can
determine the exact location of any data node within the global.
A Pointer block consists of one or more Pointer Elements. Each element
includes the global name, subscripts if they exist, and a pointer to another
Pointer block or the data block. The global reference in the element is
the first reference that exists in the next level pointer block or data block.
To reduce the amount of disk storage required by globals, the system
compresses the information in these elements. The table below describes
the format and contents of a Pointer Element and the technique used to
compress the information contained in the global reference.
Globals 6-9
Table 6-5 - Pointer Element

Offset Length
0 1 Contains a count of the number of characters
this global reference has in common with the
previous entry (i.e., the common count). For
the first entry in the block, this field is zero.
1 1 Contains a count of the number of characters

that follow the common characters in the
global reference. This number is referred to
as the unique count.
2 - Contains the unique characters from the

global reference. The length of this field is
determined by the previous field. All
parentheses and commas are replaced with an
ASCII value of 0 to explicitly define their
location in the global reference.
- 3 Contains the block number of the next Pointer

block or the Data block. This field contains
the block number of the next Pointer block or
the Data block containing the global value.
Within a Pointer element, subscripts can be numeric, string, or a

combination of the two. In order to assure that subscripts collate properly
in globals that are defined to have a numeric collating sequence, one
additional byte is pre-pended to each subscript. This byte, which
precedes the subscript, contains a count of the number of digits to the
left of the decimal point in the number. This field contains the value
255 for string subscripts.
6.2.5 Data Blocks

The Data block is the lowest level element in the hierarchical database
structure of MSM. It contains global nodes (i.e., the global name together
with its subscripts) and their data values. Each Data block is made up
of one or more Data Elements. The contents of a Data Element are
described in the table below.
6-10 Globals
Table 6-6 - Data Element

Offset Length
0 1 This field contains the common count. It is
computed in the same manner as Pointer
blocks.
1 1 This field contains the unique count. It is

computed in the same manner as Pointer
blocks.
2 - This field contains the unique characters of

the global reference. Its length is determined
by the previous field. Parentheses and
commas are treated in the same manner used
for Pointer blocks.
- 1 This field contains the data type for the value

of this global node. A value of 3 indicates a
string less than 256 characters. The byte
following this field contains the length of the
string. A value of 8 indicates a long string.
The length of the string is 256 plus the value
of the length byte.
- - This field contains the data value. The length

and contents are determined by the previous
field. For string types, the first character
contains the length of the string.
Elements are stored in collating sequence within the block up to the

capacity of the block. If the system attempts to insert an entry and there
is insufficient room, a block split occurs. A block split divides the block
into two pieces of approximately equal size. All associated pointer
blocks are updated to reflect the split. If necessary, the pointer blocks
are also split. The exception to this is appending to the end of a global.
This causes the new data to be placed into new blocks, bypassing the
split.
Globals 6-11
6.3 Global Expansion Areas
MSM allows the user a great deal of flexibility in determining where
global data is to be stored on the disk. A utility program (GLBPLACE)
is supplied with the system that creates a global at a specified location
on the disk. The user specifies the global name, UCI name, volume
group name, block number (i.e., volume number and relative block
number) for the pointer block, and block number for the data block. For
additional information on this utility, refer to Chapter 5 (MSM Utility
Programs).
Once a global has been created, additional controls within the system
allow the user to specify what areas of the disk are available to it as it
grows. These areas are referred to as global expansion areas. When
additional space is required, the system looks for free blocks with
numbers greater than or equal to the map number specified for global
expansion. If no free space is found, a <DKFUL> error occurs.
Global expansion areas can be specified for each individual global in a
UCI. A utility program (%GCH) is supplied with the system to allow
users to specify growth areas on an individual global basis. To define
the growth area for a specific global, the user must be logged onto the
UCI containing the global when the utility is run. The utility prompts
the user for the global name and block number where expansion is to
begin.
If an expansion area has not been specified for a particular global, the
system uses the expansion parameters defined in the UCI Table. For
additional information on the UCI Table, refer to Chapter 6 (System
Tables). The expansion parameters for a UCI are specified as part of
the SYSGEN process. They can also be modified at any time through
the SYSGEN. For additional information on modifying the UCI
expansion parameters, refer to Chapter 9 (Generating the System).
6.4 Global Organization

In the previous sections, the basic components of a global were
described. These included Global Directory blocks, Pointer blocks, and
Data blocks. In a general sense, Global Directory blocks contain pointers
to Pointer blocks, and Pointer blocks point to Data blocks. Also, the
Right Link field in Pointer blocks and Data blocks point to Pointer and
Data blocks that are on the same level. The various relationships that
exist between the blocks are shown in the figure that follows.
6-12 Globals
Figure 6-1 - Global Organization
GLOBAL POINTER BOTTOM LEVEL DATA

DIRECTORY BLOCK POINTER BLOCKS
BLOCK BLOCKS
GL =Data
GL(1,1)=Data
GL(1,2)=Data
Right Link
GL(2,3)=Data
GL(2,7)=Data
GL(3) =Data
Right Link
GL GL(4) =Data
GL(2,3) GL(4,3)=Data
GL(4,4)=Data
Right Link Right Link
ACCTS GL GL(4) GL(6,2)=Data

GL GL(4) GL(6,2) GL(6,6)=Data
JOURNAL GL(8,2) GL(7,1) GL(6,7)=Data
Right Link=0 Right Link=0 Right Link Right Link
GL(8,2) GL(7,1)=Data
GL(9) GL(7,2)=Data
GL(8,1)=Data
Right Link=0 Right Link
GL(8,2)=Data
GL(8,5)=Data
GL(8,7)=Data
Right Link
GL(9) =Data
GL(9,1)=Data
GL(9,3)=Data
Right Link
Globals 6-13
6.5 Cross-UCI Global References
The MSM system allows users to not only access globals stored in their
own UCI’s but to access globals stored in different UCI’s on the same
volume group as well. This is done using an extended global reference
notation that includes, in addition to the global name, the name of the
UCI where the global is stored. The notation for referencing globals in
a different UCI is:
^|UCI|Global Reference
The UCI Name specified in this notation is the name of the UCI where
the global is stored. It can be a variable containing the name or the actual
three character name itself (e.g., "FMR"). In either case, the specified
UCI must exist or a <NOUCI> error occurs. If the actual UCI name is
specified, it must be enclosed in quotes. The Global Reference specified
in this notation is the name of the global to be accessed. It may be a
simple global name, may include subscripts or may be a naked reference.
Any error message or error condition that may occur is returned by the
operating system just as if the reference had been to a global in the current
UCI. The most common error returned as a result of a Cross-UCI global
reference is the <PROT > error. This occurs whenever an attempt is
made by a program or a user in programmer mode to access a global
that it is not authorized to access.
6.6 Cross-Volume Global References

In the same fashion that MSM allows you to access information stored
in a different UCI, you can access information stored in a different
volume group. To do this, you must explicitly specify the UCI name
and the volume group name. This is done using the following syntax:
^|UCI,VGP|Global Reference
In this form, the UCI name can be a variable (e.g., UCINAME) or the
actual three-character name (e.g., "TST"). Similarly, the volume group
name can be a variable or the actual external volume group name. The
UCI and VGP names may also be combined into a single expression
(e.g., ^|"FMR,VAH"|DIC). The same rules described above for
accessing data in a different UCI on the same volume group apply when
accessing data on a different volume group.
6-14 Globals
6.7 Cross-System Global References
As an optional feature, the MSM system supports Distributed Data
Processing (DDP), which allows information that resides on a physically
different system to be accessed directly by a MUMPS program. If DDP
has been installed on the system, then remote data can be accessed by
explicitly specifying the UCI name and the remote system name in the
global reference. This is done using the following syntax:
^|UCI,SYS|Global Reference
In this example, SYS is the three-character name of the volume group
on the remote system which contains the global being referenced. This
name can be specified as a variable or the actual external system name.
The system must be active on the network at the time of the request, or
an error (i.e., <NOSYS>) occurs. The same rules described above for
accessing data in a different UCI on the same volume group apply when
accessing data on a remote system.
6.8 UCI Translation and Replication

The global translation feature of MSM provides a mechanism through
which every reference to a particular global in a UCI within a volume
group is internally changed to reference a global with the same name in
a different UCI. The UCI may be in a different volume group on the
same system or a different system when Distributed Data Processing
(DDP) is used. The replication feature allows globals SETs and KILLs
to be duplicated in up to seven (7) additional UCIs. Like translation,
the UCIs may be in different volume groups on the same machine or on
different machines. A global can be translated and replicated at the same
time. Use of explicit global references (i.e., cross-UCI or cross-system
references) bypasses the Translation and Replication Tables.
6.9 Remote Volume Groups

In addition to DDP support, the MSM system supports a concept of
Remote Volume Groups (RVGs). An RVG is essentially the same as a
local Volume Group except that it exists on another system connected
through a network to MSM. The RVG can be mounted, users can log
onto it, programs can be loaded and saved, and globals can be accessed
without the need for Cross-System global notation or translation. For
additional information on RVGs, refer to the MSM-NET Services
chapter in the appropriate MSM System Manager’s Guide.
Globals 6-15
6.10 High Availability Databases
To ensure database integrity, the MSM system supports a concept known
as bullet-proof databases. This means that in the event of a failure, the
system can be restarted and MSM will ensure that the database has logical
integrity. Using this feature, it is no longer necessary to VALIDATE
the structure of the database. This is achieved using a combination of
Before-Image Journaling (BIJ) and After-Image Journaling (AIJ). Refer
to Chapter 8 (Global Journaling) for additional information on this
feature.
The MSM system also supports a feature known as Cross-System

Journaling. Using this feature, the After-Image Journal can be
dynamically de-journaled and applied to the database of a remote system
through the Distributed Data Processing feature. This allows a hot
backup system to be maintained. Refer to Chapter 8 (Global Journaling)
for additional information on this feature.
6.11 Global Protection

The MSM system allows the user to control who is allowed to access
information and the degree of access permitted. This is done by assigning
protection attributes to a global. A utility program (%GCH) is supplied
with the system to establish these attributes. To run this utility, the user
must be logged onto the UCI where the global is stored. The utility
prompts the user for the name of the global and the protection codes.
Protection within the system is divided into four different groups or

classes of user. These are:
SYSTEM This class includes all users and programs

running in the Manager’s UCI (i.e., UCI #1).
USER This class includes all users and programs
running in the same UCI where the global is
stored.
GROUP This class includes all users and programs that
belong to the same volume group (i.e., the
program resides within the volume group or the
user is logged onto the volume group).
WORLD This class includes all users and programs that
do not belong to any of the other three classes.
6-16 Globals
Separate protection codes can be assigned for each class of user and may
be changed via the SYSGEN utility. Within a class, one of the four
following types of protection can be specified.
READ This allows users within the specified class to
look at the global, but no modifications are
permitted.
WRITE This allows users within the specified class to
look at and modify the global. The user is not
permitted to delete (i.e., KILL) the global or
nodes within the global.
DELETE This allows users within the specified class to
look at, modify, and delete the global.
NONE This denies all access to the global for users

within the specified class.
When a global is created, the system automatically assigns protection
codes to it. This default protection allows the USER and SYSTEM
classes READ, WRITE, and DELETE access. The GROUP and
WORLD classes are denied all access to the global. For globals that
begin with a percent sign (%),the GROUP and WORLD classes are
allowed READ access. The default protection for newly created globals
can be changed using the SYSGEN utility.
Globals 6-17
This page is intentionally left blank.
6-18 Globals
CHAPTER 7
ROUTINE DATA STRUCTURE
This chapter describes the internal structure used to store routines on
disk.
7.1 Overview
The MSM system stores routines on disk as a collection of routine files.
The internal structure that is used to maintain these routines consists of
a two-level data hierarchy.
At the highest level, the system maintains a directory of routine names.
Each routine name known to the system is physically stored within a
directory block. The collection of all directory blocks containing routine
names is referred to as the Routine Directory. One routine directory
exists for each UCI defined to the system.
At the lowest level, the system maintains one or more routine blocks for
each routine that is stored on disk. The first block contains the routine
name, the routine body, and additional control information describing
the routine. This block is referred to as the Routine Header Block. If
the routine being stored is too large to fit into one block, then the system
chains multiple routine blocks together to store the remainder of the
routine. The second and subsequent routine blocks are referred to as
Routine Data Blocks.
As part of the SYSGEN process, the system manager specifies the block
number for the first routine directory block in each UCI. This block
number is stored in the resident UCI table. For additional information
on the UCI table, refer to Chapter 5 (System Tables).
When a routine directory block becomes full and a new entry must be
inserted into the block, the system splits the block into two pieces. When
this occurs, the new block is allocated using the routine expansion area
information supplied during the SYSGEN. The system begins a
sequential search for a free disk block using the map block designated
as the start of the routine expansion area. The first free block that is
found is assigned to the directory.
Routine Data Structure 7-1

7.2 Routine Data Structure
The internal structure of the routine directory block is identical to the
structure of bottom-level pointer blocks for globals. Routine names are
stored in alphabetical order as if they were globals without subscripts.
The actual manipulation of routine directory blocks is performed by the
global manager in MSM.
Within the routine directory, routine names are stored in the same
location and format as entries in the global directory. When the number
of routines increase to the point where a block split occurs, two pointer
levels are created. A new block is allocated as a pointer block and half
of the original block is copied to a new bottom-level pointer block.
Each entry in the routine directory points to a single routine header block.
This routine block contains all, or part of, the routine body for the
referenced routine. These routine blocks contain the same control
information as global data blocks with the exception that the right-hand
links are used to point to routine data blocks. When the routine is too
large to fit into a single routine header block, continuation blocks (i.e.,
routine data blocks) are used. Each routine data block contains a pointer
to the next routine data block, if one exists.
If the volume group where the routine is saved specifies that more than
one type of P-Code is to be maintained, there will be a separate chain
of routine blocks for each P-Code type. Each routine header block
contains a field in the control information area which points to the routine
header block containing the different P-Code type.
7.3 Routine Data Block Format

As previously stated, the internal structure of routine directory blocks
is the same as bottom-level pointer blocks for globals. For additional
information on the structure of pointer blocks, refer to Chapter 6
(Globals). The internal structure for routine header and the internal
structure for routine data blocks is shown in the following tables.
7-2 Routine Data Structure

Table 7-1 - Routine Header Block Structure

Offset Length
0 1 Contains the release level of the generated
P-Code.
1 1 Indicates the length of the routine name.
2 8 Contains the name of the routine. If the name

is less than 8 characters, it is padded with
hexadecimal ’00’ characters.
30 1 Indicates the type of P-Code this routine

contains. A value of 0 indicates Big-Endian
and a value of 1 indicates Little-Endian.
32 4 Points to another routine header block, if one

exists, which contains a different type of
P-Code for this routine.
36 976 Contains the routine body, which consists of

one or more routine lines. Each line of a
routine is stored in pseudo-code (i.e.,
P-Code), which has its own special format.
1012 4 Points to a routine data block containing

additional routine lines. This field contains
zeroes if there are no routine data blocks.
1016 4 Contains the block number of the block.
1020 1 Contains the block type indicator. A decimal

value of 6 indicates the block is a routine
header block.
1021 1 Contains the secondary block type indicator.
1022 2 Reserved by the system for future use.
Routine Data Structure 7-3

Table 7-2 - Routine Data Block Structure

Offset Length
0 1012 Contains the routine body, which consists of
one or more routine lines. Each line of the
routine is stored in pseudo-code (i.e.,
P-Code), which has its own special format.
1012 4 Points to a routine data block containing

additional routine lines. This field contains
zeroes if there is no continuation block.
1016 4 Contains the block number of the block.
1020 1 Contains the block type indicator. A decimal

value of 7 indicates the block is a routine data
block.
1021 1 Contains the secondary block type indicator.
1022 2 Reserved by the system for future use.
7-4 Routine Data Structure

CHAPTER 8
RESILIENT SYSTEMS
This chapter describes the Before-Image Journaling, After-Image
Journaling, Cross-System Journaling through DDP, and On-Line
Backup features of MSM. Using these features, resilient system
configurations can be created.
8.1 Overview
As users become more and more dependent on computerized
applications, the impact of system failures significantly increases. At
the very least, each failure is an annoyance that users do not patiently
tolerate. In the worst case, a failure can severely damage a company’s
ability to operate. To solve this problem, system administrators look for
ways to construct systems that minimize these disruptions in service.
The goal is for these systems to be continuously available to the users

(i.e., non-stop operation 24 hours a day) or for the system to be quickly
recoverable in the event of a temporary or permanent failure. Systems
designed in this way are referred to as resilient systems. Within MSM,
the following features are provided to assist the system administrator in
implementing resilient systems.
• Before-Image Journaling - Ensures structural integrity of a

database in the event of a temporary system failure.
• After-Image Journaling - Used to update a database after a
temporary or permanent system failure.
• Cross-System Journaling - Maintains a duplicate database on

a secondary system.
• On-Line Backup - Allows database backup operations to occur

while users are logged onto the system and database updates
are occurring.
Each of these features operates independently of the other features. They

can be used in configurations that contain a single computer or in
configurations with multiple computers connected through a network.
The following sections describe each of these features in detail.
Global Journaling 8-1

8.2 Before-Image Journaling
Before-Image Journaling is the method used to ensure database integrity
in the event of a system failure. This optional feature records images of
database blocks as they existed at the instant prior to changes being made
to the block (for example, SET, KILL, block split). These images, which
are recorded in a separate file, are used by the system to rollback the
database to a point in time where structural integrity is known to exist.
This rollback of the database is automatically performed by MSM the
first time the system is started after a system failure. When after-image
journaling is used, the system will also automatically roll-forward the
database using the information stored in the after-image journal. When
this combination of before-image and after image journaling is used after
a system failure, the database will have structural integrity, and
information will be current up to the last entry in the after-image journal
file.
8.2.1 Before-Image Journaling Concepts

In MSM, each Volume Group is considered to be a separate database.
When a database is created, the system administrator can specify whether
or not it is to be protected with before image-journaling. When
before-image journaling is selected, the system administrator can specify
several tunable items, including the following:
BIJ File - The external file used to store the before-images is

referred to as the BIJ file. As part of the database setup, the user
can specify the location of the file (drive and directory) and the
size of the file.
BIJ Buffers - For performance, all BIJ file writes are buffered.
Through SYSGEN, the system administrator specifies the number
of BIJ buffers to be created. If more than one BIJ buffer is available,
then BIJ operations are overlapped (images can be added to one
buffer while a second buffer is being written to disk).
8-2 Global Journaling

BIJ Generations - Within the BIJ file, before-images are grouped
together into generations. A new generation is started after a
system- defined number of before-images or after a system-defined
time interval. When a new generation is started, it becomes the
current generation. Any previous generations will be closed when
all of the database updates associated with the generation have been
physically applied to the database. At the start of each generation,
the system is known to have database integrity.
When a system failure occurs, the system will roll-back the database to
the start of the current generation. Any previous generations that are
still open will also be rolled-back. If After-Image Journaling is active,
then the system will automatically roll-forward the database using
information from this journal.
The result of this combined use of Before-Image and After-Image
Journaling is a database that has logical consistency and contains all
transactions up to the point of the last journal entry written to the
After-Image Journal. For additional information on After-Image
Journaling, refer to Section 8.3 (After-Image Journaling) in this chapter.
For additional information on configuring and using Before-Image
Journaling, refer to Chapter 4 (MSM System Operations) in the
appropriate MSM System Manager’s Guide.

8.2.2 The BIJ Utility
The BIJ utility program stored in the Manager’s UCI is used to handle
the common functions associated with Before-Image Journaling. The
program is menu- driven and follows the same conventions outlined in
Chapter 4 (Utility Programs). The general functions performed by this
utility include:
>D ^BIJ
MSM - Before-Image Journal Utility
Before-Image Journal Functions
1 - Initialize Volume Group for Before-Image Journaling

2 - Show Before-Image Journal Information
3 - Enable Before-Image Journal
4 - Disable Before-Image Journal
5 - Before-Image Journal File Maintenance Options
Select Option:
Refer to Chapter 4 (MSM System Operation) in the appropriate MSM

System Manager’s Guide for a complete description of the BIJ utility.
This chapter includes details on the functions performed by this utility
as well as examples of how to use the utility.

8.3 After-Image Journaling
After-Image Journaling is the method used to record information about
global SET and KILL operations. The information that is captured
during the SET or KILL operation can be stored on a secondary storage
device (i.e., Disk, Floppy Disk, magnetic tape, Disk Cartridge) or the
primary disk device. In the event of a system failure, the after-image
journal can provide the information necessary to automatically
re-process all or part of the global SET and KILL operations that have
occurred since the last system backup. The following sections provide
an overview of the After-Image Journaling functions.
8.3.1 After-Image Journaling Concepts

The system manager has a great deal of flexibility in determining how
global journaling is to be used. MSM allows journaling to be active for
all globals on the system, for a specific UCI in a volume group, for a
specific partition, or for a specific global. When the system decides that
a global is to be journaled, it constructs a journal entry. Journal entries
include the following information:
• The date and time that the global reference occurred
• The name of the UCI and volume group that contains the global
being SET or KILLed
• The name of the UCI and volume group where the job was
running when the SET or KILL command was issued
• Either an S to indicate a SET operation or a K to indicate a

KILL operation
• The internal value of the key, in compressed format,
corresponding to the full global reference.
• The value of the data if the operation was a SET command.
All global SETS and KILLS are stored in chronological order so that in
the event that the journal is used for recovery, the transactions are applied
to the backup database in the proper sequence.
The user can specify on an individual global basis whether or not
journaling is to occur. The global characteristics utility (%GCH) is used
to indicate whether a global is to be journaled. Journaling attributes may
be changed at any time.

The journaling capability is automatically included as part of the MSM
multi-user system. As part of the system startup procedure,
Before-Image, After-Image, and Cross-System Journaling can
automatically be started. Refer to the appropriate MSM System
Manager’s Guide (Generating the MSM System) for additional
information on automatic startup of these functions. When After-Image
Journaling is started, the system manager must indicate to the system
where the journal information will be stored. This is done by indicating
the name directory on disk that contains the journal space.
Before-image and after-image files must be stored on disk as host files.
External devices such as magnetic tape and cartridge tape devices are
not supported for journal files. The MSM system uses a standard naming
convention for after-image journal files. This naming convention stores
the date and time that the file was created as part of the name. This
facilitates the processing of keeping track of the after-image files. To
aid in the process, the system maintains a log of after-image journal files
and their status.
8.3.2 The JRNL Utility

The JRNL utility program stored in the Manager’s UCI is used to handle
the common functions associated with After-Image Journaling. The
program is menu- driven and follows the same conventions outlined in
Chapter 4 (Utility Programs). The general functions performed by this
utility include:
> D ^JRNL
MSM - Journal Utility
Select Journal Option:
1 - Activate (Start) Journaling

2 - Deactivate (Stop) Journaling
3 - Show (Display) Journal Spaces
4 - Configure Journaling
5 - Mark Journal Space as Reusable
6 - Switch to New Journal Space
7 - Restore (Dejournal) From Journal Space
8 - Print a Journal
9 - Cross-System Dejournaling Options
Select Option:

System Manager’s Guide for a complete description of the JRNL utility.

8.4 Cross-System Journaling
The Cross-System Journaling feature of MSM allows a site to maintain
a secondary system (i.e, a hot standby backup system) that can take over
processing in the event of a failure of the primary system. To achieve
this, two systems are connected through a network using the optional
Distributed Data Processing (DDP) feature of MSM (i.e., the MSM-NET
package). As an alternative to the DDP feature of MSM, two systems
can be connected using the Network File Services (NFS) feature of Unix.
Once the two systems have been connected, the Cross-System Journaling
feature can be used. With this feature, after-image journal entries from
the primary system are automatically applied to the database of the
secondary system through the network. The time interval for applying
these updates can be specified by the user.
As an added advantage, the secondary system can be used to perform
database backup functions. While the secondary system is off-line,
journal entries are accumulated on the primary system. When the
secondary system again becomes available, the stored journal entries
will be applied. Refer to Chapter 4 (MSM System Operations) in the
appropriate MSM System Manager’s Guide for additional information
on Cross-System Journaling.
8.4.1 Cross-System Journaling Concepts

When Cross-System Journaling is enabled, system startup automatically
creates a background job to perform the Cross-System Journaling
functions. Periodically, at a time interval specified by the system
administrator, the background job will wake up and perform various
functions. It closes the current journal file, opens a new journal file, and
copies the contents of the closed file to the backup system.
In the event that the backup system is not available, the copy operation
will be suspended until the backup system is again available. When the
system becomes available, the background job will transfer all journal
entries (even if they span multiple journal files) that have occurred since
the last successful transfer to the backup system.
Using this technique, on MSM-PC and MSM-PC/PLUS systems where
there is no multi-user host operating system, the backup system can be
shutdown to perform database maintenance functions (i.e., backup,
compress, etc.). Then, when the system is started again, it will
automatically catch up to the current transaction.

8.4.2 Controlling Cross-System Journaling
The JRNL utility program stored in the Manager’s UCI is used to handle
the common functions associated with Cross-System Journaling. The
Cross-System Journaling functions are contained in a sub-menu of the
main menu. The program is menu-driven and follows the same
conventions outlined in Chapter 4 (Utility Programs). The general
functions performed by this utility include:
> D ^JRNL
Select option: 9 - Cross-System Journaling Options
Cross System Journaling Options:
1 - Cross System Journaling Parameters

2 - Journaling Volume Group Assignment Table
3 - Activate Cross System Journaling
4 - Deactivate (Stop) Cross-System Journaling
Select Option:

System Manager’s Guide for a complete description of the JRNL utility.

8.5 On-Line Backup Of A Database
To guard against catastrophic unrecoverable disk failures, the system
manager should maintain copies of each database (i.e., volume group)
on some type of external backup device (magnetic tape, DAT tape,
removeable disk, etc.). In the past, system administrators were forced
to take the system down or to restrict the database to read-only access
while the backup was performed. This requirement limited system
availability to users.
Using the On-Line Backup (OLB) feature of MSM, the system
administrator can now create a backup image of a database (i.e., volume
group) while users are logged onto the system and while database updates
are taking place. This improves system availability to users and at the
same time provides the system administrator with greater flexibility in
scheduling backup operations.
8.5.1 On-Line Backup Concepts

In order to accommodate the various backup requirements that may exist
at different sites, MSM provides three forms of on-line backup. In
particular, MSM supports the following backup types:
• Full Backup - Copies the entire database to an external backup
device (e.g., cartridge tape, DAT tape, etc.)
• Serial Incremental Backup - Copies database blocks that have
been modified since the last full or incremental backup to an
external backup device.
• Cumulative Incremental Backup - Copies database blocks that
have been modified since the last full backup to an external
backup device.
During any of these backup operations, updates to the database are
permitted. Therefore, to achieve a consistent backup, the system must
keep track of modifications to the database while the backup is running.
It does this by writing each block that is modified to the database and
to an auxiliary file referred to as a spill file. This spill file is created at
the start of the backup process. After the database backup completes,
the spill file will contain an image of every block that was modified
during the backup.

The actual on-line backup is performed using any of the various backup
utilities that are provided with the host operating system. The actual
backup consists of copying the database to external backup media by
invoking the system backup utility. When this completes, the spill file
is appended to the end of the external backup media. Together, the
database file and the spill file contain an image of the database as it
existed at the end of the backup process.
8.5.2 The OLB Utility

The OLB utility program stored in the Manager’s UCI is used to handle
the common functions associated with on-line backup of the database.
The program is menu-driven and follows the same conventions outlined
in Chapter 4 (Utility Programs). The general functions performed by
this utility include:
> D ÔLB
MSM - On-line Backup Utility
On-line Backup Functions:
1 - Full backup of a volume group

2 - Incremental backup of a volume group
3 - Cancel an interrupted backup
4 - Restore a volume group
5 - Manual restore options
6 - Define backup options
Select Option:

System Manager’s Guide for a complete description of the OLB utility.
8.6 Summary
While MSM does not provide complete fault tolerance in the strict sense
of the term, it does allow high-availability systems to be constructed
using relatively inexpensive and readily available off-the-shelf
components. In most applications, systems constructed using these
features will provide the degree of system availability required by the
users. In addition, the MSM resilient system features can be augmented
by hardware components such as mirrored disks, RAID disk arrays, UPS
devices, etc. These features will serve to further increase system
availability.

APPENDIX A
ERROR CONDITIONS
This appendix describes methods for trapping errors during program
execution and error messages generated during program execution.
A.1 Trapping MSM Errors

Two mechanisms exist within MSM to deal with errors that occur during
execution of a routine--the $ZERROR and the $ZTRAP special
variables. Whenever an error occurs during execution, descriptive
information about the error can be found in the $ZERROR special
variable. This information is available to the program only if an error
processing routine has been established in the $ZTRAP special variable.
If the $ZTRAP variable has not been established, then the routine is
terminated and descriptive information about the error is displayed on
the terminal that initiated the job. If the job was initiated from
programmer mode, the terminal is returned to programmer mode after
the information is displayed. If the program was not initiated from
programmer mode, the user is logged off after the information is
displayed. The format of this descriptive information is:
<Code>Offset^RouName:Cmnd:Arg:Major:Minor:AddInfo Line
In this display, Code is the error code (See Table A-1), 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 internal
error numbers (See Table A-2), Offset is the location (i.e., relative line
number or label+offset) within the routine, RouName is the name of the
routine, and Line is a reprint of the line in error.
The Cmd and Arg parameters are only maintained by the system when
the debugger (i.e., %DEBUG) is active. Refer to the MSM Utility Manual
for additional information on the %DEBUG utility. Finally, AddInfo
contains additional information about the error. It is not maintained for
all types of errors. When it is maintained, it provides relevant
information about the error. For example, for a disk error (i.e.,
<DKHER>) it is the block number that received the error.
Error Conditions A-1

The system also displays a trace back of the execution path whenever
an untrapped error occurs. For each nesting level (i.e., DO or XECUTE
of a program), it shows the name of the calling routine, the name of the
called routine, and how the routine was called. For commands entered
directly in programmer mode, this information is displayed on the
terminal at the time that the error occurs.
To trap errors, the routine must establish the location of an
error-processing routine in the $ZTRAP special variable. The location
of the error-processing routine must be specified as a full program
reference, that is, a line reference followed by a circumflex (^) and the
routine name, a circumflex (^) followed by the routine name, or just a
label in the current routine.
When an error occurs, the system internally resets the $ZTRAP to null
and issues a GOTO command to the location contained in $ZTRAP.
Active FOR commands are terminated. Prior to entering the
error-processing routine, the $ZERROR special variable is set to the
entire message, except for the Line, i.e.,
<Code>Offset^RouName:Cmnd:Arg:Major:Minor:AddInfoLine.
The $ZTRAP special variable must be reset by the program if future
errors are to be trapped.
A-2 Error Conditions

A.2 MSM Error Messages
Table A-1 below lists the various error messages that are produced by
the MSM system and gives a description of what causes the error.
Table A-1 - MSM Error Messages
Message Explanation
<ASYNC> Indicates 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 SYSGEN or the %MODESET utility. The
type of error is indicated in the additional information
field of $ZERROR. This is a number formed by
major*256*+minor.
<BADCH> An invalid Kanji or Shift-Jis character has been

encountered.
<BKERR> Indicates the interpreter has 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. Execution of the program can
be resumed using the ZGO command.
<CLOBR> Indicates an attempt has been made to overlay the

current routine by issuing a ZLOAD, ZREMOVE, or
ZINSERT command from within the routine.
<CMMND> Indicates the interpreter encountered an illegal or

undefined command.
<DDPER> Indicates a Distributed Data Processing (DDP) server

error has occurred.
<DIVER> Indicates an attempt has been made to divide a

number by zero.

Message Explanation
<DKFUL> Indicates 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 has been
lost. This can result in database corruption.
<DKHER> Indicates 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 which
is outside the physical bounds of the disk.
<DKRES> Indicates that 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> Indicates that a block read in from the disk was not
the type expected by the system or the block’s internal
structure was invalid. The latter can occur if the global
database is corrupted by a hard system failure (e.g.,
a power failure) or hardware malfunction (e.g., an
unrecoverable disk error on a write operation).
<DPARM> Indicates invalid use of parameter passing.
<DSCON> Indicates the telephone line associated with the

current device has disconnected.
<DSTDB> Indicates a network communications link has failed

during a Distributed Data Processing (DDP) data
transfer.
<EXPER> Indicates an exponentiation error has been detected.
<FUNCT> Indicates the interpreter has encountered an

undefined function or that a function has been used
improperly.

Message Explanation
<INDER> Indicates the interpreter has encountered illegal or
incorrect use of the indirection operator.
<INHIB> Indicates that access to a database through the

network has failed because database reads or writes
are inhibited on the specified machine.
<INRPT> Indicates the operating system has received an

interrupt (i.e., BREAK) from the terminal while the
BREAK function was enabled (i.e., a BREAK 1
command was in effect).
<ISYNT> Indicates an attempt has been 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 inserting 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.
<LCNSE> Indicates the number of jobs exceeds the license limit.
<LINER> Indicates a reference has been made to a line which

does not exist within the body of the current routine.
<MAPER> Indicates a disk block being freed is already marked

free in the corresponding MAP block.
<MERGE> Indicates a MERGE command has been issued in

which one operand is a descendent of the other
operand.
<MINUS> Indicates the interpreter found a negative number or

zero when it was expecting a positive number.
<MODER> Indicates an attempt has been made to access the

device in a mode that is not consistent with the
parameters specified when the device was opened.

Message Explanation
<MSMCX> Indicates the in-memory communication path
between MSM tasks has been interrupted.
<MTERR> Indicates an error has occurred during an Input or

Output operation to a magnetic tape device.
<MXMEM> Indicates a memory address specified as an argument

to the VIEW command or $VIEW function is outside
the limits allowed by MSM.
<MXNUM> Indicates the value of a number is greater than the

largest number allowed by the system.
<MXSTR> Indicates the value of string exceeds the maximum

length that is allowed by the system. The maximum
is 255 characters (or 511 as an option) for global
variables, and 4092 characters for local variables.
<NAKED> Indicates an access to a global variable using the

naked indicator is invalid. This can occur if the naked
indicator was not previously set by a global reference
or if the previous global reference did not include
subscripts.
<NODEV> Indicates the system has intercepted an attempt by the

program to OPEN a device which has not been
defined to the system, or an attempt to READ from
a terminal type device which is defined as an
OUTPUT ONLY device.
<NOJRN> Indicates an attempt was made to journal a global in

single-user mode.
<NOPEN> Indicates the system has intercepted an attempt by the

program to USE a device which has not been
previously OPENed by the program.

Message Explanation
<NOPGM> Indicates a reference was to a program that does not
exist in the current UCI’s routine directory. This can
also occur when referencing a library routine (i.e., %
routine stored in manager’s UCI) that does not exist.
<NOSYS> Indicates a reference to a non-existent system through

Distributed Data Processing (DDP) or to a
non-existent volume group through an extended
global notation has been attempted.
<NOUCI> Indicates a reference to a non-existent UCI through

an extended global notation has been attempted.
<PCERR> Indicates the interpreter found an illegal post-

conditional or the post-conditional argument is
invalid.
<PGMOV> Indicates there is insufficient memory left within the

partition to complete the requested operation.
<PLDER> Indicates the routine 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 > Indicates an attempt to access a protected global

which the user is not authorized to access. It can also
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> Indicates 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 (i.e., global name, parentheses,
subscripts, and commas) is greater than 255.

Message Explanation
<STKOV> Indicates the system stack has overflowed as a result
of nested indirection or a program loop.
<SYNTX> Indicates the interpreter has encountered a syntax

error in the line being executed.
<SYSTM> Indicates the MSM system has encountered an

internal error. The precise error message, including
major/minor error numbers, should be reported to
Micronetics.
<TPROC> Indicates a transaction-processing error has occurred.
<UNDEF> Indicates the operating system has intercepted an

attempt to reference a non-existent local or global
variable.
<VWERR> Indicates an attempt has been made to access a device

in shared VIEW buffer mode without ownership of
the VIEW device (i.e., device 63). This error also
occurs if the VIEW device is closed before the device
that was opened in shared VIEW buffer mode.
<ZCALL> Indicates that the function name specified on a

$ZCALL does not exist or the parameters specified
are invalid.
<ZCERR> Indicates the system has encountered an error while

processing in the $ZCALL module of the system.
This indicates an error in the user-supplied code.
<ZSAVE> Indicates that one of the lines in the routine being

compiled is too large to fit in the disk buffer. The
line should be broken into two or more lines to correct
the problem.
<ZSVGP> Indicates a ZSAVE command was issued, but the

volume group was not enabled for any p-code type.

A.3 MSM Error Numbers
Table A-2 below lists the error numbers generated by MSM and gives
a description of what causes the error.
Table A-2 - MSM Error Numbers
Major Minor Explanation

1 - Command type errors
1 Unrecognized command
2 - Argument type errors
1 Missing parenthesis
2 Missing or bad colon
3 Missing or bad equals
4 Missing or bad local variable
5 Missing or bad global variable
6 Missing or bad function
7 Missing or bad routine name
8 Missing or bad routine label
9 Missing or bad routine offset
10 Indirect argument error
11 Argument condition error
12 Bad argument delimiter
13 Bad command
3 - Expression type errors
0 Bad special variable name

1 Bad system function
2 Bad local variable
3 Bad global variable
4 Bad string constant
5 Bad numeric constant
6 Unbalanced parenthesis
7 Invalid syntax in term
8 Bad operator
9 Bad delimiter

4 - Reference type errors
0 Undefined local variable

1 Undefined global variable
2 Undefined label
3 Undefined routine
4 Invalid naked reference
5 Non-existent device or no memory for window
6 Unsubscripted local reference required
7 Variable reference required (no expressions)
8 ZLOAD usage error during routine execution
9 Undefined UCI reference
10 Attempted ZInsert of an invalid line
11 Unknown data type
12 Missing function parameter
13 Undefined system in cross-system reference
14 Global access protection violation
15 Volume group protection violation
16 ZCALL 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 descendent of other
28 Nested mnemonic namespace request

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 Maximum memory
7 String value required
8 Indirection resulted in null value
9 Indirection included more than name
10 Selected partition not active ($VIEW)
11 Invalid VIEW or $VIEW argument
12 Function parameter out of range
13 Invalid subscript
14 Device not open for access type attempted
15 Reserved For Future Use
16 Not allowed to write block 0
17 Invalid use of shared mode on VIEW buffer
18 Raised zero (0) to non-positive power
19 Raised negative number to non-integer power

6 - Environmental errors
0 Break key depressed
1 Attempt to exceed partition size
2 HALT command executed
3 LOCK Table full
4 BREAK command executed
5 Expression stack overflow
6 System stack overflow
7 Old p-code needs to be saved
8 Circuit error during DDP operation
9 Reserved for DDP internal use
10 DDP Database access inhibited
11 MSM to mumsm communication failure
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 load exceeded 50 p-code blocks
26 System out of memory
7 - Disk type errors
0-32 Block type mismatch, number is expected type
33 Hardware disk I/O error
34 Disk 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 to driver
40 Attempt to allocate block in reserved area

APPENDIX B
THE MSM PROGRAM EDITOR

This appendix describes the MSM Program Editor, its function, its
features, and instructions for its use.
B.1 Overview of the Program Editor

The MSM program editor was designed and implemented for
Micronetics Design Corporation by the Medical Informatics Research
Laboratory. It has been designed to assist the MUMPS programmer in
creating and editing programs. The editor is stored entirely in a global
(i.e., the ^% global) and therefore does not occupy any user program
space. Since it is stored in a global beginning with a percent (%) sign,
it can be accessed from any UCI. All variables used by the editor begin
with a percent (%) sign and are killed upon exit from the editor.
To invoke the editor, execute the code stored in the ^% global. This is
done by entering the following line of MUMPS code.
X ^%
If the partition is empty, then the editor allows you to create a new routine.
To do this, the editor prompts with the following:
No routine in partition
Enter label for first line of new routine:
The response that is entered is used to create the first line of the routine
with the label you specify. The editor then responds with the following
prompt:
Edit line:
The editor then waits for the user to enter a response. If a default line
reference exists, the editor displays the following prompt:
Edit line: DefLine //
The MSM Program Editor B-1

In this example, DefLine is the default line reference (i.e., the last line
that was edited). Any one of the following four responses can be given
to this prompt:
1. a line reference that identifies a specific line to be edited;
2. a period followed by an alpha character to execute one of the
special functions of the editor;
3. a question (?) mark to obtain a list of the options and special
functions that are available; or,
4. a period (.) with no other characters following it to exit the editor.
The program editor, as distributed with MSM, assumes that the output
device is a CRT, that the screen has a width of 80 characters, and that
there are 24 lines which can be used for display purposes. Whenever
the program editor displays information on the screen (i.e., in response
to a Display command or in response to a question mark), it pauses when
the screen becomes full. Whenever the program editor pauses because
of a full screen condition and there is more information to display, it
prompts with "< >". In response to this prompt, RET can be entered to
have the editor display the remaining information, or any of the responses
that are valid for the "Edit line: " prompt can be entered.
B.2 Editing a Specific Program Line

A specific line within the program may be edited by entering a line
reference in one of the following forms:
1. a line label to indicate the specific line to be edited (e.g., LOOP,

GO);
2. a line label, plus or minus a relative offset (e.g., LOOP+2,

LOOP-1);
3. a null response (e.g., a carriage return) to indicate the last line
that was edited;
4. a plus or minus offset to indicate the last line edited, plus or
minus an offset (e.g., -3, +2, etc); or,
5. a single plus or minus sign to indicate the last line edited, plus
or minus 1 (e.g., +,-).
B-2 The MSM Program Editor

Once a valid line has been identified, the editor displays the line and
prompts the user with the following:
Replace: In response to this prompt, enter any character string

contained in the line (i.e., F I=1:1, D ^LOADER). The
tab character, which is used to separate the line label from
the line body, is stored internally as a space and must be
referenced as a space. The three characters ’END’ can be
entered to indicate that information is to be appended to
the end of the line. Or, three periods (i.e., ’...’) can be
entered to indicate a range of characters. For example:
ABC...HIJ to indicate all characters from ’ABC’ to
’HIJ’, inclusive.
ABC... to indicate all characters from ’ABC’ to the
end of the line, inclusive.
... to indicate the entire line.
After entering the replacement information, the editor then responds

with the following prompt:
"With:" In response to this prompt, enter

the characters which are to replace the
string identified by the ’Replace’ question.
A null response (i.e., a carriage return)
deletes the original characters. After each
response, the editor checks to ensure that
the new line being created does not have a
length greater than 255 characters. If this
occurs, an error message is displayed and
the line is left unchanged.
The editor continues to ask for ’Replace:’ and ’With:’ strings until a null
response (i.e., a carriage return) to the ’Replace:’ prompt is entered.
When a null response is entered, the editor returns to the "Edit line: "
prompt.

B.3 Special Functions
The MSM program editor supports a wide variety of special functions
which facilitate the development and maintenance of MUMPS
programs. To invoke one of the special functions, enter a period (.)
followed by the alpha character which identifies the function, in response
to the ’Edit line: ’ prompt. The special functions supported by the editor
are listed in the table below.
Table B-1 - Program Editor Functions
Entry Code Explanation

.A Provides an alternate mode for editing lines, allowing
the user to move the cursor to the appropriate location
in the line and replace, insert, or delete characters. The
original line is displayed and the cursor is positioned
under the first character in the line. The cursor is
moved to the appropriate spot on the line by entering
one of the following characters: a space to move the
cursor to the next punctuation mark, a period (.) to
move the cursor to the next character, or a Backspace
(CTRL/H) to move the cursor back one character.
After positioning the cursor, characters can be inserted
by entering an ’I’ followed by the characters, replace
characters by entering an ’R’ followed by the
replacement characters, or delete characters by
entering a ’D’ for each character to be deleted. The
editor continues to prompt the user in this manner until
a null response is entered.
.B Breaks a line into two separate lines after a specified

character string. The editor ensures that the new line
to be created is a valid MUMPS line by checking for
a beginning space character. The user is prompted for
the line to be broken and the character string after
which the break is to occur.

.C Changes every occurrence of a specified character
string to another character string within a specified
range of lines. Each line that is found to contain the
string is displayed after the change has been made. If
the change results in a new line with a length greater
than 255 characters, an error message is displayed and
the line is not changed. The user is prompted for the
search string, the replacement string, and the starting
and ending lines for the search.
.D Displays a specific range of lines within the program.

The editor displays the lines so that the label, if it exists,
is in columns 1-8 and the next 70 characters of the line
in columns 10-79. If the program line is longer than
70 characters, the editor displays the remaining
characters in units of 68 characters. These are
displayed on succeeding lines with periods in columns
1-9 and the text in columns 12-79. The user is
prompted for the starting and ending lines to be
displayed.
.DA Displays the entire program in the same format used

for displaying a range of lines.
.E Expunges a program from the current UCI. This

function is equivalent to clearing the program buffer
(i.e., a ZREMOVE command with no operands) and
then saving over the existing program (i.e., a ZSAVE
command with the program name as the operand).
Both result in the permanent and irreversible deletion
of the program. The editor prompts the user for
verification that the user really does want to delete the
specified program. The editor also kills the
appropriate node in the ÛTILITY global (see the .F
function for information on the ÛTILITY global.

.F Files the program. The editor checks to make sure the
name of the routine (i.e., the $ZNAME Special
Variable) and the label of the first line in the routine
are the same. If they are not identical, the editor
prompts the user to verify that the program should be
stored using the current program name. If the user
does not respond with one or more characters of the
word ’YES’, or there is no current routine name, the
editor prompts for the name to be used to store the
program. The editor maintains a list of all programs
in a UCI that have been saved through the editor. The
program name is stored in global
ÛTILITY("%RD",RoutName) as part of the filing
operation. Also, when a program is filed, it is checked
for syntax errors and any errors found are displayed.
.FX Files the program and exits the editor. This function
is identical to the .F function; however, upon
completion, it exits the editor.
.G Retrieves lines of code stored in the ^ZUT global and

inserts them after a specified line in the current
program. This function retrieves lines previously
stored using the .P or .M function. The user is
prompted for the name of the storage area used when
the lines were saved and the location within the current
program where the retrieved lines are to be inserted.
The lines contained in the storage area are not altered
in any manner so that the user may retrieve the lines
in multiple programs.
.I Inserts lines at a specified location in the current

program. The editor accepts either a tab character or
a space character between the line label and the line
body of the line being inserted. The editor continues
to accept lines to be inserted until a null line is entered.
The user is prompted for the line within the current
program after which the new lines are to be inserted.

.J Joins two lines together to form a new line. The newly
formed line is checked to ensure that the length does
not exceed 255 characters. If it does, an error message
is displayed and no changes are made to the lines which
were to be joined. The user is prompted for the two
lines to be joined. The first line is used for the location
of the line created by the joining process, and the
second line is deleted after the joining. The line created
by the joining process is displayed, and the user is
prompted to verify that it is correct before any action
occurs.
.M Moves a series of lines from one location in the

program to another location. At the completion of the
move, the original lines are deleted. The user is
prompted for the starting and ending location of the
lines to be moved and the line within the program after
which the moved lines are to be inserted. The program
lines are stored in the ^ZUT global during the move.
They are stored in the same format used by the .P
function. Thus, they can be recovered with the .G
function if the move should fail after the lines have
been deleted from the program.
.P Places a specified range of lines into a temporary

storage area. This option allows the user to
temporarily store program lines in a global so that they
can be copied to another location in the current
program or transferred to a different program. The
lines of code are stored in the ^ZUT global in the form
^ZUT($I,TempName,LineNum). The original lines
of code are not changed or deleted. The user is
prompted for the name to be used to store the lines of
code, and for the starting and ending lines of code to
be stored.

.R Removes a specified range of lines from the current
program. The user is prompted for the starting and
ending location for the range of lines to be deleted.
.S Searches a specified range of lines and identifies the

lines containing a specified character string. Each line
that is found to contain the specified character string
is displayed. The user is prompted for the character
string to be used in the search and the starting and
ending lines within which the search occurs.
.V Displays variable defaults within the program editor;

the defaults can be modified for the duration of the
session. These include the terminal width (%WD),
terminal length (%SL), and the top-of-form sequence
(%TF). These variables can be permanently changed
by editing line 0 (zero) in program ZEDITOR and then
reloading the program editor.

APPENDIX C
LOADING APPLICATIONS
This appendix describes the process for installing Application Packages
that have been supplied by Micronetics Design Corporation. The process
is the same regardless of the hardware configuration of the system where
the package is to be installed.
C.1 Overview
Application packages supplied by Micronetics are distributed on floppy
disk (5.25-inch) or removable disk, cartridge tape, or magnetic tape
depending on the configuration of the user’s system. Each application
package is supplied with user documentation as well as instructions on
how to initialize the package, if required. The application package is
distributed in a format that is designed to be self-loading. The actual
loading of the package is initiated using the %PACKAGE utility
program. Upon completion of the process, all appropriate routines and
globals are loaded.
C.2 Loading the Application into a UCI

The first step when installing an application package is to determine the
UCI that the package is loaded into. For additional information about
UCIs, refer to Chapter 9 (Generating the System). Care should be taken
to ensure that the routines and globals that are supplied with the
application package do not replace or conflict with any routines and
globals that may already exist in the UCI. After determining which UCI
is used for the application package, logon to the selected UCI in
programmer mode and enter the following command:
DO ^%PACKAGE
This begins the process of loading the application package into the
current UCI. The system prompts for the device number and file name
associated with the package. For additional information on selecting
the appropriate input device, refer to Chapter 4 (Using Peripheral
Devices). The system prompts you for all necessary information. In
response to any prompt, a question mark (?) can be entered to obtain
additional information.
Loading Applications C-1

C.3 Initializing the Application
In most cases, when an application package is installed on the system,
some type of initialization process must be performed. This process
may include defining terminal types, identifying the host operating
system, and supplying other information describing the operating
environment. The initialization process is unique for each different
package. Therefore, refer to the specific instructions supplied with the
application package you are loading.
C.4 Sample Installation

The following is an example showing how %PACKAGE is used to install
the VA FileMan system for the first time. It is assumed that the floppy
disk drive on the PC is drive A.
>D ^%PACKAGE RET
This routine loads any MSM application package distribution
Enter input device <HFS>: 47 RET Magnetic Tape Device

Parameters <ASU4>: RET
Block Size <2048>: RET
THIS PROGRAM WILL INSTALL FileMan VERSION 19.00
THIS PROGRAM WILL LOAD ROUTINES AND GLOBALS INTO THIS UCI AND THE
MANAGER UCI.
DO YOU WANT TO LOAD THE SYSTEM AT THIS TIME <Y> RET
DO YOU WISH TO INSTALL THE MANAGER ROUTINES AND GLOBALS <Y> ? RET
ENTER ’YES’ IF YOU HAVE NOT PREVIOUSLY INSTALLED THIS APPLICATION.

ENTER ’NO’ IF YOU HAVE PREVIOUSLY INSTALLED THIS PACKAGE AND DO NOT
WANT TO REINITIALIZE THE MANAGER UCI. ENTER ’?’ TO GET THIS
MESSAGE.
DO YOU WISH TO INSTALL THE MANAGER ROUTINES AND GLOBALS <Y> Y RET
LOADING FMR1900 ROUTINES INTO THE MGR UCI...
%DT %DTC %IS %RCR %ZIS %ZIS1 %ZIS2

%ZISETUP
DO YOU WISH TO INSTALL THE HOST ROUTINES AND GLOBALS <Y> Y RET
C-2 Loading Applications

LOADING FMR1900 ROUTINES INTO THE FMR UCI...
DI DIA DIA1 DIA2 DIA3 DIB DIBT

DIC DIC1 DICATT DICATT0 DICATT1 DICATT2 DICATT22
DICATT3 DICATT4 DICATT5 DICATT6 DICD DICE DICE0
DICE1 DICE2 DICE3 DICE4 DICE7 DICM DICM1
DICN DICN1 DICOMP DICOMP0 DICOMP1 DICOMPX DICOMPY
DICOMPZ DICQ DICQ1 DICR DICRW DID DID1
DID2 DIDH DIDT DIDTC DIDX DIE DIE0
DIE1 DIE2 DIE9 DIED DIEZ DIEZ0 DIEZ1
DIEZ2 DIFROM DIFROM0 DIFROM1 DIFROM2 DIFROM3 DIG
DIH DII DIIS DIK DIK1 DIL DIL0
DIL1 DIL2 DILL DIM DIM1 DIM2 DIM3
DIM4 DINIT DINIT0 DINIT1 DINIT2 DINIT21 DINIT22
DINIT23 DINIT24 DINIT3 DINIT4 DINIT41 DINIT5 DINIT6
DINTEG DIO DIO0 DIO1 DIO2 DIO3 DIO4
DIOS DIP DIP0 DIP1 DIP2 DIP22 DIP3
DIP4 DIP5 DIQ DIQQ DIQQQ DIRCR DIS
DIS0 DIS1 DIT DIT0 DIT1 DIT2 DITP
DITR DITR1 DIU DIU1 DIU2 DIU3 DIV
DIVR DIWE DIWE1 DIWE2 DIWE3 DIWE4 DIWE5
DIWP DIWW DIX DIXC ZIINI001 ZIINI002 ZIINI003
ZIINI004 ZIINI005 ZIINI006 ZIINI007 ZIINI008 ZIINI009 ZIINI010
ZIINI011 ZIINI012 ZIINI013 ZIINI014 ZIINI015 ZIINI016 ZIINI017
ZIINI018 ZIINIT ZIINIT1 ZIINIT2
PACKAGE LOAD COMPLETED
RUNNING INITIALIZATION ROUTINES FOR MGR UCI...

THIS ROUTINE INITIALIZES THE DEVICE FILE WITH CURRENT PORT NUMBERS
OK? Y RET
ALL SET UP!

RUNNING INITIALIZATION ROUTINES FOR FMR UCI...
THIS VERSION OF ’ZIINIT’ WAS CREATED ON OCT 22,1989

(AT MICRONETICS (MDC) BY FileMan V.19.00)
TO SET UP FOR YOU THE FOLLOWING FILES:
3.2 TERMINAL TYPE (INCLUDING DATA)

3.5 DEVICE
FIRST, I’LL FRESHEN UP YOUR FILE MANAGER....
FileMan V.19.00
SITE NAME: COMPUTER CENTER RET
Loading Applications C-3

SITE NUMBER: 27 RET
...EXCUSE ME PLEASE, THIS MAY TAKE A FEW MOMENTS....................

......................................
TYPE OF MUMPS SYSTEM YOU ARE USING: MICRONETICS RET
INITIALIZATION COMPLETED!
NOTE: THIS PACKAGE ALSO CONTAINS PRINT TEMPLATES
NOTE: THIS PACKAGE ALSO CONTAINS OPTIONS
ARE YOU SURE EVERYTHING’S OK? Y RET (YES)
...UH OH, JUST A MOMENT PLEASE...........................

...................................
OK, I’M DONE.
NO SECURITY-CODE PROTECTION HAS BEEN MADE
>
C-4 Loading Applications

APPENDIX D
FULL SCREEN EDITOR

This appendix describes the command language of the Full Screen Editor
and how to create new programs and edit existing programs. Note that
the full screen editor only supports ANSI compatible terminals.
D.1 Invoking the Editor

The full screen editor of MSM is a comprehensive program editor that
allows programs to be created and edited in a visually informative and
user friendly manner. To invoke the full screen editor, enter the
following MUMPS command.
X ^%E
When invoked, the editor first looks to see if a program is loaded into
the users work-space. If there is one, the editor assumes that it is the
program to be edited and it displays the first part of the program. If there
is no program in the work-space, the editor responds with the following
prompt:
EDIT PROGRAM NAME:
In response to this question, enter the name of the program to be edited
followed by the RET key. Or, you can enter a question mark followed
by RET to obtain HELP information or ’^D’ to obtain a list of existing
programs. If the program name you enter exists, the program source
code is retrieved and displayed, the cursor is positioned at the top left
corner of the screen, and the editor waits for a command. If the specified
program does not exist, the editor prompts with the following:
CREATE A NEW PROGRAM? <Y>:
This prompt is to make sure that you really do want to create a new
program. If you inadvertently misspelled the program name or for some
other reason do not want to create a new program, enter N followed by
the RET key. This returns you to the EDIT program name prompt. If
you are creating a new program, enter Y followed by the RET key. You
could also just enter RET since the default response to this question is
Y.
Full Screen Editor D-1

D.2 Editor Commands
The MSM Full Screen Editor is a command oriented editor that has been
designed specifically for MUMPS programs. All commands are entered
using either a single character, a double character sequence, a number,
or a symbol. The characters may be upper-case or lower-case (i.e., A
and a are equivalent). In addition, commands can be preceded with a
number to indicate repetition and some commands are followed by an
argument. Each command indicates the type of function to be performed
by the editor. The editor performs each command as it is entered and
then waits for the next command. To enter a command, type the single
character, double character, number, or symbol of the command. Do
not enter RET after the command.
The editor commands can be broken down into groups according to the
functions they perform. The groups include cursor movement, scrolling,
editing, mark, delete, search, transfer/copy, and miscellaneous
commands. The following sections describe each of the commands
supported by the editor.
D.3 Cursor Movement Commands

The cursor commands are used to position the cursor to a specific location
on the screen. This is necessary since most editor commands perform
some action on the current screen location. The cursor commands
themselves do not modify the program source. Cursor movement can
be controlled by the four cursor keys: up arrow, down arrow, left arrow,
and right arrow. In addition, the cursor movement commands shown in
Table D-1 below can be used:
Table D-1 - Cursor Movement Commands
Command Function
Backspace Moves the cursor one position to the left. If the cursor
is in column 1 of the screen, the terminal bell rings and
no action takes place.
H Same function as Backspace
D-2 Full Screen Editor

Command Function
J Moves the cursor down to the next line of MUMPS
code. The horizontal location of the cursor is not
altered unless it is beyond the end of the new line. In
that case, the cursor is positioned to the end of the next
line. If the cursor is on the last line of the screen when
this command is entered, the screen scrolls up one line,
and the cursor stays on the last line of the screen.
K Moves the cursor up to the previous line of MUMPS

code. The horizontal location of the cursor is not
altered unless it is beyond the end of the new line. In
that case, the cursor is positioned to the end of the
preceding line. If the cursor is on the first line when
this command is entered, the screen scrolls down one
line, and the cursor stays on the first line.
L Moves the cursor right one character position. If the

cursor is at the end of the line when this command is
entered, the terminal bell rings and no action takes
place.
W Moves the cursor to the beginning of the next word or

symbol.
SPACE Moves the cursor right one character position. If the

cursor is at the end of the line when this command is
entered, the terminal bell rings and no action takes
place.
TAB Moves the cursor ten (10) character positions to the

right. If this would move the cursor outside of the
body of the line, the cursor is positioned to the last
character of the line.
0 (zero) Moves the cursor to the first character of the label if

the cursor is positioned within a label. Otherwise, it
positions the cursor to the first position of the body of
the line.

Command Function
$ Moves the cursor to the last character of the line of
MUMPS code. If the cursor is already positioned to
the last character of the line, no action takes place. If
the cursor is positioned before the last character of a
line label when this command is entered, then rather
than moving to the end of the line, the cursor moves
to the last character of the label.
RET Moves the cursor to the first character of the label of

the next line of MUMPS code. If there is no label on
the line, it positions the cursor to the first character of
the line where the label would normally be found. If
the cursor is on the last line of the program when this
command is entered, the screen scrolls up one line.
Fx Moves the cursor to the next occurrence of the

character x where x is supplied by the user. If the
character does not exist in the string from the cursor
position to the end of the line, the terminal bell rings
and no action takes place.
; Moves the cursor to the next occurrence of the last

character specified on the F command. If the character
does not exist in the string from the cursor position to
the end of the line, the terminal bell rings and no action
takes place.
nG Moves the cursor to the relative line number specified

by the value n. If n is omitted, the cursor moves to the
last line of the program.
Cursor movement commands can be entered from any location on the

screen. If the cursor is on the top line of the screen or the bottom line
of the screen and the cursor is moved beyond the edge, it wraps around
to the opposite edge. For example, if the cursor is on line 1 of the screen
and the programmer presses the K key, the cursor moves to the same
column of the last line on the screen.

D.4 Scrolling Commands
Scrolling commands control the display of the MUMPS program on the
screen. The editor always displays a line of the program completely.
When scrolling motions are made, it is always done in full lines of
MUMPS rather than physical lines on the video display. Table D-2
below shows the commands that can be used to scroll the program up
and down and to re-display the program.
Table D-2 - Scrolling Commands
Command Function
CTRL/E Scroll the screen up one line. This causes the next line
into the program to be displayed on the bottom of the
screen.
CTRL/D Scroll the screen up one half screen. This moves the
line closest to the middle of the screen to the top of the
screen and display as many additional lines of program
that fits on the screen.
CTRL/F Scroll the screen up one full screen. This moves the
last line of the display to the first line and display as
many additional lines of the program that fits on the
screen.
CTRL/Y Scroll the screen down one line. This causes the line
that immediately precedes the first line on the screen
to be displayed at the top of the screen.
CTRL/U Scroll the screen down one half screen. This moves
the line closest to the middle of the screen to the bottom
of the screen and display as many previous lines of
program that fit on the screen.
CTRL/B Scroll the screen down one full screen. This moves
the first line of the display to the last line and display
as many previous lines of the program that fit on the
screen.

Command Function
CTRL/G Display the current location in the program. This
writes a message to the last line of the screen that shows
the name of the program, the number of lines in the
program, and the current relative position within the
program.
CTRL/L Re-display the current screen. This can be used to

refresh the screen in the event of transmission errors.
CTRL/R Re-display the routine from the beginning. This

displays the routine starting with the first line. It
provides a quick way to move to the top of the routine.

D.5 Editing Commands
Editing commands work within the line of the program that contains the
cursor. All of the editing commands are single character commands and
may be entered in either upper-case or lower-case. Table D-3 below
shows the commands that can be used to insert, delete, and replace
characters within a line, to overlay characters, insert new lines, split
lines, and combine lines.
Table D-3 - Editing Commands
Command Function
nX Deletes the character at the current cursor position.
This command can be preceded by a number to
indicate the number of consecutive characters to delete
beginning with the cursor position. If the number
specified exceeds the number of remaining characters
in the line then only the characters through the end of
the line are deleted.
I Begins inserting characters before the current cursor

position. Characters continue to be inserted until a
RET or ESC is entered.
A Begins inserting characters after the current cursor

position. Characters continue to be inserted until a
V Begins overlaying characters at the current cursor

position. Characters continue to be overlaid until a
O Opens screen area to insert new lines into program.

When entered, the edit opens one line below the line
containing the cursor. Lines continue to be inserted
until a null line (i.e., a RET with no data) is entered.
-O Opens screen area to insert new lines into program.

When entered, the edit opens one line above the line
containing the cursor. Lines continue to be inserted
until a null line (i.e., a RET with no data) is entered.

Command Function
R Replaces a single character in a line. When the R
command is entered, the editor replaces the character
where the cursor is positioned with the next character
that is entered.
U Undoes the last edit command that was performed.

When the U command is entered, all the text which
was changed by the most recent edit command is
restored to its previous state.
-U Undoes all changes made to the current line.

Whenever the cursor moves into a line, a copy of the
line is made. When this command is entered, the saved
line is used to restore the line to its original state.
S Splits a line into two separate lines. The split occurs

at the character under the cursor. The character under
the cursor becomes the first character of the body of
the new line.
C Combines two consecutive lines to form a single line.

The line following the cursor is appended to the line
containing the cursor. If the resulting line would
exceed 255 characters, the terminal bell rings and no
action takes place. If the appended line has a label, it
is discarded.
/ Repeats the last edit command that was issued.

D.6 Mark Commands
The mark commands are used to identify an area of the program that is
operated on by some other command. Any portion of the program,
including single characters, parts of a lines, and multiple lines can be
marked. The marked area is displayed in reverse video to highlight it.
Table D-4 below shows the commands used to mark and un-mark areas
of a program.
Table D-4 - Mark Commands
Command Function
M Mark an area of the program. The default mark is from
the current cursor position to the end of the line. Only
one mark can be active at a time. The mark may be
in the current program or in a program previously
edited using the .E command. When the mark is not
in the current program, a mark command replaces the
old mark. If a mark is active in the current program
and this command is entered, the terminal bell rings
and no action takes place. Also, edit commands are
not allowed within a marked area.
B Set the ending bound of a marked area. When this

command is entered, the marked area is extended or
reduced so the marked area is from the start of the mark
to the current cursor position. If the cursor is before
the start of the mark when this command is entered,
the terminal bell rings and no action takes place.
-M Un-mark the current marked area. It is not necessary

for the cursor to be within the marked area when this
command is entered. The marked area is restored to
normal video after it is unmarked.

D.7 Delete Commands
The delete commands are used to remove portions of the routine. All
delete commands are entered as two character commands to ensure that
code is not accidentally deleted. They operate at the character level,
partial line level, line level, or multi-line level. They can also operate
on a area of the screen that has been identified with the mark command.
Table D-5 below shows the various delete commands that are available.
Table D-5 - Delete Commands
Command Function
DE Delete from cursor to end of line. This command
deletes all characters from the cursor (including the
cursor) to the end of the line of MUMPS code that
contains the cursor.
D$ This is the same as the DE command.
DB Delete from start of line to cursor. This command

deletes all characters from the beginning of the line of
MUMPS code that contains the cursor up to but not
including the cursor.
D0 This is the same as the DB command.
DL Delete the line containing the cursor. This command

deletes the entire line of MUMPS code that contains
the cursor. The command can be preceded with a
number to delete the specified number of consecutive
lines.
DM Delete the marked area of the program. This command

deletes the entire marked area of the program. The
marked area need not be visible at the time this
command is entered. If no area is marked, the terminal
bell rings and no action takes place.

D.8 Search Commands
The search commands are used to locate a string of text within the
program. The string can be from a single character up to 255 characters
in length. The search commands look for the first occurrence of the
string starting at a specified location. When the string is found, the cursor
is positioned to the first character of the string. Table D-6 below shows
the various search commands that are available.
Table D-6 - Search Commands
Command Function
.S Search labels and text within the program for the
specified string. If the string is not found, the terminal
bell rings to indicate that the string was not found and
the cursor returns to the location where the command
was entered.
N Continues to search forward using the string specified

by the last search operation. The editor scans forward
in the program for the next occurrence. If the string
is not found, the terminal bell rings and the cursor
returns to the location where the command was
entered.
-N Continue to search backward using the string specified

by the last search operation. The editor scans
backward in the program for the next occurrence. If
the string is not found, the terminal bell rings and the
cursor returns to the location where the command was
entered.
.J Jump to a specified label. This command searches

within the program for the specified label. If the label
exists, the cursor moves to the first character of the
label. If the label is not found, the terminal bell rings
to indicate that the label was not found and the cursor
entered.

D.9 Transfer/Copy Commands
The transfer and copy commands are used to move (i.e., transfer) or copy
lines of MUMPS code to a new location within a routine. These
commands work on one or more lines of the routine or on the marked
area of a routine. Table D-7 below shows the various transfer and copy
commands that are available.
Table D-7 - Transfer/Copy Commands
Command Function
TM Move the marked area after the cursor. This command
moves (i.e., copy and delete) the area presently marked
within the routine so that it begins on the line
immediately following the cursor. The marked area
need not be visible on the screen. If no area within the
program is marked, the terminal bell rings and no
action takes place.
TC Copy the marked area after the cursor. This copies

(i.e., no delete) the area presently marked within the
routine so that it begins on the line immediately
following the cursor. The marked area need not be
visible on the screen. If no area within the program is
marked, the terminal bell rings and no action takes
place.
P Insert last yanked lines, deleted lines, or deleted

characters. This command inserts the lines or
characters that were removed by the last delete
command or saved by the last yank command so that
they become the next line of MUMPS code
immediately following the cursor. If no lines have
been deleted or yanked, the terminal bell rings and no
action takes place.
nY Yank one or more lines beginning with the current line.

This command is used to put lines into a temporary
storage area within the editor. It can be preceded by
a number to indicate the number of consecutive lines
to be stored. Lines can be retrieved with the P
command.

D.10 Miscellaneous Commands
In addition to the groups of commands described above, the editor
includes miscellaneous commands to file programs, file and exit from
the editor, or put lines of code into temporary storage that exists across
edit sessions. Table D-8 below shows additional miscellaneous
commands that are available in the editor.
Table D-8 - Miscellaneous Commands
Command Function
.Q Quit from editing the current routine. This command
is used to terminate editing of a program. If the
program was edited using the .E command, then the
editor returns to the previous program that was being
edited. If there is no previous program, then the editor
exits and return to direct mode in MSM. If the program
has been modified, the editor displays a message and
prompt the user to verify that the editor is to terminate
without saving the changes.
.F File the routine. This command saves the program

back to disk and terminates the program edit. If the
name of the routine does not match the first line of the
routine, the user is prompted to verify the name that
is to be used when the program is saved. As part of
the save operation, the program is checked for syntax
errors. If any are found, they are displayed and the
user is prompted for whether or not the program should
be saved anyway.
.W Write the program to disk. This command is the same

as the .F command except that the editor does not exit.
After the program has been written to disk, the cursor
entered.
.E Temporarily edit another program. This command

allows the editor to edit another program and return to
the existing program when the editing is complete.
This allows lines to be moved between programs.

Command Function
.N Edit another program. This command allows the user
to discard the current program that is being edited and
to edit a different program.
.R Read lines from another routine. The user is prompted

for the name of the routine, the starting line, and the
ending line. The lines that are read from the other
program are inserted after the line that contained the
cursor when the command was entered.
.C Change every occurrence of a string. The user is

prompted for the string to be changed, the string that
replace it, the starting line to search for the string, and
the ending line to search for the string. If the string is
not found, the terminal bell rings and no action takes
place.
.G Get lines from temporary storage. The user is

prompted for the name of the area that contains the
lines. The lines are inserted after the line that contained
the cursor when the command was entered.
.P Put lines into temporary disk storage. The user is

prompted for the name of the area where the lines are
to be stored, the starting line, and the ending line. The
lines are stored with $IO as the first subscript and the
name of the area specified by the user as the second
subscript. This way area names are unique to each
user. If the area name begins with a percent sign (%),
the first subscript is 0 and the area is known to all users.
? Display HELP information. This command instructs

the editor to display a summary of each of the
commands that are available. The editor pauses after
each full screen of HELP information.

Table D-9 - Summary of Editor Commands
Cursor Movement Commands

Backspace Moves cursor one character left
H Moves cursor one character left
L or Space Moves cursor one character right
J Moves cursor down one line
K Moves cursor up one line
0 (zero) Moves cursor to beginning of current line
$ Moves cursor to end of current line
RET Moves cursor to beginning of next line
TAB Move cursor ten (10) characters right
Fx Move cursor to next occurrence of character x
; Move cursor to next occurrence last Fx character
nG Go to relative line number
Editing Commands
nX Delete characters at cursor position
I Begins insert of characters before the cursor
A Begins insert of characters after the cursor
V Begins overlaying characters at cursor position
O Begins data entry on new line after current line
-O Begins data entry on new line before current line
R Replaces character at cursor with next entered
U Undoes the last edit command
-U Undoes all changes to line
S Splits current line after cursor
C Combines current line with next line
/ Repeat the last edit command
Delete Commands
Dx Delete commands are always two characters
DE Delete from cursor to end of line
D$ Delete from cursor to end of line
DB Delete from start of line to cursor
D0 Delete from start of line to cursor
DL Delete current line containing cursor
DM Delete characters/lines that are marked

Scroll Commands
CTRL/E Scroll one line further into the program
CTRL/D Scroll one half screen further into the program
CTRL/F Scroll one full screen further into the program
CTRL/Y Scroll one line back in the program
CTRL/U Scroll one half screen back in the program
CTRL/B Scroll one full screen back in the program
CTRL/G Display current position in routine
CTRL/L Re-display current screen
CTRL/R Re-display routine from first line
Search Commands
.S Search for a string starting at cursor
.J Search for a label starting at cursor
N Continue search forward with same string
-N Continue search backward with same string
Mark Commands
M Mark line from cursor to end
B Set the ending bound of a marked area
-M Un-mark the current marked area
Transfer/Copy Commands
Tx Transfer commands are always two characters
TM Move marked area after cursor
TC Copy marked area after cursor
P Insert last Yanked or Deleted lines
nY Yank n lines starting at current line
Miscellaneous Commands
.Q Quit the current routine edit
.F File the routine and exit the routine
.W File the routine and continue editing
.E Temporarily edit another program
.N Edit a new program and discard current one
.R Read in lines from another program
.C Change every occurrence of a string
.P Put lines into temporary storage
.G Get lines from temporary storage
? Display help information

APPENDIX E
CUA FULL SCREEN EDITOR

This appendix describes the CUA style Full Screen Editor and how to
create new programs or edit existing programs. Note that the CUA style
Full Screen Editor only supports ANSI-compatible terminals.
E.1 Invoking The Editor

The CUA style full screen editor of MSM substantially conforms to the
Common User Access (CUA) standards developed by IBM as part of
their System Application Architecture (SAA) guidelines. To invoke the
full screen editor, enter the following MUMPS command:
X ^%G
If there is a program in the user’s partition, then it will be loaded by the
editor. Otherwise, the editor initializes an empty workspace where a
new program can be created. The following shows the main editor screen
with an empty workspace.
Figure E-1 - CUA Editor - Main Screen
MSM Routine Editor - [MGR,SYS] <noname>

File Edit Search Options Window Help
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
~
F1=Help F9=Select F10=Menu Bar 7:02am
Full Screen Editor E-1

E.2 Editor Screen Layout
The main editor screen consists of a title bar at the top of the screen, a
menu bar on the line directly below the title line, and a status bar on the
last line of the screen. The area between the menu bar and the status bar
is referred to as the workspace.
The title line contains the notation "MSM Routine Editor," followed by
the name of the current routine that is being edited. If the routine is
unnamed, then the title line displays <noname> where the routine name
would normally be placed. The title line also displays the name of the
UCI and Volume that contain the routine being edited.
The menu bar contains a list of the available high-level menu actions:
File, Edit, Search, Options, Window, and Help. To access the menu,
the user presses the F10 key. This highlights the menu bar and positions
the cursor on the File option. Using the and arrow keys, the cursor
can be positioned at the appropriate menu item. To select the menu item,
the RET key is pressed.
For performance reasons, pull-down menus are not used on terminal
devices. Instead, when the menu is accessed with the F10 key, the
menu bar will be replaced with a menu bar containing sub-menu items.
The arrow keys are then used to highlight the desired item, followed by
the RET key to select the item. Also, the highlighted letter can be entered
to select a menu item.
The status bar, which is used to display information about the editing
process, is composed of two areas separated by a vertical bar. The left
hand area of the status bar is used to display context-sensitive help
information. When no specific editor operation is in progress, the area
displays the function keys that can be used to obtain help information,
to mark text (i.e., select), and to activate the menu bar.
E-2 Full Screen Editor

When an editor operation is active, this area displays information about
the operation being performed. For example, when a menu item is
selected, the help area displays a one-line description of the selected
function. When no editor operation is active, the editor displays a legend
showing the most commonly used function keys.
The right hand side of the status bar is used to display status indicators,
the name of the menu item that has been invoked, and the current time
of day. The status indicators include a number greater than 1 that
indicates the number of open windows (a blank will be displayed if only
one window is open), the letter M if the program in the workspace has
been modified (a blank will be displayed if the program is not modified),
the letter O if the editor is operating in overlay mode (a blank will be
displayed if the editor is in insert mode), and the letter R if the program
has been loaded as read-only (a blank will be displayed if the program
was loaded for read and write).
E.3 Using The Workspace

When the editor is invoked, the cursor is positioned to the upper left
corner of the workspace. By default, the editor will be in insert mode;
any characters that are entered will be inserted into the routine at the
current cursor location.
Cursor keys are used to navigate around the workspace. In general,

arrow keys, the PgUp and PgDn keys, and the Home and End keys
move the cursor a specified distance. When used in combination with
the Ctrl and Alt keys, the amount of cursor movement is increased.
Also, (Backspace) will delete the character immediately before the
cursor and Del will delete the character under the cursor.
The Ins key is used to toggle between Insert mode and Overlay mode.
When the editor is in insert mode, pressing the Ins key will switch the
editor into Overlay mode. When this occurs, the letter O will appear on
the right hand side of the status line. In this mode, a character that is
entered will overlay the character under the current cursor position. If
the Ins key is pressed again, the editor switches to Insert mode. When
this occurs, the letter O in the status line is replaced with a blank.
To perform editing operations, first position the cursor to the appropriate
spot in the program. Then, select the desired function using the menu,
the function keys, or the accelerator keys. Table E-1 below shows the
various cursor positioning keys and their associated actions.

Table E-1 - Cursor Movement Keys
Cursor Key Description

Moves cursor left one character
Ctrl-Left Moves cursor left one word
Moves cursor right one character
Ctrl-Right Moves cursor right one word
Moves cursor up one physical line
Ctrl-Up Scrolls screen up one logical line
Alt-Up Moves cursor up 5 logical lines
Moves cursor down one physical line
Ctrl-Down Scrolls screen down one logical line
Alt-Down Moves cursor down 5 logical lines
Home Moves cursor to beginning of line
Ctrl-Home Moves cursor to beginning of program
Alt-Home Moves cursor to beginning of screen
End Moves cursor to end of line
Ctrl-End Moves cursor to end of program
Alt-End Moves cursor to end of screen
PgUp Pages back one screen
Ctrl-PgUp Pages back one-half screen
PgDn Pages forward one screen
Ctrl-PgDn Pages forward one-half screen
(Backspace) Erases character before cursor
Del Erases character under cursor

All of the editing functions can be accessed from the menu bar. However,
as an aid to productivity, many of the functions can be accessed directly
through the function keys without invoking the menu. Table E-2 below
shows the various function keys and their associated actions.
Table E-2 - Function Keys
Function Key Description

F1 Invokes the context-sensitive HELP function
F2 Transfers copy of marked text to the Paste buffer
F3 Deletes marked text and puts it in the Paste buffer
F4 Inserts contents of the Paste buffer before cursor
F5 Undoes the last editing change that was made
F6 Changes specified text string to new text string
F7 Finds an occurrence of specified text string
F8 Finds the next occurrence of specified text string
Shift-F8 Finds the previous occurrence of specified text
string
F9 Marks text for Cut, Copy, or Delete operation
F10 Activates the menu bar
F11 Accepts the current dialog box
F12 Cancels the current dialog box
Esc Cancels the current dialog box
In addition to the editing functions, the menus provide access to many

other functions, including: loading and saving programs, marking text,
escaping to the MSM Programmer Shell, etc. While all of these functions
can be accessed from the menu, accelerator keys, which allow functions
to be directly accessed without using the menu, have been provided for
the most commonly accessed functions. Table E-3 below shows the
accelerator keys and their associated actions.

Table E-3 - Accelerator Keys
Accelerator Description
Ctrl-A Inserts line above current line
Ctrl-B Inserts line below current line
Ctrl-C Closes the current window
Ctrl-D Escapes to the DOS Shell (MSM-PC/PLUS only)
Ctrl-E Escapes to the MSM Programmer Shell
Ctrl-F Finds an occurrence of a specified string
Ctrl-G Finds the next occurrence of a specified string
Ctrl-J Jumps to a Label or a Label+Offset
Ctrl-K Marks the current or the next word in the line
Ctrl-L Marks the current line
Ctrl-N Switches to the next open window
Ctrl-O Opens a new window
Ctrl-P Prints the routine in the current window
Ctrl-R Loads a routine into the current window
Ctrl-S Saves the routine in the current window
Ctrl-T Checks syntax of the routine in the current window
Ctrl-U Undoes all editing changes to the current line
Ctrl-V Views the list of open windows
Ctrl-W Functions the same as Ctrl-S
Ctrl-X Exits the editor and saves routine if modified

Ctrl-Y Highlights all strings that match Find string

E.4 Dialog Boxes
Whenever it is necessary for the editor to prompt the user for information,
a dialog box will be created. A dialog box is a pop-up window that
contains a title describing the function, one or more fields to be filled in
by the user, and one or more action buttons. The arrow keys or the
key can be used to move from field to field on the screen. Once the
cursor is positioned within a field, the F1 key can be pressed to obtain
HELP information. Pressing the F1 key a second time will display a
higher level of HELP information. Also, the ? key can be used to obtain
help information.
The action buttons appear at the bottom of the dialog box. The default
button (i.e., the button selected when the user presses the RET key) is
highlighted using a color or reverse video. The arrow keys or the
key can be used to move the highlighting from button to button.
E.5 File Menu

The File menu is accessed by entering the F10 key, followed by the F
key, or by entering the Alt-F key. When the File menu is invoked, a
series of options are displayed. The desired option can be selected using
the arrow keys followed by the RET key or by entering the highlighted
letter in the option. An option name that is followed by three periods
(i.e., ... ), indicates that a dialog box will be displayed when the option
is selected. If the menu item has an accelerator key, it will appear to the
right of the menu option. The following options are displayed when the
File menu item is selected.
New - This option is used to create a new routine. If the current window
contains a routine that is modified, then a new window will be created;
otherwise, the current window is used. When this option is selected, a
dialog box is displayed to prompt the user for the name of the routine
to be created.
Retrieve - This option is used to load a previously created routine into

the workspace of the current window. When this option is selected, a
dialog box is displayed to prompt the user for the name of the routine
to be retrieved and the edit mode (edit or read-write). The system also
displays the current UCI and Volume group from which the routine will
be retrieved. The Ctrl-R key can be used as an accelerator to access
this option.

Save - This option is used to save the routine in the workspace of the
current window. The routine will be saved without any dialog with the
user if the name on the first line is the same as the current routine name
and the routine contains no syntax errors. Otherwise, a dialog box will
be displayed and the user will be prompted for the appropriate action.
The Ctrl-S key (on the PC console only) or the Ctrl-W key can be
used as an accelerator to access this option.
Save as - This option is used to save the routine in the workspace of the
current window and to specify a new name for the routine. When this
option is selected, a dialog box is displayed to prompt the user for the
new name of the routine. If the specified name already exists, then the
user is prompted to verify that the routine should be overlayed.
Delete - This option is used to delete from disk the routine in the
workspace of the current window. The user is prompted to verify the
action before it is actually performed.
Print - This option is used to print the routine in the workspace of the
current window. When this option is selected, a dialog box is displayed
to prompt the user for the number of lines per page, the characters per
line, the header comment, the output device, and the output device
parameters. The Ctrl-P key can be used as an accelerator to access
this option.
Syntax - This option is used to perform a syntax check of the routine in
the workspace of the current window. If an error is detected, a message
is displayed and the error is highlighted. The Ctrl-T key can be used
as an accelerator to access this option.
Shell - This option is used to invoke the MSM programmer shell. Once
in the shell, the user can enter MUMPS commands in the same way that
they would be entered in direct programmer mode. To return to the
editor, the QUIT command is entered. The Ctrl-E key can be used
DOS - On MSM-PC/PLUS systems, this option is used to invoke the
standard DOS shell (i.e., COMMAND.COM). When the shell is
invoked, all other MUMPS processes are suspended. When the user has
completed work in DOS, the EXIT command is entered to return to
MUMPS. The Ctrl-D key can be used as an accelerator to access this
option.

Exit - This option is used to exit from the editor. If the workspace
contains a modified program, a dialog box will be displayed to prompt
the user to save the modified program, discard the modified program,
or return to the editor. The {Ctrl-Q} key (on PC console only) or the
{Ctrl-X} key can be used as an accelerator to access this option.
E.6 Edit Menu

The Edit menu is accessed by entering the F10 key followed by the E
key or by entering the Alt-E key. When the Edit menu is invoked, a
letter in the option. An option name followed by three periods (i.e., ...
) indicates that a dialog box will be displayed when the option is selected.
If the menu item has an accelerator key, it will appear to the right of the
menu option. The following options are displayed when the Edit menu
item is selected:
Undo - This option is used to undo the last editing operation. For
example, if the last operation was a Cut, then the undo option will restore
the deleted text. If the undo option is then immediately selected again,
the restored text will be deleted. The F5 key and the Ctrl-U key can
be used as an accelerator to access this option. Note that Undo only
undoes changes to the current line and only if the cursor has not left the
line since the changes were made.
Select - This option is used to mark text within the workspace. When
this option is selected, the character under the cursor will be marked.
This will be indicated by highlighting the character with reverse video
or the color red. The mark can be extended by using the arrow keys or
the arrow keys in combination with the Ctrl and Alt keys. Once an
area is marked, it can be Cut, Copied, or Deleted. The F9 key can be
used as an accelerator to access this option.
Copy - This option is used to copy the marked text to the Paste buffer.
After completion of the operation, the text becomes unmarked. The F2
key can be used as an accelerator to access this option.
Cut - This option is used to delete the marked text and to place it in the
Paste buffer. The F3 key can be used as an accelerator to access this
option.

Paste - This option is used to insert the text contained in the Past buffer
at the location starting in front of the cursor. The F5 key can be used
Delete - This option is used to delete the marked text. The deleted text
is not placed in the Paste buffer. The Del key can be used as an
accelerator to access this option.
E.7 Search Menu

The Search menu is accessed by entering the F10 key followed by the
S key or by entering the Alt-S key. When the Search menu is invoked,
a series of options will be displayed. The desired option can be selected
using the arrow keys followed by the RET key or by entering the
highlighted letter in the option. If the menu item has an accelerator key,
it will appear to the right of the menu option. The following options are
displayed when the Search menu item is selected.
Find - This option is used to search for a specified string of text. When
this option is selected, a dialog box is displayed to prompt the user for
the search string, the match case (any case or match the exact specified
case), the search direction (forward or backward) and what to do when
the end of routine is reached (wrap around to the beginning or stop).
The F7 key or the Ctrl-F key can be used as an accelerator to access
this option.
Change - This option is used to search for a specified string of text and
to replace it with a new text string. When this option is selected, a dialog
box is displayed to prompt the user for the search string, the replace
string, the match case (any case or match the exact specified case), the
search direction (forward or backward) and what to do when the end of
routine is reached (wrap around to the beginning or stop). The F6 key
can be used as an accelerator to access this option.
When the Change operation finds an occurrence of the search string in
the program, it displays a pop-up window to prompt the user for the
appropriate change action. The user can specify Change to replace the
highlighted occurrence and search for the next occurrence, Once to
change the highlighted occurrence and quit, Skip to leave the highlighted
occurrence unchanged and to search for the next occurrence, All to
replace the highlighted occurrence and all other occurrences without
further prompting, or Quit to terminate the change operation.

Next - This option repeats the previous Find operation. The search begins
at the current location and proceeds toward the end of the routine. At
the end of the routine, the search will either stop or wrap to the beginning
of the routine depending upon the option selected on the Find operation.
The F8 key or the Ctrl-G key can be used as an accelerator to access
this option.
Previous - This option repeats the previous Find operation. The search
begins at the current location and proceeds toward the beginning of the
routine. At the beginning of the routine, the search will either stop or
wrap to the end of the routine depending upon the option selected on the
Find operation. The Shift-F8 key can be used as an accelerator to
access this option.
Jump - This option is used to move the cursor to a specified location in
the routine. When this option is selected, a dialog box prompts the user
for the line label where the cursor is to be positioned. The label may
include a plus or minus offset (e.g., CUST+3, FILE-4, etc.) or an absolute
offset from the beginning of the routine (e.g., +8) can be specified. The
Ctrl-J key can be used as an accelerator to access this option.
E.8 Options Menu

The Options menu is accessed by entering the F10 key followed by the
O key or by entering the Alt-O key. When the Options menu is
invoked, a series of options will be displayed. The desired option can
be selected using the arrow keys followed by the RET key or by entering
the highlighted letter in the option. An option name followed by three
periods (i.e., ... ), indicates that a dialog box will be displayed when the
option is selected. If the menu item has an accelerator key, it will appear
to the right of the menu option. The following options are displayed
when an Options menu item is selected.
Colors - In the current release, this sub-menu option is not available. It
will be implemented in a future release.
Characters - In the current release, this sub-menu option is not available.

It will be implemented in a future release.
First line - In the current release, this sub-menu option is not available.
Help level - In the current release, this sub-menu option is not available.

E.9 Window Menu
The Window menu is accessed by entering the F10 key followed by
the N key or by entering the Alt-N key (on PC console device only).
When the Window menu is invoked, a series of options will be displayed.
The desired option can be selected using the arrow keys followed by the
RET key or by entering the highlighted letter in the option.
An option name followed by three periods (i.e., ... ), indicates that a

dialog box will be displayed when the option is selected. If the menu
item has an accelerator key, it will appear to the right of the menu option.
The following options are displayed when a Window menu item is
selected.
Open - This option is used to open a new window within the editor.
When this option is selected, the editor creates a new window with an
empty workspace and then switches the user to the new window. Also,
the count of open windows in the status bar will be increased by one.
The Ctrl-O key can be used as an accelerator to access this option.
Close - This option is used to close the current window within the editor.
Before closing the window, the editor checks to see if the window
contains a modified program. If it does, a dialog box will be displayed
to prompt the user for the action to be taken. The user can choose to
save or discard the program. The Ctrl-C key can be used as an
Next - This option is used to switch to the next open window in the chain
of active windows. When the end of the chain is reached, the operation
will wrap to the start of the chain. The Ctrl-N key can be used as an
View - This option is used to display a list of all open windows. The
list includes the name of the program being edited, the number of lines
in the program, and program status (i.e., read-only or modified). If
desired, the user can position the cursor in the list using the arrow keys
and then press the RET key to switch to the highlighted window. The
Ctrl-V key can be used as an accelerator to access this option.

E.10 Help Menu
The Help menu is accessed by entering the F10 key followed by the H
key or by entering the Alt-H key. When the Help menu is invoked, a
letter in the option. An option name followed by three periods (i.e., ...
), indicates that a dialog box will be displayed when the option is selected.
If the menu item has an accelerator key, it will appear to the right of the
menu option. The following options are displayed when the Help menu
item is selected.
Help - This option displays instructions on how to use the HELP facility
of the CUA style full screen editor.
Cursor - This option provides a list of the cursor keys supported by the
editor and the actions associated with each key.
Functions - This option provides a list of the function keys supported
by the editor and the actions associated with each key.
Accelerators - This option provides a list of the accelerator keys
supported by the editor and the actions associated with each key.
Procedures - This option provides a list of commonly-used editor
procedures and instructions on how to perform them. To display
information about a particular procedure, use the arrow keys to highlight
the item and then press the RET key.
About - This option displays the current release level of the CUA style
full screen editor.


APPENDIX F
MNEMONIC NAMESPACES
This appendix describes the system-supplied Mnemonic Namespaces
provided with MSM.
F.1 ANSI X3.64-1979 Namespace

Table E-1 below 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. Each
mnemonic must be preceded by a slash (/) when used.
Table F-1 ANSI X3.64-1979 Mnemonic Namespace
Mnemonic Function & ESC Sequence Change in $X & $Y

/BEL Ring Bell $X:None
Seq: *7 $Y:None
/BS Backspace Cursor $X:MAX(0,$X-1)

Seq: *8 $Y:None
/CBT(n) Backup n Tab Stops $X:

Minimum & Default Value Is 1 MAX(0,$X+7\8*8-(n*8))
Assumes 8 Column Tabbing $Y:None
Seq: *27 [ n Z
/CHA(n) Move Cursor To Column n $X:n-1
Minimum & Default Value Is 1 $Y:None
Seq: *27 [ n G
/CHT(n) Forward n Tab Stops $X:

Minimum & Default Value Is 1 MIN(255,$X\8*8+(n*8)
Assumes 8 Column Tabbing $Y:None
Seq: *27 [ n I
/CNL(n) Cursor Down n Lines $X:0

Cursor To Column 1 $Y:MIN(255,$Y+n)
Minimum & Default Value Is 1
Seq: *27 [ n E
/CPL(n) Cursor Up n Lines $X:0

Cursor To Column 1 $Y:MAX(0,$Y-n)
Seq: *27 [ n F
/CR Column 1 Of Current Line $X:0
Seq: *13 $Y:None
/CTC(a,b,...) Set Tab Stops $X:None
Seq: *27 [ a ; b ; ... W $Y:None
Mnemonic Namespaces F-1

/CUB(n) Cursor Back n Columns $X:MAX(0,$X-n)
Seq: *27 [ n D
/CUD(n) Cursor Down n Rows $X:None
Minimum & Default Value Is 1 $Y:MIN(255,$Y+n)
Seq: *27 [ n B
/CUF(n) Cursor Forward n Columns $X:MIN(255,$X+n)

Seq: *27 [ n C
/CUP(r,c) Position Cursor $X:c-1

To Row r Column c $Y:r-1
Minimum For c And r Is 1
Default For c And r Is 1
Maximum For c And r Is 256
Seq: *27 [ r ; c H
/CUU(n) Cursor Up n Lines $X:None

Minimum & Default Value Is 1 $Y:MAX(0,$Y-n)
Seq: *27 [ n A
/DA(a,b,...) Set Device Attributes $X:None
Parameters Are ANSI Values $Y:None
For Color, Blink, etc.
Seq: *27 [ a ; b ; ... c
/DAQ(a,b,...) Define Area Qualification $X:None
Seq: *27 [ a ; b ; ... o
/DCH(n) Delete n Characters At Cursor $X:None
Rest Of Line Slides Left $Y:None
Seq: *27 [ n P
/DL(n) Delete n Lines At Cursor $X:None
Rest Of Lines Slide Up $Y:None
Seq: *27 [ n M
/DSR(a,b,...) Device Status Request $X:None

Response Needs To Be
Read In Via READ Command
Seq: *27 [ a ; b ; ... n
/ECH(n) Erase n Characters At Cursor $X:None
Replace With Blanks $Y:None
Seq: *27 [ n X
/ED(n) Erase Display $X:None
n=0: Cursor To End Of Display $Y:None
n=1: Home To Cursor
n=2: Entire Display
Seq: *27 [ n J
F-2 Mnemonic Namespaces

/EL(n) Erase Line $X:None
n=0: Cursor To End Of Line $Y:None
n=1: Start Of Line To Cursor
n=2: Entire Line
Seq: *27 [ n K
/FF Cursor Down 1 Row $X:None

Seq: *12 $Y:($Y+1)#256
/HPA(n) Cursor To Column n $X:n-1

Seq: *27 [ n ‘
/HPR(n) Cursor Forward n Columns $X:MIN(255,$X+n)
Seq: *27 [ n a
/HT Horizontal Tab $X:MIN(255,$X\8*8+8)

Seq: *9 $Y:None
/HTS Set Horizontal Tab Stop $X:None

At Cursor $Y:None
Seq: *27 H
/HVP(r,c) Cursor To Row r And Column c $X:c-1
Minimum & Default Value Is 1 $Y:r-1
Maximum Value Is 256
Seq: *27 [ r ; c f
/ICH(n) Insert n Blanks At Cursor $X:None
Seq: *27 [ n @
/IL(n) Insert n Blank Lines At Cursor $X:None

Seq: *27 [ n L
/IND Move Cursor 1 Column Down $X:None

Seq: *27 D $Y:MIN(255,$Y+1)
/LF Move Cursor 1 Line Down $X:None

Seq: *10 $Y:($Y+1)#256
/MSMRC(n) Restore Saved Cursor Position $X:Saved value

Seq: *27 8 $Y:Saved value
/MSMRGN(n,m) Setup Scrolling Region $X:None

Seq: *27 [ n ; m r $Y:None
/MSMRM(a,b,...) Reset Modes $X:None

Seq: *27 [ ? a ; b ... h $Y:None
/MSMSC Save Current Cursor Position $X:None

Seq: *27 7 $Y:None
/MSMSM(a,b,...) Set Modes $X:None

Seq: *27 [ ? a ; b ... h $Y:None
/NEL Move To Column 1 Of Next Line $X:0

Seq: *27 E $Y:($Y+1)#256

/NP(n) Advance n Pages Of Terminal $X:0
Display Memory $Y:0
Seq: *27 [ n U
/PP(n) Backup n Pages Of Terminal $X:0
Display Memory $Y:0
Seq: *27 [ n V
/RI Reverse Index (Up 1 Column) $X:None

Seq: *27 M $Y:MAX(0,$Y-1)
/RIS Reset To Initial State $X:0

Seq: *27 c $Y:0
/RM(a,b,...) Reset Modes $X:None

Values Are ANSI Defined $Y:None
Seq: *27 [ a ; b ; ... l
/SGR(a,b,...) Set Graphical Rendition $X:None

Seq: *27 [ a ; b ; ... m $Y:None
/SM(a,b,...) Set Modes $X:None

Values Are ANSI Defined $Y:None
Seq: *27 [ a ; b ; ... h
/TBC(a,b,...) Clear Tap Stops $X:None
Seq: *27 [ a ; b ; ... g $Y:None
/VPA(r) Move To Row R At Same Column $X:None
Minimum & Default Value Is 1 $Y:r-1
Seq: *27 [ r d
/VPR(n) Cursor Down n Lines $X:None

At Same Column $Y:MIN(255,$Y+n)
Seq: *27 [ n e
/VT Vertical Tab (Up 1 Column) $X:None

Seq: *11 $Y:MAX(0,$Y-1)

F.2 ZWINTERM Namespace
The ZWINTERM Mnemonic Namespace provides a mechanism for
programmers to perform windowing type functions on dumb terminals.
These functions are also 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 will build 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 will
be applied to the memory image as well as to the physical screen.
When a window is opened in the ZWINTERM Mnemonic Namespace,
the system will make a copy from the in-memory screen image of the
area that will be overlayed by the new window. Once the window is
opened, the program can use the normal READ and WRITE commands
to access the window. Then, when the window is closed, the system
will automatically refresh the area under the window. No additional
action is required on the part of the program to restore the area.
When using the ZWINTERM Mnemonic Namespace, the user must also
specify the name of the terminal Mnemonic Namespace to be used. This
is done by issuing the /INIT format control with the name of a terminal
Mnemonic Namespace. The specified namespace may be a built-in
namespace supplied with MSM or a user- defined namespace.
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.
Table F-2 below describes the various attributes that are supported.
Table F-2 ZWINTERM Display Attributes
Attribute Description
0 Restores normal text attributes
1 Sets Bold Attribute for text
2 Sets Underline Attribute for text
5 Sets Blink Attribute for Text

Attribute Description
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
26 Clears Blink Attribute for text
27 Clears Reverse Video Attribute for text
30 Sets foreground color to Black
31 Sets foreground color to Red
32 Sets foreground color to Green
33 Sets foreground color to Yellow
34 Sets foreground color to Blue
35 Sets foreground color to Magenta
36 Sets foreground color to Cyan
37 Sets foreground color to White
40 Sets background color to Black
41 Sets background color to Red
42 Sets background color to Green
43 Sets background color to Yellow
44 Sets background color to Blue
45 Sets background color to Magenta
46 Sets background color to Cyan
47 Sets background color to White
The attribute values can be specified on the /SGR, /WBSGR, /WTSGR,

/WDSGR, and the /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 can be set to White, and the foreground text can set to Blink. This
is done by issuing multiple ZWINTERM Control Mnemonics that
address the same character location. Following is an example of how
this might be done:
W /CUP(10,40),/SGR(46),/SGR(37),/SGR(5)
Note that all of the text attributes can be reset with a single operation.
This is done by specifying a zero (0) attribute value. However, the
background and foreground colors are not affected by a zero attribute
value. 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. Table F-3
below describes the various erase operations that are supported.
Table F-3 ZWINTERM Erase Attributes
Erase Type Description

0 Erases the window in memory, or the window on the
screen, or both from and including the current cursor
position to the end of the line or the end of the window.
1 Erases the window in memory, or the window on the
screen, or both from the beginning of the window or
the line to and including the current cursor position.
2 Clears the entire window or line in memory, or the
entire window or line on the screen, or both and resets
the Blink, Reverse, Bold, and Underline attributes.
The erase values can be specified on the /ED, /EL, /WCMD, and /WCML
Control Mnemonics. The /ED and /EL functions clear the memory buffer
and the screen. The /WCMD and /WCML functions only clear the
memory buffer. If desired, the /WDSP function can be used after these
functions to refresh the screen with the contents of the memory buffer.
When multiple updates are required to a screen, the program can use
functions that only update the memory buffer followed by a refresh. This
approach prevents unnecessary repaints of the screen and improves
performance.

Error Codes
After each Mnemonic Control operation, the system will return a value
in the $DEVICE Special Variable that indicates the success or failure
of the operation. Table F-4 below lists each of the values that can be
returned by the system and provides a description of the error associated
with each of the values.
Table F-4 ZWINTERM Error Codes
Error Code Description

0 Must be 0, normal success completion
1 Window already exists
2 Bad parameter value
3 Non-existent window
4 Mnemonic space not initialized
5 Terminal does not have windowing functionality
6 Undefined terminal mnemonic space
For additional information on the USE command and the $DEVICE

Special Variable, refer to the MSM Reference Manual. Note that the
$DEVICE Special Variable is maintained for the current terminal device
and not for each window in the ZWINTERM Mnemonic Namespace.
Therefore, the value contained in the $DEVICE Special Variable reflects
the last error condition regardless of which window it occurred in.

/INIT(TermSpace,Attribute) - Initialize Namespace
TermSpace A string expression that specifies the name of a
system or user-defined terminal mnemonic
namespace.
Attribute An integer value that indicates the type of attribute
to set. Refer to Table F-2 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 (i.e.,
/WOPEN) and USE (i.e., /WUSE) for window number zero (0)
as a full screen window. The default values for scroll, auto-wrap,
automatic display, and line drawing are used.
The ZWINTERM Namespace can be used in conjunction with
other Mnemonic Namespaces. The TermSpace parameter on the
/INIT function identifies the terminal namespace that is to be used.
With this feature, applications that rely on Mnemonic Namespaces
for terminal control can be easily adapted to use the windowing
capabilities of the ZWINTERM Mnemonic Namespace.
This Mnemonic Control must be executed before any other
ZWINTERM Mnemonic Control sequences can be used. If other
Mnemonic Controls are executed before a /INIT function has been
performed, the system will return 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, then the system will implicitly perform the
/END function before executing the /INIT function.
/END - Release Mnemonic Space

This function is used to end use of the ZWINTERM Mnemonic
Namespace. The end process will free 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 will return an error code of 12 in the $DEVICE Special
Variable.

/WOPEN(Win,Row,Col,NumRows,NumCols,Flag) - Open Window
Win A positive integer used to identify the window.
Row An integer expression with a value between 0 and
23 that indicates the starting row for the window.
If the specified value is invalid or omitted, the
system assumes a value of 0.
Col An integer expression with a value between 0 and
79 that indicates the starting column for the
window. If the specified value is invalid or omitted,
the system assumes a value of 0.
NumRows An integer expression with a value between 1 and
24 that indicates the number of rows in the window.
NumCols An integer expression with a value between 1 and

80 that indicates the number of columns in the
window.
Frame A string expression that indicates the characteristics
of the window frame. A value of "F" indicates the
window should have a frame and a value of " "
indicates that the window should have no frame.
This function creates a new window with identifier Win starting
at the location specified by the Row and Col parameters. The
window will contain 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 is used to make the specified window the current
window. All READ and WRITE commands and Mnemonic
Controls will 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 overlayed by the
window will be refreshed and memory buffers associated with the
window will be 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
will update the memory buffer and the updates will immediately
be displayed on the 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 will only update the memory buffer (i.e., the updates
will not immediately be displayed on the 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 the 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 will be automatically refreshed. Note that this
function does not delete the current window. Its contents can be
displayed again using the /WDSP function.

/WMOVE(Row,Col) - Move Window
Row An integer expression with a value between 0 and
23 that indicates the row where the window is to be
positioned. If this value is invalid or omitted, a
value of 0 is assumed.
Col An integer expression with a value between 0 and
79 that indicates the column where the window is
to be positioned. If this value is invalid or omitted,
a value of 0 is assumed.
This function is used to move the location of an existing window.
If the current window is not window 0, then the current window
origin (i.e., the upper left corner) will be moved to the locations
specified by the Row and Col parameters. Also, as part of the
move function, the screen will be 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 display title at top of window
1 display 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,
0 left-justify the title
1 center the title
2 right-justify the title
This function is used to specify a title to appear in the border of
the current window. The title can appear at the top of the window
or at the bottom of the window. Also, the title can be left-justified,
right- justified, or centered within the border.

/WTSGR(Attribute) - Window Title SGR
to be set or cleared. Refer to Table F-2 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 set the attributes for the title that appears
in the border of the current window.
/WBSGR(Attribute) - Window Border SGR

optional; if it is invalid or 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

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 when text is erased (i.e., with the /ED and /EL functions).
/WGETCW - Get Current Window

This function returns the identifier (i.e., 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 will be 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 Table
F-3 for a list of the erase types and their values. This
parameter is optional; if it 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

of 0 is assumed.
This function is used to erase all or part of a line in the current

window. When this function is used, only the in-memory buffer
is updated. The /WDSP function must be used to make the changes
visible to the user.
/WWR(Mode) - Change Wrap Mode

Mode An integer value from 0 to 1 that indicates how lines
of text are to be handled when the right margin is
reached. If this value is invalid or omitted, a value
of 0 is assumed.
0 Set autowrap on
1 Set autowrap off
This function is used to set the wrap mode for the current window.
When autowrap is on, a carriage return/linefeed sequence will
automatically be inserted when a text line reaches the right margin.
If autowrap if off, the line will be truncated.

/WSC(Scroll) - Change Scroll Mode
Scroll An integer value from 0 to 1 that indicates how lines
of text are to be handled when the bottom of the
screen is reached. If this value is invalid or omitted,
0 Set scroll mode on
1 Set 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 will be moved up
when a carriage return/line feed is sent to the last line of the
window. If scroll mode is off, then the lines will not be moved
and text will be written to the last line in the window.
/WCSGR(Attribute,Location) - Window Current SGR

to set or cleared. Refer to Table F-2 for a list of the
attributes and their values. This parameter is
assumed.
Location An integer from 0 to 6 that indicates where in the
current window the attribute is to be changed. If
this value is invalid or omitted, a value of 4 is
assumed.
0 Current character
1 From current cursor position to end of line
2 Entire line containing the cursor
3 From current cursor position to end of window
4 Entire window (default)
5 From current cursor position to end of column
6 Entire column containing the cursor
This function is used to change the attributes of text within the
current window. The specified Attributes are set or cleared
according to the position of the cursor and the range of the change
specified by the Location parameter.

/CUR(Display) - Cursor
Display An integer value from 0 to 4 that indicates actions
to be performed on the cursor within the window.
If this value is invalid or omitted, a value of 0 is
assumed.
0 show cursor
1 hide cursor
2 save cursor and attributes
3 restore cursor and attributes
4 force cursor and attributes
This function is used to perform various actions on the cursor
within the current window. It allows the programmer to show the
cursor, 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
Col An integer expression with a value from 0 to 79 that

indicates the column where the cursor is to be
This function positions the cursor to the specified Row and Col
position. Positions are relative to the upper left corner (i.e., row
0 column 0) of the current window.
/ED(Type) - Erase Display

of 0 is assumed.
This function is used to erase all or part of the current window.

When this function is executed, both the memory buffer and the
screen are updated.

/EL(Type) - Erase Line
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

Char (optional) 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 Write horizontal character (-)
3 Write vertical character (|)
4 Write character upper-left corner (*)
5 Write character upper-right corner (*)
6 Write character lower-left corner (*)
7 Write character lower-right corner (*)
8 Write intersection character (inverted T)
9 Write intersection character (T)
10 Write intersection character (left T)
11 Write intersection character (right T)
12 Write intersection character (+)
Repeat An integer value that indicates the number of times

that the line drawing character specified by the Char
parameter will be written. If this value is invalid or
omitted, a value of 1 is assumed.
This function is used to perform line drawing functions. When
this function is executed, the specified character is written at the
current cursor location the specified number of times.

/SGR(Attribute) - Change Window Attributes
to set or cleared. Refer to Table F-2 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 set or clear the specified attribute in the
current window. The attributes are changed in memory and on
the screen.

Sample ZWINTERM Program
Routine: WNSAMPLE UCI: MGR,SYS Date/Time: 19-FEB-93, 12:07 PM Page: 1-1
WSAMPLE ;MDC;TEST ZWINTERM MNEMONIC NAMESPACE [ 02/19/93 10:58 AM ]
K ^TEST("WSAMPLE")
U 0::"ZWINTERM" I +$D S MSG="unable to use ZWINTERM mnemonicspace. $DEVI
..........CE= "_$D,^TEST("WSAMPLE",1)=MSG W MSG Q
W /INIT("X3.64-1979") I +$D S MSG="error during /INIT. $DEVICE= "_$D,I
..........ND=5 G EREND
W /WOPEN(1,1,1,10,40,"F") I +$D S MSG="unable to open window #1. $DEVI
..........CE= "_$D,IND=10 G EREND
W /WUSE(1) I +$D S MSG="unable to use window #1. $DEVICE= "_$D,IND=15
..........G EREND
W /WSCRON I +$D S MSG="unable to /WSCRON. $DEVICE= "_$D,IND=20 G EREND
W /WTSGR(7)
W /WOPEN(3,20,5,4,70," ") I +$D S MSG="unable to open window #3. $DEVI
..........CE= "_$D,IND=10 G EREND
W /WUSE(3),/WSCRON W /CUP(1,3),/SGR(1),"write reversed title, in diffe
..........rent positions",/SGR W /WUSE(1)
H 1 W /WT("up-left title",0,0)
H 1 W /WT("up-center title",0,1)
H 1 W /WT("up-right title",0,2)
H 1 W /WT("bottom-right title",1,2)
H 1 W /WT("bottom-center title",1,1)
H 1 W /WT("bottom-left title",1,0)
H 1 W /WT("normal position window title")
W /WUSE(3) W /CUP(1,3),/SGR(1),"Change wrap mode off: no auto wrap",/E
..........L(0),/SGR W /WUSE(1)
H 1 W /WWR(1)
F I=1:1:15 W I,", set to no auto-wrap. abcdefghijklmnopqrstuvxyz",!
W /WUSE(3) W /CUP(1,3),/SGR(1),"Change to auto wrap",/EL(0),/SGR W /WU
..........SE(1)
H 1 W /WWR(0)
F I=1:1:15 W I,", set to auto-wrap. abcdefghijklmnopqrstuvxyz",!
W /WUSE(3) W /CUP(1,3),/SGR(1),"Erase from position (4,0) to end of wi
..........ndow",!," and Write graphic characters",/EL(0),/SGR W /WUSE(1)
W /CUP(4),/ED(0),"graphic lines: ",/CUP(4,15),/?DR(1),/?DR(4),/?DR(2,5
..........),/?DR(9),/?DR(2,5),/?DR(5),!
W /CUP(5,15),/?DR(3),/CUP(5,21),/?DR(3),/CUP(5,27),/?DR(3),!
W /CUP(6,15),/?DR(10),/?DR(2,5),/?DR(12),/?DR(2,5),/?DR(11),!
W /CUP(7,15),/?DR(6),/?DR(2,5),/?DR(8),/?DR(2,5),/?DR(7) H 10
W /?DR(0) I +$D S MSG="unable to graphic mode. $DEVICE= "_$D,IND=20 G
..........EREND
W /WUSE(3) W /CUP(1,3),/SGR(1),"Open a new window, #2",/ED(0),/SGR
W /WOPEN(2,7,15,12,45,"F")
W /WUSE(2) I +$D S MSG="unable to use window #2. $DEVICE= "_$D,IND=25
..........G EREND
W /WSCRON
W /WT(" New window ")
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Scroll mode OFF: only displayed 10
.......... lines",/EL(0),/SGR W /WUSE(2)
H 1 W /WSC(1)
F I=1:1:15 W I,", set to scroll off.",!
H 5 W /WSC(0)
W /WUSE(3) W /CUP(1,3),/SGR(1),"Change to Scroll mode ON ",/EL(0),/SGR
.......... W /WUSE(2)
F I=1:1:15 W I,", set to scroll on.",!
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Clear in memory window, all first
..........line, from position (1,10) to end of 2nd. line, and from (2,7) to begi
..........n of 3rd.line ",/EL(0),/SGR W /WUSE(2)
W /CUP(0,0),/WSCROFF,/WCML(2),/CUP(1,10),/WCML(0),/CUP(2,7),/WCML(1)
H 5 W /WUSE(3) W /CUP(3,3),/SGR(1),"NOW previous lines must be REMOVED
.......... in WINDOW",/EL(0),/SGR W /WUSE(2)
W /WSCRON
H 5 W /WUSE(3) W /CUP(1,3),/SGR(1),"Underline window title ",/ED(0),/S
..........GR W /WUSE(2)
W /WTSGR(4) H 4
W /WUSE(3) W /CUP(1,3),/SGR(1),"Close window # 2 ",/EL(0),/SGR W /WUSE
..........(2)
W /WCLOSE(2) I +$D S MSG="unable to close window #2. $DEVICE= "_$D,IND
..........=30 G EREND

Routine: WNSAMPLE UCI: MGR,SYS Date/Time: 19-FEB-93, 12:07 PM Page: 1-2
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Use previous window, and refresh i
..........t ",/EL(0),/SGR W /WUSE(1)
W /WREFRESH I +$D S MSG="unable to refresh window #1. $DEVICE= "_$D,IN
..........D=35 G EREND
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Clear window from begin window to
..........position (3,4) ",/EL(0),/SGR W /WUSE(1)
W /CUP(3,4),/ED(1)
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Clear window from position (6,25)
..........to end of window",/EL(0),/SGR W /WUSE(1)
W /CUP(6,25),/ED(0)
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Clear all window in memory",/EL(0)
..........,/SGR W /WUSE(1)
W /WSCROFF,/WCMD(2)
H 5 W /WUSE(3) W /CUP(1,3),/SGR(1),"Display cleared window",/EL(0),/SG
..........R W /WUSE(1)
W /WSCRON
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Write a message in position (5,5)
..........",/EL(0),/SGR W /WUSE(1)
H 1 W /CUP(5,5),"Message in position (5,5)",!
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Move window",/EL(0),/SGR W /WUSE(1
..........)
W /WMOVE(10,10) I +$D S MSG="unable to move window. $DEVICE= "_$D,IND=
..........40 G EREND
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Write a sentence in blinking",/EL(
..........0),/SGR W /WUSE(1)
W /SGR(5),"Blinking sentence in a moved window.",!,/SGR I +$D S MSG="u
..........nable to change window attributes /SGR. $DEVICE= "_$D,IND=45 G EREND
H 4 w "Changing different attributes",!
W /WUSE(3) W /CUP(1,3),/SGR(1),"Restore title to normal attributes",/E
..........L(0),/SGR W /WUSE(1)
H 2 W /WTSGR(0)
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Change to reverse window border",/
..........EL(0),/SGR W /WUSE(1)
H 1 W /WBSGR(7)
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Set current window from (5,5) posi
..........tion to end of line UNDERLINED",/EL(0),/SGR W /WUSE(1)
H 1 W /CUP(5,5),/WCSGR(4,1)
H 2 W /WUSE(3) W /CUP(1,3),/SGR(1),"Set default reverse window",/EL(0)
..........,/SGR W /WUSE(1)
H 1 W /WDSGR(7)
H 4 W /WDSP I +$D S MSG="unable to reverse the attributes. $DEVICE= "_
..........$D,IND=50 G EREND
W /WUSE(3) W /CUP(1,3),/SGR(1),"Position cursor in (5,10), and erase r
..........est of line.It must appear in reverse.",/EL(0),/SGR W /WUSE(1)
H 2 W /CUP(5,10),/EL(0)
H 4
END W /END U 0::"" Q
EREND W MSG S ^TEST("WSAMPLE",IND)=MSG W /END U 0::"" Q^L

APPENDIX G
USER DEFINED COMMANDS

This appendix describes how to write user defined commands, functions,
and special variables in MSM.
G.1 Commands, Functions, And Special Variables

The MSM system provides a mechanism that allows system
administrators to define their own Commands, Functions, and Special
Variables. This allows the system administrator to extend the MUMPS
language where special functionality is needed. This can often be useful
when converting from another dialect of MUMPS to MSM.
All user defined Commands, Functions, and Special Variables must

begin with a prefix of ZZ (e.g., ZZMYCMD, ZZMYFUNC, etc. The
syntax for these 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. When invoking the command
or function or referencing the special variable, the entire name must be
specified. 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 (i.e., MGR) on the system volume group (i.e., volume
group 0). When a user defined command, function or special variable
is encountered by the system, the appropriate routine will be invoked at
the Uname label (i.e., 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 will be
considered undefined.
User Defined Commands G-1

When a user defined command is encountered, internally the system will
issue a DO command to the appropriate entry reference (i.e.,
Uname^%ZZCMNDS). The line labels for commands may not contain
a formal list. For functions and special variables, the appropriate entry
reference (i.e., Uname^%ZZFUNCS or Uname^%ZZSVARS) will be
invoked as an extrinsic function or extrinsic variable. Therefore, the
line label must end in ( ) in order for the function or special variable to
return a value.
G.2 Passing Parameters To The Routine

When parameters are specified on user defined commands or functions,
they are passed to the MUMPS 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. Then, $1 corresponds to the first parameter, $2
corresponds to the second parameter, etc. Omitted parameters are passed
as the null string. These internal variables are read-only and can not be
modified by the user routine. For user defined special variables, the
value of $0 is always 0 (zero).
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 done 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. User defined special variables behave like user
defined functions; however, parameters may not be specified.
G.3 Sample User Defined Command

The following is an example of a user defined command. The same type
of constructs are used for user defined functions and special variables.
%ZZCMNDS ;User Defined Commands; [ 02/04/93 4:18 PM ]
;
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
G-2 User Defined Commands

GLOSSARY
ANSI
The American National Standard Institute.
Argument
An expression which controls what action will take place in the

function or command with which it is used.
Array
An organized set of local or global elements or nodes which are

referenced by subscripts and a common variable name.
ASCII
The American Standard Code for Information Interchange. This
code consists of 128 characters which comprise the standardized
character set.
Background Job
A job that was started by the JOB command. This process runs
in parallel with the process which contained the JOB command.
Baud
A term which describes the data transmission rate between two

devices.
Big-Endian
Describes the bit ordering of integer values when they are stored
in memory. In Big-Endian format, the most significant digits
precede the least significant digits.
Break
A command used to interrupt program execution so that debugging

may take place.
Glossary-1
Canonic Number
A numeric value which has no leading or trailing zeros after the
decimal point.
Carriage Return
A keyboard instruction, often used to indicate the end of a
command. This key is commonly marked RETURN, ENTER, or
CR.
Collating Sequence
An order that is assigned to a grouping of subscripts. This sorting
can be done in either string or numeric sequence.
String - 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 found within the body of a routine which describes

when the routine was written, what the routine does, etc. This is
a non-executable line of code that begins with a semicolon (;).
Compiler
The language compiler is a highly sophisticated system program

that scans each line of MUMPS code, divides it into basic
components, analyzes each component to insure 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 operand
1 by use of the underline (_) symbol.
2-Glossary
CONFIG.MSM
A file found in the root directory or the local directory which
contains information about the MSM system you are running.
When MSM is started, this file is read to determine how MSM is
to be setup.
Configuration
The collection of hardware and software that comprises the entire
computer system.
Control Characters
Characters from the standard ASCII set which have special

meaning to the MSM system. These characters are obtained by
depressing the control key (usually marked CTRL) at the same
time that the associated control character is depressed.
Cursor
The on-screen marker, usually a box or an underline, which
indicates the location where the next data entry will occur.
Data
The information (letters, numbers, symbols) that is entered into
the system for processing or storage.
Database
The location where storage of the data takes place in global arrays.
In MSM, this is where the MSM system has been installed
(database 0).
Default
The value which is assumed as the entry to a prompt if the carriage
return is depressed. In MSM default values are displayed within
greater than and less than signs, (<DEFAULT>).
Glossary-3
Descendant
Any array node on a lower subscript level which is reachable from
that node and shares the first ’x’ subscripts in common. An
example would be the nodes R(3,4,5) and R(3,6,4,7), which 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 is considered a device.
Expression
A character string which yields a value upon execution.
Function
An action which gives the user the ability to perform routine

operations in a more efficient manner. In MSM, a function begins
with a dollar sign ($) or with a dollar sign and the letter Z ($Z) for
specialized MUMPS functions.
Global
The permanent storage medium utilized by MUMPS. The
information is stored in a global array or a simple global variable
and is generally placed on a disk system.
Global Variable
A reference name for data stored in a global on the disk. These
variables are accessible or changeable by any user on the system
with the proper protection level.
Hardware
The physical components of the computer system other than the

software; for example, the computer itself (monitor, disk drive,
etc.), the tape drive, and the printer.
4-Glossary
Indirection
A method of using the value of an expression rather than the
expression itself. The symbol used to indicate that indirection is
being used is the at-sign (@), followed by the value which
represents the expression.
I/O Supervisor
The section of MSM responsible for the input, error detection,
error correction, and output operation of each device attached to
the system. For each device type, the I/O supervisor coordinates
all data transfers and synchronizes them with job execution.
Interpreter
That part of the MSM system that processes the pseudo-machine
code which has been generated by the compiler.
Job
Any use of the MSM system which 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 if necessary. This option does
not apply to single-user versions of MSM.
LAT
A Local Area Transport protocol developed by Digital Equipment
Corporation to support networked terminals and printers.
Line
A string of characters ending with a specified read terminator (i.e.,

carriage return/line feed).
Line Label
An optional name at the start of a routine line which identifies the
line to the system. This label is limited to eight characters and
must begin with an alphabetic or percent (%) character.
Glossary-5
Literal
A string, enclosed in quotations, which can be acted upon but not
changed by a command. The literal may contain any valid ASCII
character; however, certain of these may be excluded because they
have special meaning to the MSM system.
Little-Endian
Describes the bit ordering of integer values when they are stored
in memory. In Little-Endian format, the least significant digits
precede the most significant digits.
Local Variable
Any variable that exists within memory only. These variables are
unique to a particular user and are valid only for the duration of
the user’s login.
Map
The space allocated for disk storage. Each map consists of 512
blocks (each 1024 bytes in size).
Modem
Acronym for MOdulator DEModulator. This device is used to
convert data to a form which can be transmitted via a phone line
to a remote site, and then re-converted to a form usable by the
remote site processing system.
MUMPS
Acronym for Massachusetts General Hospital Utility
Multi-Programming System. This system was developed in the
late 1960s to handle storage, retrieval, and manipulation of large
amounts of medical data. It is one of only four ANSI standard
languages.
Naked Reference
A shortcut method for referring to a particular global node. The
naked reference can generally be used wherever a global reference
is permitted. The naked reference can be specified for a previously
referenced node by using a circumflex (^), followed by the unique
portion of the descendant’s subscript.
6-Glossary
Node
That element of a global array addressed by the name common to
all members of the array and a unique subscript.
Operating System Monitor
That system which 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 the overall efficiency and throughput of the system.
Programmer Access Code (PAC)
The three letter designation which must be entered in order to gain

access to programmer mode. One PAC can be specified for each
configuration on the system.
Parameters
The collection of guidelines for the usage of a particular device.
Partition
The area of memory which consists of a logical grouping of the

local symbol table, the current routine edit buffer, and the work
areas used by the system and the job. This space will grow and
shrink based upon the requirements of the current job.
Peripherals
A collection of devices, both physical and logical, which are
associated with the MSM system. These can be used to gain access
to printers, terminals, and sequential devices, as well as for
examining or modifying memory contents or alternate disk
storage.
Programmer Mode
The mode which permits the user to directly enter MUMPS

commands to the interpreter. Access is gained through entry of a
valid UCI and PAC.
Prompt
A message issued by the system which requires input by the user.
Glossary-7
Remote Volume Group
A Volume Group which belongs to a remote system, but is
mounted for use on the local system. The Volume Group is
accessed through DDP.
Routines
Library Routines - That group of utility programs accessible to all
users on the system.
System Manager Routines - Those routines that are only accessible
via the manager’s UCI.
Run Mode
The method used to directly access a routine in a particular UCI.

Access is gained by entry of a valid UCI and routine name stored
in that UCI.
Sparse Array
An array which contains space only for those elements which are
actually defined.
Special Variables
A group of variables ($ZA, $ZB, and $ZC) which have special
meaning to the MSM system. These variables are used to indicate
status information about the results of the last operation
performed.
Stack
That area of the MSM system set aside for nesting of subroutines
resulting from execution commands.
Stap
The area of the MSM system set aside for complex expression
nesting.
String
Any set of ASCII characters with a maximum length of 255
characters.
8-Glossary
String Literal
A string of characters enclosed in double quotes within the context
of a line.
Subroutine
A collection of commands which together allow control to pass
from the routine to the subroutine and back to the main routine.
Subroutines are generally used where multiple recurring tasks are
required for execution of the main routine.
Subscripts
A numeric or string interpreted value appended to a local or global

variable used to identify a specific element or node in an array.
Subscripts must be enclosed in parentheses and are separated by
commas when more than one is indicated.
SYSGEN
The system generation utility used to specify one or more
configurations to the MSM system. These configurations are used
by the system at startup to initialize the system with the defined
parameters. This is done via an interactive dialogue with MSM
which supports on-screen help for any prompted value.
Terminators
The specified set of control characters which are used to terminate

a read operation. MSM uses a default value of line feed, carriage
return (i.e., $C(10,13), but permits the user to alter this value
through use of proper parameters associated with the current
device.
Tied Terminal
The mode used to force a particular terminal to automatically start
up a particular routine in a specified UCI.
Glossary-9
Timeout
A timing convention which allows the user to specify how long
the system should attempt to perform a given command before
proceeding. It is expressed in the format of a colon (:), followed
by an integer which is then appended to a READ, OPEN, or JOB
command.
User Class Identifier (UCI)
The three letter designation (upper case) for a work area within
the MSM system. Each UCI created has its own unique routine
and global directory.
Utilities
Library Utilities - A group of utilities used to aid in the
development of application programs where commonly
performed functions are required.
System Manager Utilities - Those utilities intended for use by the
system manager to ensure proper performance of the system.
These can be accessed only from the manager’s UCI.
Variable
A symbolic name for a location where data is stored. In MSM
there are three type of variables:
Local Variables - Those variables stored in memory only.

Global Variables - Those variables stored in arrays for permanent
storage on disk.
Special Variables - Those variables which hold special meaning
to the MSM system.
Volume Group (VolGroup)
A string value that specifies a three uppercase character volume

group name.
Volume Number (VolNum)
A numeric expression that specifies an internal volume group

number.
10-Glossary
INDEX
$HOROLOG, 4-4, 4-5, 4-10 Access Modes
$IO, 3-4 HFS Devices, 3-33
$JOB, 3-4 Magnetic Tape, 3-43, 3-44
$VIEW Function, 3-28 Accessing Devices, 3-4
$X Variable, 3-6 Active Jobs
$Y Variable, 3-6 %ACTJOB Utility, 4-4
$ZA Values After-Image Journaling, 6-16,
HFS Devices, 3-35 8-4, 8-5
Host System Spool, 3-61 Angle Brackets
IJC Devices, 3-39 See Chapter 4
Magnetic Tape, 3-50 ANSI Standard, 1-1
SBP Devices, 3-26 ANSI Type Terminals, 3-12
Spool Device, 3-57 ANSI X3.64-1979
Terminal Devices, 3-20 Mnemonic Namespaces, 3-7,
$ZB Values F-1
HFS Devices, 3-35 Application Loading
Host System Spool, 3-61 Appendix C
IJC Devices, 3-39 Arrays, Sparse, 1-4
Magnetic Tape, 3-51 ASCII Characters, 2-1, 3-2, 3-6,
SBP Devices, 3-26 3-11, 3-44
Spool Device, 3-57 ASCII Collating Sequence, 6-2
Terminal Devices, 3-20 ASYNC Error, A-3
$ZC Values Asynchronous Error
HFS Devices, 3-35 See ASYNC Error
Host System Spool, 3-61
Magnetic Tape, 3-51 Backspace Block, 3-48
SBP Devices, 3-26 Backward Space Tape, 3-49
Spool Device, 3-57 Baud Rate
Terminal Devices, 3-21 Terminals, 3-15, 3-16
$ZERROR, 2-14 - 2-16, 2-18 Baud Rate Setting
$ZREFERENCE, 2-18 SETBAUD Utility, 4-13
$ZTRAP, 2-14 - 2-18 Before-Image Journaling, 6-16
$ZTRAP Variable, 2-15 Buffers, 8-2
Concepts, 8-2, 8-3
%DEBUG Utility, 2-19 Files, 8-2
%ER Utility, 2-18 Generations, 8-2
%ET Utility, 2-14, 2-18 BIJ Status Block, 6-4
%GCH Utility, 6-3, 6-16, 8-4 BIJ Utility, 8-3
%HELP Utility, 4-3 BKERR Error, A-3
Block Dump
Index-1
BLKDMP Utility, 4-11 %GCH Utility, 4-6
Block Offset Change Global Values
SBP Devices, 3-24 %GCHANGE Utility, 4-6
Block Types Changing Job Priority
BIJ Status Block, 6-4 %HL Utility, 4-7
Data, 6-4, 6-10, 6-11 Changing UCIs, 2-7
Global Directory, 6-4, 6-7, Character Echo, 3-14
6-9 Checksums, 4-4
Journal, 6-4 %CHKSUM Utility, 4-4
Label, 6-4 Circumflex, 1-4, 2-6, 2-13, 4-4,
Map, 6-4, 6-6 A-2
OLB Status Block, 6-4 See Chapter 4
Pointer, 6-4, 6-9 Clobber Error
Routine Block, 7-4 See CLOBR Error
Routine Data, 6-4, 7-1, 7-2 CLOBR Error, A-3
Routine Directory, 6-4, 7-1 CLOSE Command
Routine Header, 6-4, 7-1 - 7-3 HFS Devices, 3-32
SBP, 6-4 Host System Spool, 3-60
Spool Data, 6-4 IJC Devices, 3-38
Spool Directory, 6-4 Magnetic Tape, 3-43
UCI Directory, 6-4 Routine Interlocks, 3-41
Boldface Type, xii SBP Devices, 3-24
Bottom-Level Pointer, 6-9, 7-2 Spool Device, 3-54
BREAK Terminal Devices, 3-8
Key, 2-2 VIEW Device, 3-28
Levels, 2-19 CMMND Error, A-3
Recognition, 2-13 Collating Sequence, 6-2, 6-3
Break Error Command Error
See BKERR Error See CMMND Error
Broadcast A Message Commands
BCS Utility, 4-11 CLOSE, 3-8, 3-24, 3-28,
Buffer Cache, 1-5, 6-5 3-32, 3-38, 3-41, 3-43, 3-54,
Buffer Mode 3-60
HFS Devices, 3-33 Input And Output, 3-5
Magnetic Tape, 3-44 LOCK, 5-1, 5-6
Buffer Offset OPEN, 3-8, 3-24, 3-28, 3-32,
HFS Devices, 3-34 3-38, 3-41, 3-43, 3-54, 3-60
Magnetic Tape, 3-47 READ, 3-4, 3-5, 3-7
USE, 3-8, 3-24, 3-28, 3-32,
Cache, Buffer, 1-5 3-38, 3-43, 3-54, 3-60
Canonic Numbers, 6-2, 6-3 User-Defined, G-1, G-2
Change Global Characteristics VIEW, 3-28, 5-2
2-Index
WRITE, 3-4, 3-5, 3-7, 3-11 Copying Globals
Common Utility Routines, 4-4 %GCOPY Utility, 4-6
Communication Failure Creating Routines, 2-8
See MSMCX Error Cross-System Global
Compile Routines, 1-3 Reference, 6-15
%RELOAD Utility, 4-9 Cross-System Journaling, 6-16,
Compression, 6-7, 6-9 8-7
Control Blocks Cross-UCI Global
Device Descriptor Block, 5-2, Reference, 6-14
5-12 Cross-Volume Global
Lock Table, 5-1, 5-6 Reference, 6-14
PVECTOR, 5-1, 5-4 CTRL
SVECTOR, 5-1, 5-2 See Control Characters
UCI Table, 5-2, 5-10 CUA Full Screen Editor
Volume Group Table, 5-1, 5-8 Invoking, E-1
Control Characters, 2-1 - 2-3, Overview, E-1
3-11 Cursor Positioning, 3-13
Backspace, 2-2
Break, 2-2 Data Bits
CTRL/C, 2-2 Terminals, 3-15, 3-16
CTRL/H, 2-2 Data Block, 6-4, 6-10, 6-11
CTRL/I, 2-2, 2-3 Data Element, 6-11
CTRL/J, 2-3 Data Length
CTRL/L, 2-3 Terminals, 3-11
CTRL/M, 2-2, 2-3 Database Integrity
CTRL/O, 3-11, 3-14 VALIDATE Utility, 4-14
CTRL/Q, 2-3, 3-14 VERIFY Utility, 4-14
CTRL/R, 2-3 Database Maintenance
CTRL/S, 2-3, 3-14 DBMAINT Utility, 4-12
CTRL/U, 2-3 Database Management System,
CTRL/X, 2-3 1-3
DEL, 2-2 Database Repair
ESC, 2-2 DBFIX Utility, 4-11, 4-12
RET, 2-2, 2-3 Date And Time
TAB, 2-2, 2-3 %D Utility, 4-4
Control Key, xii, 2-1 %T Utility, 4-10
Control Terminal Functions, DDB
3-10 See Device Descriptor Block
Conventions DDP
Documentation, xii See Distributed Data
Convert Hex To Decimal Processing
%HD Utility, 4-7
Index-3
DDP Link Failure Disk Block Number
See DSTDB Error HFS Devices, 3-34
DDP Server Error SBP Devices, 3-25
See DDPER Error Disk Buffers, 6-5
DDPER Error, A-3 Disk Database, 6-3
Decimal To Hex Disk Full Error
%DH Utility, 4-5 See DKFUL Error
Defining UCIs Disk Hard Error
See MSM System Manager’s See DKHER Error
Guide Disk Map
Delete Characters, 2-2 DISKMAP Utility, 4-12
Delete Globals Display Error Codes
%GDEL Utility, 4-6 %ERRCODE Utility, 4-5
Delete Input Line, 2-3 Display Error Log
Delete Routines %ER Utility, 4-5
%RDEL Utility, 4-9 Distributed Data Processing,
Deleting Lines, 2-10 6-15
Deleting Routines, 2-12 DDP Utility, 4-12
Delimiter String DIVER Error, A-3
Magnetic Tape, 3-46 Divide Error
Destination Code See DIVER Error
Spool Device, 3-55, 3-56 DKFUL Error, 6-12, A-4
Device Characteristics DKHER Error, 3-25, 3-26, 3-29,
Terminals, 3-10 3-33, A-4
Device Descriptor Block DKRES Error, A-4
Layout, 5-2, 5-12 DKSER Error, 6-7, A-4
Device Designators, 3-3 DO, 2-13
Device Not Open Error Do Command
See NOPEN Error See Chapter 4
Device Parameters Documentation
See OPEN/USE Parameters Conventions, xii
Device Selection Downlevel Error Trapping, 2-18
%SDEV Utility, 4-10 DPARM Error, A-4
Device Special Variables DSCON Error, A-4
See $X, $Y, $ZA, $ZB, And DSTDB Error, A-4
$ZC DTR Signal, 3-13
Directory Dump And Restore
Routine, 7-1 MSMDR Utility, 4-13
Disallowing Logons
Terminals, 3-13 EBCDIC Character Set, 3-44
Disconnect Error Echo Characters
See DSCON Error %ECHO Utility, 4-5
4-Index
Terminal Devices, 3-14 Extended Global Directory List
Editing Routines, 2-9 %GDE Utility, 4-6
Editing Specific Lines, 2-11 Extended Global Reference,
Editors 6-14, 6-15
Global Editor (%GEDIT), 4-6 External To Internal Date
Efficiency Of Globals %DI Utility, 4-5
%GE Utility, 4-6 External To Internal Time
Empty Line Delete, 3-11 %TI Utility, 4-10
Environmental Flags
%MODESET Utility, 4-8 Fast Global Restore
Erase Tape, 3-49 %FGR Utility, 4-5
Error Codes Fast Global Save
%ERRCODE Utility, 4-5 %FGS Utility, 4-5
Error Conditions File Designator
Appendix A Spool Device, 3-55
Error Messages, xii, A-3, A-4, File Listing
A-6 - A-8 %FLIST Utility, 4-5
Format, A-1 File Name
Error Numbers, A-9 - A-12 DOS, 3-33
Error Trapping, 2-13 Unix, 3-33
DO/XECUTE Level, 2-15 VMS, 3-33
Down Level, 2-18 File Number
Error Conditions, A-1 Spool Device, 3-55, 3-56
Interactive Debugging, 2-19 File Offset
Standard, 2-14 HFS Devices, 3-34
System Supplied, 2-18 Fixed Length READ
User Defined, 2-15 Terminals, 3-9
Escape Processing, 2-2, 3-11, Fixed Length Records
3-13, 3-18, 3-20, 3-21 Magnetic Tape, 3-44
Examine A Job Flow Control
JOBEXAM Utility, 4-12 Terminals, 3-15, 3-16
Executing Routines, 2-13 Flush Input Buffer, 3-10
Execution Traceback, A-2 Form Feed, 2-3
Exit Message, 2-4, 2-8 Forward Space Block, 3-48
Expansion Areas Forward Space Tape, 3-49
Global, 6-12 Free Space
EXPER Error, A-4 %SP Utility, 4-10
Exponentiation Error Full Screen Editor, 2-11
See EXPER Error See also CUA Full Screen
Editor
Index-5
Commands, D-2 Save (%GS), 4-7
Cursor Movement, D-2, D-4 Search (%GSE), 4-7
Delete Commands, D-10 Select (%GSEL), 4-7
Editing Commands, D-7 Global Directory Block, 6-4,
Invoking, D-1 6-7, 6-9
Mark Commands, D-9 Global Expansion Areas, 6-12
Miscellaneous Commands, Global Name
D-13, D-14 Definition, 6-2
Overview, D-1 Global Organization, 6-12, 6-13
Scrolling Commands, D-5, Global Protection, 6-16
D-6 Global Reference
Search Commands, D-11 Cross-System, 6-15
Summary Of Commands, Cross-UCI, 6-14
D-15 Cross-Volume, 6-14
Transfer/Copy Commands, Global Select
D-12 %GSEL Utility, 4-7
FUNCT Error, A-4 Global Size
Function Keys, 3-19 %GSIZE Utility, 4-7
Functions Global Transfer
User Defined, G-1, G-2 %TRANS Utility, 4-11
$VIEW, 3-28, 5-2 Global Variables, 1-3, 1-4
Collating Sequence, 6-2
Generating The System Overview, 6-1
SYSGEN Utility, 4-14 Usage, 6-1
Global
Changing Values HALT, 2-8
(%GCHANGE), 4-6 Hardcopy Devices
Characteristics (%GCH), 4-6 Terminals, 3-14
Copy (%GCOPY), 4-6 Help Information
Delete (%GDEL), 4-6 Utilities, 4-3, 4-7
Directory List (%GD), 4-6 HFS
Editor (%GEDIT), 4-6 See Host File Server, 3-31
Efficiency (%GE), 4-6 Host Commands
Extended Directory List %HOSTCMD Utility, 4-7
(%GDE), 4-6 Host File Listing
Fast Restore (%FGR), 4-5 %FLIST Utility, 4-5
Fast Save (%FGS), 4-5 Host File Server, 3-31
List (%G), 4-6 $ZA Values, 3-35
List (%GL), 4-6 $ZB Values, 3-35
Maintain (GBMAINT), 4-12 $ZC Values, 3-35
Place (GBPLACE), 4-12 Device Numbers, 3-3
Restore (%GR), 4-7 Examples, 3-36
6-Index
Ownership Commands, 3-32 Interpreter
Host System Spool P-Code, 1-3
$ZA Values, 3-61 Interrupt Error
$ZB Values, 3-61 See INTRP Error
$ZC Values, 3-61 Interrupts
Device Numbers, 3-3 Terminals, 3-12
Examples, 3-62 Invalid Negative Number
Ownership Commands, 3-60 See MINUS Error
Invalid P-Code Error
I/O Supervisor, 1-5 See PLDER Error
IJC IRQ Levels
See Interjob Communication, STUIRQ Utility, 4-14
3-37 Issuing Host Commands
INDER Error, A-5 %HOSTCMD Utility, 4-7
Index Routines ISYNT Error, A-5
%INDEX Utility, 4-7
Indirection Error Job Priority
See INDER Error %HL Utility, 4-7
INHIB Error, A-5 Journal Block, 6-4
Initialization Values Journal Maintenance
Terminals, 3-15, 3-16 JRNL Utility, 4-12
INRPT Error, A-5 Journaling
Insert Error After-Image, 8-4, 8-5
See ISYNT Error Before-Image, 8-2, 8-3
Inserting Lines, 2-10 BIJ Utility, 8-3
Inspect Memory, 3-28 Cross-System, 8-7
Integrity Checker JRNL Utility, 8-5, 8-8
VALIDATE Utility, 4-14 OLB Utility, 8-10
VERIFY Utility, 4-14 JRNL Utility, 8-5, 8-8
Interactive Debugging, 2-19
%DEBUG Utility, 4-4 Killing A Job
Interjob Communication KILLJOB Utility, 4-12
$ZA Values, 3-39
$ZB Values, 3-39 Label Block, 6-4
$ZC Values, 3-39 Label Processing, 3-48, 3-49
Device Numbers, 3-3 Labeled Tape, 3-44
Examples, 3-40 Language Compiler, 1-3
Ownership Commands, 3-38 LAT
Internal To External Date See Local Area Transport
%DO Utility, 4-5 Layout Of System Tables
Internal To External Time See Chapter 5
%TO Utility, 4-10
Index-7
LCNSE Error, A-5 $ZB Values, 3-51
Library Utilities, 4-3 $ZC Values, 3-51
License Error %MTCHK Utility, 4-8
See LCNSE Error Access Modes, 3-44
Line By Line Editor, 2-11 Device Numbers, 3-3
Edit Specific Lines, B-2 Examples, 3-52
Overview, B-1 Ownership Commands, 3-43
Special Functions, B-4 - B-8 WRITE Commands, 3-47,
Line Carrier, 3-13 3-48
Line Error Magnetic Tape Error
See LINER Error See MTERR Error
Line Feed, 2-3, 3-12 Maintenance Routines, 1-6
Line Labels, 2-10 Major Number, A-1
LINER Error, 2-10, A-5 Map Block, 6-4, 6-6
List Global Directory Map Block Error
%GD Utility, 4-6 See MAPER Error
List Globals Map Control Plocks
%G Utility, 4-6 MAPnnn Utilities, 4-13
%GL Utility, 4-6 MAPER Error, A-5
Loading Applications Mathematical Functions
Appendix C %MFUNC Utility, 4-8
%PACKAGE Utility, 4-8 Maximum Memory Error
Loading Routines, 2-9 See MXMEM Error
Local Area Transport, 2-1 Maximum Number Error
Local Variables, 1-3 See MXNUM Error
Lock Table Maximum String Error
Layout, 5-1, 5-6 See MXSTR Error
Logging Errors Memory Dump
%ET Utility, 4-5 %MDMP Utility, 4-8
Logging Off The System, 2-8 Merge Command Error
Logging Onto The System, 2-4 See MERGE Error
- 2-6 MERGE Error, A-5
%LOGON Utility, 4-8 Messages
Logical Record Length Between Jobs, 3-37
Magnetic Tape, 3-46 Minor Number, A-1
Lost Block Recovery MINUS Error, A-5
RECOVER Utility, 4-13 Minus Sign
Lower Case Setup See Chapter 4
Terminals, 3-12 Mnemonic Controls, 3-7, F-1
Mnemonic Namespaces, 3-7
Magnetic Tape, 3-42 ANSI X3.64-1979, 3-7, F-1
$ZA Values, 3-50
8-Index
ZWINTERM, 3-7, F-5 No Journal Allowed
Mode Error See NOJRN Error
See MODER Error No Open Error
Mode Flags See NOPEN Error
%MODESET Utility, 4-8 No Program
SWREG Utility, 4-14 See NOPGM
Mode Switches No Program Error
VIEW Device, 3-29 See NOPGM Error
Modem Control, 3-14 No System Error
MODER Error, 3-45, 3-49, A-5 See NOSYS Error
Modes No UCI Error
Programmer, 2-5, 2-13 See NOUCI Error
Run, 2-6, 2-13 NODEV Error, 3-38, A-6
Tied Terminal, 2-6 NOJRN Error, A-6
Modify Disk Blocks, 3-28 NOPEN Error, 3-21, 3-33, A-6
Monitor, Operating System, 1-4 NOPGM Error, 2-9, A-7
Monitoring A Job NOSYS Error, 6-15, A-7
PEEK Utility, 4-13 NOUCI Error, 6-14, A-7
Mouse Control Null Characters, 3-44
%MOUSE Utility, 4-8
MSM System OLB Status Block, 6-4
Database Management, 1-3 OLB Utility, 8-10
Functional Description, 1-2 Omitted Items, xii
I/O Supervisor, 1-5 OPEN/USE Parameters
Language Compiler, 1-3 HFS Devices, 3-32
Operating System Monitor, Host System Spool, 3-60
1-4 IJC Devices, 3-38
Utility Program Library, 1-5 Magnetic Tape, 3-43
MSMCX Error, A-6 Routine Interlocks, 3-41
MTERR Error, 3-45, 3-50, A-6 SBP Devices, 3-24
MUMPS, 1-1 Spool Device, 3-54
Acknowledgement, xi Terminal Devices, 3-8
MXMEM Error, A-6 VIEW Device, 3-28
MXNUM Error, A-6 OPEN Command
MXSTR Error, A-6 HFS Devices, 3-32
Host System Spool, 3-60
NAKED Error, A-6 IJC Devices, 3-38
Naked Indicator Error Magnetic Tape, 3-43
See NAKED Error Routine Interlocks, 3-41
Namespaces,Mnemonic, F-1 SBP Devices, 3-24
No Device Error Spool Device, 3-54
See NODEV Error Terminal Devices, 3-8
Index-9
VIEW Device, 3-28 Pass All
Open Devices Terminals, 3-11
%DEVUSE Utility, 4-5 PCERR Error, A-7
Operating Modes Percent Character, 2-9
Programmer, 2-5, 2-13 Percent Editor, 2-11
Run, 2-6, 2-13 Percent Sign, 4-3
Tied Terminal, 2-6 See Chapter 4
Operating System, 1-1 Performance Monitor
Operating System Functions RTHIST Utility, 4-13
%OS Utility, 4-8 Peripheral Devices
Operating System Monitor, 1-4 Accessing, 3-4
Output Only Overview, 3-1
Terminals, 3-14 Using, 3-1
Overview PGMOV Error, A-7
MSM System, 1-1 Physical Block Size
Peripheral Devices, 3-1 Magnetic Tape, 3-46
Routine Structure, 7-1 Placing A Global
System Design, 1-1 GBPLACE Utility, 4-12
System Tables, 5-1 PLDER Error, A-7
Using The System, 2-1 Pointer Block, 6-4, 6-9
Ownership Commands Post Conditional Error
HFS Devices, 3-32 See PCERR Error
Host System Spool, 3-60 Print Routines
IJC Devices, 3-38 %RPRT Utility, 4-9
Magnetic Tape, 3-43 Processing Trapped Errors, 2-15
Routine Interlocks, 3-41 Program Editor
SBP Devices, 3-24 Edit Specific Lines, B-2
Spool Device, 3-54 Overview, B-1
Terminal Devices, 3-8 Special Functions, B-4 - B-8
VIEW Device, 3-28 Program Overflow Error
See PGMOV Error
P-Code, 1-3 Programmer Access Code, 2-5
PAC Programmer Mode, 2-5, 2-13
See Programmer Access Code Programmer Prompt, 2-5, 2-7,
Parameter Passing Error 2-8
See DPARM Error Prompted READ, 3-10
Parity PROT Error, 6-14, A-7
Terminals, 3-15, 3-16 Protection
Partition Size, 2-5 - 2-7, 5-4, 5-5 Classes, 6-16
%PARTSIZ Utility, 4-8 Global, 6-16
Partition Vector Protection Error
Layout, 5-1, 5-4 See PROT Error
10-Index
Pseudo-code, 1-3 Rewind Tape, 3-48
PVECTOR Right Link, 6-5, 6-12, 7-2
See Partition Vector Right Margin
Terminals, 3-9
Question Mark, 4-3 Routine
See Chapter 4 Change (%RCHANGE), 4-9
QUIT, 2-13 Compare (%RCMP), 4-9
Quotes, 2-10 Compile (%RELOAD), 4-9
Copy (%RCOPY), 4-9
Read Disk Blocks, 3-28 Delete (%RDEL), 4-9
READ Terminator Directory (%RD), 4-9
HFS Devices, 3-35 First Line List (%FL), 4-5
SBP Devices, 3-25 Print (%RPRT), 4-9
Terminal Devices, 3-11, 3-17 Restore (%RR), 4-9
Record Format Save (%RS), 4-9
HFS Devices, 3-34 Search (%RSAND), 4-9
SBP Devices, 3-26 Search (%RSE), 4-9
Recording Density Select (%RSEL), 4-10
Magnetic Tape, 3-45, 3-46 Size (%RSIZE), 4-10
Relative Block Numbers, 6-3 Routine Data, 6-4
Remote Volume Group, 6-15 Routine Data Block, 7-1, 7-4
Definition, 6-15 Routine Data Block Format, 7-2
Remove Lock Table Entry Routine Data Blocks, 7-1, 7-2
RECOVLK Utility, 4-13 Routine Data Structure, 7-1, 7-2
Repeated Items, xii Routine Directory, 6-4, 7-1
Replication, 6-15 Routine Editor Date
Replication Tables %NEWED Utility, 4-8
TRANSLAT Utility, 4-14 Routine Header, 6-4
Reprint Current Line, 2-3 Routine Header Block, 7-1 - 7-3
Reset A Terminal Device, 4-12 Routine Index
Resetting Device Values %INDEX Utility, 4-7
Terminals, 3-15 Routine Interlocks, 3-41
Resilient Systems Device Numbers, 3-3
See Chapter 8 Examples, 3-41
Restore Globals Ownership Commands, 3-41
%GR Utility, 4-7 Routine Transfer
Restore Routines %TRANS Utility, 4-11
%RR Utility, 4-9 Routines
Resume Output, 2-3 Creation Of, 2-8
Retension Tape, 3-49 Deleting From Disk, 2-12
Return Key, xii Deleting Lines, 2-10
Rewind And Unload Tape, 3-49 Editing, 2-9
Index-11
Executing, 2-13 Special Variables
Library $DEVICE, 3-7
See Chapter 4 $IO, 3-4
System Manager $JOB, 3-4, 5-5
See Chapter 4 $KEY, 3-7
Tied To A Terminal, 2-6 $X, 3-6, 3-12, 5-12
RS-232 Interface, 2-1 $Y, 3-6, 3-12, 5-12
Run Mode, 2-6, 2-13 $ZA, 3-6
$ZB, 3-6
Save Globals $ZC, 3-6
%GS Utility, 4-7 $ZERROR, 2-14 - 2-16, 2-18,
Save Routines A-1, A-2
%RS Utility, 4-9 $ZREFERENCE, 2-18
SBP Block, 6-4 $ZTRAP, 2-14 - 2-18, A-1,
SBP Devices A-2
$ZA Values, 3-26 Device Values, 3-6
$ZB Values, 3-26 User Defined, G-1, G-2
$ZC Values, 3-26 Spool Data, 6-4
Device Numbers, 3-3 Spool Device, 3-53
Examples, 3-27 $ZA Values, 3-57
Ownership Commands, 3-24 $ZB Values, 3-57
SBP Maintenance $ZC Values, 3-57
SBP Utility, 4-13 Device Number, 3-3
SBP Status Examples, 3-58
%SBP Utility, 4-10 Ownership Commands, 3-54
SBSCR Error, A-7 Spool Directory, 6-4
Search Globals Spooler Parameters
%GSE Utility, 4-7 Host System Spool, 3-60
Search Routines Spooling Maintenance
%RSAND Utility, 4-9 SPL Utility, 4-14
%RSE Utility, 4-9 Square Root
Select Device %SQRT Utility, 4-10
%SDEV Utility, 4-10 Stack Overflow Error
Select Routines See STKOV Error
%RSEL Utility, 4-10 Standard Error Processing, 2-14
Sequential Block Processor Standard Tape Labels, 3-44
See SBP Devices Status Information
Setting Up Tied Terminals HFS Devices, 3-35
See MSM System Manager’s Host System Spool, 3-61
Guide IJC Devices, 3-39
Slash Commands, 3-7, F-1 Magnetic Tape, 3-50
Sparse Arrays, 1-4 SBP Devices, 3-26
12-Index
Spool Device, 3-57 Language Compiler, 1-3
Terminal Devices, 3-20 Operating System Monitor,
STKOV Error, A-7 1-4
Stop Bits Utility Program Library, 1-5
Terminals, 3-15, 3-16 System Error
Stream Mode See SYSTM Error
HFS Devices, 3-34 System Error Trap, 2-18
Magnetic Tape, 3-45 System Manager Utilities, 4-3
SBP Devices, 3-26 System Shutdown
Structured Program Listing SSD Utility, 4-14
%INDSTR Utility, 4-8 System Startup
Subscript Error STU Utility, 4-14
See SBSCR Error System Startup Exit
Supported Terminals, 2-1 STUSER Utility, 4-14
Suspend Output, 2-3 System Tables
SVECTOR See Chapter 5
See System Vector System Vector
Syntax Error Layout, 5-1, 5-2
See SYNTX Error SYSTM Error, A-8
SYNTX Error, 3-25, A-8
System TAB Control, 3-12
Broadcast (BCS), 4-11 Tape Mark Errors
Dump And Restore Inhibit, 3-45
(MSMDR), 4-13 Tape Status
Examine Job (JOBEXAM), Update, 3-49
4-12 TCP/IP, 2-1
Free Space (%SP), 4-10 Terminal Control Characters
Generation (SYSGEN), 4-14 See Control Characters
Integrity (VALIDATE), 4-14 Terminal Devices, 3-8
Journaling (JRNL), 4-12 $ZA values, 3-20
Kill Job (KILLJOB), 4-12 $ZB values, 3-20
Lock Table (LOCKTAB), $ZC values, 3-21
4-13, 5-7 Device Numbers, 3-3
Map Control Blocks, 4-13 Escape Processing, 3-18
Overview, 1-1 Examples, 3-22
Performance (RTHIST), 4-13 Initialization Values, 3-15,
Status (%SS), 4-10 3-16
System Activity Ownership Commands, 3-8
COUNTERS Utility, 4-11 Terminal Emulator
System Components, 1-2 %XMIT Utility, 4-11
Database Management, 1-3 Terminals Supported, 2-1
I/O Supervisor, 1-5 Terminate Input, 2-2, 2-3
Index-13
Terminator Characters, 3-17 SBP Devices, 3-24
Text Buffer Size Spool Device, 3-54
Terminals, 3-17 Terminal Devices, 3-8
Tied Terminal Mode, 2-6 VIEW Device, 3-28
Time And Date User Class Identifier
%D Utility, 4-4 See UCI
%T Utility, 4-10 Manager’s
Timeout On Logon, 2-4 See Chapter 4
Top-Level Pointer, 6-9 User Error Processing, 2-15
TPROC Error, A-8 Using Peripheral Devices, 3-1
Transaction Error Utilities, 1-5
See TPROC Error Common Routines, 4-4
Translation Tables Library, 4-3
TRANSLAT Utility, 4-14 Supplied With System, 4-4
Trapping Errors System Manager, 4-3
See Error Trapping Utility Menu
Typeahead, 3-10 %UTL Utility, 4-11
Utility Program Library, 1-5
UCI, 2-4, 2-5 Utility Programs
Changing, 2-7 See Chapter 4
UCI Directory, 6-4 See MSM Utility Manual
UCI Maintenance Initiate Execution
UCIMGR Utility, 4-14 See Chapter 4
UCI Number Interrupt Execution
%GUCI Utility, 4-7 See Chapter 4
UCI Table Library, 4-4
Layout, 5-2, 5-10 Utility Routines
UCI Translation, 6-15 Conventions
UNDEF Error, A-8 See Chapter 4
Undefined Function Error
See FUNCT Error Variable Length Mode
Undefined Variable Error HFS Devices, 3-34
See UNDEF Error Magnetic Tape, 3-45
Unix lp Spooler, 3-60 SBP Devices, 3-26
Unlabeled Tapes, 3-45 Variables
Update $X and $Y Global, 1-3, 1-4, 6-1
Terminals, 3-12 Local, 1-3
USE Command Locking, 5-6
HFS Devices, 3-32 Video Buffer
Host System Spool, 3-60 %VIDEO Utility, 4-11
IJC Devices, 3-38 VIEW Command, 3-28
Magnetic Tape, 3-43 VIEW Device, 3-28
14-Index
Device Number, 3-3
Examples, 3-30
Ownership Commands, 3-28
VIEW Device Error
See VWERR Error
VIEW Error
See VWERR Error
VMS Print Spooler, 3-60
Volume Group
Table Layout, 5-1, 5-8
Volume Group Number, 3-25
VWERR Error, 3-49, A-8
Window Placement
Terminals, 3-18
Window Size
Terminals, 3-18
Write Tape Mark, 3-48
XECUTE, 2-11
Z Commands, 2-8
ZALLOCATE, 5-1, 5-6
ZINSERT, 2-10, 2-11
ZLOAD, 2-9, 3-5
ZPRINT, 2-10, 3-5
ZQUIT, 2-16
ZREMOVE, 2-9 - 2-12
ZSAVE, 2-12
ZUSE, 3-11
ZWRITE, 3-5
ZCALL Error, A-8
See ZCERR Error
ZCERR Error, A-8
ZSAVE Error, A-8
See ZSVGP Error
ZSVGP Error, A-8
ZWINTERM
Mnemonic Namespace, 3-7,
F-5
Index-15
16-Index

MSM-Micronetics Standart Mumps - User&#39;s Guide v.4.0 (Micronetics) 1997 Revised

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

MSM-Micronetics Standart Mumps - User&#39;s Guide v.4.0 (Micronetics) 1997 Revised

Uploaded by

Copyright:

Available Formats

MSM

MICRONETICS STANDARD MUMPS

The software described in this document is furnished under a license by

This manual is copyrighted. All rights are reserved. This document

CHAPTER 1 THE MSM SYSTEM

1.1 System Overview ..................................................... 1-1

CHAPTER 2 USING THE MSM SYSTEM

2.1 Supported Terminals ................................................ 2-1

2.9 Programmer Shell ..................................................... 2-19

CHAPTER 3 USING PERIPHERAL DEVICES

3.1 Overview .................................................................. 3-1

3.13 Magnetic Tape .......................................................... 3-42

CHAPTER 4 MSM UTILITY PROGRAMS

4.1 Using the MSM Utility Programs ............................ 4-1

CHAPTER 5 SYSTEM TABLES

5.1 Overview .................................................................. 5-1

6.1 Global Variables ....................................................... 6-1

6.2 The Disk Database ................................................... 6-3

CHAPTER 7 ROUTINE DATA STRUCTURE

7.1 Overview .................................................................. 7-1

CHAPTER 8 RESILIENT SYSTEMS

8.1 Overview .................................................................. 8-1

APPENDIX A ERROR CONDITIONS

A.1 Trapping MSM Errors .............................................. A-1

APPENDIX B THE MSM PROGRAM EDITOR

B.1 Overview of the Program Editor .............................. B-1

APPENDIX C LOADING APPLICATIONS

C.1 Overview .................................................................. C-1

APPENDIX D FULL SCREEN EDITOR

D.1 Invoking the Editor .................................................. D-1

APPENDIX E CUA FULL SCREEN EDITOR

E.1 Invoking the Editor .................................................. E-1

E.7 Search Menu ............................................................. E-10

APPENDIX F MNEMONIC NAMESPACES

F.1 X3.64-1979 Namespace ........................................... F-1

APPENDIX G USER DEFINED COMMANDS

G.1 Commands, Functions, and Special Variables ......... G-1

GLOSSARY .................................................................... Glossary-1

INDEX ............................................................................. Index-1

Table 2-1 Control Characters .......................................... 2-2

Table B-1 Program Editor Functions .............................. B-4

Figure 1-1 MSM System Components ............................. 1-2

Micronetics Standard MUMPS (MSM) is a full implementation, with

The following describes the various documentation conventions that are

CTRL/x The Control key pressed at the same time as

<ERROR> An MSM error message.

’val’ In HELP messages, ’val’ is used to indicate

> The MSM Programmer prompt.

••• The series of items repeats a user-specified

• Shows a break in a list where consecutive

BOLD Items in a dialogue are shown in bold to

1.1 System Overview

• Implementations that coexist with PC-DOS, MS-DOS,

• Includes Networking, Journaling, Interjob Communication,

The MSM System 1-1

1.2 Functional Description

Figure 1-1 - MSM System Components

MSM System Components

1-2 The MSM System

1.2.2 The Database Management System

The MSM System 1-3

An array is a collection of data stored under a common name. Subscripts

1.2.3 The Operating System Monitor

1-4 The MSM System

MSM-Micronetics Standart Mumps - User's Guide v.4.0 (Micronetics) 1997 Revised

MSM-Micronetics Standart Mumps - User's Guide v.4.0 (Micronetics) 1997 Revised