Mumps/II /MDH Toolkit

The Mumps/II Programmer's Guide Version 10.0 Kevin C. O'Kane, Ph.D. Computer Science Department University of Northern Iowa Cedar Falls, IA 50614 okane@cs.uni.edu kc.okane@gmail.com http://www.cs.uni.edu/~okane http://www.omahadave.com Sept 7, 2008

Contents

Preface Introduction to Mumps/II Programming Basics How To Run a Program Mumps/II Compile Script MDH Compile Script Interpreting a Program Error Messages Variable Types Data Types Commands Zmain Precedence Operators Language Specification Data Types and Values Variables Global Arrays Writing Programs Example Programs Operators Arithmetic unary operators: + - Arithmetic binary operators: + - * / \ ** Arithmetic relational operators: > < String binary operator: _ String relational operators: = [ ] ]] ? Logical operators: &, ! ' Indirection operator: @ Commands break (abbreviation: b) Important Notes on break and quit catch (abbreviation: ca) close (abbreviation: c) continue (no abbreviation) declare (no abbreviation) do (abbreviation: d) else (abbreviation: e) export (abbreviation: ex) for (abbreviation: f) goto (abbreviation: g) halt (abbreviation: h) hang (abbreviation: h) html (abbreviation: html) if (abbreviation: i) job (abbreviation: j) kill (abbreviation: k) lock (abbreviation: l) merge (abbreviation: m) new (abbreviation: n) open (abbreviation: o) quit (abbreviation: q) Notes on break and quit read (abbreviation: r) set (abbreviation: s) shell and sql extensions try (abbreviation: t) use (abbreviation: u) view (abbreviation: v) write (abbreviation: w) xecute (abbreviation: x) z... (abbreviation: z...) Builtin Functions $ascii(e1) or $ascii(e1,i2) $char(i1) or $char(i1,i2) or $char(i1,i2,...) $get(i1) or $get(i1,i2) $data(vn) $extract(e,i2) or $extract(e1,i2,i3) $find(e1,e2) or $find(e1,e2,i3) $justify(e1,i2) or $justify(e1,i2,i3) $len(e1) or $len(e1,e2) $name(vn,[e1]) $order(vn[,d]) $piece(e1,e2,i3) or $piece(e1,e2,i3,i4) $qlength(e1) $qsubscript(e1,e2) $query(e1[,c]) $random(i1) $reverse(i1) $select(t1:e1,t2:e2,...tn:en) $text(L1) or $text(L1+/-I2) or $text(I1) $translate(S1,S2) or $translate(S1,S2,S3) $view

Special Text Functions $zzAvg(arg) $zzBMGSearch(arg,arg2) $zzCentroid(arg1,arg2) $zzCount(gbl) Stream Input Functions $zzScan $zzScanAlnum Similarity Functions $zzCosine(arg1,arg2) $zzSim1(arg1,arg2) $zzDice(arg1,arg2) $zzJaccard(arg1,arg2) $zzIDF(arg1,arg2) $zzDocCorrelate(arg1,arg2,arg3,arg4) $zzMax(arg) $zzMin(arg) $zzMultiply(arg1,arg2,arg3) Regular Expression Matching $zPerlMatch() $zReplace() $zzTermCorrelate(a1,a3) $zzTranspose(arg1,arg2) Shred functions $zShred(a1,a2) $zShredQuery(a1,a2) $zSmithWaterman(arg1,arg2,arg3,argi4,arg5,arg6,arg7) $zzSum(gbl) Word Functions $zStopInit(arg) $zStopLookup(arg) $zSynInit(arg) $zSynLookup(arg) Math Functions $zacos(arg) $zasin(arg) $zatan(arg) $zcos(arg) $zexp(arg) $zlog(arg) $zlog10(arg) $zpow(arg1,arg2) $zsin(arg) $ztan(arg) $zab(arg) Absolute value $zb(arg) Remove extraneous blanks. $zcd[(filename)] Dump global arrays $zchdir[(directory_path)] Change directory $zcl[(filename)] Restore global arrays $zdate Date in printable format $zd1 Date in Linux time $zd2(InternalDate) Convert Linux time to printable time $zd3(Year,Month,Day) Gregorian time to Julian $zd4(Year,DayOfYear) Julian to Gregorian time $zd5(Year, Month, Day) Julian time $zd6 Hour, minute, second $zd7 Linux time to printable time $zd8 Linux time to printable time $zd9 Linux time to printable time $zf(arg) Test if file exists $zflush Flush native file system globals $zg Size of global arrays $zh(arg) Encode string as HTML parameter $zhit Calculate Btree cache hit ratio. $zm(global) Next global array row. $zlower(string) Convert to lower case.. $zn(arg1,[arg2]) Word normalize $zp(arg1,arg2) Pad to the right with blanks $zr(arg) Square root $zs(arg) Execute shell command $zseek(arg) Move to file address $zsqr(arg) Square an argument $zstem(arg) Return word stem $zsystem(arg) Execute shell command $ztell Tell file position $zu(exp) Is expression numeric? $zwi(arg) Initialize parse buffer $zwn Return next token $zwp Return next parsed token $zws Initialize parse buffer Builtin Variables $horolog (Abbreviation $h) $io (Abbreviation: $i) $job (Abbreviation $j) $test (Abbreviation $t) $storage (Abbreviation $s) $x $y Installing the Compiler Other Software Needed MS Windows Install MS Visual C++ Binary Install MS Visual C++ Full Build Details Windows XP Apache Web Server Interface Linux Install Linux/Cygwin Quick Install Linux/Cygwin Full Installation Compiling Programs Global Arrays Using Mumps/II with a Web Server Uncontrolled Program Termination Program Formats and Error Messages Compiler Implementation Overview Writing Programs, Functions and Calling Conventions Program Structure Main Programs and Functions Hybrid Mumps/II and C++ Programs Implementation Notes Relational Algebra for Global Arrays Programming Examples How To Write Web Server CGI Mumps/II Scripts Technical Notes Index Appendix B - GNU GPL/LGPL and Documentation Licenses Appendix D - Mumps/II 95 Pattern Matching Appendix E - Using Perl Regular Expressions Appendix G - Manual Pages Appendix H - PCRE License Appendix I - MAC OS/X Installation Instructions

Preface

The purpose of this document is to present an overview of the Mumps/II Compiler implementation of the Mumps/II language. This package consists of source code for compilers and support libraries for various operating systems for a dialect of the Mumps language. Mumps/II is a simple, easy to learn string and hierarchical data base scripting language originally developed for medical computing applications but is now used in many other settings. Related documentation is available at:

Mumps/II Manual
MDH/C++ Manual
Information Storage & Retrieval in Mumps/II
IDF Searching of Genomic Data Bases

Introduction to Mumps/II

Mumps (also referred to as 'M') is a general purpose programming language that supports a native hierarchical data base facility. It is supported by a large user community (mainly biomedical), and a diversified installed application software base. The language originated in the mid-60's at the Massachusetts General Hospital and it became widely used in both clinical and commercial settings. A dwindling number of implementations exist for the language. There were ANSI, ISO (ISO/IEC 11756:1992) and DOD approved standards for Mumps although these have mainly lapsed in recent years.

As originally conceived, Mumps differed from other mini-computer based languages of the late 1960's by providing: 1) an easily manipulated hierarchical (multi-dimensional) data base that was well suited to representing medical records; 2) flexible string handling support; and (3) multiple concurrent tasks in limited memory on very small machines. Syntactically, Mumps is based on an earlier language named JOSS and has an appearance that is similar to early versions of Basic that were also based on JOSS.

This software package includes both a compiler and interpreter for Mumps/II

The Mumps/II Compiler is a translator that converts Mumps/II to C++. The compiler implements much of the most recent Mumps standard (see the manual). Mumps/II programs are translated to standard C++ programs and subsequently compiled to binary executables. The compiler distribution contains the compiler source code, the manual, the run-time functions source code, all written in C/C++, and examples, written in Mumps/II. The compiler works under Linux and Cygwin (for Windows) with the 'gcc/g++' compilers and Microsoft Visual C++ 2005 under Windows.

The Mumps/II Interpreter is a compiled Mumps/II program that permits direct execution (interpretation) of Mumps/II programs. It is available under Linux, Cygwin and Microsoft Windows.

The MDH (Multi-Dimensional and Hierarchical Data Base Toolkit) is a Linux-based, open sourced, toolkit of portable software that supports Mumps/II-compatible, very fast, flexible, multi-dimensional and hierarchical storage, retrieval and manipulation of data bases ranging in size up to 256 terabytes. The package is written in C and C++ and is available under the GNU GPL/LGPL licenses in source code form. You must install the Mumps/II Compiler in order to use the MDH.

Programming Basics

1. The Mumps/II programs described in this document can be run in either of two ways: either as interpreted code using the Mumps/II Interpreter or as binary executables resulting from application of the Mumps/II Compiler. Binary programs run faster that interpreted programs but the difference can be small if the programs are dominantly input/output jobs. The Mumps/II Interpreter is created by compiling the program "mumps.mps" provided with the distribution. For WinXP based systems, where a C/C++ compiler is not normally available, the interpreter may be s simpler and easier approach to developing applications. All programs that execute with the interpreter can be compiled by the compiler.

2. How to Run a Program.

   Programs written in Mumps/II normally have the extension ".mps" when used with the compiler. Programs written for the interpreter, however, may have any extension but ".mps" is preferred. MDH programs written in C++ must have the ".cpp" extension.

   When you compile a Mumps/II program, a C++ translation of your program is made and resides on the disk with the same name but with the .cpp extension. The C++ translation is then compiled and linked with run-time libraries to build an executable binary. On MS Windows, the binary will have the same name as your original program but with the .exe extension. On Linux, the binary will have the extension .cgi and the same name as your original program. Depending on which system you are using, there will be other, intermediate files generated by the Mumps/II and C++ compilers. These are not important.

   You may compile a program either by using the built in script "mumpsc" or by manually performing each of the steps at the command prompt.

   To compile a Mumps/II program using the script, type:

   mumpsc myprog.mps
   

   This will translate your Mumps/II program to C++, run the C++ compiler on the result, and link the output of the C++ compiler with the standard Mumps/II libraries.

   To do the above steps individually, type the following sequence:

   mumps2c myprog.mps
   g++ -O3 -o myprog.cgi myprog.cpp -lmpscpp -lmumps -lmpsglobal_native -lpcre
   

   The first command ("mumps2c") translates the Mumps/II program to C++. The output will be named "myprog.cpp". The second command ("g++") runs the C++ compiler on "myprog.cpp" and links the result with the standard Mumps/II libraries (using the native gloabl arrays). You may wish to use this sequence if your Mumps/II programs has embedded C++ code that calls on special libraries that are not included in the "mumsc" script, for example, PostgreSQL.

   Also, use the above "g++" command to compile a C++ program generated by the Mumps/II Compiler that you may have edited (for example, to insert debugging information). You may not use the "mumpsc" script to compile a ".cpp" program generated by the Mumps/II Compiler. The "mumpsc" script may only be used to compile Mumps source programs (".mps" extensions) and MDH programs (".cpp" extensions). When "mumpsc" sees you compiling a program with the ".cpp" extension, it sets certain switches that are not appropriate for a ".cpp" program generated by the Mumps Compiler.

   To compile an MDH/C++ program using the script, type:

   mumpsc myprog.cpp
   

   To interpret a program, type:

   mumps myprog.mps

   The Mumps Interpreter runs your program from source code. Note: the interpreter is subject to several restrictions and should not be used for production work. It is intended for debugging and quick, interactive viewing of global arrays.

3. Generally speaking, in most cases you will receive syntax error messages from which will identify the error and the line number in the original Mumps program containing the error. When using the compiler, in some cases, an error may be detected by the C++ compiler. If you get C++ error messages, the line number on the error message will refer to the line number in the C++ translation of your Mumps program. To translate this to a line number in your Mumps program, look into the generated .cpp file at the line number given in the C++ error message and then back track to the nearest prior commented Mumps source line - this is the line in your Mumps programs that caused the problem.

   For example, if you get a message from the C++ compiler saying that you have an error at line 1234 in the C++ module, open the C++ file and move to line 1234. At that location you will see something like:

   /*=================================================================================* svPtr->LineNumber=4; // write "the sum is: ",total,! /*=================================================================================*/ if (svPtr->out_file[svPtr->io]==NULL) ErrorMessage("Write to input file",svPtr->LineNumber); svPtr->hor[svPtr->io]+=fprintf(svPtr->out_file[svPtr->io],"%s","the sum is: "); if (sym_(SYMGET,(unsigned char *) "total",(unsigned char *) tmp0,svPtr)==NULL) VariableNotFound(svPtr->LineNumber); svPtr->hor[svPtr->io]+=fprintf(svPtr->out_file[svPtr->io],"%s",tmp0); fprintf(svPtr->out_file[svPtr->io],"\n"); svPtr->hor[svPtr->io]=0; svPtr->ver[svPtr->io]++;

   Notice that each original line of Mumps code and its line number in the original Mumps file appear in a comment prior to the C++ translation. To find the line of Mumps code that caused the C++ error, look for the line of Mumps code next preceding the line which the C++ complier flagged as being in error. Generally speaking, you may receive C++ error messages if you reference non-existent labels or subroutines, or incorrectly specify indented do blocks (see below). It is not necessary to know C++ to do this. Also, you may see ^M (control-M) characters in the code, especially if you are viewing a MS WinXP file with a Linux editor. These are visible due the differences bewteen the operating systems. Under WinXP, each line ends in a a set of carriage-return and a line-feed characters. Under Linux, each line ends in a line-feed character only. The control-M's you see are the carriage-returns. They are harmless.

4. Mumps has two basic classes of variables: local and global. Local variables reside in memory and exist during program execution (like normal variables) while global variables reside on disk and continue to exist after the program has terminated. Generally speaking, global and local variable names can be used interchangeably except that all globals begin with a circumflex (^).

5. Unlike other languages which employ many data types, Mumps has basically one data type - string. Strings that contain numbers, however, can have arithmetic operations performed on them. Neither global nor local variables need to be declared - they will created as needed (note: an extension in the Mumps Compiler permits scalar variables to be pre-declared in order to improve performance). Variables can be destroyed by the KILL command.

6. All Mumps statements begin with a keyword. A keyword can be fully spelled out or, in many cases, abbreviated. The common keywords are:

   set read write if else halt hang use open close do for quit break

   After a keyword there is one blank followed by (in most cases) an "argument". An argument may not have any embedded blanks unless they are within quotes ("..."). Blanks are delimeters in Mumps and their use is restricted.

   More than one command may be on the same line if there is one or more blanks following the previous commands argument. Two or more blanks are required if the previous command had no argument. For example:

   set a="abc" write a,!
   quit:a=b  write a,!
   

   In the first line, both an assignment and write commands are on the same line. In the second line, the quit has no argument so there are two blanks separating it from the write The figure :a=b in the quit is not an argument: it is called a post-conditional. Post-conditionals are expressions that are evaluated before command execution. If true, the command is executed. If false, the command is not executed. Most commands may have post-conditionals attached to the command word.

7. Mumps programs that are to compiled begin with the command zmain which has no arguments and may not be followed by any other text on the line. Interpreted programs do not require zmain. In this guide, zmain will normally appear in each program. The interpreter ignores this line.

   On the other hand, if a source code program begins with a line such as:

   #!/usr/bin/mumps

   and, if the source code file has execute permissions, and the Mumps interpreter is in /usr/bin/mumps, typing the name of the source code file will cause its execution (by the interpreter).

8. There is no precedence. All expressions are evaluated strictly left to right unless you use parens. This can cause problems if you are not careful. The expression:

   a+b-c*d/e means: ((((a+b)-c)*d)/e) Note that: if a=b&c=d write "hello",! means: if (((a=b)&c)=d) write "hello",! which is probably not what you wanted. You probably wanted: if (a=b)&(c=d) write "hello",!

9. The main operators are +, -, *, /, \, #, **, _, >, <, [, ], ', ?, and @. See below for a description of the operators. Note that there is an integer division operator (\) as well as a floating point division operator (/).

10. Mumps has many functions for string processing. These are covered in the manual and you should study them. Mumps also permits indirect execution, that is, your program can create and execute code dynamically.

Language Specification

Introduction

The purpose of this section is to provide you with an introduction to the Mumps language in general and the Mumps compiler. The Mumps language originated in the mid-60's at the Massachusetts General Hospital. The acronym stands for "Massachusetts General Hospital Utility Multi-Programming System". It is a language which is similar in some respects to BASIC but it contains many additional features not found in BASIC, or for that matter, in most other languages. In its full form, Mumps is an interpretive language. In fact, parts of the language specification require that it can never fully become a "compiled" language such as FORTRAN, COBOL or PL/I. In the compiler, some features, therefore, mainly those involving run time interpretation and symbol table binding, are removed. See above for details.

Among the features which make Mumps attractive for both bio-medical and general scientific applications are:

Hierarchical data base facility. Mumps data sets are not only organized along traditional sequential and direct access methods, but also as hierarchical trees whose data nodes are addressed as path descriptions in a manner which is easy for a programmer to master in a relatively short time.

Flexible and powerful string manipulation facilities. Mumps built-in string manipulation operators and functions provide programmer's with access to efficient means to effect complex string manipulation and pattern matching operations.

Transportability to widely different systems Mumps presently runs under a large number of operating systems on many machine architectures. These systems range in size from small home micro-computers to the largest central time sharing systems. Through efforts that have taken place by the Mumps Development Committee over the years, a well organized language definition has been written and formally published. This standard provides for a far tighter specification for system performance and linguistic definition than is normally the case. As a result, programs written under a Mumps system can be moved with relatively little effort from one system to another.

Full numeric data handling facilities Mumps provides, in addition to string handling facilities, a full range of fixed and floating point computational facilities.

Data Types and Values

