SOFTWARE USER'S MANUAL for the STARS Foundation Project Network Protocol CONTRACT NO. N60921-87-C-0286 CDRL SEQUENCE NO. A008 29 February 1988 Version 1.0 Prepared for: Naval Research Laboratory Washington, D.C. 20375-5000 Prepared by: Westinghouse Electric Corporation Development & Operations Division P.O. Box 746 Baltimore, MD. 21203 February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Page i TABLE OF CONTENTS Page 1. Introduction 1 2. Glossary 1 3. Computer System Capabilities 2 4. Function Description 3 5. Usage Instructions 4 6. Operation Instructions 5 7. Appendix A - Example A-1 8. Appendix B - XMODEM File Transfer Protocol B-1 9. Appendix C - KERMIT File Transfer Protocol C-1 February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Page 1 1. Introduction This Software User's Manual provides the procedures for implementing the Network Protocol, a set of Ada packages developed for the STARS Foundations program. The Network Protocol is designed for reusability and to be incorporated into a larger system to complete the application. The purpose of the Network Protocol is to provide the Kermit and XMODEM file transfer protocols based on published algorithms. The Network Protocol is a set of Ada packages which implement only the file transfer protocols. The specific interface to a particular domain is to be supplied by the user. This application has been designed to meet the reusability goal of the STARS program since no Ada code modifications will have to be made to either file transfer protocol for any domain. The goal of this manual is to describe the operation of the Network Protocol program. This document will provide information on how to use the Network Protocol program for a specific environment with the intention of the specific implementation serving as a guide for similar implementation in a different environment. The Network Protocol program is not intended as a stand alone program. This document will focus on the reuse considerations and the operation of the Kermit and XMODEM file transfer protocols. The specific interfaces and mechanisms to select the desired protocol should be provided by the user and based on the domain specific application. This User's Manual has been tailored to meet the documentation needs of a computer software configuration item intended to be a reusable portion for many different environments. 2. Glossary ACK -- What the receiver replies to the sender when the receiver accepts the data that was sent to it. For XMODEM, use the ASCII character 6. For KERMIT, use a Y packet. Binary Prefix -- For KERMIT, it is the character used to indicate that the next data byte has its MSB set to 1. This is only used for binary file transfers when the data communication path is 7 bits wide. CAN -- For XMODEM, this means cancel the transfer. The ASCII character 24 is used. Checksum -- A calculation done on data being transferred to help ensure its accurate receipt. The byte that results from the calculation is sent after the data. If the receiving protocol calculates the same checksum from the data that the sending protocol sent with the data, the data is accepted as accurate. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Page 2 Controlify -- For KERMIT, this means that the 6th bit of a character is toggled. Control quote -- For KERMIT, the character that is used to signal that the next data byte is an encoded control character. EOT -- For XMODEM, the ASCII character 4, which signals the end of the transmission. MSB -- the most significant bit of a data byte. NAK -- What the receiver replies to the sender when the receiver does not accept the data that was sent to it. For XMODEM, use the ASCII character 21. For KERMIT, use an N packet. Packet -- For KERMIT, the way KERMIT control information and user data is grouped for the transfer. There are several different KERMIT packets. See APPENDIX C of the USER'S MANUAL for more detail. SOH -- ASCII character 1, signals the start of XMODEM header information for an XMODEM transfer block, or the start of a KERMIT packet. TOCHAR -- For KERMIT, changing a numerical value into a character by adding 32 to the value and changing it into an ASCII character. UNCHAR -- For KERMIT, changing a character back into a numerical value by taking the character's associated ASCII collating sequence number and subtracting 32. 8-Bit Prefixing -- For KERMIT, the way binary data is transferred over a 7 bit communications path. 3. Computer System Capabilities A. Purpose The purpose of Network Protocol is to provide the user with the means of using either the XMODEM or Kermit file transfer protocol with as little effort as possible. The only function that the user will be required to perform is to define the interface and instantiate the desired protocol. B. General Description Network Protocol is implemented as a group of generic packages. Both file transfer protocols are implemented as generics so that the process for using either one is exactly the same. C. Functions Performed Network Protocol implements the elements of both the XMODEM and Kermit file transfer protocols which are considered to be standard. The functions February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Page 3 provided are SEND and RECEIVE. The fact that there are only two functions instead of four is a result of the use of generics to implement both file transfer protocols. The invocation of either the send or receive function will be performed in the same way regardless of which file transfer protocol has been instantiated. 4. Function Description A. SEND The purpose of this function is to send a file. This function requires no inputs when it is called. The expected result of this function is that the file is sent. There is no output from this function. This function depends on several other functions to accomplish the goal of successfully sending a file. The primary requirement is that the transfer can take place only if the RECEIVE function is implemented from the same file transfer protocol as the sender. There are several other basic functions which are used by SEND that are included in Network Protocol and become available when the desired protocol is instantiated. Other functions that are required by SEND, such as reading and writing to the RS-232 port and reading and writing the file to disk (or whatever medium the user desires) must be supplied by the user because they are specific to the environment in which Network Protocol is being implemented. This function simply sends a file according to the rules of the protocol for which it has been instantiated. B. RECEIVE The purpose of this function is to receive a file. This function requires no inputs when it is called. The expected result of this function is that a file is received according to the rules of the instantiated protocol and stored according to the subprograms used to instantiate the protocol. This function depends on several other functions to accomplish the goal of successfully receiving a file. The primary requirement is that the transfer can take place only if the SEND function is implemented from the same file transfer protocol as the receiver. There are several other basic functions which are used by RECEIVE that are included in Network Protocol and become available when the desired protocol is instantiated. Other functions that are required by RECEIVE, such as reading and writing to the RS-232 port and reading and writing the file to disk (or whatever medium the user desires) must be supplied by the user because they are specific to the environment in which Network Protocol is being implemented. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Page 4 This function simply receives a file and stores it according to the rules of the protocol for which it has been instantiated. 5. Usage Instructions The use of Network Protocol is dependent on the user adapting the application to fit the environment it is to be run in. Since Network Protocol is not a standalone program, certain procedures must be written before it is executable. The following must be supplied by the user before the program can be used: A. A type definition for the type BYTE. B. Procedures which provide the ability to read from and write to the RS-232 port (or whatever is being used to "transfer" the data). C. Procedures to read a file from and write a file to the medium that the user desires. D. A way to identify the file that is to be transferred. Once the user has supplied the information described in A through D above, a file transfer protocol must be selected. It is important to remember that the protocol selected must also be available on the machine that the file is to be transferred to or from. Once the selection of the protocol has been made, that protocol must be instantiated. The protocols can be instantiated as follows: A. package XMODEM is new XMODEM_PROTOCOL ( BYTE, name of procedure to read a file, name of procedure to write a file, name of procedure to read from the RS-232 port, name of procedure to write to the RS-232 port, RS_WRITE_FLUSH, SERVICE ) ; B. package KERMIT is new KERMIT_PROTOCOL ( BYTE, name of procedure to read a file, name of procedure to write a file, name of procedure to read from the RS-232 port, name of procedure to write to the RS-232 port, RS_WRITE_FLUSH, SERVICE ) ; Now that the desired protocol has been instantiated, the program is used by running the procedure that identifies the file that is to be transfered. This procedure should contain a means for opening the file that is to be sent or received. Once the file is open, the transfer is accomplished by calling the February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Page 5 desired send or receive procedure in the instantiated protocol. Examples of this are: A. XMODEM.SEND B. KERMIT.SEND C. XMODEM.RECEIVE D. KERMIT.RECEIVE After termination, a copy of the file that was sent should reside on the medium chosen by the user on the machine that ran the receive portion of the protocol. 6. Operation Instructions The following process is required to implement Network Protocol. A. Obtain a copy of the Network Protocol source code on your machine. B. Develop a package which defines and implements the processes of reading and writing files to whatever medium you desire. This package should contain processes for opening, closing, and creating files and any local variables required to implement these processes. C. Develop a package which defines and implements the process of reading from and writing to the RS-232 port. NOTE: This package is extremely machine dependent. D. Choose which protocol you wish to use. E. Develop a main procedure. This procedure should include: 1. The definition of the type BYTE if it was not defined in part B above. 2. A procedure that prompts for the name of the file that is to be transferred. This procedure can do a number of other things such as prompt for the direction (send or receive) and quit. There should be some way to open the file for reading if it is being sent and for creating the file for receiving. 3. An instantiation of the desired protocol in the manner described in the usage instructions above. 4. An instruction that calls the desired part of the instantiated protocol. F. Compile and link all source code. G. Run the program by running the main procedure that you developed. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix A Page A-1 APPENDIX A EXAMPLE This example is the program that was used to demonstrate the Network Protocol as required in the contract. The focus of this example will be the implementation of the XMODEM file transfer protocol. The only change required to implement the Kermit protocol is the replacement of the XMODEM instantiation with the Kermit instantiation and the replacement of the lines XMODEM.SEND and XMODEM.RECEIVE with KERMIT.SEND and KERMIT.RECEIVE. The following is a description of a package that is included in Network Protocol but is not visible to the user. The reason this package is explained is because the functions that the user is required to develop and implement are used by this package. PROTOCOL_INDEPENDENT_UTILITIES package body This package is non-visible. The purpose of this package is to implement operations common to both file transfer protocols. The operations that are implemented in this package are: 1. LOW_BYTE_OF_SUM is a function which adds the values of all bytes in a block being transferred, assuming less than 256 bytes so the total will fit in 16 bits, and returns a byte whose "value" is the low byte of the total. Required input is the block being transferred. Expected output is a byte. 2. RS_READ_WITH_TIMEOUT is a procedure which reads a byte and returns it in a specified amount of time. If a byte is not read in the given time, the procedure returns a boolean value to the calling procedure specifying that a byte was not read. The act of reading a byte is done through another procedure in this package. The required input is a "DURATION" type value. Expected output is a boolean value specifying whether or not a byte was received, and the byte if one was received. 3. RS_READ_BLOCK_WITH_TIMEOUT is a procedure which uses RS_READ_WITH_TIMEOUT to read a complete block of data. It returns a boolean value that tells the calling procedure if the entire block was read. Also an integer holding the byte number of the last byte read is returned. The required input is a "DURATION" type value. Expected output is the complete block of data, the boolean value, and the integer value of the index of the last byte read. 4. F_WRITE_BLOCK is a procedure which writes a complete block of data to disk using the procedure called F_WRITE. The required input is the block of data. There is no expected output. 5. F_READ_BLOCK is a procedure which reads a complete block of data from a disk file. It returns the block of data, a boolean value which tells the calling program if the end of the file was reached, and an integer February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix A Page A-2 containing the number of the last byte in the block that was read. If the end of the file is reached and the block is not completely filled, the remaining bytes of the data block are filled with the byte value for the NUL ASCII character. There are no inputs to this procedure. 6. RS_WRITE_BLOCK is a procedure which uses RS_WRITE to write a whole data block to the RS-232 port. The required input for this procedure is the complete data block. There is no output from this procedure. 7. LONG_READ is a procedure which reads a response from the RS-232 port. It is called LONG_READ because it will attempt to read as long as the error count is less than the limit of ten (10). This procedure uses RS_READ_WITH_TIMEOUT to do the actual reading from the RS-232 port. The required inputs are an error limit other than the default of ten (10), a "DURATION" type value, and an integer which holds the number of errors. The expected output is the byte that is read. 8. WRITE_READ_WITH_EXPECTED_RESPONSE is a procedure which writes a byte to the RS-232 port and then waits for the correct response. This procedure is the same as LONG_READ except that the byte is written first. The required inputs are the same as for LONG_READ except for the additional byte that is to be written and the byte that is the expected response. The expected output is the byte that is read. 9. GET_BYTE is a procedure which reads one byte from the RS-232 port by calling the procedure RS_READ_WITH_TIMEOUT. This procedure is local to the receive procedure of the selected protocol. If a byte is not available to be read, the read error exception will be raised. 10. The body which insures that BYTE supports 8-bit unsigned values and that INTEGER supports 16-bit signed values. NOTE: The procedures referred to as RS_READ and RS_WRITE must be supplied by the user since their implementation is machine dependent. The following are the packages used in the example to provide entry points that are required to be supplied by the user. These packages were developed for the VAX/VMS environment. The medium used for file storage is disk. GENERIC_TEXT_FILE_IO package body The purpose of this package is to provide the tools needed to perform input/output operations on text files compatable with TEXT_IO. The operations implemented in this package are: 1. OPEN_READ is a procedure which opens the disk file that is to be read from. The required inputs are the file name and the "form" of the file; both are strings. There are no expected outputs. 2. F_READ is a procedure which reads from the disk and returns one character or byte at a time to the calling procedure. If there are no more characters in the particular line, it reads the next line until the end of February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix A Page A-3 file is reached. If the end of the file is reached, a boolean value indicating that condition is returned. There are no inputs required for this procedure. Expected outputs are the character or byte read and the boolean value indicating the end-of-file condition. 3. CLOSE_READ is a procedure which closes the disk file that is being read from. There are no required inputs and no expected outputs. 4. OPEN_WRITE is a procedure which creates and opens the disk file that is to be written. The required inputs are the file name and the "form" of the file; both are strings. There are no expected outputs. 5. F_WRITE is a procedure which writes a byte to the disk file. The required input is the byte that is to be written to the file. There are no expected outputs. 6. CLOSE_WRITE is a procedure which closes the disk file that is being written to. There are no required inputs and no expected outputs. 7. NAME_OF_FILE_BEING_TRANSFERRED is a procedure which returns a string containing the name of the file which is being transferred, ie. read from. There are no required inputs. The name of the file being transferred in string form is the expected output. TERMINAL_IO This package defines and implements the RS-232 port interface. It consists of: 1. A visible definition of BYTE as range 0 .. 255. 2. A visible procedure named TTY_WRITE which writes a byte to the terminal or RS-232 port. 3. A visible procedure named TTY_READ which reads a byte from the terminal or RS-232 port, or returns after a specified period saying there was no byte available. 4. A visible procedure named TTY_FLUSH which is a null procedure since no buffered output is done. 5. A visible procedure named TTY_RESTORE which resets or restores the terminal or RS-232 port to its original setting. 6. A number of non-visible variables that define the channel and masks to be used to enable the terminal or RS-232 port to behave in the desired fashion. 7. A non_visible procedure named TTY_PREP which assigns the terminal or port a channel, saves the original terminal or port characteristics, sets the terminal or port mode to EIGHTBIT/PASTHRU/NOTTSYNC, and sets up input and output functions and modifiers. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix A Page A-4 NOTE: The operations performed in this package are machine specific. DEMO_XMODEM This procedure is used to demonstrate the XMODEM protocol. This procedure instantiates the protocol and is executed after logging in remotely from another machine, presumably a PC. The user is expected to be running an XMODEM file transfer protocol on the remote machine. Once this procedure is executed the user will be prompted for the desired mode (send or receive) and the file name. A that point the file will be transferred. This procedure makes use of the machine dependent package called TERMINAL_IO. This procedure consists of: 1. An instantiation of GENERIC_TEXT_FILE_IO. 2. An instantiation of XMODEM_PROTOCOL. 3. A procedure specification and body named SERVICE which is a null procedure. 4. The following procedure bodies which are the same as described in package body TEST_PKG: A. TTY_WRITE B. TTY_WRITE_LINE 5. A procedure body named DISPLAY which displays a character on the terminal, taking into account whether a control character will have a reasonable effect. 6. A procedure body named GETCHAR which gets a character or byte from the RS-232 port. 7. A procedure body named GETUCHAR which gets an upper case character from the RS-232 port. 8. A procedure body named PROMPT_AND_READ which issues a prompt to and then reads the response from the RS-232 port. 9. A function named WHAT_WE_ARE_DOING that prompts the user for what function (which direction) is desired. The function returns a value corresponding to the direction the user supplies. 10.A procedure body named SEND_A_FILE which prompts the user for the name of the file that is to be sent, opens that file for input, calls XMODEM.SEND, and closes the file when the transfer is complete. 11.A procedure body named RECEIVE_A_FILE which prompts the user for the name of the file to be received, opens that file for output, calls XMODEM.RECEIVE, and closes the file when the transfer is complete. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix A Page A-5 12.The code for the body of DEMO_XMODEM which is simply a loop that calls the procedures described above to determine if the user wishes to send, receive, or quit and then depending on the user's response calls the correct part of the XMODEM protocol. EXECUTION To transfer a file to another machine, the user must login to the remote machine. Once the user is logged into the remote machine and is running another XMODEM on the host machine, he simply runs DEMO_XMODEM and replies to all of the prompts. All of the packages and procedures described in this appendix have been delivered in conjunction with Network Protocol with the hope that they will serve as a basis for developing the required code for other environments. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix B Page B-1 APPENDIX B XMODEM File Transfer Protocol A. XMODEM Protocol Overview The goal of the XMODEM protocol is to send or transfer a file in 132 byte blocks. Each block contains three separate bytes that are used for error control. The blocks are read and sent sequentially from the beginning of the file until the end of the file is reached. Every block consists of: a Start Of Header (1 Byte), a Block Number starting from 01 Hex, incrementing by 1 up to 0FF Hex and then wraping to 00 Hex (1 Byte), the One's Complement of the Block Number (1 Byte), 128 Data Bytes from the file, and a Checksum for error checking (1 Byte). Each block is either acknowledged or not acknowledged by the receiving XMODEM based on the block number and its complement being what is expected and the checksum being correct. If a block is not acknowledged by the receiver, the same block is resent by the sender. If the final block does not contain a full 128 data bytes, the remaining bytes are padded with NUL's. A more detailed explanation of the different aspects of the protocol is given below. B. Definitions 01 HEX START OF HEADER 04 HEX END OF TRANSMISSION 06 HEX ACKNOWLEDGE SECTOR 15 HEX NOT ACKNOWLEDGE SECTOR 18 HEX CANCEL TRANSFER 43 HEX CRC INDICATING CHARACTER C. File Level Protocol 1. Common to both Sender and Receiver: A. All errors are retried ten (10) times. 2. Receiver Program Considerations: A. Ten (10) second timeout. B. Send NOT ACKNOWLEDGE SECTOR () every time it times out. C. In receiving a block, a 1 second timeout for each character and the Checksum. D. If a needs to be sent for any block, receiver must wait for a clear line. E. Synchronizing - If a valid block number is received: February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix B Page B-2 1. It is the expected one. 2. A repeat of the previous block (receiver's got glitched and sender is retransmitting). 3. Any other block number indicates a FATAL loss of synchronization. Abort the transmission. 3. Sending Program Considerations: A. When there is no more data to send, an should be sent and repeated until an is received. B. Suggest that the whole transfer be receiver driven. D. Block Number Calculation Both the sender and the receiver have a variable that holds the current block number. The sender increments its block number after it receives an from the receiver and reads the next block from the file. The receiver increments its block counter after sending an . See section above for synchronizing considerations. E. Checksum Calculation Both the sender and the receiver perform the same checksum calculation. The calculation consists of the addition of all 128 data bytes with any carry thrown away. The sender computes the checksum as it is filling the 128 data bytes and then sends the final value in the 132nd byte. The receiver calculates its own checksum based on the 128 data bytes that it receives and then compares it with the value in the 132nd byte. If they are the same and the block number is correct an is sent, otherwise a is sent. F. Errors All errors are retried ten (10) times before the transfer terminates. G. Data Flow Example SENDER RECEIVER times out after 10 seconds, <-- 01 FE -data- xx --> <-- 02 FD -data- xx --> (data line gets hit) <-- 02 FD -data- xx --> <-- 03 FC -data- xx --> (ACK gets garbaged) <-- 03 FC -data- xx --> <-- February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix B Page B-3 --> <-- --> <-- (finished) H. Code Required to Implement Xmodem The items covered in this section are further illustrated in Appendix A. 1. The only type that is required to be defined is the type BYTE. 2. A package or procedure that instantiates the desired generic file transfer protocol, which would be XMODEM in this case, is required. 3. A package that defines the machine interface. Specifically how to read from and write to the RS-232 port. I. Operations implemented in the XMODEM_PROTOCOL package are: 1. UPDATE_FOR_NEXT_BLOCK is a procedure which updates the block number, the complement of the block number, and the error count each time a block is both successfully transmitted and received. The required inputs for this procedure are the variables which are updated. The expected outputs are the same as the inputs since the parameters are all "in out". 2. WAIT_FOR_CLEAR is a procedure which is called if an error occurs while receiving a block. It increments the error counter and waits for a clear line so a response can be sent. The input and output for the procedure is an integer value for the error count. 3. NEW_BLOCK is a procedure which is called anytime the start of a new block is expected. The procedure calls WRITE_READ_WITH_EXPECTED_RESPONSE, which is implemented in the non-visible PROTOCOL_INDEPENDENT_UTILITIES package, to look for a {Start of Header" byte. The FILE_TRANSFER_ERROR exception is raised if the error limit is exceeded. The required input to this procedure is an integer value holding the error count. The expected output is the updated error count and the "Start of Header" byte. 4. LOOK_FOR_RESPONSE is a procedure which is called by both sender and receiver when a specific response to the byte that is sent to the other is required. This procedure calls WRITE_READ_WITH_EXPECTED_RESPONSE, which is implemented in the non-visible PROTOCOL_INDEPENDENT_UTILITIES package. The FILE_TRANSFER_ERROR exception is raised if the error limit is reached. The error count is reset at the end if the expected response is received. The inputs for this procedure are the bytes to be sent and the expected response, and an integer value holding the error count. The expected output is the byte that is expected and the reset error count. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix B Page B-4 5. RECEIVE is a procedure which implements the receive portion of the XMODEM file transfer protocol. The procedure consists of: A. A call to LOOK_FOR_RESPONSE which sends a NAK and then looks for a SOH to begin the transfer. B. A loop containing: 1. An "if" statement testing for: A. A "Start of Header" byte: 1. Read the block number byte using GET_BYTE. 2. Convert block number byte to an integer. 3. Read the complement byte using GET_BYTE. 4. Convert the complement byte to an integer. 5. Check the block number and complement against the block number and complement expected and raise the Blk_Error exception if they are not the same. 6. Read the 128 bytes of data using RS_READ_WITH_TIMEOUT. 7. Raise Read_Error if all 128 bytes are not received. 8. Read the Checksum byte using GET_BYTE. 9. Convert Checksum to an integer. 10. Calculate another Checksum from the data received using LOW_BYTE_OF_SUM. 11. If Checksums are equal: A. Acknowledge receipt of block using RS_WRITE. B. Write block to file using F_WRITE_BLOCK. C. UPDATE_FOR_NEXT_BLOCK. 12.If Checksums are not equal: A. Send a using RS_WRITE. B. Increment error count. B. An "End of Transmission" byte: February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix B Page B-5 1. Acknowledge receipt of using RS_WRITE. 2. Return to calling procedure. C. Anything else: 1. Call WAIT_FOR_CLEAR. 2. Send a using RS_WRITE. 2. Call NEW_BLOCK. 3. Exception handler containing: A. READ_ERROR: 1. Call WAIT_FOR_CLEAR. 2. Send a using RS_WRITE. 3. Call NEW_BLOCK. B. BLK_ERROR: 1. Call WAIT_FOR_CLEAR. 2. If block number is previous one: A. Send using RS_WRITE. B. Decrement error count. 3. Otherwise: A. Send using RS_WRITE. 4. Call NEW_BLOCK. 6. SEND is a procedure which implements the send portion of the XMODEM file transfer protocol. This procedure consists of: A. A call to LONG_READ to begin the transfer. B. Reset the error count. C. A loop containing: 1. An if statement testing for: A. A byte containing or a boolean specifing that the current block is the first to be sent: February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix B Page B-6 1. An if statement testing for the first block: A. Set the boolean value to false. 2. Otherwise: A. UPDATE_FOR_NEXT_BLOCK. 3. An if statement testing for the end of input file condition: A. Reset error count to 0. B. End the transmission by sending an and receiving an by calling LOOK_FOR_RESPONSE. C. Return to the calling procedure. 4. Read a 128 byte block by calling F_READ_BLOCK. B. Error count reaching the error limit: 1. Raise the file transfer error exception. C. Otherwise 1. Increment the error counter. 2. Send start of header using RS_WRITE. 3. Send block number using RS_WRITE. 4. Send complement of block number using RS_WRITE. 5. Send 128 byte block of data using RS_WRITE_BLOCK. 6. Calculate the checksum by calling LOW_BYTE_OF_SUM. 7. Send the checksum using RS_WRITE. 8. Look for an or from the receiver using RS_READ_WITH_TIMEOUT. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix C Page C-1 APPENDIX C Kermit File Transfer Protocol A. Kermit Protocol Overview Information is transferred between two Kermits using sequenced packets. The sequence numbers cycle through 0 to 63. Each packet is preceded by a ASCII SOH to indicate the packet start. Each packet ends with a checksum (and an optional end of line character). There are several packet types. This Kermit uses the following set: S - Send initialization F - File header D - Data Z - signals end of file B - Break transmission N - NAK Y - ACK T - Timeout -- internal to one side of transfer Q - corrupt packet received -- internal to one side A Kermit packet has the following format: (optional padding chars) SOH Packet length indicator for this packet Packet sequence number (somewhere between 0 and 63 inclusive) Packet type (one of the above) Data (maximum for this Kermit of 91 bytes per packet) Checksum (optional end of line) Kermits have the ability to negotiate certain parameters at the start of a file transfer. This is done with the S packet. The sending Kermit will place its desired parameters into an S packet and send it to the receiving Kermit. The receiving Kermit will send the sending Kermit its S packet with its parameters. Upon examination of these parameters, each side can make adjustments to allow the transfer to continue. The parameters this Kermit understands and the current default values are: Packet Length -- default 94 Time in seconds before signalling internal timeout -- 5 seconds Number of padding characters required -- 0 Pad character to use -- NUL (ASCII 0) End of line character -- Carriage return (ASCII 13) Control character quote -- # Binary prefix -- Y February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix C Page C-2 The default length of 94 includes 3 overhead characters in the packet; there are 91 characters for data. Padding characters are used to precede packets. This Kermit does not require padding characters, but can send them to another Kermit. The control quote is the character that is used to precede control characters (more below). This Kermit asks for # and can accept any legal control quote (see da Cruz reference) for the other Kermit's control quote. The binary prefix is the character that is used when transferring 8 bit data over a 7 bit data path. This technique in Kermit is called 8 bit prefixing. This Kermit can do 8 bit prefixing, and indicates this with a Y, but does NOT automatically request 8 bit prefixing. If the other Kermit signals that it wants 8 bit prefixing, this Kermit will use the character that the other Kermit sends for the binary prefix (more below). Kermit does not permit the transfer of characters with the 7 lower order bits in the range of ASCII 0 to ASCII 31 plus ASCII 127 (the control characters) without coding them. Kermit encodes these characters by toggling bit 6 (7th bit from the right). This altered character is preceded by the control quote and the pair together constitute the control character. For example, to send an ASCII NUL (00000000), bit 6 is toggled (01000000). This new character is a @. Then the pair #@ is sent to the other Kermit. The other Kermit sees the # and knows the next character is special. It toggles bit 6 again and obtains 00000000, which is the original character. If # is part of the data, ## must be sent. Kermit can send binary data over 8 bit data communication paths much like it sends text data. If the 7 lower order bits are in the control character set or equal the #, the data byte is preceded by the control quote and the byte, with bit 6 toggled, is sent. Decoding occurs at the receiving Kermit, leaving the original byte. With an 8 bit data communication path, no other altering of the data bytes is necessary. Kermit also has a provision for sending 8 bit data over a 7 bit path--8 bit prefixing. If the two Kermits have negotiated for 8 bit prefixing (that is, both sides have this capability and one or the other side has requested it by placing a legal binary prefix character in the S packet), all bytes with the MSB equal to 1 will be preceded by the binary prefix character. The character most often used is &. The 7 lower bits are treated just as if 8 bit prefixing were not occurring. If the 7 lower order bits fall into the control character set, or are equal to #, they will be encoded and preceded by the control quote. If the MSB equals 1, the binary prefix is sent before the rest. For example, send the byte 11111111. First, it is determined by the sending Kermit that the MSB equals 1, so the binary prefix character is needed. It is then noted that the 7 lower order bits equal 1111111 (127, or ASCII DEL), which requires encoding. Bit 6 is toggled, leaving 0111111, which is the ? character. Note that the control quote is needed. The sending Kermit sends the sequence &#? for the byte 11111111. If the byte to send is an ASCII NUL (00000000), the top order bit is not set, so the characters sent are #@, as described before (& is NOT needed). The receiving Kermit knows to decode & as indicating that the next data byte (interpreted after any decoding for the control quote) should have its MSB set equal to 1. If the binary prefix character is part of the data during a February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix C Page C-3 transfer with 8 bit encoding, it must be prefixed by itself. So if & is used for the prefix and & is in the data, && must be sent. Kermit also encodes certain values to ensure that the result does not fall into the control character range. This occurs in the S packet, for example. All numeric values are altered by having 32 added to them. For example, the default values of 94 and 5 are sent as ~ and %, which are the ASCII characters 126 and 35 respectively. The packet sequence numbers are coded in this way as are the actual packet lengths for the packets being sent. The checksum this Kermit supports is the 8 bit sum folded into 6 bits mode. For more information about Kermit: KERMIT, A File Transfer Protocol Frank da Cruz Digital Press, 1987 B. Limitations of the Kermit reuse package This is NOT a full Kermit. There are no provisions in the software provided for 1) a user interface, 2) connect mode, nor 3) server mode. This package provides the high level source to do the necessary encoding to change file data into Kermit packets and to decode Kermit packets to obtain the original data. This package, with the appropriate user supplied routines and user set-up communication paths, will send or receive a file with any other Kermit. This package is designed to be part of a user program that the user has created to meet his/her needs. C. Changing the Reusable Kermit To change the default parameters for the S packet: The default constants are in the package KERMIT_CONSTANTS. The actual values that are used throughout the program (and are determined by the negotiate process) are found in the package KERMIT_GLOBALS. To change 8 bit prefixing to ON: Change QBIN_REQUEST to be equal to DEFAULT_QBIN. Set DO_8_BIT_PREFIXING equal to TRUE. (In KERMIT_GLOBALS package). To add features to the S packet: Change NUM_FEATURES in KERMIT_CONSTANTS. Add default values in KERMIT_CONSTANTS. Add global variables in KERMIT_GLOBALS. Add extra checks to the procedure CHECK_SI_RESPONSE in package GENERAL_UTILITIES. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix C Page C-4 Add extra options to the S packet Kermit sends when it is the receiver in the procedure CONSTRUCT_SI_RETURN in package GENERAL_UTILITIES. To modify the checksum used: Use one of the legal Kermit checksums (see da Cruz reference). Add that option to the S packet. Add the checksum routine to the package GENERAL_UTILITIES. You may need to add tests in the procedures PUT_PACKET and GET_PACKET in GENERAL_UTILITIES to know which CHECKSUM to use. To add repeat encoding: Add the encoding part to NEXT_DATA; the decoding part to EXTRACT_DATA. Both of these routines are in GENERAL_UTILITIES. To modify the packet size this Kermit would like to receive: To shrink, change DEFAULT_MAXL. To expand, change MAX_DATALEN (increases packet record size), change DEFAULT_MAXL. These variables are found in the package KERMIT_CONSTANTS. D. What is Happening Where This Kermit checks other Kermit's S packet and sets up global values -- GENERAL_UTILITIES.CHECK_SI_RESPONSE. This Kermit sets up its S packet -- GENERAL_UTILITIES.CONSTRUCT_SI_RETURN. Data is obtained from file and encoded -- GENERAL_UTILITIES.NEXT_DATA. Data is obtained from packet and decoded -- GENERAL_UTILITIES.EXTRACT_DATA. Direct interface to files for system -- F_READ, F_WRITE, OPEN_READ, OPEN_WRITE, CLOSE_READ, CLOSE_WRITE. The user supplies these and provides the real subprogram names upon instantiation. Direct interface to port -- TERMINAL_IO package, user supplied. CHECKSUM -- GENERAL_UTILITIES.CHECKSUM. Packets sent -- GENERAL_UTILITIES.SEND_PACKET (tracks retries). GENERAL_UTILITIES.PUT_PACKET (uses user supplied routine to write byte to port). Packets received -- GENERAL_UTILITIES.RECEIVE_RESPONSE (tracks total time waiting). GENERAL_UTILITIES.GET_PACKET (uses user supplied routine to read byte from port). Coding of characters -- Add 32 -- GENERAL_UTILITIES.TOCHAR Subtract 32 -- GENERAL_UTILITIES.UNCHAR Toggle bit 6 -- GENERAL_UTILITIES.CONTROLIFY. Send initialization packet, file header, data and end of file (also break transmission) -- SEND_UTILITIES package. February 29, 1988 User's Manual N60921-87-C-0286 STARS Network Protocol Appendix C Page C-5 Receive initialization packet, file header, data (and end of file and break transmission) -- RECEIVE_UTILITIES package. NOTE -- the above mentioned packages are all part of the KERMIT_PROTOCOL package body (which is part of the NETWORK PROTOCOL package body).