Version 2.1.1.1 contains two programs:
1. mumpsCL (mCL) – mumpsAPI Command Language (development environment).
2. mumpsSVR (mSVR) - mumpsAPI TCP/IP Server
mCL
DESCRIPTION
mCL is a terminal based development environment for MUMPSV1. It is a tightly bound implementation and used for local development within a MUMPSV1 environment. It is based on DCL (Digital Command Language). It does not use the mumpsAPI communications package. It is designed to be used to quickly develop server based code for an application. It is simple to use and is intended as an alternative to the MUMPSV1 utilities.
FEATURES
Built to operate within Terminals that emulate VT100's and support ANSI escape processing.
Interacts with the programmer via a command language based on DCL (Digital Command Language) that operates on globals, routines and displays system level information.
Available Commands are:
CHANGE – lets the programmer switch between environments (UCI')
COPY – copies routines or globals between namespaces.
DELETE – deletes routines or globals.
DIRECTORY – displays ^$routine or ^$global directory contents.
DISPLAY – used to display system level information as well as key mappings.
EDIT – simple full screen editor for routines. Simple global editing.
EXIT – exit the mCL programming environment.
HELP – lists all commands and command qualifiers help information.
MONITOR – runs a monitor that samples system information and displays it at specified intervals.
PARSE – parses routines and displays errors.
RESTORE – restores routines and globals from save files.
SAVE – saves routine and globals to a file. Encodes globals that contain control characters if the /ENCODE qualifier is specified. Additionally, if the /PARSE qualifier is specified, each line of the saved routine will be parsed and reformatted based on the stored style parameters.
SEARCH – search routines or globals for a pattern.
SHOW – shows the content of specified routines or globals. Globals are iterated. By default only global nodes that contain data are displayed. If the /NODATA is specified on the command, only the lowest specified level is displayed without data.
mumpsSVR
DESCRIPTION
mumpsSVR is a TCP/IP server that runs on the MUMPSV1 V1.66+ system.
ENHANCEMENTS
Enhancements included in this version:
Server:
The code has been made much more robust and generalized.
Enhanced to support multiple dispatch interfaces. Currently two are supported:
MData
MObjects (Not released at this point)
Compiler:
1995 ANSI compliant compiler written in MUMPS has been added.
DISPATCH INTERFACES SUPPORTED
MDATA
MData implements 16 of the 18 requests that attempt to replicate the equivalent functionality of the nodeM project.
These are the current requests implemented:
1. Verify client connection.
2. Disconnect client from server.
3. Get the MUMPS version string.
4. Set data to a global node.
5. Get global node data value.
6. Kill a global or global node.
7. Get the $Data value of a global node.
8. Get the $Order value of a global node (forward and reverse).
9. Get the reverse $Order value of a global node.
10. Increment the record count in a global node.
11. Merge one global array into another.
12. Get a list of global names from the directory.
13. Incrementally lock a global node.
14. Incrementally unlock a global node.
15. Call an extrinsic function.
16. retrieve - Not Implemented
17. update - Not Implemented
18. Send a non-existent request to generate an error.
Although the general functionality is replicated, mumpsSVR is not a replacement for nodeM. NodeM is designed to run in-process on GT.M. The mumpsSVR implementation has expanded the functionality and, in some cases, the response message has changed.
The following are some mumpsSVR features:
All data requests and responses are formatted in JSON.
All informational and error messages are formatted in JSON. These messages are returned to the client as well as logged to a file within the database directory. The log file records all pertinent messages for one server session. A new server session creates a new sequential file.
A management utility (%mapimgr) is supplied that starts and stops the server as well as view the status of the server. Additionally, it lets the manager customize the server policies.
A test client (mapitcl) is included in the mapiClient.rsa file. All routines in this file should be installed in a non-MGR UCI. It exercises all of the functions listed above.
A unit test routine (%mapitun) is included that tests and verifies some fundamental functionality.
A code transformation routine (%mapicdt) routine exists for the programmer to generated routines that contain hidden functionality for the MUMPS system being supported or debugging.
A documentation routine(%mapidoc) exists that, when run, will display each or all routines documentation.
A 1995 ANSI compliant compiler has been added. It implements the 1995 standard to the extent that MUMPSV1 does.
Two guides are included in the kit - Programmer's Reference Guide which outlines how to construct the requests and an Administrator's Guide which outlines how to operate the system.
MOBJECTS
MObjects is a forked version of EsiObjects that runs on MV1. The TCP/IP component is currently implemented but has not been tested against the system. Consequently, the core MObjects routines have not been included. This will happen in a future release.
KIT CONTENTS
A database file (mapiDB) for MUMPSV1 V1.66+. It contains all the mumpsAPI and compiler routines and globals.
mapiMCL.rsa, mapiServer.rsa and mapiTestClient.rsa routines saves as backup.
Programmer and Administrator’s Guides in two formats - .html and .pdf
Release notes - readme.txt
License File - license.txt
REQUIREMENTS
The following are required to install the mumpsAPI server.
MUMPSV1 V1.65+ running on any one of the supported platforms.
Storage in the MGR UCI that does not contain routines in the %mapi*, %mcmp* or %mcl* name space.
INSTALLATION
MUMPSV1 V1.66+
You must have MUMPSV1 V1.66 or greater installed. You can get it at:
https://sourceforge.net/projects/mumpsapi/?source=directory
NOTE: if you have GT.M installed, you may have to change the mumps executable file to mv1.
Make sure you have installed the basic set of utilities.
Use the ^%M command utility:
M> d ^%M
MCL>
SERVER SIDE
To install or upgrade the server, follow the instructions listed below.
There are two ways to install mumpsAPI.
1. Simply start up the existing mapiDB database.
a. The kit file mapiDB contains a completely installed database. All you have to do is start it up.
b. Change to the mumpsv1 directory - the same directory as the mumps executable.
c. Move the mapiDB file into the selected directory.
d. Start it up with the following command:
./mumps -j65 ./mapiDB
Note: The number of jobs must exceed the number requested by the server. The default number for the server is 64. You can change that by invoking the %mapimgr routine and executing the Set Server Policies.
2. Install the routines into your existing database.
a. Download the mumpsapi.zip file from SourceForge.
b. Expand the kit file into a directory of your choice. Typically, the directory that holds the MUMPSV1 system is easiest.
c. All server, compiler and initialization routines reside in the mapiServer.rsa file. They are prefixed by %mapi*, %mcmp* and %mclini* respectively. Make sure you do not have any routines beginning with these prefixes in the MGR UCI.
d. Sign into the MGR UCI in programming mode. If you had loaded a previous version, delete all %mapi* routines. (It is not done automatically because you may have written some of your own routines in that namespace.) Then invoke the routine restore utility. Import the routines.
e. Now you must initialize the system. To do this, execute the following command. It will setup all default globals in the MGR area.
f. do ^%mclinit
3. At this point the system is ready to run. Go to the Administrator's Guide for instructions on how to management the system.
4. To program against the mumpsAPI, go to the Programmers Guide.
CLIENT SIDE
If you used the preloaded database mapiDB, it has a test UCI named TST. Use the CD command to transfer to it.
If you want to load the test client routines into your own test UCI, they resides in the mapiTestClient.rsa file. This routine may reside in any UCI or MUMPSV1 system that has access to the IP address of the server.
1. Use the CD command to transfer to your test UCI.
2. Use the routine restore utility ^%RR to restore them.
KNOWN PROBLEMS
1. The server has not been tested with non-MUMPS clients such as JavaScript.
2. The server sends all responses back as strings and does not differentiate between strings and numbers.
TO DO
Finish the M Command Language (MCL) and include it in the mumpsAPI system. This routine set will provide a Digital Command Language like interface for:
Administration:
Commands for maintenance of user information.
Server policy information.
Programming:
Commands and functions needed for a reasonably complete MUMPS programming environment, replacing most library utilities (%).
Fullscreen routine and global editing capability.
1995 parsing capabilities.
Implement a GUI interface for the MCL environment to replace the terminal interface.
Transition the core routines of MObjects (EsiObjects) and get it to work with the TCP/IP dispatch interface.
Implement MObjects GUI, a replacement for the current EsiObjects IDE.
