Revised 27 AUG 90 - Minor type corrections, section 9 added. Pacsat Protocol: File Transfer Level 0 Jeff Ward, G0/K8KA Harold E. Price, NK6K ABSTRACT This document specifies Version 0 of the File Transfer Level 0 (FTL0) protocol designed for use on store-and-forward satellites (PACSATs). The protocol provides procedures for transferring binary files to and from a server computer using an error- corrected communication link. Further to basic file transfer facilities, FTL0 provides file selection and directory procedures. Because a server may contain many files, only some of which are of interest to each client, the client may ``select'' a subset of the server's files. Subset selection is based on a flexible logical equation involving a large number of file characteristics. The scope of directory requests or file download requests can be limited to those files currently selected. This protocol is designed to work specifically with files in which the actual ``data'' or ``body'' of the file is preceded by a standard ``header'', specified in the PACSAT File Header Defini- tion document. 1.0 BACKGROUND Terrestrial packet-radio bulletin board systems (PBBSs) in the amateur radio service generally provide a character-based, human-to-machine interface through which user's command the PBBS software. A similar interface has been adopted on the FUJI-OSCAR store-and-forward (PACSAT) satellites. Through the character-based interface, the user selects messages, requests directory list- ings, and views, stores and deletes messages. All messages are stored as ASCII text files, and the PBBS maintains a directory entry for each message. The directory contains message source, destination, title, time of storage, size, and status. The PBBS also stores data relating to each user station, such as the most recent message each user station has listed or viewed. Since messages and PBBS commands contain only ASCII characters, the user's station equipment can be as basic as an ASCII terminal connected to a terminal node controller (TNC). This simplicity makes the current system attractive, and has lead to its widespread adoption. These current PBBS systems also have several drawbacks, stemming from the text-based user interface and from the lack of a flexible, informative message header. All messages must be in ASCII, only simple ASCII message headers are supported, and only a few search-keys are provided for message selection. These limitations are particularly damaging in the PACSAT environment, where the user base is large, the communications bandwidth is restricted, and the onboard computer software must be compact and highly reliable. The File Transfer Level 0 protocol defined here, and the PACSAT File Header Definition presented elsewhere, combine to provide a PBBS protocol suite which overcomes the limitations of the current text-based protocols. The proposed protocols are based on a different model of a store-and-forward messaging network. The PBBS is a ``server'' and the user stations are ``cli- ents''. The server stores files, each of which contains a ``header'' of known format, followed by a ``body''. The header holds information about the file and about the body, including (but not limited to) the file length, creation date, destination, source, keywords, and body compression technique. The body is the data portion of the file, which can be any digital information, e.g. binary, ASCII, FAX, digitised voice, etc. The user station, or ``client'' is assumed to be under computer control. The client sends files to the server and receives files from the server over an AX.25 data link, using an automated server/client file transfer protocol. The client software interprets and displays the file headers and bodies for the human user. When the user wishes to upload a file to the server, client software must add suitable standardized header fields to the file, and it may also compress or otherwise prepare the file for uploading. Each user is generally interested in only a small subset of the files avail- able on a server. Using a powerful selection facility the client can select an interesting subset of the files on the server for directory listing or downloading. The selection can be based on any combination of items in the file header, thus user's software can assure that the user only ``sees'' files which are likely to be of interest. The server might not keep a user data base, and the client software must store any important information concerning the user's last server session. For example, to implement a command equivalent to the PBBS command ``list new'', the client software must store the message number, or date and time of the of the last access to the server. Since this protocol is also useful for terrestrial servers, we use the terms ``server'' and ``client'' throughout, instead of ``PACSAT'' and ``groundsta- tion''. The protocol does depend on the presence of the standard PACSAT file header, this is to implement file locking or other features. A version of the protocol that can be used by terrestrial stations without the PACSAT headers is under consideration. FTL0 includes several features that make the protocol somewhat more complex than some others in use in the amateur packet network. These features include simultaneous bidirectional file transfer, file locking by forwarding gateways, and multiple destination forwarding. As is sometimes the case, the actual implementation is smaller than the specification. The pseudo-code provided in Appendix B and C show that the protocol is actually quite straightforward. The authors also plan to make the prototype source code available on a public BBS. 1.1 FTL0 The FTL0 protocol can support full-duplex message transfer, in which a single data link (AX.25 connection) is used simultaneously to upload one file and to download another file. Client software does not necessarily have to implement this capability. The protocol provides for continuation of uploads and down- loads interrupted by loss of the data link (generally caused by LOS at a satellite groundstation), and includes confirmation handshakes at all critical stages of file transfer. An FTL0 file transfer should withstand interruption at any stage. It is assumed that the client software uses the transparent mode of an AX.25 TNC and that the AX.25 connection represents an error-free channel. Other data links which present an ordered, error corrected byte stream may be used. Although the link may be terminated at any time, it is assumed that the link will not pass corrupted or out-of-order bytes, and that processes at both ends of the link will be notified if the link is terminated. The PACSAT File Header standard provides overall checks on the integrity of files transferred to and from fully-compliant servers. FTL0 commands and responses form simple ``packets'' inside the byte stream on the communications link. Specifically, in AX.25, an FTL0 packet may be trans- mitted in one or more AX.25 I frames; neither the server nor the client is aware of the AX.25 I frame boundaries. The packet format is described in 2.0 below. 1.2 Associated Documents PACSAT Data Specification Standards defines the meaning of data types and structures within this specification. The PACSAT File Header Definition defines the file header fields which must be pre-pended to files before uploading to a fully-compliant FTL0 server. (FTL0 procedures for terrestrial servers without PACSAT file headers are under development.) 1.3 Terminology server is the PACSAT or the PBBS. client is the user station. commands are transmitted from the client to the server responses are transmitted from the server to the client uplink is data flow from the client to the server downlink is data flow from the server to the client packet is a sequence of bytes as defined in 2.0 below frame is an AX.25 level 2 I frame data link generally an AX.25 level 2 link, but may be a link using any protocol which provides an ordered, error-checked, data transparent byte stream. 1.4 Overview of Operation To allow simultaneous uploading and downloading, FTL0 clients and servers implement two state machines. One is related to file uploads, and the second to all other possible commands. FLT0 is not symmetric; the protocol state machines implemented by the server are necessarily different from those imple- mented by the clients. Dividing the data stream into packets allows for modular software implementa- tion and the multiplexing of commands and data on a single data link. The packet format is simple. Every packet begins with 2 bytes of control informa- tion, which can be followed by 0 to 2047 bytes of data. The packet may arrive in many AX.25 I frames. No packet synchronization or checksumming is provid- ed, since the data link (AX.25 connection) provides a notionally error-free connection. Full file error checks are performed at the completion of file transfers. It is assumed that neither the client software nor the server software is aware of or can control data link (AX.25) frame boundaries. A FTL0 session starts when an data link is established between the server and the client. The server will send a LOGIN response when the connection is established. To allow the user to specify a group of files for directory listings or down- loading, the client software implement may implement menus or some other user interface. Once the user has indicated the desired files, the client software converts the user's preferences into an equation , such as ( (SOURCE = "G0K8KA*") && (KEYWORD = "*FTL0*") ) && (FILE_NUMBER > 3215). And then encodes the equation in a postfix, binary format as a SELECT command. When the server receives a SELECT command it builds a list of files for which the equation evaluates to TRUE. As a response to the SELECT command, the server informs the client how many files are in the selection list. When the client sends a one of the directory commands, the server responds by transmitting directory information for the next 10 files on the selected list. Each subsequent directory command results in the server transmitting directory information for a further 10 files from the selection list, until the list is exhausted. Specific files or files from the selection list may be requested by the client for downloading. The download procedure consists of two command/response cycles. On the first cycle, the client requests the file and the server responds by transmitting the file as a series of DATA packets followed by an END_OF_DATA packet. The server then waits for the client to acknowledge re- ceipt of the file. When the server receives the acknowledgement, it transmits a final handshake and the download is finished. To upload a file to the server, the client sends an UPLOAD command telling the server how large the file is. The server responds with a handshake which either tells the client to abort or to proceed. If instructed to proceed, the client sends the entire file as a series of DATA packets followed by an DATA_END packet. The server receives the entire file, and then either ac- knowledges the transfer or sends an error indication. Because PACSAT may go over the horizon in the midst of a transaction, down- loading and uploading can be continued during several sessions with the serv- er. When a download is interrupted, the client must retain the file offset at which communications was interrupted. For interrupted uploads, the server stores the appropriate offset. 1.5 File Identification Although servers may identify files using some kind of system file name (PACSATs use the MS-DOS standard of an 8 character body and a 3 character extension), FTL0 does not use server file names to identify files. Instead, the server assigns every file a 32-bit file number. This is to insure that two files with different contents but the same name will never be confused. Thus, every message which a user uploads to PACSAT (or another FTL0 server) will have a unique identifier. 1.6 Gateway Procedures Some messages on PACSAT will be destined for gateway stations which will introduce the messages into other networks. It is essential that only one gateway download and relay each message. To accommodate this, FTL0 provides locked downloads. Only one gateway at a time can perform a locked download of a given file for a given destination. If a locked download is interrupted, this will be indicated in the PACSAT File Header of the file, so that other gateways can tell when a file is in the process of being delivered. PACSAT File Headers allow files with multiple destinations, and separate locks are implemented for each destination. See Appendix A for further information. 1.7 Delivery Registration A simple form of delivery registration is supported by FTL0. In the final handshake after receiving a file, the client can command the server to modify the contents of the PACSAT File Header to show the AX.25 address of the client and the time at which the download was completed. It is intended that this facility be used if the file is specifically addressed to the client station, not for files of general interest. If the file has multiple destinations, one ``registration'' is supported for each destination. See Appendix A for fur- ther information. 1.8 State Variables In order to support full-duplex operations, the server and the client maintain 2 state variables, one relating to the uploading of files and the other relat- ing to all other operations (selecting, directories, and downloading). These are called the uplink state and the downlink state variables. Appendix B provides pseudo-code definitions of the state transitions for servers, Appendix C is for clients. 2.0 PACKET FORMAT An FTL0 packet is a sequence of information bytes preceded by a two byte header. After establishment of a data link, the first byte delivered to either client or server is the first byte of a packet header. The packet header informs the client/server the type of the packet and the number of information bytes which will follow. There may be between 0 and 2047 informa- tion bytes, inclusive. After reception of the final information byte of a packet, the client/server expects the next byte to be the first byte of anoth- er packet header. Such a stream is shown below, where [] indicates that there may be no data bytes.