Basically, Mumps has only one data type: string, although it does allow integer and floating point computations as well as logical expressions. The values in a string may be any ASCII code from 32 to 126 (decimal) inclusive. The Mumps Compiler does not permit usage of the ASCII zero character (<NULL>). Ordinarily, strings will contain ASCII printable characters. String constants are enclosed in double quote marks ("). A double quote mark can be included with two adjacent quote marks (""). A constant containing only numerics (and, optionally, plus, minus and decimal point), need not be enclosed by quotes (although doing so has no effect). The following are examples of valid Mumps character string constants:

When a string is being used as a number (e.g., in addition), the numeric portion must be 20 characters or less in length. Numeric constants are restricted to integer or decimal values (positive or negative). If a string begins with a number but ends with non-numeric characters, only the numeric leading portion will participate in operations requiring numeric operands (e.g., add, subtract, etc.); the trailing non-numeric portion is lost. On the other hand, if a string begins with non-numeric characters, its value will be interpreted as 0. The following are examples:

Only one plus or minus sign is permitted at the beginning of a string or the value will be interpreted as 0. Although "string" is the basic data type, Mumps converts strings internally to floating point values (double) for calculations. Consequently, numbers are of approximately 15 digit precision. Internally, integers are stored as C++ language "long" and floating point numbers as "double."

Logical values in Mumps are special cases of the numerics. A numeric value of zero is interpreted as false while a non-zero value is interpreted as true. Logical operators yield either zero or one and their results can be treated like any other numeric. Similarly, the numeric result of any numeric operator can be used as a logical operand. The results of string operators are interpreted either as zero (leading characters non-numeric) or some value (leading characters numeric). Strings and the results of string operations can therefore participate as the operands of logical operators.

Variables

Variables are named in Mumps in much the same manner they are named in other languages. A Mumps variable name must begin with a letter (A through Z) or percent sign (%) and may be followed by either letters or numbers. Both upper and lower case letters may be used for variables names. Mumps, in effect has only one data type so any variable name may be any value. All Mumps variables are varying length strings. The maximum string length permitted is determined when the compiler is installed. This number is usaullyat least 1024.

In Mumps there are no data declaration statements. Variables come into existence through the set or the read command and pass from existence through the kill command.

In the Mumps, there are two kinds of arrays: internal arrays and global arrays. The following pertains to internal arrays: arrays are not dimensioned. A name used as an array variable may also, at the same time, be used as a scalar. Array values are created by assignment or appearance in a read statement. If you create an element of an array, let us say element 10, it does not mean that Mumps has created any other elements: that is, it does not imply that there exist elements 1 through 9. You may specifically create these or not. Array indices may be positive or negative numbers or character strings. Arrays in Mumps may have multiple dimensions. The following are some examples of arrays:

Global Arrays

Global arrays may be viewed either as multi-dimensional matrices or as tree structured hierarchies. For example, the following is taken from the MeSH Hierarchy. Note the original tree-like organization of the data and see the corresponding Mumps commands to represent the data in the data base. The codes used in the lines of Mumps code are the codes used by Mesh:

Cardiovascular System;A07 Blood Vessels;A07.231 Arteries;A07.231.114 Aorta;A07.231.114.056 Aorta, Abdominal;A07.231.114.056.205 Aorta, Thoracic;A07.231.114.056.372 Sinus of Valsalva;A07.231.114.056.847 Arterioles;A07.231.114.060 Axillary Artery;A07.231.114.085 Basilar Artery;A07.231.114.106 Brachial Artery;A07.231.114.139 Brachiocephalic Trunk;A07.231.114.145 Bronchial Arteries;A07.231.114.158 Carotid Arteries;A07.231.114.186 Carotid Artery, Common;A07.231.114.186.200 Carotid Artery, External;A07.231.114.186.200.210 Carotid Artery, Internal;A07.231.114.186.200.230 Carotid Sinus;A07.231.114.186.456 Celiac Artery;A07.231.114.207 Cerebral Arteries;A07.231.114.228 Anterior Cerebral Artery;A07.231.114.228.100 Circle of Willis;A07.231.114.228.351 Middle Cerebral Artery;A07.231.114.228.550 Posterior Cerebral Artery;A07.231.114.228.700 Temporal Arteries;A07.231.114.228.868

As matrices, data may be stored not only at fully subscripted matrix elements but also at other levels. For example, given a three dimensional matrix mat1, you could initialize it as follows:

In this example, all the elements of a three dimensional matrix of 100 rows, 100 columns and 100 planes are initialized to zero.

Unlike other programming languages, however, there are additional nodes of the matrix which could have been initialized such as indicated by the following example:

In effect, this means that mat1 can also be a single dimensional vector, a two dimensional matrix and a three dimensional matrix simultaneously.

Furthermore, not all elements of a matrix need exist. That is, the matrix can be sparse. For example:

In the above, only index values 0, 10, 20, 30, 40, 50, 60, 70, 80, and 90 are used to create each of the dimensions of the array and only those elements of the matrix are created. The omitted elements do not exist.

Global arrays are unique to Mumps. As a programmer, you will work with them as though they were arrays. The system, however, interprets them as tree path descriptions for the system's external data files. A global array is distinguished by beginning with the circumflex character (^). The remainder of the specification is the same as an internal array. global arrays are not dimensioned and they may appear anywhere an ordinary variable may appear (except in certain forms of the "kill" command). A typical global array specification consists of the array name followed by some number of indices (indices may be constants, variables [including internal or global arrays] or expressions of string, numeric or mixed type). For example:

The system files are viewed as trees. Each global array name ("A", "SHIP", "CAPTAIN", and "HOME" in the above) is the root of a tree. The indices are thought of as path descriptions to leaves. For example, out of the root "^a" there may be many branches, the above specifies to take the branch labeled "1" (note: this does not mean the "first" branch out of the node - it means the branch with label "1"). At the second level the specification says to take the branch labeled "43" (note: this does not imply that branches 1 through 42 necessarily exist). The path description is followed (or, possibly, created if the global array specification appears on the left hand side of an assignment statement or in a read command) to a final node. The value at the node is either retrieved or a new value stored depending upon the context in which the global array specification was used. The indices of global arrays may be numeric or character strings. The second sequence of examples above illustrates this usage.

Both string and character indices may be mixed in the same path description.

A value may be stored at any position in the tree. For example:

Mumps arrays are not pre-declared and they are sparse. That is, only those elements which you explicitly create actually exist. For example, if you create element ^A(10), it does not necessarily mean that elements ^A(1) through ^A(9) exist.

Global arrays are often interpreted as trees where each successive index describes the path through a multi-way tree. At each node, data can be stored (or not). The path from the root to a node is given by the sequence of indices of an array reference. The data base can store many trees, each distinguished by their array name.

The Mumps global array facility is due to the early uses of Mumps in medical data bases which are basically hierarchical in nature. The Mumps global arrays were a solution to the problem of how to represent the tree-like structure of patient data in a simple and easily manipulated data structure.

For example, consider a basic patient record. At the top level is the patient's id node at which is stored the patient's name. At the second level, are nodes for demographic (address, gender, phone number, etc.) data and the main entry node for clinical data. Clinical data is organized by diagnostic or problem category and each problem or diagnostic code is divided into episodes of the problem organized by onset date. For a given problem and onset, the data are divided by category (medications, lab tests, orders, notes, etc.) which are further subdivided by, for example, in the case of lab tests, test, date, time and result. For example:

Here, the tree is named patient which is also the name of the global array (notice that global arrays always have a circumflex (^) preceding their name). The Mumps code to populate the above might look like:

set ^patient("123-45-6789")="Jones, John, J" set ^patient("123-45-6789","Demographics","Street")="123 Elm St" set ^patient("123-45-6789","Demographics","City")="Anytown" set ^patient("123-45-6789","Demographics","State")="IA" set ^patient("123-45-6789","Demographics","ZIP")="50613" set ^patient("123-45-6789","Dx",789.00,"6/23/2005")="Dr Smith" set ^patient("123-45-6789","Dx",789.00,"6/23/2005","lab","HCT","6/23/2005","10:45",45.2)="" set ^patient("123-45-6789","Dx",789.00,"6/23/2005","lab","HCT","6/23/2005","20:45",43.2)="" set ^patient("123-45-6789","Dx",789.00,"6/23/2005","lab","HCT","6/24/2005","21:10",44.2)="" set ^patient("123-45-6789","Dx",789.00,"6/23/2005","lab","HCT","6/25/2005","14:10",44.2)=""

Notice that the empty string can be stored at a node. In these cases, the actual data (the lab test result) is the value of the final index. Also note that each intermediate node need not be created. The nodes representing ""Demographics", "lab", "Dx", HCT, and others are not explicityly created. Their creation is implicit in constructing the longer paths of which they are intermediates.

Writing Programs

Mumps was originally conceived as a language to be executed by interpreters. Consequently, the syntax and structure of commands tend to be line oriented and simple to parse.

Each command in Mumps begins with a key word. The keyword may be abbreviated, in many cases to a single letter (this was to save storage and time on the early interpreters but has no effect on efficiency in the Mumps Compiler). A command is followed optionally be a post-conditional expression and then, in most cases by one or more arguments. The blank character is a terminator in Mumps so the placement of blanks is important. A blank is used to separate a command keyword from its arguments and to terminate the list of arguments. If a command has no arguments and there are others commands following on the line, the command (or, the command and its post-conditional) are followed by at least two blanks. Blanks may not be embedded in expressions except in quoted fields.

A post-conditional is an expression that will be evaluated prior to executing the arguments of a command. If the expression is true, the arguments will be executed. If the expression is false, the arguments will not be executed and control will move to the next command. Some commands, such as the if and the else may not be post-conditionalized. Other commands, such as the do and the goto may not only be post-conditionalized at the command level, but also at the argument level. Most commands are only post-conditionalized at the command level. Here are some valid commands with and without post-conditionals (";" causes the remainder of the line to be interpreted as a comment):

set i="hello world" set i="hello",j="world" ; multiple arguments to the "set" set:a=10 i="hello world" ; only executed if "a=10" is true goto label1 gotto:b<a label1 ; executes only if "a<b" is true goto label1:c>d ; executes only if "c>d" goto lab1:c>d,lab2:d<e ; multiple post-conditionals quit:a=b set i="hello" ; argumentless "quit" followed by 2 blanks goto:a=10 lab1:c>d,lab2:d<e ; multiple post-conditionals

The basic assignment statement in Mumps is the set statement. It may have one or more arguments. The left hand side is evaluated and the result is assigned to the variable on the left hand side. Expressions in Mumps are evaluated strictly left-to right without precedence. If you want a different ordering of the evaluation, you must use parentheses. This is true in any Mumps expression in any Mumps command. It is a common source of error, especially in if commands with compound predicates.

Variable in Mumps, as noted above, can be local, that is, present only during the execution of the program, or global, which is to say, disk resident and persistent from one execution of the program to the next. Both local and global variables may be either scalar or arrays although most local variables tend to be scalar and most global variables tend to be arrays in practice.

A variable, either global or local, is created by appearing on the right hand side of a set statement (or as an argument in a read statement). The Mumps symbol table is dynamic and variables are created as needed. They may also be destroyed (kill).

Expressions may involve both local and global variables, operators (see below) and constants. Constants may be either numeric or string. String constants are enclosed in double quits (use two immediately adjacent double quotes to create a single double quote in a quoted string). Strings are converted to numerics as needed and back again. The basic internal data type is string. For example (in each of these, the item written is followed by a <new-line> character due to the "!"):

set i=2 write i,! ; writes 2 set i=2*3 write i,! ; writes 6 set i="2"*3 write i,! ; writes 6 set i=" 2"*3 write i,! ; writes 6 set i="""hello""" write i,! ; writes "hello" set ^a="test" write ^a,! ; writes test set a="test" write a,! ; writes test set ^a(1)="tst" write ^a(1),! ; write tst set a(1)="tst" write a(1),! ; write tst

The last four examples use global and local scalars, respectively.

The input/output commands are read and write. They may each use formatting codes. The formatting codes are:

! - new line (!! two new-lines, etc.) # - new page ?x - advance to column "x" (new-line if needed)

The read command may contain out put codes and string constants along with the variable names to be read. This permits prompts to be embedded in the read (note: this only applies when reading from the console). For example:

This will cause the prompt "enter name:" to be written at the beginning of a new line (!) and then the cursor will tab to column 20 and await the user's input which will be stored in variable "x".

Examples of the write command:

write "hello world",! set i="hello",j="world" write i," ",j,! set i="hello",j="world" write i,!,j,! write 1,?10,2,?20,3,?30,4,!!

The first example above writes "hello world" followed by a new-line. The second does the same. The third writes "hello" and "world" on separate lines. The fourth writes 1, 2, 3, and 4 in columns 10, 20,30 and 40, respectively followed by two new-lines.

The argumented form of theif statement Mumps tests one or more expressions for true and does or does not execute the remainder of the line depending upon the result. A value is considered to be "true" if it is non-zero and "false" if zero. If there are multiple arguments, each argument must be true. Note that the if command has as its scope the entire remainder of the line on which it appears, not just the next command. As a side effect, the if statement sets the system built-in variable $test to "true". And's ("&") and or's ("|") may be used in expressions along with not's ("'"). The relational operators are cited below. Examples:

1 set i=1,j=2,k=3 2 if i=1 write "yes",! ; yes 3 if i<j write "yes",! ; yes 4 if i<j,k>j write "yes",! ; yes 5 if i<j&k>j write "yes",! ; does not write 6 if i<j&(k>j) write "yes",! ; yes 7 if i write "yes",! ; yes 8 if 'i write "yes",! ; does not write 9 if '(i=0) write "yes",! ; yes 10 if i=0|(j=2) write "yes",! ; yes

Note the multiple arguments on line 4 above. This effectively constitutes an "and" operation. Also note line 5. Due to strict left-to-right, non-precedence parse, the expression is interpreted as though it had been written "(((i<j)&k)>j)". The "i<j" is true (1); "1&k" is true (1) but "1>j" is false so the expression is false. The expression on line 6 is probably what was wanted. It is very important to include parentheses in compound expressions to express precedence.

The argumentless form of the if statement (which is followed by two or more blanks) tests the current value of $test and does or does not execute the remainder of the line depending upon if $test is true (1) or false (0). For example:

set i=1 if i=1 write "yes",! if write "yes again",!

The above will write "yes" and "yes again" because the first if sets $test to true. A negative side effect of this is that $test can be reset to false in the scope of the first if:

set i=1 if i>1 write "yes",! if i>2 write "yes yes",! if write "yes again",!

The above will write "yes" only. The second if on the second line sets $test to false. For compiled code, $test is restored to its previous value upon exit from a block:

set i=1 if i=1 do . if i=0 write 123,! else write 987,!

The false if expression sets $test only within the block. The previous value is restored on exit. Note: $test is not restore from block exit in the interpreter.

The principle iterative command is the for command. It has the syntax of a local, scalar index variable followed by an equals sign followed by one or more arguments. The arguments may either be specific values the index variable should have or a range specification. A range specification is either two numbers separated by a colon or three numbers separated by two colons. In both cases, the first number is the initial value for the index variable, and the second is the increment (or decrement if negative). The third number, if present, is the limit value. If no third number is specified, there is no upper limit and some other mechanism must terminate the loop. For example:

for i=1:1:10 write i,! ; 1,2,...9,10 for i=1,3,5,7 write i,! ; 1,3,5,7 for i=10:-1:0 write i,! ; 10,9,...2,1,0 for i=1:1 write i,! ; 1,2,3 ... for i=1:1:10,100,200 write i,! ; 1,2,...9,10,100,200 for i=10,20,30:1:40 write i,! ; 10,20,30,31,...40

An argumentless for loops forever until stopped by another command. The quit command will terminate the nearest command on the current line:

for i=1:1 write i,! quit:i>10 ; 1,2,...9,10

If there are multiple for commands, the quit terminates the nearest:

for i=1:1:10 for j=1:1 write j,! quit:j>5

the above will write 1 through 5 a total of 10 times.

The for is often used with the argumentless form of the do command. The argumentless form of the do assumes there will be a block of code immediately following the current command line. The block will be executed. For example:

for i=1:1:10 do . write i . write " ",i*i,!

The above will write the numbers 1 through 10 followed by the square of the number.

In the compiled code, when you enter a block by means of an argumentless do, the value of $test is stored and restored on normal exit from the block. If you exit the block by means of a goto, the value of $test is not restored. $test is not restored under any circumstances in the interpreter.

In the context of a block, the quit command means to quit the block, not the for. For example:

for i=1:1:10 do . write i . if i>5 write ! quit . write " ",i*i,!

The above will write 5 lines with numbers and their squares and 5 lines with just the numbers (6 through 10). The quit terminates the block but not the for. A break (this is a non-standard feature of the Mumps Compiler) may be used to exit a block:

for i=1:1:10 do . write i . if i>5 write ! break . write " ",i*i,!

The above will only write 5 lines. The break terminates the block and the for. A break may only be used in a block. Alternatively, the quit could be used as follows:

for i=1:1:10 do write ! quit:i>4 . write i . if i>4 quit . write " ",i*i

The above will write 5 lines, 4 of which have the number and its square. Note the two blanks after the argumentless do.

Another form would be:

set i=1 for do . write i," ",i*i,! . set i=i+1 . if i>10 break

The above will write 10 lines, each with two numbers.

Blocks may be nested but the break only applies to the block in which it appears:

set i=1 for do . write i," " . set j=1 . for do .. write j," " .. set j=j+1 .. if j>10 break . write ! . set i=i+1 . if i>10 break

The above will write ten lines, each with 11 numbers (1 number for the outer loop and 10 numbers due to the inner loop).

The do command is also used to invoke subfunctions. See the discussion and examples below under the do command.

For input/output, Mumps uses a scheme based on unit number. The Mumps compiler permits 10 unit numbers. By default, your program begins using unit 5, the console screen and keyboard (stdin and stdout in Linux terminology). You may open files and associate them with unit numbers through the open command and disassociate files from unit numbers with the close command. It is important that you close files that you have used for output as this will insure that the buffers have been written to disk. The use command tells the system which I/O unit to use. This unit remains in effect until changed. For example, the following copies the contents of file "aaa.dat" to file "bbb.dat" which is created if it did not previously exist:

zmain open 1:"aaa.dat,old" open 2:"bbb.dat,new" write "copying ...",! for do . use 1 . read rec . if '$test break . use 2 . write rec,! close 1,2 use 5 write "done",!

Each read command sets $test to true is successful. On end of file, $test is set to false and the loop terminates. the ",old" and ",new" markers indicate if the file is being opened for input (",old") or output (",new").

Example Programs

Mumps is a very simple but powerful string manipulation and data base scripting language. It is similar in structure to early forms of BASIC and can generally be learned in a few hours. The following are a series of examples of Mumps programs and explanations of the code.

1. Program to sum the first 100 numbers:

   zmain set total=0 for i=1:1:100 set total=total+i write "the sum is: ",total,!

   Notes:

   • A program can be written using a text editor such as vi, emacs or some other editor that does not embed special characters in the text (as some word processor programs do).

   • Lines of Mumps code may begin with a blank, a plus sign (+), a pound sign (#), a character, or a letter.
     • If a line begins with a pound sign, the remainder of the line is taken as a comment and not processed by the compiler.
     • If a line begins with a plus sign, the remainder of the line is taken to be C++ code and is passed unchanged to the C++ compler.
     • If the line begins with a letter, the word beginning with the letter up to the first blank on the line is taken as a label. There must be at least on blank following a label.
     • If the line begins with a character or one or more blanks, the line has no label. The code for the line begins at the first non-blank character.

   • Each line has one or more commands, each beginning with a keyword. Most commands have operands which are separated by exactly one blank from the command word. In cases where the command has no operands, the command is either the final item on a line or it is seprated from the next command by two or more blanks. Operands to commands may not have embedded blanks except in quoted fields.

   • Every program has at least one zmain command that identifies the main program. The zmain must be on a line by itself.

   • In the example above, the set introduces the assignment command. The variable "total" is created (first use) and assigned the value zero.

   • The for command is the iterative command and can have 3 arguments: starting value, increment and limit. It can also have other forms (see below). The scope of the for command shown is the current line.

   • The write command writes variables, strings, numbers, etc. Each element is separated from the others by a comma. The "!" means new line. You may also use something of the form ?15 to mean tab to position 15 (a numeric constant is required).

2. Program to read a file of numbers and sum them.

   zmain set sum=0 for do . read val . if '$test break . set sum=sum+val write "sum is ",sum,!

   • The program reads numbers until it receives an end-of-file. The loop cotrol is a the for command with no arguments. Note there are 2 blanks after the word for. These are REQUIRED as there is no argument. A for with no arguments loops until a quit (single line context) or a break (multiple line do context).

   • The input command in Mumps is read. It reads from the current I/O device (see below, by default, this is stdin). Mumps reads a line at a time thus multiple values should, in this case, be on separate lines (note: there are, however, functions to extract separate values from a line - see below).

   • The do command is used to invoke a section of code as a subroutine. It often is followed by an argument giving the name of the entry point of the code module being invoked. However, you use the do without an argument if you want to invoke a block of code contained on a group of lines immediately following in the code. The block of lines must must each begin with one or more "." characters to express the level of depth and in order to tell the compiler the extent of the block. You may have blocks within blocks. Nested blocks have more leading "." characters. A block ends when the indent (".") level reduces. In the example above, the block of code invoked by the do command is the three lines immediately following the do, each having one ". " preceding the code on the line.

   • Although the for has single line scope, the do effectively extends the scope to subsequent lines. The break, in this case, is a non-standard extension that exits both the do and its controlling for.

   • A break is not permitted in a single line for - use quit. A quit on a single line for terminates a for. HOWEVER, a quit in a do block means "continue" - that is, skip the remainmder of the block and return to the command following the controlling do. This often results in the block being re-invoked.

   • The builtin variable "$test" indicates if something worked or not. If the previous read succeeded (i.e., did not achieve end-of-file), "$test" is true, false otherwise. The single quote "'" is the "not" sign so the expression in the if command means "not $test" which will be true if the read failed (end of input).

   • Some Mumps commands such a for and if have a scope that extends through the end of the line on which they appear. This can cause some unusual consequences.

     For example, if the previous program could have also been written with multiple commands following on the same line as the for as:

     zmain set sum=0 for read val if '$test quit set sum=sum+val write "sum is ",sum,!

     it would not work. This is because of the if command. If the if expression is not true, the remainder of the line is not executed. Thus, if the read were successful, the expression in the if would be dalse and the remainder of the line, including the set statement, would not execute. There is a way around this sort of problem:

     zmain set sum=0 for read val quit:'$test set sum=sum+val write "sum is ",sum,!

     Here the "not $test" is applied as a postconditional (note the ":") to the quit command. When a postconditional is applied, the command is only effective if the postconditional is true. the quit command on a one line for statement means to terminate the loop. Because the quit has no argument (a postconditional is not an argument), at least two blanks are required before the next command. Most commands may have postconditionals. Overall, you should probably use the do and a dotted indet block.

3. Write a program to read a line of text and separate the words.

   zmain read line set line=$zb(line) // replaces multiple blanks by one blank for i=1:1 do . set word=$piece(line," ",i) // separates the string delimited by " " . if word="" break . write word,! when given the input: How much wood would a wood chuck chuck if a wood chuck would chuck wood? produces: How much wood would a wood chuck chuck if a wood chuck would chuck wood?

   Notes:

   • The function $zb() returns a string from which multiple blanks have been replaced with single blanks. Builtin functions in Mumps begin with a dollar sign ($). Functions whose names begin with a "z" are extensions from the legacy language standard. A complete list of these functions can be found in the manual.

   • The for of the for command in the example initializes "i" to 1 (the first constant after the equals sign) and increments it by 1 (second constant) after each iteration. There is no upper limit.

   • The builtin function $piece(source,pattern,start[,end]) returns a string from "source" delimited by "pattern" The string returned follows the "start"-1 instance of the pattern and ends at the "end" instance of pattern if "end" is present, "start" otherwise. An empty string is returned if the function cannot extract the requested piece of the source string. For example:

     set a="abc.def.ghi.jkl" write $piece(a,".",1) -> abc write $piece(a,".",2) -> def write $piece(a,".",1,2) -> abc.def

4. Write a program to read two numbers and a numeric operator, perform the operation and report the result. That is, use indirection (interpretation).

   zmain read first read second read op if first'?.N write "operand 1 must be numeric",! halt if second'?.N write "operand 2 must be numeric",! halt if $length(operator)'=1 write "operator must be a single character",! halt if $find("+-*/#",op)=0 write "unknown operator",! halt set str=first_op_second write str,"=",@str,! input: 10 2 * output: 10*2=20

   Notes:

   • The expression first'?.N is an example of the pattern match operator (?). It means "first not-pattern .N" or, the expression is true if the contents of first are not consistent with the pattern ".N". The figure ".N" means "some number of numerics" ("." means any number - including zero, "N" means numeric). See the manual for other examples and pattern matching codes.

   • The halt command terminates the program.

   • The $length() function returns the length of a string. The $find() function (see manual) returns an integer that is zero (false) if the second string is not found in the first string. It returns a positive integer if it is found. See the manual for a description of what the integer means. In the case of the example, the function is used to determine if the operator is one of the allowed operators.

   • The "_" operator means concatenate two strings together.

   • The "@" is the indirection or interpretation operator. It causes the expression following it to be evaluated and executed. Interpretation is slow but handy. In the example, the string "str" conrtains an expression composed of the values read in from the keyboard with the operator between them (an arithmetic expression). When the "@" operator is applied to a string containing a valid Mumps expression, the system evaluates the expression (at run-time) and returns a string containing an answer.

     Some legal forms for indirection:

     write @"2+3",! // writes 5 set ^a(1)="3*3" write @^a(1),! // writes 9 set ^a(9)="4+4" set i="8+1" write @^a(@i),! // writes 8

     Indirection should be used sparingly since it is inefficient.

   • You can trap errors from the interpreter with:

     zmain set x="1/0" try NoMessages set i=@x catch InterpreterException write "error",! halt

   • The statement:

     write @(first_op_second),!

     also works.

5. Write a program that reads in an expression and then applies it to each line a file:

   zmain read "enter expression: ",exp open 1:"input.dat,old" if '$test write "file open error",! halt for do . use 1 . read line . if @exp use 5 write line,! example input expression: $find(line,"abc")

   Notes:

   • The program will, by interpretation, apply the expression to weach line of input. If the expression is "true", the input line will be printed.

   • The "open" statement opens an input file. Open files are referred to by unit numbers that you pick (1 thru 4, normally). The ",old" part means the file exists. If you are creating a file, use ",new". If the file open fails, $test is false.

   • The unit number for your keyboard/screen is 5. It is the only unit number that you can both read and write too. A common error is to try to write to an input file or read from an output file. When you do a read or write, Mumps uses the current unit number, usually 5. If you want another, use the use command. After a unit number is specified, it remains in effect until changed.

6. Write a program to read a file and build a dictionary of the words found in the file and count the total number times each word occurs. Input is fom stdin.

   zmain for do . read line . if '$t break . set line=$zb(line) // replaces multiple blanks by one blank . for i=1:1 do .. set word=$piece(line," ",i) // separates the string delimited by " " .. if word="" break .. if '$data(^dict(word)) set ^dict(word)=1 .. else set ^dict(word)=^dict(word)+1 // caution - "else" isn't what it seems set word="" for do . set word=$order(^dict(word)) . if word="" break . write word," ",^dict(word),!

   • The $piece() function returns the ith piece of the first string delimited by the second.

   • The $data() function is true if the global array node exists. It is false otherwise.

   • The (i>$order() function returns the next ascending value of the final index of the global array argument or the empty string if there are no more. Indices are retrieved in collating sequence order (ASCII). If the value of the argument is the empty string, the function returns the value of the first index, if one exists. On sucessive iterations, the value to the function is the current index value which results in retrieving the next index value, if one exists.
   • The else command (notice the two blanks after it - it has no arguments) is not really connected to the if statement. In Mumps, else checks the value of $test and executes the remainder of the line if $test is false. No preceding if is required - the else is purely related tio $test. One consequence of this is that if you have an if statement that executes (its expression is true), and an else on the following line, if the line executed as a result of the if causes $test to become false, the subsequenct else will execute! Note also, an if command may also have no arguments (followed by at least two blanks). If this is the case, it tests $test and executes the remainder of the line it is on if $test is true.

   • Notice the double nested loops expressed by the level indent dots. The outer loop reads input while the inner loop processes each line. When the inner loop terminates, the outer loop interates.

   • The program reads a line from standard input, removes extraneous blanks, the extracts successive words from the line (until the string returned from $piece() is empty). Each word extracted is checked against the data base. If the word is not in the global array as an index ($data() returns non-zero), intialize the global array element for this word as zero; otherwise, increment the value stored in the global array - the count of the number of times this work has occurred. When the input is exhausted, the program prints the words (indices) and the count stored at each one.

7. Write a program to produce an indented display of the indices of a global array tree. Assume the tree has no more than 4 levels of depth.

   Notes:

   • The program is written as a set of four nested for loops.

   • The outer loop iterates the first index; the first nested loop iterates, the second index, and so forth.

   • Should the global array have fewer than four levels of indices, the program willl still work. If there are no indecies as a given level three, for example, the third nested loop will immediately return an empty string and the loop will terminate. The fourth nested loop will not be attempted.

   • Notice that prior to each loop, the index variable is set to the initial value of empty string and that the value returned by $order() is tested for empty string. The first value presented to $order() is empty and the last value returned is empty.

   zmain for i=1:1:5 for j=1:1:5 for k=1:1:5 for l=1:1:5 set ^tree(i,j,k,l)=i for lev1="":$order(^tree(lev1)):"" do . write lev1,! . for lev2="":$order(^tree(lev1,lev2)):"" do .. write ?5,lev2,! .. for lev3="":$order(^tree(lev1,lev2,lev3)):"" do ... write ?10,lev3,! ... for lev4="":$order(^tree(lev1,lev2,lev3,lev4)):"" do .... write ?15,lev4,! Both programs produce output such as: 1 1 1 1 2 3 4 5 2 1 2 3 4 5 3 1 2 3 4 5 4 1 2 3 4 5 5 1 2 3 4 5 2 1 1 2 3 4 5 2 1 2 3 4 5 3 1 2 3 4 5 4 1 2 3 4 5 5 1 2 5 . . .

   In the example, the for loops initialize, increment and terminate the loops automatically. Each loop initializes its loop variable with the empty string, immediately runs the incrementing function, and tests the results for empty string. If the empty string is returned, the loop terminates. Otherwise, the loop body is executed. Notice that after initialization, the increment is done immediately thus providing the true initial value for the loop variable. This occurs only when a function replaces the increment position. Normally, in iterative loops, the loop is executed once with the initial value prior to adding the increment. There are other extended forms fo the for command. See the manual.

Operators

1. Arithmetic unary operators: + -

   The arithmetic unary operators are: + and -. The plus operator (+) has no effect other than to force the expression to its right to be interpreted as numeric. The minus operator forces numeric interpretation and negates the result. For example:

   set I="123 ELM STREET" write +I yields 123 write -I yields -123

2. Arithmetic binary operators: + - * / \ **

   The addition (+), subtraction (-), multiplication (*) and exponentiation (**) operators perform in the normal manner. Operands are given a numeric interpretation if necessary. Operands may be either expressions, constants, variables or array references. Results are computed in floating point if appropriate. Mumps has two division operators: full division (/) and integer division (\). Full division give results which may have fractional parts. Integer division truncates the answer to an integer.

   The modulo operator (#) gives the left operand modulo the right operand. The following are examples:

   2+3 yields 5 2.31+1 yields 3.31 3-5 yields -2 7/4 yields 1.75 7\4 yields 1 11#3 yields 2 (please see compiler notes) 3**2 yields 9

3. Arithmetic relational operators: > <

   The greater than (>) and less than (<) relational operators compare numbers. If the operands are not numbers, they are given a numeric interpretation. The result is either zero for FALSE or one for TRUE. For example:

   1>2 yields 0 2>1 yields 1 1<2 yields 1 2<1 yields 0

   Both operators may be negated producing not greater than ('>) and not less than ('<) (note: the single quote mark is the negating operator). There is no "less than or equals" or "greater than or equals" operators as such. For example:

   1'>2 yields 1 2'>1 yields 0 1'<2 yields 0 2'<1 yields 1

4. String binary operator: _

   The only binary string operator is concatenation (_) represented by an underscore character. The following are examples:

   "ABC"_"XYZ" yields "ABCXYZ" "ABC"_123 yields "ABC123" 123_456 yields 123456

5. String relational operators: = [ ] ]] ?

   The equals relational operator (= and '=) tests for equality as in the following example:

   if "ABC"="ABC" write "EQUALS" if "ABC"'="ABC" write "EQUALS"

   We would expect that "EQUALS" would be written to the terminal in the first case and not in the second. The not-equals operator is formed by the single quote mark and the equals sign. The equals and not-equals operator may be used with strings or numbers.

   The contains operator ([ and '[) determines if the right hand operand is contained in the left hand argument. For example:

   set A="NOW IS THE TIME" if A["THE" write "YES" if A'["THE" write "YES"

   The word "YES" would by printed on the terminal for the first example and not printed for the second.

   The follows and sorts after operators (] '] ]] and ']]) are used to test if the left hand operand follows the right hand operand in the collating sequence. For example:

   set A="ABC" if A]"AAA" write "YES" if A]]"AAA" write "YES" if A']"AAA" write "YES" if A']]"AAA" write "YES"

   The word "YES" would be printed at the terminal for the first two exmples and not printed for the second two.

   The pattern matching operator (? and '?) is used to determine if a string conforms to a certain pattern. Pattern match operations are converted to Perl Compatible Regular Expressions and are executed by functions in the PCRE library which must be present. You may access the PCRE directly, using Perl expression format with the ^perlmatch(string,pattern) function discussed in Appendix E.

   The Mumps patterns are:

   A for the entire upper and lower case alphabet. C for the 33 control characters. E for any of the 128 ASCII characters. L for the 26 lower case letters. N for the numerics P for the 33 punctuation characters. U for the 26 upper case characters. A literal string.

   A pattern code is made up of one or more of the above, each preceded by a count specifier. The count specifier indicates how many of the named item must be present. Alternatively, an indefinite specifier - a decimal point - may be used to indicate any count (including zero). For example:

   set A="123-45-6789" if A?3N1"-"2N1"-"4N write "OK" if A'?3N1"-"2N1"-"4N write "OK" set A="JONES, J. L." if A?.A1",".A write "OK" if A'?.A1",".A write "OK"

   Extensions to the pattern syntax suggested by the Mumps 95 standard, including support for alternation, are supported as described in Appendix D.

6. Logical operators: &, ! '

   The logical operators AND (&), OR (!) and NOT (') may be applied in the usual manner. The user should note, however, that since Mumps has strict left-to-right precedence, the results can sometimes be odd:

   1&1 yields 1 2&1 yields 1 1&0 yields 0 1&0<1 yields 1 1&(0<1) yields 1 1!1 yields 1 1!0 yields 1 0!0 yields 0 2!0 yields 1

   The "NOT" operator may be used in conjunction with other operators to form compound operators. The resulting compound operators are:

   '< not less than '> not greater than '= not equal '[ not contains '] not follows '? not pattern

7. The indirection operator: @

   The indirection operator permits direct interpretation of string expressions. For example:

   set a="2+2" write @a,!

   will result in the value "4" being written to the current output device.

Commands

Each statement in Mumps begins with a unique command word. Often the command word is abbreviated to a single character. The single character abbreviations are unique for all commands except those which begin with the letter "Z". For commands not beginning with the letter "Z", Mumps does not check the spelling of the command word if more than one character of the spelling is given. Generally speaking, only the first letter is used to determine the command. Thus "write", "W", and "WRIGHT" all have the same meaning.

The format of a command normally consists the command word or letter followed (optionally) by a post-conditional, followed by exactly one blank followed by the arguments to the command. Most commands can have multiple arguments. Multiple arguments are delimited by commas. If a line is to have more than one command, the first command is delimited by exactly one blank and the next command word or letter follows immediately. Blanks are very significant in Mumps.

As noted above, most commands may be "post-conditionalized". A post-conditional is a logical expression which is used to determine if the command (and all its arguments) should be executed. It is like a small "if" statement. A post-conditional appears as a colon followed by an expression. If the expression evaluates to 0 (false), the command (or argument) is not executed. If the expression evaluates non-zero, the command or argument is executed.

The following are examples of the above:

an ordinary assignment statement:

set I=10*5

same as above with command word abbreviation:

s I=10*5

an assignment statement with multiple arguments:

s I=10*5,J=5,K=I+J ;(K will equal 55)

an assignment statement post-conditionalized:

s:I=10 J=0 ;(set J to zero if I equals 10)

a multiple command line:

s I=10*5 s j=5 s S=I+J ;(same as above)

Table of Commands

1. break (abbreviation: b)

   Mumps usage is non-standard. It may be used to exit an indented block. It may not be used in any other context.

   For example:

   for i=1:1:10 Do . write i,! . if i>5 break

   The above will print 1 through 6. See Notes on break and quit for further details.

2. catch (abbreviation: ca)

   (compiler only) A catch command immediately follows a try command. If one of the commands on the try command line fails, the catch is entered if the cause of the failure is the exception noted in the argument to the catch command. The permitted arguments are:

   1. InputLengthException
   2. InterpreterException

   The try command may be followed by one or more optional control words. If no control words are present, the command MUST be followed by at least two blanks. The optional control words are:

   1. NoMessages

      Used when invoking the interpreter to suppress interpreter error message generation. If NoMessages is not present and there is an error detected during interpretation, the interpreter will generate specific error messages to stdout.

   Example:

   try read a catch InputLengthException write "line too long",! halt write a set a="2+2" try NoMessages write @a,! catch InterpreterException write "expression error",!

3. close (abbreviation: c

   The close command closes a unit number and makes it available for other uses. It also frees the system buffers for other uses. The argument must evaluate to a number which corresponds to an open unit. In Mumps this must be in the range of 1 to 4 (other values will terminate your program). An output file must be closed explicitly. Failure to do so may result in loss of some or all of the file. The close command may be post-conditionalized and it may have multiple arguments.

   close 4 close I close:K=J 1,2

4. continue (no abbreviation)

   See quit

5. declare (no abbreviation)

   The non-standard declare command can be used to improve speed by declaring Mumps variables as permanent variables in the C++ environment. A variable so declared, does not need to be looked-up in teh run-time symbol table each time it is used. This can significantly improve speed of execution. Only unsubscriped Mumps variables may be declareed. They may not be killed. Variables must be declared within the main program or a subroutine (i.e., not globally) and they have the scope of the entire routine in which they are declared. Declared variables may be passed to subroutines but a received parameter may not be declared in the scope of the receiving subroutine. Examples:

   zmain declare i,j,k for i=1:1:10 do . for j=1:1:10 do .. for k=1:1:10 do ... set ^a(i,j,k)=0

6. do (abbreviation: d)
   • The do command with an argument causes the program to branch to the label specified by the argument and continue execution beginning at that label. Execution proceeds until a quit command is encountered at which time execution returns to the invoking do. If an end of source file is encountered, it is interpreted as a halt command.
     • Interpreter only: The do may invoke disk resident, uncompiled, Mumps routines.

   • The do command may be post-conditionalized and its arguments may be post-conditionalized.

   • The argumentless do causes the code on the immediately following line to be executed. This line must be the beginning of a block with a level of dotted indent greater than that of the line containing the do. This block is terminated by a quit, a break or by encountering a line with a lower level of dotted indent. An argumentless do must be followed by two blanks (unless it is the last command on a line). It may be Post-Conditionalized.

   • Within an argumentless do block, a quit will return to the line containing the original do and resume execution of that line. A break will exit the block but resumes execution with the line following the block.

   • See the discussion on the effect of break and quit on blocks invoked by do commands.

   • do commands with arguments may be post-conditionalized at the argument level.

   • do with arguments:

     Arguments may have three forms:

     1. Names of labels local to the current routine, with or without parameters:

        zmain write "hello " do www write ! halt www write "world" quit --------------------------- zmain write "hello " do www("world") write ! halt www(a) write a quit --------------------------- zmain write "hello " write $$www("world"),! write ! halt www(a) quit a

        Each of the above writes "hello world" by executing a local subroutine. Note that invoking the routine as a function requires the "$$" while invoking it with a do does not include the "$$".

     2. Names of subroutines linked to the current executable module such as the following:

        ^www() write "world" quit zmain write "hello " do ^www write ! halt --------------------------- ^www(a) write a quit zmain write "hello " do ^www("world") write ! halt --------------------------- ^www(a) quit a zmain write "hello " write $$^www("world") write ! halt ---------------------------

        Note the empty open/close parentheses in the first example. These are required at present. For a thorough explanation of the meaning of "$$" and "^" before function labels, see the section on Functions .

     3. Name of other binary executables. These are other Mumps programs (although, the could be written in other languages if the conform to the calling conventions) and compiled to binary executables. All are assumed to have the ".cgi" extension:

        zmain write "hello " do ^pgm1 write ! halt where pgm1 is pgm1.cgi compiled from the following: zmain write "world" halt

        Programs invoked in this manner may not, at present, have parameters nor may they return values. They do, however, have all the variables and values from the calling program's symbol table available and any new variables the called program may create or any changes to existing variables will be reflected in the calling program's symbol table upon return. This method is relatively slow and should be used sparingly. It creates a separate shell, stores the current symbol table on disk (in a file whose name is the same as the calling program's process id), and invokes the program. The called program, upon invocation, loads the symbol table, executes, dumps the symbol table back to disk and terminates. The shell created terminates and control is returned to the calling program which loads the revised symbol table.

     The embedded interpreter will permit constructions of the form:

     do ^ABC that will cause the file "ABC" to be loaded and interpreter. This format for compiled code causes the execution of a separately compiled Mumps function.

     If the label following the do command begins with two circumflexes (^), a separately compiled C++ function is invoked. The function may be declared in the current file or in a separate file. Functions from separate files may be pre-compiled and linked. See the section on Functions If a separately compiled function has no arguments, the open and close parentheses are not required when invoked by do.

     A label of the form xxx^yyy may be used in the compiler for separately compiled functions. The xxx is interpreted as a label appearing in the routine yyy.

   • do without arguments: (see: Notes of break and quit for details)

     for i=1:1:10 do write " continuing" . write !,i . if i>5 quit . write " ",i write !,"done",! writes 1 1 continuing 2 2 continuing 3 3 continuing 4 4 continuing 5 5 continuing 6 continuing 7 continuing 8 continuing 9 continuing 10 continuing done ------------------------------------------ set i=9 if i>0 do write " continuing" . write !,i . if i>5 quit . write " ",i write !,"done",! writes: 9 continuing done ------------------------------------------ for i=1:1:10 do write " mark " do write " end of line",! . write i . if i>5 quit . write "X" writes: 1X mark 1X end of line 2X mark 2X end of line 3X mark 3X end of line 4X mark 4X end of line 5X mark 5X end of line 6 mark 6 end of line 7 mark 7 end of line 8 mark 8 end of line 9 mark 9 end of line 10 mark 10 end of line ------------------------------------------ for i=1:1:10 do write " continuing" . write !,i . if i>5 break . write " ",i write !,"done",! writes: 1 1 continuing 2 2 continuing 3 3 continuing 4 4 continuing 5 5 continuing 6 ------------------------------------------ set i=9 if i>0 do write " continuing" . write !,i . if i>5 break . write " ",i write !,"done",! writes: 9 done ------------------------------------------ for i=1:1:10 do write " mark " do write " end of line",! . write i . if i>5 break . write "X" write ! writes: 1X mark 1X end of line 2X mark 2X end of line 3X mark 3X end of line 4X mark 4X end of line 5X mark 5X end of line 6

7. else (abbreviation: e)

   The else command tests the value of the system wide built-in variable $test. If $test (abbreviated as $t) is zero, the remainder of the line on which the else appears is executed. If $t is not zero, the remainder of the line is not executed. $test is set, among other ways, by the if statement. Since else does not take arguments, it must be followed by two blanks.

   For example:

   else set i=10

   The else does not require a preceding if statement. It depends solely on the value of $test. See the discussion below on details as to how $test may be set.

8. export (abbreviation: ex)

   The export command exports the variables given as arguments to the next outer symbol table:

   ^tst(i,j) write "in subroutine ",$data(i)," ",$data(j)," ",$data(k),! set i=10,j=20,k=30 write "in subroutine ",i," ",j," ",k,! export k quit zmain write "in main",! set i=1,j=2,k=3 write "before call to subroutine ",i," ",j," ",k,! do ^tst(i,j) write "after call to subroutine ",i," ",j," ",k,! writes: in main before call to subroutine 1 2 3 in subroutine 1 1 0 in subroutine 10 20 30 after call to subroutine 1 2 30

9. for (abbreviation: f)

   Iterative loop command. Examples of the single line scope For:

   for i=1:1:10 write i,! // prints 1 through 10 on successive lines for i=10:-1:1 write i,! // prints 10 through 1 on successive lines for i=1:2:10 write i,! // prints 1, 3, 5, 7, and 9 on successive lines for i=1:1 write i,! quit:i>100 // no upper limit format set i=0 for set i=i+1 write i,! quit:i>100 // infinite loop format for i=1,4,6 write i,! // explicit values of index for i=2,5,10:1:20,30,100:1:105 write i,! // mixed formats - iterative and explicit for write "hello",! // write hello infinitely for i=$order(^a(i)) write i,! // writes all the indices of ^a() for i=2:$order(^a(i)):8 write i,! // writes indices of ^a() between 2 and 8

   If the for has no arguments (the "do forever" format), it must be followed by two blanks.

   Mumps Compiler non-standard extensions permit other forms of the for loop. The first of these, shown in the example below, permits a function to be executed for each iteration. In this format, the increment is replaced by a function call. The loop variable is initialized and, for each iteration, the function is invoked and its result is copied to the loop variable. The loop iterates until the value of the loop variable becomes the third argument or endlessly, if the third argument is omitted. The function is invoked immediately after initialization before the first iteration. Thus, the first value of the variable in the loop is not the initialized value but the result of the first function execution.

   zmain for i=1:1:10 s ^a(i)=i // initialize a global array e1 for i="":$order(^a(i)):"" write ^a(i),! // write all values of ^a() write ! kill ^a for i=1:1:3 for j=1:1:3 for k=1:1:3 set ^a(i,j,k)=i for a="^a(1)":$query(a):"" do . if $piece(a,"(",1)'="^a" break // $query() returns all globals . write a," -> " . write $qsubscript(a,0)," ",$qsubscript(a,1)," ",$qsubscript(a,2)," ",$qsubscript(a,3),! write ! for i="":$order(^a(i)):"" do . for j="":$order(^a(i,j)):"" do .. for k="":$order(^a(i,j,k)):"" do ... write i," ",j," ",k,! writes: 1 10 2 3 4 5 6 7 8 9 ^a("1","1","1") -> a 1 1 1 ^a("1","1","2") -> a 1 1 2 ^a("1","1","3") -> a 1 1 3 ^a("1","2","1") -> a 1 2 1 ^a("1","2","2") -> a 1 2 2 ^a("1","2","3") -> a 1 2 3 ^a("1","3","1") -> a 1 3 1 ^a("1","3","2") -> a 1 3 2 ^a("1","3","3") -> a 1 3 3 ^a("2","1","1") -> a 2 1 1 ^a("2","1","2") -> a 2 1 2 ^a("2","1","3") -> a 2 1 3 ^a("2","2","1") -> a 2 2 1 ^a("2","2","2") -> a 2 2 2 ^a("2","2","3") -> a 2 2 3 ^a("2","3","1") -> a 2 3 1 ^a("2","3","2") -> a 2 3 2 ^a("2","3","3") -> a 2 3 3 ^a("3","1","1") -> a 3 1 1 ^a("3","1","2") -> a 3 1 2 ^a("3","1","3") -> a 3 1 3 ^a("3","2","1") -> a 3 2 1 ^a("3","2","2") -> a 3 2 2 ^a("3","2","3") -> a 3 2 3 ^a("3","3","1") -> a 3 3 1 ^a("3","3","2") -> a 3 3 2 ^a("3","3","3") -> a 3 3 3 1 1 1 1 1 2 1 1 3 1 2 1 1 2 2 1 2 3 1 3 1 1 3 2 1 3 3 2 1 1 2 1 2 2 1 3 2 2 1 2 2 2 2 2 3 2 3 1 2 3 2 2 3 3 3 1 1 3 1 2 3 1 3 3 2 1 3 2 2 3 2 3 3 3 1 3 3 2 3 3 3

   Alternatively, other starting and ending values can be specified:

   for i="":$order(^a(i)):12 write ^a(i),! // writes values up to but not including 12 for i=2:$order(^a(i)):8 write ^a(i),! // writes values 3 through 7, inclusive

   Another format is:

   set i="" for i=$order(^a(i)) write ^a(i),! writes all level 1 values of ^a() global. do $zwi("this is a test string") for i=$zwn write i,! writes: this is a test string

   where the loop iterates so long as the value of the loop variable does not become zero or the empty string. The Function is invoked before each iteration, including the first. The first example iterates through all values fo the global array. The second example initializes the internal buffer with the string then extracts each word from the string until there are no more (returns an empty string).

   Note: the order of presentation of the indices is determined by the collating sequence in the above.

   Important Notes on break and quit

   • A quit in a single line for terminates processing of the for. If there are multiple for commands, it terminates the nearest:

     for i=1:1:10 write i,! if i>5 quit writes 1 through 6 only. for i=1:1:10 for j=1:1:10 write j,! if j>5 quit writes 1 through 6 ten times. for i=1:1:10 write i,! if i>5 break illegal - generates error message - break not allowed.

   • A break may NOT be used in a single line for command. It may ONLY be used in an indented block that was introduced by a do command.

   • In an indented block, quit and reak have special meanings:
     • A quit ends further processing of the block in which it appears and returns to the line containing the invoking do at a point just after the do. Processing of the line containing the invoking do resumes. If there are more commands on the line, they are executed.

     • A break ends further processing of the block in which it appears but does not return the line containing the invoking do. Instead, execution moves to the line following the block in which the do appears. Examples:

     for i=1:1:10 do write " continuing" . write !,i . if i>5 quit . write " ",i write !,"done",! writes 1 1 continuing 2 2 continuing 3 3 continuing 4 4 continuing 5 5 continuing 6 continuing 7 continuing 8 continuing 9 continuing 10 continuing done

     In this example, the block is invoked 10 times. After each invocation, the remainder of the line containing the for is executed producing the instances of the word "continuing". Each block invocation prints the value of "i". When the value of "i" is greater than 5, the block executes the quit command thus returning to the invoking line early. When the value if "i" is 5 or less, the full block is executed and return is made to the invoking line at block end. When the for command finishes execution, control is passed to the line following the for and "done" is printed.

     set i=9 if i>0 do write " continuing" . write !,i . if i>5 quit . write " ",i write !,"done",! writes: 9 continuing done

     In this example, the block is entered, the value of "i" is printed but, because "i" is greater than 5, the quit is executed and control is returned to the invoking do and the word "continuing" is printed. Now, the line being completely executed, control passes to the line following the block and "done" is printed.

     for i=1:1:10 do write " mark " do write " end of line",! . write i . if i>5 quit . write "X" writes: 1X mark 1X end of line 2X mark 2X end of line 3X mark 3X end of line 4X mark 4X end of line 5X mark 5X end of line 6 mark 6 end of line 7 mark 7 end of line 8 mark 8 end of line 9 mark 9 end of line 10 mark 10 end of line

     In this example, multiple do commands are shown. Note the two blanks following each. Each do invokes the block following the line containing the do

     On the other hand, the break command terminates the the block in which it is contained but execution does not return to the line containing the invoking do but, instead, continues with the line following the block:

     for i=1:1:10 do write " continuing" . write !,i . if i>5 break . write " ",i write !,"done",! writes: 1 1 continuing 2 2 continuing 3 3 continuing 4 4 continuing 5 5 continuing 6 --------------------------------------- set i=9 if i>0 do write " continuing" . write !,i . if i>5 break . write " ",i write !,"done",! writes: 9 done --------------------------------------- for i=1:1:10 do write " mark " do write " end of line",! . write i . if i>5 break . write "X" write ! writes: 1X mark 1X end of line 2X mark 2X end of line 3X mark 3X end of line 4X mark 4X end of line 5X mark 5X end of line 6

     In these examples, execution of the break can be seen to terminate the current block and move to the line following the block.

   • Note: the contents of $test revert to their former value when exiting an indented block by means of break or Mb>quit:

     if 1=1 do . write "test 1: ",$test,! . if 1=2 write "wow",! . else write "not wow",! . write "test 2: ",$test,! write "test 3: ",$test,! writes: test 1: 1 not wow test 2: 0 test 3: 1

     If you exit a block with a goto, the value of $test is not restored.

   see: Unsupported and Non-Standard Features

10. goto (abbreviation: g)

    The goto command causes unconditional transfer of control. In the compiler, local program labels and functions may be used. Variables are not permitted. Label names must not be the same as variable names. Both the command and each argument may be post-conditionalized. If you exit an indented block with a goto, the value of $test is not restored to its pre-block value.

    Permitted argument forms:

    goto label goto ^function

    The second example causes the current program to terminate and control to be passed to a different executable name "function.cgi". This is accomplished by an "execve()" system function. The symbol table is dumped prior to transfer and loaded by the target executable. Control is never returned to the invoking program except if the invoked program cannot be executed.

11. halt (abbreviation: h)

    The halt command terminates execution of the Mumps program and returns you to the operating system or web server. It may be post-conditionalized. For example:

    halt:I=3

12. hang (abbreviation: h)

    The hang instruction suspends execution of your program for a specified period of time (in seconds). It takes as an argument the number of seconds to wait. It may be post-conditionalized. The hang instruction differs from the halt instruction only in the argument: a hang without an argument is a halt instruction. For example:

    hang:I=J 2*K

13. html (abbreviation: html)

    The html command causes the remainder of the line to be treated as html code and sent to the standard output. The command may not be abbreviated. The remainder of the line is scanned first for embedded Mumps expressions which are replaced by their results:

    &! codes which will be replaced by line feeds (same as the ! in the write statement.

    &~expression~ codes whose expression will be evaluated and the result substituted for the entire code. Thus, assuming the Mumps variable ptid exists:

    html < center > Patient &~ptid~ < /center >

    The value of ptid will be substituted in to the line and the result will be sent to the standard output.

14. if (abbreviation: i)

    The if command permits conditional execution. The scope of the command is the remainder of the line unless there is an argumentless do command on the line. If one of the arguments to the if is false, execution procedes to the next line. Thus the following is in error:

    set i=2 if i=3 write "no",! else write "yes",!

    The else is NOT executed.

    Note that expressions are evaluated left to right. This sometimes causes problems for people used to dealing with other languages. For example, the expression:

    I=0&J<0

    is always false since it is parsed as: (((I=0)&J)<0)

    if I is zero, the first expression is true (value of 1); if J is less than zero, then J is interpreted as true giving, as a result of the AND operation (&), a value of 1 which is not less than zero - therefore false. If I is not zero then, regardless of the value of J, the AND operation results in false (value of zero) which is not less than zero - therefore false. The expression should have been written as:

    (I=0)&(J<0)

    The if commnad may be used with no arguments (requires 2 blanks after command word) or with multiple arguments separated by commas. If no arguments are given, the current value of $test is examined and, if true, the remainder of the line containing the if is executed. If multiple arguments are given, each is evaluated. If all are true, the remnainder of the line is executed. If an argument is not true, the remainder of the line including any unevaluated arguments are not executed and execution resumes on the next line.

    The if command sets $test: if the argument(s) is/are true, $test is set to true, false otherwise.

    An if command with single line scope may initially set $test to true, but a subsequent command on the same line may set it to false. Thus, on the following line, $test may be false even though the expression in the previous if was true (see example below).

    The value of $test is restored upon return from nested blocks except if those blocks are exited with a goto command.

    See the discussion on the effect of break and quit on blocks invoked by if commands.

    Examples:

    set i=1,j=2,k=3 if i=1 write "true",! // writes true if write "true",! // writes true if i=1,j=2,k=3 write "true",! // writes true if i=1,j=3,k=3 write "true",! // does not write true if i=1 do . write "true",! // writes true if i=1 if j=3 write "true",! // writes true write $test,! // writes 1 if i=1 if j=9 write "true",! // does not write true write $test,! // writes 0 if i=1 do . write "test 1 ",$test,! . if j=20 do .. write "test 2 ",$test,! . write "test 3 ",$test,! write "test 4 ",$test,! writes: test 1 1 test 3 0 test 4 1

15. job (abbreviation: j)

    The job command performs a fork(). The global arrays are not closed prior to the fork.

    If you are using the native globals, you must close them with the ZCLOSE command and reopen them in either the parent or child. Both processes may not open the globals concurrently. If both attempt to open the globals after the fork, one will pend until the other has closed the globals (zclose).

    With the Berkeley DB, both processes may access the globals and there is no need to close them prior to the job command.

16. kill (abbreviation: k)

    The kill command is used to prune the symbol table and to delete parts of the global arrays.

    There are three forms of the kill command: the first deletes all entries in the local (i.e., non-global) symbol table; the second deletes specific elements from the local symbol table or specific elements from the global arrays; and the third is used to delete all elements from the local symbol table except for certain named symbols. All forms may be post-conditionalized. The first form - delete the entire local symbol table - is denoted by the kill command alone:

    kill

    The second form appears as a list of references (note: indirection for the names is permitted):

    kill A,B,^G(1,2,33)

    The above would delete variables A, B and the global array node ^G(1,2,33). Note: if the global array node ^G(1,2,33) has descendants, they are also deleted. Also, if a local array node is deleted, any of its descendants are also deleted.

    The final form of the kill may be used to delete all elements from the local symbol table except for certain protected elements. It has the following format:

    kill (A,B(1,1),K)

    In the above, the local symbol table will be deleted except for variables A, B(1,1) and K. All other variables will be lost. Global array nodes may not be used in this form of the kill statement.

    Indirection is permitted.

17. lock (abbreviation: l)

    The lock command marks a portion of the data base for exclusive access for an individual user. A lock with no arguments frees all prior lock's. The locks are stored in a file named "Mumps.Locks" which is opened for exclusive access by the locking/unlocking job. The contents of the fill may be deleted to remove all locks.

    Examples:

    lock // removes all locks lock ^a(1) // locks ^a(1) and all children; lock +^a(1) // increment lock count for ^a(1) lock -^a(1) // decrement lock count for ^a(1) lock ^a(1):20 // lock ^a(20) with a 20 second timeout lock ^a(1),^b(1) // multiple locks

18. merge (abbreviation: m)

    The merge command copies from one array to another. At present, only global arrays may participate in the merge command. Examples:

    for i=1:1:9 for j=1:1:9 set ^a(i,j)=i+j merge ^c=^a // copies all of ^a to ^c for i=100:1:109 s ^b(i)=i merge ^b(103)=^a(3) // copies ^a(3) to ^b(103) and children of // ^a(3) to be children of ^b(103) merge ^d=^a(3) // creates ^d=^a(3); ^d(1)=^a(3,1),...

    Note: in code of the form "merge ^x(103)=^a(3)", ^x(103) does not exist if "^x(103)" did not previously exist and if "^a(3)" does not exist. In the above examples, there "^a(3)" does not exist (but it does have descendants).

19. new (abbreviation: n)

    The new command creates a new symbol table or namespace and pushes the old namespace onto a stack. The Mumps compiler implementation of new differs from the legacy standard Mumps. See also: export

    If new is used with no arguments, a new namespace is created, any previous namespaces are pushed-down and unique variable names from prior namespaces are instantiated with no values in the new namespace. Upon exit from the block in which the new was executed, the old namespace is restored and the contents of the new namespace are lost. A block is determined to be exited if you execute a quit from a section of code entered by a do without arguments or you revert to a lower level of dotted indent.

    A call to a separately compiled function results in an implied 'new'. A call to a local function with parameters also results in an impled 'new'. A call to a local function without parameters does not result in an implied 'new'. See the examples below.

    If you include an argument to new consisting of a parenthesized list of variable names, a new namespace will be created that contains instantiated copies, with no values, of the unique variable names from lower namespaces except those variables names in the parenthesized list.

    If you include one or more variable names as an argument, not enclosed in parentheses, new copies of these variables will be created. Upon exit, the old copies will be restored.

    At any given level, there may be only one new command.

    Examples:

    zmain # Example 1 'new' # 'new' creates a new symbol table and # pushes down the old table. The new table # is empty. Upon exit from th 'do' block, # the old table is restored and contents of # new symbol table are lost. set i=1,j=2,k=3 write "before ",i," ",j," ",k,! do . new . set i=100,j=200,k=300 . write "in block ",i," ",j," ",k,! write "after ",i," ",j," ",k,! # writes 1 2 3 # Example 2 'new exclusive' # 'new' creates a new symbol table and # pushes down the old table. Variable # 'i' is created in the new table along # with its contents. Otherwise, the new # table is empty. Upn block exit, the # contents of the new table are lost, # including any changes to 'i' and the # old table is restored along with the # old value of 'i'. set i=1,j=2,k=3 write "before ",i," ",j," ",k,! do . new (i) . set j=200,k=300 . write "in block ",i," ",j," ",k,! write "after ",i," ",j," ",k,! # writes: # before 1 2 3 # in block 1 200 300 # after 1 2 3 # Example 3 'new inclusive' # 'new' pushes down the old symbol table and # creates a new symbol table. The new table # contains all the contents of the old table # including an instance of 'i' which contains # the empty string. Since 'i' was in the old # symbol table, its previous value is not # visible. Upon exit from the block, the # old symbol table becomes visible with none # of the variables changed. No values are copied # to the old symbol table. set i=1,j=2,k=3 write "before ",i," ",j," ",k,! do . new i . write "in block ",i," ",j," ",k,! write "after ",i," ",j," ",k,! # writes: (value of 'i' in block is the empty string) # before 1 2 3 # in block 2 3 # after 1 2 3 halt # Example 4 - implied 'new' with separately compiled functions # A call to a separately compiled function results in an # implied 'new' for the function. The old symbol table is # restored on exit. ^tst(a,b) write "in subroutine ",$data(i)," ",$data(j)," ",$data(k),! set i=10,j=20,k=30 write "in subroutine ",i," ",j," ",k,! quit zmain write "in main",! set i=1,j=2,k=3 write "before call to subroutine ",i," ",j," ",k,! do ^tst(5,20) write "after call to subroutine ",i," ",j," ",k,! # writes: # in main # before call to subroutine 1 2 3 # in subroutine 0 0 0 # in subroutine 10 20 30 # after call to subroutine 1 2 3 # Example 5 - implied 'new' with call by reference. # Same as above except that changes to the arguments # passed by reference (.i,.j), are returned to the # calling symbol table. ^tst(i,j) write "in subroutine ",$data(i)," ",$data(j)," ",$data(k) set i=10,j=20,k=30 write "in subroutine ",i," ",j," ",k,! quit zmain write "in main",! set i=1,j=2,k=3 write "before call to subroutine ",i," ",j," ",k,! do ^tst(.i,.j) write "after call to subroutine ",i," ",j," ",k,! # writes: # in main # before call to subroutine 1 2 3 # in subroutine 1 1 0 # in subroutine 10 20 30 # after call to subroutine 10 20 3 # Example 6 - implied 'new' on local functions with parameters # If a local function (one without '^' at the beginning of its # name) is called, an impled 'new' is performed: zmain set i=10 set j=20 set k=30 write "main program: ",i," ",j," ",k,! do test(i,j,k) write "main program: ",i," ",j," ",k,! halt test(a,b,c) write "sub-program: ",a," ",b," ",c,! set a=11 set b=22 set c=33 quit # writes: # main program: 10 20 30 # sub-program: 10 20 30 # main program: 10 20 30 # Example 7 - implied 'new' on local functions with call by # reference: (similar to separately compiled functions above) zmain set i=10 set j=20 set k=30 write "main program: ",i," ",j," ",k,! do test(.i,.j,.k) write "main program: ",i," ",j," ",k,! halt test(a,b,c) write "sub-program: ",a," ",b," ",c,! set b=22 set c=33 quit # writes: # main program: 10 20 30 # sub-program: 10 20 30 # main program: 10 22 33 # Example 8 - no implied 'new' for local functions without parameters # A local function called without parameters shares the same symbol # table as the calling routine. All variables are available and any # changes are visible upon return: zmain set i=10 set j=20 set k=30 write "main program: ",i," ",j," ",k,! do test write "main program: ",i," ",j," ",k,! halt test write "sub-program: ",i," ",j," ",k,! set j=22 set k=33 quit # writes: # main program: 10 20 30 # sub-program: 10 20 30 # main program: 10 22 33

20. open (abbreviation: o)

    The open command opens sequential files and associates them with unit numbers. Opened files may be read or written. This implementation permits unit numbers 1 through 4 and 6 through 9 to be used by the programmer. Unit 5 is reserved for the normal user console (stdin and stdout). The open command takes a device number (either a number or an expression which evaluates to a number in the range of 1,2,3,4,6,7,8,9) and a file name. The file name must either be a variable name or a quoted literal. The file name consists of a valid file name followed by either ,new ,APPEND or ,OLD.

    If followed by ,new, the program assumes you are opening the file for output: any previous files with this name are lost You may only write to this file. If you open the file with the ,OLD option, the program assumes the file exists and opens it for input only (reads). If you specify ,APPEND, the file is opened for output with all new data written to the file appearing after the previously existing data. If an error takes place, $test is set to zero and the remainder of the command is not inspected. If no error takes place, $test will be one. The user should not attempt to reference units for which the open command returned a $test value of 0. For example:

    open 1:"data,old" open 1:"data,new" open 1:"data,append"

    You should be careful to close any file you have opened for output in order not to loose any of the file's contents. You must close an open unit number before re-using the unit number in another open command.

21. quit (abbreviation: q)

    The quit command provides an exit point for a FOR, xecute (interpreter only) and do commands. It may be post-conditionalized. It normally takes no arguments (therefore, you need two spaces after it if there are any commands following it on the same line). In the FOR case, the quit terminates the nearest loop. In the do case, the quit returns to the most recently invoking command. In the xecute case, execution of the xecute text is terminated and control is returned to the original command line. The continue is an alias for the quit

    Arguments are permitted for the quit command if the command is being used to return from a block invoked by a function. For example:

    Write $$abc,! . . . abc quit "test"

    The above will print "test".

    see: Notes on break and quit

22. read (abbreviation: r)

    The read command reads data into variables. It may be post-conditionalized. Ordinarily the read command reads from the user's terminal (unit number 5). The read command can be redirected to other devices and files, however, by use of the use command (see below). It is a common source of error - sometimes quite destructive errors - for the user to read or write to the wrong device. Many Mumps programmers explicitly place the use command immediately prior to the read or write commands. Ordinarily, the read command takes one or more arguments which may be local scalar variables, local array elements, or global array elements. Each of these is read successively from the input device. When more than one argument is present, a carriage return / line feed is taken as the delimiter between the successive input values. For example:

    read A,B,^A(1,3,99)

    If the input is derived from the user's terminal, the user might type the following sequence in response to the above:

    22 38 NOW IS THE TIME

    The read command may also write before it reads. This mode is only permitted at the user's console. The options permitted for "write before read" are: a literal constant in quotes; and a tab, new line, or new page operation. A tab operation is specified by a question mark followed by an expression which is interpreted as arithmetic. The effect is to cause the cursor to move to the named column on the page or screen. The new line operation is caused by typing an exclamation point (!). The program will generate a carriage return / line feed pair. A new page is induced by the pound-sign (#) character. For example, if you wish to read name, social security number and password with user input from column 20, the following might be appropriate:

    read "NAME",?20,N,"SSN",?20,S,"PASS",?20,P

    After the above, the variable N will contain the name, S the social security number and P the password.

    The read command also permits single character input. That is, a read operation will be satisfied as soon as the user strikes any character on the keyboard: no carriage return is required. The variable will contain a number which is the equivalent of the ASCII character struck. This mode is denoted by preceding the variable to be read by an asterisk. For example:

    read "ENTER A LETTER ",*A

    The read is satisfied when any character is struck. There is also another form of the read: that which contains "time-outs". Time-outs permit the programmer to specify a maximum interval of time which the program should wait for the user to reply to the read operation. The time-out may be used with either the regular or character by character mode. The time-out is specified by placing a colon after the variable followed by an expression which will be interpreted as numeric. The value of the expression is the amount of time in seconds to wait for a user response to this operation. If the user fails to respond in the required interval, the $test built-in variable is set false (0) and the variable contains nothing. If the user does respond in time, $test is set true (1) and the variable contains the user's reply. For non-character by character mode input, the user must type the carriage return for the input to be valid. If the time-out expires before the user type the carriage return, all input is lost. For example:

    AGAIN read "ENTER NAME ",N:20 if '$test goto AGAIN

    Multiple variables may receive the same value by enclosing them in parentheses. For example:

    read (a,^b(1),c)

    If the input is "999", each variable in the list, "a", "^b(1)" and "c", will receive the value "999".

23. set (abbreviation: s)

    The set command is the assignment command for Mumps. The expression to the right hand side of the equals sign is evaluated and placed in the storage associated with the variable on the left hand side. Global variables may be used on the left hand side. The set command may be post-conditionalized. The $piece function may be used on the left hand side of an expression. For example, if the variable a contains the value "aaa.bbb.ccc", the command:

    $p(a,".",2)="xxx"

    will result in the value of a becoming "aaa.xxx.ccc"

    Multiple values may be set at the same time in the compiler:

    set (i,^a(1),j,^a(2)=99

    The above will cause i,^a(1),j, and ^a(2) to be each set to the value 99. The $piece() function may not be used on any of the items in a multiple set.

24. try (abbreviation: t)

    (compiler only) The try command has as its scope the current line. The commands on the line are executed. If any of the commands throws an error, execution terminates and control is transferred to the catch command on the following line. If no errors are thrown, execution skips the catch command and resumes with the line following the catch. A try command MUST be followed immediately be a catch command. Neither the try nor catch commands may contain a do command. The try command takes optional control word arguments (see below). If none are present, it MUST be followed by at least two blanks. Example:

    try read a catch InputLengthException write "line too long",! halt write a

    The try command may be followed by one or more optional control words. If no control words are present, the command MUST be followed by at least two blanks. The optional control words are:

    1. NoMessages

       Used when invoking the interpreter to suppress interpreter error message generation. If NoMessages is not present and there is an error detected during interpretation, the interpreter will generate specific error messages to stdout.

    Example:

    try read a catch InputLengthException write "line too long",! halt write a set a="2+2" try NoMessages write @a,! catch InterpreterException write "expression error",!

25. use (abbreviation: u)

    The use command tells the program which device (unit) number to use for input output operations (reads and writes). The unit designated as the input/output device remains in effect until changed by the use again or an error occurs. If the program detects an error it always resets the the current device number to 5 - the number associated with the user's console terminal. The valid range of unit numbers in Mumps is 1 through 5. The current unit number can be determined from the $IO (abbreviation: $I) built-in variable. The command is specified as the letter U or the word use followed by an expression which is interpreted as numeric. For example:

    use 1

26. view (abbreviation: v)

    The view command is not used in this implementation.

27. write (abbreviation: w)

    The write command transmits data to an output device or file. Output goes to the file or device associated with the current unit number (see $io). Normally output is directed to the user's console terminal ($io=5, stdout). By the use command, however, data may be directed to another unit number and its associated file. All unit numbers other than unit 5 must be opened prior to use (unit number 5 is already open when the program begins and may not be otherwise opened). The write command takes as arguments either literals in quotes, numeric constants, variable names, both local and global, and control codes and expressions for tab, new line and new page operations. The control operations are the same as those discussed above for the read operation. Output is stream oriented: that is, each write does not begin on a new line: it begins where the last line left off. Wrap-around occurs at your terminal depending upon the current terminal monitor level width setting. You may specify single character output by an asterisk followed by a decimal number. The system will send the ASCII character associated with the number you specify (e.g., *7 will send the BELL character). For example:

    write "Name of Patient",?25,name write !,"Age",?20,age write *65,*66,*67,! set i="10*2" write @i

28. Xecute (abbreviation: x)

    The xecute command permits execution of strings as though there had been lines of code. In the Mumps Compiler, xecute is performed by a resident interpreter. Interpretation should be avoided, if possible, as it is considerably slower than direct execution of compiled code. At present, the xecute may not be followed by another command on the same line.

    Examples:

    set test="for i=1:1:20 write i,!" xecute test

    The numbers 1 through 20 will be written to the current output device.

29. Z (abbreviation: z)

    The Z in ANSI Mumps permits the implementor to add special commands. The Mumps Compiler does not support Z type commands of other vendors.

    zclose - Close the global array files. Causes all internal buffers to be written. Globals will automatically be re-opened if a reference to a global is subsequently made.
    • zexit - Indicates end of Mumps code section. If your program consists of one or more Mumps routines followed by one or more C++ functions, you must place a zexit command at the end of the last Mumps routine. The zexit command causes the final Mumps epilogue to be written. If this is not done, the following C++ functions will be interpreted, erroneously, as part of the last Mumps routine.

    • zmain - The zmain command is used to introduce the main program to the compiler. It is discussed in detail below. It and the remainder of the line on which it appears are ignored by Mumps programs.

Builtin Functions

1. $ascii(e1) or $ascii(e1,i2)

   $ascii returns the numeric value of an ASCII character. The string is specified in e1. If no i2 is specified, the first character of e1 is used. If i2 is specified, the i2'th character of e1 is chosen. For example:

   $ascii("ABC") YIELDS 65 $ascii("ABC",1) YIELDS 65 $ascii("ABC,2) YIELDS 66 $ascii("") YIELDS -1

2. Special Text Functions

   The following builtin functions are compiled from the MDH Toolkit. They are compiled C++ functions that can be called directly from Mumps. Builtin functions can be added to the MDH package by modifying builtins.cpp and mumpsc/builtin.h.

   When invoked as Mumps functions, use the $zz... or $z... format. This is required ifn you are using the interpreter. If you are using the compiler, you may use either the $zz... and $z... format or the slightly faster compiler interface to the same functions.

   For the compiler interface, if invoked as functions with return values, each name is preceded by "$$^". If invoked by the do command, each name is preceded by the "^" only.

   For both forms, parameters are specified in the same manner. For example, the $zzCosine() and ^Cosine() functions, both of which return an answer, can be invoked with:

   set c=$zzCosine(^A,^B)
   set c=$$^Cosine(^A,^B)

   The builtin functions include:

   1. Document Similarity Functions

      $zzCosine(gbl1,gbl2) or ^Cosine(gbl1,gbl2)

      $zzSim1(gbl1,gbl2) or ^Sim1(gbl1,gbl2)

      $zzDice(gbl1,gbl2) or ^Dice(gbl1,gbl2)

      $zzJaccard(gbl1,gbl2) or ^Jaccard(gbl1,gbl2)

      Computes the Cosine/Sim1/Dice/Jaccard similarity coefficient between first and second arguments. Both arguments are numeric global array vectors. For example:

      zmain kill ^A kill ^B set ^A("1")=3 set ^A("2")=2 set ^A("3")=1 set ^A("4")=0 set ^A("5")=0 set ^A("6")=0 set ^A("7")=1 set ^A("8")=1 set ^B("1")=1 set ^B("2")=1 set ^B("3")=1 set ^B("4")=0 set ^B("5")=0 set ^B("6")=1 set ^B("7")=0 set ^B("8")=0 write "Cosine=",$zzCosine(^A,^B),! write "Sim1=",$zzSim1(^A,^B),! write "Dice=",$zzDice(^A,^B),! write "Jaccard=",$zzJaccard(^A,^B),! Output: Cosine=0.75 Sim1=6 Dice=1 Jaccard=1

   2. $zzAvg(vector) or ^Avg(gbl_vector)

      Computes and returns the average of the numeric values in the vector. For example:

      zmain for i=1:1:10 set ^a(99,i)=i set i=$zzAvg(^a(99)) write "average=",i,!

      The above writes 5.5

   3. $zzBMGSearch(arg1,arg2) or ^BMGSearch(arg1,arg2)

      Boyer-Moore-Gosper Function - returns the number of non-overlapping occurrences of arg1 in arg2. These functions, wer obtained from ftp://ftp.uu.net/usenet/comp.sources.unix/volume5/bmgsubs.Z were written by Jeffrey Mogul (Stanford University), based on code written by James A. Woods (NASA Ames) and are believed to be in the public domain.

      zmain write $zBMGSearch("now","now is the now of the now in the know "),! writes: 4

   4. $zzCentroid(gblMatrix,gblRef) or ^Centroid(gblMatrix,gblRef)

      A centroid vector gblRef is calculated for the invoking two dimensional global array gblMatrix. The centroid vector is the average value for each for each column of the matrix. Any previous contents of the global array named to receive the centroid vector are lost. The global array gblMatrix must contain at least two dimensions. For example:

      zmain for i=0:1:10 do . for j=1:1:10 do .. set ^A(i,j)=5 set %=$zzCentroid(^A,^B) for i=1:1:10 write ^B(i),! writes: 5 5 5 5 5 5 5 5 5 5

   5. $zzCount(gblVector) or ^Count(gblVector)

      Computes and returns the number of numeric values in the vector. For example:

      zmain kill ^a for i=1:1:10 set ^a(99,i)=i set i=$zzCount(^a(99)) write "count=",i,!

      The above writes 10

   6. $zzScan([maxLen]), $zzScanAlnum([maxLen]), ^Scan() or ^ScanAlnum()

      Returns the next word in the current input stream delimited by white space. Words are restricted to a maximum length of 1023. For ^ScanAlnum(): words beginning with one or more digits are ignored although words containing digits other than in the first position are returned; and, by default (see below), words shorter than 3 characters or longer than 25 characters are ignored. Words returned by ^Scan() may contain any printable ASCII character. ^Scan() returns all characters in input words delimited by 'whitespace' without any conversion to lower case. Words returned by ^ScanAlnum() will contain only lower case alphabetic and numeric characters. ^ScanAlnum() converts upper case characters to lower case. Both functions will advance to additional lines as needed. If a word exceeds 1023 bytes, the results are undefined. When there are no more input words, an empty string is returned and $test is set to false. If only part of a line is scanned as a result of ^Scan() or ^ScanAlnum(), a subsequent 'read' command will begin at the white space following the last word read by ^Scan() or ^ScanAlnum().

      The default word size limits for ^ScanAlnum() may be changed by including embedded C++ code prior to invoking ^ScanAlnum(). If you change the limits, they remain changed until the program ends or you change them again and the change effects all calls to ^ScanAlnum() regardless of whether in the current or some other subroutine. See example below. Either or both word limits may be changed. If the limits are less than zero or greater than 1023, respectively, a NumericRangeException() will be thrown. Note: for interpreter execution, you must modify the interpreter driver "mumps.mps" and add the embedded C++ code prior to the interpreter being invoked.

      $zzScan and $zzScanAlnum work the same except each may take an optional argument specifying the maximum length word to be returned.

      Note: if scanning input from 'stdin' (i/o unit 5), you signal end of file by a control-d (control-z on DOS) on a separate line by itself.

      For the input line: now -- __ ?? !@#$%^&*()_+= IS 2for the time for zmain for set i=$zzScan quit:'$test write i,! writes: now -- __ ?? !@#$%^&*()_+= IS 2for the time for for set i=$zzScanAlnum() quit:'$test write i,! writes: now the time for To alter the scan word size limits, include C++ lines such as the following: + svPtr->ScanMinWordSize=5; + svPtr->ScanMaxWordSize=10; zmain for set i=$$^ScanAlnum() quit:'$test write i,! on input: a aa aaa aaaa aaaaa aaaaaa aaaaaaa aaaaaaaa aaaaaaaaa aaaaaaaaaa aaaaaaaaaaa writes: aaaaa aaaaaa aaaaaaa aaaaaaaa aaaaaaaaa aaaaaaaaaa loop based example: zmain for i=$$^ScanAlnum() do . write i,! writes: now the time for

   7. $zzMax(gbl) or ^Max(gbl_vector)

      Computes and returns the maximum numeric value in the vector. For example:

      zmain for i=1:1:10 set ^a(99,i)=$r(100) set i=$zzMax(^a(99)) write "max=",i,!

      The above writes the largest value.

   8. $zzMin(gbl) or ^Min(gbl)

      Computes and returns the minumum numeric value in the vector. For example:

      zmain for i=1:1:10 set ^a(99,i)=i set i=$zzMin(^a(99)) write "min=",i,!

      The above writes 1.

   9. $zzMultiply(gbl1,gbl2,gbl3) or ^Multiply(gbl_matrix1,gbl_matrix2,gbl_matrix3)

      Multiplies the first and second matrix leaving the result in the third. For example:

      zmain set ^d("1","1")=2 set ^d("1","2")=3 set ^d("2","1")=1 set ^d("2","2")=-1 set ^d("3","2")=0 set ^d("3","2")=4 set ^e("1","1")=5 set ^e("1","2")=-2 set ^e("1","3")=4 set ^e("1","4")=7 set ^e("2","1")=-6 set ^e("2","2")=1 set ^e("2","3")=-3 set ^e("2","4")=0 set %=$zzMultiply(^d,^e,^f) for i="":$order(^f(i)):"" do . for j="":$order(^f(i,j)):"" do .. write i," ",j," ",^f(i,j),! writes: 1 1 -8 1 2 -1 1 3 -1 1 4 14 2 1 11 2 2 -3 2 3 7 2 4 7 3 1 -24 3 2 4 3 3 -12 3 4 0

   10. $zPerlMatch(string,pattern) or ^perlmatch(string,pattern)

       Applies the Perl pattern to string and returns 1 if the pattern fits and 0 otherwise. The perlmatch function has the side effect of creating variables in the local symbol table to hold backreferences, the equivalent concept of $1, $2, $3, ... in Perl. Up to nine backreferences are currently supported, and can be accessed through the same naming scheme as Perl ($1 through $9). These variables remain defined up to a subsequent call to perlmatch, at which point they are replaced by the backreferences captured from that invocation. Undefined backreferences are cleared between invocations; that is, if a match operation captured five backreferences, then $6 through $9 will contain the null string. See here for further details. Example:

       zmain write "Please enter a telephone number:",! read phonenum if $zperlmatch(phonenum,"^(1-)?(\(?\d{3}\)?)?(-| )?\d{3}-?\d{4}$") do . write "+++ This looks like a phone number.",! . write "The area code is: ",$2,! else do . write "--- This didn't look like a phone number.",! writes: Please enter a telephone number: (123) 456-7890 +++ This looks like a phone number. The area code is: (123) zmain write "Please enter a telephone number:",! read phonenum if $zPerlMatch(phonenum,"^(1-)?(\(?\d{3}\)?)?(-| )?\d{3}-?\d{4}$") do . write "+++ This looks like a phone number.",! . write "The area code is: ",$2,! else do . write "--- This didn't look like a phone number.",! writes: Please enter a telephone number: (123) 456-7890 +++ This looks like a phone number.

   11. $zReplace(string,pattern,replacement) or ^Replace(string,pattern,replacement)

       The regular expression in pattern is evalueted on string and, if there is a match, the matching section is replaced by replacement. Example:

       zmain set a="now is the time for all" set a=$$^Replace(a,"is","IS") write a,! set a="[[now is the time]]" if $zperlmatch(a,"(\[\[)(.*)(\]\])") do . set a=$$^Replace(a,$2,"ABC") . write a,! writes: now IS the time for all [[ABC]] zmain set a="now is the time for all" set a=$zReplace(a,"is","IS") write a,! set a="[[now is the time]]" if $zperlmatch(a,"(\[\[)(.*)(\]\])") do . set a=$zReplace(a,$2,"ABC") . write a,! writes: now IS the time for all [[ABC]]

       In the first part, the word 'is' is replaced by 'IS'. In the second part, a match is sought for any content between two sets of matching brackets ([[...]]). The matched section is in back reference $2. This is then used as a pattern to be replaced.

   12. $zzSum(gblVector) or ^Sum(gblVector)

       Computes and returns the sum of the numeric values in the vector. For example:

       zmain for i=1:1:10 set ^a(99,i)=i set i=$zzSum(^a(99)) write "sum=",i,!

       The above writes 55.

   13. $zzTranspose(gblMatrix1,gblMatrix2) or ^Transpose(gbl_matrix1,gbl_matrix2)

       Transposes the first global array matrix leaving the result in the second. For example:

       zmain kill ^f set ^d("1","1")=2 set ^d("1","2")=3 set ^d("2","1")=4 set ^d("2","2")=0 set %=$zzTranspose(^d,^f) for i="":$order(^f(i)):"" do . for j="":$order(^f(i,j)):"" do .. write i," ",j," ",^f(i,j),! yields: 1 1 2 1 2 4 2 1 3 2 2 0

   14. $zShred(a1,a2) or ^Shred(arg1,size)
       $zShredQuery(a1,a2) or ^ShredQuery(arg1,size)

       The ^Shred() function shreds the input string arg1 into fragments of length size upon successive calls. The function returns a string of length zero when there are no more fragments of length size remaining (thus, short fragements at the end of a string are not returned). ^Shred() copies the input string to an internal buffer upon the first call. Subsequent calls retrieve from this buffer. When the buffer is consumed, the fuction will copy the contents of the next string submitted to the buffer. Example:

       zmain set a="now is the time for all good men to come to the aid of the party" for do . set j=$zShred(a,5) . if j="" break . write j,! writes: nowis theti mefor allgo odmen tocom etoth eaido fthep

       The ^ShredQuery() function shreds size shifted copies of the input string arg1 into fragments of length size upon successive calls. That is, the function first returns all the size fragments of the string in the same manner as ^Shred(). However, it then shifts the starting point of the input string to the right by one and returns all the size length fragments relative to the shifted starting point. It repeats this process a total of size times.

       The function returns a string of length zero when there are no more fragments of length size remaining (thus, short fragements at the end of a string are not returned). ^ShredQuery() initially copies the input string to an internal buffer upon the first call. Subsequent calls retrieve from this buffer. When the buffer is consumed, the fuction will copy the contents of the next string submitted to the buffer. Example:

       zmain set a="now is the time for all good men to come to the aid of the party" for do . set j=$zShredQuery(a,5) . if j="" break . write j,! writes: nowis theti mefor allgo odmen tocom etoth eaido fthep owist hetim efora llgoo dment ocome tothe aidof thepa wisth etime foral lgood mento comet othea idoft hepar isthe timef orall goodm entoc ometo theai dofth epart isthe timef orall goodm entoc ometo theai dofth epart

   15. $zSmithWaterman(str1,str2,ShowAligns,ShowMat,Gap,MisMatch,Match) or ^SmithWaterman(str1,str2,ShowAligns,ShowMat,Gap,MisMatch,Match)

       Computes the Smith Waterman score between two strings. Result returned is the highest alignment score achieved. String lengths are limited by STR_MAX in the interpreter. If you compare very long strings (>100,000 character), you may exceed stack space. This can be increased under Linux with the command:

       ulimit -s unlimited

       For example:

       zmain set s1="now is the time" set s2="now i th time" set i=$zSmithWaterman(s1,s2,1,0,-1,-1,2) write "score=",i,! yields: 1 now- is the time 16 ::: :: ::: ::::: 1 now i- th time 16 score=23

       Parameters:

       If "show_aligns" is zero, no printout of alignments is produced. If "show_aligns" is not zero, a summary of the alternative alignments will be printed.

       If "show_mat" is zero, intermediate matrices will not be printed.

       The parameters "gap", "mismatch" and "match" are the gap and mismatch penalties (negative integers) and the match reward (a positive integer).

       If insufficient memory is available, a segmentation violation will be raised. Try increasing the stack size (see above).

   16. $zzIDF(global,doccount) or ^IDF(gbl_ref,docCount)
       

       Calculates the Inverse Document Frequency score of words in the gbl_ref vector. The paramater docCount is the total number of documents. Each element of the gbl_ref vector contains the number of times the term (the index value for this element) occurs in the collection. See http://www.cs.uni.edu/~okane/source/ISR/isr.html for further details. For example:

       zmain set ^a("now")=2 set ^a("is")=5 set ^a("the")=6 set ^a("time")=3 set j=4 set %=$zzIDF(^a,j) for i="":$order(^a(i)):"" write i," ",^a(i),! writes: is 0.7 now 2.0 the 0.4 time 1.4

   17. $zzTermCorrelate(a1,a3) or ^TermCorrelate(gbl_ref1,gbl_ref_2)

       Calculates the Term-Term co-occurence matrix (gbl_ref2) for The Document-Term matrix in gbl_ref1.

       A Term-Term matrix has terms (words) as the indices of its rows and columns. A Term-Term matrix gives, for each position, the degree to which the term corresponding to the row is similar to the term corresponding to the column. The diagonal, which is the degree a term is related to itself, is ignored.

       A Document-Document matrix has document id's as its row and column indices. A cell in the matrix indicates the degree to which the row document is related to the column document. The diagonal is ignored.

       In both the doc-doc and term-term matrices, the upper and lower diagonal matrices are mirror images of one another. For example:

       zmain kill ^A,^B set ^A("1","computer")=5 set ^A("1","data")=2 set ^A("1","program")=6 set ^A("1","disk")=3 set ^A("1","laptop")=7 set ^A("1","monitor")=1 set ^A("2","computer")=5 set ^A("2","printer")=2 set ^A("2","program")=6 set ^A("2","memory")=3 set ^A("2","laptop")=7 set ^A("2","language")=1 set ^A("3","computer")=5 set ^A("3","printer")=2 set ^A("3","disk")=6 set ^A("3","memory")=3 set ^A("3","laptop")=7 set ^A("3","USB")=1 set %=$zzTermCorrelate(^A,^B) for i="":$order(^B(i)):"" do . write i,! . for j="":$order(^B(i,j)):"" do .. write ?10,j," ",^B(i,j),! writes: USB computer 1 disk 1 laptop 1 memory 1 printer 1 computer USB 1 data 1 disk 2 language 1 laptop 3 memory 2 monitor 1 printer 2 program 2 data computer 1 disk 1 laptop 1 monitor 1 program 1 disk USB 1 computer 1 data 1 laptop 2 memory 1 monitor 1 printer 1 program 1 language computer 1 laptop 1 memory 1 printer 1 program 1 laptop USB 1 computer 1 data 1 disk 1 language 1 memory 2 monitor 1 printer 2 program 2 memory USB 1 computer 1 disk 1 language 1 laptop 1 printer 2 program 1 monitor computer 1 data 1 disk 1 laptop 1 program 1 printer USB 1 computer 1 disk 1 language 1 laptop 1 memory 1 program 1 program computer 1 data 1 disk 1 language 1 laptop 1 memory 1 monitor 1 printer 1

   18. $zzDocCorrelate(gbl_ref1,gbl_ref_2,method,threshold)
       ^DocCorrelate(gbl_ref1,gbl_ref_2,method,threshold)

       The square Document-Document matrix gbl_ref2 is calculated from the Document-Term matrix gbl_ref1 according to method (Cosine, Sim1, Dice, Jaccard). Elements inf the Document-Document matrix must exceed threshold.

       A Document-Document matrix has document id's as its row and column indices. A cell in the matrix indicates the degree to which the row document is related to the column document. The diagonal is ignored. For example:

       zmain kill ^A,^B set ^A("1","computer")=5 set ^A("1","data")=2 set ^A("1","program")=6 set ^A("1","disk")=3 set ^A("1","laptop")=7 set ^A("1","monitor")=1 set ^A("2","computer")=5 set ^A("2","printer")=2 set ^A("2","program")=6 set ^A("2","memory")=3 set ^A("2","laptop")=7 set ^A("2","language")=1 set ^A("3","computer")=5 set ^A("3","printer")=2 set ^A("3","disk")=6 set ^A("3","memory")=3 set ^A("3","laptop")=7 set ^A("3","USB")=1 set %=$zzDocCorrelate(^A,^B,"Cosine",.5) for i="":$order(^B(i)):"" do . write i,! . for j="":$order(^B(i,j)):"" do .. write ?10,j," ",^B(i,j),! which writes: 1 2 0.887096774193548 3 0.741935483870968 2 1 0.887096774193548 3 0.701612903225806 3 1 0.741935483870968 2 0.701612903225806

   19. $zStopInit(arg)
       ^StopInit(file_name)
       $zStopLookup(word)
       ^StopLookup(word)
       ^SynInit(file_name)
       $zSynInit(fileName)
       ^SynLookup(word)
       $zSynLookup(word)

       A call to ^StopInit(file_name)/$zStopInit(file_name) will open and load file_name of stopwords into a C++ container. The file should consist of one word per line. If the file cannot be opened or there is insufficient memory to hold the list of words, the program will halt with an error message. ^StopInit()/$zStopInit() convert all words to lower case. A call to ^StopLookup(word)/$zStopLookup(word) will return 1 if word is in the stoplist, 0 otherwise. Words presented to ^StopLookup(word)/$zStopLookup(word) should be in lower case. ^SynInit opens a synonym file. The file should consist of two or more words separated by one blank from one another. The first word on each line will be returned if any of the remaining words are sought by ^SynLookup. For example:

       zmain set %=$zStopInit("stop") if $zStopLookup("and") write "yes",! set %=$zSynInit("synonyms") write $zSynLookup("compressions"),! writes: yes compression

3. $char(i1) or $char(i1,i2) or $char(i1,i2,...)

   $char translates numeric arguments to ASCII character strings. Numeric values greater that 128 will generate errors. For example:

   $char(65) yields "A" $char(65,66) yields "AB"

4. $data(vn)

   $data returns an integer which indicates whether the variable vn is defined. The value returned is 0 if vn is undefined, 1 if vn is defined and has no associated array descendants; 10 if vn is defined but has no associated value (but does have descendants); and 11 is vn is defined and has descendants. The argument vn may be either a local or global variable. For example:

   set A(1,11)="foo" set A(1,11,21)="bar" $data(A(1)) ; yields 10 $data(A(1,11)) ; yields 11 $data(A(1,11,21)) ; yields 1

   $get(i1) or $get(i1,i2)

   Returns the value of the local variable specified as the first operand or a default value, specified as the second operand. If the second operand is omitted, an empty string is the default value.

5. $extract(e1,i2) or $extract(e1,i2,i3)

   $extract returns a substring of the first argument. The substring begins at the position noted by the second operand. If the third operand is omitted, the substring consists only of the i2'th character of e1. If the third argument is present, the substring begins at position i2 and ends at position i3. Note that this differs from the usual SUBSTR function in PL/I. If only "e1" is given, the function returns the first character of the string "e1". If i3 specifies a position beyond the end of e1, the substring ends at the end of e1. For example:

   $extract("ABC",2) YIELDS "B" $extract("ABCDEF",3,5) YIELDS "CDE"

6. $find(e1,e2) or $find(e1,e2,i3)

   $find searches the first argument for an occurrence of the second argument. If one is found, the value returned is one greater than the end position of the second argument in the first argument. If i3 is specified, the search begins at position i3 in argument 1. If the second argument is not found, the value returned is 0. For example:

   $find("ABC","B") YIELDS 3 $find("ABCABC","A",3) YIELDS 5

7. $justify(e1,i2) or $justify(e1,i2,i3)

   $justify right justifies the first argument in a string field whose length is given by the second argument. In the two operand form, the first argument is interpreted as a string. In the three argument form, the first argument is right justified in a filed whose length is given by the second argument with i3 decimal places. The three argument form imposes a numeric interpretation upon the first argument. For example:

   $justify(39,3) YIELDS " 39" $justify("TEST",7) YIELDS " TEST" $justify(39,4,1) YIELDS "39.0"

8. $len(e1) or $len(e1,e2)

   The $len function returns the string length of its argument. For example:

   $len("ABC") YIELDS 3 $len(22.5) YIELDS 4

   If a second argument is given, the function returns the number of non-overlapping occurrences of "e2" in "e1" plus 1.

9. $name(vn[,count])

   The $name function returns the evaluated name of a variable with all or some of its subscripts. For example:

   set a=1,b=2,c=3,d=4 set x(1,2,3,4)=99 write $name(x(a,b,c,d),! write $name(x(a,b,c,d),99),! write $name(x(a,b,c,d),4),! write $name(x(a,b,c,d),3),! write $name(x(a,b,c,d),2),! write $name(x(a,b,c,d),1),! write $name(x(a,b,c,d),0),! will write: x(1,2,3,4) x(1,2,3,4) x(1,2,3,4) x(1,2,3) x(1,2) x(1) x

10. $order(vn[,d])

    The $order() function traverses an array from one sibling node to the next in key ascending or descending order. The result returned is the next value of the last index of the global or local array given as the first argument. The default traversal is in key ascending order except if the option second argument is present and it evaluates to "-1" in which case the traversal is in descending key order. If the second argument is present and has a value of "1", the traversal will be in ascending key order. Numeric indices are stored in ASCII collating sequence order.

    Examples: zmain for i=1:1:9 s ^a(i)=i set ^b(1)=1 set ^b(2)=-1 write "expect (next higher) 1 ",$order(^a("")),! write "expect (next lower) 9 ",$order(^a(""),-1),! write "expect 1 ",$order(^a(""),^b(1)),! write "expect 9 ",$order(^a(""),^b(2)),! set i=0,j=1 write "expect 1 ",$order(^a(""),j),! write "expect 9 ",$order(^a(""),-j),! write "expect 1 ",$order(^a(""),i+j),! write "expect 9 ",$order(^a(""),i-j),! set i="" write "expect 1 2 3 ... 9",! for do . set i=$order(^a(i),1) . if i="" break . write i,! set i="" write "expect 9 8 7 ... 1",! for do . set i=$order(^a(i),-1) . if i="" break . write i,!

11. $piece(e1,e2,i3) or $piece(e1,e2,i3,i4)

    The $piece function returns a substring of the first argument delimited by the instances of the second argument. The substring returned in the three argument case is that substring of the first argument that lies between the i3'th minus one and i3'th occurrence of the second argument. In the four argument form, the string returned is that substring of the first argument delimited by the i3'th minus one instance of the second argument and the i4'th instance of the second argument. If only two arguments are given, i3 is assumed to be 1. For example:

    $piece("A.BX.Y",".",2) YIELDS "BX" $piece("A.BX.Y",".",1) YIELDS "A" $piece("A.BX.Y",".",2,3) YIELDS "BX.Y"

    $piece can be used on the left hand side of a set command or as an argument in a read command. In these cases, the first argument must be a local or global variable. The contents of this variable are altered to the value of the right hand side of the set statement or the value read by the read statement. The entire contents of the local or global variable are not altered, only the part which would have been extracted by the $piece function.

12. $qlength(e1)

    Returns the number of subscripts in the variable name. Examples:

    set i=1,j=2,k=3 set b(1)=99 w $ql("^a(i,j,k)"),! w $ql("^a(i,j,k)"),! w $ql("a(b(1),2)"),! write $ql("^a"),! the above write 3, 3, 2, and 0, respectively.

13. $qsubscript(e1,e2)

    The $qsubscript function returns a portion of the array reference. Examples:

    set i=1,j=2,k=3 write $qsubscript("^a(i,j,k)",-1),! write $qsubscript("^a(i,j,k)",0),! write $qsubscript("^a(i,j,k)",1),! write $qsubscript("^a(i,j,k)",2),! write $qsubscript("^a(i,j,k)",3),!

    The above prints the empty string (environements are not defined in this implementation), ^a, 1, 2, and 3 respectively. Note: the variables or values of the subscripts must be valid.

14. $query(e1[,c])

    The $query() function returns the next array element in the collating sequence. $query() takes a string as an argument rather than an actual global variable as is the case in the legacy Mumps standard. Return value: the next ascending entry in the global array data base. Index values in the returned string are normally quoted unless a second argument is given (see below). An empty string is returned when there are no more global arrays to return. If a second argument is given, its value replaces the quotes surrounding the returned index values. Note: this version of $query() returns the alphabetically next global in the global array file or the empty string. This means that when the elements of one global have all been returned, the elements of the next global will begin or the empty string will be returned if the end of the global array data base has been achieved. Consequently, you must test the returned value to determine if the returned results have moved on to a new global array. Examples:

    zmain # # assume the global array data base is completely empty. # for i=1:1:3 for j=1:1:3 for k=1:1:3 set ^a(i,j,k)=i set x=$query("^a(1)") write "example 0 ",x,! for do . set x=$query(x) . if x="" break . if $piece(x,"(",1)'="^a" break // $query() returns all globals . write "example 1 ",x,! set j=3 write "example 2 ",$query("^a(j)"),! // variables permitted write "example 3 ",$query("^a(2*j-j)"),! // expressions permitted set a="2+1" write "example 4 ",$query("^a(@a)"),! // indirection permitted set z="^a(1)" write "example 5 ",$query(@z),! // indirection permitted set z="^a(2)" write "example 6 ",$query(z),! for a="^a(1)":$query(a):"" do . if $piece(x,"(",1)'="^a" break // $query() returns all globals . write "example 7 ",a," -> " . write $qsubscript(a,0)," ",$qsubscript(a,1)," ",$qsubscript(a,2)," ",$qsubscript(a,3),! write ! // an alternative way of extracting index values for i="":$order(^a(i)):"" do . for j="":$order(^a(i,j)):"" do .. for k="":$order(^a(i,j,k)):"" do ... write "example 8 ",i," ",j," ",k,! writes: example 0 ^a("1","1","1") example 1 ^a("1","1","2") example 1 ^a("1","1","3") example 1 ^a("1","2","1") example 1 ^a("1","2","2") example 1 ^a("1","2","3") example 1 ^a("1","3","1") example 1 ^a("1","3","2") example 1 ^a("1","3","3") example 1 ^a("2","1","1") example 1 ^a("2","1","2") example 1 ^a("2","1","3") example 1 ^a("2","2","1") example 1 ^a("2","2","2") example 1 ^a("2","2","3") example 1 ^a("2","3","1") example 1 ^a("2","3","2") example 1 ^a("2","3","3") example 1 ^a("3","1","1") example 1 ^a("3","1","2") example 1 ^a("3","1","3") example 1 ^a("3","2","1") example 1 ^a("3","2","2") example 1 ^a("3","2","3") example 1 ^a("3","3","1") example 1 ^a("3","3","2") example 1 ^a("3","3","3") example 2 ^a("3","1","1") example 3 ^a("3","1","1") example 4 ^a("3","1","1") example 5 ^a("2","1","1") example 6 ^a("2","1","1") example 7 ^a("1","1","1") -> a 1 1 1 example 7 ^a("1","1","2") -> a 1 1 2 example 7 ^a("1","1","3") -> a 1 1 3 example 7 ^a("1","2","1") -> a 1 2 1 example 7 ^a("1","2","2") -> a 1 2 2 example 7 ^a("1","2","3") -> a 1 2 3 example 7 ^a("1","3","1") -> a 1 3 1 example 7 ^a("1","3","2") -> a 1 3 2 example 7 ^a("1","3","3") -> a 1 3 3 example 7 ^a("2","1","1") -> a 2 1 1 example 7 ^a("2","1","2") -> a 2 1 2 example 7 ^a("2","1","3") -> a 2 1 3 example 7 ^a("2","2","1") -> a 2 2 1 example 7 ^a("2","2","2") -> a 2 2 2 example 7 ^a("2","2","3") -> a 2 2 3 example 7 ^a("2","3","1") -> a 2 3 1 example 7 ^a("2","3","2") -> a 2 3 2 example 7 ^a("2","3","3") -> a 2 3 3 example 7 ^a("3","1","1") -> a 3 1 1 example 7 ^a("3","1","2") -> a 3 1 2 example 7 ^a("3","1","3") -> a 3 1 3 example 7 ^a("3","2","1") -> a 3 2 1 example 7 ^a("3","2","2") -> a 3 2 2 example 7 ^a("3","2","3") -> a 3 2 3 example 7 ^a("3","3","1") -> a 3 3 1 example 7 ^a("3","3","2") -> a 3 3 2 example 7 ^a("3","3","3") -> a 3 3 3 example 8 1 1 1 example 8 1 1 2 example 8 1 1 3 example 8 1 2 1 example 8 1 2 2 example 8 1 2 3 example 8 1 3 1 example 8 1 3 2 example 8 1 3 3 example 8 2 1 1 example 8 2 1 2 example 8 2 1 3 example 8 2 2 1 example 8 2 2 2 example 8 2 2 3 example 8 2 3 1 example 8 2 3 2 example 8 2 3 3 example 8 3 1 1 example 8 3 1 2 example 8 3 1 3 example 8 3 2 1 example 8 3 2 2 example 8 3 2 3 example 8 3 3 1 example 8 3 3 2 example 8 3 3 3

    Note that in the above, if the argument ^a(1) is given, the next value in the global data base is ^a(1,1,1) since this is the next higher actual stored key. The key ^a(1) is not a stored key in the above.

    If a second argument is given it must be a character string of length one. The character will become the delimiter between the fields of the result - that is, the character specified will replace the "(", "," and ")" tokens in the returned string. For example:

    zmain for i=1:1:3 for j=1:1:3 for k=1:1:3 set ^a(i,j,k)=i set x=$query("^a(1)","#") write x,! set j=3 write !,$query("^a(j)","#"),! set ^a(1)="^a(2)" set z="^a(1)" write $query(@z,"#"),! write $query(z,"#"),! write: ^a#1#1#1# ^a#3#1#1# ^a#2#1#1# ^a#1#1#1#

    If you use this format, note that you can not resubmit the returned global array reference to the function for another higher index. Only valid format global array references may be submitted as a first argument to the function.

15. $random(i1)

    $random returns an integer in the range zero through i1-1. For example: $random(100) yields a value between 0 and 99

16. $reverse(i1)

    The $reverse() function reverses the order of the characters in the argument string. Example:

    set x="now is the time" write $reverse(x),! the above writes "emit eht si won"

17. $select(t1:e1,t2:e2,...tn:en)

    The $select function takes a variable number of arguments delimited by commas. Each argument consists of two parts: a logical expression and a result expression. The function evaluates in sequence each of the logical expressions (shown above as t1, t2, ...tn - note: these can be any expression in reality: a zero result is called false and a non-zero result is called true). If a logical expression is true, the result expression (e1, e2, ... en) is evaluated and becomes the value for the function. In the compiler, there is a maximum of ten argument pairs permitted.

18. $text(L1) or $text(L1+/-I2) or $text(I1)

    $text() extracts text values from the source code. It only works on lines or original source code that began, after the line start character, with two semi-colons. The operand may be a label, a label plus or minus an offset or a offset only. All reference must be in the same file as is currently being compiled. An offset without a label is an offset from the first line of the file.

19. $translate(S1,S2) or $translate(S1,S2,S3)

    If only two strings are given, characters appearing in the second string are removed from the first string. If three strings appear and the second and third string are of equal length, characters from the first string appearing in the second string are replaced by their counterparts from the third string. If the second string is longer than the third string, the characters from the second string which have no counterpart in the third string are removed. By "counterpart" we mean a character equally offset in the third string to the character in the second string.

20. $view

    $view is not supported.

21. $z...

    $zfunctions are extensions added by the implementor. A user may add new $Z functions by modifying the zfcn() function. The Mumps compiler has the following $Z functions:

    Math Functions

    The following functions are available. Their arguments and return values are the same as the corresponding C++ functions.

    • $zacos(arg) - computes the inverse cosine (arc cosine) of the input value. Arguments must be in the range -1 to 1.
    • $zasin(arg) - computes the inverse sine (arc sine) of the argument arg. Arguments must be in the range -1 to 1.
    • $atan(arg) - computes the inverse tangent (arc tangent) of the input value.
    • $zcos(arg) - `cos' computes the cosine of the argument arg. Angles are specified in radians.
    • $zexp(arg) - calculates the exponential of arg, that is, e raised to the power X (where e is the base of the natural system of logarithms, approximately 2.71828).
    • $zlog(arg) - Returns the natural logarithm of arg, that is, its logarithm base e (where e is the base of the natural system of logarithms, 2.71828...).
    • $zlog10(arg) - returns the base 10 logarithm of arg.
    • $zpow(arg1,arg2) - calculates arg1 raised to the exponent arg2.
    • $zsin(arg) - computes the sine of the argument arg. Angles are specified in radians.
    • $ztan(arg) - computes the tangent of arg.

    The following special purpose functions are available:

    1. The $zab(arg) function returns the absolute value of its numeric argument.

    2. The $zb(arg) function returns a string in which leading and all multiple blanks have been replaced by single blanks.

    3. The $zcd[(filename)] function dumps the globals to a sequential ASCII file in the current directory. If an argument is given, it is taken as the name of the file to which the globals will be written. If the argument is omitted, a file name is constructed from the system date of the form number.dmp where number is the high order 8 digits of the value of the C++ time() function at the time of the dump.

       The dump file is ASCII text. Each entry in the global array is represented by two lines. The first line is the global array reference and the second line is the store value. In the global array reference, parentheses and commas are replaced by the "~" character.

    4. The $zchdir(directory_path) function changes the current directory to the path specified. If the operation succeeds, a zero is returned. If it fails, -1 is returned.

    5. The $zcl function restores the globals from the file named dump. Create this file by using the $zcd function and renaming the output file to dump. Please note this name. It is different than the names used by the dump function.

    6. The $zdate (or $ZD ) function returns the system date and time in standard system printable format. This includes: day of week, month, day of month, time (hour:minute:second), and year (4 digits).

    7. The function $zd1 returns the number of seconds since January 1, 1970 - a standard used in Linux. This number may be used to accurately correlate events.

    8. The function $zd2(InternalDate) translates the Linux time from $ZD1 into standard system printable format. The argument is a Linux format time value.

    9. The function $zd3(Year,Month,Day) returns the day of the year (Julian date) for the Gregorian date argument.

    10. The function $zd4(Year,DayOfYear) returns the Gregorian date for the Julian date argument.

    11. The function $zd5(Year, Month, Day) returns a string consisting of the year, a comma, the day of year, and the number of days since Sunday (Monday is 1).

    12. The function $zd6 returns a string consisting of the hour, a colon, and the minute.

    13. The function $zd7 returns a string consisting of the year, hyphen, month, hyphen, and day of month. If an argument is given in the form of the number of seconds since Jan 1, 1970, the result returned will reflect the argument date.

    14. The function $zd8 returns a string consisting of the year, hyphen, month, hyphen, and day of month, comma, and time in HH:MM format. If an argument is given in the form of the number of seconds since Jan 1, 1970, the result returned will reflect the argument date.

    15. The function $zd9 returns a string consisting of the year, hyphen, month, hyphen, and day of month, comma, day of week and time in HH:MM format. If an argument is given in the form of the number of seconds since Jan 1, 1970, the result returned will reflect the argument date.

    16. The $zf(arg) function returns a zero or one indicating if the file given as the argument exists.

    17. The $zg function gives a profile of the global file systems. It returns 6 values, separated by blanks, that give the the address of the file system root block, the size of the DATA file, the size of the KEY file, the number of internal buffers in use, the file system mask in hexadecimal and the version number. The files are limited to 2 gigabytes each at present.

    18. The $zflush function flushes all modified native global array handler buffers to disk. The function should only be used with the native globals. After flushing, all updates to the btree file system have been committed. In cases where the internal buffers are very large, this function may take several seconds to execute. The function returns the empty string. Flushing the buffers is a precaution against system failure which would otherwise result in corruption of the global arrays.

    19. The $zh(arg) function encodes its argument in the form necessary to be a cgi-bin parameter. That is, alphabetics remain unchanged, blanks become plus signs and all other characters become hexadecimal values, preceded by a percent sign.

    20. The $zhit function calculates and returns the native global array cache hit ratio. This number ranges between zero and one. A value of one indicates all requests were satisfied from the cache while a value of zero indicates no requests were satisfied from the cache. Calling this function resets the hit ratio to zero.

    21. The $zm(global) function returns the next row of the global array matrix.

    22. The $zlower(string) function returns the input string with alphabetics converted to lower case.

    23. The $zn(arg[,arg2]) function normalizes word content for use with information storage and retrieval systems. It converts the word passed as an argument to lower case and removes non-alphabetics. The result is returned as the value of the function. If a second argument is given, the word is truncated to the numeric value of the argument. If no second argument is given, words are truncated to 25 characters if their length exceeds 25 characters. This function is used with document indexing applications.

    24. The $zp(arg1,arg2) function left justifies the first argument in a string whose length is given by the second argument, padding to the right with blanks.

    25. The $zr(arg) function returns the square root of its numeric argument.

    26. The $zs(arg) function takes one argument string which it passes to a shell for execution. Output is sent to standard out.

    27. The $zseek(arg) function takes one argument (a positive integer) which is a byte offset in the currently active (use) file. The command moves the file pointer to that location in the file. The function works with files longer than 2GB if the compiler was configured (see configure) for large file sizes.

    28. The $zsqr(arg) function return the square of its numeric argument.

    29. The $zstem(arg) return the word english word stem of the argument. This function attempts to remove common endings from words and return a root.

    30. The $zsystem(arg) Executes "arg" in a system shell. Returns -1 (fork failed) or the return code of the argument.

    31. The $ztell function returns the byte offset in the currently open file. Similar to the C++ ftell() function. This function works with files larger than 2GB. Note: The offset returned is for the file most recently made the default i/o file by the use command.

    32. The $zu(expression) function returns 1 if the expression is numeric, 0 otherwise.

    33. The $zwi(arg) function loads an internal buffer with the string given as the argument. The contents of this buffer are returned by the $zwn and $zwp functions.

        zmain set i="now, is the time, for all good" do $zwi(i) for w=$zwp write w,! write "-------",! do $zwi(i) for w=$zwn write w,! writes: now , is the time , for all good ------- now, is the time, for all good

    34. The $zwn function returns successive words from the internal buffer delimited by blanks. When no more words remain, it returns an empty string (string of length zero). Returned words are converted to lower case. See example.

    35. The $zwp function returns successive words from the internal buffer delimited by blanks and punctuation characters. When no more words remain, it returns an empty string (string of length 0). Returned words are converted to lower case. See example.

    36. The $zwp(string) initializes the parse buffer but does not convert "string" to lower case as is the case with $zwi()

    Built-in Variables

    1. $horolog (Abbreviation $h) - The $H built-in variable returns a string consisting of two numbers. The first is the number of days since December 31, 1840 and the second is the number of seconds since the most recent midnight. The variable may not appear as the target of an assignment or read command. These values are relative to Greenwich Mean Time.

    2. $io (Abbreviation: $i) - $io gives the current unit number. Mumps I/O is, at any given time, directed to a given unit number. In Mumps, i/o, by default, is directed to unit 5 - the user's console. This is the unit from which all read's and write's will take place. If the user open's another unit number for further file operations, the use command is used to redirect the read and write commands to this unit. The $io variable indicates the current i/o unit number. It may not appear as the target of an assignment statement or as an argument of a write command although it may appear in both contexts as a source argument such as in computation of an index of a target array.

    3. $job (Abbreviation $j) - The $job variable returns the system job number. This is the process PID.

    4. $test (Abbreviation $t) - The $test variable reflects the status after certain commands. Generally speaking, it is set to one (1) when the command succeeds and to zero (0) when the command fails. The value in $test remains until it is changed. Examples of commands that set $test are: read, open, if, and lock. In compiled code, the value of $test on entry to a block is restored on exit.

    5. $storage (Abbreviation $s - Always returns 999.

    6. $x - The $x variable gives the current horizontal position of the record in the current unit number. For terminals, this is the horizontal cursor position. For other files, it is the number of characters since the start of the current record.

    7. $Y- The $y variable gives the vertical position of the current unit number. It is pre-set to zero for each top of forms format control used.

    ---

    ---

    Installing the Compiler

    The compiler is supplied as both a compressed gzipped tar file (for Linux) and a zip file (for DOS). Uncompress and untar or unzip the distribution. Do not attempt to use the Linux distribution with DOS as it will not work correctly. In MS Windows, the unzip will create a directory named mumpsc in the root directory of the C: disk drive. The zip file consists primarily of executables while the Linux distribution contains the full source code. In Linux, the untar will create a directory named mumpsc in the directory from which you perform the untar. The following is an example of the untar/ungzip for Linux:

    tar xvzpf mumpscompiler-9.00.src.tar.gz

    Other Software Needed

    In addition to the software provided in this package, you will need additional software which is probably included in your Linux distribution disks. You should install:

    1. Required: The Perl Compatible Regular Expression Libraries which are used to support the pattern match operator (libpcre0 and libpcre0-devel) (http://pcre.org).
    2. Optional: The Berkeley Data Base to handle globals (db4, db4-devel, and db4-utils or higher). Note: you probably have db1 installed as it is used by several system functions. You will need BDB 4.3 or later, however. The present release is keyed to the most recent BDB data base release. If the BDB is not present, you must use the native global array system. This will be made the default by "configure" on Linux systems. The system was developed and tested with version 4.3.28.

    Note: the new C++ routines require a recent version of the C++ compiler that incorporates changes to the language standard made in 1999. Some Linux distributions may not have the most recent version of the g++ compiler. The code in this distribution was compiled using g++ version 3.4.3.

    MS Windows XP:

    You may either build the compiler from source code (this requires Cygwin and the MS Visual C/C++ compiler) or download the binaries (requires only the MS Visual C/C++ compiler. You may also just download the binary executable interpreter which requires no additional software.

    A free copy of the MS Visual C++ command line compiler is available from:

    http://msdn.microsoft.com/vstudio/express/visualC/default.aspx

    Cygwin is available from:

    http://www.cygwin.com/

    If you download the binaries, when the Windows version is unziped, the distribution will reside in a directory named mumpsc in the root directory of your C: disk. The mumpsc directory will contain the manual ("compiler.html"). See the appropriate INSTALL file for details. The *.zip distributions contain binary executables, header files and documentation. Full source code is in the *.tar.gz files.

    1. MS Visual C++ Binary Install

       The Microsoft Visual C++ version of Mumps/MDH installs to c:\mumpsc when you unzip the distribution. This version contains both the compiler and MDH toolkit. It also contains modified pcre routines and header files.

       You must install a command line version of the MicroSoft Visual C/C++ compiler. A free version of this compiler is available at:

       http://msdn.microsoft.com/vstudio/express/visualC/default.aspx

       The Mumps zip file distribution contains pre-built executable versions of the Mumps Compiler and run-time libraries. Unzip the distribution to your C:\ drive so that the files are located in the directory 'mumpsc' (this will be the default). The distribution will build a directory tree under 'mumpsc'. In this directory tree are the libraries, executables, some source files and documentation.

       Important: Once you have unzipped the files on C: drive, add c:\mumpsc\bin to your PATH:

       path=%path%;c:\mumpsc\bin;

       You can make this permanent by going to:

       Start | Settings | Control Panel | System

       and then clicking on the 'Advanced' tabe then on "Environment Variables" Edit the environment variable named 'Path' and add ';c:mumpsc\bin' at the end. Be carefull when editing this as you could cause serious problems if this variable becomes corrupt.

       To compile a mumps program with the native globals data base, open a command prompt for the Visual C/C++ compiler which should be accessible as:

       Start | Programs | Visual C++ 2005 Express Edition | Visual Studio Tools | Visual Studio 2005 Command Prompt

       and type mumpsc xxx.mps

       where "xxx.mps" contains the mumps program. The excutable will be "xxx.exe"

       To compile a C++ program that uses the MDH Toolkit:

       mumpsc zzz.cpp

       The stack size of running programs can be an issue. For WindowsXP, the stack size is set in the file "mumpsc.bat" in the batch file variable "STACK". It is presently set at 10,000,000 but may be adjusted higher or lower, as needed. Some programs, most notably the Smith-Waterman alignment procedure, may recurse many times and this may cause stack overflow unless the stack size is increased.

    2. MS Visual C++ Full Build Details

       To re-build the Windows XP compiler, you need Cygwin and the MS VC compiler.

       The build routine is "MSVCbuild.bat". This routine is included in the source distribution:

       mumpscompiler-x.xx.src.tar.gz

       which untars/ungzips under the directory 'mumpsc'. You should untar/unzip this file under cygwin in your cygwin home directory.

       The build bat file should be run from this directory from a Windows XP command prompt whose PATH and other environment variables have been set to access the Microsoft compiler. (See above regarding an MS Visual C++ command prompt).

       As the Linux/Cygwin 'configure' iprogram does not work under Windows XP in native mode, you must run configure under Cygwin. This will configure the source C and C++ files for the MSVC environment.

       To configure for MSVC, under Cygwin, type:

       configure --with-msvc

       This will properly configure the source files.

       Note: if you do this under Linux, some functions may be incorrectly specified.

       To use the Berkeley Data Base,however, you must download and install the Berkeley package from

       http://www.sleepycat.com.

       The BDB is distributed under its own license which is different than the GNU GPL/LGPL. You should read and understand the Berkeley license before you use this data base.

       The file "db.h" is included in the main source distribution. It is located in include and renamed to be "db.x". This file is part of BDB 4.2.52 and is distributed to assist in compiling applications using BDB.

       You should update this file as needed for your version or rename the one provided to "db.h" before you build the system. Otherwise, you will see an error message whrn the BDB support functions are being built. You may ingnore these errors if you do not plan to the the BDB.

       Do _NOT_ rename db.x if you are building the system for Linux or Cygwin.

       The BDB file "libdb42.dll" is built by the BDB install package should be copied to your c:\windows directory. The file "libdb42.lib" also built by the BDB install package should be copied to c:\mumpsc\lib. NOTE: one file name ends in "lib" and the other in "dll" - don't confuse them!

       The batch MSVCBuild.bat compiles the software, builds mumpslib.lib, and copies the relevant files to "c:\mumpsc\". Besides the MSVC++ compiler and its compile and runtime librarues, you need the MicroSoft lib.exe program to create libraries. File lib.exe is not part of the free distribution.

       The Mumps Compiler (mumps2c.exe) and the bat files to compile and run programs are copied to "c:\mumpsc\bin". This directory must be added to your PATH variable as shown above. The bat files in the directory "mdh.bat" and "mumpsc.bat" are hardcoded to look for libraries and include files in "c:\mumpsc\". If you move or rename this directory, you must modify these files as well as mumpsc/MSVCbuild.bat.

       It is tricky to configure pcre 4.5 for Windows. Thus, provided with the distribution are object files for pcre.c and get.c (named get.obj and pcre.obj) from the pcre 4.5 distribution. Note also that the pcre 4.5 pcre.h file is in mumpsc/include. These files can be replaced with newer versions as needed. The pcre is covered by a separate license given elsewhere in this distribution.

       The c:\mumpsc directory contains:

       
       c:\mumpsc\bin            executables and scripts
       c:\mumpsc\lib            object libraries
       c:\mumpsc\include	header files
       c:\mumpsc\doc            documentation
       c:\mumpsc\src            source code
       

       Do not enable the optimization switch /O2 or other values that optimize for speed as they have caused problems with pattern matching.

    3. Windows XP Apache Web Server Interface

       If you want to use and test web based software, you will need a copy of the Apache Server for Windows XP. This can be downloaded from

       http://www.apache.org/dist/httpd/binaries/win32/#released

       Find the latest file of the form:

       http://www.apache.org/dist/httpd/binaries/win32/apache_2.2.3-win32-x86-no_ssl.msi

       download it then double click on it (it will initiate the self install procedure).

       To run programs through the web server, start the server (see Apache documentation). You will place your scripts in the default 'cgi.bin' directory which should be located at:

       C:\Program Files\Apache Software Foundation\Apache2.2\cgi-bin

       Copy to this directory the file 'cgi.mps':

       #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ #+ Mumps Compiler Run-Time Support Functions #+ Copyright (c) 2006 by Kevin C. O'Kane #+ okane@cs.uni.edu #+ #+ This library is free software; you can redistribute it and/or #+ modify it under the terms of the GNU Lesser General Public #+ License as published by the Free Software Foundation; either #+ version 2.1 of the License, or (at your option) any later version. #+ #+ This library is distributed in the hope that it will be useful, #+ but WITHOUT ANY WARRANTY; without even the implied warranty of #+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU #+ Lesser General Public License for more details. #+ #+ You should have received a copy of the GNU Lesser General Public #+ License along with this library; if not, write to the Free Software #+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA #+ #+ http://www.cs.uni.edu/~okane #+ #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ zmain +#include <mumpsc/cgi.h> + if (argc==2) $SymPut("%",argv[1]); + else $SymPut("%",""); for i=1:1:10 set j=$p(%,"/",i,i+1) if $p(%,"/",i+1)="" quit x "do ^"_j halt

       Compile this program with the Mumps Compiler. This creates a program which will become the executing shell for your actual script. It will be named cgi.exe.

       To write an executable script, create a file with the '.cgi' extension such as:

       #!/Program Files/Apache Software Foundation/Apache2.2/cgi-bin/cgi write "Content-type: text/html ",!! write "<html><body>" write "Hello World<p>" for i=1:1:10 write i,"<br>",! write "</body></html>" halt

       The script, when invoked by the server, invokes the shell (cgi.exe) which parses the name of the script file you want to run and executes it. Name the script above "a.cgi".

       Pay close attantion to the line:

       write "Content-type: text/html ",!!

       If this line is not correct, the page will not display. Also note that blanks only appear at the beginning of lines for the interpreter. Do not use characters. The URL will be:

       http://127.0.0.1/cgi-bin/a.cgi

       Where 'a.cgi' is the name of the script file immediately above. The results appear as:

       

    Linux and Cygwin Installs:

    Download and un-tar/un-gzip the distribution:

    http://math-cs.cns.uni.edu/~okane/cgi-bin/newpres/m.compiler/compiler/index.cgi

    A a directory named mumpsc will be created by the un-gzip/un-tar procedure.

    Linux/Cygwin Quick Root Install

    For the impatient, login as root and try the following:

    Linux:

    tar xvzf mumpscompiler-9.01.src.tar.gz
    cd mumpsc
    ./configure prefix=/usr
    make
    make install

    use:

    ./configure prefix=/usr --with-cpu64

    if you have a 64bit processor.

    Cygwin:

    tar xvzf mumpscompiler-9.01.src.tar.gz
    cd mumpsc
    ./configure prefix=/usr
    make
    make install

    use:

    ./configure prefix=/usr --with-cpu64

    if you have a 64bit processor.

    The commands "mumps" and "mumpsc" should now be active.

    Full Linux/Cygwin Installation

    Installation is a two step process:

    • compile and link the modules
    • copy the modules to target directories

    First, run the autoconfig script:

    ./configure

    This will test your configuration and provide any warnings concerning missing libraries. See configure.ac for autoconfig source details. The "configure" script has many options, all of which have default values. You may override these defaults with parameters to the "configure" command.

    By default, the compiler will be built in your home directory in a directory named "mumps_compiler" (~/mumps_compiler).

    To build in other directories, use a command such as:

    ./configure prefix=/usr

    This will build the installation in the system directories (/usr/include, /usr/bin, /usr/lib, etc). You must be root to do this.

    If you want the Berkeley Data Base facility to be the default global array file handler, add the parameter "--with-bdb" to the "configure" command:

    If you want to take advantage of very large files and very large native global arrays (file sizes greater than 2 gigabytes), you need to enable large file support:

    ./configure prefix=/usr --with-native

    The native globals btree has an internal cache. Each block in the cache is the same size as the btree block (default: 1025). By default, the cache is set to 9. This may be overridden by "configure":

    ./configure prefix=/usr --with-native --with-cache=1000

    where the number specified (1000 in this case) will be the number of blocks cached. This value may not be less than 9 and must be selected from a list of values (see table below).

    ./configure --with-cpu64

    the "--with-cpu64" option enables code for 64 bit processors using gcc/g++ compilers enabled to generate 64 bit code. This option has been tested using the to a limited degree on Intel Xeon64 processors. The --with-cpu64 causes compiles to look for libraries in /usr/lib64.

    The "configure" file (see "configure.ac") has been developed with Red Hat and Debian releases. It has had limited testing with Apple OS/X. It is not suitable for DOS systems.

    configure options
    Option	Meaning	Default
    --with-cpu64	enables 64 bit code generation	32 bit code.
    --with-msvc	Builds modules so they can be compiled with the MicroSoft Visual C++ compiler.	not enabled
    --with-djgpp	Builds modules for compilation with the DJGPP compiler. The --file-64 option must be omitted with this option.	not enabled
    --with-native	Makes native globals the default global file handler.	Native data base
    --with-bdb	Make Berkeley Data Base the default global file handler.	Native data base.
    --with-includes=DIR	Used to identify header dirs for Apple port.	N/A
    --with-libraries=DIR	Used to identify library directories to Apple port.	N/A
    --with-cache=VAL	Native globals cache size.	1025. Note: the permitted values for this field are: 9, 17, 33, 65, 129, 257, 513, 1025, 2049, 4197, 8193, 16385, 32769, 65537, 131073, 262145, 524289, or 1048577.
    --with-ibuf=VAL	Maximum text size of an interpreted program.	20000. Maximum value for this field is 32000 and the minimum value is 4096. Note: in order to run "checkout.mps" in the distribution, this value needs to be at least 20000.
    --with-strmax=VAL	Maximum internal string size (STR_MAX)	4096.
    --with-block=VAL	Native btree block size.	1024. Note: this value must be one of: 1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288, 1048576, or 2097152. The size of the btree block determines the maximum file size. A block size of 1024 permits the key file to grow to 2 terabytes. A block size of 2048 would permit the key file to grow to 4 terabyte, a block size of 4096 permits a 16 TB max key file size and so on (doubles at each step). Larger blocks, however, can result in slower performance. You should select the smallest block size possible for your application. A block must be capable of storing a key plus about 30 bytes of overhead.

    The "configure" script will generate warnings and/or error messages if certain required modules are missing.

    To install for Red Hat based Linux distributions (such as Red Hat and Mandrake), type:

    make

    then, as root if your are installing to system directories, type:

    make install

    To compile a Mumps program type:

    mumpsc myprog.mps

    and the result will be "myprog.cgi" if you followed the syntax rules in "compiler.html".

    Note: if you allowed "configure" to install the compiler files to the default "$HOME/mumps_compiler" directory, you should add $HOME/mumps_compiler/bin" to your "PATH" variable.

    Implementation specific notes

    Some versions of Linux (e.g., Debian) install some libraries under different names and in different directories.

    The install will place several "man" pages on your system. These are:

    1. mumpsc

    If you are going to use the Berkeley DB, you need to be sure that it has been installed on your system. If not, install it before you install the Mumps Compiler. It generally goes by the name db3 or db4 on your distribution disks. The Mumps Compiler will not work with anything prior to db3 and there may be problems if you have an early version of db3. Please try to use the latest version available. If you receive an error message concerning the function stat on or about line 74 in global.c, alter the function call to remove the next to last argument (NULL). This problem is caused by some versions of the Berkeley DB having a different calling structure than others. Be aware that some systems install DB3 and DB4 to directories other than those for which the system was written. If you get error messages listing unknown header or library files, this may be your problem.

    Each new release of the BDB seems to change important API calling parameters. We attempt to keep the current Mumps release in compliance with the most recent BDB release and their changes but this is not always possible. Consequently, you may experience errors when compiling global.c as this is the interface with the BDB. This may be particularly true if you are using a release of the BDB prior to Version 3.2.9.

    You may now try the checkout code. If you have installed hte software locally to you directory, be certain to adjust the PATH variable as noted above and re-logon.

    Move to the sub-directory mumpsc/doc/examples and compile the checkout routine:

    mumpsc checkout.mps

    This will compile the Mumps program "checkout.mps". Please note: this is "checkout.mps", not "checkout1.mps". The file "checkout1.mps" is invoked by "checkout.mps" and contains code in a format suitable for the compiler (i.e., it has a "zmain" command).

    The default compilation uses the native global array file system. You may request the BDB global array file system by:

    mumpsc -b checkout.mps

    Alternatively, if you have made the BDB file system the default (with "configure") you may force the native file system with:

    mumpsc -n checkout.mps

    Present in the examples directory along with checkout.mps is a file named checkout1.mps which is essentially similar. Do not compile this file. It will be interpreted by checkout.mps as a result of an Xecute command. To run the compiled program, type:

    checkout.cgi

    many lines will flash by. It will pause and ask you for input: type a few random characters. As the last test, the compiled program will execute (via the Xecute command) the file checkout1.mps. This file is similar to checkout.mps but used for testing the interpreter. It too will ask for some random characters. Finally, the interpreted file will finish and the compiled file will end.

    There are also validation routines in the directory "validate" that may be compiled and excuted to test your installation.

    There are two global array file systems. The default is the native global array handler. The other system is referred to in this manual as the Berkeley Data Base (BDB) array file system. The native global array file system will produce data files named key.dat and data.dat while the Berkeley DB will produce a file named Mumps.DB as well as several files each of whose names begins with the prefix "__db". Erase these files should you re-run the test code as residual data in them will cause subsequent tests to fail.

    Multiple compiled Mumps programs may be executed concurrently with the Berkeley DB. The underlying Berkeley DB software will arbitrate disk accesses in the event of two or more concurrent attempts to store into the data base. The native global array handler, on the other hand, will take exclusive control of the data base for the duration of a program's execution. Other programs will pend waiting for the global arrays to be come available.

    You may want to check the preprocessor defined variables in include/mumpsc. These may need to be set for your operating system and for other options. These files contain operating system and environment specific settings in preprocessor defined variables located near the beginning of the file. Each contains a comment as to its optional settings. The default settings should be adequate for most purposes.

    If you need to debug C++ programs generated by the Mumps Compiler, you may compile from the C++ source by:

    mumpsc myprog.c

    where "myprog.c" was created from a Mumps program named "myprog.mps" by the compiler. This will enable you to modify the generated C++ program and still compile it with all the options and libraries required by Mumps.

22. There are a set of checkout routines in the directory "validate" that can be used to verify your installation and as examples of the dialect of mumps accepted by the compiler.