Category : Miscellaneous Language Source Code
Archive   : MUMPS.ZIP
Filename : USER.DOC

MICROMUMPS



USER MANUAL





Version 5





Division of Computer Science
University of California
Davis, CA 95616





William Yaksick
Richard F. Walters



December, 1986
























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.

$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. 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 interrupt execution. 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 next
Ctl-G is transmitted directly to output port, and informa-
tion 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 specify completely 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) types the value of the variable var

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

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.

An OPEN command specifying one of the disk files requires the
syntax (DRIVE:FILENAME). Failure to specify parameters will gen-
erate an error. These two parameters may be string variables or
quoted constants. For example,

OPEN 3:(``A'':``TEST.ASM'')

will assign to device number 3 the ASCII file TEST.ASM. 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=``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 the file), and 1 (purge the file and close it). For exam-
ple,

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.

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. An alternate syntax,

USE 2:n

addresses the m-th byte of the n-th sector. READ and WRITE ac-
tions are permitted in this mode, but extreme care is required
not to overflow the existing file structure. In general, this
option is intended only for the advanced programmer who is al-
ready familiar with MSDOS or CP/M. Potential hazards of its
misuse include a) unknown errors when the user attempts to write
past the end of a random file and b) disruption of the address-
ing when a sector is overflowed.

11. SET $X and SET $Y

Frequently, it is desirable, in screen formatting-dependent rou-
tines, to redefine the $X and $Y special variables to conform to
new locations of the cursor after terminal-specific write se-
quences 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, M-11, 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 argu-
ments 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 single 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.

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.
$ZCOUNT returns the number of free blocks available in
GLOBALS.DAT. It can be used in program mode to avert any
problems of overflowing allocated global area.

ZD(ELETE) 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 called NAME

ZD(ELETE) (name:n) where the parameter `n' may either
be M (or m), denoting a MUMPS routine, or Z (or z) to denote
an assembly routine.

ZDELETE may also take the following variations:

ZD(ELETE) "lower" deletes a MUMPS routine with the
name lower (in lower case letters). ZD(ELETE)
("lower":"M") same as the previous example ZD(ELETE)
("ASMB":"z") deletes the assembly routine ASMB



ZE(RROR) When an error is encountered and the ZERROR
has been set, the error message giving the location of the
error is displayed (pointer to command, label plus offset).
If ZERROR has arguments, control will pass to the
entryref^routine in the argument.

ZF(ETCH) is used to fetch an operating system file and place it
in the current library file. Two forms are available:

ZF(ETCH) assumes that the file pointed to by
is an MSDOS file with the extension type .MMP.

ZF(ETCH) , where `n' may take the value M (or m)
to refer to MUMPS routines, and Z (or z) to refer to assem-
bly routines. In either case, the file is loaded into the
routine library file.

The parameter may include wildcard characters.
When in command (direct) mode, the ZFETCH command will re-
port 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 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.

ZI(NSERT) : inserts the string BEFORE the
specified line. Moves the line pointer just past the newly
inserted line. The format of the may be one of the
following:

``label (space) command line'' ``(space)
command line'' VAR, where var is a previously de-
fined string conforming to one of the two options
listed above.

Note that the quotation marks are required if the string is
entered directly.

ZL(OAD) 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.

ZM(OVE) (without arguments) moves pointer to top of routine

ZM (+n) moves pointer to label and advances +n lines

ZM : moves to end of routine

$ZMATH (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: the
current routine drive name; the global drive name; and the
pathname used to specify the subdirectory under which the
Routine Library is filed. The special variable $ZPATH re-
tains the value of the pathname to the Routine Library file.

Other forms of ZOPTION are:

ZO "A" sets the Routine drive to A, ($ZROUTINE set to A).
Note that the quotation marks are required.

ZO ("A":"B") sets the Routine drive to A, the Global
drive to B. $ZROUTINE is set to A, $ZGLOBAL is set to B.

ZO ("":"":"C:\SUB1\LIB.DAT") leaves $ZR and $ZG un-
changed, but sets the name of the ROutine Library to LIB.DAT
and sets the pathway to that file as \SUB1.

ZO ($ZR:$ZG) dump buffers. This option may be invoked when the
user wishes to make sure that the disk is updated with the
latest changes to 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)

ZP(RINT) (without arguments) prints entire routine in workspace
(P may be used instead of ZP, as in DSM)

ZP * prints current line
ZP prints the line specified by , optionally
offset by (n) lines
ZP :label2(+n2)> prints all lines between and includ-
ing the lines referenced by label1 and label2 as modified by
n1 and n2
ZP lists all lines from the referenced label to the
end of 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
listing. Typing a Control-C while halted terminates print-
ing and returns to direct mode.

$ZP(ath) returns the pathname used to access the Routine Library
currently active. This pathname may be changed using ZOP-
TION.
ZR(EMOVE) (without arguments): deletes entire routines from
workspace (but not from the Routine Library).
ZR * deletes current line
ZR deletes line specified by label and offset.
ZR :label2 (+n)> deletes all lines between and in-
cluding label1 and label2 (plus offsets)
ZR deletes all lines from specified label and offset
to end of routine

ZS(AVE) (without arguments) saves the routine with the current
name assigned ($ZNAME)
ZS saves routine with name assigned. This form must be
used the first time a routine is saved. Thereafter, the name
should not be used in saving a odified routine, or an error
will result and the user must re-enter the command without a
name.

ZW(RITE) outputs a MUMPS routine to an MSDOS operating
system file with the name .MMP. Since MSDOS files are
always stored in upper case, it is not possible to store
separately two routines with the same name, one in upper
case, the other in lower case.





































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













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

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.


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.

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



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.

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


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 = 4 exit: al = 0 successful
bx = retrieved word


Notice that the entry and return registers parallel
operating system calling conventions.


SPECIAL CAUTION

A note is made here in relation to assembly routines that read or
write to disk files.

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.



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.