MUMPS Kermit Kermit-M is written in the 1982 ANSI Standard MUMPS language. MUMPS is typically used for transaction-oriented data base applications. There are two types of MUMPS implementations, those running under some host operating system (e.g. CP/M, VMS, Unix), and those with their own integrated operating system. In the former type, it is probably faster to use a Kermit developed for the host operating system, and then use local utility programs to transfer between the host operating system and MUMPS data structures. Kermit-M was developed on M/11, which has its own integrated operating system. In this case, Kermit must be written in the MUMPS language (since that's the only language available on such systems), and Kermit must be able to understand MUMPS data structures. Since MUMPS was never intended to be a systems programming language, there are certain performance penalties in using Kermit-M. Kermit-M is divided into two main sections. The first provides most of the functions of other Kermits, including Server mode. There is no 8-bit quoting, so that only the 7-bit ASCII character set is supported. In this section, he command parser follows TOPS-20 style, with extensive HELP. The second provides the interface between the Kermit file structure and MUMPS data structures. This is accessed with the MUMPS command, and is organized as a series of menus, in the more usual MUMPS interactive style. Since MUMPS systems do not have typical (e.g. TOPS-20 style) file systems, Kermit-M must simulate a file system within MUMPS data structures, and the MUMPS command must provide typical file system services (Directory of files; Copy, Rename, and Erase files). The MUMPS command also provides the mechanism for interpreting Kermit files as MUMPS data structures, and vice-versa. The MUMPS data structures that are supported are 1) routines, 2) globals, 3) sequential 'files' (e.g. magtape, sequential disk processor, terminals), and 4) globals interpreted as sequential files. Although MUMPS is an ANSI standard language, certain sections of the language which are critical to Kermit-M are implementation-specific. Almost everything dealing with I/O is in this category. The initial version of Kermit-M was developed at the New York State College of Veterinary Medicine, on a PDP-11/44 running InterSystems' M/11, Version 5. It will have to be modifed for any other MUMPS implementation. A separate document has been prepared for those who need to prepare a new version. Installation of Kermit-M Kermit-M consists of about 20 MUMPS routines (all starting with the prefix ZKR) which are about 2 to 4 KB of text), and one reference global (^ZKRX) which is about 40KB. The routines, reference file, and external comments are provided in two ways: as 3 files on 800BPI 9 track magnetic tape (separated by tape marks) , and as TOPS-20 files named, respectively, 'KERMITM.ROU', 'KERMITM.GLO', and 'KERMITM.ECM'. [Editors note: These have been renamed to MPKERMIT.ROU, MPKERMIT.GLO, and .ECM, respectively, for distribution purposes.] The first file contains the text of all routines. The first line is a string of MUMPS code that allows the rest of the file to be loaded according to the proposed MDC standard on interchange of routines. (This code is 'R DATE F I=0:0 R ROU Q:ROU="" ZL ZS @ROU'.) The second line is the date and time the file was written. Following these two header lines are the routine texts. Each routine begins with one line containing just its name, and ends with a null line. The file ends with an additional null line. If the file can be opened as a sequential device, all the routines can be loaded into the MUMPS routine space by entering the following MUMPS code: 'R X X X'. The second file contains the reference file, ^ZKRX. The first line is a string of MUMPS code that allows the rest of the file to be loaded according to the proposed MDC standard on interchange of globals. (This code is 'R DATE F I=0:0 R GREF Q:GREF="" R DATA S @GREF=DATA'.). The second line is the date and time the file was written. Follwing this are pairs of lines, the first of each pair being the global reference, and the second being the data to be stored at that reference. The file ends with a null line in place of a global reference. If the file can be opened as a sequential device, the global can be loaded into the MUMPS data space by entering the following MUMPS code: 'R X X X'. The third file contains 'external' comments. These are additional comments, too lengthy to fit in the routine text, which are stored in global ^COMMENT. The first two subscripts in ^COMMENT are the routine name and the label to which the comment applies. The third subscript is always '0', and the fourth level contains text lines, at subscripts 1 by 1. This file is organized and loaded exactly as the second file (reference global). Once the routines and reference global are loaded, it may be necessary to make certain system-dependent changes. See the document 'Adapting Kermit-M to different implementations of MUMPS'. On InterSystems M/11 Version 5 systems, either a) Kermit-M must be loaded into the 'manager' UCI, or b) routine ZKRTC must be moved to the 'manager' UCI and renamed to %ZKRTC, and the two calls to this routine (TTYON+1^ZKR and ZKRC+5^ZKRC) must be edited accordingly. New York State College of Veterinary Medicine Veterinary Computing Facility Kermit-M User's Guide Introduction Kermit is a program that transfers information between different computer systems. The original Kermit was written for the TOPS20 operating system. Since then, Kermits have been developed for Unix, VMS, CMS, RT-11, CP/M, MS-DOS, and Apple DOS. These operating systems run on a wide variety of computers, from micros (Apple II, DEC Rainbow, IBM PC) thru minis (PDP-11, VAX-11) to mainframes (IBM 370, DECSYSTEM-20). Kermit-M is a version of Kermit that is written in MUMPS. The original version is designed for PDP-11 computers running InterSystem's M/11 operating system (version 5). All Kermits communicate with each other. Thus with the development of Kermit-M, it is now possible to transfer routines, globals, and sequential files between our M/11 systems and many other computer systems. For example, you could develop programs in standard MUMPS on an M/11 system, and then download them to a micro-MUMPS system. Or, you could create data files from searches on M/11, and transfer them to a mainframe system or VMS) for statistical analysis. Limitations Kermit can achieve a thruput of about 50 characters per second, which is about 6.5 hours per megabyte; in 20 minutes Kermit could transfer about 50 disk blocks. Clearly, this speed is only acceptable for transferring MUMPS routines or small data files. Over a 9600 bps direct connection, Kermit is about 3 times as fast as over a 1200 bps phone line, i.e. about 150 cps. This speed is still not acceptable for large data files. Industry-standard magnetic tape (9 track, 1/2 inch) is the best method of transferring large quantities of data between systems. System load due to Kermit-M Kermit-M on the NYSCVM MUMPS system is a fairly intensive user of both the processor and the disk or during file transfer to or from other systems, or while Kermit-M files are being transferred to or from MUMPS data structures. Programmers should avoid using Kermit-M during times of heavy system use. Using Kermit-M -- an overview To SEND files to another computer, the basic steps are: 1. transfer from MUMPS data structures (e.g. routines) to the Kermit-M file system (see below). 2. connect to the other computer 3. Issue the SEND command at the Kermit-M end, and the RECEIVE command at the other end 4. break the connection (may involve logging off the other system) To RECEIVE files from another computer: 1. connect to the other computer 2. Issue the RECEIVE command at the Kermit-M end, and the SEND command at the other end 3. break the connection 4. transfer from the Kermit-M file system to MUMPS data structures. Some detailed examples of sessions are given at the end of this document. The Kermit-M file system The file system is a familiar concept to microcomputer and traditional time-sharing system users, but not to most MUMPS programmers. Basically, the data accessible to the program is a set of sequential (line-by-line) files. These may represent globals, routines, or MUMPS sequential files, but they are all stored as a list of lines, separated by . Each file has a unique name, which is separated into two parts: filename.filetype for example, ZKR.ROU The filename names the information, and the filetype gives some indication of what kind of data is in the file. Common filetypes are: .ROU -- a set of MUMPS routines, in %RO/%RI format .MMP -- one micro-MUMPS routine .GLO -- global references and data, in %GO/%GI format .TXT -- text The filename usually represents the MUMPS data structure in some way. For example, file ZKR.ROU might be a set of routines from program ZKR, and file ZKRX.GLO might be ^ZKRX. There are file system commands for managing files: ERASE to delete unwanted files, COPY to make another copy of a file, RENAME to change a file name, and DIRECTORY to see what files are in the file system. As you work in the file system, you are often asked to specify a file or set of files. You may enter an exact file name, or you can use 'wild cards' in either or both of the filename and filetype. The 'wild card' is an asterisk (*) character, which indicates that any (or no) completion of the field is acceptable. For example, Z*.ROU would include all files of filetype 'ROU', and with the initial letter of the filename as 'Z'. *.GLO would include all files with filetype 'GLO' Z*.* would include all files with the initial letter of the filename as 'Z' *.* would include all files in the file system In this way you can deal with logical groups of files with one command, instead of typing each exact file name. Communicating between MUMPS and the Kermit-M file system Since Kermit-M files are what Kermit actually sends and receives, we need some way to get information in these files to and from MUMPS data structures, namely, routines, globals, and sequential files. This is accomplished by the INPUT and OUTPUT options within the MUMPS command of Kermit-M. Accessing Kermit-M There is a separate copy of Kermit-M, including data files, in each UCI in which it resides. Currently, these are : MGR on both systems, ETA (A) and ETB (B). There is a copy in TSA (A); however, this may be a different version than the others (as TSA is the test location). You must get the data you wish to transfer to or from one of these UCI's, preferably, ETA or ETB. Call Kermit-M by signing into a UCI in direct (programmer) mode and: >D ^ZKR When you see the prompt: Kermit-M> you are at the command level. Enter commands using TOPS-20 style (this is for consistency with other Kermits), which is considerably different that the usual MUMPS style. You can enter entire commands, ending with . Or, you can enter the command in parts, ending each section with ; Kermit-M will complete as much of the command as it can and prompt you for more. You can enter '?' at any point in the command to see possible completions. One of the commands is MUMPS. This invokes the Kermit-to-MUMPS interface subprogram, which is organized as a series of menus in conventional MUMPS interactive style. (This command is not necessary or available in other Kermits.) Here is an overview of the functions and commands in Kermit-M: Kermit-M> EXIT or QUIT -- leave Kermit HELP -- information SEND -- send files to another machine RECEIVE -- receive files from another machine SERVER -- take all commands from another machine, e.g. to send or receive files GET,FINISH,BYE -- commands for a remote Kermit server SET -- set up to communicate with other systems CONNECT -- connect to another machine SHOW -- show the current values of SET parameters STATISTICS -- statistics about the most recent transfer MUMPS -- enter the Kermit-M file system and the Kermit-M <--> MUMPS transfer options within the MUMPS command: DIRECTORY of Kermit-M files COPY Kermit-M files RENAME Kermit-M files ERASE Kermit-M files INPUT options (Kermit-M files --> MUMPS data structures) 1. sequential file in (e.g. print, write to tape or SDP) 2. routine input (micro-MUMPS routines) 3. routine input (like %RI) 4. global input (like %GI) 5. sequential global input OUTPUT options (MUMPS data structures --> Kermit-M files) -- inverse of choices 1 to 5 of INPUT options Adapting Kermit-M to different implementations of MUMPS Introduction Kermit-M is an implementation of the KERMIT file transfer program written in 1982 ANSI Standard MUMPS. It uses most of the new language features in the 1982 Standard, including SET $PIECE, subscript indirection, two-argument $PIECE, $EXTRACT, and $ LENGTH, extended pattern matching, and fixed-length READ. It would be a tedious job to translate to the 1977 Standard or non-standard versions of MUMPS. Even within the 1982 Standard, there are many implementations, all of which differ in some important ways for the Kermit implementor. This document explains how to adapt the Kermit-M implementation for your specific MUMPS. Limitations on terminal I/O for all versions Your MUMPS must implement the single-character READ and WRITE commands to terminal lines as follows: READ *A -- 'A' must be returned as the decimal value of the ASCII character read, e.g. CTRL/C is returned as 3. All 128 7-bit codes (0-127) must be readable. WRITE *A -- 'A' must be the decimal ASCII value of the character to be written (inverse of READ *). The MUMPS standard does not state what values are returned by a READ *, nor what values are expected by a WRITE *. In addition, your MUMPS must support the fixed-length READ (which is standard): READ A#COUNT -- read COUNT characters into variable A as text; no explicit terminator of the READ is necessary. Finding implementation-specific code All code that depends on the implementation of MUMPS should be commented at the end of each such line with the comment: ;** version where 'version' is a mnemonic for the MUMPS implementation, e.g. 'M/11 V5' for InterSystems M/11, version 5. There is always at least one other version of the same code, immediately following any 'version' code, which is commented as: ;** STD This means that this code will run on any MUMPS implementation. Note that it might not do anything useful. For example, to open a communications port without echo, the code might be: we might have something like: O TTY:("":"S") ;** M/11 V5 ;open port TTY without echo ;** STD In this case, there is no standard way to turn off echo on a port, so we just you must write your own. Altering the code for your version The code for all implementations except the one you're actually running is commented out at the beginning of each such line. So, locate all lines including the ;** construct, comment out our lines, and remove the comments from the lines for your version. In some cases, you'll have to write detailed code. Other variations in I/O 1) Input and output buffer size When running at high input speeds, incoming packets must be limited to no longer than the length of the system's input buffer. For example, in M/11 V5, the default input buffer length for terminal lines is 64 characters; this is the maximum packet length at high speeds (at 1200 Baud, the program usually empties enough of the buffer to allow maximum length, i.e. 94, packets). The Kermit protocol does not specify any flow control mechanism (e.g. XON/XOFF), so there is no way for MUMPS to inform the other Kermit that the input buffer is about to overflow, which is how this problem is usually solved in ordinary terminal I/O. You can use the SET RECEIVE PACKET-LENGTH command to do this; for a more permanent fix, alter the code in INITPAR^ZKRUM which sets the initial value of RPSIZ. The size of the output buffer is not usually a problem, since most operating systems will suspend a program that tries to do output to a full output buffer, until there is room in the buffer. If not, use the SET SEND PACKET-LENGTH command to set the default output packet size. Note however that the other Kermit can request a different maximum; you might have to use SET RECEIVE PACKET-LENGTH on the other Kermit. 2) Image mode and terminators You must ensure that the SOH character is passed thru the operating system to Kermit. The default SOH is CTRL/A (ASCII 1); if there is a problem with this, the user can SET RECEIVE START-OF-PACKET and SET SEND START-OF-PACKET as necessary; or for a more permanent fix, the code in INITPAR^ZKRUM can be altered. SOH is the usually the only non-printing character sent or received by Kermit. However, if the other end needs padding (which it will request in its Send-init packet or its acknowledgement to Kermit-M's Send-init), we must be able to transmit it thru the operating system. Setting line parameters Kermit-M provides several SET options that must be implemented in a system-specific manner. These include SET PARITY, SET BAUD, and SET DUPLEX. Also, local echo is enabled and disabled in a system-specific manner, and the OPEN, CLOSE, and USE commands are implementation-specific. In some systems, it may not be possible to change parity or baud from within MUMPS; these options should be removed, either by changing ^ZKRX("COMMAND"...) or giving messages like 'can't do that on this system' when trying to execute the command in routine ZKRSET. In M/11 V5, the parity, 8-bit data, and baud can only be set by a program running in the system manager's UCI. Routine ZKRTC, which provides these functions , must reside in this UCI (along with the rest of Kermit). Alternatively, if Kermit is to reside in another UCI, routine ZKRTC must be moved to the system manager's UCI and renamed %ZKRTC, and the calls to ZKRTC (at TTYON+1^ZKR and ZKRC+5^ZKRC) must be modified to call %ZKRTC. You will have to write an analogous routine for other systems. In MUMPS running under other operating systems, you can probably perform these functions with system calls.