home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Power-Programmierung
/
CD1.mdf
/
mumps
/
user.doc
< prev
next >
Wrap
Text File
|
1989-03-06
|
53KB
|
1,386 lines
MICROMUMPS
USER MANUAL
Version 5
Division of Computer Science
University of California
Davis, CA 95616
William Yaksick
Richard F. Walters
December, 1986
(updated March 1989)
(version 5.2 )
(marked '***')
Introduction
A single user version of Standard MUMPS has been implemented on
8086/88 and compatible microcomputers operating under the PCDOS
(MSDOS) Operating system. This research has been supported in
part by the Veterans Administration, the MUMPS Systems Laborato-
ry, Nagoya, Japan, Shared Medical Systems, the Lister Hill Na-
tional Center for Biomedical Communications of the National Li-
brary of Medicine, IBM Corporation, Cornell University and the
University of California. It is distributed by the University of
California, Davis, and by the MUMPS Users Groups of England,
Japan and Brazil.
In its current version, MicroMUMPS includes all commands of the
ANSI Standard applicable to single user versions. This manual
describes extensions to the MUMPS language that are included in
MicroMUMPS. In general, direct I/O extensions conform to those
of DSM and ISM implementations. Some special capabilities avail-
able at the micro-computer level are also described in this manu-
al.
Initiating MicroMUMPS
To enter the MUMPS interpreter, begin by turning on the machine
and initiating the operating system. Then type ``MUMPS'', and
the interpreter will be loaded. When loaded, the interpreter
will give an initial message identifying the Version number and
then display a prompt ``>'', which is repeated each time the in-
terpreter is awaiting further input from the user. If MUMPS has
been configured for auto execute mode using the SETMUMPS utility,
then the command line entered during setup will be executed in-
stead of the initial prompt. See the SETMUMPS utility documenta-
tion for more information on auto execute mode.
To exit MUMPS, type HALT or H, and the monitor will once again
assume control of the system. ALWAYS EXIT USING THE HALT command
to allow the system to rewrite all modified global files before
returning control to the operating system. Failure to do so may
result in loss of data in the global files.
Special Features of MicroMUMPS
MicroMUMPS now includes all the features added to Standard MUMPS
for inclusion in the ANS 1984 standard. These features are:
SET $PIECE The syntax SET $PIECE(X,delim,n)=``NEW VALUE'' es-
tablishes NEW VALUE as the nth piece of variable X.
$ASCII(expr1,intexpr2) returns the $ASCII function on the
intexpr2th character of expr1
$EXTRACT(expr) returns the first character of the value of
expr.
- 1 -
$JUSTIFY now includes a leading zero in front of decimal frac-
tions between -1 and 1.
$LENGTH (exprl,expr2) gives the number of non-overlapping times
expr2 occurs in expr1.
$TEXT(+0) returns the name of the routine.
Pattern match: alternating forms permitted (see newsletter)
READ A#n reads up to n characters, terminating at n.
In addition to permitting string subscripts, decimal subscripts
are also allowed in MicroMUMPS. Note that the collating order
specified by the MUMPS Development Committee treats ``canonical
numbers'' as special cases, separating them from other numbers
and alphanumeric strings. See the section on Language Extensions
for further details on this topic.
Adherence to Portability Requirements of the MUMPS Standard
This version of Standard MUMPS adheres to or exceeds all provi-
sions specified in part III of the ANSI Standard X11.1. String
variables may be up to 255 characters in length, numeric preci-
sion is maintained to a minimum of nine significant digits, ex-
tensible to 14. Numbers up to 10 raised to the 25th power can be
represented, subscripts may be up to 63 characters, etc. Some
versions (distributed in Japan and China) permit use of the 8th
bit in character representation and permit manipulation of two-
byte characters.
Implementation-Specific Features of MicroMUMPS
ANSI X11.1 1984 reserves for the implementor a number of language
elements. This section describes briefly the manner in which
some of those features have been treated in MicroMUMPS
1. Direct entry of routine lines
MUMPS can be executed by direct commands, processed as soon as
they are typed, or by executing stored routines. Provision must
be made for the entry of command lines that can be stored as rou-
tines. In MicroMUMPS, the TAB character (control - I on some
keyboards) is used to signal the start of a command line that is
to be stored in the workspace. The Tab character echoes as a
space (a change from earlier versions). Multiple Tabs are permit-
ted for indentation purposes. Multiple spaces between commands
are also allowed.
When inserting new command lines into text, they are placed im-
mediately IN FRONT of the current text pointer which is then up-
dated to point after the inserted line. Extensions that permit
manipulation of the current text pointer are described in the
section on language extensions.
When a routine is entered from an editor, the linestart character
may be any combination of one or more tabs or spaces.
- 2 -
2. Control Character Functions
A number of special characters are interpreted by MicroMUMPS to
provide specific actions similar to those encountered in the
operating system. These characters are:
Control-A information typed to next carriage return is not
echoed.
Control-C execution interrupt. Return to direct mode. The
system can be configured to ignore Ctrl-C using the SETMUMPS
utility or BREAK 0 (see below).
Control-G talk-through mode. Everything typed until the next
Ctl-G is transmitted directly to output port, and all infor-
mation received from port is echoed to screen. This feature
can be disabled, and MicroMUMPS is delivered with the
feature inactive, since it will cause a system to hang if an
external port is not connected.
Control-H backspace and delete character.
Control-P echo to printer.
Control-S pause output. Resume by typing any char. (See
special note in introduction for PCDOS.)
Control-X remove line, erasing it from screen.
Rubout backspace and delete character.
3. BREAK and ZGO Commands
The ANSI Standard does not completely specify the BREAK command.
In this version, BREAK may be used in several ways.
BREAK 0 disables control-C interrupt
BREAK 1 enables control-C interrupt
BREAK (arg) halts execution and types out argument
BREAK (var) halts and types the value of variable
Return to execution following interruption by a BREAK command is
accomplished by the ZGO command, which picks up routine execution
at the point at which it was suspended. In addition, ZGO may be
used with Control-C, when used in indirect mode, as shown below.
ZGO (no args) returns to normal execution
ZGO 1 executes a single command then returns
to BREAK mode.
ZGO 2 completes execution of the current line and the
first command on the following line.
4. READ * and WRITE *; READ A#n
The READ * syntax of Standard MUMPS permits user definition of
the interpretation of this special command. In MicroMUMPS, the
suggestion contained in the MUMPS Programmer's Reference Manual
is followed, and READ * is used to implement a single character
READ for use in those programs where single character input is an
important requirement of certain applications. When MUMPS en-
- 3 -
counters the READ command followed by an asterisk, it returns a
single character which is the ASCII code equivalent of the char-
acter entered from the keyboard. Note that the READ * command
does not echo the character typed to the screen.
READ A#n, where n is the number of characters to be read, will
cause the READ to be terminated either when n characters have
been typed or when a carriage return is typed. This form of the
READ command is a new feature of 1984 ANS MUMPS.
5. $STORAGE
The special variables $STORAGE returns a number equivalent to the
number of unused bytes of storage remaining in the user
workspace. This value is only minimally affected by creation of
new variables (two bytes are used to store an address for each
variable). The remainder of the space is used for storing the
current active Routine.
6. VIEW Command
VIEW is implemented with a single argument that may have the
values 0 through 5. The meaning of these values is defined as
follows:
0 returns a list of local variable names and values
1 returns local variable names, subscripts and
values of local subscripted variables
2 returns a list Global Variable Names
3 returns a list of MUMPS routines in routine file
4 returns a directory of all files available to
that user on default I/O drive
5 returns a directory of *.MMP ASCII files on disk
With Version 5.2, VIEW 3 has been changed to include zcallable ***
assembly language routines (.OBJ). At the end of the list of MUMPS ***
routines, starting on a new line, the words 'assembly language' will ***
appear. The Assembly language OBJ routines will follow. ***
7. HANG and Timeout Functions
The HANG command permits a pause of specified number of seconds.
Likewise, various commands such as READ allow for a timeout in
the same units. Because of difference in processing speeds, the
exact time may vary.
8. OPEN #: (parameters)
OPEN allows assignment of different I/O and disk devices and
files. The device assignments currently available in OPEN, CLOSE
and USE are:
0 the primary input device (console/keyboard)
1 printer (listing device)
2 disk file
3 disk file
4 disk file
5 Serial Port
Open 0 is ignored, since the primary input device is automatical-
ly opened when MUMPS is invoked. If OPEN is invoked with either
1 or 5 as the device specification, parameters are ignored.
- 4 -
An OPEN command specifying one of the disk files requires the
syntax (DRIVE:PATHNAME). Failure to specify parameters will gen- ***
erate an error. These two parameters may be string variables or
quoted constants. For example,
OPEN 3:("A":"\SOURCE\TEST.ASM") ***
will assign to device number 3 the ASCII file TEST.ASM which is ***
in the subdirectory 'SOURCE' on drive A. The subdirectory ***
'SOURCE' must exsit in the drive A before initializing MUMPS. ***
Note the necessity for both quotation marks and parentheses
in this specification. If variables have been previously set,
they may also be used. For example, if X="A" and
Y="\SOURCE\TEST.ASM", then the command ***
OPEN 3:(X:Y)
is a valid syntax for this command.
MicroMUMPS also permits addition of a record at the end of an ex-
isting file. The syntax for this variation of the OPEN command
is:
OPEN 3:("A":"FILE.EXT":"END")
Thereafter, any records written to that file are added at the
end. See the description of the USE command for random
read/write of files. See also your operating systems manual for
specification of random file I/O.
9. CLOSE #: options
CLOSE refers to the same files and devices specified in OPEN and
USE, described above. The two options available are 0 (close and
lock file), and 1 (purge file and close it). For example,
CLOSE 3:0 (closes and saves the file specified as device 3)
CLOSE 2:1 (erases the file referred to as device 2)
The default value (if no number appears after the colon) is to
leave the file in the status it was in when MUMPS use of the file
started (a new file is deleted, an old file retained).
NOTE: When exiting MUMPS, it is essental to close files prior to
typing HALT, so as to avoid loss of data in existing buffers.
10. USE #
USE instructs the interface to direct I/O to the device/file
specified. USE 1 directs output to the printer, USE 2 references
read and write commands to the file specified, etc.
The USE command has several variations that can be used with dev-
ices 2, 3 and 4 to permit appending data at the end of a sequen-
tial file and accessing directly records in a random file. For a
sequential file,
USE 2:``END'' will move the file pointer to the end of
the current file and add data at that point. This option should
only be used when a pre-existing file has been opened.
- 5 -
Random files must first be declared outside MUMPS using standard
operating system procedures. Individuals who are not familiar
with these procedures should not attempt to use this feature.
When a random file exists, the syntax
USE 2:n where n is the sector number to be read,
will move the pointer to that location so that the next READ or
WRITE is of the desired sector.
11. SET $X and SET $Y
Frequently, it is desirable, in screen format-dependent routines,
to redefine the $X and $Y special variables to conform to new lo-
cations of the cursor after terminal-specific write sequences
have been executed. MicroMUMPS uses the same convention that has
been adopted by several commercial versions of Standard MUMPS.
$X and $Y may be set by the user, who must write special routines
to accomplish this function. MicroMUMPS now supports this feature.
12. WRITE (without arguments)
Several commercial MUMPS systems (DSM, ISM, etc.) use WRITE without
arguments as a way to view local variables. In order to make use
of MicroMUMPS as convenient as possible for individuals who use
these versions, we have implemented WRITE with no arguments to
perform exactly the same function as VIEW 0. The list of variables
is displayed, but subscripted values are not displayed.
MSDOS Specific Features
1. Terminal I/O
The IBM PC does not allow for single character form feed control.
Version 2.0 and subsequent releases permit escape sequence con-
trols for various screen functions. Refer to your operating sys-
tem manual to determine if these functions are available on your
system. Use WRITE *nn where nn is the decimal value of an ap-
propriate ASCII code to accomplish these functions.
2. Serial Port I/O
Input and output of data on a serial line other than the system
console is supported in this version of MicroMUMPS. The facility
is provided using standard calls for auxiliary input/output ports
devices as described in the MSDOS documentation. It is necessary
to set the speed and character length outside MUMPS. Note that
at higher baud rates it is possible to lose characters, since in-
terrupt handling and buffering is not provided in MSDOS calls.
3. Sequential File I/O
As described above, MicroMUMPS provides features that allow read-
ing and writing of sequential ASCII files. The OPEN, USE, READ
and WRITE commands operate like the SDP files provided by DSM-11.
A CNTRL/Z is returned to the MUMPS routine when an End-of-File is
detected on reads. This facility is useful for writing MUMPS
routines or globals to backup data and for interface to other
languages or word processors. These features may also be used in
conjunction with external MSDOS ports to transfer files between systems.
- 6 -
Z-Command Extensions
The ANS MUMPS Standard provides a means to extend the language to
take care of I/O and other features not fully specified in the
standard. In most cases, syntax of the MicroMUMPS Z-extensions
are similar or identical to DSM and ISM comparable commands. In
one or two instances,, minor differences exist. Users familiar
with DSM, ISM, or with earlier versions of MicroMUMPS should note
these language features carefully to avoid potential confusion or
misuse.
ZCALL is a complex function allowing users to invoke assembly
language routines from within MUMPS. This feature is
described separately at the end of the User Manual.
$ZC[OUNT] returns the number of free blocks available in the
global file. It can be used in program mode to avert any
problems of overflowing the allocated global area.
ZD[ELETE] <fname> will delete a routine file from the Routines
file. This command is different from the DSM and ISM method
of deleting disk copies of routines. ZDELETE can take
several forms.
ZD[ELETE] "<name>" will delete the MUMPS routine named <name>
which MUST be enclosed in quotes. For example:
ZD "lower" will delete a MUMPS routine named lower
ZD[ELETE] <var> will delete a MUMPS routine whose name is
the value of the variable var. For example:
SET VAR="lower" ZD VAR will delete the routine lower.
ZD[ELETE] ("<name>":"<n>") where the parameter <n> may either be
the character 'M' (or 'm'), denoting a MUMPS routine, or the
character 'Z' (or 'z'), denoting an assembly routine. As with
first example, "<name>" and/or "<n>" may be replaced by a
variable. For example:
ZD ("lower":"M") deletes the MUMPS routine lower.
ZD ("ASMB":"z") deletes the assembly routine ASMB.
ZE[RROR] When an error is encountered in a routine and $ZERROR has
been set previously, control will pass to the label^routine
in $ZERROR. The Z-command ZE can be used to force an error.
$ZERROR will be updated with:
<n> ; <label^routine> ; <char>
where <n> is the error number (as found in ERRORS.DAT)
<label^routine> is the line where the error was found
<char> is the number of the character in the line where
the error was discovered.
ZF[ETCH] is used to fetch one or more ASCII-formatted routine files
located in a DOS directory and place it in the current library
file. Care must be taken to make sure that the files are rou-
tines, since ZFETCH will load a null routine if they are not.
Several forms are available:
ZF[ETCH] <pathname> assumes that the file(s) pointed to by
<pathname> are MSDOS MUMPS files.
- 7 -
ZF[ETCH] (<pathname>:<n>), where <n> may take the value 'M'
(or 'm') to refer to MUMPS routines, and 'Z' (or 'z') to
refer to assembly routines. In either case, the file is
loaded into the current routine library file.
The parameter <pathname> MUST include the filename and three
character extension and MAY include wildcard characters (e.g.,
the '*'). It MAY also include the disk drive designation and
any DOS directory path. The parameter <pathname> may be a
character string enclosed in quotation marks, or it may be a
variable designating the file. When in command (direct) mode,
the ZFETCH command will report all fully expanded filenames as
they are loaded. For example, to load all the MUMPS routines
of the VA File Manager from a distribution disk:
ZFETCH "A:\FMGR\DI*.MMP"
will load and report the name of all MUMPS routines starting
with DI.MMP in the FMGR subdirectory of the floppy disk on
Drive A.
It is permitted to have MUMPS routines and assembler .OBJ
routines with the same name, since they are accessed in dif-
ferent ways within MUMPS (assembly routines are only invoked
via the ZCALL command).
$ZG[LOBAL] returns the drive name on which globals are currently
located. It is useful in program mode to manage files when
multiple disks are used.
$ZGPATH returns the pathname used to access the Globals currently ***
active. The path name may be changed using ZOPTION. Note ***
that there is no abbreviation for this. ***
ZI[NSERT] <string>:<label[+n]> inserts the <string> BEFORE the
specified line. Moves the line pointer just past the newly
inserted line. The format of <string> may be as follows:
" label (space) command-line"
" (space) command-line"
VAR (where VAR is a previously defined string con-
forming to one of the options listed above.)
Note that the quotation marks are required if the string is
entered directly.
ZL[OAD] <name> retrieves the named routine from the Routine Li-
brary and places it in the workspace. The line pointer is
set at the end of the routine loaded. ZLOAD does not require
quotation marks.
ZM[OVE] [arg] moves the routine line pointer to the location
specified in the optional argument. There are several forms.
ZM[OVE] (without arguments) moves pointer to top of routine
ZM <label>[+n] moves pointer to <label> and, if present,
advances +n lines, where n is an integer.
ZM : moves to end of routine.
- 8 -
$ZM[ATH](n,var) returns mathematical functions of var depending on
the value of n:
$ZM(1,var) returns the square root of var
$ZM(2,var) returns the log base e of var
$ZM(3,var) returns the value of e to the power var
$ZN[AME] returns name of current routine
ZO[PTION] (without arguments) displays three parameters: 1) the
current routine drive name; 2) the drive and pathname of the ***
global file; and 3) the pathname of the routine library file. ***
The special variable $ZR[OUTINE] retains routine drive and the
the special variable $ZG[LOBAL] retains global drive. The
special variable $ZP[ATH] retains the value of the pathname to
the routine library file. The special variable $ZGPATH retains ***
the value of the pathname to the global file. ***
ZO[PTION] (<arg1>:<arg2>:<arg3>) allows the user to change the
routine and global environment temporarily within the current
MUMPS session. Before the environment is changed, any data
in the buffers will be saved in the old environment. The
arguments are positional and refer to the routines drive,
the global drive and pathname, and the routines pathname
respectively. Each argument is optional, but all preceding
colons (':') are required to denote the position.
ZO "A" sets the routine drive to A, ($ZR[OUTINE] set to A).
Note that the quotation marks are required.
ZO ("A":"B") sets the routine drive to A, the global drive
to B. $ZR[OUTINE] is set to A, $ZG[LOBAL] is set to drive B.
$ZGPATH is set to drive B while the pathway and global file ***
name remain unchanged. ***
ZO ("A":"C:\MUMPS\USERGLOB") sets the routine drive to A, the ***
global drive to B, and the pathway and global filename to ***
C:\MUMPS\USERGLOB. ($ZR is set to A, $ZG is set to B and ***
$ZGPATH is set to C:\MUMPS\USERGLOB.) ***
ZO ("":"":"C:\SUB1\LIB.DAT") leaves $ZR, $ZG and $ZGPATH ***
unchanged, but sets the path and name of the routine library
to \SUB1\LIB.DAT ($ZPATH). Note that this also could be
written as ZO (::"C:\SUB1\LIB.DAT")
ZO ($ZR:$ZG) is a pseudo-change, in that it leaves the routines
drive and the globals drive exactly as is. It has the effect
of dumping (or saving) the buffers. This option should be
invoked whenever the user wishes to make sure that the disk
is updated with the latest changes to routines file and the
global data.
$ZO[RDER](args) returns the next full global subscript reference
after the argument specified.
Example: assume that ^A(2),^A(2,1),^A(2,3,1,1), and ^A(3)
are defined. The MUMPS command line:
SET X="^A("""")" FOR I=1:1 SET X=$ZO(@X) Q:X="" W X,!
would write: ^A(2) ^A(2,1) ^A(2,3,1,1) ^A(3)
- 9 -
ZP[RINT] prints all or part of the routine currently in the MUMPS
workspace. (P may be used instead of ZP, as in DSM and ISM.)
ZP[RINT] (without arguments) prints the entire routine
ZP[RINT] * prints the current line
ZP[RINT] <label>[+n] prints the line specified by <label>,
optionally offset by +n lines
ZP[RINT] <label1>[+n1]:<label2>[+n2] prints all lines between
and including the lines referenced by <label1> and <label2>
as modified by n1 and n2
ZP[RINT] <label>[+n]: lists all lines from the referenced
<label> to the end of the routine in the work space.
Note that ZPRINT does not affect the position of the line
pointer.
Note also that use of Control-S while in print mode halts the
listing. Typing a Control-C while halted terminates printing
and returns to direct mode.
$ZP(ATH) returns the pathname used to access the routine library
currently active. This path may be changed using ZOPTION.
ZR[EMOVE] deletes all or part of the routine that currently resides
in the MUMPS workspace. It does not effect routines residing
in the routines library.
ZR(EMOVE) (without arguments) deletes the entire routine
from the workspace (but not from the Routine Library).
ZR[EMOVE] * deletes the current line
ZR[EMOVE] <label>[+n] deletes the line specified by <label> as
optionally modified by +n.
ZR[EMOVE] <label1>[+n]:<label2>[+n] deletes all lines between
and including label1 and label2 as modified by their optional
offsets.
ZR[EMOVE <label>[+n]: deletes all lines from the specified
<label> and offset to the end of the routine.
ZS[AVE] saves the routine currently residing in the workspace to
the current routines library.
ZS[AVE] <name> saves the routine with <name> assigned. This
form must be used the first time a routine is saved. Thereafter,
it is not necessary to use the name in saving a modified routine,
unless the user wishes to change the name and save multiple copies
ZS[AVE] (without arguments) saves the routine in the workspace
with the name stored in $ZNAME. If $ZNAME is undefined, an error
message will occur.
ZW[RITE] "<name>" outputs a MUMPS routine to a MSDOS ASCII file with
the name <name>.MMP. Since MSDOS files are always stored in
upper case, it is not possible to store separately two routines
with the same name where one is in upper case and the other is
in lower case.
- 10 -
Global Files
The global file structure for MicroMUMPS is a balanced tree
structure with pointers in the B-Tree and subscripts plus data at
the bottom level. This structure is efficient for handling large
files, and it also permits variable length subscripts and vari-
able length keys.
Several cautionary remarks should be made with respect to the use
of globals. In order to increase execution speed by reducing the
number of disk seeks (a major delay on floppy disk systems), in-
memory buffers are used. The number of buffers routinely set up
in the distribution disk is six. This number can be modified to
increase global performance using the SETMUMPS utility. A disk
directory bit map is retained in memory, and updated each time
globals are added or KILLed. This bit map is an essential key to
the global files. If a system failure occurs before the bit map
directory has been written to memory, serious degradation of the
global files may occur, usually resulting in the loss of one or
more variables previously set. For this reason, it is important
to minimize the potential effect of this loss by following one or
more of the suggestions given below.
One way to update files online is to use the ZOPTION command in
either direct or indirect mode. Invoking ZOPTION with the same
parameters that are currently in effect will force update of the
disk. As noted in the ZOPTION documentation above, typing ZO
($ZR:$ZG) will also force buffers to be emptied, and will have no
other effect on the status of the system.
NOTE: It is dangerous to remove disks from the computer while
MUMPS is running. Some information stored in memory relates to
the files on a given disk, and replacing disks may result in
serious file destruction.
Backup files of transactions, or other software mechanisms to
protect against power failures may be used as in all systems.
Occasional use of the global dumper utilities (see section on
utility programs) will also provide checkpoint backup for sensi-
tive file.
To maximize data base performance, the globals file should be
created at the beginning of an empty disk. This avoids file
fragmentation and positions the file near the start of the disk's
directory.
Another way that appears to offer promise for improving perfor-
mance of MicroMUMPS is to use ``solid state disk'' options. See
current literature for techniques of designating solid disk areas
in expanded memory. Remember, however, that this version of Mi-
croMUMPS makes use of available memory for Routine buffering, so
that solid state disk usage is less important than was the case
with earlier releases.
- 11 -
UCD ZCALL MicroMUMPS
This document describes an extension to UCD MicroMUMPS that permits
executing assembly language routines while in MUMPS. It should be
useful for many activities such as screen manipulation and exter-
nal file management. ZCALL provides the mechanism to execute
user-generated assembly language routines.
The syntax is:
ZC[ALL] ^rtn[,^rtn]...
where ^rtn has the form: ^rtn_name[([parameter_list])]
| , | | , |
where parameter_list is:| |[| |]...
| expr | |,expr|
and expr may be: a global or local variable name
a literal string
a settable function (except $PIECE)
^rtn-name references an assembly routine contained in
a file with the file extension '.OBJ'.
- the ZCALL command may be post-conditionalized
- ^rtn may be post-conditionalized if no
parenthesized expression is present.
- indirection:
^rtn may be specified by indirection if no parenthesized
expression is present.
parameters may be specified by indirection if ^rtn is
not indirect.
ZCALLing an assembly routine is much like DOing a standard MUMPS
routine, except that a label reference (alternate entry point)
may not preceed the caret (^) in the command arguemnt. ZCALLed
assembly routines are dynamically buffered just as standard rou-
tines. All routines, standard MUMPS and assembly, constitute a
single set that is subject to the current `least recently used'
buffering algorithm. ZCALL executes the assembly routine
`rtn_name.OBJ'. There is no conflict if an assembly routine and
a MUMPS routine share a common primary filename. That is,
ABC.MMP and ABC.OBJ may both exist.
Example:
assume MUMPS program ABC.MMP contains the code segment
... ZC ^ABC ...
then the following MUMPS code segment is valid
... DO ^ABC ...
- 12 -
Unlike MUMPS routines that are first loaded from disk to the
MUMPS partition (thus limiting their size to the partition size),
assembly language routines are loaded directly from disk to the
routine buffer area. This eliminates any size restriction on an
assembly routine. The Zedit commands (ZLOAD, ZREMOVE, etc.) have
no effect on assembly routines. That is, ZLOAD ABC will load
ABC.MMP (if it exists) independently of the existence of ABC.OBJ.
Parameters are passed by value, i.e. after evaluation. There is
no explicit limit on the number of parameters. An implicit limit
is the 255 character MUMPS line length limit, before evaluation.
Evaluated parameters are passed to a buffer area. The length of
of this buffer is defined by the user. No limit exists on the
length of this user buffer (and therefore on the combined
evaluated length of all parameters). Notice that the parameter
syntax allows null parameters to be passed to the assembly rou-
tine.
ZC ^RTN passes no parameters
ZC ^RTN() passes (1) null parameter
ZC ^RTN(,) passes (2) null parameters
ZC ^RTN(var1,,^var2,) passes (4) parameters:
1. the value of local var1
2. a null parameter
3. the value of global ^var2
4. a null parameter
ZCALLable assembly routines may optionally take advantage of the
`call back' facility. This facility allows the assembly routine
to `call back' to MUMPS to have the following services performed.
func# function
0. set a local or global variable or settable function.
exception: $PIECE
1. fetch a global/local variable or dollar function.
exception: $PIECE
2. kill a global or local variable.
3. convert unsigned byte in AL register to ASCII string.
4. store a word variable within MUMPS.
5. get the word variable previously stored.
WRITING ASSEMBLY ROUTINES
This section explains the minimum assembly source file required
to generate a ZCALLable routine. It presents a skeleton that may
be used to construct actual routine source files with a line-by-
line explanation. A skeleton file (SKELETON.ASM) is included on
the distribution disk. Label names may be changed to suit the
user. If this is done, take care to replace any duplicate refer-
ences of the changed label name. No source line may exist
preceding line 1 that would generate byte(s) in the object file.
The form and order of the lines must be preserved.
- 13 -
1: CODE SEGMENT BYTE PUBLIC 'CODE'
2: ASSUME CS:CODE, DS:CODE, ES:CODE
3: jmp my_code ;jump to executable code
4: call_back dd 0 ;call_back vector
5: bfsiz dw offset stk_siz-$-5 ;'buf' size
6: t_len dw 0 ;total parameter length
7: p_count db 0 ;parameter count
8: buf rs 80H ;communications buffer
9: stk_siz dw 0 ;MUMPS stack free space
A: user_data dw ??
:
:
M: more_user db ??
N: my_code: ;start of user code
:
:
P: retf ;return to MUMPS
1: cseg
1: CODE SEGMENT BYTE PUBLIC 'CODE'
Line 1. The required assembler directive. Notice that the 'pub-
lic' attribute allows you to have several source files (or li-
brary routines) that will link together to generate a zcallable
module.
2: ASSUME CS:CODE, DS:CODE, ES:CODE
Line 2. CS=DS=ES constitutes the Intel `small model.' Notice the
absence of an SS register declaration.
3: jmp my_code ;jump to executable code
Line 3. must be a `JMP label' instruction where `label' must
match the label of line `N'. This jump must be the standard
length jump instruction (3 bytes) and not a short or a far jump.
4: call_back dd 0 ;call_back vector
Line 4. must appear exactly as shown. This line generates room
for a four byte far-call vector that is used to access the call
back services described below. This line must exist even if the
routine will not perform a call-back. The value is filled in by
MUMPS.
5: bfsiz dw offset stk_siz-$-5 ;'buf' size
Line 5. generates a word variable that holds the length of the
buffer generated by line 7.
6: t_len dw 0 ;total parameter length
Line 6. generates a word variable which has the meaning 'total
passed parameter length'. On entry, MUMPS fills this word with
the combined length of all passed parameters existing in the
buffer 'buf'. It does not count itself or the byte count of the
number of passed parameters.
- 14 -
7: p_count db 0 ;parameter count
Line 7. generates a byte variable. On ZCALL, MUMPS fills this
byte with the count of passed parameters.
8: buf rs 80H ;communications
buffer
Line 8. establishes the communications buffer. It is used to
accept passed parameters on entry as well as call-back communica-
tions (see below). The length of the buffer is specified by the
user and should be large enough to accept all communications
data. As MUMPS loads the buffer, it checks `bfsiz' and will not
overflow the buffer. A new MUMPS error `ASSEMBLY BUFFER OVER-
FLOW' is reported if all passed parameters cannot be loaded into
'buf' on entry.
On entry, 'buf' holds the passed parameters. The format is:
parameter
length parameter
[|---------------|--------------|]...
1 byte n bytes
Parameter length is the actual parameter length not counting the
length byte. `p_count' is the number of occurences of this data
structure.
An example using DEBUG
DB9 (display memory by bytes starting @ byte 9, i.e. t_len)
BBBB:0009 0A 00 03 03 65 66 67 00 04 65 66 67 68 . . . .
t_len: 0A 00 10 valid bytes in 'buf'
p_count: 03 3 parameters in 'buf'
buf: 03 3 byte length
65 66 67 param value 'ABC'
00 a null param
04 4 byte length
65 66 67 68 'ABCD'
9: stk_siz dw 0 ;MUMPS stack free space
Line 9. generates a word value that holds the free room on the
MUMPS stack on entry. See the section `STACK CONSIDERATIONS'
below.
A: user_data dw ??
:
M: more_user db ??
Lines A. thru M. (inclusive) constitute an optional user data
area. Consistent with the Intel ``small model'', user data is
not restricted to this area but may be interspersed throughout
the code.
N: my_code: ;start of user code
Line N. The first line of executable code. The label must be
referenced in line 2 jump instruction.
- 15 -
P: retf ;return to MUMPS
Line P. To return to MUMPS, simply execute a far return. If your
assembler does not offer a mnemonic that generates the 1-byte far
return 0CBH, the following code will provide that mnemonic:
retf macro
db 0CBH
endm
Three files are included on the distribution disk that provide an
example of writing and using ZCALLable assembly routines:
SKELETON.ASM - this file provides a starting point for writ-
ing an assembly routine. It contains the required lines dis-
cussed above. Actual user data items replace the example
lines "user_data" through "more_user". User code should start
at label "my_code".
Two files, ZCTEST.ASM and ZCTEST.OBJ, are the source code and
object code respectively for the example ZCALLable routine
"ZCTEST". Refer to the section "ASSEMBLING ROUTINES" below:
the file ZCTEST.OBJ is NOT the direct output of an 8086 assem-
bler.
ZCTEST is a ZCALLable assembly routine initially written at UCD
to debug the development of the ZCALL command and is included to
aid the assembly programmer in writing zcall routines and ex-
ercising some of the zcall functions.
An example of using ZCTEST from within MUMPS:
First set the following MUMPS variables:
SET A="A LOCAL VARIABLE",B=2,C=3,^GVN="A GLOBAL VARIABLE"
The MUMPS command ZCALL ^ZCTEST(,A,B+C,,^GVN) yields:
o the ZCTEST signon message
o a report of passed parameters:
passed parameters:
null parameter
A LOCAL VARIABLE
5
null parameter
A GLOBAL VARIABLE
note: parameters passed by value, i.e. after evaluation
note: if no parameters are passed, "none" is reported
o the ZCTEST menu:
Call-Back Options: <ESC> to quit
<0> set glvn or settable function
<1) fetch glvn or dollar function
<2> kill glvn
choice ?
A single keystoke reponse to "choice ?" will cause a request for
the appropriate variable name and/or values.
- 16 -
STACK CONSIDERATIONS
As stated above, a seperate stack segment is not allowed. Howev-
er, two options are available: Option 1: Not too surprisingly,
the user may set-up his own stack within the single code segmnet.
This is the old 8080 way of doing things. The only consideration
is that stack segment (SS) and stack pointer (SP) must be re-
stored to the entry state whenever a `call-back' is made, as well
as return to MUMPS. Option 2: The user may elect to 'share' the
MUMPS stack, but must do so with care. Since the MUMPS hardware
stack shares a memory area with the execution stack (with each
growing toward the other), no statement can be made as to the
maximum stack space that will be available. However, on entry,
the word variable user is left to test and consider if this
available room will be sufficient for the assembly routine
without overflow. MUMPS has no way of detecting an overflow
caused by the assembly routine. Further, if a 'call-back' is
made, MUMPS will need (AND USE) as much as twice the length of
all communications data (i.e. the length of a passed variable,
after evaluation). However, since MUMPS is in control on 'call-
back', any overflow will be reported. The absolute maximum free
space possible is in the order of 2010 bytes but is reduced from
this amount depending on 1. how deeply the users MUMPS routines
are nested (stacked) and 2. The combined length of all arguments
referenced in the nested routines.
REGISTER CONSIDERATIONS
The user module is paragraph aligned. On entry, the code segment
register (CS), data segment register (DS) and extra segment re-
gister (ES) are set to the base of the user module and the in-
struction pointer (IP) is zeroed such that CS:IP & DS:0 both
point to the 1st byte of the user module (The `jmp my_code' in-
struction). The stack resister SS & SP are the MUMPS stack. All
other registers should be considered uninitialized. On return
from call-back, MUMPS will restore the user's DS & ES registers:
all others not containing return data are destroyed. On return
to MUMPS (the `retf' far return), the user need not restore any
registers except for the stack pointer (SP) and stack segment
(SS) as discussed above.
CALL BACK SERVICES
To enhance the usefulness of assembly routines executing on (far)
call from MUMPS, a list of call-back services is provided.
The list, in function number order, is currently:
0. Set a global or local variable or settable function except $PIECE.
1. Fetch a MUMPS global/local variable or dollar function except $PIECE.
2. Kill a MUMPS global/local variable.
3. Convert 8-bit number to ASCII string.
4. Store a word value for later retrieval.
5. Recall a previously stored word variable.
- 17 -
The calling convention for making a call-back is as close as
possible to the calling convention used to make operating system
calls. Register CL is loaded with a call-back function number, DX
is set to the address of the calling string and a far call is
made to the call-back vector `call_back'. Returned string data is
placed in the communications buffer `buf'. Register AL contains
an error flag.
All communications are in the form: one byte containing the
string length (this byte does not count itself), followed by
an ASCII string with no terminator.
FUNCTION 0 SET LOCAL OR GLOBAL VARIABLE
SET A SETTABLE DOLLAR FUNCTION EXCEPT $PIECE
entry: cl = 0 exit: al = 0 successful
dx = name address al = 0feh invalid name
bx = value address
On entry, dx & bx point to the length byte of their respective strings.
example:
:
set_name db 15,'^ADDRESS("WJY")'
set_value db 12,'123 MAIN ST.'
:
:
mov cl, 0 ;'set' function number
lea dx, set_name
lea bx, set_value
callf call_back ;go do it
result: variable ^ADDRESS("WJY") with be set to 123 MAIN ST.
Notice that, as a consequence of communicating with strings, if the
MUMPS variable NAME has the value "WJY", the following example
produces the same results as above.
set_name db 14,'^ADDRESS(NAME)'
set_value db 12,'123 MAIN ST.'
:
:
mov cl, 0 ;'set' function number
lea dx, set_name
lea bx, set_value
callf call_back ;go do it
FUNCTION 1 FETCH LOCAL OR GLOBAL VARIABLE
FETCH A DOLLAR FUNCTION EXCEPT $PIECE
entry: cl = 0 exit: al = 0 successful
dx = name address al = 0ffh not found
al = 0feh invalid name
example:
:
fetch_name db 15,'^ADDRESS("WJY")'
:
:
mov cl, 1 ;'fetch' function number
lea dx, fetch_name
callf call_back ;go do it
result: 'buf' contains bytes 0Ch,'123 MAIN ST.'
- 18 -
FUNCTION 2 KILL LOCAL OR GLOBAL VARIABLE
entry: cl = 2 exit: al = 0 successful
dx = name address
al = 0feh invalid name
example:
:
kill_name db 8,'^ADDRESS'
:
:
mov cl, 2 ;'kill' function number
lea dx, kill_name
callf call_back ;go do it
result: Complete file ^ADDRESS deleted.
FUNCTION 3 CONVERT 8-bit UNSIGNED INTEGER TO ASCII STRING
entry: cl = 3 exit: al = 0 successful
al = unsigned interger
result: integer valued ASCII string in 'buf'
The following two functions provide a (developmental) mechanism to
allow inter-routine communications. They provide a means to pass a
word value between assembly routines. The meaning of the word is
entirely defined by the assembly programmer. Among other uses, it
could represent the base address of an extra segment of memory
obtained directly from the operating system.
FUNCTION 4 STORE A WORD
entry: cl = 4 exit: al = 0 successful
dx = word to be stored
FUNCTION 5 RECALL A WORD (previous stored by func 4)
entry: cl = 5 exit: al = 0 successful
bx = retrieved word
FUNCTION 6 READ CHARCTER FROM KEYBOARD
entry: cl = 6
result: al=char code
Notice that the entry and return registers parallel operating
system calling conventions.
SPECIAL CAUTION
Assembly routines that read or write to disk files require special
handling. Assembly routines are loaded into the MUMPS data segment
and are executed in that location. On entry to an assembly routine,
the DTA base address is set to the base of the MUMPS data segment.
It is therefore necessary to:
1. Get the DTA base address (via function 2FH) and store it.
2. Set the DTA base address to the base of the assembly routine:
Set DTA base to user CS register value via function 1AH.
3. Perform disk file operations
4. Recall stored entry DTA value and reset DTA base before exiting
to MUMPS.
- 19 -
ASSEMBLING ROUTINES
ZCALL ^rtn will execute ROUTINE_NAME.OBJ that was obtained as
follows:
- create source code file RTN.ASM with intermixed code and
data segment. That is, code, data, and extra segments sharing
the same base address. See the section ``Stack Considerations''
for more details concerning the SS register. This approach simu-
lates the Intel "small model".
- assemble the source.
- link the resulting .OBJ file. Note that requesting unini-
tialized memory is not allowed.
- rename RTN.EXE to RTN.OBJ.
*** Should you inadvertently forget to rename the .EXE file to
.OBJ, you will get the new MUMPS error `ASSEMBLY BUFFER OVERFLOW'
when you attempt to ZCALL this routine.
- 20 -
