1. IBM VM/CMS KERMIT Program: John Chandler (Harvard/Smithsonian Center for Astrophysics); con- tributions from Vace Kundakci and Daphne Tzoar (Columbia U), Bob Shields (U. Maryland), Victor Lee (Queens U.), Gary Bjerke (U. Texas at Austin), Greg Small (UC Berkeley), Clark Frazier (Harvard Bus. Sch.), Bob Bolch and Steve Blankinship (Triangle), Ron Rusnak (U. Chicago), Andre Pirard (U. Liege) Language: IBM/370 Assembler Documentation: John Chandler (CfA) Version: 4.0 (87/12/17) Date: 1987 December Kermit-CMS Capabilities At A Glance: Local operation: No Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Z interruption: Yes (through micro) Filename collision avoidance: Yes Can time out: No 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: No Communication settings: No Transmit BREAK: No Transaction logging: Yes Session logging: No Raw transmit: Yes (no prompts) Sliding window: No Long packets: Yes Act as server: Yes Talk to server: Yes Advanced server functions: Yes Advanced commands for servers: Yes Local file management: Yes Handle Attribute Packets: Yes Command/init files: Yes Command macros: No Kermit-CMS is a member of the generic Kermit-370 family and shares most of the features and capabilities of the group. As its name implies, Kermit-CMS is the version of Kermit-370 that runs under the VM/CMS operating system. The primary documentation for Kermit-CMS is actually the chapter on Kermit-370, which describes general properties; the present chapter assumes the reader is familiar with that material. Only the details specific to CMS operation will be discussed here, e.g., command syntax relating to the CMS file system or com- mands not offered in general by Kermit-370. CMS Specifics of Kermit-370: Global INIT file: SYSTEM KERMINI * User INIT file: KERMINI * Debug packet log: KER LOG A1 Server reply log: KER REPLY A1 Maximum packet size: 1920 Maximum disk LRECL: 65535 1.1. The VM/CMS File System The features of the CMS file system of greatest interest to Kermit users are the format of file specifications (or filespecs) and the concept of records. The latter is described in the Kermit-370 chapter. The VM/CMS filespec takes the form filename filetype filemode (often abbreviated FN FT FM). The filename and filetype are one to eight characters each. The name field is the primary identifier for the file, and the type is an indicator which, by convention, tells what kind of file it is. For instance, TEST FORTRAN is the source of a Fortran program named TEST. MODULE is the filetype for executable programs (as distinct from object code, which has a filetype of TEXT!). Although some operating systems consider the filetype optional, VM/CMS requires a type for each file. Therefore, Kermit-CMS supplies a default type of "$" for any received file if no type is provided by the remote system. The same default is used for a missing filename. At the same time, the FN and FT are forced to conform to CMS rules in other respects. The FN and FT may contain, in any order, uppercase letters, digits, and the special characters "$" (dollar sign), "#" (pound sign), "@" (at sign), "+" (plus), "-" (hyphen), ":" (colon), and "_" (underscore). Other characters may be not be included. If an invalid character is found in the FN or FT field, it is replaced by an underscore (or converted to uppercase if it is a lowercase letter). Also, both FN and FT are truncated, if necessary, to eight charac- ters. The filemode, which consists of a letter and a number, is similar to a device specification on microcomputer systems: FN FT FM would translate to FM:FN.FT in CP/M or MS-DOS if the filemode number is ignored. Indeed, the filemode number is more properly an attribute of a file than part of its name -- no two files can co-exist with names that match all but the filemode number. Even the filemode letter is not a fixed part of the filespec because the same mini-disk could be accessed under a different mode letter. In some ways, the filemode letter is also like a disk directory designator, since many such mini-disks may reside on the same disk drive. For this reason, the Kermit concept of the "working directory" is equated with a particular disk mode letter under Kermit-CMS. The current "working directory" is, thus, the "home" filemode (normally "A", which is the primary user mini-disk under CMS), and file trans- fers take place preferentially to and from the "home" disk. If the filemode is omitted from a filespec when sending, the "home" disk is normally used, but there is an option for using a default of "*" instead. In this case, the user's disks are scanned according to the search order and the first occurrence of the file is the one that is sent. If the filemode is omitted from a filespec when receiving, the "home" disk is used with a filemode number of "1". To provide compatibility with other operating systems, when Kermit-CMS sends a file, it ordinarily makes a file header with only the filename and filetype. It also converts the intervening blank to a period. On the other hand, extra information may be added by way of the SET FOREIGN subcommand. VM/CMS allows a group of files to be specified in a single filespec by includ- ing the special "wildcard" characters "*" and "%". A "*" matches any string of characters (even a null string) from the current position to the end of the field; a "%" matches any single character. Here are some examples: * COBOL A All files of type COBOL (all COBOL source files) on the A disk. F* * * All files whose names start with F. % * B All B-disk files with one-character FN's. CMS files, like those in other IBM 370 systems, are record-oriented (see the introduction to the Kermit-370 chapter). In particular, CMS files are charac- terized by record format (RECFM), which may be fixed-length or varying-length, and by maximum record length (LRECL). The size of record blocks is irrelevant, however, because CMS performs the blocking and deblocking operations automati- cally and transparently, including the spanning of records across block boun- daries. Records in CMS files may be up to 65535 bytes long. 1.2. Program Operation At startup time, Kermit-CMS looks for two initialization files, SYSTEM KERMINI and KERMINI (where is the user's logon ID). If either of these files exists on more than one disk, it will be read and executed from the first copy in the search order. The file SYSTEM KERMINI should be placed on a publicly accessible disk by a systems programmer, preferably the same disk where the Kermit executable module is kept. The file KERMINI can be maintained by the user on any convenient disk. One important distinction between Kermit-CMS and other Kermits is that a program running under VM/CMS is unable to interrupt a read on its "console". This means that the CMS version of Kermit cannot time out after sending a packet. The only way to time out is from the other side: typing a carriage return to the local Kermit causing it to retransmit its last packet, or an automatic timeout as provided by most other Kermits. Five CP SET parameters (MSG, IMSG, WNG, ACNT, and TIMER) are set OFF during protocol mode (and restored afterwards) to prevent CP from interrupting any I/O in progress, and RUN is set ON to ensure that Kermit can recover from acciden- tal attention interrupts. Also, on a TTY line, the TERMINAL LINESIZE is set OFF to prevent CP from inserting carriage return-linefeed pairs into packets, TERMINAL SCROLL is set to CONT to prevent CP pauses, LINEDIT is set OFF to en- sure that all characters are taken literally, and the CMS user terminal trans- lation tables (established via the CMS SET INPUT and OUTPUT commands) are tem- porarily suppressed for both short and long packet protocols. The settings in effect when Kermit starts up are saved as a sort of "normal" status snapshot (as opposed to the "protocol" status just described). The protocol status is selected whenever Kermit enters protocol mode and also after Kermit executes a CP command in server mode. Similarly, normal status is selected when Kermit leaves protocol mode and before Kermit executes a CP command in server mode. Note: if Kermit is interrupted in the midst of a transfer or while in server mode, these parameters will be left with peculiar settings (namely, the protocol status), and they may need to be restored by hand. CMS is different from some other IBM mainframe systems in that allows a program to take control of prompting and synchronization on "TTY" lines. Kermit-CMS takes advantage of this option, and it is not, in general, necessary to enable handshaking on the micro Kermit before connecting to CMS. In other words, handshaking should be suppressed for both "TTY" and "SERIES1" devices (the micro Kermit should have HANDSHAKE set OFF, and Kermit-CMS should have HAND- SHAKE set to 0). Since the generic Kermit-370 default handshake (XON) is retained in Kermit-CMS, the subcommand "SET HANDSHAKE 0" is a good candidate for inclusion in SYSTEM KERMINI. Interactive Operation: To run Kermit-CMS interactively, invoke the program from CMS by typing KERMIT. When you see the prompt, Kermit-CMS> you may type a Kermit subcommand. The cycle repeats until you exit from the program. For example: KERMIT Kermit-CMS Version 4.0 (87/12/17) Enter ? for a list of valid commands Kermit-CMS>send foo * Files with fn FOO are sent Kermit-CMS>receive test spss File is received and called TEST SPSS A1 Kermit-CMS>exit The prompt string under CMS is truly interactive. In other words, the string (without carriage return or linefeed) appears only when fresh input is needed from the terminal. If, for example, Kermit is invoked after several subcom- mands have been stacked up, the stack is read and executed before the first prompt appears. Command Line Invocation: Kermit-CMS may also be invoked with command line arguments from CMS. The ar- guments are interpreted as one or more subcommands to be executed by Kermit after completion of the initialization. For instance: KERMIT send test fortran or KERMIT set debug on # set file binary # server Kermit will exit and return to CMS after completing the specified subcommand or subcommands. Note that several commands may be given on the command line as long as they are separated by the LINEND character, which is pound sign in this case. The command line may contain up to 130 characters. EXEC Operation: Like other CMS programs, Kermit-CMS may be invoked from a CMS EXEC. Subcom- mands can be passed to Kermit using the program stack and/or command line ar- guments. For example, to start up Kermit-CMS and have it act as a server, in- clude the line: KERMIT server To pass more than one subcommand, they must be stacked in the order in which they are to be executed. To start up a Kermit-CMS server with a three charac- ter CRC, include: &STACK set block 3 &STACK server KERMIT Another way of setting up multiple subcommands would be to collect the subcom- mands into a TAKE file and then issue the TAKE subcommand via the command line or program stack. Of course, EXEC's may be executed from Kermit, either directly or from a TAKE file, and Kermit subcommands, in turn, may be issued from EXEC's as long as Kermit is active. See the TAKE subcommand for more details. Server mode: Command execution in server mode is different in several respects from normal operation. First of all, some Kermit subcommands are not allowed (see the list of subcommands in the Kermit-370 chapter). Moreover, command errors always terminate any active TAKE file. Also, commands other than CP commands run in a special environment with RUN ON, TIMER OFF, and so forth. Another difference is that Kermit intercepts all SVC instructions in order to catch console I/O and transmit the data to the local Kermit as text packets. Since Kermit does not emulate the substitution functions of the LINEDIT macro, some messages will appear rather cryptic. A more serious problem with this redirection is that some VM/CMS system commands may issue console I/O directly to CP, so that some messages never appear to the local Kermit (except, perhaps, as bad packets). For non-TTY terminals, such messages are stacked up in the console output queue and appear all at once when Kermit returns from server mode. 1.3. Kermit-CMS Subcommands Kermit-CMS supports all the subcommands described in the corresponding section of the Kermit-370 chapter. In addition, there are two more, both of which can be issued as remote Kermit commands when Kermit-CMS is in server mode. The first is CMS, which is just a synonym for the generic HOST subcommand. The second is CP, which specifically issues a command to CP. In most cir- cumstances, the latter is not needed, since CMS will pass along CP commands to CP. The remainder of this section concentrates on the subcommands that have special form or meaning for Kermit-CMS. See also the chapter on Kermit-370 for further details. THE SEND SUBCOMMAND Syntax: SEND filespec [foreign-filespec] The SEND subcommand causes a file or file group to be sent from CMS to the Ker- mit on the other system. filespec takes the form: filename filetype [filemode] but the filemode if optional only if the foreign-filespec is omitted. filespec may contain the wildcard characters "*" or "%". If filespec contains wildcard characters then all matching files will be sent. If, however, a file exists by the same name on more than one disk, only the first one Kermit-CMS encounters, according to the disk search order, is sent. See also the CWD sub- command. The foreign-filespec, if any, is used for the file header of the outgoing file, replacing the usual filename.filetype copied from the CMS filespec. It may take one of two forms: filename filetype or arbitrary-string Normally, this form of the SEND subcommand is used only for single files be- cause the foreign-filespec is used only for the first file of a group (subsequent files having default headers). However, in the two-token form of the foreign-filespec either the name or type may be an Equals sign "=" to sig- nify that the corresponding CMS name or type is to be retained in the file header. In that case, the partial renaming carries through an entire group of files. It is the user's responsibility to prevent such partial renaming from sending duplicate file headers within a file group. Although the file transfer cannot be cancelled from the CMS side, Kermit-CMS is capable of responding to "cancel file" or "cancel batch" signals from the local Kermit; these are typically entered by typing Control-X or Control-Z, respec- tively. THE RECEIVE SUBCOMMAND Syntax: RECEIVE [filespec] The RECEIVE subcommand tells Kermit to receive a file or file group from the other system. You should then issue a SEND subcommand to the other Kermit. The format of filespec is: filename filetype [filemode] If the optional filespec is not included, Kermit-CMS will use the name(s) provided by the other Kermit. If that name is not a legal CMS file name, Kermit-CMS will delete excess characters and will change illegal characters to underscores. A filespec in the subcommand indicates what name the incoming file should be given. The filespec may include a filemode to designate the destination disk. If none is provided, the file will be saved on the "home" disk with filemode number "1". If you want to use the same name but a dif- ferent filemode, specify "= = FM". Wildcards may not be used. If the optional filespec is provided, but more than one file arrives, the first file will be stored under the given filespec, and the remainder will be stored under their own names on the "home" disk. If, however, "= = FM" is used, all files will be placed onto the specified disk. When the record format is fixed, any received record longer than the logical record length (LRECL) will be truncated, and shorter records will be padded. The padding character is a blank for text files and a null for binary files. Received binary (but not V-binary or D-binary) files are treated as byte streams and broken up into records all of the logical record length. See the SET FILE TYPE, SET FILE LRECL, and SET FILE RECFM subcommands. If an error occurs during the file transfer, as much of the file as was received is saved on disk. If the sending of a file is cancelled by the user of the foreign system, Kermit-CMS will discard whatever had arrived, unless AP- PEND is ON or INCOMPLETE is KEEP. If the incoming file has the same name as an existing file, and WARNING is OFF, the original file will be overwritten. If WARNING is set ON, however, Kermit-CMS will change the incoming name so as not to obliterate the pre-exist- ing file. It attempts to find a unique name by successively modifying the original and checking for the existence of such a file at each step. The pro- cedure begins by truncating the filetype to six characters if necessary, and then appending "$0". If a file by that name exists, Kermit then replaces the "0" with a "1". It continues in this manner up to "9", and if an unused name cannot be found, the transfer fails. THE GET SUBCOMMAND Syntax: GET foreign-filespec [filespec] The GET subcommand tells Kermit to request a file or file group from the other system, which must have a Kermit running in server mode. The syntax is compli- cated by the allowance of two forms for the foreign-filespec, just as in the SEND subcommand. Here the parsing is based on the number of "words" (blank-delimited strings) in the subcommand argument, which can be anything from one to five. If the number is anything but four, the interpretation is unambiguous, but when there are four words, the first word plays the key role. If it has more than eight characters or contains a "." or "/", it is assumed to be the whole foreign-filespec; otherwise, it is assumed to be the first of two words that, when joined by a ".", make up the filespec on the other system. THE TAKE SUBCOMMAND Syntax: TAKE filespec Execute Kermit subcommands from the specified file, where filespec has the for- mat fn [ft [fm]]. The default filetype is "TAKE", and the default filemode is "*". Kermit subcommands may also be executed from CMS EXEC's, so that the TAKE sub- command is, in a sense, superfluous under VM/CMS. In CMS terminology, Kermit establishes a Kermit subcommand environment, and EXEC's written in EXEC 2 or REXX may invoke subcommands within that environment. For example, to display the current packet checksum type, an EXEC 2 would issue &SUBCOMMAND KERMIT SHOW BLOCK-CHECK and a REXX macro would issue Address KERMIT 'SHOW BLOCK-CHECK' There is one important difference between executing a TAKE file and an EXEC: the former may issue a QUIT or EXIT subcommand, but the latter may not. Also, a Kermit subcommand issued from an EXEC returns a completion code according to the current error status (see the table under "After Kermit Completes" in the Kermit-370 chapter). An EXEC could therefore be set up to react appropriately to file transmission errors or other unpredictable events. THE SET SUBCOMMAND Syntax: SET parameter [value] The SET subcommand establishes or modifies various parameters controlling file transfers. The following SET subcommands are available in Kermit-CMS, but not in Kermit-370 in general: DESTINATION "Home" disk. FILE LRECL Logical Record length for incoming file. RECFM Record format for incoming files. SEARCH-ALL Determine the default disk search scope. SET DESTINATION Syntax: SET DESTINATION letter This subcommand is equivalent to the CWD subcommand (q.v.). SET FILE LRECL Syntax: SET FILE LRECL number This sets the logical record length for incoming files to a number from 1 to 65535 (64K-1). This variable is used only for fixed format and binary files. The default is 80. SET FILE RECFM Syntax: SET FILE RECFM option This sets the record format to use for incoming files. Valid options are "Fixed" and "Variable" (the default). Fixed-format records are padded or trun- cated, as needed, to the current LRECL. SET SEARCH-ALL Syntax: SET SEARCH-ALL ON or OFF ON If the user omits the filemode from a SEND subcommand (or a GET request to the other Kermit), Kermit-CMS will search all accessed disks for the named file or files. OFF If the filemode is not specified, only the "home" disk and its read-only extensions will be searched for matching files. (Default.) THE CWD SUBCOMMAND Syntax: CWD letter The CWD (Change Working Directory) subcommand establishes a new default ("home") CMS disk. letter may be the mode letter of any accessed disk. Sub- sequent file transfers take place preferentially to and from the default disk. The initial home disk is "A". THE DIRECTORY SUBCOMMAND Syntax: DIRECTORY [filespec] Under Kermit-CMS, the DIRECTORY subcommand is identical to the CMS LISTFILE command. THE SPACE SUBCOMMAND Syntax: SPACE [letter] This subcommand displays the storage allocation on the specified CMS disk. If letter is omitted, the default disk specified by the CWD subcommand is dis- played. Aside from this default, the subcommand is identical with CMS QUERY DISK. THE GIVE SUBCOMMAND Syntax: GIVE table-name filespec This subcommand compares the named table with its default values and saves the differences in a TAKE file named filespec. The format of filespec is fn [ft [fm]]. The default filetype is "TAKE", and the default filemode is that of the "home" disk. See the CWD subcommand. THE CP AND CMS SUBCOMMANDS Syntax: CP or CMS text of command Although Kermit-CMS does not have a full set of its own subcommands for manag- ing local files, it provides those services through the operating system. You can issue any CP or CMS command, but if Kermit-CMS has been invoked as a normal user-area program, rather than as a high-memory "resident" program or nucleus extension, other user-area CMS commands (such as COPYFILE) are illegal. Even then, you can list, type, rename or delete files, send messages, and so on. The CMS subcommand under Kermit is synonymous with the HOST subcommand. 1.4. How to build an executable version of Kermit-CMS Before attempting to build Kermit-CMS, look in the Kermit distribution under both IK0KER and IKCKER for an installation document, as well as "beware", help, and update files, and read them first. They will probably contain information that is more current than what you see here. Kermit-CMS consists at present of a large assembly and a small optional one. The large assembly (KERMIT ASSEMBLE) contains the Kermit program, and the small one (KERMBOOT ASSEMBLE) is a bootstrap program for loading Kermit into high memory and running it. Although KERMBOOT is all in one file in the Kermit dis- tribution, the source for Kermit itself is in many pieces, some generic for Kermit-370 and some specific to CMS. All the necessary pieces are sequenced in columns 73-80 so that the numbers form a strictly increasing sequence when the pieces are correctly "pasted" together. It is important to preserve the original sequence numbers so that updates, if any, can be applied to the source. To create a runnable version: 1. Combine the following "ASM" files from the Kermit distribution into a single file with RECFM F and LRECL 80: IK0DOC, IK0MAC, IKCMAC, IK0DEF, IK0MAI, IK0CMD, IK0COM, IKCUTL, and IK0PRO. The resulting file is the composite source for Kermit-CMS, called KERMIT ASSEMBLE. This source must retain the original sequence numbers in columns 73-80 (in other words, be sure not to resequence the source acciden- tally by using the editor!) 2. Copy or rename IKCBOO ASM from the Kermit distribution (if desired) to a file called KERMBOOT ASSEMBLE with RECFM F and LRECL 80. 3. GLOBAL the necessary MACLIBs. Under VM/SP, these are DMSSP, CMSLIB, OSMACRO, and TSOMAC. 4. Assemble the source file(s). 5. Load one file into memory via: LOAD KERMIT or LOAD KERMBOOT. In the former case, the entire Kermit program is now loaded; in the latter, only a bootstrap program which expects to find the object file KER- MIT TEXT at run time. Under CMS/SP Release 4 and above, there is a third and better option, namely, LOAD KERMIT (RLDSAVE). 6. Create the executable called KERMIT MODULE via: GENMOD KERMIT. Al- ternatively (under CMS/SP Release 3 and below), create both KERMIT and KERMBOOT modules to give the user a choice of user-area or high-memory execution. Since Kermit-CMS is serially reusable, it can be reinvoked in the user area with the START command, but the high-memory version must be reloaded each time. If Kermit is loaded using the RLDSAVE option (Release 4 and above), the module can, in fact, be run either way; the command NUCXLOAD KERMIT will load Ker- mit "permanently" into high memory for invocation at need. 7. If your site's ASCII/EBCDIC translation table for TTY lines does not conform to the one listed in the appendix (which in turn conforms to the one given in the IBM System/370 Reference Summary), then enter the appropriate SET ATOE/ETOA/TATOE/TETOA subcommands in the SYSTEM KERMINI file, which should reside on the same disk as KERMIT MODULE (and KERMIT TEXT). NOTE: If the ASCII/EBCDIC translation is not in- vertible, Kermit will not and cannot work. 1.5. What's New Below is a list of the more important CMS-specific features in Version 4.0 of Kermit-CMS added since the previous release, Version 3.1, in September 1986. For the list of generic additions, see the chapter on Kermit-370. 1. System commands issued through Kermit via the CMS or HOST subcom- mands are automatically passed on to CP if (a) CMS rejects them and (b) IMPCP is set ON. 2. Kermit subcommands may be executed directly from CMS EXEC's. 3. Reject files known (via A-packets) to be too big for available storage. 4. Bypass user translation tables and set TERMINAL SCROLL CONT for protocol mode on TTY lines. 5. KERMBOOT avoids the loading problem (VIRTUAL STORAGE CAPACITY EXCEEDED) due to large GLOBAL TXTLIB's and preserves the untokenized command line so that Kermit may be given mixed-case or long words as part of the initial command. 1.6. What's Missing Work on Kermit-CMS will continue. Features that need to be improved or added include: - Allow timeouts so Kermit-CMS does not wait forever if a packet does not arrive in a timely fashion. This is not possible under CMS at present. - Detect file properties from Attribute packets and allow overriding current parameter settings. Also implement file archiving. - Add a SET REPEAT subcommand. - Finish SET LINE, so that Kermit-CMS can be used as a local Kermit, connecting to a remote host over another communication port. Add a CONNECT subcommand. - Intercept CP messages during protocol mode, rather than just sup- pressing them. Display the messages later or log them or send in packets as appropriate. - Define EXEC variables from Kermit by analogy with the XEDIT EXTRACT subcommand.