107/10/84 KERMIT-TSO 1. Introduction KERMIT is a set of programs that transfer files between computers over normal terminal communication lines. It implements the "KL10 Error-Free Reciprocol Microcomputer Interchange over TTY-Lines" protocol. Originally designed to be used between a microcomputer and the DEC-20, the protocol will also transfer files to and from a microcomputer and IBM mainframe systems running under MVS/TSO. KERMIT transfers data by creating packets with information regarding the type of packet being sent, it's length, a packet number, and a checksum to determine whether the data has been modified during transmission. If a packet is lost or garbled, KERMIT will attempt to resend it. Written in IBM 370 assembly language to run under MVS/TSO on IBM 370-series mainframes (System/370, 303x, 43xx, 308x, ...). 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 transmitting the next character. IBM systems talk to their terminals through a communications front end (IBM 3705, 3725, COMTEN 3670, etc). These front ends generally insist on using the 8th bit of each character for parity. This means that binary files (files con-taining other than ordinary letters, digits, punctuation, carriage returns, tabs, and so forth) can not be correctly sent or received by these systems with Kermit (protocol version 1). The IBM system under MVS/TSO is unable to interrupt a read on its "console". This means that the IBM version of Kermit cannot timeout. The only way to "timeout" TSO Kermit is from the other side -- typing a carriage return to the micro's Kermit causing it to retransmit its last packet, or an automatic timeout as provided by Kermit-20. For this reason, TSO Kermit waits thirty seconds before sending its first packet when sending files from MVS/TSO. This gives the user sufficient time to return to the local Kermit and issue the Receive command. Otherwise, a protocol deadlock would arise requiring manual intervention by the user. Also, MVS/TSO stores files as records rather byte streams. MVS/TSO Kermit has to worry about assembling incoming data packets into records and stripping CRLFs from incoming lines, and also appending CRLFs to - and stripping trailing blanks from -- outgoing records. You must be using an ASCII terminal to run KERMIT-TSO. KERMIT-TSO must be installed as a Command Processor (CP) on your system. Please note that this document should be used in conjunction with the Kermit manual, and assumes you have read the sections pertaining to the IBM/PC microcomputer. For more information regarding the manual, see the Reference section at the end of this report. - 0 -1- 107/10/84 KERMIT-TSO 2. TSO Command Syntax and Options KERMIT You simply type a carriage return after issuing the KERMIT command. Commands: Send Receive Set Show Status Help Exit Quit ? 2.1. TSO KERMIT Command Options SEND [dataset name] Send the specified dataset. KERMIT-TSO will send only one file per request, no wildcarding is allowed. If the dataset name is not specified, KERMIT-TSO will prompt for one. Note, dataset must be cataloged. RECEIVE [dataset name] Receive the file sent from the micro. If the dataset name is not specified KERMIT-TSO will prompt for one. If no dataset previously exists with this name a file will be created using the value of the SPACE parameter. (NOTE, at this time KERMIT-TSO does not trap for abends, and if the file being received excedes the space allocated KERMIT-TSO will abnormally terminate.) The attributes for the dataset will be taken from the RECFM, LRECL, and BLKSIZE parameters. If a dataset exists KERMIT-TSO will prompt to see if you wish to overwrite the dataset. SET Set the parameter to the specified value. Legal Set commands are: -2- 107/10/84 KERMIT-TSO SPACE Specifies the number of tracks to be allocated to the dataset. The default is 5 tracks. Both the primary and secondary allocation are set to the value specified. RECFM Denotes the record format to be used when creating the dataset. Only fixed and variable length records are allowed, where variable is the default. Indicate the desired record format by either an F or a V. BLKSIZE Indicates the block size for creating the dataset. The default is 80 and the maximum is 32767. If the RECFM is F the blocksize must be a multiple of the value specified in the LRECL parameter. If RECFM is F then the BLOCKSIZE must be at least LRECL + 4. LRECL Indicates the logical record length for creating the dataset. The default is set to 80, and the maximum allowed is 255. If the RECFM is V the value must include the 4 bytes for the record descriptor word (RDW). QUOTE The quote character you wish to use in place of the default (#). It must be a single, printable character from among the following: 33-62, 96, or 123-126 (decimal). START Indicates the start-of-header character which you choose to send and receive. The default is a CNTL-A (ASCII 01), but can be set to any two digit number between 00 and 31 (dec). END Indicates the end-of-line character you choose to send. The default is a CR (ASCII 13), but can be set to any two digit number between 00 and 31 (dec). PAC Allows the user to specify the packet size the micro should use when sending to KERMIT-TSO. The range is 26-94 (decimal), where 94 is the default. DEBUG [ON | OFF] Allows the user to specify whether a trace -3- 107/10/84 KERMIT-TSO of packet information will be writen to a dataset. Before using this option the user must have allocated a dataset to file name (ddname) "DEBUG". DELAY Allow the user to specify the length of time in seconds that KERMIT-TSO will wait after the user issues a SEND. The default is 20 seconds. This will give the user time to escape back to his micro KERMIT and issue the neccesary commands. SHOW STATUS Displays the current value of all variables that can be changed via the SET command. STATUS Returns the status of the previous execution of KERMIT-TSO. Therefore, STATUS will either display the message "Kermit completed successfully", or the last error encountered prior to aborting. HELP Displays a message that briefly explains KERMIT-TSO commands. EXIT from KERMIT-TSO. QUIT Same as EXIT. ? Lists all legal KERMIT-TSO commands. 3. Examples under TSO Here is a brief example of how to use the IBM/PC in conjunction with KERMIT-TSO to send a file to the IBM-PC. A>kermit Kermit-86>set loc on ; Indicate half duplex Kermit-86>set ibm on ; Cause line turn around wait Kermit-86>set baud 1200 ; Set the baud rate Kermit-80>connect [ The micro will act as a regular terminal from now on.] [ Login here as you normally would, and run KERMIT-TSO.] kermit KERMIT-TSO>? Legal Commands are: Receive, Send, Help, Exit, Quit, Set, Status, Show KERMIT-TSO>send finger.database ; Send this file Waiting 20 seconds before sending. ^]C ; Return to the micro -4- 107/10/84 KERMIT-TSO ; by typing ]C Kermit-86> Kermit-86>receive ; Micro receives the file [the file is sent .......] Kermit-86>connect [press carriage return to see TSO's prompt] KERMIT-TSO>status Kermit completed successfully KERMIT-TSO>ex READY logoff CONNECT TIME - 2:30.95 SYSRONR Logged off TSO at 15:34:25 on July 6, 1984 ^]C ; Return to the micro ; by typing C Kermit-86>exit A> In order to send a file from the IBM/PC to the IBM mainframe repeat the above procedure swapping the command SEND with RECEIVE and vice versa. 4. Additional Information 1. The commands are supplied with a help option, so a question mark can be typed to get the appropriate format or a list of options. The question mark, however, must be followed by a carriage return; KERMIT-TSO will respond and display the prompt again. For instance, SET ? will list all valid options for the SET command. 2. When receiving files, if the record format is fixed, any record longer than the logical record length will be truncated. The record length can be as high as 255. For receiving files, the maximum record length is 255. 3. Before connecting to the IBM mainframe, three flags must be set. You should set the IBM flag on, set the LOCAL-ECHO flag on (used to indicate half duplex), and specify the baud rate you will be using. To turn a flag on, type to the micro's prompt "Set XXX On" where XXX is the flag name. Indicate the baud rate by typing "Set baud", and choose from among a list the IBM-PC supplies. These flags will remain in effect as long as you do not exit from the micro's version of Kermit. See the example of a session for further clarification. 4. The current version of KERMIT-TSO does not support timeouts. The user, therefore, should hit the carriage return key after a long period of inactivity (that is, when the screen display does not change.) -5- 107/10/84 KERMIT-TSO 5. Since the micro does not send an error packet when it aborts, KERMIT-TSO does not know the micro has stopped sending it information. Therefore, when you connect back to the IBM, KERMIT-TSO may still be sending packets (they will appear on the screen). The user must hit a carriage return until KERMIT-TSO has sent the maximum number of packets allowed and aborts. The error message, however, will not indicate that communication stopped because the micro aborted, but rather that no start of header character was found. 6. The minimum send packet size KERMIT-TSO will allow is 26. This is necessary to avoid an error while sending the filename or an error packet. If the micro tries to set the value to be less than 26, KERMIT-TSO will immediately abort with an error of "Bad send-packet size." 7. During the initialization process with the micro, KERMIT-TSO sends all six pieces of information (that is, the receive packet size, the timeout data, the number of padding characters, the character used for padding, the line terminator, and the quote character.) When receiving this data from the micro, KERMIT-TSO ignores the data regarding timeouts and padding; they do not effect the program's execution. Therefore, if the quote and end-of-line characters used are the defaults, the micro need only send KERMIT-TSO its buffer size. Only if the defaults are not used must ALL the information be sent (since the data is organized positionally). If, however, the micro sends all the information even when not required, KERMIT-TSO will simply ignore the irrelevant portion. 8. When sending packets to KERMIT-TSO, the micro must use a carriage return as the end-of-line character. TSO requires a carriage return to terminate a read from the terminal; thus, if any other character is used, KERMIT-TSO will never get the packets. 9. KERMIT-TSO translates the data it reads back to ASCII (characters not representable in ASCII are replaced by a null). Not only is it easier to work with ASCII characters, but it makes things more consistent throughout the many versions of Kermit. When the packets are sent to the micro, KERMIT-TSO converts all data back to EBCDIC. The ASCII to EBCDIC translation table can be found in Appendix V of the Kermit manual. 4.1. Error Messages KERMIT-TSO supplies the micro and the user with numerous error messages. If the execution must be aborted, an error packet is sent to the micro before KERMIT-TSO stops. The same message can be retrieved via the STATUS command when KERMIT-TSO returns and displays the prompt. If KERMIT-TSO aborted because the maximum amount of retries was exceeded (20 on initialization packets and 5 on others), the error message will display the most recent error (i.e. - the last NAK KERMIT-TSO encountered). If execution stops because the micro aborted, the error message will convey that to the user, but it is the micro's responsibility to pinpoint the error. The messages KERMIT-TSO gives are as follows : "Bad send-packet size" Sent when the micro attempts to set its receive buffer size to a value that is less than 26 (the minimum that KERMIT-TSO will -6- 107/10/84 KERMIT-TSO accept) or larger than 94, the maximum. It will also occur if KERMIT-TSO tries to send a packet that is larger than the maximum specified. "Bad message number" If the packet number is less than zero or greater than 63 (at which point it should "wrap around" back to zero). This message is returned if the packet type does not fall between A-Z. "Unrecognized State" If KERMIT-TSO is in a state not previously defined by the protocol, it will abort with this message. "No SOH encountered" This error arises if KERMIT-TSO reads the entire packet without encountering an SOH character. The result is that it sends a NAK to the micro, and marks this error as the most recent one. "Bad Checksum" If the checksum calculated by KERMIT-TSO does not match the one sent by the micro, KERMIT-TSO NAK's the packet and flags this error. "Bad character count" This error is set if KERMIT-TSO receives a packet whose size is illegal (that is, if the size parameter was garbled during transmission of the packet.) "Micro sent a NAK" Keep track of who rejected the packet. "Lost a packet" When a packet is received and the sequence number is different from the number KERMIT-TSO expected, the packet is NAK'ed. "Micro aborted" Tells you that the micro aborted unexpectedly. "Invalid RECFM, only fixed or variable supported" KERMIT-TSO will abort on any file-system error it encounters when reading from the file it is to send. It can only send files with variable or fixed length record formats, therefore, Wylbur Edit or Packed format files will cause an error. "BLKSIZE not a multiple of LRECL for RECFM=F" KERMIT-TSO will refuse RECEIVE request and return to the KERMIT prompt. The BLOCKSIZE is not an integral multiple of the LRECL when RECFM F (fixed) is specified. "LRECL not less than BLKSIZE-4 for RECFM=V' KERMIT-TSO will refuse RECEIVE request and return to the KERMIT prompt. The LRECL for RECFM=V (variable) must be four less than -7- 107/10/84 KERMIT-TSO the BLKSIZE to include the block descriptor work (BDW). "Open for dataset failed" Indicates a problem opening the dataset. 5. Reference For a more detailed explanation of Kermit or information regarding the IBM-PC, consult the Kermit manual, Kermit Users Guide and Specification. The manual is available in the Reference Library at USITE. - - - - - - - - - - - - - - - -8-