IBM VM/CMS KERMIT (Chapter from Kermit User Guide) Page 106 8. IBM VM/CMS KERMIT Program: Daphne Tzoar, Columbia University; contributions from Bob Shields (U. of Maryland), Victor Lee (Queens U.), Gary Bjerke (U. of Texas at Austin), Greg Small (UC Berkeley) Language: CMS Assembler Documentation: Daphne Tzoar, Columbia University Version: 2.01 Date: May 1985 CMS Kermit Capabilities At A Glance: Local operation: No Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes (fixed format) Wildcard send: Yes ^X/^Y interruption: Yes 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: No Act as server: Yes Talk to server: No Advanced server functions: No Advanced commands for servers: No Local file management: Yes Handle Attribute Packets: No Command/init files: Yes Command macros: No Kermit-CMS is a program that implements the KERMIT file transfer protocol for IBM 370-series mainframes (System/370, 303x, 43xx, 308x, etc.) under the VM/CMS operating system. It is written in IBM 370 assembly language. This program runs only over ASCII (asynchronous) lines attached to a 3705-style front end or a Series/1 running the Yale ASCII Terminal Communication System. The program should also work on the IBM 7171 ASCII Device Control Unit and the 4994, al- though this has not been verified as of this writing. For more details on this, see the section SET SERIES1. These systems have several peculiarities that users should be aware of. These are half duplex systems; the communication line must "turn around" before any data can be sent to it. The fact that a packet has been received from the IBM system is no guarantee that it is ready for a reply. Thus any Kermit talking to this system must wait for the line turnaround character (XON) before trans- mitting the next character. It is up to the user to tell the other Kermit that it is talking to an IBM mainframe. IBM VM/CMS KERMIT Page 107 Also, a program running under VM/CMS is unable to interrupt a read on its "console". This means that the CMS version of Kermit cannot timeout. The only way to "timeout" CMS Kermit 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. 8.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 and the concept of records. 8.1.1. File Specifications The VM/CMS file specification is in the form FILENAME FILETYPE FILEMODE (often abbreviated FN FT FM). FILENAME and FILETYPE are at most 8 characters in length each. The name field is the primary identifier for the file. The type is an indicator which, by convention, tells what kind of file we have. For instance TEST FORTRAN is the source of a FORTRAN program named TEST. MODULE is the normal suffix for executable programs. Although some operating systems consider the FILETYPE optional, VM/CMS requires a valid type. There- fore, Kermit-CMS supplies a default type of "X" if one is not provided by the remote system. 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 FILEMODE is omitted from a file specification when sending, a FM of "*" is used. In this case, the users disks are scanned according to the search order and the first occurrence of the file is the one that is sent. If FILEMODE is omitted from a file spec when receiving, a default of "A1" is used. To provide compatibility with most other operating systems, Kermit-CMS sends only the FILENAME and FILETYPE. It also converts the intervening blank to a period. The FN and FT may contain, in any order, uppercase letters, digits, and the special characters "$" (dollar sign), "#" (pound sign), "@" (at sign), "+" (plus), "-" (dash), ":" (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 the letter "X". VM/CMS allows a group of files to be specified in a single file specification by including the special "wildcard" characters, "*" and "%". A "*" matches any string of characters from the current position to the end of the field, includ- ing no characters at all; 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. IBM VM/CMS KERMIT Page 108 % * B All files on the B disk whose FN is exactly one character long. 8.1.2. File Formats Several differences exist between VM/CMS files and those of most other operat- ing systems. One distinction is that CMS encodes its data using the EBCDIC character set. The operating system, VM, translates all incoming characters from ASCII to EBCDIC. Kermit-CMS then translates the data it reads back to AS- CII (characters not representable in ASCII are replaced by a null). This is done in order to correctly calculate the checksum, the method used to guarantee error-free transfer. When Kermit-CMS sends packets, it converts all data back to EBCDIC. Note that the translate tables used by Kermit must correspond to the ones used by the system (VM). The ASCII to EBCDIC translations can be found in the Appendix. Another difference is that VM/CMS stores files as records rather than byte streams. VM/CMS Kermit has to worry about assembling incoming data packets into records and appending carriage return-linefeed to outgoing records. 8.2. Program Operation Kermit-CMS can be invoked at the command line or from an exec. Commands con- sist of one or more fields, separated by spaces. Each field must be eight characters or less. Fields longer than the maximum length are truncated. Upon initial startup, the program looks for two special initialization files, SYSTEM KERMINI and (USERID) KERMINI (that is, the userid of the person running CMS-Kermit.) These files can be placed on any disk. The purpose of these files is to allow Kermit to be customized for a particular system and for a user's specific settings without changing the source code. The file SYSTEM KERMINI should be placed on a publicly accessible disk by a systems programmer. The file would contain commands that all users would need to issue in order for Kermit to run on the system, such as commands to modify the ASCII-to-EBCDIC and EBCDIC-to-ASCII tables used by Kermit-CMS. The file (USERID) KERMINI would contain commands that the user generally issues every time Kermit is run. Kermit-CMS executes any commands found in these files as though they were typed at the terminal. Here is a sample init file: * Asterisk in column one is a comment. set debug on set warning on set block 3 Three CP SET parameters MSG, IMSG and WNG are always set OFF during the actual file transfer (and restored afterwards) to prevent CP from interrupting any I/O in progress. IBM VM/CMS KERMIT Page 109 Interactive Operation: To run Kermit-CMS interactively, invoke the program from CMS by typing "KERMIT". When you see the command's prompt, KERMIT-CMS>. you may type Kermit commands repeatedly until you are ready to exit the program, for example: .KERMIT Kermit CMS Version 2.01 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 During interactive mode, you may use the help ("?") feature while typing Kermit-CMS commands. A question mark typed at almost any point in a command, followed by a carriage return, produces a brief description of what is expected or possible at that point. Command Line Invocation: Kermit-CMS may also be invoked with command line arguments from CMS. For in- stance: .KERMIT send test fortran or .KERMIT set debug on # set file binary # server Kermit will exit and return to CMS after completing the specified command or commands. 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. Kermit will not run under CMSBATCH or disconnected since the user does not actually have a console. Commands can be passed using TAKE files and/or command line arguments. For example, to start up Kermit-CMS and have it act as a server, include the line: IBM VM/CMS KERMIT Page 110 KERMIT server To pass more than one command, they must be stacked in the order in which they are to be executed. To start up a Kermit-CMS server with a three character CRC, include: &STACK set block 3 &STACK server KERMIT Prompts and messages will still be displayed on the screen. 8.3. Kermit-CMS Commands Here's a brief summary of CMS Kermit commands: CMS executes a CMS command. CP executes a CP command. EXIT from Kermit-CMS. HELP about Kermit-CMS. QUIT from Kermit-CMS RECEIVE files from other Kermit. SEND files to other Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. STATUS inquiry. TAKE commands from file. TDUMP dumps the contents of a particular table. The remainder of this section concentrates on the commands that have special form or meaning for CMS Kermit. THE SEND COMMAND Syntax: SEND filespec The SEND command causes a file or file group to be sent from the CMS system to the Kermit on the remote system. filespec takes the form: filename filetype [filemode] 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 CMS Kermit encounters, according to the disk search order, is sent. 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 and Control-Z respec- tively. IBM VM/CMS KERMIT Page 111 THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-CMS to receive a file or file group from the other system. You should then issue a SEND command to the remote Kermit. The format of the 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 excessive characters from it, and will change illegal characters to the letter X. Use the file specification to indicate that the incoming file should be stored under a different name. The filespec may include a filemode to designate the destination disk. If none is provided, the file will be saved with fm A1. If you want to use the same name but a different filemode, specify = = FM. Wildcards may not be used in any field. 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 A disk. If, however, = = FM is used, all files will be placed onto the specified disk. When receiving files, if the record format is fixed, any record longer than the logical record length will be split up to as many records as necessary. If the record format is variable, the record length can be as high as 64K. For send- ing files, the maximum record length is 64K. See the SET LRECL and SET RECFM commands. 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 remote system, Kermit-CMS will discard whatever had arrived. If the incoming file has the same name as a file that already exists, and WARN- ING is OFF, the original file will be overwritten. If WARNING is set ON, Kermit-CMS will change the incoming name so as not to obliterate the pre-exist- ing file. It attempts to rename the file by replacing the first character with a dollar sign ($). If a file by that name exists, it also replaces the second character with a dollar sign. It continues in this manner for all characters of the filename and filetype. If the file cannot be renamed, the transfer fails. THE TAKE COMMAND Syntax: TAKE filespec Execute Kermit commands from the specified file, where filespec has the format fn ft [fm]. The command file may include TAKE commands. IBM VM/CMS KERMIT Page 112 THE SERVER COMMAND Kermit-CMS is capable of acting as a server. The user connects to the CMS sys- tem once to set various options and to start the server. From then on, he need not connect to the CMS system again. The current version of Kermit-CMS can send files (the user on the other end types the GET command, using either a space or a period as the delimiter between filename, filetype, and filemode), receive files (the user types SEND), and terminate by either returning to CMS (user types FINISH) or logging the user out (user types BYE). To put Kermit-CMS into server mode, first issue any desired SET commands to select various options and then type the SERVER command. Kermit-CMS will await all further instructions from the user Kermit on the other end of the connec- tion. For example: KERMIT-CMS>.set warning on KERMIT-CMS>.set debug on KERMIT-CMS>.set block 3 KERMIT-CMS>.server THE SET COMMAND Syntax: SET parameter [value] Establish or modify various parameters for file transfer. You can examine their values with the SHOW command. The following SET commands are available in Kermit-CMS: ATOE Modify ASCII-to-EBCDIC table used by Kermit-CMS BLOCK Level of error checking for file transfer DEBUG Log packets sent and received during file transfer END-OF-LINE Packet terminator ETOA Modify EBCDIC-to-ASCII table used by Kermit-CMS FILE Type of incoming or outgoing file LRECL Logical Record length for incoming file PACKET-SIZE Maximum receive packet size QUOTE Use to quote outgoing control characters RECFM Record format for incoming files SERIES1 Indicate if coming in via a Series/1 WARNING Specify how to handle filename collisions SET ATOE Syntax: SET ATOE num1 num2 This command allows you to modify the ASCII-to-EBCDIC translate table used by Kermit-CMS to conform to your system. Specify the offset of the ASCII value within the table and the new value for that location. Both num1 and num2 should be between 0 and 255 (decimal). Note that the table is twice as long as necessary because the translate instruction expects a table that contains 256 characters. IBM VM/CMS KERMIT Page 113 SET BLOCK SYNTAX: SET BLOCK number Determine the type of block check used during file transfer. Valid options for number are: 1 (for a one character checksum), 2 (for a two character checksum) and 3 (for a three character CRC). SET DEBUG Syntax: SET DEBUG ON or OFF ON Keep a journal of all packets sent and received in the file KER LOG A1. If the file already exists, it is overwritten. OFF Stop logging the packets. SET END-OF-LINE Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than car- riage return, specify the decimal value of the desired ASCII character. number must be between 0 and 31 (decimal). SET ETOA Syntax: SET ETOA num1 num2 This command allows you to modify the EBCDIC-to-ASCII translate table used by Kermit-CMS to conform to your system. Specify the offset of the EBCDIC value within the table and the new ASCII value for that location. Both num1 and num2 should be between 0 and 255 (decimal). SET FILE Syntax: SET FILE BINARY or TEXT BINARY Tells CMS Kermit to treat each character as a string of bits and not to perform translation on the data. Also, no carriage-return is added to the end of outgoing records. Incoming bytes are added to the end of the current record which is written out when the specified LRECL is reached. TEXT Tells CMS Kermit that the file is plain text. ASCII-to-EBCDIC and EBCDIC-to-ASCII translation is performed on the data. Carriage return-linefeed are appended to outgoing records and are used to deter- mine the end of incoming records. IBM VM/CMS KERMIT Page 114 SET LRECL Syntax: SET LRECL number Set the logical record length for incoming files to a number from 1 to 65536 (64K). This variable is used only for fixed format files. The default is 80. SET PACKET-SIZE Syntax: SET PACKET-SIZE number Use the specified number as the maximum length for incoming packets. The valid range is 26-94, where 94 is the default. SET QUOTE Syntax: SET QUOTE char Use the indicated printable character for prefixing (quoting) control charac- ters and other prefix characters. The only reason to change this would be for sending a very long file that contains very many "#" characters (the normal control prefix) as data. It must be a single character in the range: 33-62, 96, or 123-126 (decimal). SET RECFM Syntax: SET RECFM option Set the record format to use for incoming files. Valid options are "F" for fixed format or "V" for variable format. The default is variable. SET SERIES1 Syntax: SET SERIES1 ON or OFF Kermit-CMS automatically determines whether you are connected via a Series/1 emulation controller or a TTY line. This command is provided though so you can override Kermit-CMS. When you SET SERIES1 ON, Kermit disables the 3270 protocol conversion function by putting the Series/1 into "transparent mode"; this allows Kermit packets to pass through the Series/1 intact. SET WARNING Syntax: SET WARNING ON or OFF ON If an incoming file has the same name as an existing file on the specified disk, Kermit will attempt to rename the incoming file so as not to destroy (overwrite) the pre-existing one. OFF Upon a filename collision, the existing file will be replaced by the incoming file. IBM VM/CMS KERMIT Page 115 THE SHOW COMMAND Syntax: SHOW option Use to display the values of all parameters that can be changed with the SET command, except for ATOE and ETOA (see the TDUMP command). option can be a particular parameter or the keyword "ALL". THE STATUS COMMAND Syntax: STATUS Returns the status of the previous command. The response will either display the message "Kermit completed successfully", or the last error encountered. THE TDUMP COMMAND Syntax: TDUMP table-name Display the contents of table-name since it can be modified using the SET com- mand. The ATOE and ETOA tables can presently be 'dumped'. CP AND CMS COMMANDS Syntax: CP text of command CMS text of command Although Kermit-CMS does not provide explicit commands for managing local files or interacting with the operating system, it is possible to do so. You can is- sue any CP or CMS command, though each word will be truncated to eight charac- ters. You can list, type, rename or delete files, send messages and so on. At this time, though, you cannot run another program from Kermit-CMS. 8.4. Before Connecting to the Mainframe When connecting to the CMS system as a TTY device ("line at a time" mode) several flags must first be set on the micro version of Kermit. You should set the LOCAL-ECHO flag to ON (this is used to indicate half-duplex). This is the norm but not true in every case; if each character appears twice, set the LOCAL-ECHO flag OFF. HANDSHAKE should be set to XON and FLOW-CONTROL should be set to NONE. The parity should be set according to the system's specifica- tions. On some micro versions of Kermit, all of the above is done in one step using the DO IBM macro (or SET IBM ON). Set the baud rate to correspond to the line speed. When connecting to the CMS system through the Series/1 terminal emulation con- troller ("full-screen" mode), certain flags must be set on the micro version of Kermit. You should set the LOCAL-ECHO flag to OFF (this is used to indicate full-duplex). HANDSHAKE should be set to OFF and FLOW-CONTROL should be set to XON/XOFF. For most systems, the PARITY should be set to EVEN. Set the baud rate to correspond to the line speed. Immediately after issuing a SEND, RECEIVE or SERVER command to Kermit-CMS, the screen will be cleared. This is IBM VM/CMS KERMIT Page 116 to make sure the terminal is not stuck in a MORE or HOLDING state before pack- ets are sent via the full-screen I/O operation. After the file transfer is complete, and you re-connect to Kermit-CMS, you should enter the Series/1 "Master Reset" sequence (probably "CTRL-G") so that the screen is refreshed. 8.5. How to build an executable version of Kermit-CMS Kermit-CMS is composed of three assembly language source files that are as- sembled separately and then linked together. They are: KERMIT, NEXTFST, and WILD. To create a runnable version: 1. GLOBAL the necessary MACLIBs. For SP, the MACLIBs used are DMSSP, CMSLIB and TSOMAC. 2. Make sure the source files are named as listed above and are saved on disk in fixed format with a logical record length of 80. 3. Assemble the three source files. 4. Load the files into memory via: LOAD KERMIT 5. Create a runnable version called KERMIT MODULE via: GENMOD KERMIT 6. If your site's ASCII/EBCDIC translation table 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 ap- propriate SET ATOE/ETOA commands in the SYSTEM KERMINI file. Note that if the ASCII/EBCDIC translation is not invertible, Kermit will not and cannot work. To run CMS Kermit, simply type "KERMIT" to the CMS system prompt. 8.6. What's New Below is a list of the more important additions in Version 2.01 of CMS Kermit: 1. Add prefixing of the "8th bit". This allows CMS Kermit to send or receive fixed format binary data, such as microcomputer binary files. 2. The maximum record length allowed has been increased to 64K for both incoming and outgoing files. 3. Repeat count prefixing has been added to speed up transmission. In addition, Kermit-CMS now packs as much data as possible into an out- going packet rather than one packet per record (it makes a big difference). 4. Support for two character checksum and three character CRC. 5. If filetype is not supplied by the remote Kermit, use a default of "X" rather than failing. Also allow the option to rename an incom- ing file upon filename collision. IBM VM/CMS KERMIT Page 117 6. Add debugging mode to log packets and to acknowledge the attention if the user types a BREAK. Add a SHOW ALL command. 7. Allow input to command parser from command line. Multiple commands should be separated by the linend character. After execution of these commands, Kermit returns control to CMS. 8. Add support for Series/1 front end. 9. Add server support. 10. Upon startup, read commands from two init files: SYSTEM KERMINI and (USERID) KERMINI (that is the userid of the person running Kermit). Lines with an asterisk as the first character are comments. Add the TAKE command. The LRECL for these files must be 130 or less. 11. Implement skip file or file group when sending or receiving (in this case, discard incoming file). 12. Allow system manager to change ASCII/EBCDIC translation tables to conform to the various specifications of different systems. Also, bypass user translate tables when sending and receiving data. 8.7. What's Missing Work on Kermit-CMS will continue. Features that need to be improved or added include: - Allow timeouts so CMS Kermit does not wait forever if a packet does not arrive in a timely fashion. - Allow any binary file to be sent and received properly, not only fixed format binary files. - Better keyword parsing, which is rather crude at this time. - Support of the more advanced server functions. - Addition of a RUN command. - Ability to SET LINE, so that Kermit-CMS can be used as a local Ker- mit, connecting to a remote host over another communication port.