[Simh] OSs with accessible documentation
Tom Morris
tfmorris at gmail.com
Sat Feb 6 14:35:23 EST 2016
I don't know if the list allows attachments, but attached is the text
generated by tesseract 3.05 (current development head) out of the box for
the scanned image PDF here:
http://bitsavers.trailing-edge.com/pdf/dec/pdp15/DEC-15-GXZC-D_MUMPS_Apr72.pdf
No OCR is going to be good enough for applications like text-to-speech
without additional manual correction, but for the purposes of help search
engines find the PDFs in the first place and then easily searching within
them after they're found, I think the current generation of OCR is more
than adequate.
Tom
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.trailing-edge.com/pipermail/simh/attachments/20160206/a96120e0/attachment-0001.html>
-------------- next part --------------
programming language
M U M P S
Programming Language
llllllllll
First printing January 1971
Second printing October 1971
Revised April 1972
Information in this document is subject
to change without notice and should not
be construed as a commitment by Digital
Equipment Corporation.
Reproduction of this document in whole
or in any part is permitted.
For additional copies, order No. DEC—lS—GXZC—D from
Software Distribution Center, Digital Equipment
Corp ration, Maynard, Massachusetts, 01754
Price $4.00
FOREWORD
MUMPS (Massachusetts General Hospital gtility
Multi—Erogramming System) is a single-language
interactive time sharing system developed for
a medium scale computer.
This language was developed by the Laboratory
of Computer Science of Massachusetts General
Hospital andHarvaniMedical School, Boston,
Massachusetts. This development was supported
by research grants from the National Center for
Health Services Research and Development
(HS 00240) and from the National Institute of
General Medical Sciences (GM 15287). This
manual is adapted from a users' manual printed
by the Laboratory of Computer Science.
This edition of the MUMPS Programming Language
manual is a revision of manual number DEC—l5-GXZB—D.
Technical changes in the program as documented
have been marked with a solid line; editorial
changes have been marked with a broken line.
Examples:l
.IIIIII
Pages changed: ii, l-2, 4-5, 4-6, 4-10, Chapter 5
all pages, 6-3, 7-2, A—l, Readers Comments page.
The Index has been updated accordingly.
iii
INTRODUCTION
CHAPTER 1
CHAPTER
1.1
2
2.1
2.1.1
2.1.2
2.3
2.3.1
2.3.2
CONTENTS
BASIC LANGUAGE FEATURES
ARITHMETIC OPERATORS
OUTPUT - THE TYPE COMMAND
RECOVERY FROM TYPOGRAPHICAL ERRORS
NUMBERS IN MUMPS
PRECEDENCE OF ARITHMETIC OPERATORS
VARIABLES IN MUMPS - THE SET AND KILL COMMANDS
Subscripts
USE OF THE FOR CLAUSE
FORMAT CONTROL
WRITING MUMPS PROGRAMS
STEPS AND PARTS
Steps
Parts
THE DO STATEMENT
THE IF STATEMENT
Arithmetic Comparison Operators
Boolean Operators
MULTIPLE CLAUSES
BRANCHING -- THE GOTO COMMAND
THE QUIT COMMAND
INPUT -- THE ASK COMMAND
CHAPTER
CHAPTER
2.10
2.11
2.12
3
3.1
3.4
3.5
4
4.3
4.3.1
4.3.2
4.3.3
ERROR HANDLING
CREATING AND CHANGING A MUMPS PROGRAM
CHANGING OR DELETING LOCAL VARIABLES
SINGLE—LETTER COMMANDS
MULTIPLE COMMANDS ON A LINE
PROGRAM COMMENTS
PROGRAM DEBUGGING -- BREAK AND GO COMMANDS
STRING HANDLING OPERATIONS
STRING VARIABLES
STRING CONCATENATION (.)
STRING INPUT -- THE READ COMMAND
STRING COMPARISONS ( =. I. J.)
PATTERN VERIFICATION (:)
MORE ABOUT MUMPS PROGRAMMING
MUMPS PROGRAM LIBRARIES -- CALL AND OVERLAY
COMMANDS
INPUT/OUTPUT DEVICES
SECONDARY STORAGE
DECtape I/O
Paper Tape I/O
Saving Programs Using READ and WRITE Commands
SPECIAL (SYSTEM) VARIABLES
vi
4.5
SPECIAL COMMANDS AND COMMAND FORMS
4.5.1 The HANG and HALT Commands
4.5.2 More About the QUIT Command
4.5.3 More About the DO Command
4.5.4 UNTIL and WHILE Terminators in the FOR Clause
4.5.5 The PRINT Command
4.5.6 The XCOM Command
CHAPTER 5 USING FUNCTIONS IN MUMPS
5.1 NUMERIC FUNCTIONS
5.1.1 $ROOT(NVE)
5.1.2 $LENGTH(SVE)
5.1.3 $VALUEIS‘EI
5.1.4 $INTEGER(NVE)
5.1.5 $FIND(SVE1,SVE2,NVE)
5.1.6 $BOOLEAN(BOOL1,NVE1;BOOL2,NVE2;...;BOOLn,NVEn)
5.1.7 $DEFINE (variable name)
5.1.8 $NEXT(NVE)
5.1.9 $HIGH(VAR(SUBSCRIPT))
5.1.10 The $OBTAIN and $QUERY Functions
5.1.10.1 $OBTAIN (GLOBAL NAME (SUB1,...SUBn))
5.1.10.2 SQUERY (GLOBAL NAME (SUBl,...,SUBn))
5.1.11 $Z(NVE)
5.1.12 $KORE
5.2 STRING FUNCTIONS
5.2.1 $CHARACTER(NVE)I
5.2.2 $EXTRACT(SVE,NVE1,NVE2)
5.2.3 $PIECE(SVE1,SVE2,NVE1,NVE2)
5.2.4 $STEP(NVE)
5.2.5 STEXTINVE)
5.2.6 $MONEY(SVE[operator]SVE[operator]SVE...)
CHAPTER 6 THE GLOBAL DATA BASE
6.1 USE OF OPEN AND CLOSE COMMANDS
6.2 USE OF THE $DEFINE FUNCTION
6.3 USE OF THE $HIGH FUNCTION
vii
4—7
4-7
4-8
4-8
4—10
4-10
U1 U1 U1
l I I I I I I
N N |—|
U1 U1 U1 U1 U1 U1 U1 U1 U1 U1 U1 U1 U1 U1 U1
I I I l I I I I I I
O 0 KO 00 00 \I \I 01 01 U1 U1 uh J3 m I\)
5-10
5-11
5-11
5—11
6.4. STORAGE OF DATA IN GLOBAL ARRAYS 6-3
6.5 RETRIEVAL OF DATA FROM GLOBAL ARRAYS 6—4
6.6 NAKED GLOBAL VARIABLES 6—4
6.7 THE JOIN COMMAND 6-6
CHAPTER 7 PROGRAM AND DATA PROTECTION SCHEME
7.1 DEFINITIONS 7-1
7.1.1 Mode of User Interaction 7-1
7.1.2 Program Status (D or I) 7—2
7.1.3 Terminal Privileges 7—2
7.1.4 Protection Keys 7~3
7.2 DEVELOPING, FILING, AND USING MUMPS PROGRAMS 7-3
7.2.1 Scratchpad Operation
7.2.2 Creating and Filing New Programs 7—5
7.2.3 Modifying Existing Programs 7—10
7.2.4 Changing Program Status (D, I, and X) 7-11
7.2.5 Changing a Program Name 7—12
7.2.6 Using Programs in I—Mode 7-12
7.2.7 Summary of Program Protection Rules 7-14
7.3 PROTECTION OF GLOBALS . .g 7-14
7.3.1 OPEN Key ' 7-15
7.3.2 READ Key 7—15
APPENDIX A EXPLANATION OF MUMPS MESSAGES A-l
TABLES
4-1 SPECIAL VARIABLES THAT MAY BE REFERENCED OR SET 4-6
4-2 SPECIAL VARIABLES THAT MAY BE REFERENCED ONLY 4-7
5-1 LEGAL FUNCTIONS FOR NESTING 5-15
7-1 LOG-IN CONVENTIONS ' 7-5
7-2 LOG-IN EXAMPLES 7-6
viii
INTRODUCTION
MUMPS (the Massachusetts General Hospital Utility Multi-Programming
System) is a user-oriented, general—purpose programming language inte-
grated with an interactive time—sharing system. The MUMPS language
is user-oriented in that it is a high-level language that is eaSy to
learn and use. The MUMPS environment allows a programming session to
center around a reactive terminal, thus minimizing the user's time in
programming a problem, the computer's time needed in checking it out,
and, most important, the elapsed time required to obtain a final run—
ning application program. The system is especially powerful in on-
line data management applications requiring interactive terminals
structured to provide a general information system. The MUMPS language
has the capability to manipulate character strings and data files with
the same ease and flexibility that it handles numeric and Boolean
expressions.
The hardware system is composed of three basic elements —
1) A medium scale central processor.
2) Scanners capable of interfacing to local or remote
Teletypellike terminal devices.
3) At least one high—speed disk memory system.
MUMPS was originally conceived as a special purpose problem—oriented
system for medical information processing at Massachusetts General
Hospital. It was soon realized that the general-purpose character
of the system indicated that it could serve as the foundation of a
clinical data management system. The general objective of using the
system for the acquisition, storage, and retrieval of medical record
information gained impetus as a growing number of particular applica—
tion areas were integrated into the structure.
The MUMPS system functions in a variety of on—line clinical applica—
tions - automated interpretive patient histories, laboratory informa—
tion processing, medical diagnosis, entries of physical examination
notes and radiology reports, medical records, hospital care health
planning, critical data management, and others. As the system
evolved, it became clear that it could provide a reliable service
function in a wide range of applications areas.
1Teletype is the registered trademark of the Teletype Corporation.
Unlike other on—line information systems, MUMPS language programs are
not compiled into machine language, but are executed by an interpreter
that is resident within the time—sharing system. This approach not
only facilitates the development of programs in an interactive environ-
ment, but also permits implementation of several novel features in the
language.
In the first three chapters, the reader is introduced to the basic
structure and components of the MUMPS language. These chapters are
structured to enable the reader to readily acquire a working knowledge
of the language. Important points are occasionally repeated for em-
phasis, and examples are abundant. Most examples are self—contained
programs that the reader can actually type in and run while learning
the language, thus reinforcing the concepts that are introduced.
Learning MUMPS at a Terminal
The best way to learn the MUMPS language is at a terminal connected
to a MUMPS system. The command and program examples in the following
chapters can be typed in and executed. If you are in doubt about the
effect of a command or a form of syntax, try it out to see how MUMPS
interprets it.
The status of every terminal is set up beforehand by the MUMPS system
manager, through the MUPAK utility package. Usually, a practice
terminal is set up in the "scratchpad" mode of operation, which per-
mits you to type in commands for direct execution, compose program
steps, and execute programs in "indirect“ mode. A limited storage
area ("user partition") is reserved for your program steps and vari—
able data. Access to other programs or the MUMPS global data base is
usually restricted, and you cannot file your programs permanently.
A typical log—in procedure for a scratchpad user is as follows (check
with your MUMPS system manager to obtain your user name, scratchpad'
key, and the current procedures):
1. Press the BREAK key. MUMPS reSponds by typing:
MUMPS LINE 1
ID
2. Type your user name, scratchpad key [in brackets], and an
asterisk:
MUMPS LINE 1 . .
ID STFI3-23* (User Inputs are underlined)
If the scratchpad key is 0.00, it and the brackets are
omitted (close up the Space).
I—2
3. Press the ENTER key. (The ENTER key may also be labeled
ESC, ALT MODE, or PREFIX, depending on the type of
terminal.) If your ID codes are valid, MUMPS responds
with a CRLF (carriage return—line feed) and types a right
caret:
MUMPS LINE 1
ID w
>
The right caret (>) indicates that you are communicating with MUMPS in
the "direct" mode of operation. You can type in any of the command
examples or program steps that appear in the following chapters, or
compose and execute your own programs. It is possible to become stuck
accidentally in the "indirect" mode of operation (executing numbered
program steps) so that you are unable to enter more commands from the
keyboard. If MUMPS fails to type the right caret after you enter a
command, you are probably in that condition. To regain control, press
the BREAK key. MUMPS prints out an error message and returns to
direct mode.
To terminate a session at the terminal, enter a HALT command (Chapter 4)
or press the ENTER key after the terminal has requested your ID. MUMPS
types out THANK YOU to indicate the end of the session.
Fully detailed sign-on, sign—off, and file protection descriptions
appear in Chapter 7- Once you are acquainted with the advanced
features of the MUMPS language, you can generate and file your own
programs, use these and the programs of other users, and use and
modify the MUMPS global data arrays.
CHAPTER 1
BASIC LANGUAGE FEATURES
1.1 ARITHMETIC OPERATORS
MUMPS allows four arithmetic operators. They are:
+ addition
— subtraction
* multiplication
/ division
Any "well—formed" combination of these operators and numerical oper-
ands constitutes a number—valued expression (NVE) (see 1.4).
1.2 OUTPUT - THE TYPE COMMAND
MUMPS can be used to evaluate and TYPE the answer to an arithmetic ex-
pression. To use the TYPE command, type "TYPE", followed by
one space, followed by the numeric expression desired, and then
press the ENTER key. MUMPS evaluates the expression and types out
the result. For example:
>TYPE l+(2*3)-4/l@
6.35
>
The system types a carriage return and line feed followed by a right
caret (>) to indicate that it has returned control to the user and is
waiting for the next command to be ENTERed. In the example above and
in other examples throughout this manual, all input typed by the user
is underlined; system output is not underlined.
1.3 RECOVERY FROM TYPOGRAPHICAL ERRORS
Occasionally, when entering data or writing a MUMPS statement, the
user may make a typographical error. There are two ways to correct
errors of this sort: character rubout or line deletion.
One or more characters in the line may be deleted by striking the
RUBOUT key. This causes the system to type out a backslash ( \ ) and to
delete the last non-deleted character from the line. The user may then
continue entering text. For example:
.1? KD". 555?}: 1+s*4
15
>
MUMPS recognizes the above statement as "TYPE l+3*4" and executes it
correctly.
Every character typed in since the last ENTER may be deleted by typing
Control U1. The system responds by echoing up—arrow U (IU) followed by
a carriage return and line feed, and then waits for the correct text
to be typed in.
1.4 NUMBERS IN MUMPS
MUMPS calculations are performed in fixed—point arithmetic and numbers
retain an accuracy of TWO decimal places. Results of calculations
that produce more than two decimal places are truncated (as opposed to
being rounded). The largest number value allowed in MUMPS is 1310.71,
positive or negative. It is important to note that these restrictions
apply to intermediate as well as to final results; if the magnitude of
any result exceeds 1310.71, MUMPS detects the error, prints the error
message MAXIM, and enters direct mode.2
For example:
>TYPE lgg*lgg/99 The intermediate result
‘“““_‘_—_“_‘ (10,000) is too large.
? MAXIM
>
>IIPE 2/3*5 The intermediate result
1.98 (0.66) was truncated to 2
> decimal places.
>TYPE I.3*l.ll7 The second number has too
many decimal places. Numbers
? MINI” in MUMPS are limited to two
> places.
1Control U (CTRL U) is formed by pressing the CTRL key while strikin
the letter U.
2The range of MUMPS numbers can be extended by the $MONEY function
described in Chapter 5.
1-2
It is vital that the programmer understand the limitations of MUMPS
arithmetic; the truncation of results (as in the second example above)
is the cause of many logical errors in MUMPS programs.
NOTE
NO ERROR MESSAGE IS OUTPUT WHEN A TRUNCATION
IS PERFORMED.
1.5 PRECEDENCE OF ARITHMETIC OPERATORS
MUMPS evaluates arithmetic expressions from left to right, with two
exceptions. First, multiplications or divisions occurring immediately
to the right of an addition or subtraction are performed prior to the
addition or subtraction. (Note that multiplication following division
is performed after the division, in the normal left—to-right order.)
Secondly, the user may change the order of evaluation by t.e use of
parentheses. For example:
EXPRESSION RESULT
1+3*4/12 2
(1+3)*4/12 1.33
l+3*(4/12) 1.99
(1+3)*(4/12) 1.32
C1+3*4)/12 1.M8
3+2/4+1 4.5M
(3+2)/4+1 2.25
3+2/(4+1) 3.40
3+2*4+1 12
(3+2)*4+1 21
3+2*(4+1) 13
1/2*3/4 0.37
1/(2*3)/4 0.04
1/(2*3/4) fl.66
1*2/3*4 2.64
1*2/(3*4) E.16
The subtraction operator (—) may also be used for arithmetic negation
(i.e., it may be used as a "unary minus"). For example:
>TYPF -c3+4)
-7
>
1.6 VARIABLES IN MUMPS - THE SET AND KILL COMMANDS
MUMPS can assign values to variables by means of the SET command.
The user can specify the name of a variable by using from one to three
letters. More than three letters may be used, but those after the
third are ignored. Thus 7AR, VARIABLE, VARIANCE, and VARIANT are all
recognized by MUMPS as VAR. % is legitimate as the first character
of a variable, but certain % variables are predefined and have a
special meaning (see Table 4-1).
To use the SET command, type "SET", followed by a space, followed by
the variable name to be set, followed by an equal sign (=), followed
by the expression whose value is to be assigned to the variable name,
and then press the ENTER key. MUMPS evaluates the expression and, if
legal, assigns the result to the variable name. For example:
>$ET A:I+5*5/5
SET may also reference values previously assigned to a variable. For
example:
>SET BsA*5+12
A single SET command may be used to SET several variables:
>55? A:1,B:A+A,D:A+B,C:D-B
As can be seen, arguments (e.g., A=1) are separated by a single comma
(,). Once a variable has been defined, it may be used to define other
variables, as above, or its value may be typed out using the TYPE com-
mand.
When used with the SET command, the equal symbol (=) does not mean
"equality" in the usual mathematical sense. Rather, its meaning is
more akin to "assign this value to". For example, once defined, a
variable may be set to the value of an expression containing itself:
>TYPF. A
23
>SFT A=A+3
>TYP F A
26
>
The value of a variable may be changed at any time by giving it a new
value with a SET command:
>SET 13:11
>TYPE A
4
>SFT A=23
>TYPE A
23
>
When a variable is given a new value, MUMPS "forgets" the old one and
assigns the new one to it. Often, it is desirable to eliminate a vari—
able completely rather than give it a new value. This may be done by
the KILL command:
>KILL A
>TYPE A
? UNDEF
>
Here MUMPS was made to "forget" the existence of the variable A by
execution of the "KILL A" command. Like the SET command, KILL may
take a list of arguments. When the command is executed, all the vari-
ables in the list are deleted or "forgotten".
>KILL AzFIABCISUM
>
Variables which are not defined may be KILLed without causing an
error.
If no arguments follow a KILL command, all locally defined variables
Ci.e., those defined within your user partition) are deleted. In like
manner, if no arguments follow a TYPE command, all locally defined
variables are typed.
1.6.1 Subscripts
Variables in MUMPS may be subscripted. Subscripts can be used to
indicate different "cases" or "examples" of a variable, or different
positions in a matrix, etc. To use subscripts in any expression,
simply type the name of the variable, followed by an open parenthesis,
followed by the expression whose numerical value is to be taken as
the subscript, and a close parenthesis. Subscripted variables must
always have only ONE level of subscripting, and the value of the sub-
script must be a positive number from 0.00 to 327.67. Subscripts
themselves may contain variables, provided any such variables are
assigned numerical values. Subscripted and nonsubscripted variables
may not use the same name, e.g., N and N(l) cannot be defined at the
same time.
The following are all legal subscripted variables:
AGE(2) ABC(25.08)
AGE(Q) ABC(N)
AGE(O+3*B) ABC(4+(B+2*N))
Subscripts can themselves be subscripted variables:
ABC(ABC(AGE(3))) NUM(AGE(I+4))
An entire array may be deleted by killing the array name.
>KILL ABC
>
An individual array member may also be killed.
>KILL ABC(2_5_._Q§2LA_Bg_N_)
1.7 USE OF THE FOR CLAUSE
Often it is desirable to repeat the same calculation over and over
again with the only difference being the value of some number in the
calculation. The use of the FOR clause allows the useful tool of
iteration to be implemented with a minimum of program space. Essen-
tially, the FOR clause causes the command(s) following it on the same
line to be executed FOR a specified set of values of the same variable.
>FOR I=1:2:3:4:8134 SET XCIJ=I+1V9
>TYPE XCA)
14
>
>FOR I=1:1:9 TYPE 2*13" "
2 Q 6 8 13 12 14 16 18
>
In the first example above, the FOR clause sets I=l (the first number
in the FOR list) and then executes the command following the FOR
clause. It then repeats the execution of the SET command for the other
values of I as specified in the FOR list.
In the second example, the FOR clause sets I=1, the first number in the
FOR list specification, and tests the value of I (INDEX) against the
third number (TERMINATOR) in the FOR list (9). Since the value of
the INDEX variable I is NOT LARGER than the value of the TERMINATOR (9),
the command following the FOR clause is executed. Next, FOR increments
the INDEX by the value of the INCREMENT (1) (betWeen the colons), and
again tests the value of the INDEX to see if it exceeds the TERMINATOR.
The sequence is repeated until the value of the INDEX is greater than
the value of the TERMINATOR.
The two types of FOR lists may be combined in the same FOR clause. The
following example illustrates such a combination:
>FOR I:5,8,33:6:57 TYPE I+1/5.}
6.66
1E.66
44
52
66
68
76
The STARTING VALUE, INCREMENT, and TERMINATOR may be numbers, arithmetic
expressions, or numerically defined variables:
>SET A=5
>FOR I=1+1/2:A:33.40 TYPE Ia" "
1.50 6.501 11-56? 16.591 21.55.) 26.5?! III-SO
>
1.8 FORMAT CONTROL
Often it is necessary to present large amounts of data in some well—
formatted manner. MUMPS allows three special format characters:
# page-feed (or form-feed)
I carriage—return line-feed (CRLF)
?N tabulate (start typing N spaces from left margin)
These characters, as well as quoted text literals, may appear in a
TYPE statement (as well as in certain other statements discussed
later). When MUMPS scans the TYPE command's list of arguments, if it
finds one of the above format characters, it outputs the appropriate
formatting operation as well as the quoted text string.
>FOE A=I:2:4=4212 TYPE. "VRLU:=":A*A:I
VALUF=1
VALUE=4
UALUE=16
UQI.UF=64
VALUE=1A4
>
In the above example, note that a comma is used following "A*A" and
before the CRLF character (1). Commas that are normally used as de-
limiters in an argument string may not be omitted preceding and/or
following format control characters. (However, I! is permitted.)
The tabulation character (?N) is particularly useful for preparing
columns of data:
>FOR R=@.5:@.1:1.2 TYPE "R=",R;?1@:"A=":3.14*R*R,I
R=I2I5fl A=fl-7g
R=Go6fl A=1-12
R=GO7M A=1-53
3:908? 9:2
11:0‘9-0’ 61.12053
T=1 A=3014
E=1olfl A=3-79
R=1029 9:4-51
In the above example, the format expression ?10 causes the "A=" column
to start on the 10th character from the absolute left margin (i.e., the
margin that is in effect when %M=0). If %M and ?N conflict, %M takes
precedence. For example, if %M is set to 10 and a piece of text is
formatted to start at position ?8, the text will start at character
position 10 from the absolute left margin.
In any line of text, if one text string overlaps the starting position
for a ?N—formatted string, the ?N string starts on the next available
character position. For example:
>SET ZM=¢
>SFT A=17
>TYPF A:?6:"METERS"
17 METERS
>SFT A="SEVENTEEN"
>TYPE A:?6:"METERS"
SEVENTEENMETEES
>
CHAPTER 2
WRITING MUMPS PROGRAMS
2.1 STEPS AND PARTS
The simple commands presented as examples in Chapter 1 are considered
"direct“ steps -— that is, they are executed by MUMPS as soon as they
are entered. You can see the result of a direct command immediately,
but a direct command must be retyped every time it is performed. The
real pOWer of MUMPS lies in the automatic sequential execution of
commands stored in memory. Commands executed in this manner are con—
sidered "indirect" steps.
2.1.1 Steps
Indirect steps are composed and entered while you are still in direct
mode (identified by the right caret that MUMPS types after each ENTER).
TO compose a step, type a positive two—place decimal number followed
by a space and the command string that you wish to have "remembered“:
>Ialm TYPE A*31.2
>
The fractional part of the step number must be non—zero (i.e., "1.00"
is not legal).
After typing the command string, press the ENTER key (also known as
ESC, ALT MODE, or PREFIX). MUMPS does not execute the command at
this time; it stores the step in its memory and reSponds by typing a
CRLF followed by a right caret. MUMPS is then ready for entry of
another step or a direct command.
The STEP NUMBER is the label by which the step may be referenced in
other sections of the program. Steps are stored in step number order.
If you wish to change the contents of a STEP after you have ENTERed it,
you may simply retype it, using the same STEP number. MUMPS replaces
the old STEP with the new one having the same step number. Similarly,
if you have defined STEPS 2.34 and 2.50, and now wish to INSERT a new
step between the two old ones, you may do so by using a step number
between 2.34 and 2.50. The new step will be inserted in the program
memory between the old STEPS 2.34 and 2.50.
2.1.2 Parts
MUMPS also handles groups of steps as PARTS. The PART that a STEP
belongs to is indicated by the integer portion of the step number.
For example, step 2.35 is one of the steps in PART 2. PART numbers
may range from 0 to 999. Within a PART, steps may take decimal
values of from .01 to .99. By convention, MUMPS programmers write
their own programs so that a PART contains all the coding necessary
for a specific task. Thus, if a program were designed to perform many
different tasks, each PART in the program would be written to perform
just one of those tasks.
2.2 THE DO STATEMENT
The DO statement causes MUMPS to execute indirect parts or steps
automatically in step number sequence. Consider the following short
program to calculate the area of circles of radius R:
l-IU TYPE "A=": R;?1€I:"A="
1.15 SET A=3-14*R*R
1.2M TYPE 9:!
The three STEPS (1.10, 1.15, and 1.20) are stored in numerical order
by MUMPS. Together, they form a program that has a single part
(PART 1). To start the program, load the variable R with a numerical
value and use a DO command:
'1" 23.. fl
3 --.—It:
U1
V>SE
In executing the DO command, MUMPS "does" each step, in numerical order,
in the part referred to by the DO command. When there are no more
steps in PART 1, MUMPS does a CRLF and types the right caret, indicat—
ing that it is ready to accept another command string or store a new
step.
The DO command, like the TYPE command, may be modified by one or more
FOR statements. For example, you could use the program of STEP 1 to
type the areas corresponding to several radius values by entering the
following statement:
>FOR R=1oQUEOsQSIZeSO D0 1
R=1 A=3-14
3:1.25 A=4.9g
R=1056 A=7056
R=1.75 A=9-6O
R=2 A=12056
R=2o25 A=15-88
R=205fl A=19-62
Remember, a FOR clause causes repeated execution of whatever command
string follows it on the same line. Above, the command string follow—
ing the FOR is a DO statement, and thus all of PART 1 is executed for
each value of R, the INDEX of the FOR clause.
Note that although STEP 1.15 requires a value for the variable R for
successful execution, the variable need not be defined when the step
is typed in. In MUMPS, variables need not be defined with a value
until the time they are actually referenced or used. In this example,
the initiating FOR clause assigns a new value to R for every repetition
of PART 1.
DO statements may also be stored as command strings within steps of a
MUMPS program. For example, the following program (PART 2) makes
reference to a single step of PART 1:
2.15 SFT R=203
2.26 D0 1.15
2.25 TYPE "AREA=",A;!
>D0 2
AREA=16C6Q
A DO statement could reference all of PART 1 as well as a single
Step:
3.15 SET R=2o75
3.22 D0 1
>DO 3
R=2o75 A=23o73
VOLUME=361o88
>
A DO statement that references another part may also be controlled by
a FOR clause, so that the other part is executed repeatedly, as in
the following program.
4.10 SET SUM:A+B,DIF:A-B
4.59 TYPE "sum: ",sum
4.4% TYPE " DIFFERENCE:_”,DIF,!
6.16 SET A=10
6.5% FOR 822,5,15 D0 4
410$
SUM: 12 DIFFERENCE: 8
SUM: 15 DIFFERENCE: 5
SUM: 25 DIFFERENCE: -5
>
MUMPS begins this program at STEP 6.10, the first step in PART 6.
When it encounters the FOR and the DO statements in STEP 6.30, it
"does" each step in part 4 for the three values of B. After PART 4
has been "done" for each value of B, MUMPS does not find any more
steps in PART 6 (called by the DO 6 command string in direct mode)
and so it types out the right caret and waits for the next command.
In computer terminology, the DO_command allows MUMPS to execute a PART .
of a program written as though it were a subroutine within the main
program. Usually, subroutines are written so that many different
Sections of the program may cause the execution of the subroutine at
different times and with different sets of data. In a statistical
program, for example, PART 34 may be the subroutine for computing
the standard deviation of N numbers about an arithmetic mean of MU.
A single DO command may refer to a LIST of steps or parts. For
example, provided that the user has previously defined all of the
steps and parts referred to below, all of the following statements
would be legal DO commands.
DO 2,3,67,56.l4
DO 1.34
DO 3.45,5,9
FOR I=l:2:46 DO 3,15
FOR ABC=34,56,104,200:1:250 DO 3.45,6
2.3 THE IF STATEMENT
In executing a program, MUMPS can make decisions as to what action
to take depending on the current value of variables or expressions
within the program. An IF clause specifies the condition for which
the command string following it on the same line is to be executed.
Changing the example of sums and differences above, we can write a
program to only type out the differences of the two numbers A and B
if they are positive. If the difference is less than zero, the pro-
gram types g.
4.1% SET SUM:A+B,DIF=A-B
4.20 TYPE "SUM: ”,SUM
4.24 IF DIF<U SET DIFzfi
4.26 TYPE " DIFF: ",DIF,!
6.28 FOR A=ZZ FOR B:lfl,lS,34,5fl D0 4
>
20.5.
sum: 52: DIFF:
IE
SUM: 58 DIFF: 2
SUM: 54 DIFF: B
SUM: 7B DIFF: G
>
In this example, the SET command in step 4.24 is executed only when
the value of DIF is less than zero. Thus the program makes a decision
based on the value of the variable DIF.
2.3.1 Arithmetic Comparison Operators
In general, the decision in an IF clause is made upon examination of
a comparison of two expressions, variables, constants, etc. In the
example above, the comparison made in step 4.24 is whether or not the
value of DIF is less than zero; the specific comparison operator is
“less than" (<). The complete set of arithmetic comparison operators
in MUMPS is as follows:
= equals
< less than
> greater than
<> or >< greater than or less than (not equal)
=< <= less than or equal
=> >= greater than or equal
2-5
2.3.2 Boolean Operators
In the example above, the general form of an IF clause is "IF" followed
by a comparison sub—clause based on a comparison operator. The power of
IF statements may be greatly increased by using another kind of operator,
the Boolean Operator, to modify or link together two comparison sub-
clauses. In MUMPS the three types of Boolean operators (in order of
precedence) are:
' NOT
& AND
I OR (inclusive 0R)
For example:
IF A:B&C>D D0 2
Part 2 is "done" if A equals B, AND C is greater than D; i.e., only if
both comparison clauses are TRUE.
IF A:B!C>D DO 2
Part 2 is done if either or both sub—clauses are true.
IF 'A:B D0 2
Part 2 is done if A is NOT equal to B. Note that this is equivalent to
either of the following statements:
IF '(A:B) D0 2
IF A><B D0 2
Finally, using the three Boolean operators, many different comparison
sub—clauses may be linked together to form complex Boolean expressions:
IF A:B!C=5!B=2*(A+B)&'A=C D0 2
The decoding of this complex Boolean is left as an exercise to the
reader.
2.4 MULTIPLE CLAUSES
IF and FOR clauses may be combined in modifying a MUMPS command string.
You may use as many modifying clauses as can fit on one line. THE
ORDER OF EVALUATION IS FROM LEFT TO RIGHT.
FOR 1:1:1:23 IF I*2:B-C FOR 423,4,9 FOR K:2,5 DO 5,3,7
MUMPS takes the following action on this command string. The first
(left—most) INDEX variable I is stepped through the specified values.
For each value of I, IF the conditions specified in the Boolean sub—
clause are met, then J (the second INDEX variable) is stepped through
its values. Again for each value of J, the last INDEX variable K is
stepped through its values and for each value of K, parts 5, 3, 7 are
"done".
2.5 BRANCHING -- THE GOTO COMMAND
In general, MUMPS executes the steps in a part in ascending numerical
sequence. One exception to this rule is the DO command which causes
the normal sequence of control to be interrupted, transferred for a
time to another section of the program, and then returned to continue
the normal sequence.
GOTO is another command in MUMPS that alters the normal sequence of
execution. In programming terminology, GOTO is a command that trans-
fers control from one area of a program to another. When MUMPS en-
. counters a GOTO command, it "goes" to the beginning of the referenced
part or step. Execution then continues in the normal manner. Unlike
DO, however, the GOTO command does not imply that control will be re—
turned after execution of the referenced PART or STEP.
For example, let us assume that a program has defined an array of num-
bers called X(I) for values of I from 1 to 12. The following program
first finds the sum of the 12 numbers in PART 1 and then transfers con—
trol to PART 2 where the mean is computed and typed out.
1.1m SET sum:4
1.2m FOR I:1:1:12 SET sum=sum+X(1>
1.5a TYPE !,"THE sum EQUALS ",sum
1.55_GOT0 2
2.1% TYPE ", AND THE MEAN IS ",SUM/IZ
>DO 1
THE SUN EQUALS 85.89, AND THE MEAN IS 7.15
>
2-7
In the example above, there could have been another GOTO statement in
STEP 2.20 that transferred control to another PART or STEP. This is
perfectly legal. In fact, STEP 2.20, if it existed, could have been
GOTO 1.10, for example, and control would simply cycle through the
above sequence over and over again.
The GOTO statement may be modified by an IF clause, producing the ef—
fect of conditional branching. Clearly, however, the GOTO Statement
should not be modified by a FOR clause since the GOTO does not return
control. For the same reason, a GOTO may not have a list of STEPS or
PARTS to "go" to. Also, GOTO may be used only in a stored command
string, and not in direct mode. Thus, you could not start a program
from direct mode by typing "GOTO l".
2.6 THE QUIT COMMAND
In the previous examples, a PART was considered "finished" by MUMPS
when there were no more STEPS in the PART. A program may abort exe-
cution of sections of a PART or STEP by the use of the QUIT command.
For example: '
fluifi FOR I=1tl=10® IF AGECID=91 QUIT
In STEP 4.10, the search through array AGE stops when 100 values have
been searched, or when an array member having the value 91 has been
found. The following program illustrates conditional termination of a
PART.
17-31 TYPE !:"SUM="
17.35 SET SUM=O
17.49 D0 19
19.20 FOR KI=1:1:50 SET SUM=SUM+AGECKI>
19-38 IF SUM=G QUIT
19.49 TYPE SUM:" MEAN= ":SUM/52:!
>D0 17
SUM=1275 MEAN= 25-50
>
The last step in PART 19 is only executed if the sum of the array AGE
is not zero.
2.7 INPUT -- THE ASK COMMAND
In the examples considered thus far, all of the variables used in the
expressions have been SET by commands stored within the program. The
power and flexibility of MUMPS ingreatly increased by allowing the
user to define numerical data in an interactive mode with the computer.
Let us assume for the moment that a program is needed to form the sum
of N arbitrary numbers. The following program will do the job:
2.12 SET SUM:B
2.15 ASK "WHAT IS THE NUMBER OF I
2.2% TYPE "THANK YOU, LET'S BEGIN
2.52 FOR I:l:1:N DO 5
2.5% TYPE 1,"SUM ",SUM
TEMS? “,N,!!
2" i
9
5.12 ASK "ITEM:",ITM(I),!
5.22 SET SUM=SUM+ITMCI>
When Part 2 is "done" via the DO command, the program allows the user to
define the number (N) of items in his list. It then waits for the
user to define each of the items in that list. When N items have been
entered by the user (to terminate each item, press the ENTER key) the
program types out the sum.
>D0 2
WHAT IS THE NUMBER OF ITEMS?;L
THANK YOU, LET'S BEGIN:
ITEMri
ITEM:
ITEM:_
ITEM:1§
ITEMré
ITEM:§§
ITEMzfig
.4.
9
SUM 14%
>
In the ab0ve example, an item might have been expressed as a sum (e.g.,
ITEM=§i§ rather than_2), since the ASK Command evaluates the expression
input. $ROOT(X) is also legal as long as X is defined (for discussion
of $ROOT see Chapter 5).
ASK, like TYPE, KILL, and SET, will accept a list of variables to be
entered. Like TYPE, it also accepts format characters (line—feed,
form-feed, and tab (?N)) and outputs any text strings enclosed in
quotes.
PASK ?5:"AGE OF SAMPLE = ":AGE,!:?13:" TYPE = ":TYP
AGE OF SAMPLE = 1:;
TYPE = g
2.8 ERROR HANDLING
When MUMPS is unable to process a command for any reason, it outputs
a five-character error message. If it is executing a step (rather
than a direct command) the Step-number precedes the message. The
message is followed by CRLF and a caret to indicate that the user has
control in direct mode. For example:
>TYPE 102*162
? MAXIM
>
>1.1@ YOG
>DO 1.1%
? 1.12 cmmnn
>
Refer to Appendix A for a complete list of MUMPS messages.
2.9 CREATING AND CHANGING A MUMPS PROGRAM
If you type a MUMPS command string preceded by a legal step number
(0.01 to 999.99), MUMPS interprets it as a step and stores it in the
Step Buffer (an area of your user partition). To change the contents
of a step, simply redefine it using the same step number, and MUMPS
will update it in the buffer.
To verify the contents of a step or a part or a list.of steps and
parts, you may use the WRITE command in direct mode:
>ERITE 2,3,1,6
2-10
MUMPS prints out on the terminal all of the steps in PART 2, the
single STEP 3.1, and all of the steps in PART 6. When MUMPS finishes
writing all of the steps and parts, it returns control to direct mode.
To delete any step or part in the program, you may uSe the ERASE com-
mand. Like WRITE, it accepts a list of steps or parts to be erased.
ERASE and WRITE, WHEN USED WITHOUT A LIST OF STEPS OR PARTS FOLLOWING
THEM, REFER TO ALL PROGRAM STEPS IN YOUR USER PARTITION. Be very
careful in the use of the ERASE command; know exactly which sections
of the program you are deleting.
2.10 CHANGING OR DELETING LOCAL VARIABLES
Local variables are the variables defined during the execution of
program Steps or direct commands. They are stored in the symbol table
portion of your user partition. To verify the contents of any Vari—
able, use the TYPE command:
>SET I=123-2
>[IFE I
123020
>
Any local variable may be changed by a SET command.
When it is used without a list of variable names as argument, the TYPE
command causes your terminal to type out all the variables that are
defined in your user partition. In addition, several permanent
system variables ($L, etc.) are typed out for your reference.
(These are defined in Chapter 4.)
To delete any variable in your partition, use the KILL command. KILL.
can take a list of variables to be deleted.
ALL VARIABLES IN YOUR USER PARTITION. Be careful in the use Of the
KILL command; know exactly which variables you are KILLing. (The
special system variables ($L, etc.) are not changed by the KILL command.
2—ll
2.11 SINGLE-LETTER COMMANDS
In all the examples thus far, the full name was used to specify each
command. In actual fact, however, MUMPS makes use of ONLY THE FIRST
LETTER of a command word. For example, the statement:
FOR I:l:1:10 IF I<QTY FOR ARG:2,4 D0 5
can also be expressed as follows:
F I=1:l:l% I I<QTY F ARG:2,4 D 5
In the above command string, note that the second "I" (standing for
IF) is distinguished from the third I (the variable I) by position
only. When MUMPS scans a command string, it "remembers" the first
letter and ignores all other characters until it finds a space or
reaches the end of the line. If it finds a single space and the
command requires arguments, MUMPS interprets the characters following
the space as arguments.
2.12 MULTIPLE COMMANDS ON A LINE
With the exception of modifying clauses like FOR and IF, the above
examples have been restriCted to one command per line. In MUMPS, this
restriction is unnecessary. The number of MUMPS commands per line is
limited only by the 72.characters allotted for a Teletype line. The
sequence of execution is as follows: beginning at the first command
word on the line, all commands are executed from LEFT to RIGHT, one
after the other. When there are no more commands left on the line to
execute, MUMPS continues with the next Step in numerical order. Of
course, this numerical sequence may be altered by the DO and GOTO
commands.
The following example illustrates the use of multiple, single—letter
commands within a step.
A I'N:",N F 1:1:1
:2 :N T 1,1,":" A C S A=A+C
"MEAN=' S CzA/N I C<10 T " "
OIOIOJCN
o o
o o
AWN.—
8888
V
U
0
(N
ENE?
enmph I
MEAN: 2. 511
A double Space convention allows a WRITE-all, ERASE-all, KILL-all, or
TYPE-all to be folIOWed by other commands in the same step:
>1.1@ W T "END OF PROGRAM"
>DO l
1.16 W T "END OF PROGRAM"
END OF PROGRAM
>
The double Space following TYPE is interpreted by MUMPS as "type all“.
Without the double space, MUMPS might attempt to type the contents
of the variable ASK.
2.13 PROGRAM COMMENTS
The MUMPS programmer can insert comments in his program simply by
preceding the desired comment with a semicolon ( ; ). However, it
should be noted that comments occupy Space that could otherwise be
used by the program. The following statement illustrates the manner
in which the individual lines may be commented.
5.10 S AGE=22 3SET TO SEARCH FOR ALL 22-YR OLDS.
>DO 5-12
>TYPE AGE
22
>
When MUMPS encounters such a statement, it considers all characters
following the semicolon (up to the end of the line) to be a comment.
2.14 PROGRAM DEBUGGING -- BREAK AND GO COMMANDS
Often, for debugging purposes, a uSer may wish to interrupt the opera-
tion of his program at predetermined points to examine his program data
in some detail. After examining the data, he may then wish to resume
the normal sequence of operation from the point of interruption. This
technique is especially useful in the early stages of program debugging.
2—13
The BREAK command interrupts execution of the program, prints out ?,
the number of the Step where the BREAK command was found, and the
word BREAK, and returns control in direct mode. The user has the
option of examining local variables as Well as other data at this
point. He may, for example, change the value of some local array, by
executing a statement in direct mode. When the user wishes to resume
execution of the program, he issues the command GO in direct mode and
presses the ENTER key. MUMPS then continues from where it left off:
1.05 TYPE "BREAK EXAMPLE"
1.16 SET I=fl
1.15 BREAK
1.22 TYPE "I=":I
>DO 1
BREAK EXAMPLE
? 1.15 BREAK
>TYPE I
O
> O
I=@
If you introduce an error while inspecting results or, for example,
you hit BREAK during a TYPE ALL, you lose the breakpoint. MUMPS types
an error message and returns you to direct mode. If you attempt to
continue with a GO, a STACK error is created:
>DO 1
BREAK EXAMPLE
? 1.15 BREAK
>TYPE
D=1.1@
I=0
TYP=4
AGE=36
A=SEVENTEEN
fl!
? IOINT + BREAK key pressed
>m
? STACK
‘>
CHAPTER 3
STRING HANDLING OPERATIONS
In Chapters 1 and 2 of this manual, you were introduced to the basic
features of the MUMPS language as well as some of the commands. In
this chapter, we will discuss the STRING capabilities of MUMPS.
3.1 STRING VARIABLES
By now you may have realized that the main purpose of MUMPS is not to
perform complex arithmetic with high accuracy. The language has only
basic arithmetic operations and its decimal accuracy of two digits is
not very impressive when compared to the eight or more place accuracy
of scientific languages like FORTRAN. In fact, the main power of MUMPS
lies in its ability to perform powerful and flexible operations on
STRING data. This capability allows MUMPS to be used with great success
in information processing applications.
To begin with, we need a working definition of a string datum. If we
consider the set of printing characters that can be typed by a Tele—
type, we have the universe of elements that can be combined to make a
string datum. Exceptions are that @ and \. may not be used in a MUMPS
string. For example, consider the following series of Teletype charac-
ters:
ABCDEFGHI&**%0084—156=./?JG"#*)(,
The thirty—four printing characters above constitute a STRING datum.
Of course, the particular string used above may make no sense to any—
body, but it is still a string, since it is made up of a sequence of
characters "strung" together. That is all there is to a definition
of a string datum -- a string of printing characters that are considered
as a single identifiable quantity. Other examples of strings are:
MY NAME IS .
ABCDEFGHIJKLMNOPQRSTUVWXYZ
SHSL JMVM %$0/MM Note that Space is considered
XXXXXXXPPPPPQQQQQKKKKK a string character.
10774992784993774552.HH GGY08 Note that printing
23.78 numerals may be "strung"
0.27 together to form a
l STRING datum.
5678.9953
The maximum length of any string is 73 characters.
3-l
Of course, the concept of string data would be of little use if
there were no way to store and reference the particular string value
of interest. Just as MUMPS allows the programmer to define a variable
name that has a numeric value, it also allows him to define a string
variable —- which naturally enough has a string value.
In order to define a string variable having a particular string value,
you may use the SET command in much the same way that you used it to
SET a numeric valued variable. For strings, however, you must notify
MUMPS that the variable is to be assigned a string value rather than a
numeric value. This can be accomplished by typing SET, followed by a
space, followed by the name (which may be subscripted or unsubscripted)
of the variable to be assigned a string value, followed by an equal
sign (=), followed by a quotation mark ("), followed by the actual
string to be assigned to the variable, followed by a closing quotation
mark. For example:
>SET NME="JOHN DOE":AGE=22:STR="22"
>TYPE NMEJ " ": STR: 11AGE
JOHN DOE 22
22
>
In this example, a single SET command has three arguments to consider.
First, it SETS the variable NME to the string value “JOHN DOE". Second—
ly, it SETS the variable AGE to the numeric value 22. Note that there
are no quotation marks in the AGE=22 portion of the statement. MUMPS
assumes that the user means to assign the numeric value twenty-two to
the variable named AGE. When MUMPS encounters the argument STR="22",
it interprets it to mean SET the variable called STR equal to the
string value formed by the concatenation of two numeral "2"'s. To
understand the difference between the numeric value 22 and the string
value "22" consider the two expressions below:
AGE+lO*(I-l)/5.78
l+3*2.5+STR
The first expression can be evaluated and the result of the calculation
could be used to SET some variable or type out the numeric result. The
second expression, where STR is a defined STRING variable, is meaning-
less. One cannot combine a number value and a string value. When
evaluating the second expression MUMPS Would output the error message
MIXED (both string and numeric values in the same expression). However,
the members of an array need not be of the same data type. For ex-
ample:
SET ID(1):”JOHN DOE",ID(2)=22,ID(3):"22"
is perfectly legitimate.
3.2 _S_'I;RING CONCATENATION t.)
String values may be combined (concatenated) by use of the concatena—
tion operator which is a period (.). For example:
>SET A:"NME= ",B:"FRED "
>SET A:A.B
>TXPE A."JONES"
NME: FRED JONES
>
3.3 STRING INPUT -- THE READ COMMAND
String data can be ENTERed and stored in the MUMPS memory with the
READ command; READ is analogous to the ASK command used to input
numeric data. In both cases, MUMPS waits for the user to ENTER a
value, which is then stored as a variable. With the READ command,
however, whatever data the user enters is assumed to be a String
datum. The syntax for using the READ command is the same as for ASK.
Like the ASK command, READ can force output of quoted text literals
separated from the variable names by delimiting commas. For example,
if you wanted to request the user's name, age, and address, you
might use the following program:
9.1g READ 1,"UHAT IS YOUR NAME PLEASE? ",NAM
9.12 ASK !,"AND YOUR AGE? ",AGE,!
9.4a READ "AND UHERE DO YOU LIVE? ",!,ADD
> O 2
UHAT IS YOUR NAME PLEASE? QOHN DOE
AND YOUR AGE? fig
AND UHERE DO YOU LIVE?
12D4 SOUTHABAY STATE ROAD, BOSTON. MASS.
>
When MUMPS encounters the READ statement above, it outputs the special
format characters and the quoted text—literals, and then waits for the
user to ENTER a character string as the answer to the question. When
the user presses the ENTER key, MUMPS assigns the string value to the
variable.
3.4 STRING COMPARISONS ( =, [, 3,)
String values may be tested against other string values in much the
same way that numeric values may be tested. The examples below assume
an array named ID in core containing 20 names (held as strings) and 20
numbers (held as numerics). ID(l) contains the first string, ID(2)
the first number, and so on up to ID(39), which contains the last string
and ID(40) which contains the last number. String equality can be
tested by using the equals operator (=). For example, the program:
4.10 READ "NAME:",NAM,!
4.26 FOR 121:2:39 IF IDCI):NAM TYPE ID(I+1),!
4.3% TYPE "END OF SEARCH"
will search the table and print out the number associated with the
name that was input, providing that the name is found.
>D0 4
NAMEngCK JONES
IDS
END OF SEARCH
>90 4
NAME:HARRY TRUMAN
END OF SEAR
>
To make this program more useful, the contains operator ([) might be
. used; this tests whether.the string value on the right side is_contained
in the string value on the left side. For example, assuming the pro—
gram 5.13 READ "NAME=",NAM,!
5.2m IF NAM="" Q
5.5a FOR I=1:2:39 IF ID(I)[NAM T ID(I)," ",ID(I+1),!
5.4a TYPE "END OF SEARCH",! GOTO 5.10
is stored, then the following might occur
>QQJI
NAMEzJACK JONES
JACK JONES 135
END OF SEARCH
.NAHEszCK
JACK JONES 165
ALFRED JACKSON 104
JACKO SMITH IDS
END OF SEARCH
NAME:BOG
END OF SEARCH
NAMEzg;
JACK JONES IDS
ALFRED JACKSON 104
BILL RODGERS IUI
END OF SEARCH
NAME:
The user simply strikes ENTER to return to direct mode; this inputs
the null character represented in 5.20 by (that is, nothing en-
closed in quotes).
Note that "JACK"[“JACK" would match, and that "JOACK"["JACK" would not.
Suppose we wished to output all the names starting with G or H. The
follows operator (1) can be used; this tests whether the string value
on the left “follows" that on the right (i.e., whether the value on
the left would appear after the value on the right if both were in a
dictionary). To extend this to the full set of characters that MUMPS
can store in a string, the following collating sequence is used:
null
A through Z
[ ] i t reading from left to
space :éiigmand from top to
l " # $ % & , ( ) * + ' - - /
fl through 9
- - < = > ?
' I
Thus "#" follows "A", "ABC" follows "AB" (the "C“ is compared with
null), GtC- By convention, " FRED" does not follow "FRED".
To return to the example, the program '
6.10 FOB 1:1:2239 DO 7
6.29 TYPE? "END 0? SEARCH”:!
7.25 IF IDCI)J"I" Q
7.39S I IDCI)]"G" TYPE IDCI):" ":ID(I+1):!
will achieve the desired result.
>DO 6
GEORGE SMITH 121!
GERALD JACKSON 144‘
HQEEY THOHT 165
I‘ND 017 SEARCH
>
Ineguality Conditions can be tested by use of the Boolean NOT operator
('). For example: ,
1.1m READ "CODE = ":C
1.15 IF 'C="27EB" TYPE !:"ILLEGAL";! GOTO 1.1%
1.20 TYPE 1:"BEGIN"
>DO 1
CODE = 31-;
ILLEGAL
CODE = ROQER
ILLEGAL
CODE = ages
BEGIN
>
In STEP 1.15, "ILLEGAL" is typed only if the contents of C equals
something other than 272B (i.e., '(C=272B)).
The "not" operator can be used with the contains ([) and follows (J)
operators as well.
3.5 PATTERN VERIFICATION (:)
Very often, in response to a stored READ command, the user will ENTER
a string datum that is different from what the MUMPS program may be ex-
pecting. If the need for exact specification is real, the program may
examine the value of a variable and make some decision based on the
type of characters that the user entered. An example for this type
of pattern recognition is the entry of a date in a program that is
assigning hospital beds to incoming patients. For reasons of uni-
formity, the programmer may wish to insist that the user enter the
date in the following pattern: two numbers for the month, a slash,
two numbers for the day, a slash, and two numbers for the year; for
example, 10/07/46 Cr 12/08/68. The pattern verification operator (=)
can be used for this purpose.
The following program will READ the date and check it to make sure
that the string value ENTERed corresponds to the pattern required:
1.55 READ 1,"DATE 0F ADM: ",DAT,!
1.4a 1F DAT:2N"/"2N"/"2N QUIT
1.5a TYPE "NO GOOD, PLEASE FIX " GOTO 1.53
In Step 1.33, the string value of DAT is entered by the user. Step
1.40 checks the value of DAT to see if it is of the pattern 2N (two
numerals), followed by a slash mark (the quoted text—literal "/"),
followed by 2N (another two numerals), etc. If the value entered for
DAT fails to meet the pattern specifications, control passes to Step
1.50 and a message is printed out.
>DO 1
DATE OF ADM: JAN 1 7m
NO GOOD, PLEASE P1X
DATE OF ADM: 1 JAN 70
N0 GOODspLEASE FIX
DATE OF ADM: @1/m1/7m
>
In actual fact, specific patterns such as that described above are
rarely used.
More often, it is desired to determine if the user has
entered a specific type of string character. The pattern codes
recognized by MUMPS are:
A
N (D
Passes alphabetic characters only (A—Z). Does not
pass numbers or punctuation.
Passes numerals (0-9) only.
Mixed. Passes combinations of alphabetics and
numerals.
Passes only punctuation marks. Includes all print-
ing characters (including a space) except the num—
bers and the alphabetic characters.
Passes combination of alphabetic and punctuation.
Passes combination of numbers and punctuation.
Universal. Passes any character.
NOTE
A quoted text literal passes only
the characters enclosed in the
quotes (specifies an exact match).
In the example above, the pattern specification follows the single
colon and contains numbers as well as the numeric pattern code (N for
numerals).
If the programmer does not care exactly how many numerals
are entered, but merely wishes that only numerals will be passed, he
ter without any numbers in front of it.
_ -11
_ _._1_
A indefinite pattern match I, wh1c1 is simply the code let—
For example, if the program-
mer wishes to test whether or not the variable DAB is composed of an
indeterminate number of alphabetic characters followed by precisely
four numbers and one punctuation mark (and nothing else), the pattern
A4N1P will serve the purpose. Notice that any number of alphabetics
(even zero) will satisfy the first code letter. Some additional ex—
amples may be found below. Note that any given string can be passed
by several different patterns. The more specific the programmer is
in setting up his pattern match, the finer a filter will be implemented.
String Some of the Patterns that will pass it
1234DD NA, 4NA, 4N2A, "1234"A, "l"3NlA"D", U
JOHN DOE U, APA, A" "A, A1P3A
Note that in using the pattern verification operator (also called the
syntax analyzer) the string value must be on the left of the operator,
and the pattern on the right. For example:
IF STR:N DO 7
-IF QTY:2A1P3N D0 7
IF ABC:2N&MON:5A1P5N DO 7
In the first two examples, IF the variable name before the colon has
the pattern coded after the colon, Part 7 will be "done". If the
pattern does not match the value of the variable, Part 7 will not be
done. In the third example, there are two pattern matches, connected
by the Boolean operator & (AND). Both patterns must be satisfied in
order to execute Part 7. Note that spaces may not explicitly appear
in the pattern, except in a quoted text literal.
Strings can be tested for a "no match" condition by use of the
Boolean NOT operator ('):
2.1g READ 1:"LAST NAME, FIRST NAME ",N
2.15 IF 'Nzé": "A GOTO 2.1g
2.2g READ 1," ID ".ID
This format is more_convenient if you want to continue within a
single part whether or not the "match" condition occurs.
MUMPS functions, which are identified by the $ prefix, are not
described until Chapter 5. However, the $VALUE function is introduced
here to show its use with string comparisons. The $VALUE function
converts a string value to a numeric value.
Thus, $VALUE("33") will have the numeric value 33. If the string
value does not represent a number, the value zero is returned. Both
$VALUE("DD" and $VALUE("FRED") will have the numeric value D. When
MUMPS executes a function it only examines the first character of the
name after the $, and thus function names may be abbreviated in much
the same way as commands. For example:
5.17 S A:$V(AGE)
The following example operates as an enquiry program for an array of
names and numbers similar to that used in previous examples. If the
user inputs a number, each name associated with that number is output
(but in alphabetical order); if the user inputs a string containing a
space, the number associated with first instance of that name is found.
If a string not containing a space is input, every name containing that
string is output, along with its associated number. Such a program
might allow enquiries to an internal telephone directory; as it is
coded for this example, it does not represent the best way of implement—
ing such an application, but is given solely to illustrate the concepts
discussed in this section. The example is coded in short form to give
you an idea of how terse the MUMPS language can be. Note that the ac—
tual strings are not sorted, but rather only the pointers to them in
array L.
111
:U
1.13
1.26
1.3%
1.48
1.50
1.69
0
CC
1.1%
5 G 1.1%
NE? I IDCI)[S T !,ID(I)," ",ID(I+1) S J:J+1
3h-UID
2"0
010
“ nu to.
HSGDZ 3
(j S
Oh!"
1
him :
~HJ>N
W
I.--t..t_l:nmN
V
2.25 S
2.31
2.32
2.59
2.40
2.42
2.50
2.51
2-61
ll
J=1 F I=2:2:AO I IDCI):N S LCJ):I-1,J:J+1
”NONE" Q
5%
9
’
I
I IDCLCIJ)IID(L(I+1)) S T:1 D 2.61
HHHHLLZ
H II II II H II
»~—-ano~<fi
0‘
HQ“
0.
Lupe. m.-
1- I
I—CNN
<0
I !,ID(L(I))
mEJ‘rlH-quI—qm mHmn—«Hza
1"
r‘
\—4
‘J
(1 I
(1+1) TrT1xx-w
3:
I I
1"
I-i
‘J
«I
3.58
5.69
~+m
2 59 I ID(I):S T !,ID(I+1) Q
1," NOT FOUND"
“DO 1
QUERY :MIKE
NONE
QUERY :1ga4
DAN B. “"
DON U.
QUERY :IOIZ
NANCY K.
WILLY w.
QUERY :DO
DON U. 04
DON w. 1058
QUERY :BILL
BILL S.—TU§B
QUERY :JOHN
JOHN Q. 1656
JOHN M. 1U42
QUERY :LGGU
NONE
QUERY :
{—
3—10
CHAPTER 4
MORE ABOUT MUMPS PROGRAMMING
In previous chapters of this manual, little or no prior knowledge or
experience with MUMPS was assumed. This chapter, however, as well as
Chapters 5 and 6, assumes some familiarity with the MUMPS language.
Basically, the purpose of this chapter is to introduce to the reader
several additional commands and capabilities, and to tie up any loose
ends created in the previous chapters.
4.1 MUMPS PROGRAM LIBRARIES -- CALL AND OVERLAY COMMANDS
The amount of core space allocated to any user is limited in size, and
each program must fit into this space. However, a program may cause
execution of other filed programs by use of the CALL and OVERLAY com-
mands. When a program is brought into core by a CALL or OVERLAY com-
mand, it replaces the invoking program and MUMPS begins executing it at
the first non—zero part. A program accessed in Such a manner is treated
like any other program by MUMPS, and it may CALL or OVERLAY still more
programs. The effective size of the user's program is thus extended
indefinitely.
CALL is treated in the same manner as the D0 command, except that it
takes program names as arguments instead of part numbers. When the
program that was CALLed is finished executing, the original CALLing
program is read back into core and re—entered at the point immediately
following the invoking CALL command. However, the calling program
itself must be filed, or MUMPS will be unable to find and return to it.
(For details, see Chapter 7.)
The second command, OVERLAY, is used like the GOTO command previously
discussed. Unlike CALL, the OVERLAY command cannot take more than one
program name as an argument, since MUMPS does not "remember" the name
of the OVERLAYed program, but simply reads in the OVERLAYing program
and begins execution of it at the first non—zero part.
When programs are CALLed or OVERLAYed local data is available and re-
mains unchanged; execution begins at the first non—zero part. When a
program is brought in by OVERLAY in direct mode, control remains with
the user in direct mode. Since each use of the OVERLAY command takes
an average of one Disk access time, and since each CALL command takes
two Disk accesses (one for the CALLed program, and one to return to the
CALLing program), care should be exercised in the planning of program
segments. -
4.2 INPUT/OUTPUT DEVICES
MUMPS timesharing allows multiple users to have access to the same
central processor via separate remote terminals. It also allows one
user to have access to many terminals from one program. In addition
to terminals, MUMPS systems also include ancillary Input/Output de—
vices such as the high-speed paper tape reader and punch, DECtape
transports, etc. Each of these I/O devices is assigned an identifica—
tion number. To use one of these devices, you must perform the
following:
First, you must establish "ownership" of the device since, in a time—
sharing environment, many programs may be competing for a single de-
vice. Ownership is established through use of the LOCK command.
Before sending output to a device, you must LOCK to it. In direct
mode this is done by entering:
|
LOCK DEVICE
Where DEVICE is a numeric expression that represents the number of the
device in question. Note that in direct mode the LOCK command must be
the last command on a line. If the LOCK procedure is successful, that
is, if no other user has already LOCKed to the device specified, MUMPS
reSponds with a Carriage—Return and Line Feed and prints the usual right
caret (>). If the device has already been LOCKed to, MUMPS responds by
typing IOLOK, which indicates that the device is "owned" by some other
program. If there is no such device, a MAXIM error printout occurs.
MUMPS follows a different procedure when the LOCK command is a stored
command (i.e., in a Step). If the LOCK is successful, MUMPS ignores
the rest of the line after the LOCK command and proceeds to the next
Step in the program. If the LOCK procedure is unsuccessful, MUMPS
continues on the same line and proceeds to execute any further com—'
mands. The usefulness of this procedure may best be illustrated by
examples:
1.2% LOCK 12 TYPE "DEVICE 12 IS BEING USED" QUIT
2.59 LOCK 6 TYPE "6 IS IN USE, TRY ANOTHER" GOTO 5
4.56 LOCK 6 GOTO 4.56
In the first example, if the LOCK is unsuccessful, MUMPS continues on
the same line, outputs the quoted message, and then QUITs the part
it was executing. In this case, the programmer has decided that if
he cannot have device number 12, then he does not want any device
4-2
(so he QUITs). In the second example, the same thing happens, except
that in this case the programmer decided to try another, presumably
in Part 5. The technique illustrated by the third example is much
more common; if the LOCK is unsuccessful, the program continues trying
until it is successful. (Note that a program may be required to wait
for an indeterminate amount of time using this technique.) In each of
the three examples, if the LOCK is successful, control passes to the
next Step. A program may own more than one I/O device at a time, but
a LOCK command takes only one argument.
After the program has established OWnership of a device, it must
then inform MUMPS that it wishes to use the device for actual I/O.
A program may not communicate simultaneously with more than one
input/output device. The device identification number is stored in
a local variable called %I. This variable may be treated as any
other numeric variable in local storage. It may be referenced in a
number-valued expression, and it may be SET. In order to change
the device being used for I/O, one need only SET the value of %I
to the desired ID number. Each I/O command references the device
whose ID number equals the current value of %I.
The PRINCIPAL I/O DEVICE is defined as the device (usually a Teletype-
like terminal) that originally calls up the program. When %I is equal
to zero, MUMPS uses the principal device, whatever it happens to be.
It is the custom when using the terminal to SET %I equal to zero.
When a user signs on from the terminal, %I contains the actual
device number divided by one hundred (this allows the program to
identify the terminal being used). When MUMPS detects an error, the
value of %I is SET equal to zero so that error messages are output
to the principal I/O device.
When an I/O device is no longer required by a program, it can be re;
leased for use by other programs by means of the UNLOCK command. UN-
LOCK may take a list of arguments and UNLOCKs are always successful;
MUMPS continues on the same line of code after executing the UNLOCK.
When a program is halted, all devices "owned" by that program are
UNLOCKed automatically. LOCKing and UNLOCKing the principal
I/O device are ignored.
4.3 SECONDARY STORAGE
Obviously, the limited amount of fast core memory available can not be
allocated for applications requiring vast amounts of storage. Conse—
quently, core is partitioned among the users, and only a limited amount
of fast local storage space is available per user. MUMPS provides
three types of secondary storage systems: Global arrays stored on
Disk, linear storage tracts stored on DECtape, and paper tape.
The structure and use of Global arrays is discussed in Chapter 6. For
the time being, let us turn our attention to the use of DECtape devices.
4.3.1 DECtape I/O
Multiple DECtape transports are available for use under program control.
Access to a DECtape is obtained by setting the Input/Output device
variable (%I) equal to the appropriate device identification number.
Subsequent READ, WRITE, ASK, and TYPE commands operate on the DECtape
unit specified by the value of the %I variable. Since the DECtape is
organized as a linear storage device, one additional control variable
is needed. The address variable %ADDRESS (%A), which can be set by the
user, points to the next word position that will be accessed by any of
the commands that require I/O. The value of %A is in terms of DECtape
words divided by one hundred so that %A=24.05 means that the next word
position to be referenced is number two thousand four hundred and five.
Each DECtape word holds three MUMPS characters. As MUMPS accesses
words, the value of %A is updated so that it always points to the next
available location. The range of %A is 0.00 to 1310.71. The avail—
ability of the address variable permits extensive use of address
arithmetic in applications needing large amounts of data for long term
storage.
A11 output to DECtape must be followed by an EOM, symbolized by an
exclamation point (I) or a page feed (#). For example:
>TYPE X: le: !,Z:!
If a TYPE command is not followed with an EOM, the next attempt to
TYPE onto DECtape will cause an error (even though that next statement
is correct).
4.3.2 Paper Tape I/O
The paper tape station is programmed in much the same way as terminals. I
After LOCKing to the device and setting up the %I variable, TYPE,
PRINT, READ, WRITE, and ASK commands are all legal. Paper tape
provides a convenient off—line storage medium for programs during
early stages of development.
4.3.3 Saving Programs Using READ and WRITE Commands
Programs may be saved and retrieved on either paper tape or DECtape
mediums by means of READ and WRITE commands without arguments. It is
only necessary to LOCK to the device and set the %I variable appro-
priately. For example, let us aSSume that in a particular MUMPS con-
figuration the paper tape station is assigned as device number 12. I
The following command sequence, then, will "dump" any locally held
MUMPS program onto paper tape.
>LOCK l2
>SET 21:12 W
The same program may be retrieved at a later time and restored within
the user's partition by the following sequence.
>LUCK 12
>SET %I=12 5
Programs can be saved on DECtape by similar setup commands. However,
the %A variable may need to be set to a starting value, and it is
advisable to add an "end-of-program" marker. For example, assuming
the DECtape is device No. 14, the commands:
>LOCK 14
>SET %I=14:%A=24o at 5
>W T "*":!
cause the local program to be written on DECtape unit 1 Starting at I
word 2405. After the "write all" (WRITE followed by double space),
an asterisk is added as an "end—of-program" marker.
The program may be retrieved and restored in the user's partition by
the following sequence:
>LOCK 14
>SET ZI=14;%A=24. at 5 B
When the program is read back, the asterisk creates an error because
it is not a step number. The error stops the tape at the point where
one program ends and the next begins.
4.4 SPECIAL (SYSTEM) VARIABLES
A number of special system variables are defined within MUMPS to con—
trol the flow of information and to provide system information to indi-
vidual users. Two of these variables (%A and %I) have already been
discussed; all of the special variables are listed and defined in
tables 4—1 and 4—2. Table 4-1 defines variables that may either be
referenced or SET by the user. Table 4—2 defines special variables
that may only be referenced by the user. You will note that each vari—
able shown in Table 4—1 begins with a "percent" character (%), and each
variable in Table 4-2 begins with a "dollar sign" ($) character.
Table 4-1. Special Variables that may be
Referenced or SET
VARIABLE ABBREVIATION DEFINITION
==_—=—_i
\
%ADDRESS %A Address of next word to be accessed
on DECtape. (Automatically updated
after a DECtape access.)
%ERROR %E Controls action of independent pro—
gram when errors or interrupts occur.
(Initiallv -.01)
%E=fl BREAK is ignored.
%E=—.fll BREAK terminates the program.
%E=-.fi3 Set %E to S on a BREAK. (Use
for implementation of user
defined operations.)
%IODEVICE %I Contains the number of the I/O device
to be used by MUMPS. When the
job is first started, %I contains
the device number divided by 100.
%FORMAT %F Contains the number of characters from
the left margin that define the loca—
tion of the right margin. (Initially
set to 72.) CRLF occurs on first space
following the %F-th character.
%MARGIN %M Controls where the first character
on a line will occur; can be used
for tabbing. %M should be less than
%F for proper operation.(Initially fl.)
gpAGE %P Controls where a carriage return and
a form-feed control character is out—
put in lieu of a CRLF. %P=fi disables
this feature. (Initially Q.) (Form-
feed is not available on all types of
terminal.) .
%KEY %K Contains protection key for globals or
programs. (Initially fl.) Refer to
Chapter 7 for more detailed informa—
tion on key protection.
4-6
Table 4-2. Special Variables that may be Referenced Only
VARIABLE ABBREVIATION DEFINITION
SLOCATION $L Equals the number of the Step that
is being executed at any time.
$STORAGE $S Equals the number of free characters
of storage left in the partition.
STIME $T STIME contains the number of seconds
since midnight, divided by 100.
$DATE SD $DATE contains a six character string
with year, month, and day; "yymmdd".
This form allows convenient collating
operations.
$X $X X-coordinate. Equals the number of
characters typed since the last car-
riage—return line-feed on the princi—
pal output device only.
$Y ‘ $Y Y—coordinate. Equals the number of
carriage-return line—feeds since the
last PAGE feed on the principal out—
put device only.
4.5 SPECIAL COMMANDS AND COMMAND FORMS
In addition to the commands described in preceding sections of this
manual, MUMPS provides several other special commands and command forms
that are described in the following paragraphs.
4.5.1 The HANG and HALT Commands
The HANG command provides for a program to "HANG" for a specified num-
ber of seconds during which time no attention is given to the program
calling for a HANG. This facility is especially useful in applications
where the programmer periodically wants to check the status of a vari-
able and take action when the variable has changed; in the event that
it has not, the program goes into "limbo" for another period of time.
The number of seconds to HANG is specified as an argument to the HANG
command. Consider the following examples:
HANG 0.04 The next command is not executed until four
seconds have elapsed.
HANG 1.20 The next command is not executed until 120
seconds have elapsed.
HANG 0 ' Give up the rest of your current processor
time slice.
HALT Terminates the user's session at the terminal.
4‘7
The reader will note the similarity between HANG and HALT; that is, both
commands begin with the letter H. If a command begins with an H and has
no argument after it, MUMPS interprets it as HALT. If there is an argu-
ment following the command, MUMPS interprets it as a HANG command and
takes the appropriate action.
4.5.2 More About the QUIT Command
To better understand the QUIT command, it may be helpful to think of a
program's execution as occurring at different levels. Each time a DO
command, a CALL command, or a FOR modifier is encountered the level of
the program is raised by one. The normal termination of the above com—
mands and FOR modifier decreases the current level by one. When QUIT
is executed, the current level is also decreased by one and the invok—
ing command or FOR modifier is terminated.
The QUIT command is used if a program is in the range of a D0 or CALL
command and it completes its computation; control then returns to the
code immediately folloWing the invoking command. If the invoking com—
mand was a DO from direct mode, control is returned to direct mode.
If the program is currently in a FOR 100p, the repetitive loop ends
when a QUIT command is executed, and the program continues from the
QUIT statement. For example:
1.61 F I=1:1:IB R !:A(I) I A(I)="DONE" Q T !!:"THANKS"
>D 1001
ISIS;
aisle
2 I
D
Z
I:
m
2
I"!
V
The array A(I) is READ until A(I) is equal to "DONE", at which point
the FOR is terminated, and the message “THANKS" is typed.
4.5.3 More About the DO Command
There are two additional points that should be made concerning the use
of the DO command that were not covered in Chapter 2. First, for some
editing applications, the user may wish to create a new program Step
under program control rather than by entering the new Step via direct
mode. This may be accomplished by use of the DO command if the argument
is a STRING of the proper format. The use of this facility may best
be illustrated by examples:
Statement Effect
DO "1.20 TYPE x+3“ A Step 1.20 is created containing
the command TYPE x+3.
DO 3.10,$C(I).“ ".STP,3.2fi Step 3.10 is "done", a Step
created whose contents are the
value of the string STP, and then
Step 3.20 is "done".
The Step number of STP is the
value of the number variable I.
Note the mandatory space between
the Step number $C(I) and the
contents STP.
DO $C(I)." ".STP,I As above, Step I is created. But
in this case, the DO command has
a second argument, I. Therefore,
this command will create the Step
and then immediately execute it.
Secondly, it was stated in Chapter 2 that if the argument of a DO com-
mand was a Step number, then MUMPS would execute that Step and then
return to the next argument, if any, in the DO command. This is
strictly true only if the Step that was "done" does not have any GOTO
command in it. If the invoked Step does have a GOTO in it, MUMPS will
honor the GOTO and will not return to the invoking DO command until the
end of a Part or a QUIT command is encountered, after which it returns
as usual. In effect, this gives the programmer the ability to DO a
Part starting with a Step that is not necessarily the figgp Step in
that Part.
4-5-4 UNTIL and WHILE Terminators in the FOR Clause
The FOR statement has been described as having two different formats
(Range and List) that may be intermixed. For example: 1:1:200 (Range),
l,4,2,8,45 (List), l:l:4,8,12 (intermixed), and l,5,2:4:12,3,6,l:l:5
(intermixed).
In the Range format, the limit may be replaced by a WHILE or UNTIL
clause. For example:
For K=l:fl UNTIL X=2... MUMPS will do everything in the range
of the FOR statement UNTIL the Boole-
an condition (X=2) is TRUE. It then
stops and goes on to the next Step.
FOR K=l=l WHILE X=2... In this case, MUMPS will do every-
thing in the FOR statement WHILE
the Boolean condition (X=2) is TRUE.
In other words, when the Boolean
condition fails to be true, the
FOR statement will be stopped and
control passes to the next line.
4.5.5 The PRINT Command
Although MUMPS has been created with a great deal of device independence,
it is very often desirable to take advantage of special features of
certain I/O devices. The PRINT command accepts numeric arguments, the
low-order seven bits of which are taken as an ASCII character. This
character is transmitted without any conversion to the device specified
by %I. Using this command, it is possible for the programmer to take
advantage of the control functions for a particular device, such
as the bell (PRINT .07), carriage return without a line feed
(PRINT .13), or a line feed without a carriage return (PRINT .10).
Multiple codes ban be specified by separating them with commas. For
example,
>PRINT .Ia,.10,.1m,. at 7
results in three line feeds (without a carriage return) and ringing the
bell.
4.5.6 XCOM Command
This command permits a MUMPS program to access specific disk blocks
on_either DECdisk or Disk Pack. The command.is provided primarily
for use by system programming or management personnel and is key
protected for system security. Complete information on the use of t
this command is provided in Chapter 7 of MUMPS Operator‘s Guide
(DEC—15-MMUPA-A-D).
CHAPTER 5
USING FUNCTIONS IN MUMPS
MUMPS contains a number of useful functions. By convention, MUMPS
function names are always preceded by a "dollar sign" ($) and, like
commands and special variables, only the first letter of the actual
name is required. Expressions that are to be evaluated as "arguments"
by the function are specified in parentheses and separated by commas
as part of the function call. The form for using functions is best
illustrated by an example:
1.13 EUR I:1:1:1U SET ARYCI):(2*I)*(2*I)
1.2% FOR 121:1:19 TYPE " ",$ROOTCARYCI))
>D0 1
2 4 6 8 10 12 14 16 18 2%
>
MUMPS provides for two basic types of functions that are classified
according to the type of value that is returned. The Numeric Func-
EEEEE are those that return numeric values. Similarly, functions
that return string values are termed String Functions. Numeric
functions may be used anywhere numeric values are legal. String
functions may also be used where string values are legal. However,
except for SBOOLEAN, they may ppp_be nested within other functions.
Table 5-1 (at the end of this chapter) shows functions which may be
legally nested.
In the function descriptions that follow, SVE refers to a string valued
expression and NVE refers to a numeric valued expression. In cases
where a function has more than one argument of the same type, the
arguments are numbered according to position.
5.1 NUMERIC FUNCTIONS
Numeric functions included in HUMP. are
$ROOT SDEFINE
SLENGTH $NEXT
SVALUE $HIGH
SINTEGER $OBTAIN
SFIND SQUERY
SBOOLEAN s z
$KORE
llIII
Each of these functions is described in paragraphs that follow.
5-1-1 $329M.)
This function first forms the value of the numeric valued expression
specified by NVE. NVE may be a number, a numeric variable, or an ex-
pression such as AGE+3/YRS, provided that the variables AGE and YRS
both have numeric values. In any case, if the NVE results in a legal—
ly defined MUMPS number, $ROOT(NVE) returns the value of the square
root of NVE. If NVE is a negative valued expression, MUMPS types the
error message MINUS. $ROOT may be used in the same manner as any
other numeric expression, for example, to compute and store the value
of the hypotenuse of a right triangle of sides A and B one might use
SROOT in the following way:
SET C=$ROOT(A*A+B*B)
To determine if the hypotenuse is an even multiple of 5, one might
use the following:
1.13 SET D:$R(A*A+B*B)/5
1.56 IF D/1 at U*13fl:D TYPE "MULTIPLE" QUIT
1.60 TYPE "NOT MULTIPLE OF 5"
5.1.2 $LENGTH(SVE)
The SLENGTH function ($L) returns the number of characters contained
in the string'valued expression SVE.’ For example: ' '
$L("HELLO") Returns the numeric value 5.
$L(NAM) Where the argument NAM has
the string value "JOHN DOE", the
numeric value returned is 8.
5.1.3 $VALUE(SVE)
The $VALUE function ($V) evaluates the string argument SVE and attempts
to convert it to a number equal to the value represented by the digits
in the string. If the leftmost characters of the string represent
a valid number, $V returns that number; otherwise, $V returns 0. The
user should check for SVE="0" before using SV to avoid ambiguity.
The following are all valid SVE's for the $V function:
$V("l.lfl") Returned as the numeric l.l¢.
$V("l+3/4") Returned as the numeric 1.75.
$V(AGE) Where AGE = "59", $V returns
the numeric 59
$V("$T/6fi,FRED") Number of minutes since midnight/100
The following examples cause SVALUE to return the numeric value 0.
$V("JOHN DOE") This string does not represent a
number.
$V(AGE) Where AGE does not contain a string
that can be evaluated as a number
(e.g. , "FIFTY-NINE YEARS.")
The $V function is useful after checking the syntax of a response to a
query. In the following example, assume that a two—digit number is
required:
1.1M READ “NUMBER PLEASE ",STR!
1.12 IF STR:2N TYPE "THANK YOU" GOTO 1.16
1.14 TYPE "USE ONLY TWO DIGITS PLEASE",! GOTO 1.19
1.16 SET NUM:$V(STR)
>DO 1
NUMBER PLEASE §§§
USE ONLY TWO DIGITS PLEASE
NUMBER PLEASE é;
THANK YOU
>
The reader will note that in applications programs it is safer to
use a READ command followed by appropriate syntax checking than to
use an ASK command. This technique allows programmed recovery from
input errors.
5 . 1 . 4 SINTEGER (NVE)
This function returns the integer portion of the numeric valued ex—
pression NVE (i.e., the fractional part, if any, is not returned).
For example:
$I(30.26) Returns the numeric value 30.
$I(AGE/5) If AGE contains the numeric
value 59, the integer value
returned is 11.
IIIIII)
5.1.5 $FIND(SVE1,SVE2,NVE)
The $FIND function (SF) searches for the occurrence of the string
SVE2 within SVEl. NVE is an optional argument and, if present, the
search through SVEl begins with the NVEth character; otherwise, the
search begins with the first character of SVEl. If $F "finds" SVE2
within SVEl, it returns a number that represents the character posi—
tion following the last character of SVE2. If $F does not find SVE2
within SVEl, it returns a zero. For example, where
STR="ABCDEFGHIJKLMNOP"
the following $F functions will return the values indicated.
$F(STR,"A",1) returns 2.
$F(STR,"A",3) returns a; A does not occur after
the third character in STR.
$F(STR,"EFG",1) returns 8.
$F(STR,"ACD",1) returns U; the string ACD is
not found.
5.1.6 $BOOLEAN(BOOLl,NVE1;BOOL2,NVE2;...;BOOLn,NVEn)
Very often it is desired to type one of tw0 messages or to branch to
different Steps depending on some condition in a program. This type
of operation, where it is desired to do "A" if one thing is true, "B“
if something else is true, or "C" if another condition is true, can
be achieved with the SBOOLEAN function. The SB function tests
multiple Boolean expressions and as.soon as it finds one of the
expressions true, returns a corresponding numeric value. For example,
assuming le, Y=2, E="ABE", then
>T FD(X>Y:1:X=3:X+Y?FE”A",X-Yi1r”)
'1
>
results in evaluation of the expression X—Y and typing of -1.
If the returned numeric value is a part or step number, it can be
used as the argument to a GOTO, in which case a controlled branch is
executed. It could also be used as the third argument of a SPIECE
function where the string variable contains multiple messages and the
$B controls which message the $PIECE would return. For example, if
the variable X contains "HELLO, GOOD BYE", and the variable D controls
the typing of either HELLO or GOOD BYE, depending on whether it
5-4
contains a 2—digit number, then:
1.1% T $P{X:"s":$B€D:2N:131:23)
would result in typing HELLO if D contains a 2—digit number, and GOOD
BYE otherwise.
The $8 function allows argument pairs to be separated by either commas
or semicolons. The advantage in using semicolons is that the eye
more easily can spot the separation of pairs than it can with commas.
The function does not evaluate any of the numeric arguments except
those within the NVE which it is returning. This allows the other
NVE's to contain undefined variables. One requirement of the function
is that there THEE be at least one TRUE Boolean expression; therefore,
it is suggested that the last Boolean argument contain an always
TRUE value, such as the number 1.
5.1.7 $DEFINE (variable name)
The $DEFINE function ($D) can be used to check the data type of either
local or global variables. The variable to be checked is simply named
as an argument to the SD function. $D returns one of six number values
as follows:
U undefined
1 string valued datum
2 numeric valued datum
3 (spare) returned
4 pointer to structure at lower level for global
. . variables
5 p01nter and string valued datum only (Ch. 6)
6
pointer and numeric valued datum
5.1.8 $NEXT(NVE)
$N returns the number of the first MUMPS Step following the Step
specified by NVE. For example:
$NEXT(0) returns the Step number of the
first Step in the program.
$NEXT(¢.99) returns the Step number of the
first Step in Part 1.
If there are no Steps after the value of NVE, SN returns zero (g).
5—5
5 . 1 . 9 SHIGH (VAR (SUBSCRIPT) )
$HIGH returns the value of the lowest subscript numerically greater
than the specified subscript of the given array. For example, if
the array name ABC has the following defined values:
.3C11)
ABC(l.5)
ABC(3.12)
then the following values are returned by SH:
$H(ABC(fi)) returns 1.
$H(ABC(1.1)) returns 1.5.
$H(ABC(3.12)) returns U.
Notice that if there are no numerically greater subscripts, SH returns
zero (fl).
5.1.10 The $OBTAIN and SQUERY Functions
It is frequently useful to retrieve information from a global accord-
ing to its physical arrangement rather than the logical arrangement.
MUMPS does not physically sort a new entry at a level into ascending
subscript order, but finds a "convenient" place within the file at
that level. Therefore, while a file may logically consist of
entries at subscripts l, 3, 7, and 15, the physical layout may very
well be 3, 1, 15, 7, in-that order. As the file at that level gets
larger, several disk blocks may have to be allocated for it, and it
would be useful to know the physical order of the entries to minimize
the number of disk accesses.
In many cases, it is necessary to consult every entry of a file at a
certain level, in order to establish a successful "hit" (e.g., in
the case where the first three letters of a surname are mapped to
the first three levels, and the balance of the surname is stored,
along with others having the same first three letters, in a 4th
level sequential file). The SOBTAIN and $QUERY functions have been
designed to aid the MUMPS programmer when he encounters this need.
5.1.10.1 SOBTAIN (GLOBAL NAME (SUB1,...,SUBr)) —- $OBTAIN causes a
search of the Specified global array to be performed to determine if
a level of subscripting exists below that specified in the argument
(SUBn). If the search is successful, the number of the (physically)
first subscript or node is returned. If only an empty node exists
(all data has been KILLed), a —l is returned. If there is no lower
level present, an UNDEF error results. For example, if there exists
a global called "A" having the following physical structure:
+A(3) (pointer only)
+A(3,7) "String A“
¢A(3,2) "String B"
+A(3,4) "String C"
+A(3,l) "String D"
The command:
SET J=$OBTAIN (+A(3))
causes J to be set to the numeric value 7 and sets up the global for
access at this level (i.e., naked syntax references can now be made
at this level). If, in the above example, the command:
SET J=$OBTAIN (+A(3,4))
is issued, an UNDEF will be caused since there are no lower levels
defined in the structure. In practice, the user should utilize the
$DEFINE function if there is any doubt as to the existence of a lower
level.
5.1.10.2 $QUERY (GLOBAL NAME (SUB ...,SUBn)) -- $QUERY causes a Search
1!
of the specified global array to be performed at the current level to
obtain the next (physically sequential) subscript. If the search is
successful, the number of the next subscript is returned; otherwise,
a -l is returned.
This function is typically used in conjunction with the $OBTAIN
function to sequentially search a level completely in the physical
order of subscript occurrence. The following example shows a typical
application of both functions. ‘
Assume the global name is +A, and that I, J, and K are
subscript values for the first three levels. Further,
assume that X contains the string to be searched for at
the fourth level. D is a temporary variable for inter-
mediate results.
19.10 SET D=$D(+A(I,J,K))
19.20 IF D=4: D=5! D=6 DO 20 QUIT
19.30 TYPE "NOTHING TO SEARCH"
20.10 SET D=$OBTAIN(+(K))
20.20 IF D=-l TYPE "NOTHING FOUND"_QUIT
20.30 IF X=(D) TYPE "FOUND IT" QUIT
20.40 SET D=$QUERY(+(D)) GOTO 20.20
Comments :
1. Part 19 proves there is a structure to search and
calls on part 20 to do the search.
2. Step 20.10 causes the global to advance to the
fourth level as well as get the first physical
subscript at that level.
3. Step 20.20 checks for end of file.
4. Steps 20.30 and 20.40 can use the naked access
at the fourth level.
5.1.11 $Z(NVE)
The $Z function returns a pseudo random number of modulus NVE.
5.1.12 $KORE
The $KORE function is a feature of MUMPS which permits a program to
access any specified core location. $KORE should only be used in
conjunction with an assembly listing of the operating system and is
provided primarily for use by system programming or management
personnel. This command is key protected for system security. Com-
plete information on the use of $KORE is provided in Chapter 7 of
MUMPS Operator's Guide (DEC-lS-MMUPA-A-D).
String Functions included in MUMPS are:
$CHARACTER
$EXTRACT
$PIECE NOTE
SSTEP String functionS'cannot be nested
STEXT together.
$MONEY
Each of these functions is described in the paragraphs that follow.
5.2.1 $CHARACTER(NVE)
The $CHARACTER function ($C) converts the number value NVE to a
character string. For example:
$C(33) yields the character string “33".
$C(X) yields the character string "1U.92"
where X=10.92.
The resulting string expressions can be evaluated by string com—
parison operators (:, =, [, ]) for format centrol, etc.
5.2.2 $EXTRACT(SVE,NVE1,NVE2)
$E EXTRACTS all the characters from SVE that are between the NVElSt
and NVE2nd
NVE2, $E returns a "null string". The null string can be represented
in MUMPS programs by the notation "". If NVE2 is equal to NVEl or if
NVE2 is omitted, SE returns the NVElSt character only. If the length
of the string is such that $E runs out of characters before satisfying
Luvs-1n MU‘D‘I any: mum") 4. A
MU L11 LV VHJ. all-U LV VJ-IL I L11:
the NVElSt character and the end of the string. Only the integer parts
of NVEl and NVE2 are considered.
character locations, inclusive. If NVEl is greater than
This function is frequently used in editing routines. By combined use
of the SEXTRACT function with the concatenation operator (.), any seg—
ment of a string may be extracted and replaced by another. For example,
assume that the string variable NAM="JOHN DOE" and we want to change
it to last—name first, comma, first-name last. The following state—
ments will do it:
SET LST=$EXTRACT(NAM,$FIND(NAM," ",l),$LENGTH(NAM))
SET FIR=$EXTRACT(NAM,1,$FIND(NAM," ",0)—2)
SET NAM=LAS.",".FIR
5.2.3 $PIECE(SVEl,SVE2,NVEl,NVE2)
Often, to save space, a programmer will pack several "pieces" of data
in a single string, thus cutting down on overhead space and access
time. The SP function examines the string variable SVEl, which is
assumed to be divided into "fields" delimited by the first character
of SVE2. $P returns the text in the fields specified by the two
arguments NVEl and NVE2. If NVE2 is equal to NVEl, or if NVE2 is
omitted, $P returns only the NVElSt field without delimiters. If
there is no NVEl field, then a null string is returned. If $P runs
out of fields before satisfying NVE2, it returns any characters be—
tween the SVE2 delimiter and the end of the string. For example, where
STR="34,6.E9,JOHN D0E,BOST0N,JUNE.22“
DEL=II ' ll
then the following would be true:
$P(STR,DEL,3) returns "JOHN DOE"
$P(STR,DEL,2) returns "6.09"
$P(STR,DEL,3,4) returns "JOHN DOE,BOSTON"
$P(STR,DEL,4,1U) returns "BOSTON,JUNE,22"
$P(STR,DEL,8) returns a null string, since there
is no eighth field in SVEl
$P(STR," “,l) returns "34,6.fi9,JOHN"
5-10
The delimiter may be Specified literally, as Well as by a variable.
If the delimiter within the argument is a punctuation mark, the same
mark can be used as the delimiter in the SP statement without quota-
tion marks:
$P(STR,3) returns "JOHN DOE"
5.2.4 $STEP(NVE)
The $STEP function ($5) returns the string value of the Step specified
by NVE, without the STEP NUMBER. This function may be useful in edit-
ing applications where it is necessary to treat the contents of a Step
as a string.
5.2-5 w
The STEXT function evaluates the_numeric argument NVE to return three
ASCII characters. ST is used primarily by MUMPS system programmers.
For example, assume NBR is equal to 6lfil¢28. Then
$T(NBR)
returns the three-character string lAB.
‘ <— optional—4
+ +
5.2.6 $MONEY(SVE1 {;}SVE2{;}SVE3 )
/ /
SMONEY extends the normal range of MUMPS numbers ($1310.71), to
permit operations on numbers which contain up to nine significant
digits and exponents in the range from 1046 to 10-30.
The $M function allows the arithmetic operations +, -, *, /, where
each of the operations has its normal arithmetic meaning. The SM
function accepts only string valued expressions (SVE's), not
ual numeric values. Hence, constants used in $M expressions
must be enclosed in quotes and variables must have been previously
set to string values. For example:
SET X="1.5"
SET Y="-2.3'l (Sign needed only if negative)
SET Z="4" (Decimal point may be omitted)
SET SUM=$M (X+Y+Z)
The value of SUM will be the string "3.2".
SET T=$M (SUM + "1.2")
Since 1.2 is a constant used in a $M expression it must be enclosed in
quotes. Further, other MUMPS functions must not be nested within $M
expressions. This means that the expression:
1.23 SET A=$M("123.4"+$C(72))
is illegal. However, the following will solve this problem:
1.23 SET B=$C(72)
1.33 SET A=$M("123.4"+B)
Unlike normal MUMPS arithmetic operations, a $M expression is
evaluated STRICTLY from left to right, in the order in which the
operations appear. Parentheses are NOT permitted. Thus, a $M
expression containing multiplication and division may indeed yield
a different result from that given by normal MUMPS arithmetic. For
example:
SET A=6, B=9, C=3
SET X=A+B/C ;RESULT X=9
SET A="6", B=ll9ll’ C=u3n
SET X=$M (A+B/C) FRESULT X="5"
In the first example, because it is normal MUMPS arithmetic, B/C is
evaluated prior to addition to A. Hence, B/C = 3, A+3 = 9. In the
second example, because it is SM evaluation, A + B is evaluated first
and then that result is divided by C. Hence A + B = "15", 15/C = "5",
which is the STRICT left to right application of the arithmetic
operations.
If the desired result was X = A + 2, two solutions are possible:
SET T = $14 (B/C)
SET X = $M (A+T)
or
SET X = $M (B/C + A)
In many instances the second solution, which is obviously more
desirable because it is shorter, will suffice. In complicated
expressions it may be necessary to defined sub-expressions and
then use these in a $M function involving only addition and sub—
traction.
In addition to nine digits and an optional sign and decimal point,
string values to be used in $M functions may include an exponent.
The exponent portion consists of an up arrow (+), a Sign, and one
or two digits indicating a power of 10.
1.11 SET X="15++5"
1.21 SET Y="-1.275+-12"
In the first example the result is 15 x 105 or 1500000. In the
second example the result is -l.275 x 10-12 (or -0.000000000001275).
When it is necessary to input a value to be used in a $M function, it
should be input via a READ command rather than an ASK, since the READ
allows the input of string valued variables. When entering data via
READ, the string may contain up to nine significant digits, an
optional decimal point, and Sign, and an exponent. When more than
nine significant digits are entered all digits following the ninth
are interpreted as an equivalent number of zeroes.
INPUT VALUE VALUE USED FOR CALCULATION
"1234.56" 123.456
"36942305.009"_ 36942305
"123456789123T-13" .0000123456789
"600430009523760" 600430009000000
".00032405619342" .000324056193
When values calculated by $M functions are to be printed, they
are entered in TYPE statements just as any other numeric output. Up
to nine significant digits are output with a sufficient number of
leading or trailing zeroes to adjust for the power of ten required.
RESULTS OF CALCULATION I W
1.23456 1.23456
1.5xiol5 ' 1500000000000000
6.78x10'12 .00000000000678
The following examples illustrate many of the features of the
$M function.
Example A:
The following program will input a value N and compute N
factorial. N factorial is defined as the product of all
5-13
integers between 1 and N. It is written symbolicially as N!
Hence 5! = 1 X 2 X 3 X 4 X 5 = 120.
1.1g
1.29
1.25
1.3g
1.35
1.4U
DO 1
ENTER N. PROGRAM WILL COMPUTE N!
READ 1,"ENTER N. PROGRAM WILL COMPUTE N! ",N,!
SET X: H 1 II I FAG: ll 1 II
SET NN=$V(N)
FOR I=1:1:NN SET FAC=$M(F*X),X=$M(X+"1")
TYPE N,"FACTORIAL=",FAC,1
GO TO 1.10
[01
5 FACTORIAL=12U
ENTER N. PROGRAM WILL COMPUTE N! 1U
1U FACTORIAL=36288UU
ENTER N. PROGRAM WILL COMPUTE N1 12
15 FACTORIAL=13U767436UUUU
Example B:
The following program allows the user to enter a value R which is the
radius of a circle. The program calculates the area of a circle of
2
radius R from the equation A=NR .
l.l¢
1.2g
1.39
1.4fl
1.5g
Example C:
SET PI="3.14159"
READ "ENTER R ",R,1
SET A=$M(PI*R*R)
TYPE "FOR A CIRCLE OF RADIUS ",R,"THE AREA IS ",A,11!
GOTO 1.2%
The program is a compound interest problem. The input is a rate of
interest as a percentage. The program determines the number of years
it takes to double $100 at the given rate by compounding interest
annually.
l.fl5
1.1%
1.2%
1.3g
1.4g
1.5T
1.6g
1.7g
SET DBL="2¢g"
READ ll!!,"ENTER INTEREST RATE ",R,1
SET C="1Hg",y=¢
TYPE 1!,"CAPITAL INTEREST YEAR",!
SET INT=$M(C*R),C=$M(C+INT),Y=Y+1
TYPE C," ",INT," ",Y,!
SET X=$M(C-DBL) IF $E(X,1)="-" GOTO 1.4
GOTO 1.1
SIHS
TABLE 5-1
LEGAL FUNCTIONS FOR NESTINGH'
FUNCTION '1‘() BF? NESTED
PRIMARY
FUNCTION .ifi
SBOOLEAN $DEFINE SF SHIGH SINTEGE $KORE SLENGTU $ $OBTAIN $QULRY SROOT SVALUE $Z $CHARACTER $EXTRACT $MONEY $P $STEP $TEXT
N U M E R 1 C S T R I N G
$BOOLEAN X X X X X X X X X X X X X X
$DEFINEI x x x x x x
$FIND
. -I-
SEIGE
SINTEGER
$KORE
$LENGTH
$NEXT
+
$OBTAIN
$QUERY+
$ROOT
$VALUE
$2
$CHAR-
ACTER
$EXTRACT
$MONEY
SPIECE
$STEP
$TEXT
T , , . .- . . .
++Nesting Is permitted only Within the subscript portion of the argument.
X = legal combination.
IIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIII-ll-I-IlllllI-Il-II-I
CHAPTER 6
THE GLOBAL DATA BASE
The MUMPS language allows local data required by a program to be refer—
enced symbolically and space for it to be allocated as needed. Local
data is the set of variables established within the domain of a parti—
cular program, and available and defined only within that program.
The data actually resides within the user partition, and functions as
scratch or transient data. Local arrays are treated as if they are
intended to be sparse i.e., only Subscripts for which data are defined
are allocated space. A symbolic variable used in a program may be
given either a numerical value or a variable length string value. When
it has a String value, only that space required by the string is actu-
ally allocated. Thus, for both strings and sparse arrays, the over-
head of a compiler system does not exist (i.e., maximum sizes of ar—
rays and maximum lengths for string variables are not allocated).
This philosophy is extended to data management on disk. Elements
stored in data files are referenced entirely symbolically; the file
name is similar to that of a local variable name in a program. Fields
in the data file are treated as array elements and referenced by means
of subscripts; subfields are referenced by appending additional sub-
scripts. Data files on the disk thus comprise an external system of
arrays, which provides a common data base available to all programs.
The arrays that make up this external system are called global vari-
ables, and are identified by global array names. A global name (or
file name) consists of the character up—arrow (+) followed by one to
three alphabetic characters. The form of the subscript portion of an
array reference consists of an arbitrary number of numeric expressions
separated by commas and enclosed by parentheses.
Like local arrays, the range of legal subscript values for global ar-
rays is 0.00 to +327.67. Use of values outside this range will be
treated as an error (MAXIM). Each addressable element of a global ar-
ray is called a node. Thus +A(l), +GHC(7,3,4), and +B(l,2,9,3,7.46)
f
are all nodes. The structure of these arrays is hierarchical, and any
node within an array tree may possess either a numeric or a string data
value and/or a pointer to a lower level in the tree. Data may be
stored at any level, and there are no constraints to the dimension or
size of the array. In addition, the quantity and magnitude of sub-
scripts for an array are dynamic so that both the content of an array
and its structure may vary.
6.1 USE OF OPEN AND CLOSE COMMANDS
To avoid time—sharing conflicts, a program must use the OPEN command to
prevent other programs from changing global arrays which it is in the
process of altering. The argument of OPEN may be one array name or a
list of array names. For example:
OPEN 16
or
OPEN TA,TB,1C
OPEN prevents any other program from altering data in any of the specie
fied arrays. The effect of OPEN is cancelled when the program halts
or at the occurrence of the command CLOSE, which does not allow any
arguments, and releases all opened arrays to other users in the system.
If an OPEN is unsuccessful, all open arrays will be CLOSEd, and MUMPS
continues trying to open the arrays until it is successful. Also, a-
program error will CLOSE all globals. A program may not alter a global
array it has not OPENed.
If the CLOSE command is combined with other commands on the same line,
C must be follOWed by a double space: e.g. >CLJLJ3541. If a single
space were used, MUMPS would attempt a "CALL G".
Since modification of content and structure of a global array may be
caused by a variety of programs in the System, a particular program
must sometimes examine the current configuration of an array before
attempting to access or update it. MUMPS provides a Set of functions
to determine the type and structure of a global array. These functions
($D and SH, described in Chapter 5) permit the programmer to locate
the nodes where information is stored within an array as well as empty
nodes that are available for data storage.
6.2 USE OF THE $DEFINE FUNCTION
The program may determine the data type of a specified node by applica—
tion of the function $DEFINE as $DEFINE(+ARRAY(NVE1,NVE2,...)). The
numeric value returned represents the current status as follows:
fl — undefined with no datum or structure associated
with it
1 - string valued datum only
2 — numeric valued datum only
6-2
3 - not used
4 - pointer to structure at lower level only
- 5 - pointer plus string valued datum
6 - pointer plus numeric valued datum
6.3 USE OF THE $HIGH FUNCTION
The program may determine the next sequential node at a given level by
means of the function $HIGH as in $HIGH(+ARRAY(NVE1,NVE2,...,NVEn)).
The function returns the lowest subscript value which is on the same
level as NVEn and which is higher than NVEn. To determine the exact
state of that defined node the $DEFINE function must be used. If, upon
completing the scan of a file, no subscript value greater than that
specified is found, $HIGH returns a value of zero (U). Thus, when $HIGH
is used as an instruction in an iterative process, the value returned
must always be checked for zero as an escape. Consider the following
example where TA consists of nodes +A(l), +A(1,l), +A(1,2), and
¢A(l,l,2).
>T $H(TA(1 1))
2
>T $HCTA(1,1,1))
2
>T $H(TA(1 2))
U
>
6.4 STORAGE OF DATA IN GLOBAL ARRAYS
The storage of data into an array is accomplished solely by the assign-
ment command, SET (i.e., READ and ASK may not be used to directly store
data in a global array). Consider the following statement:
SET TAPRCUN,NAME):"JOHN DOE",1APR(UN,AGE):34
Assume the global array name +APR is reserved as an active patient
record file. Each patient entry in the file is accessed through his
hospital unit number, in this case a local variable UN. Both NAME and
AGE are also local variables whose values indicate the appropriate cate-
gory at the second level of the array. This Statement then assigns the
string value "JOHN DOE" and the numeric value 34 to the specific second
level categories, name and age respectively. Subsequently, a statement
such as:
6—3
SET TAPRCUN,CHEM,N)=$DATE.",”.TEST
might define the Nth laboratory test in the Chemistry Lab with the
double field entry of the date concatenated with the test name.
6.5 RETRIEVAL OF DATA FROM GLOBAL ARRAYS
Retrieving data from global arrays is no different from retrieving
data from local arrays. The statement:
TYPE "THE AGE OF ",tAPRCUN,NAME)," IS ",TAPRCUN,AGE)
could result in outputting the following.
THE AGE OF JOHN DOE IS 34
To print out a list of a patient‘s laboratory tests (assuming +APR(UN,CHEM)
is the total number of tests definedh the following statement might be
used:
FOR I:1:1:TAPR<UN,CHEM) T ITAPR(UN,CHEM,I)
The KILL command when applied to a specific node in a global array,
prunes the array tree at that node. Any data value and/or array point-
ers to lower level nodes are removed, and that node reverts back to
an undefined status. The statement KILL iAPR1UN)would delete all in—
formation for the patient defined by the local variable UN.
6.6 NAKED GLOBAL VARIABLES
Included in the global array syntax is the "naked" global variable.
The form of the naked variable consists of the up—arrow followed by a
subscript (or a series of subscripts) enclosed in parentheses. This
notation is equivalent to the last previously used global array refer—
ence, except that the value of the last referenced subscript is replaced
with the value of the first subscript in the naked variable. For ex—
ample, the statement:
TYPE " THE AGE OF ",1APRCUN,NAME)," IS ",1‘(AGE)
is equivalent to the previous example that typed NAME and AGE.
Once a block of data accommodating a single level of subscripting is
referenced, it is maintained in core memory until a reference is given
to a different level by the program. Use of the naked variable then
permits other data at the same level to be referenced merely by speci-
fying a terminal subscript, so that once a level is reached often no
further disk access need be made to manipulate associated information.
If any data in a block is altered, it is only written back on the disk
when a reference is made to a block other than the one that is in core
memory, when a CLOSE or HALT command is given, or when an error causes
a program to crash.
By far the most common errors that occur in the use of global arrays
stem from the use of the so—called "naked" variable syntax. The fol—
lowing examples illustrate some of the problems that may be encountered.
These examples represent only a few of the many possibilities for pro—
ducing erroneous results when using naked variables. It is a powerful
syntax but one that must be used cautiously.
Example A.
IF $D(TA(I,J)):U SET TCJ):UALUE
In this case, the user is testing the status of +A(I,J) by means of the
$DEFINE function. If $DEFINE returns a zero value, that node is unde-
fined. The user then reasons that since $DEFINE has brought him to the
desired level, he is safe in using the naked variable. Incorrectll
The user has no way of knowing where the search has ended and thus can-
not know the current level. For example, the search may have ended at
the first level if no TA(I) node was defined. To be safe, the user
Should spell out the full name as in:
IF $D(TA(I,J)):U SET TA(I,J)=VALUE
Of course, if $DEFINE returns a non-zero result, the use of naked vari-
ables is perfectly safe.
Example B.
OPEN TG SET TCI):VALUE
To avoid time sharing conflicts, the first global reference after an
OPEN may not be a naked reference.
Example C.
SET TGCI,J,K):T(K)+1
This command string is legal, but the result may not be what the user
expects. The problem lies in the order of evaluation that MUMPS uses
for processing a SET command string. The first side of the equal Sign
(=) that is evaluated is the right side. The use of the naked variable
in this case will reference the last used level, not necessarily the
same as +G(I,J,K) on the left side of the equal sign.
A more proper use would be:
SET TCK)=?G(I,J,K)+1
This command string will cause the appropriate node to be incremented
by one.
Example D.
FOR I=1:1:N SET T41,D):VAL(I>
While this example seems benign enough, it is not. Each time MUMPS
goes through the FOR loop, it will go down another level in the global
array!!! The referenced nodes will look like:
6.7 THE JOIN COMMAND
Frequently, nodes may share data at a lower level. For example, there
may be a node for each of the proprietary names of a particular job
while lower—level data remains the same in each case. The JOIN command
can be used to allow nodes to "share" the same data at a lower level.
For example:
JOIN +A(i,3,2)++A(7,5,5,4)
"joins" the A(l,3,2) node to the A(7,5,6,4) node; as a result, the
statement
TYPE +A(1,3,2,5)
will actually output +A(7,5,6,4,5).
There are presently several implementation restrictions on use of the
JOIN command. In particular, JOINS can only be made within a single
global array (i.e., the names must be the same). Also, the node on the
left may not have a pointer to a lower level.
CHAPTER 7
PROGRAM AND DATA PROTECTION SCHEME
Program and data file protection is an important part of the MUMPS
system. Through the use of the MUPAK utility package, the system
manager can control every aspect of application program and data
filing and retrieval. Programs are protected from unauthorized use,
inspection, or modification by a sign—in scheme involving user name
codes, program name codes, and program access keys. Global data is
protected by access keys that prevent unauthorized reading or data
modification.
MUMPS and MUPAK together provide a comprehensive protection scheme,
but the number of protection features that are actually applied may
be determined by the installation manager. Some installations may
require absolutely no protection -- others may require considerable
protection due to their public nature.
Most of the protection scheme is established through the MUPAK
utility package. Program protection keys, however, are assigned by
the MUMPS program author when the program is filed.
7.1 DEFINITIONS
Some of the terms that describe users, terminals, programs, and data
files in the MUMPS system are defined below.
7.1.1 Mode of User Interaction
Direct: In direct mode, the user can enter MUMPS commands for
immediate execution, or compose and enter numbered MUMPS program
steps. Direct mode is available only at terminals that are
assigned developmental Status (defined below). Different log—in
procedures give the user scratchpad privileges, permission to
create new programs, or permission to use or modify existing
programs.
Indirect: Indirect mode is in effect while stored program steps
are being executed sequentially by MUMPS. The program may type
out conversational queries and allow the user to enter data, but
the user cannot enter direct MUMPS commands or compose program
steps.
IIIIY
7.1.2 Program Status (D or I)
Programs are assigned D or I status by log-in procedures. The MUPAK
utility package can also assign certain I-status programs to operate
as "autoload“ programs for specified users.
D-Status (Develgpmental): D—status programs may be requested by
name during log—in at a developmental terminal. If a D-status
program is requested during log-in at an operational terminal,
MUMPS prints the message NOT FOUND.
I—status (Independent): I—status programs may be requested by
name at operational as well as at developmental terminals.
D-status programs can be converted to I-status by a special
log-in procedure.
Load and Go: All I-status programs are considered "load and go".
When a user logs in in I—mode and requests a library program by
name, the program begins execution automatically at the lowest
non-zero step number. The terminal remains in I—mode, so the
user cannot stop execution and examine or modify the program
itself.
Autoload: An autoload program is an I-status program that has
been assigned by MUPAK to begin execution when a particular
user signs in. The user does not Specify a program name. An
autoload program can also be assigned to begin execution in
response to the operation of the BREAK key at a "tied"
terminal.
7.1.3 Terminal Privileges
Each MUMPS terminal can be assigned by the MUPAK utility package to
serve in one of four privilege categories —— developmental, opera-
tional, tied, or closed. DevelOpmental terminals have unrestricted
privileges but log—in is elaborate. Other terminal classes have
progressively fewer privileges but simpler log-in procedures.
Developmental: Developmental terminals are allowed access to
direct mode for execution of direct MUMPS commands and composi-
tion and filing of MUMPS applications programs. Other programs
of D or I status can be brought in for execution or inSpection
in direct mode. A developmental terminal can also execute D- or
I—status programs in indirect mode. Direct or indirect mode is
7-2
established at the time of log-in, not by the type of program
that is in effect.
Operational: Operational terminals are restricted to I-status
programs. Through specific log—in procedures, the user can re—
quest load-and—go programs by name, or begin execution of an
"autoload" program associated with his user name code.
Tied: Tied terminals are restricted to a single autoload program
that begins execution when the BREAK key is pressed. No other
log-in is necessary.
Closed: Closed terminals are the most restricted from the user's
standpoint, in that he cannot log in or otherwise request service
However, closed terminals can be controlled by a MUMPS applica—
tion program that prints out instructions and requests information
nput to be entered at the keyboard.
7.1.4 Protection Keys
A key is a positive MUMPS number in the range 0.01 through 1310.71 in—
clusive. If the key associated with any key—protected item is zero,
then the item is considered to be unprotected. All previous descrip—
tions in the body of this manual have assumed no protection for the
sake of simplicity.
7.2 DEVELOPING, FILING, AND USING MUMPS PROGRAMS
MUMPS applications programs are developed, debugged, and modified in
the D (direct) operating mode at a terminal that has been assigned
developmental status. To prevent unauthorized users from filing new
programs or modifying existing ones, the user's intent must be es-
tablished at the time of log—in.
By citing a scratchpad (SP) key during log-in, a user can gain access
to a developmental terminal for direct command execution or the
creation of short temporary programs.
By citing a nonexistent program key (NE) during log—in, the user can
establish a program name, create the program, and file it permanently
in the program library. A protection key can be assigned at the time
the program is filed.
Users can request an existing program for execution by specifying a
program name during log-in. However, access in D—mode to key—protected
programs is denied unless the correct key is specified. Thus, programs
cannot be examined or modified by unauthorized users. Any program can
be executed on request without citing the key, but a protected program
cannot be inspected or changed unless the key is cited.
Operational terminals can only request and execute I-status programs.
(However, these programs may call or overlay programs which are filed
in D-status.)
Codes and symbols used during log-in are defined in Table 7-1. Log—in
examples are described in Table 7-2.
7.2.1 Scratchpad Operation
Log-in: Scratchpad log-in permits a user to operate a terminal
without filing any programs. Log in as follows:
1. Press the BREAK key. MUMPS responds by typing:
MUMPS LINE 1
ID
2. Type user name, scratchpad key [in brackets], and an
asterisk:
MUMPS LINE 1 (User input is
ID APCC3.23* underlined.)
If no scratchpad key has been assigned, the key
number and brackets are omitted and the asterisk
is typed after the user name:
MUMPS LINF 1
ID-ABC*
3. Press the ENTER key. (The ENTER key may also be
labeled ESC, ALT MODE, or PREFIX, depending on
the type of terminal you have.) If your ID codes
are valid, MUMPS responds with a CRLF (carriage
return-line feed) and types a right caret:
MUMPS LINE 1
ID AEGIS-23*
>
The right caret indicates that the terminal is in
direct mode and will accept direct MUMPS commands
or indirect step entries.
Scratchpad Capabilities: The commands, example programs, and
demonstrations appearing in the body of this manual assume that
the terminal is in "scratchpad'i mode of operation; the terminal
is in direct mode and the user is able to execute direct com—
mands, create new program steps, execute these programs, or
Item
User Name
Program Name
Mode
Designator
Scratchpad
Key
Nonexistent
Program Key
Protection
Key
Table 7-1
Log—In Conventions
Example Explanation
ABE Established through MUPAK (usually
three letters).
ABE:TIM User ABE's program TIM. (Program
name, following colon, can be up to
three letters. Numbers are not
permitted.)
Asterisk specifies log-in to direct
mode. If asterisk is omitted, only
I—Status programs can be invoked.
[SP] Authorizes uSe of a terminal in
scratchpad mode. Actual key is
assigned through MUPAK.
[NE] Authorizes use of a terminal in
creating and filing a new program.
This key is also assigned through
MUPAK.
[N.NN] Authorizes a D-mode user to examine
or modify a protected program. Keys
are assigned to programs by the user
when the program is filed.
NOTE
Keys are positive MUMPS
numbers (0.01 through
1310.71).
7-5
(BREAK)
in STEC3-253*
>
(BREAK)
MUMPS LINE 1
ID STE:TIME2-593* NEW D
>
(BREAK)
Mumps LINE 1
ID §l§
THE TIME IS 7:55
THANK YOU
(BREAK)
MUNPS LINE 1
ID STE:TIM
THE TIME IS 7:56
THANK YOU
(BREAK)
MUMPS LINF 1
ID STE:TIME37.2]*I
>w
Table 7-2
Log-In Examples
User STE logs in for a session of D—mode
scratchpad operation. The [SP] key can
be omitted if set to 0.00 by MUPAK.
User STE logs in to create program STE:TIM.
MUMPS responds by authorizing the NEW
program and classifying it in D—status.
The INE] key can be omitted if set to 0.00
by MUPAK.
User STE logs in for his autoload program,
which executes and terminates automatically.
(MUPAK assigns the Program STE:TIM as STE's
autoload program.)
Any user logs in in I—mode for the STE:TIM
I-status program. The program operates
as a load-and-go (executes automatically
and terminates).
User STE logs in for his I-status program
STE:TIM, specifies the protection key, and
requests D-mode (*). Note that MUMPS prints
out the filed status of the program (I). The
program enters his user partition where it
can be run, inSpected, or modified.
1.1m T "THE TIME IS "
1.15 S HR:SI($T/36)
1.2? S MIN=$ICCST-HS*36)*1m/6)
1.25 T HE,":"
1.3G I MIN<10 T "G",MIN @
1.35 T MIN Q
>D 1
THE TIME IS 8:01
>
call and overlay other filed programs. While programs are being
executed automatically by MUMPS, the "indirect" mode is in effect:
everything that takes place is under control of the program. (To
interrupt execution of a long or repetitive program, press the
BREAK key. The terminal will step executing and return to the
direct mode.)
In the scratchpad mode, programs cannot be filed, since the log-in
procedure does not specify a program name. When a session at a
terminal is ended by a HALT command, the programs and any
associated local variables in the user partition are erased. Even
if the same user logs in again in scratchpad mode, the partition
is empty.
Scratchpad-mode programs can be saved on paper tape or DECtape,
as described in Chapter 4. When the user logs in again he can
read in the same programs, resume development, and execute them.
Call and Overlay Commands: A scratchpad user can employ the
CALL and OVERLAY commands to bring in filed programs for execu-
tion. However, an unfiled developmental program in the user
partition will be lost when the CALL or OVERLAY takes place.
MUMPS will attempt to return to the developmental program, but
will not find it in the file. An OVERLAYed program simply remains
in the partition after it has been completed. No attempt is made
to retrieve the original program.
The effects of CALLing or OVERLAYing key—protected programs in
D—mode are discussed later.
7.2.2 Creating and Filing New Programs
Log—in: The intent to create and file a new program must be de-
clared at the time of log—in. After the BREAK key is pressed and
MUMPS responds with the request for ID, type the user name, a
colon, the proposed program name (also one to three letters),
the NE key, and an asterisk followed by (ALT). For example:
MUMPS LINE 1
ID STE:GNGE2.SGJ*
If the uSer name is accepted, the program name is legal, and the
key is valid, the system responds "NEW D" and enters direct mode
(indicated by a right caret):
MUMPS LINE 1
ID STE:GNGE2.SQJ* NEW D
>
The "NEW D" response indicates permission to develop a program of
the specified name, and that the program is classified as a
develOpmental program (D-mode) (the log—in method for changing
the program to I—mode appears later).
Filing a New Program: Once the program has been composed and
debugged to the uSer's satisfaction, it can be stored using the
FILE command (usable only in direct mode), for example:
>F
The program is filed under the uSer name and program name speci—
fied at log—in.
Assigning Protection Key: Protection keys prevent other D—mode
users from examining, altering, or deleting filed programs. A
protection key may be assigned at the time the file command is
given, for example:
>F [2.53
A new program initially has a key of zero (no protection). If
no key is assigned, it remains zero.
“hanging and Re-Filing; After a program has been filed, it re-
mains in the user partition until the use of the terminal is
HALTed. The user can continue to run it, or even modify it and
re—file. Every time a FILE command is entered, the program
currently present in the user partition replaces the previous
program in the file. If the new program has fewer steps, unused
steps of the old program are erased. However, a program must
contain at least one step in order for the FILE command to take
effect.
Once a key has been assigned, it need not be repeated. The FILE
command leaves the previous key intact. To change a key, simply
use a FILE command with the new key specified. To remove a key
from a previously protected program, uSe:
>F [fl]
Using Calls and Overlays: While develOping a program, the user
may want to CALL or OVERLAY another filed program. The develop—
mental program must be filed before a CALL or OVERLAY command
is entered. Otherwise, MUMPS will be unable to retrieve the
original program.
To CALL or OVERLAY programs filed under another user name, the
form ABC:DEF (user name:program name) may be used. For example,
the command:
>CALL A;SAM:CHG
CALIs current user's program A and user SAM's program CHG. If no
user name is given, MUMPS assumes that the user name is the last
one specified by a CALL or OVERLAY. In the example above, if the
program SAM:CHG contains the statement
>CALL DJB
SAM's program DJB will be CALLed. The current user name is stored
on each CALL and restored on return.
Referencing Key-Protected Programs: If a program referenced by
CALL or OVERLAY is protected, the key may be cited either in %K
or in the command itself:
>CALL ROG:ERTE19.23
In a CALL to a protected program, citing the key allows the user
to inspect the CALLed program in direct mode if there is an error
or interrupt. If a program CALLS a protected program without
citing the key, the protected program will run in load-and—go
fashion, but the terminal cannot be returned to direct mode until
the protected program is done and an unprotected program level is
reached. If there is an error, or if the user attempts to
interrupt execution with the BREAK key, MUMPS will erase the
partition and return to direct mode.
Every OVERLAY attempt in direct mode is by definition an intent to
"peek" at the program, since the OVERLAYing program is loaded into
the partition and the terminal is returned to direct mode. There—
fore, the key of a protected program must be cited in an OVERLAY.
If the user attempts to OVERLAY to a protected program without
citing the key, the partition is erased and a ?KEY error message
is printed.
7—9
Programs intended for execution in I—mode may themselves CALL or
OVERLAY D—status or I—status programs without Specifying keys,
even though these programs are key-protected. Since an opera—
tional terminal user cannot stop execution and take control in
direct mode, keys can be disregarded. Keys prevent programs from
being inspected by unauthorized users.
Notes on Keys:
1. Where a key is not required (the key is zero) citing a key
is not an error. Thus %K need never be cleared. (%K is
set to 0.00 during log-in.)
2. A key cited syntactically (within brackets) takes
precedence over the %K value.
3. Although I—mode programs are not protected from being run,
the program may contain an internal "password" scheme to
prevent unauthorized uSe.
7.2.3 Modifying Existing Programs
Once a program is created and filed, the originator can run it and
modify or update it. So can any other D-mode user, if he knows the
program name and protection key.
Log—In: To obtain an existing program and retain control in
Demode, the user must specify the program name and protection
key, if any, at the time of log—in:
BREAK
MUMPS LINE 1
ID STE:AE12.5]*D
>
If MUMPS finds a program of that name and the protection key is
correct, MUMPS prints the program status (D or I) and the caret
indicating that the program is present in the user partition.
Changing a Program and Re-Filing: The uSer can execute the program
and add, modify, or delete steps just as when develOping new pro—
grams. A new version can be filed using the FILE command. A new
protection key can be assigned when the program is re—filed. (If
no key is specified, the previous key stays in effect.)
IN USE Condition: In order to prevent time—sharing conflicts, a
program is considered to be IN USE as soon as any terminal logs in
specifying that program and getting control in direct mode. Until
that terminal logs out no other terminal may log in for that pro-
gram in direct mode. Thus, it is impossible for two terminals to
simultaneously change and file the same program.
7.2.4 Changing Program Status (D, I, and X)
Programs are assigned D(developmental) status when they are created.
D-status programs cannot be invoked for execution by I—mode users. If
a user attempts to log in for use of a D—mode program in I—mode (i.e.,
autoload or load-and-go), MUMPS will respond "NOT FOUND".
Changing D to I: In order to release a D—status program to the
program library for autoload or load—and—go uSe, it must be
changed to I—status. This is done at log—in time by adding an I
after the asterisk in the identification entry:
(BREAK)
MUMPS LINE 1
ID STE:AE12.5]*I OK
ID
MUMPS types OK, indicating that the named program has been changed
to I status, and asks for a new ID.
CAUTION
Before releasing a program in I status, the user
should make sure it contains a quit or HALT
command or other means of graceful exit. Since
an I—mode user's ability to interrupt execution
depends on the condition of the %E system variable,
he may not be able to terminate a program that
loops endlessly. ‘
Changing I to D: An I-status program can be changed back to
D status (withdraWn from autoload or load—and—go use) by adding
a D after the asterisk during log-in.
Expunging (X): Any existing program can be expunged (deleted
from the file) at log—in by adding an X after the asterisk:
CBREAK)
MUMPS LINF 1
ID STE:AC12.S]*X OK
In STF:A[19.53* nor Fouyp Program has now been deleted.
ID '—_-——__'——‘ Replying with a null string
THANK YOU logs out the terminal.
An expunged prOgram disappears from the file. The program name
can be used again.
7.2.5 Changing a Program Name
The following procedure changes a program named XYZ:A*D to the name
SDH:B*D
1. Log in to create the new program SDH:B*
2. When MUMPS responds
NEW D
bring in the existing program with a direct OVERLAY
command, i.e.:
>0UERLAY XYZ:A
or, if there is a key:
>OUFRLAY XYZ:AE13.21]
3. When MUMPS responds with the right caret, indicating that
the called program is in the uSer partition, enter a FILE
command. The program will be filed under the name speci-
fied at log—in. Assign a protection key, if desired.
4. Sign off (HALT).
5. Log in again using the name of the old program and add an
X to expunge it from the file.
7.2.6 Using Programs in I—Mode
In actual practice, the direct mode is restricted to users who are
authorized to create programs and file them. Day—to-day users, at
'operational terminals, do not compose programs. Such terminals are
limited to conversational data entry and message printout under control
of an applications program. The terminal never leaves the I—mode to
permit direct command insertion or program composition. I—mode users
cannot invoke developmental (D-mode) programs by name for execution.
Log—In: I—mode users may obtain programs in three ways: by user
name/program name (load—and—go), by user name only (autoload),
or by operation of the BREAK key (at tied terminals). I-mode
log—in codes (user names and keys) are controlled through MUPAK
by the MUMPS system manager. If the name and key given at log-in
are legal, MUMPS loads the program and begins execution at the
first non—zero step. The terminal is never released to direct
control. The result of an error or an attempt to stop the program
by pressing the BREAK key depends on the value of the %E system
variable (Table 4—l). When the program runs out of steps, or
reaches a quit or halt command, MUMPS terminates the session at
7-12
the terminal. To obtain another program, the user must log in
again.
Requesting Programs by Name (Load—and-Go): An I-mode user signs
in for a Specific I-mode program by entering user name and program
name. The asterisk is not used:
MUMPS LINE 1
ID STE:TIM
Since I-mode users cannot inSpect programs, the key numerals (if
assigned) and brackets are omitted.
Autoload Program: Any I-mode program may be assigned by MUPAK to
a particular user name as that user's "autoload" program. For
example, program ABE:TIM[37.3]I could be assigned as the autoload
program for user ABE. User ABE only needs to enter his user name
in order to obtain the program, which begins immediate execution.
The same I—status program may be run by anyone who enters the
proper user name and program name at log—in without citing a key;
since direct mode cannot be entered, the program cannot be
examined or changed. An I-status program may always be loaded via
autoload or load-and~go even if it is IN USE or other terminals
have invoked it via autoload or load-and—go.
Tied Terminals: MUPAK can also assign an I-mode program to act
as the autoload program for a specific tied terminal. The program
will load and begin execution in response to an operation of the
BREAK key; no log-in is required. For example, program SDH:A[3.2]I
might be assigned as the autoload program for terminal 5. Whenever
the terminal 5 BREAK key is pressed, that program begins execution.
End Use of I-Status Programs: The purpose of MUMPS application
programming is to develop a set of programs useful to the ultimate
user (e.g., the nurse, clerk, etc.) These users must be given
entry to the system through passwords used during logtin. These
passwords are usually names of programs filed in the I—status.
A practical application program structure always contains a set
of programs and subroutines calling and overlaying each other.
The bulk of these routines should remain in D—status to preclude
inadvertent sign—in to a subroutine or a piece of the overall
package in the wrong sequence.
It is possible that all users may sign in for the same root
program,or sub—executive, which routes the user to appr0priate
D-status pieces of the package. Thus, the only program in the
system to be filed in I—status might be that root progranL
Hence the guideline; the only program(s) that mpg; be filed in
I—status are autoload programs and those which must be known by
name by the ultimate users during log-in. If such programs are
not I-status, the error message "NOT FOUND“ will be given in
reSponse to log—in.
7.2.7 Summary of Program Protection Rules
l. The status of a program (i.e. Independent or Developmental)
only has meaning at log—in time. In particular, the program
status determines the action in case of error or BREAK key
operation. If the log—in command string does 39; include
the asterisk, the program must be filed in I-status or execu—
tion will not begin. If there is an error or the BREAK key
is pressed, %E will be interpreted according to Table 4-l.
If log—in does include the asterisk, the program may be
filed in either I or D status. If there is an error or the
BREAK key is pressed, %E will be ignored and control will
revert to the user in direct mode.
2. Assume a user has logged in for development. As he composes
his program he may invoke any program he knows by name, using
CALL and OVERLAY commands, and they will execute. However,
he will not be allowed inspection privileges unless he also
cited the program's key. (Program protection keys only have
to do with inspection privileges, not execution.)
3. The purpose of operational and tied terminals is to absolutely
preclude development from those terminals.
4. The purpose of closed terminals is to absolutely preclude any
log—in procedure.
7.3 PROTECTION OF GLOBALS
A global may be key-protected to prevent unauthorized examination and/or
alteration of global data. A global has two keys in order that author—
ization can be given to examine data without implying authorization to
7—14
change it. Since a global must be open in order to change it, these
keys are knOWn as the READ KEY and the OPEN KEY. Since altering a
global implies reading (or examining) it, the OPEN key is sufficient
for any legal operation on the global. Both keys are set by the MUMPS
Utility Package (MUPAK).
7.3.1 OPEN Key
A key protected global may be opened either by loading the key into
the system variable %K, or by using the key within the syntax of the
OPEN command. For example, to open global ABC which has an OPEN key
of 1.27, either of the following will suffice:
S %K=l.27 O +ABC
or
O +ABC[l.27]
The second form is necessary when it is required to open more than
one key-protected global in a single statement; for example:
0 +ABC[1.27], +BCA[7.21]
Once a global is open, no key need be cited to perform any legal opera—
tion on that global.
If the global has an OPEN key value of S, no key need be cited in order
to open the global (the global is considered to be unprotected).
7.3.2 READ Key
The READ key is used to enable examination of a global by a user who
is not authorized to alter it (does not have the OPEN key). For
example, where ABC had a READ key of 99, either of the following will
suffice:
s %K=99,A= $D( +ABC(1,2))
or
s A=$D( +ABCI99](1,2))
As with the OPEN key, the second form is useful where reference is
made to more than one global; for example:
s A: +ABC[99]( +x[1](4))
or
S A: iABCI99](3),B= ¢X[1](4)
HOWever, if +ABC and +X Were OPEN in the above examples, the keys
would not be required.
Since the OPEN key implies permission to read, it may be used wherever
the READ key would otherwise be required.
APPENDIX A
EXPLANATION OF MUMPS MESSAGES
When execution of a MUMPS program is terminated by an error or a
break, the program executive outputs a short message to indicate the
reason for termination. This message is preceded by the number of
the Step being executed unless the error occurred while in Direct
mode. It is useful to categorize the types of messages which may be
printed:
l. MUMPS programming error messages
This class of message results from errors associated
with programming problems (either in the language
syntax or semantic misunderstandings).
2. Operating System error messages
This class results from various troubles which are
detected by the operating system and which are beyond
the control of the MUMPS application programmer.
3. Voluntary program termination message
There is only one message of this type, and it is
?IOINT
indicating the Break key has been activated for a
voluntary termination of execution.
4. Debugging Aid message
The ?BREAK message is an indication that a BREAK
command has been encountered in the program.
All errors are considered terminal. After encountering any error,
it is not possible to resume execution of the program from the point
of error.
However, the BREAK decoding aid is associated with a G0 command which
permits execution to resume at the step following the BREAK.
Each of the MUMPS messages is explained below.
MUMPS PROGRAMMING ERROR MESSAGES
Message Explanation
CLOSE An attempt has been made to store into an unopened
Global.
CMMND Indicates illegal use of a command. This includes
using a command that normally takes an argument and
omitting the argument, as well as using a command that
has not been defined in the language.
DISK! Hardware error encountered during disk transfer.
FRACT
FUNCT
GLOBE
IOLOK
MAXIM
MINIM
MINUS
MIXED
STEPS
STORE
SYMBO
SYNTX
Indicates that a fractional number was encountered
when the process being executed was expecting an
integer number. Also invoked when a step number has
no fractional part.
Indicates illegal use of a function. Includes the
use of an undefined function as well as an illegal
use of an argument for a legal function.
Improper Global access.
A reference has been made to a device that is not
"owned” by this partition.
An attempt has been made to perform an operation
without citing the required key.
Indicates that the value of a number has exceeded
the positive bounds set by the MUMPS system. The
maximum value for a number is +l3lO.7l. Also uSed
to indicate that a string has exceeded 73 characters.
Indicates that a number has too many digits follow-
ing the decimal point.
Indicates that a negative or zero number was en-
countered when a positive number was expected.
For example, MUMPS will cause a MINUS error if
the user tries to call a subscripted variable with
a negative subscript. Only positive subscripts are
allowed.
Indicates that the user has mixed string and numeric
arguments in the same expression. For example, if
the variable NAME contains the text "JOHN DOE" and
the variable NUM is equal to the numeric value 3,
the expression NAME+NUM would cause a MIXED error.
Indicates that the available stack space is used up.
Generally indicates nesting is too deep in D0, FOR,
or CALL statements, or that a GOTO is executed
while in the range of a FOR clause.
Indicates that user has tried to reference steps
that are not defined in the program buffer. Also
invoked when an attempt has been made to modify
the step currently being executed.
The amount of free space in the user's partition
is too small to allow increased allocation of
space to the symbol table or step buffer. The
variable $STORAGE contains the amount of free
Space, in terms of characters, left in the partition
buffer. For example, $STORAGE equal to 0.72 indicates
that there are seventy-two characters of free space
left.
Indicates misuse of a symbol (e.g., a non—subscripted
reference to an array).
Indicates that the current step being executed has
an error in syntax. Syntax errors include illegal
punctuation, illegal use of operators, illegal use
of parentheses, as well as errors encountered in
editing a step. Syntax errors comprise a great
majority of errors made in the MUMPS system and usually
the user will be able to determine the exact cause of
the error by merely looking at the step concerned.
A-2
TRAP
UNDEF
Message
?IOINT
Message
BLOCK
CHPNT
IODSK
IODT
IOERR
IOPTP
IOPTR
Message
? N BREAK
Your terminal has been disabled.
Indicates that the program has tried to reference
a variable that is currently undefined.
VOLUNTARY PROGRAM TERMINATION MESSAGE
Explanation
signifies an attempt to interrupt execution by press—
ing the break key.
OPERATING SYSTEM ERROR MESSAGES
Explanation
Unspecified error.
The free list is too low to allow setting globals or
filing programs. Call the computer operator.
Bad data on the disk; call the computer operator.
Disk error.
DECtape error.
Line Printer or Card Reader error.
Paper Tape Punch error.
Paper Tape Reader error.
DEBUGGING AID MESSAGE
Explanation
Indicates that program control has reached a BREAK
command at step N. BREAK commands are used to interrupt
execution of the program to allow the user to more
easily debug his program. '
ERRORS DURING CALL AND OVERLAY
If errors are detected in a program other than the program name (and
user name) specified at log-in, because a call or overlay is in
effect, the error message is expanded.
Example:
Suppose user JOE logs in for his program AXE, and an error occurs in
JOE:AXE. The printout is:
?ERROR 2:10 (Error detected during Step 2.10)
Now suppose JOE:AXE had been error free, but called JOEzBAD which
contained an error. The printout is:
?ERROR :BAD 3.20
indicating that JOE:BAD step 3.20 caused the error (the "JOE" is
suppressed since it is assumed the user remembers what user code he
entered at log—in.
Furthermore, suppose program JOE:AXE calls a general system program
filed under user code SYS and named GEN, and that an error occurs while
it is executing. The printout is:
?ERROR SYS:GEN 4.40
INDEX
%A (%ADDRESS), 4—4 $CHARACTER string function, 5-9
A pattern verification code, 3—7 Characters
Abbreviation format, 1—8
of commands, 2—12 null, 3—5
of function name, 3-9, 5-l string, 3—l
Access to core location, 5—8 Clauses
Access to programs, I—2, 7-3 combined in one string, 2—7
Addition (+1, l-l FOR, 1-7, 2-2, 2—3
ALT MODE see ENTER key format, 4—9
Ampersand ( & ) usage, 2—6 terminator, 4—9
Analyzer, syntax, 3—8 UNTIL, 4—9
AND ( & ) sign usage, 2—6 WHILE, 4—9
Angle bracket, right see Caret CLOSE command, 6'2, 6—5
Apostrophe sign ( ' J usage, 2—6, Closed terminals, 7-3
3—5, 3—6, 3—8 Codes for pattern verification, 3—6
Arrays, 6-l Codes, log—in, 7-5
Arrays, storage of global, 6—3 Collating sequence, 3—5
Arithmetic comparison operators, 2—5 Colon (:i usage, 3‘6, 3‘8
Arithmetic operators, l-l Combining clauses in one string,2—7
precedence, 1—3 Comma (,) usage, 1—4, 1’8
Arithmetic negation, 1’3 in Boolean numeric function,5—5
ASK command, 2—9, 2-10 in expressions, 5-l
Asterisk (*) usage, 4—5, 7—14 string comparison operator, 3—4
At sign (@) nonusage, 3—l Command execution sequence, 2-12
Autoload programs, 7—l3 Commands
status, 7-2 single letter, 2—12
Special, 4—7
Commands
Backslash (\ ) nonusage, 3—1 ASK, 2‘9, 2‘10
Bell, 4—10 BREAK, 2—13, 2—14
Boolean operators, 2—6, 3-5, 3—6, CALL, 4‘1; 7‘7
3—8 CLOSE, 6—2, 6-5
$BOOLEAN numeric function, 5—4 DO, 2‘2, 2'4: 4’8: 4‘9
Brackets [ 3 string comparison ENTER, 1‘1
operators, 3-4 ERASE, 2—lO, 2-13
Branching FILE, 7—8
$BOOLEAN function, 5-4 GO, 2—13, 2—14
conditional, 2-8 GOTO, 2—7, 2-8, 4—9
GOTO command, 2—7 HALT, 4-7, 4-8, 6—5
BREAK command, 2-13, 2-14 HANG; 4‘7: 4‘8
Breakpoint, loss of, 2—13 JOIN, 6‘5
KILL, 1-4, 1-5, 1—6, 2-11,
2—13, 6-4
CALL command, 4—l LOCK, 4—2 , 4-3
scratchpad mode, 7—7 OPEN, 6-2
Calls, 7-8 OVERLAY, 4—1, 7—7
Caret, right, I—3, l—l PRINT, 4—10
Carriage return without line feed, QUIT: 4‘2, 4'8
4—10 READ, 3—3
Changing program, 2—10 SET. 1’4, 2‘11, 3‘2, 6‘3, 6‘6
name, 7-12 TYPE, 1-1, 1-8, 2-ll
status, 7—11 UNLOCK, 4—3
Changing and refiling WRITE: 2‘10: 2'11: 2'13
existing programs, 7-lO XCOM, 4—10
new programs, 7—8 Comments to program, 2-13
Changing variables, 2—11 Communication with device, 4—3
Character count, $LENGTH func- Comparison Operators, 2-5, 3-4
tion, 5—2
Concatenation operator (.),
5-10
Conditional branching, 2-8
Conditional termination, 2-
Contains operator ([), 3-4,
Control transfer (GOTO), 2—
Control (CTRL) U (+U), line
deletion, 1—2
Conventions for log-in,
Core space, 4—l
Core location access, 5-8
Core storage, secondary,
Creating a program, 2—10
3-3,
8
3-6
7
7-5
4-4
D (Developmental) status, 7-11
Data
ile protection,
reference, 6-l
referencing at same level, 6—5
retrieval from global arrays,
5—6 to 5—8, 6—4
sharing by nodes,
storage, 6—2
type determination,
Debugging, 2—l3
message, A—3
Decimal places,
DECtape
output, 4—4
transports, 4-2
word capacity, 4—4
$DEFINE numeric function, 5—5,
Defining string variable, 3‘2
Definitions of terms in MUMPS
system, 7—1, 7-2, 7—3
Deletion of
character, RUBOUT (\), 1-2
line, CTRL U ( TU), 1-2
program, 7—ll
step or part, ERASE command,
variables, 2-ll
7—2,
6—2, 7-1
6-6, 6-7
$DEFINE, 6—2
1-2
6-2
2—11
variables (KILL command), l-6
Delimiter
$PIECE function, S-lO, 5—ll
space used as, 2-12
Developing, filing and using
programs, 7—3
nonexistent program key (NE), 7—3
scratchpad key (SP), 7-3
Developmental (D) status, 7—2, 7—ll
Developmental terminals, 7—3
Device communication, 4-3
Direct mode, 2—10, 7—1, 7—12
LOCK command, 4-2
Disk access time
CALL command, 4-l
OVERLAY command, 4—1
Division (/), l—l
DO command, 2—2, 2-4, 4-8
Dollar Sign ($) usage, 4-6, 4—7, 5—1
Double space usage, 2-13, 6—2
Error handling,
Error messages summary,
Errors
ESC key
Evaluation order SET command
I
Execution levels of program, 4—
Execution of program,
Execution sequence of commands,2-12
Expunging (X) or deleting
FILE command,
Filing new programs,
FollOws operator ('1 )1
FOR clause,
Format control, 1
Function names in MUMPS,
Editing contents of string, 5—ll
Editing routines, 5—10
ENTER command, l-l
ENTER key, 2—1
EOM (end of page marker),
Equals sign (=) usage, 1-4
as string comparison operator,
ERASE command, 2-10 .
2—10
4—4, 4—5
3-4
A-l
in call and overlay, A—3, A-4
in global arrays, 6-5, 6-6
logical, l—3
MAXIM, 1-2
MINUS, 5-2
MIXED, 3—2 .
STACK, 2-14
typographical, 1-1,
see ENTER key
1-2
string, 6-6
Exclamation point (1) usage
2—6
1-8
Boolean operator,
in format control,
ll usage in format statement 1—8
8
7-4
program, 7—ll
$EXTRACT string function, 5—
SFIND, numeric function, 5—4
7-8
7—8
3-5, 3—6
lw7, -3
terminators, 4—
-2, 2
IKDN
8
characters, 1—8
precedence of characters,
5—1
1—9
abbreviated names, 3—9
Functions
$DEFINE, 6—2
Functions, numeric
$BOOLEAN 5—4,
$FIND,
$HIGH,
$INTEGER,
$KORE, 5—8
$LENGTH, 5
$NEXT, 5—5
5
2
, 5—5
5-4
5-5, 6—3
5-3
$OBTAIN,
SQUERY, 5
$ROOT, 5-
$VALUE, 3
$2, 5-8
Functions,
$CHARACTER,
SEXTRACT ,
SMONEY,
SPIECE ,
$STEP ,
$TEXT,
string
5—9
5—9
5-ll
5-4,
5-11
5—ll
5-10
Global data protection,
7—15
Global array storage,
retrieval of data,
Global variables, 6-l
naked, 5-7, 6-4, 6-5
GO command, 2~l3, 2—14
GOTO command, 2—7, 2—8,
6—3
5-6 to 5-8, 6-4
4—9
HALT command, 4—7, 6-5
HANG command, 4—7
Hardware system, I—l
$HIGH numeric function, 5—6,
High—speed paper tape reader
and punch, 4—2
6-3
I (Independent) status, 7—2, 7—4
%I, device identification number,
I mode
autoload, 7—13
end use of I status programs,
log-in, 7-12
requesting program by name (load-
and-go), 7—13
tied terminals, 7—l3
using programs in, 7-12
ID number (device identification)4—3
IF statement, 2—5
IN USE condition on existing program,
7-10, 7-11
Increment, l-7
Index variable, l-7
Independent (I) program status,
7—4
Indirect mode,
LOCK command, 4—2
Indirect steps, 2—l
Inequality conditions,
Input, ASK command, 2-
Input/output devices,
principal device, 4—
Inserting a step, 2—1
7-13
7—2,
I—3, 7—1, 7—7
3-5
9
4—2
3
$INTEGER numeric function, 5—3
Interactive mode, 2—9
Interruption of program, 2—l3
JOIN command, 6—6
Key changing, in new program, 7-8
Key—protected programs, 7—9
Key, protection, 7—1, 7-3,
Key = zero, 7-10
KILL command, l—4,
6—4
$KORE numeric function,
7—8
1-5, 1-6, 2-11,
5-8
$LENGTH numeric function, 5—2
Length of Teletype line, 2-12
Levels of program execution,
Libraries, program, 4-1
Line deletion, CTRL U ( +U), l-2
Line feed without carriage return,
4—10 ,
Linear storage device, 4—4
List format of FOR clause,
Load and go programs, 7—12
status, 7—2
Local data reference,
LOCK command, 4—2
Logical errors, 1—3
Log-in, I-2
conventions,
examples, 7—6
on existing programs,
I mode, 7—12
new programs,
4-8
4-9
6-1
7—5
7—10
7—7
M pattern verification code, 3—7
6..
MAXIM error message, 1—2, 4-2, 1
Messages, explanation of, A-l
MINUS error message, 5—2
MIXED error message, 3—2
Mode
direct, 2—lO, 7-‘, 7—12
indirect, I—3, 7—l, 7—7
interactive, 2—9
scratchpad, I—2, 7—7
$MONEY string function, 5—ll
Multiplication (*), l-l
Multiple clauses, 2—7
Multiple codes in PRINT command,_ 4—10
Multiple commands on one line, 2-12
N pattern verification code, 3-7
?N (tabulate) in format control, l—8p
Naked global variables, 5—7, 6—4, 6—5
. $NEXT numeric function, 5—5
Node, 6-1, 6-3, 6—4
data sharing, 6-6, 6—7
Nonexistent program key (NE), 7—3
NOT, Boolean operator, 2—6
Null character, 3—5
Number sign (#) usage (page/form
feed), l-8, 4-4
Number valued expression (NVE), l-l,
5-l
Numbering of steps and parts,
Numbers in MUMPS, l—2
Numeric
data, 2—9
evaluation,
functions,
value, 3—2
valued expression,
2-2
5—8
5-1 through 5-6
5-1
SOBTAIN, numeric function, 5-7
Off-line storage, 4—5
OPEN command, 6—2
OPEN KEY, 7-15
Operating system error messages, A—3
Operational terminals, 7-3, 7—4
Operators
arithmetic, l-l, l—3
arithmetic comparison,
Boolean, 2—6
concatenation (.), 3-3,
OR, Boolean operator, 2—6
Output devices, see input/output
Output partial string, $PIECE
function, 5-10
Output, the TYPE command,
OI'T'E‘DT.AY 4—1
7-7
5-6,
2-5
5-7
l-l
command,
scratchpad mode,
Overlays, 7—9
P pattern verification code, 3-7
Paper tape I/O, 4-5
Parentheses ( ) usage, 1’6, 5-1
Partial string output $PIECE
function, S-lO
Parts, 2-2
Pattern verification ( : ), 3-6
codes, 3—7, 3—8
Percent sign (%) usage, l—4, 4—6
$PIECE string function, 5-4, 5—10
Pound sign (#) see Number sign
Precedence of arithmetic
operators, 1-3
Precedence in format, 1—9
PREFIX key see ENTER key
Principal input/output device. 4—3
PRINT command, 4-10
multiple codes, 4-10
Program access, I-2, 7-3
Program debugging, 2—l3
Program comments, 2-13
Program crash, 6—5
Program creating and changing, 2—10
changing and refiling, 7—8
filing, 7-8
log-in, 7—7
protection key, 7-8
referencing key-protected
programs, 7—9
using Calls and Overlays,
Program deletion, 7—ll
Program execution, 7-4
Program execution levels,
Program,filing new, 7—8
Programs in I mode, using,
Program interruption, 2-l3
Program libraries, 4-l
Program location $NEXT function,5-5
Program,modification of existing,
changing and refiling, 7—10
IN USE condition, 7—ll
log-in, 7—lO
Program name, changing,
Program protection keys,
Program protection rules,
7—14
Program retrieval,
PrOgram status
autoload, 7-2
changing, 7—ll
D — developmental,
expunging (X), 7—ll
I — independent, 7—2
load-and-go, 7-2
Protection of data, 6-2
Protection, file, 7—l
Protection of globals, 7-14
Protection keys, 7-l, 7—3,
Protection rules summary,
7-9
4—8
7—12
7-12
7-1
summary,
4-5
7-2
7-8
7-14
3—7
5-7
Q pattern verification code,
$QUERY numeric function, 5—6,
QUIT command, 4-2, 4-8
Quotation mark (") usage,
Quoted text literals, l—8,
3-2
3-3
Random number, $3 function, 5-6
Range format in FOR clause, 4—9
READ command, 3-3
READ KEY, 7—15
Reentry from subprogram, 4-1
Referencing data at same level, 6-5
Remote terminals, 4—2
Retrieval of data from global
arrays, 5—6 to 5-8, 6-4
Retrieval of program, 4-5
Right angle bracket, see Caret
Right caret see Caret
$ROOT numeric function, 5-2
RUBOUT ( \), character deletion,l—2
Scratchpad (SP) key, 7-3
Scratchpad mode, I-2, 7—7
Scratchpad operation
capabilities, 7-4
log—in, 7—4
Search function $FIND,
Secondary storage, 4—4
Semicolon usage, $BOOLEAN func-
tion, 5-5
Sequence of command execution,
SET command, string evaluation,
l—4, 2—11, 3—2, 6—3
Sharp sign (#) usage, 1—8, 4-4
Single letter commands, 2—12
Space as printing character,
Space usage in commands, 2—12
Space usage, double, 2—l3
Special commands, 4-7
Special system variables,
referenced only, 4—7
referenced or SET , 4—6
Square root function, SROOT, 5-2
STACK error, 2—14
Status of program, 7—14
Status of terminal, I—2
$STEP string function,
Steps, 2-1
step numbers, 2-
Storage, I—2, 4—l
data, 6—1, 6-2
global arrays,
off-line, 4—5
secondary, 4-4
String characters, 3—l
String comparison operators, 3—4
String concatenation (.), 3—3, 5—7
String data, 3-2, 3-3
definition, 3-l
String functions, 5—l,
String input, READ command,
String pattern, 3—6
String replacement,
function, 5-9
String value, 3-2
String valued expression (SVE),
5—ll to 5—14
String variables, 3-1
definition, 3—2
Subscripts, 1—6
Subscript value identification,
$HIGH function, 5-6, 5'3
Subtraction (—), l-l
Symbols, log-in, 7—5
Syntax analyzer, 3-8
System variables, 4-6
referenced only, 4-7
referenced or SET, 4—
5-4
2—12
3-1
4-6
5-11
1
6-3
5—9 to 5-14
3-3
$EXTRACT
R—‘l
_, ...,
6
Teletype line length, 2—12
Terminal privileges, 7—2, 7-3
closed, 7—3
developmental, 7—2
Operational, 7—3
tied, 7—3
Terminal status, I—2
Terminals, remote, 4-2
Termination, conditional, 2-8
Termination message, A—3
Terminator, 1—7
Text literals, quoted, l-8, 3-3
STEXT string function, 5—ll
Tied terminals, 7—3, 7—13
Timesharing, 402, 6—2, 7-11
Transferring control (GOTO), 2-7
Truncation, l-2
TYPE command, 1—1, 1-8, 2—11
Typographical errors, l—l, 1—2
U pattern verification code, 3-7
+U see Control U
Unary minus, 1-3
Undefined variables,
UNLOCK command, 4-3
UNTIL terminator in FOR clause,
Up arrow ( +) usage, 6—1
User partition, I—2
1—5
4-9
Variables, l-4, 2—11
defining string ,
deletion of, 1-6
index, l-7
name definition,
referenced only,
referenced or SET,
string, 3-l
SubScripted, 1-6
undefined, l—5
Value, numeric, 3-2
SVALUE numeric function,
5—3
Value, string,
3-2
$DEFINE,
4-7
4—6
4—6
3-8, 5—2,
3-2
WHILE terminator in FOR clause, 4—9
WRITE command, 2-10, 2—11
Writing a program, 2-10
X (expunging or deleting
programs), 7—ll
XCOM command, 4-10
Z pattern verification code, 3-7
$Z numeric function, 5—8
Zero key, 7—10
HOW TO OBTAIN SOFTWARE INFORMATION
Announcements for new and revised software, as well as programming notes,
software problems, and documentation corrections are published by Software
Information Service in the following newsletters.
Digital Software News for the PDP-8 8. PDP-I2
Digital Software News for the PDP—II
Digital Software News for the PDP-9/l5 Family
These newsletters contain information applicable to software available from
Digital's Program Library, Articles in Digital Software News update the
cumulative Software Performance Summary which is contained in each basic
kit of system software for new computers. To assure that the monthly Digital
Software News is sent to the appropriate software contact at your installation,
please check with the Software Specialist or Sales Engineer at your nearest
Digital office.
Questions or problems concerning Digital's Software should be reported to
the Software Specialist. in cases where no Software Specialist is available,
please send a Software Performance Report form with details of the problem to:
Software Information Service
Digital Equipment Corporation
I46 Main Street, Bldg. 3-5
Maynard, Massachusetts Ol754
These forms which are provided in the software kit should be fully filled out
and accompanied by teletype output as well as listings or tapes of the user
program to facilitate a complete investigation. An answer will be sent to the
individual and appropriate topics of general interest will be printed in the
newsletter.
Orders for new and revised software and manuals, additional Software Per-
formance Report forms, and software price lists should be directed to the
nearest Digital Field office or representative.vU.S.A. customers may order
directly from the Program Library in Maynard. When ordering, include the
code number and a brief description of the software requested.
Digital Equipment Computer Users Society (DECUS) maintains a user library
and publishes a catalog of programs as well as the DECUSCOPE magazine
for its members and non-members who request it. For further information
please write to:
DECUS
Digital Equipment Corporation
146 Main Street, Bldg. 3-5
Maynard, Massachusetts Ol754
M U M P 5
Programming Language
DEC—l5—GXZC-D
READER'S COMMENTS
Digital Equipment Corporation maintains a continuous effort to improve the quality and usefulness
of its publications. To do this effectively we need user feedback -- your critical evaluation of
this manual.
Please comment on this manuaI's completeness, accuracy. organization, usability and read-
ability.
Did you find errors in this manual? If so, specify by page.
How can this manual be improved?
Other comments?
ease st-te your position. Date:
Name: Organization:
Street: Department:
City: State: Zip or Country
——————————————— —FoIdHere--—————————-—-———-——— —
FIRST CLASS
PERMIT NO. 33
MAYNARD. MASS.
BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN THF. UNITED STATES
Eflflfllfill
Digital Equipment Corporation
Software Information Services
146 Main Street, Bldg. 3-5
Maynard, Massachusetts 0! 754
Postage will be paid by:
More information about the Simh
mailing list