Columbia Kermit

home *** CD-ROM | disk | FTP | other *** search

/ Columbia Kermit / kermit.zip / guts / guts.man < prev next >

Wrap

Text File | 2020-01-01 | 24KB | 531 lines

1 - KERMIT-GUTS February 11, 1985 - 1. Introduction +_______________ 0KERMIT 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/GUTS. 0KERMIT 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. 0Written in IBM 370 assembly language to run under MVS/GUTS 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. 0IBM systems talk to their terminals through a communications front end (IBM 3705, 3725, COMTEN 3805, 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). 0The IBM system under MVS/GUTS is unable to interrupt a read on its "console". This means that the IBM version of Kermit cannot timeout. The only way to "timeout" GUTS 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, GUTS Kermit waits twenty seconds before sending its first packet when sending files from MVS/GUTS. 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. 0Also, MVS/GUTS stores files as records rather byte streams. MVS/GUTS 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. 0You must be using an ASCII terminal to run KERMIT-GUTS. 0KERMIT-GUTS can only work with OS files, not with GUTS files. This 0 - 1 - 1 - KERMIT-GUTS February 11, 1985 0means that if you want to transfer a GUTS file you will have to copy it first to an OS file. The KERMIT-GUTS receives a file from a micro he will store it as an OS file. You can then after transmission copy the OS file to a GUTS file. For more information see chapter 5. -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. - - - - - - - - - - - - - - - 2 - 1 - KERMIT-GUTS February 11, 1985 02. GUTS Command Syntax and Options +__________________________________ -/KERMIT 0You simply type a carriage return after issuing the KERMIT command. 0Commands: 0 Send 0 Receive 0 Set 0 Show 0 Status 0 Help 0 Exit 0 Quit 0 ? -2.1. GUTS KERMIT Command Options +________________________________ 0SEND <dataset name> Send the specified dataset. KERMIT-GUTS will send only one file per request, no wildcarding is allowed. If the dataset name is not specified, KERMIT-GUTS will prompt for one. Note, dataset must be cataloged. Kermit will only search on the volume(s) specified with the /SET UNIT= command. Kermit will add your &INDEX prefix to the dataset name unless you have written a leading and trailing apostrophy. 0RECEIVE <dataset name> Receive the file sent from the micro. If the dataset name is not specified KERMIT-GUTS 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-GUTS does not trap for abends, and if the file being received excedes the space allocated KERMIT-GUTS will abnormally terminate.) The attributes for the dataset will be taken from the RECFM, LRECL, and BLKSIZE parameters. If a dataset exists KERMIT-GUTS will prompt to see if you wish to overwrite the dataset. Note| Kermit will create an OS dataset, not a GUTS 0 - 3 - 1 - KERMIT-GUTS February 11, 1985 0 file. The OS dataset will be plased on the volume, or one of the volumes you have specified by the /SET UNIT= command. 0SET <parameter> <value> Set the parameter to the specified value. Legal Set commands are: - SPACE <d> 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. 0 RECFM <c> 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. 0 BLKSIZE <d> 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. 0 LRECL <d> 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). 0 QUOTE <c> 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). 0 START <d> 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). 0 END <d> 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). - - 4 - 1 - KERMIT-GUTS February 11, 1985 0 PAC <d> Allows the user to specify the packet size the micro should use when sending to KERMIT-GUTS. The range is 26-94 (decimal), where 94 is the default. 0 DEBUG <ON | OFF> Allows the user to specify whether a trace 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". 0 DELAY <d> Allow the user to specify the length of time in seconds that KERMIT-GUTS 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. 0STATUS Returns the status of the previous execution of KERMIT-GUTS. Therefore, STATUS will either display the message "Kermit completed successfully", or the last error encountered prior to aborting. 0HELP Displays a message that briefly explains KERMIT-GUTS commands. 0EXIT Exit from KERMIT-GUTS. 0QUIT Same as EXIT. 0? Lists all legal KERMIT-GUTS commands. - - - - - - 5 - 1 - KERMIT-GUTS February 11, 1985 03. Examples under GUTS +______________________ 0Here is a brief example of how to use the IBM/PC in conjunction with KERMIT-GUTS to send a file to the IBM-PC. 0 A>kermit 0 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 0 < The micro will act as a regular terminal from now on. > < Logon here as you normally would, and run KERMIT-GUTS.> 0 /KERMIT KERMIT-GUTS Version 1.00 at GUC. 0 KERMIT-GUTS>? Legal Commands are: Receive, Send, Help, Exit, Quit, Set, Status, Show KERMIT-GUTS>send finger.database ; Send this file 0 Waiting 20 seconds before sending. ^$C ; Return to the micro - 0 ; by typing <escape>$C 0 Kermit-86> Kermit-86>receive ; Micro receives the file 0 <The file is sent .......> 0 Kermit-86>connect 0 <press carriage return to see GUTS's prompt> 0 KERMIT-GUTS>status Kermit completed successfully KERMIT-GUTS>ex _ /OFF TSC0018I ABCAA logged off at 13.47.10, Monday, February 11, 1985 ...... 0 ^$C ; Return to the micro ; by typing <escape>C 0 Kermit-86>exit 0 - 6 - 1 - KERMIT-GUTS February 11, 1985 0 A> 0In 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. - - - - - - - - - - - - - - - - - 7 - 1 - KERMIT-GUTS February 11, 1985 04. Additional Information +_________________________ 0 The commands are supplied with a help option, so a question +1. 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-GUTS will respond and display the prompt again. For instance, SET ? will list all valid options for the SET command. 0 When receiving files, if the record format is fixed, any +2. 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. 0 Before connecting to the IBM mainframe, three flags must be +3. 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. 0 The current version of KERMIT-GUTS does not support timeouts. +4. The user, therefore, should hit the carriage return key after a long period of inactivity (that is, when the screen display does not change.) 0 Since the micro does not send an error packet when it aborts, +5. KERMIT-GUTS does not know the micro has stopped sending it information. Therefore, when you connect back to the IBM, KERMIT-GUTS may still be sending packets (they will appear on the screen). The user must hit a carriage return until KERMIT- GUTS 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. 0 The minimum send packet size KERMIT-GUTS will allow is 26. +6. 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-GUTS will immediately abort with an error of "Bad send-packet size." 0 During the initialization process with the micro, KERMIT-GUTS +7. 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-GUTS ignores the data regarding timeouts and padding; they do not effect the program's execution. 0 - 8 - 1 - KERMIT-GUTS February 11, 1985 0 Therefore, if the quote and end-of-line characters used are the defaults, the micro need only send KERMIT-GUTS 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-GUTS will simply ignore the irrelevant portion. 0 When sending packets to KERMIT-GUTS, the micro must use a +8. carriage return as the end-of-line character. GUTS requires a carriage return to terminate a read from the terminal; thus, if any other character is used, KERMIT-GUTS will never get the packets. 0 KERMIT-GUTS translates the data it reads back to ASCII +9. (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-GUTS converts all data back to EBCDIC. The ASCII to EBCDIC translation table can be found in Appendix V of the Kermit manual. - - - - - - - - - - 0 - 9 - 1 - KERMIT-GUTS February 11, 1985 04.1. Error Messages +___________________ 0KERMIT-GUTS 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-GUTS stops. The same message can be retrieved via the STATUS command when KERMIT-GUTS returns and displays the prompt. If KERMIT-GUTS 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-GUTS 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-GUTS gives are as follows : 0 "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-GUTS will accept) or larger than 94, the maximum. It will also occur if KERMIT-GUTS tries to send a packet that is larger than the maximum specified. 0 "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. 0 "Unrecognized State" If KERMIT-GUTS is in a state not previously defined by the protocol, it will abort with this message. 0 "No SOH encountered" This error arises if KERMIT-GUTS 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. 0 "Bad Checksum" If the checksum calculated by KERMIT-GUTS does not match the one sent by the micro, KERMIT-GUTS NAK's the packet and flags this error. 0 "Bad character count" This error is set if KERMIT-GUTS receives a packet whose size is illegal (that is, if the size parameter was garbled during transmission of the packet.) 0 "Micro sent a NAK" Keep track of who rejected the packet. 0 - 10 - 1 - KERMIT-GUTS February 11, 1985 - "Lost a packet" When a packet is received and the sequence number is different from the number KERMIT-GUTS expected, the packet is NAK'ed. 0 "Micro aborted" Tells you that the micro aborted unexpectedly. 0 "Invalid RECFM, only fixed or variable supported" KERMIT-GUTS 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. 0 "BLKSIZE not a multiple of LRECL for RECFM=F" KERMIT-GUTS 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. 0 "LRECL not less than BLKSIZE-4 for RECFM=V' KERMIT-GUTS will refuse RECEIVE request and return to the KERMIT prompt. The LRECL for RECFM=V (variable) must be four less than the BLKSIZE to include the block descriptor work (BDW). 0 "Open for dataset failed" Indicates a problem opening the dataset. - - - - - - - - - 11 - 1 - KERMIT-GUTS February 11, 1985 0 5. Sending and receiving a GUTS file. + _____________________________________ - KERMIT-GUTS can only send and receive OS files. If you want to send a GUTS file you must first copy it to an OS file. If you want to receive a GUTS file, you must copy the OS file to a GUTS file. The following examples will illustrate how to do this: - Sending a GUTS file to a micro + ______________________________ 0 /ALLCAT PUB001,TESTFILE -- Allocate and catalog an OS file called -- -- TESTFILE on PUB001. -- (Note. The Volumename must corresponde with the volume or volumes you have specified with the /SET UNIT= command. See GUTS referense Manual for further information.) 0 /TSOS DATA,TESTFILE -- Copy the GUTS file "DATA" to the OS file -- -- TESTFILE -- 0 /KERMIT -- Start up the KERMIT-GUTS program -- KERMIT-GUTS version 1.00 at GUC. 0 KERMIT-GUTS> SEND TESTFILE Waiting 20 seconds before sending. 0 (Now go back to your micro and tell it to receive a file) 0 (After successful transmission you connect back to KERMIT-GUTS) KERMIT-GUTS> EXIT /SCRUNC TESTFILE -- Scratch and uncatalog the OS file -- - - - - - - - - 12 - 1 - KERMIT-GUTS February 11, 1985 0 Receiving a GUTS file from a micro. + ___________________________________ 0 /KERMIT -- Start the KERMIT-GUTS program -- KERMIT-GUTS version 1.00 at GUC. 0 KERMIT-GUTS> RECEIVE TESTFILE (Tell KERMIT-GUTS to receive a file from the micro and call the OS file "TESTFILE") 0 (Now go back to your micro and ask it to send your file to GUTS. After successful transmission go connect back to KERMIT-GUTS.) 0 KERMIT-GUTS> EXIT 0 /OSTS TESTFILE,TEST -- Copy the OS file "TESTFILE" to -- -- a GUTS file and call it "TEST" -- 0 /SCRUNC TESTFILE -- Scratch and uncatalog the OS file -- -- called TESTFILE -- - - - - - - - - - - - - - 13 - 1 - KERMIT-GUTS February 11, 1985 0 6. Reference + ____________ 0 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 at Gothenburg Universities' Computing centre. - - - - - - - - - - - - - - - 0 - 14 -