home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Power-Programmierung
/
CD1.mdf
/
mumps
/
percentm.doc
< prev
next >
Wrap
Text File
|
1987-07-08
|
36KB
|
1,252 lines
John Lewkowicz
New York State College of Veterinary Medicine
Cornell University
Ithaca, N.Y. 14853
Copyright 1986
Permission is hereby granted to copy and distribute this
document and the programs/data bases described herein for
any non-commercial purpose. Any use of this material for
commercial advantage without the prior written consent of
the author is prohibited.
Introduction
This utility package is a unified collection of MUMPS
programs designed to aid programmers in developing and main-
taining MUMPS programs and data bases. It provides for
creating, editing, listing, saving, restoring and killing of
both routines and globals in a single interactive package.
To invoke any of the utility functions, issue the command:
DO ^%M
while in direct mode. The first time the program is run on
any system it will automatically initialize all data bases
and ask for various default conditions.
This package was designed specifically to run on
MicroMUMPS developed at UC Davis by Dr. Walters and his
associates. It is written in standard MUMPS but makes use of
many special Z-extensions to the language provided by that
implementation. In addition, it is set up to run in a
single-user environment, since none of the scratch globals
support multiple users.
All programs and globals in the utility package begin
with the characters %M, as will any future extensions. No
data bases are needed initially since any necessary ones
(such as the terminal definition global %MTC) will be
created for you the first time the package is executed. Try
to avoid creating programs or routines starting with %M,
since they might conflict with future expansions of this
utility package.
All terminal I/O (including Console, Printer, Sequen-
tial MSDOS files, etc) is coordinated via a terminal defini-
tion program and data base to provide considerable device
independence. This package makes use of many special termi-
nal characteristics (such as High and Low intensity) if they
are available. You can use one of the initial options to
define or modify new terminals and to tie a given terminal
type to a specific I/O port. The first time this package is
run, neutral default definitions are used, but you can pick
the Terminal option to Define/Tie a new definition to your
Console or Printer. This reconfiguration will improve
interactions with the program.
A special feature available when Saving or Restoring
either Routines or Globals is that they can be transmitted
between computers by directing Input/Output of the Save file
to MicroMUMPS device number 5. The user need only establish
a hardware link via the communications port and %M will han-
dle all the rest.
2
MicroMUMPS Utilities Cornell University
%M also supports multiple volume global saves which
permit saving large data bases on multiple floppy disk
volumes. Routine saves are still output to single volumes
since it is assumed the programmer can subdivide routines to
distribute them on more than one floppy disk.
Standard Conventions
There are a number of keyboard and name specification
standards that are available in this package. Some of the
conventions are always in effect (like ? and ??), whereas
others (such as ?L) are only available when logically
needed.
? and ?? can be used to answer any question in the package
to get additional HELP on how to answer that particular
question. A single question mark (?) will get you one
line of abbreviated help. A double question mark (??)
will get you the same abbreviated HELP line together with
any extended help available.
^ always lets you back up to the previous question or
set of questions.
: and :: Whenever you see a ":", in indicates that the pro-
gram is waiting for a keyboard entry. A double colon
("::") is displayed whenever a default answer has been
supplied for you. If a default answer has been supplied,
you can accept it by pressing the <RETURN> key.
"?L" can be entered (when appropriate) to get a directory
listing (either routines or globals depending on earlier
choices). This option is available on all routine or glo-
bal name specification questions.
"?S" is similar to "?L" except that it lists only the
selected routine or global names (more on selection
later).
Routine/Global Name entry - when selecting routine or
global names (i.e., to flag them for listing, saving,
restoring, etc), you can either enter specific names (one
at a time) or use the ``wild card'' characters ``*'' and
``?''. The ? character in a name represents any single
character, whereas the * character represents any number
of characters. For example:
``A*B" selects all names starting with ``A'' and ending
with the character ``B'' regardless of name length.
``A?B'' selects all three-character names starting with
``A'' and ending with ``B.''
3
MicroMUMPS Utilities Cornell University
Combinations of the above are allowed, but avoid the spe-
cial cases of ?, ??, ?L and ?S as they conflict with
other conventions already discussed.
The ' (not) character is used to de-select one or more
names from the list already specified. For example,
A* selects all names starting with ``A''
A1* subsequently de-selects all names within that
subset that start with the characters A1.
Global Reference - when working on globals, often you are
given the option to specify an individual global or part
of a global. This option is used instead of the name
question to permit you to pick individual nodes or
branches of a global (e.g., to list or edit part of a
global) rather than groups of global names (e.g., when
saving or restoring globals). When entering a Global
Specification, the following rules apply:
NAME ONLY (^XYZ) implies that you want to process the entire
global
FULL Reference (^XYZ(1,"ABC",2)) implies that you want to
work on that node only.
PARTIAL REFERENCE (^XYZ(1, or ^XYZ(1 ) implies that you
want to work on that node and all of its descendants.
4
MicroMUMPS Utilities Cornell University
Functional Descriptions - Routines
Directory
A directory of all routines is maintained in ^%MU.
This directory is updated when editing, restoring or killing
routines. If you choose the option to refresh the directory,
a temporary MSDOS file SCRATCH.DAT is created and killed in
the process of creating the new directory. You may specify
the Drive and output device for the directory.
Edit
An option used to create and edit routines. The rou-
tine to be edited is loaded into a scratch global ^%MRE and
all edit operations are performed on that global. The rou-
tine on disk is NOT updated until you give the editor the
File command. When specifying a name to be edited, you
can enter an asterisk (*) to indicate that you wish to use
the routine currently in ^%MRE, thereby saving load time.
The editor also allows you to enter COMMENTS associ-
ated with labels in a routine. These comments are held in %M
and do NOT take up partition space when the program is
executed. They can be printed with the program when using
the List option. They can also be Saved and Restored along
with the routines.
To Enter/Edit comments for a given label in the rou-
tine being edited, simply enter a semicolon and the Label
name when the editor is looking for a command (eg, you could
enter ':LABEL' to Enter/Edit comments for the label LABEL).
List
This option allows you to list routines (optionally
with their comments) on the device of your choice. NOTE that
you will want to use the terminal definition option to esta-
blish the parameters of your devices (printer, etc.). If
output is to the console or any CRT device, the program will
pause with a keyboard read at the end of each page.
Find
This command allows you to search for one or more
strings (or patterns) in a specified set of selected routines.
You specify where the search results are to be directed. (If
a CRT, the program pauses at the end of each page).
Change
Change allows you to change one or more strings in a
specified set of routines to new strings. Output trace of
the changes can be directed to the device of your choice.
(But no pauses at the end of each screen for CRT's.) You
can set the TO string to a null (<return> only) to delete
the target (FROM) string.
5
MicroMUMPS Utilities Cornell University
Save
Save allows you to save a specified set of routines
(with an option to include the comments) to a specified
output device - an MSDOS sequential file (devices 2,3, or 4
in MicroMUMPS). You will be asked for a Drive and File name
for the output file.
Note: You can specify device 5 to direct the save
operation to the external communication port. This option
can be used in conjunction with a RESTORE operation on
another computer (also using device 5) to effect computer-
to-computer transfers of routines and globals. However, use
of inter-computer transfers requires that the communication
ports are properly set up prior to initiating this process.
Failure to do so will probably hang the system and require
rebooting with consequent loss of workspace files.
Restore
Restore allows you to restore routines, and, option-
ally, comments that were Saved with the Save option. You
specify the name(s) that are to be restored and whether or
not you want the comments associated with those routines to
be restored also. For UCD MicroMUMPS version 5.0 and later,
this function will restore the routines to ASCII files with
the .MMP extention. You will still need to ZFETCH them
into the routines library file.
Note: You can restore from device 5 to read information
being transmitted from another computer (see Save option above).
Kill
Kill allows you to remove a specified set of routines.
It also kills the routines entry in the directory (^%MU) and
any comments that are associated with this routine (^%M).
Xtended Directory
This function acts in a manner similar to the DIREC-
TORY command but also lists the first line of each routine
and the second line if it is a comment line. It is a very
useful convention to have the first line of each routine
contain (as a comment) the author's name and optionally the
last date modified, and the 2nd line of each routine be a
comment line that briefly describes the function of the rou-
tine. As an example, the following two lines could be the
first two lines of the routine %M:
%M ;John Lewkowicz - NYS College of Veterinary Medicine
;Programmer Utilities - Main Entry Point and Dispatch
The X function would then list both of these lines when dis-
playing the directory.
6
MicroMUMPS Utilities Cornell University
Functional Description - Globals
Directory
Directory gives you a directory of all globals. This
directory is maintained in ^%MU, similar to the routine
directory. Since it is much easier to create and delete glo-
bals and harder (if not impossible) to track these changes,
it is recommended that you refresh the directory before you
list it. When refreshing, the temporary scratch file
SCRATCH.DAT is created and deleted. You will also get to
specify the Drive and output device for the directory.
Edit
Edit lets you edit a global reference (entire global,
specific node, or specific branch). It loops through your
reference, displaying each node and getting your changes.
After each node you can specify whether to do the node
Again, go on to the Next node or Stop editing this refer-
ence.
List
List lets you list a global reference (all or part of
the global) to a specified device. If that device is a CRT
(as defined by the Terminal definition option), the program
will pause at the end of each screen.
Find
Find allows you to search for one or more strings (or
patterns) for a given global reference. Output of search
results is sent to the device of your choice, with CRT's
pausing at the end of each screen.
Change
Change allows you to change one or more strings (FROM)
to new strings (TO) for a global reference (all or part of a
global). A trace of the changes is output to the device of
your choice. There are NO pauses at the end of a screen on
CRT's. The TO string can be a null ("") to DELETE the FROM
string.
Save
Save allows you to output one or more globals to a
specified output device. Usually output is to one of the
sequential MSDOS files (devices 2,3, or 4 in MicroMUMPS),
and you will be asked to enter the drive and file name
specification for the output file.
When doing a global Save, you can specify the maximum number
7
MicroMUMPS Utilities Cornell University
of bytes to output to the output file. If you make use of
this feature, you can create multiple output files (volumes)
to save large data bases on floppy disks. For example, to
save 1MBYTE worth of data on 5 1/4" double-sided, double
density disks with 360K bytes on each disk, you could indi-
cate that the maximum bytes to output is 360K (in response
to the question asked just before the ``Ready to Start''
question). The utility would then start a global Save and
continue through the first 360K bytes. At that time, the
output file is closed and you will be advised to remove the
disk, insert a new one, and define where the continued out-
put is to go. Naming each of the continuation files is your
responsibility. Each of the resulting save files is complete
and standalone (including a definition of Date/Time lines)
and can be individually restored when using the RESTORE
option.
Restore
Restore allows you to retrieve one or more specified
global names from a file created with the Save option.
Kill
Kill allows you to remove a specified set of global
names. Deleted globals are also removed from the directory
in ^%MU.
Xtended Directory
This command will provide you with a global directory
on a specified output device and will list along with each
entry the contents of the top data node if it is defined.
Thus, you can comment the data base by defining a string at
the name level, for example:
^%MTC="Terminal Definition and Port Assignments"
8
MicroMUMPS Utilities Cornell University
Terminal Characteristics
This utility allows you to define the characteristics
of specific terminals and to tie those terminals logically
to UCD MicroMUMPS port assignments. using these definitions
in programs (for example this utility package %M) allows the
programmer a certain device independence difficult to
achieve when device-specific codes are used in programs.
Most of the terminal specific values that might be of use to
a programmer are maintained by this utility and can be set
up once at the beginning of a package initialization. These
parameters include:
Right Margin - The number of characters that will fit on one
line. Use of this parameter allows the programmer to
ensure that data fits on a line, to center data, etc. As
an example, to center a string of data on a line, the
following code could be used (assuming string to be cen-
tered is in variable `X' and variable RM contains the
value for the right margin):
W !,?RM2-$L(X)2),X,!
Screen Length - The number of lines that will fit on a
screen or page. This parameter permits the programmer to
pause at the end of a screen or start a new page with
header information, etc.
Form Feed - The character sequence necessary to clear the
screen and start a new page. The MUMPS ``#'' does NOT
always perform this function depending on the terminal
and the use of SETMUMPS described in the MicroMUMPS User
Manual. If this value is initialized correctly, the pro-
grammer can always clear the screen with a
W @FF or W @IOFF
High Intensity - If a terminal supports multiple intensities
(or multiple colors), it is possible to switch to the
High intensity (or a designated color) by writing out the
character sequence of this variable with a
W @LH or W @IOLH
Low Intensity - String of characters that will switch termi-
nals that support dual intensity back to LOW intensity
(or a specified color) by writing the command
W @HL or W @IOHL
In all cases where outputting these strings or executing
strings of code, the codes are set up so that terminals
9
MicroMUMPS Utilities Cornell University
that do not support a feature will not be affected
adversely. For example, a terminal that doesn't support
dual intensity would have a high intensity and low inten-
sity string of ``*0'', which would result in a W *0 to
the device, a command that would not affect the terminal.
Cursor Positioning - On terminals that support cursor posi-
tioning, you can Xecute an indirect MUMPS command after
setting the desired X and Y positions as follows:
S DX=10,DY=20 X XY... -or- S DX=10,DY=20 X IOXY
Terminal Type - The variable SUB (or IOST) contains a string
that defines the terminal type. The first character
defines the general type (C=CRT, P=printer, O=Other), and
the rest of the string is free text defining the specific
type (e.g., DEC LA120).
The following entry points are available to the programmer
for general access to these terminal values:
CURRENT^%MTC will open the device specified in $IO and
return the following parameters
FF - Form Feed character sequence
HL - High to Low Intensity switch character sequence
LH - Low to High Intensity switch character sequence
RM - Right Margin
SL - Screen Length
XY - Cursor positioning command
SUB - Terminal Subtype
In addition to opening the device if necessary, an
optional startup string will be sent to the device (this
function can be used to set up initial default terminal
conditions such as high intensity, printer pitch, etc.).
^%MTC will let the user pick which of the MUMPS I/O ports
they wish to direct output To/From. On return, the device
has been opened, an optional initialization string has
been output to the device, and the following variables
are available for use by the program:
IO - Device Number selected (numeric)
0 - Console
1 - Printer port
2 - Sequential MSDOS file
3 - Sequential MSDOS file
4 - Sequential MSDOS file
5 - AUX port for external communication
IOFF - Character sequence to clear screen/start new page
IOHL - Character sequence to go to low intensity
IOLH - Character sequence to go to hight intensity
10
MicroMUMPS Utilities Cornell University
IORM - Right Margin (characters/line -1)
IOSL - Screen/Page length (lines -1)
IOST - Terminal Subtype (see SUB above)
IOXY - MUMPS command string Xecuted to position cursor
If the device selected is an MSDOS sequential file, then
the default setup code for those devices (2-4) will be
Xecuted and the program will ask the user for a file
specification (Drive and File Name) and then open that
file.
11
MicroMUMPS Utilities Cornell University
Defining a Terminal
This option is used to define a new terminal type or to
modify the definition of an existing terminal (such as
startup strings, right margin, etc). The parameters main-
tained by this utility reside in ^%MTC. This global does not
need to exist when you first run the %M utility package,
since it will be initialized by ^%M8 to include a number of
standard CRTs and Printers as well as the MSDOS sequential
files. If the terminals on your system are in the file after
this initialization, you can use the ``Defining MUMPS
Ports'' option to attach a specified terminal type to a
specific I/O port.
This utility option allows you to define terminal-
specific characteristics. Enter a ``?'' or ``??'' if you
need help on a specific question. After entering the termi-
nal specification, there will be NO apparent change on the
terminal, since you have not yet assigned these parameters
to a Port number.
Example (ADM3A CRT) (user responses in bold face)
Terminal Name: ADM3A name of terminal
Description: C-Lear-Siegler ADM3A
Form Feed Character(s): *26,# (# resets MUMPS $X,$Y)
Hi->LO characters: *27,*41 (use *0 if not available)
LO->HI character(s): *27,*40 (use *0 if not available)
Right Margin: 79 (characters per line - 1)
Screen Length: 23 (Lines per page - 1)
Cursor Positioning: W *24,"=",*DY+32,*DX+32 (move to DX,DY)
Startup Code: O %IO U %IO W *27,*40 (start at high intensity)
12
MicroMUMPS Utilities Cornell University
Defining a MUMPS Port
This function allows you to assign one of the defined
terminal types and its parameters to one of the numeric
MicroMUMPS ports (0-4). The ports are defined as:
0 - Console (input/output)
1 - Printer (output only)
2 - MSDOS sequential file (input-output)
3 - MSDOS sequential file (input-output)
4 - MSDOS sequential file (input-output)
5 - AUX port (COM1 or COM2)
After you have tied a terminal to a port, the program
will issue a
D CURRENT^%MTC
and set up the correct parameters for the appropriate port.
Utility Data Bases (Globals used by %M package)
^%M - Holds user-generated comments associated with specific
labels for specific routines. Entered/Edited when editing
Routines.
^%MD - Defines the default Routine library and Global drives
to be used when running the %M utility functions. Ini-
tialized first time through routine %M8. %M8 can be
invoked directly (D ^%M8) to change these defaults.
^%MRE - Temporary scratch file into which routine lines are
written when editing a routine. All of the actual editing
of these lines is done on data in this global.
^%MTC - Contains device descriptions and current assignments
of the MUMPS ports.
^%MU - Utility global that holds directories (Routine and
Global) as well as Routine and Global restore specifica-
tions.
13
MicroMUMPS Utilities Cornell University
^%M Global Structure
Description
This global contains free text comments associated with
a given routine and label. The data is entered/edited when
editing routines. It is used when listing routines and can
be saved and restored with the routines at the user's
option.
Structure
|-----|
| %M |
|-----|
/\
/ \ (ROUTINE)
/
|---|
|---|
/\
/ \ (LABEL)
/
-------------------
| | | | | | |
|(0) |(n)
|---------| |------|
|last line| | Data |
| used | |------|
|---------|
ROUTINE is a Routine Name
LABEL is a Routine line label
last line used is an integer pointing to the last data node (n)
Data contains free text comments
^%MD Global Structure
Description
This global contains the Default Routine and Global
drives used by the Utility package %M.
Structure
^%MD=RG
R is the default Routine drive (A-P)
G is the default Global Drive (A-P)
14
MicroMUMPS Utilities Cornell University
^%MRE Global Structure
Description
This global holds the routine currently being edited.
The editor is line-oriented, and the line number is the sub-
script into this global.
Structure
|------|
| %M |
|------|
/\
/ \ (ROUTINE)
/
|---|
|---|
/\
/ \ (LABEL)
/
-------------------
| | | | | | |
|(0) |(n)
|---------| |-----|
|last line| | Data|
| used | |-----|
|---------|
ROUTINE is a Routine Name
LABEL is a Routine line label
last line used is an integer pointing to the last data node (n)
Data contains free text comments
15
MicroMUMPS Utilities Cornell University
^%MTC Global Structure
Description
This global contains terminal definitions and the
current MUMPS port assignments. It is initialized by routine
%M8 and updated by routine %MTC (at labels DEFINE and
DEFAULT).
Structure
|---------|
| ^%MTC |
|---------|
/\
/ \
/(n) \ (TERMINAL)
/ \
|---------| |------|
| Terminal| | Desc |
|---------| |------|
n is an integer MUMPS port number (0-5)
Terminal is a terminal name like ADM3A
Desc is a description of the terminal in the following format:
Desc = ``FF~HL~LH~RM~SL~XY~TD~SC'' where:
FF - Form Feed sequence
HL - Low intensity sequence
LH - High intensity sequence
RM - Right Margin
SL - Screen Length
XY - Cursor Positioning code
TD - Terminal description (such as C-ADM3A)
SC - Startup code to be eXecuted when Opening device
16
MicroMUMPS Utilities Cornell University
^%MU Global Structure
Description
A utility global for use by the %M utility package. It
holds directories (both Routine and Global) as well as Rou-
tine and Global restore specifications.
Structure
|--------|
| ^%MU |
|--------|
/\
/ \
/ \
------- ---------------
| |
(``ROU'' or ``GBL'') (``RESR'' or ``RESG'')
| |
|---| |---|
|---| |---|
/\ /\
/ \ (NAME) / \ (n)
/ \ / \
|-----------| |----------------|
|SELECTED | |SPECIFICATION |
|-----------| |----------------|
NAME is a Routine or Global Name (depending on whether the
subscript is ``ROU'' or ``GBL'').
SELECTED os a True/False indication (1/0) as to whether the
name has been selected or not.
SPECIFICATION is a restore specification (either Routine or
Global depending on whether the previous subscript is
``RESR'' or ``RESG'' in the following format:
NAME:IF
where Name is the actual user entry (such as X?Z*) and IF
is the indirect pattern match that will be used to test a
target name (such as 1"A"1E1"B".E).
17
MicroMUMPS Utilities Cornell University
Save-Restore File Structure
The Save/Restore routines and globals are written out
as sequential files to the designated devices. The first
line is always a free text description of the file and the
second line is a free text data and time. Both lines could
be nulls.
------------------------------------------------------------
GLOBAL ROUTINE
``Description'' ``Description''
``Date and Time'' ``Date and Time''
Global Reference Routine name
data element routine line
Global reference routine line
data element routine line
. .
. .
. .
(Blank global reference (Blank routine line is used
indicates file done) to indicate end of routine)
Routine name
routine line
routine line
.
.
.
(blank routine name indicates
end of file)
You can use %M to save and restore both routines and
globals between computers without the creation of a tem-
porary file (using device #5 on both computers. If you want
to transmit or receive routines or globals from OTHER sys-
tems, you can use the following sections of MUMPS code to
transmit (TX) or receive (RX) a line (L) to/from the other
machine.
TX R X G TX:X'="" W L,! R X G TX:X'="" W $L(L),! R X G TX:X'=""
Q
RX R !,A:10 E W "*-ERROR-*",! G RX
R1 R !,X:10 E W "*-ERROR-*",! G RX
S X=$S(X'?1N.N:0,$L(A)'=X:0,1:1) W $S(X:"",1:"*-ERROR-*"),!
G RX:'X
Q
The code above assumes that the device in-USE for the
read/writes is connected to the microcomputer via an RS-232
serial line and that echo is turned off, and that the
default line length is set at 255 characters (i.e., O
DEV:(255:1) for Intersystems MUMPS).
18
MicroMUMPS Utilities Cornell University
Utility Package Routines
%M Main entry point. Gets primary options and
dispatches control to other routines in the package as
appropriate. Also processes name specifications and
flags (selecting) entries in appropriate directories.
%M0 Processes Directory requests (including ``?L'' and
``?S''), and both Global and Routine List options.
%M1 Controls the Editing of both Routines and Globals.
The actual editing of routines is handled by the %ME...
routines, but global editing is done by %M1.
%M2 Processes Delete and Find options for Routines and
for Globals.
%M3 Processes the Change option for Routines and Globals.
%M4 Performs Save and Restore operations for both Rou-
tines and Globals.
%M5 Gets user options for Terminal and Port specifica-
tions. Dispatches control to %MTC for actual updates.
%M6 Does actual Routine/Global Save or Restore (%M4 is
used to collect options and set up for Save/Restore
operation.
%M7 Handles eXtended Directory for both Routines and
Globals.
%M8 Initializes both the default drive data base (^%MD)
and the terminal characteristic data base (^%MTC).
%M9 Displays help text for the Utility package.
%M10 A Continuation of %M9 help text).
%MEDT Routine and comment file editor.
%MEDT1 Continuation of %MEDT.
%MEDTE Extended explanations for %MEDT.
%MEDTE1 Continuation of %MEDTE.
%MTC Terminal definition routine. Entry points at
%MTC to let user select a port.
CURRENT^%MTC to get current device parameters.
%MTCD Continuation of %MTC with entry points to define
characteristics of a terminal (DEFINE) and to assign a
terminal to a MUMPS I/O port (DEFAULT).
%MTCH Used to display help text for %MTC questions.
19