[...]

[...] |----First FTL0 packet-----|----Second FTL0 packet---| 2.1 Header Format struct FTL0_PKT { unsigned char length_lsb; unsigned char h1; } - 8 bit unsigned integer supplying the least significant 8 bits of data_length.

- an 8-bit field. bits 7-5 contribute 3 most significant bits to data_length. bits 4-0 encode 32 packet types as follows: 0 DATA 1 DATA_END 2 LOGIN_RESP 3 UPLOAD_CMD 4 UL_GO_RESP 5 UL_ERROR_RESP 6 UL_ACK_RESP 7 UL_NAK_RESP 8 DOWNLOAD_CMD 9 DL_ERROR_RESP 10 DL_ABORTED_RESP 11 DL_COMPLETED_RESP 12 DL_ACK_CMD 13 DL_NAK_CMD 14 DIR_SHORT_CMD 15 DIR_LONG_CMD 16 SELECT_CMD 17 SELECT_RESP All other values reserved 2.2 Information Length The value is formed by pre-pending bits 7-5 of the

byte to the byte. indicates how many more bytes will be received before the beginning of the next packet. If is 0, there are no information bytes. 3.0 LOGON As soon as a data link is established between the client and the server, the client is considered to be logged on. The server sends a LOGIN_RESP packet with one byte of flags and a 4-byte timestamp. When the client receives the LOGIN_RESP packet the server is initialized and ready to begin transactions. 3.1 Initiation of Session An FTL0 session is initiated when a data link is established between the client and the server. 3.2 Server Login Response Packet When the data link is established the server transmits a LOGIN_RESP packet. Packet: LOGIN_RESP Information: 5 bytes struct LOGIN_DATA{ unsigned long login_time; unsigned char login_flags; } - a 32-bit unsigned integer indicating the number of seconds since January 1, 1970. - an 8-bit field. bit:76543210 xxxxSHVV Bit 3, the SelectionActive bit, will be 1 if there is already an active selec- tion list for this client. The SelectionActive bit will be 0 if there is no active selection for this client already available. Bit 2, the HeaderPFH bit, will be 1 if the server uses and requires PACSAT File Headers on all files. If the HeaderPFH bit is 1, the flag PFHserver used in the following definition should be considered TRUE. The HeaderPFH bit will be 0 if the server does not use PACSAT File Headers. If the HeaderPFH bit is 0, the modified procedures specified in Section 7 should be used. Bits 1 and 0 form a 2-bit FTL0 protocol version number. The version described here is 0. 3.3 Server Login Initialization Upon transmitting the LOGIN_RESP packet the server should initialize its state variables to UL_CMD_WAIT and DL_CMD_WAIT. 3.4 Client Login Initialization Upon receiving the LOGIN_RESP packet, the client should initialize its state variables to UL_CMD_OK and DL_CMD_OK. 4.0 SELECT The select command is the mechanism through which the client can search the server for desirable files. The human user can search the files on the server based on any information contained in the PACSAT File Header. To achieve this goal, the implementation and specification go through several levels of ab- straction which must be followed closely. The user's desires form an equation. The equation might simply be ``the file is to G0K8KA and it was stored after my last logon''. Or it might be more complex, e.g. ``the file is less than 8 kbytes, and it was created after 9 July 1990, and it has ``landrover'' as one of its keywords''. Humans would naturally express this in ``infix'' notation: (FILE_SIZE < 8k) && (CREATE_DATE > 9 July 1990) && (KEYWORDS == "*landrover*") The server uses ``postfix'' notation, like an RPN calculator, and wants an equation like: (FILE_SIZE < 8k) (CREATE_DATE > 9 july 1990) && (KEYWORDS == "*landrover*") && To convert a postfix logical equation into a SELECT command, the client must encode the logical operators, the relational operators the header item names, and the values to compare against. The header item names and comparison values are encoded just as they are in the PACSAT File Header definition. The logical operators and relational operators are encoded as single bytes. The complete syntax is defined below. 4.1 Client Issuing Select Command When the client's downlink state variable is DL_CMD_OK (e.g. the client is not involved in another select, file download, or directory download), the client may transmit a SELECT_CMD packet. Packet: SELECT_CMD Information: variable length SELECTION SELECTION is defined recursively by the following structures and rules. struct SELECTION { struct LVALUEx equation; unsigned char end_flag; } - 0x00 is recursively defined by two structures LVALUE0 and LVALUE1: struct LVALUE0 { struct LVALUEx t1; struct LVALUEx t2; unsigned char lop; } and are further LVALUE0 or LVALUE1 structures. is and 8-bit field representing a logical operator: bit 76543210 00000001 is AND 00000010 is OR struct LVALUE1 { unsigned char relop; unsigned int item_id; unsigned char length; unsigned char constant[]; } is an 8-bit field encoding a relational operator: bit7 0 bit654 Relational Operator 000 equal to 001 greater than 010 less than 011 not equal 100 greater than or equal to 101 less than or equal to 110 reserved 111 reserved bit3210 Type of Comparison 0000 treat as a multi-byte unsigned integer (valid for 1,2, and 4). 0001 treat as a multi-byte signed integer (valid for 1,2,and 4). 0010 treat as an array of unsigned char 0011 treat as an array of ASCII characters, convert to lower case before making comparison. 0100 treat as an array of ASCII characters, convert to lower case before comparison and interpret wildcard characters. ALL OTHER VALUES RESERVED. is a 16-bit unsigned integer identifying one of the PACSAT Header Definition header items. is the number of bytes in the array. is an array of bytes which are compared against the header item identified by , using the specified relational operator and compari- son type. 4.2 Response to Select Command The server responds with one of the packets from 4.2.1 or 4.2.2 and returns its downlink state to DL_CMD_OK, ready to accept another command from the client. 4.2.1 Successful Selection If the server can interpret the SELECT_CMD packet, it responds with a SELECT_RESP packet Packet: SELECT_RESP Information: 2 bytes unsigned int no_of_files is a 16 bit unsigned integer telling how many files have been selected. It may be 0. 4.2.2 Unsuccessful Selection If the server cannot interpret the SELECT_CMD packet, it responds with a DL_ERROR_RESP packet. Packet: DL_ERROR_RESP Information: 1 byte unsigned char err_code is ER_POORLY_FORMED_SEL if the selection equation could not be parsed by the server because of a syntax error. 5.0 DOWNLOAD To receive a file from the server, the client uses the download command. This command can be used to download a specific file, to continue the downloading of a specific file, or to download the next file in the selection list. 5.1 Client Initiates Download When the client's uplink state variable is DL_CMD_OK, the client may send the DOWNLOAD_CMD packet. Packet: DOWNLOAD_CMD Information : 9 bytes of arguments with the following structure struct { unsigned long file_no; unsigned long byte_offset; unsigned char lock_destination; } is a 32-bit binary integer uniquely identifying a file on the serv- er. Two reserved values have special meanings: If is equal to 0xffffffff, the server will attempt to use the next file in the current selec- tion list, moving from older files to newer files. If is equal to 0, the server will attempt to use the next file in the current selection list, moving from newer files toward older files. If is not one of the reserved values, the server attempts to download the file which it associates with . is a 32-bit unsigned binary integer giving the offset from the beginning of the file at which the download should begin. If the client is continuing an aborted download, this argument should be set to the number of bytes previously received. Otherwise it should be 0. is an 8 bit unsigned binary integer. It will generally be set to 0 by non-gateway stations. [If is not 0, it indicates that the client wishes to con- duct a locked download for the destination numbered by . If the exists and is not already locked, the client's AX.25 address is placed in the PACSAT File Header AX25_DOWNLOADER item associated with the specified DESTINATION item. Destination numbering is defined in section Appendix A.] 5.2 Server Responses to the Download Command When it receives a DOWNLOAD_CMD packet the server determines whether the download is possible. This may include determination of the desired file number from the current select list. 5.2.1 Downlinking File Data If the download is possible the server transmits the file data beginning bytes from the beginning of the file. If is greater than or equal to the file length, no data is transmitted. The file data bytes are transmitted as information in DATA packets. These packets may be any size from 0 to 2047 bytes. [If is not-zero, the server sets the asso- ciated before beginning to send DATA packets.] Once the server has transmitted a DATA packet containing the last byte of the file, or if the was greater than or equal to the file length, the server transmits a single DATA_END packet. After transmitting the end packet, the server expects to receive a DL_ACK_CMD or DL_NAK_CMD. 5.2.2 Failure of Download Command If the server cannot service the download command, it responds with a DL_ERROR_RESP packet. Packet: DL_ERROR_RESP Information: 1 byte unsigned char err_code; is an 8-bit unsigned binary integer will be one of: ER_SELECTION_EMPTY if the selection list has no more files in it or no select command was previously received. ER_NO_SUCH_FILE_NUMBER if the file identified by does not exist. [ER_ALREADY_LOCKED - was not 0, and the file is already locked for the specified destination. ER_NO_SUCH_DESTINATION - was not 0, and the file has fewer than DESTINATION items in its PACSAT File Header.] 5.3 Client Accepting or Rejecting Downloaded File 5.3.1 Successful Download Upon reception of the DATA_END packet from the server, the client performs any possible checks on the received file. If the file passes the checks, the client transmits a DL_ACK_CMD packet. Packet: DL_ACK_CMD Information: 1 byte unsigned char is an 8-bit unsigned integer identifying one of the destinations in the PACSAT File Header of the downloaded file. should be 0 if the client does not wish to register receipt of the file. Upon receiving the DL_ACK_CMD packet, the server completes the download proc- ess. [If is not 0, the appropriate DESTINATION item in the PACSAT File Header is located and the associated AX25_DOWNLOADER and DOWNLOAD_TIME items are updated. If was non-zero in the DOWNLOAD_COMMAND, the server locates the appropriate DESTINATION item in the PACSAT File Header and updates the associated DOWNLOAD_TIME item.] 5.3.2 Unsuccessful or Aborted Download If the client wishes to abort the download before receiving the DATA_END packet from the server, or finds that the downloaded file fails some integrity test after reception of the DATA_END packet, the client sends the DL_NAK_CMD packet. Packet: DL_NAK_CMD Information: none Upon receiving this packet, if the server has not already sent the DATA_END packet, it will do so and proceed to the final unsuccessful download handshake (5.4.2). If DL_NAK_CMD is received after the server has transmitted the DATA_END packet, the server proceeds to the final download handshake. 5.4 Final Download Handshake 5.4.1 Completion of Successful Download [If the server receives the DL_ACK_CMD, it removes any lock from the file and sets and for the specified item.] [If in the DL_ACK_CMD is non-zero, the server attempts to set the and items associated with the specified item. If the does not exist, the server transmits a DL_ABORTED_RESP packet.] If was 0, the server transmits a DL_COMPLETED_RESP packet, and returns its downlink state variable to DL_CMD_OK. Packet: DL_COMPLETED_RESP Information: none. This response tells the client that the server has completed processing the DL_ACK_CMD. The client downlink state variable should be set to DL_CMD_OK. If the L2 link fails before the client receives the DL_DONE_RESP, the client cannot be sure the DL_ACK_CMD was processed. This is important if the client had specified a or a . In either of these cases, the client should treat the download as incomplete and continue it later. This assures that the PACSAT File Header has been properly modi- fied. If both and were 0, the client can consider the download complete. 5.4.2 Completion of Unsuccessful Download A download is ``unsuccessful'' if the server receives the DL_NAK_CMD from the client or if is non-zero and indicates a non-existent destination. If was non-zero, the lock is removed and is updated. The server transmits the DL_ABORTED_RESP packet. Packet: DL_ABORTED_RESP Information: none The server downlink state variable returns to the DL_CMD_OK state. Upon reception of the DL_ABORTED_RESP the client downlink state variable returns to DL_CMD_OK. 6.0 DIRECTORY The client uses directory commands to get information about files on the server. Servers conforming to the PACSAT File Header Definition send PACSAT File Headers as directory entries. ``Long'' directory entries are the com- plete PACSAT File Header and ``short'' directory entries are only the Mandato- ry File Header items. The client can request a directory entry for a specific file or for the files in the selection list. The selection list can be scanned from oldest to newest files or from newest to oldest files. 6.1 Initiating a Directory The client may request a directory whenever the client downlink state variable is DL_CMD_OK. To request a directory, the client transmits either a DIR_LONG_CMD packet or a DIR_SHORT_CMD packet. Packet: DIR_LONG_CMD or DIR_SHORT_CMD Information: 4 bytes unsigned long file_no; is a 32-bit unsigned binary integer identifying a file or files on the server. There are two reserved values: 0 and 0xffffffff. If is 0xffffffff, the server will send directory entries for the next 10 files in the current selection list, moving from older files to newer files. If is 0, the server will send directory entries for the next 10 files in the current selection list, moving from newer files toward older files. 6.2 Server Responses to Directory Commands 6.2.1 Successful Directory Request If the directory request can be serviced (there are files in the selection list, or a specified file exists) the server will transmit one or more PACSAT File Headers in a series of DATA packets followed by a DATA_END packet. A maximum of 10 file headers will be transmitted for each DIR command. 6.2.2. Failed Directory Request If the directory request cannot be serviced, a DL_ERROR_RESP packet is trans- mitted. Packet: DL_ERROR_RESP Information: 1 byte unsigned char err_code; will be one of: ER_SELECTION_EMPTY - if the was 0 or 0xffffffff, and either there are no files left in the selection list or there is no selection list. ER_NO_SUCH_FILE_NUMBER - if is not 0 or 0xffffffff and no file identified by exists on the server. 7. UPLOAD 7.1. Initiating an Upload The client can initiate an upload any time the client's upload state variable is UL_CMD_OK. Packet: UPLOAD_CMD Information: 8 bytes struct { unsigned long continue_file_no; unsigned long file_length; } - a 32-bit unsigned integer identifying the file to contin- ue. Used to continue a previously-aborted upload. Must be 0 when commencing a new upload. - 32-bit unsigned integer indicating the number of bytes in the file. 7.2 Server Responses to Upload requests Downlink Packet: UL_GO_RESP or UL_ERROR_RESP 7.2.1 Successful Upload Request Packet: UL_GO_RESP Information: 8 bytes struct { unsigned long server_file_no; unsigned long byte_offset; } is a 32-bit unsigned binary integer identifying the client's file on the server. is a 32-bit unsigned binary integer number of bytes from the beginning of the file at which the client should begin file transmission. This will be 0 if the was zero. After receiving the UPLOAD_PROCEED_RESP packet, the client should advance to the data transmitting state described in Section 7.3. 7.2.2 Unsuccessful Upload Request If the server cannot process the upload request, it will transmit an UL_ERROR_RESP packet. Packet: UL_ERROR_RESP Information: 1 byte unsigned char err_code; must be one of: ER_NO_SUCH_FILE_NUMBER if is not 0 and the file identified by does not exist. Continue is not possible. ER_BAD_CONTINUE if is not 0 and the does not agree with the previously associated with the file identified by . Continue is not possible. ER_FILE_COMPLETE if is not 0 and the file identified by was completely received on a previous upload. Note - receipt of this command should be accepted by the client as confirmation of file receipt by the server. ER_NO_ROOM if the server does not have room for the file. After transmitting the UL_ERROR_RESP packet, the server's uplink state varia- ble is set to UL_CMD_OK. 7.2.3 Continuation of Uploads Any file for which the client receives a UL_GO_RESP should be continued until a UL_ACK_RESP or a non-recoverable UL_ERR_RESP or UL_NAK_RESP for that file is received. The server should be prepared to continue reception of any file for which it has transmitted a UL_GO_RESP. Some file numbers will be allocated by the server and lost by link failure before the UL_GO_RESP reaches the client; a 32-bit file number space provides sufficient scope for some lost file num- bers. To avoid saving partial files for these lost file numbers, the server should not reserve space for a message until it has received at least one DATA packet from the client. 7.3. Data Uplinking Stage The client now uplinks the bytes from the file, in DATA packets. The uplink- ing should begin bytes from the start of the file. After trans- mitting a DATA packet containing the last byte in the file, the client should transmit a DATA_END packet. The client should also transmit a DATA_END packet if the was greater than or equal to the file length. The server may attempt to terminate the upload by transmitting a UL_NAK_RESP at any time during the upload. If the client receives a UL_NAK_RESP packet before transmitting a DATA_END packet the client must send a DATA_END packet. 7.4. Completion of Upload 7.4.1 Successful Upload Completion When the server receives the DATA_END packet it will check the integrity of the file as far as possible. If the checks pass, the server will downlink a UL_ACK_RESP packet. Packet: UL_ACK_RESP Information: none After transmitting the UL_ACK_RESP the server uplink state variable is UL_CMD_OK. After receiving the UL_ACK_RESP, the client uplink state variable is UL_CMD_OK. 7.4.2 Failure Caused by Server Rejecting Upload The server may reject an upload while the client is sending DATA packets (due to file system problems on the server) or after the client has sent the DATA_END packet (due to corruption of the file). If the server must abort the upload while receiving DATA packets or after receiving the DATA_END checks fail, it sends the UL_NAK_RESP packet. Information: 1 byte unsigned char err_code; must be one of: ER_BAD_HEADER - The file either has no PFH, or has a badly-formed PFH. ER_HEADER_CHECK - The PFH checksum failed. ER_BODY_CHECK - The PFH body checksum failed. ER_NO_ROOM - The server ran out of room for file storage before the upload was complete. The server will implement procedures to avoid frequently running out of room, but this cannot be guaranteed. After transmitting the UL_NAK_RESP packet, the server uplink state variable is UL_CMD_OK. After receiving the UL_ERROR_RESP, the client uplink state varia- ble is UL_CMD_OK. 7.4.3 Link Failure During Upload If the data link fails before the server receives the DATA_END packet, the server retains the offset of the next byte needed for the file. This value will be transmitted by the server as if the client later contin- ues the upload by specifying the in the of an UPLOAD_CMD packet. If the offset is not 0, the server may safely retain a temporary file containing the data received so far. If the server retains files for which the is 0, these should be purged after some reasonable time, since the client may not know the of the file. 8.0 TERMINATION OF SESSION The session is terminated by closing the data link. Either the client or the server may decide to close the link when uplink state is UL_CMD_OK and down- link state is DL_CMD_OK. The link is also terminated if unexpected packets are received. If the link terminates when any state machine is not in the _CMD_OK state, appropriate actions are taken. 9.0 OTHER ERROR CONDITIONS There are other error conditions which might occur when a server is processing commands. Such errors are indicated by DL_ERROR_RESP or UL_ERROR_RESP packets with appropriate error codes. Robust client implementations will be prepared to handle such packets at any time during the session. Specific codes which have currently been assigned are ER_ILL_FORMED_CMD and ER_SERVER_FSYS. 9.1 ER_ILL_FORMED_CMD This error code is transmitted by the client when a command is received with too many or too few data bytes, and when an unrecognized command is received. The current command is aborted and the appropriate server state machine is returned to the _CMD_OK state. 9.2 ER_SERVER_FSYS This indicates a failure in the server file system, e.g. no file handles available for the server to complete the requested operation. The current command is aborted, and the appropriate server state machine is returned to the _CMD_OK state." APPENDIX A - Use of the PACSAT File Header The PACSAT File Header Definition defines a standard header which will be found at the beginning of every file downloaded from PACSAT (or any fully compliant FTL0 server). One purpose of the PACSAT File Header is to allow clients to determine the status of files on the server. Specifically, the originating client may wish to find out if the file has been downloaded by its intended destination, and a Gateway client may wish to find out if a message still needs to be downloaded for relay to a particular destination. Both of these tasks are done by exam- ining a set of PACSAT File Header Items comprising , and . A gateway will examine to see if it can relay or deliver the file. If so, it will examine and to deter- mine the delivery status of the message: If is zero, the message still needs to be relayed. If is non-zero, but is blanks, the message is in the process of being downloaded, and the download started at . If is non-zero, and is non-blank, the mes- sage has been downloaded for relay to the . A similar (but simpler) procedure is used to see if a specific destination station has ``registered receipt'' of a file. When receipt is registered (at the end of a successful download), and will both be correctly set. For these checks to work correctly, the downloading clients must use the proper command procedures. Gateways must set the correct in their DOWNLOAD_CMD packets, and clients must set the correct in the DL_ACK_CMD. The procedure should be implemented by all gateways. The procedure is optional for client implementations. The proper number for or is deter- mined as follows. If a file has only one item, it is destina- tion 1. Any other destinations are numbered sequentially in order of occur- rence in the PACSAT File Header. APPENDIX B - Server State Transition Definitions SERVER STATE DEFINITIONS The following pseudo code defines the transitions of the Server state machines in FTL0. One state machine is used for file uploading. The other state machine is used for all other procedures. It is assumed that the data link will be terminated if there have been no packets transmitted or received for a period of time (TBD). If the link is terminated by this ``activity timeout'' both state machines receive a ``Data Link Terminated'' event. ``Data Link Terminated'' is also generated if the link fails for any reason. When an unexpected packet is received by one of the state machines, that state machine terminates the data link and returns to an uninitialized state. The second state machine is notified of this through a ``Data Link Terminated'' event, and also returns to an uninitialized state. At this point, the FTL0 processing for this client ceases until the establishment of another data link. STARTUP State variables are created when a data link is established between client and server. The server executes the following: Transmit LOGIN_RESP packet. ul_state := UL_CMD_OK dl_state := DL_CMD_OK SERVER UPLINK STATE MACHINE This machine receives only frames which are relevant to the file uploading process : UPLOAD_CMD, DATA, and DATA_END. It also is executed upon timeout of the input timer or termination of the level 2 link (from local or remote causes). state UL_CMD_OK { EVENT: Receive UPLOAD_CMD packet{ if ok to upload Send UPLOAD_GO_RESP packet. ul_state <- UL_DATA_RX else Send UL_ERROR_RESP packet. ul_state <- UL_CMD_OK } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. ul_state <- UL_UNINIT } } state UL_DATA_RX { EVENT: Receive DATA packet { Try to store data. if out of storage { Transmit UL_NAK_RESP packet. Close file. Save file_offset and file_number. ul_state <- UL_ABORT } else { Update file_offset. ul_state <- UL_DATA_RX } } EVENT: Receive DATA_END packet { Close file. if file passes checks { Transmit UL_ACK_RESP packet ul_state <- UL_CMD_OK } else { file_offset <- 0 Save file_offset and file_number Transmit UL_NAK_RESP packet ul_state <- UL_CMD_OK } } EVENT: DEFAULT{ if (file_offset > 0) Save file_offset and file number. if EVENT is not "data link terminated" Terminate data link. ul_state <- UL_UNINIT } } state UL_ABORT { EVENT: Receive DATA packet ul_state <- UL_ABORT EVENT: Receive DATA_END packet ul_state <- UL_CMD_OK EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. ul_state <- UL_UNINIT } } SERVER DOWNLINK STATE MACHINE This machine receives all packets other than UPLOAD_CMD, DATA, and DATA_END. state DL_CMD_OK { EVENT: Receive SELECT_CMD packet { if syntax is correct { Form select list. Transmit SELECT_RESP packet. dl_state <- DL_CMD_OK } else { Transmit DL_ERROR_RESP packet. dl_state <- DL_CMD_OK } } EVENT: Receive DIR_LONG_CMD or DIR_SHORT_CMD packet { if there are directories to send dl_state <- DL_DIR_DATA else { Transmit DL_ERROR_RESP packet. dl_state <- DL_CMD_OK } } EVENT: Receive DOWNLOAD_CMD packet { if request can be serviced { seek to if <> 0 set PFH DOWNLOAD_TIME. dl_state <- DL_FILE_DATA } else { Transmit DL_ERROR_RESP packet. dl_state <- DL_CMD_OK } } EVENT: Receive DL_NAK_CMD packet dl_state <- DL_CMD_OK EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- DL_UNINIT } } state DL_DIR_DATA { if there is more directory data to send { Transmit directory data in DATA packets. dl_state <- DL_DIR_DATA } else { Transmit DATA_END packet. dl_state <- DL_CMD_OK } EVENT: Receive DL_NAK_CMD packet{ Transmit DATA_END packet. dl_state <- DL_CMD_OK. } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- DL_UNINIT } } state DL_FILE_DATA { if there is more file data to send Transmit file data in DATA packets. dl_state <- DL_FILE_DATA } else { Transmit DATA_END packet. dl_state <- DL_FILE_END } EVENT: Receive DL_NAK_CMD packet { If lock_destination <> 0 unlock lock_destination. Transmit DATA_END packet. Transmit DL_ABORTED_RESP packet. dl_state <- DL_CMD_OK } EVENT: DEFAULT { If lock_destination <> 0 unlock lock_destination. if EVENT is not "data link terminated" Terminate data link. dl_state <- DL_UNINIT } } state DL_FILE_END { EVENT: Receive DL_NAK_CMD packet { dl_state <- DL_CMD_OK Transmit DL_ABORTED_RESP packet. If lock_destination <> 0 unlock lock_destination. } EVENT: Receive DL_ACK_CMD packet { if register_destination <> 0 and register_destination exists { set PFH AX25_DOWNLOADER set PFH DOWNLOAD_TIME Transmit DL_COMPLETED_RESP packet. } else if register_destination <> 0 and it doesn't exist { Transmit DL_ABORTED_RESP. } else if lock_destination <> 0 { unlock lock_destination. set PFH AX25_DOWNLOADER. set PFH DOWNLOAD_TIME. Transmit DL_COMPLETED_RESP packet. } dl_state <- DL_CMD_OK } EVENT: DEFAULT { If lock_destination <> 0 unlock lock_destination. if EVENT is not "data link terminated" Terminate data link. dl_state <- DL_UNINIT } APPENDIX C - Client State Transition Definitions Client Pseudo-code State diagrammes. The following diagrammes indicate how an FTL0 client should react to different events when in different states. ``User Requests'' come from the process using the FTL0 state machine. Receive packets come from the data link and transmit packets go to the data link. It is assumed that the data link will be terminated if there have been no packets transmitted or received for a period of time (TBD). If the link is terminated by this ``activity timeout'' the state machines receive a ``Data Link Terminated'' event. ``Data Link Terminated'' is also generated if the link fails for any reason. UPLINK STATE MACHINE The client uplink state machine controls the file uploading process. File downloading and all other processes are controlled by the downlink state machine. The state of the uplink is indicated by the ul_state variable. The uplink state machine processes the following events: EVENT: User Requests Uplink EVENT: Data Link Terminated EVENT: Receive UL_GO_RESP EVENT: Receive UL_ERROR_RESP EVENT: Receive UL_ACK_RESP EVENT: Receive UL_NAK_RESP Where the ``EVENT: DEFAULT'' is indicated, this includes all events on the above list which have not already been processed. State UL_UNINIT { EVENT: User Requests File Upload Refuse. EVENT: DEFAULT ignore. } State UL_CMD_OK { EVENT: User Requests File Upload { Transmit UL_CMD packet, setting if necessary. ul_state <- UL_WAIT } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. ul_state <- UL_UNINIT } } State UL_WAIT { EVENT: Receive UL_GO_RESP packet. { Associate with the file. Mark the file CONTINUE. ul_state <- UL_DATA } EVENT: Receive UL_ERROR_RESP packet. { If error is unrecoverable, mark the file IMPOSSIBLE. ul_state <- UL_CMD_OK } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. ul_state <- UL_UNINIT } } State UL_DATA { If there is data to send { Transmit DATA packet. ul_state <- UL_DATA. } else { Transmit DATA_END packet. ul_state <- UL_END. } EVENT: Receive UL_NAK_RESP packet. { if error is unrecoverable mark file IMPOSSIBLE. Transmit DATA_END packet. ul_state <- UL_CMD_OK. } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. ul_state <- UL_UNINIT } } State UL_END { EVENT: Receive UL_ACK_RESP packet. { Mark file COMPLETED. ul_state <- UL_CMD_OK } EVENT: Receive UL_NAK_RESP packet. { If error is unrecoverable mark file IMPOSSIBLE. ul_state <- UL_CMD_OK } } DOWNLINK STATE MACHINE The client's downlink state machine processes the following events: EVENT: User requests download EVENT: User requests directory EVENT: User requests selection EVENT: User requests abort EVENT: Receive DL_ABORTED_RESP packet. EVENT: Receive DL_COMPLETED_RESP packet. EVENT: Receive SELECT_RESP packet. EVENT: Receive LOGIN_RESP packet. EVENT: Receive DATA packet. EVENT: Receive DATA_END packet. EVENT: Receive DL_ERROR_RESP packet. The only user request which generates and event when not in DL_CMD_OK state is ``user requests abort'', which is processed in the DL_DATA state. All other requests are ignored (perhaps queued) until dl_state is DL_CMD_OK. State DL_UNINIT{ } State DL_CMD_OK{ EVENT: User requests download { Transmit DL_CMD packet. dl_state := DL_WAIT. } EVENT: User requests directory { Transmit DIR_LONG_CMD or DIR_SHORT_CMD packet. dl_state := DL_DIR_WAIT. } EVENT: User requests selection { Transmit SELECT_CMD packet. dl_state := DL_SEL. } EVENT: User requests abort { ignore. dl_state := DL_CMD_OK } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } State DL_WAIT{ EVENT: Receive DL_ERROR_RESP packet { dl_state <- DL_CMD_OK. } EVENT: Receive DATA packet. { Store data. Mark file INCOMPLETE. dl_state <- DL_DATA. } EVENT: Receive DATA_END packet. { If file at client is ok { Mark file DATA_OK. Save equal to file length. Transmit DL_ACK_CMD. } Else { Mark file INCOMPLETE. Save of 0. Transmit DL_NAK_CMD. } dl_state <- DL_END. } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } State DL_DATA{ EVENT: User requests abort { Save current offset as . Transmit DL_NAK_CMD. dl_state <- DL_ABORT. } EVENT: Receive DATA packet. { Store data. dl_state <- DL_DATA. } EVENT: Receive DATA_END packet. { If file is ok at client Transmit DL_ACK_CMD packet. Else Transmit DL_NAK_CMD packet. dl_state <- DL_END } EVENT: DEFAULT{ Save current offset as . if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } State DL_END{ EVENT: Receive DL_ABORTED_RESP packet. { dl_state <- DL_CMD_OK. } EVENT: Receive DL_COMPLETED_RESP packet. { Mark file COMPLETE. dl_state <- DL_CMD_OK. } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } State DL_ABORT{ EVENT: Receive DATA packet. { Ignore. dl_state <- DL_ABORT. } EVENT: Receive DATA_END packet. { dl_state <- DL_END. } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } State DL_DIR_WAIT{ EVENT: Receive DATA packet. { Send directory data to user. dl_state <- DL_DIR_DATA. } EVENT: Receive DL_ERROR_RESP packet. { dl_state <- DL_CMD_OK. } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } State DL_DIR_DATA{ EVENT: Receive DATA packet. { Send directory data to user. dl_state <- DL_DIR_DATA } EVENT: Receive DATA_END packet.{ dl_state <- DL_CMD_OK } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } State DL_SEL{ EVENT: Receive DL_ERROR_RESP packet. { dl_state := DL_UNINIT } EVENT: Receive SELECT_RESP packet. { dl_state := DL_UNINIT } EVENT: DEFAULT{ if EVENT is not "data link terminated" Terminate data link. dl_state <- UL_UNINIT } } APPENDIX D - Error Codes Value Name 1 ER_ILL_FORMED_CMD 2 ER_BAD_CONTINUE 3 ER_SERVER_FSYS 4 ER_NO_SUCH_FILE_NUMBER 5 ER_SELECTION_EMPTY 6 ER_MANDATORY_FIELD_MISSING 7 ER_NO_PFH 8 ER_POORLY_FORMED_SEL 9 ER_ALREADY_LOCKED 10 ER_NO_SUCH_DESTINATION 11 ER_SELECTION_EMPTY 12 ER_FILE_COMPLETE 13 ER_NO_ROOM 14 ER_BAD_HEADER 15 ER_HEADER_CHECK 16 ER_BODY_CHECK