pacsat protocol: file transfer level 0 - tapr · pacsat protocol: file transfer level 0 jeff ward,...

Pacsat Protocol: File Transfer Level 0

Jeff Ward, GO/KSKAHarold E. Price, NK6K

ABSTRACT

This document specifies Version 0 of the File Transfer Level 0 (FTU)) protocol designed foruse on store-and-forward satellites (PACSATs). The protocol provides procedures fortransferring binary files to and from a server computer using an error-corrected communica-tion link.

Further to basic file transfer facilities, FL0 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 flexiblelogical equation involving a large number of file characteristics. The scope of directory re-quests 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 “bodv”of the file is Dreceded bv a standard “header”, specified in the PACSAT File Head&Definition document.

1.0 BACKGROUND

Terrestrial packet-radio bulletin board systems(PBBSs) in the amateur radio service generallyprovide a character-based, human-to-machineinterface through which user’s command the PBBSsoftware. A similar interface has been adopted onthe 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. Allmessages are stored as ASCII text files, and thePBBS maintains a directory entry for each mes-sage. The directory contains message source, des-tination, title, time of storage, size, and status. ThePBBS also stores data relating to each user station,such as the most re-cent message each user stationhas listed or viewed.

Since messages and PBBS commands contain onlyASCII characters, the user’s station equipment canbe as basic as an ASCII terminal connected to aterminal node controller (TNC). This simplicitymakes the current system attractive, and has leadto its widespread adoption.

These current PBBS systems also have severaldrawbacks, stemming from the text-based user

interface and from the lack of a flexible, informa-tive message header. All messages must be inASCII, only simple ASCU message headers aresupported, and only a few search-keys are pro-vided for message selection.

These limitations are particularly damaging in thePACSAT environment. where the user base islarge, the communications bandwidth is restricted,and the onboard computer software must be com-pact and highly reliable.

The File Transfer Level 0 protocol defined here,and the PACSAT File Header Definition pre-sented elsewhere, combine to provide a PBBSprotocol suite which overcomes the limitations ofthe current text-based protocols.

The proposed protocols are based on a differentmodel of a store-and-forward messaging network.The PBBS is a “SeTver” and the user stations are“clients”. The server stores files, each of whichcontains a “header” of known format, followed bya “body”. The header holds information about thefile and about the body, including (but not limitedto) the file length, creation date, destination,source, keywords, and body compression tech-nique. The body is the data portion of the file.

209

which can be any digital information, e.g. binary,ASCII, FAX, digit&d voice, etc.

The user station, or “client” is assumed to beunder computer control. The client sends files tothe server and receives files from the server overa n A X 2 5 d a t a l i n k , u s i n g a n a u t o m a t e dserver/client file transfer protocol. The clientsoftware interprets and displays the file headersand bodies for the human user. When the userwishes to upload a file to the server, clientsoftware must add suitable standardized headerfields to the file, and it may also compress orotherwise prepare the file for uploading.

Each user is generally interested in only a smallsubset of the files available on a server. Using apowerful selection facility the client can select aninteresting subset of the files on the server for cli-rectory listing or downloading. The selection canbe based on any combination of items in the fileheader, thus user’s software can assure that theuser only “sees” files which are likely to be of in-terest.

The server might not keep a user data base, andthe client software must store any importantinformation concerning the user’s last serversession. For example, to implement a commandequivalent to the PBBS command “list new”, theclient software must store the message number, ordate and time of the of the last access to theserver.

Since this protocol is also useful for terrestrialservers, we use the terms “server” and “client”throughout, i n s t e a d o f “PACSAT” and“groundstation”. The protocol does depend on thepresence of the standard PACSAT file header, thisis to implement file locking or other features. Aversion of the protocol that can be used by terres-trial stations without the PACSAT headers is un-der consideration.

FIX0 includes several features that make theprotocol somewhat more complex than some oth-ers in use in the amateur packet network. Thesefeatures include simultaneous bidirectional filetransfer, file locking by forwarding gateways, andmultiple destination forwarding. As is sometimesthe case, the actual implementation is smaller thanthe specification. The pseudo-code provided inAppendix B and C show that the protocol is actu-ally quite straightforward. The authors also plan

to make the prototype source’code available on apublic BBS.

1.1 FTLO

The FTLO protocol can support full-duplex mes-sage transfer, in which a single data link (AX.25connection) is used simultaneously to upload onefile and to download another file. Client softwaredoes not necessarily have to implement this capa-bility. The protocol provides for continuation ofuploads and downloads interrupted by loss of thedata link (generally caused by LOS at a satellitegroundstation), and includes confirmation band-shakes at all critical stages of file transfer. AnFIX0 file transfer should withstand interruption atany stage.

It is assumed that the client software uses thetransparent mode of an AX.25 TNC and that theAX.25 connection represents an error-free chan-nel. Other data links which present an ordered,e r ro r cor rec ted by te s t ream may be used .Although the link may be terminated at any time,it is assumed that the link will not pass corruptedor out-of-order bytes, and that processes at both,ends of the link will be notified if the link is termi-nated. The PACSAT File Header standard pro-vides overall checks on the integrity of files trans-ferred to and from fully-compliant servers.

FTLO commands and responses form simple“packets” inside the byte stream on the communi-cations link. Specifically, in AX25, an FIX0packet may be transmitted in one or more AX.25 Iframes; neither the server nor the client is awareof the AX.25 I frame boundaries. The packetformat is described in 2.0 below.

1.2 Associated Documents

PACSAT Data Specification Standards defines themeaning of data types and structures within thisspecification.

The PACSAT File Header Definition defines thefile header fields which must be pre-pended tofiles before uploading to a fully-compliant FTLOserver. (FTLO procedures for terrestrial serverswithout PACSAT file headers are under develop-ment .)

210

1.3 Terminology implement may implement menus or some otheruser interface.

serverclientcommands

responses

upiink

downlink

packet

framedata link

is the PACSAT or tbe PBBS.is tbe user station.are transmitted from the client to tbeserverare transmitted from the sewer to theclientis data flow from the client to theserveris data flow from the server to theclientis a sequence of bytes as defined in2.0 belowis an AX25 level 2 I framegenerally an AX.25 level 2 link, butmay be a link using any protocolwhich provides an ordered, error-checked, data transparent westream.

1.4 Overview of Operation

To allow simultaneous uploading and download-ing. FU.4 clients and servers implement two statemachines. One is related to file uploads, and thesecond to all other possible commands. FLTO isnot symmetric; the protocol state machines im-plemented by the server are necessarily differentfrom those implemented by the clients.

Dividing the data stream into packets allows formodular software implementation a n d t h emultiplexing of commands and data on a singledata link. The packet format is simple. Everypacket begins with 2 bytes of control information,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 isprovided, since the data link (AX.25 connection)provides a notionally error-free connection. Fuhfile error checks are performed at tbe completionof file transfers.

It is assumed that neither the client software northe server software is aware of or can control datalink (AX25) frame boundaries.

A lTL0 session starts when an data Iink is estab-lished between tbe server and the client. TheServer will send a LOGIN response when theconnection is established.

To allow the user to specify a group of files for di-rectory listings or downloading, the client software

Once the user has indicated the desired files, theclient software converts the user’s preferences intoan equation , such as

( (SOURCE = “GOKWV”) && (KEYWORD =“*FFLO*“) ) && (FILE NUMBER > 3215).

And then encodes the equation in a postfix, binaryformat as a SELECT command. When the serverreceives a SELECT command it builds a list offiles for which the equation evaluates to TRUE.As a response to the SELECT command, theserver informs tbe client bow many files are in theselection list.

When the client sends a one of the directory com-mands, the server responds by transmitt ingdirectory information for the next 10 files on theselected list. Each subsequent directory commandresults in the server transmitting directory infor-mation for a further 10 files from the selection list,until the list is exhausted.

Specific files or files from the selection list may berequested by the client for downloading. Thedownload procedure consists of two com-mand/response cycles. On the first cycle, theclient requests the file and the sewer responds bytransmitting the file as a series of DATA packetsfollowed by an END OF DATA packet. Theserver then waits for t.62 client to acknowledge re-ceipt of the file. When the server receives the ac-knowledgement, it transmits a final handshake andthe download is finished.

To upload a file to the server, the client sends anUPLOAD command telling the server how largethe file is. The server responds with a handshakewhich either tells the client to abort or to proceed.If instructed to proceed, the client sends the entirefile as a series of DATA packets followed by anDATA END packet. Tbe server receives the en-tire fileTand then either acknowledges the transferor sends an error indication.

Because PACSAT may go over tbe horizon in themidst of a transaction, downloading and uploadingcan be continued during several sessions with tbeserver. Wben a download is interrupted, the clientmust retain the file offset at which communica-tions was interrupted. For interrupted uploads,the server stores the appropriate offset.

211

1.5 File Identification

Although servers may identify files using somekind of system file name (PACSATs use the MS-DOS standard of an 8 character body and a 3character extension), FFLO does not use server filenames to identify fries. Instead, the server assignsevery fde a 32-bit file number. This is to insurethat two files with different contents but the samename will never be confused. Thus, every mes-sage which a user uploads to PACSAT (or anotherFI’LO server) will have a unique identifier.

1.6 Gateway Procedures

Some messages on PACSAT will be destined forgateway stations which will introduce the mes-sages into other networks. It is essential that onlyone gateway download and relay each message.To accommodate this, FTL0 provides lockeddownloads. Only one gateway at a time can per-form a locked download of a given file for a gjvendestination. If a locked download is interrupted,this will be indicated in the PACSAT File Headerof the file, so that other gateways can tell when afile is in the process of being delivered.

PACSAT File Headers allow files with multipledestinations, and separate locks are implementedfor each destination. See Appendix A for furtherinformation.

1.7 Delivery Registration

A simple form of delivery registration is supportedby FILO. In the final handshake after receiving afile, the client can command the server to modifythe contents of the PACSAT File Header to showthe AX.25 address of the client and the time atwhich the download was completed. It is intendedthat this facility be used if the file is specificallyaddressed to the client station, not for files of gen-eral interest. If the file has multiple destinations,one “registration” is supported for each destina-tion. See Appendix A for further information.

1.8 State Variables

In order to support full-duplex operations, theserver and the client maintain 2 state variables,one relating to the uploading of files and the otherrelating to all other operations (selecting, directo-ries, and downloading). These are called the up-link state and the downlink state variables.

Appendix B provides pseudo-code definitions ofthe state transitions for sewers, Appendix C is forclients.

2.0 PACKET FORMAT

An FILO packet is a sequence of informationbytes preceded by a two byte header. After es-tablishment of a data link, the first byte deliveredto either client or server is the first byte of apacket header. The packet header informs theclient/server the type of the packet and the num-ber of information bytes which will follow. Theremay be between 0 and 2047 information bytes, in-clusive. After reception of the final informationbyte of a packet, the client/server expects the nextbyte to be the first byte of another packet header.Such a stream is shown below, where [ <data > ]indicates that there may be no data bytes.

4engtb lsbxhl> [<info), . I ]<lenqth lsbxhl> [ <info>. e . ]I ---P&t ITLO packet--- 1 --Second FTLO packet--- 1

2S Header Format

struct FTLOJ’KT (unsigned char 1engthJsb;unsigned char hl;

<length-lsb > - 8 bit unsigned integerthe least significant 8 bits of data length.

suPPlYmg

< hl > - an &bit field.

bits 7-5 contribute 3 most significantbits to data length.

bits 4-O encode 32 packet types asfollows:

0 DATA1 DATA END2 LOGIN RESP3 UPLOAD CMD4 UL GO RESP5 UL-ERROR RESP6 UL-ACK R&P7 ULNAK-RESP8 DO-iL6AD CMD9 DL ERROR RESP10 DL-ABORTED RESP11 DL-COMPLETED RESP12 D L - A C K C M D -

212

13 DL NAK CMD14 DIR SHORT CMD15 DIR-LONG i!MD16 SELECT CIiiD17 SELECT-RESP

2.2 Informatiom Length

The <information length > value is formed bypre-pending b i t s 715 of the <hl> byte to the<length Isb > byte. <information length > indi-cates ho& many more bytes will be received be-fore the beginning of the nex t packe t . I f<informationtion bytes. -

length> is 0, there are no informa-

3-O LOGON

As soon as a data link is established between theclient and the server, the client is considered to belogged on. The server sends a LOGIN RESPpacket with one byte of flags and a 4-byte-times-tamp.

When the client receives the LOGIN RESPpacket the server is initialized and ready to begintransactions.

3.1 Initiation of Session

An flL0 session is initiated when a data link isestablished between the client and the server.

3.2 Server Login Response Packet

When the data link is established the server trans-mits a LOGIN RESP packet.

Packet: LOGIN RESPInformation: 5 bytes

struct WIN-DATA (unsigned long login time;unsigned char loqin~flaqs;

1

clogin time> - a 32-bit unsigned integer indicat-ing the number of seconds since January 1,197O.

<@in-flags > - an 8-bit field.

Bit 3, the SelectionActive bit, will be 1 if there isalready an active selection list for this client. TheSelectionActive bit will be 0 if there is no activeselection for this client already available.

Bit 2, the HeaderPFH bit, will be 1 if the serveruses and requires PACSAT File Headers on allfiles. If the HeaderPFH bit is 1, the flagPFHserver used in the following definition shouldbe considered TRUE.

The HeaderPFH bit will be 0 if the Server doesno t use PACSAT Fi le Headers . If theHeaderPFH bit is 0, the modified proceduresspecified in Section 7 should be used.

Bits 1 and 0 form a 2-bit FI’LO protocol versionnumber. The version described here is 0.

3.3 Server Login LnitiaIization

Upon transmitting the LOGIN RESP packet theserver should initialize its &te variables toUL CMD WAIT and DL CMD WAIT.

3.4 Client Login In.itial.ization

Upon receiving the LOGIN RESP packet, theclient should initialize its state variables toUL CMD OK and DL CMD OK.

4.0 SELECT

The select command is the mechanism throughwhich the client can search the server for desirablefiles. The human user can search the files on theserver based on any information contained in thePACSAT File Header. To achieve this goal, theimplementation and specification go through sev-eral levels of abstraction which must be followedclosely.

The user’s desires form an equation. The equationmight simply be “the file is to GOKSKA and it wasstored after my last logon”. Or it might be morecomplex, e.g. “the file is less than 8 kbytes, and itwas created after 9 July 1990, and it has‘landrover” as one of its keywords”. Humanswould naturally express this in “infix” notation:

(FILE SIZE < 8k) && (CREATE DATE > 9July lh) && (KEYWORDS = = “‘landrover*“)bit:76543210

xxxxsHvv

213

The server uses “postfix” notation, like an RPNcalculator: and wants an equation like:

(FILE SIZE < 8k) (CREATE DATE > 9 july1990) g& (KEYWORDS = = “*landrover*“) &&I

To convert a postfix logical equation into aSELECT command. the client must encode thelogical operators, the relational operators theheader item names, and tbe values to compareagainst. Tbe header item names and comparisonv a l u e s a r e encocled j u s t a s they a r e i n t b ePACSAT File Header definition. The logical op-erators and relational operators are encoded assingle bytes. Tbe complete syntax is defined be-low .

4.1 Client Issuing Select Command

struct LVALUEl (unsigned char relop;unsigned int item id;unsigned char length;unsigned char constant [ ] ;

1

< relon > is an 8-bit field encoding a relational op-erator:

b i t0

When the client’s downlink state variable isDL CMD OK (e.g. the client is not involved inanother select, file download, or directory down-load), the client may transmit a SELECT CMDpacket.

b i t000001010011100101110111

Packet: SELECT CMDInformation: variable length SELECTION

bit 321Q0000

SELECTION is defined recursively by the fol-lowing structures and rules.

struct SELECTION (struct LVALUEx equation;unsigned char end-flag;

>

<end flag > - 0x00

<equation > is recursively defined by two struc-tures LVALUEO and LVALLJEI:

0001

0010

0011

0100

struct LVALUEO (struct LVALUEX t1;struct LVALUEx t2;unsigned char lop;

1

ALL OTHER VALUES RESERVED.

<item id > is a 160bit unsigned integer identifyingone of the PACSAT Header Definition headeritems.

c tl > and < t2 > are furtber LVALUEO orLVALUEl structures. <length> is the number of bytes in the

cconstantf ]> array.c lop> is and 8-bit field representing a logical op-erator:

bit 76543210ooooOool is AID

<constant[ ] > is an array of bytes which are com-pared against the header item identified byc item id > , using the specified relational operatorand co&parison type.

00000010 is OR

Relational ODeratorequal togreater thanless thannot equalgreater than or equal toless than or equal toreservedreserved

Tvne of ComDarisontreat <constant > as a multi-byteunsigned integer (valid for<length > l,2, and 4).treat <constant > as a multi-bytesigned integer (valid forc length > 1,2,and 4).treat <constant > as an arrayof unsigned chartreat <constant > as an array ofASCII characters, convert tolower case before making com-parison.treat <constant > as an array ofASCII characters, convert tolower case before comparisonand interpret wildcard characters.

214

4.2 Response to Select Command

T’he server responds with one of the packets from42.1 or 4.2.2 and returns its downlink state toDL CMD OK, ready to accept another commandfrom the client.

4.2.3 Successful Selection

If the server can interpret the SELECT CMDpacket, it responds with a SELECT RESP packet

Packet: SELECT RESPInformation: 2 bytes

unsigned int no of fil- - .es

en0 of files> is a 16 bithow &any files have been

UkgIEd

sekcted.

4.2.2 Unsuccessful Sele-ction

integer tellingIt may be 0.

If the server cannot interpret the SELECT CMDpacket, it responds with a DL ERROR-RESPpacket

Packet: DL ERROR RESPInformation: 1 byte -

unsigned char err code

<err ctie> is ER POORLY FORMED SEL ifthe s&tion equat& could not be parsed by theserver because of a syntax error.

5.0 DOWNLOAD

To receive a file from the server, the client usesthe download command. This command can beused to download a specific file, to continue thedownloading of a specific file, or to download thenext file in the sehion list.

5.1 Client hitiates Download

When the c l i en t ’ s uplink s t a t e va r i ab le i sDL CMD OK, the client may send theDO-WNLCAD CMD packet.

Packet: DOWNLOAD CMDInformation : 9 byte< of arguments with theroll owing structure

struct (unsigned long file no;unsigned long bytkoffset;

unsigned char lock-destination;

<file no> is a 32.bit binary integer uniquelyidentifying a file on the server. Two reserved val-ues have special meanings: If <file-no> is equalto Oxffffffff, the server will attempt to use the nextfile in the current selection list, moving from olderfiles to newer fdes. If <file no> is equal to 0, theserver will attempt to use the next file in the cur-rent selection list, moving from newer files towardaider files. If <file-no > is not one of the reservedvalues, the server attempts to download the filewhich it associa tes with c file no x

<byte offset > is a 320bit unsigned binary integergiving-the offset from the beginning of the file atwhich the download should begin. If the client iscontinuing an aborted download, this argumentshould be set to the number of bytes pre,viouslvdreceived. Otherwise it should be 0.

<lock destination > is an 8 bit unsigned binaryintege;. It will generally be set to 0 by non-gate-way stations.

IIf < lock destination > is not 0, it indicates thatthe client wishes to conduct a locked download forthe destination numbered by clock destination > .If the <lock destination > exists and-s not ahead\*locked, the client’s AX25 address is placed in thePACSAT FiJe Header AX25 DOWNLOADERitem associated with the specified DESTINATIONitem. Destination numbering is defined in sectionx.x]

5.2 Server Responses to the DownloadCommand

When it receives a DOWNLOAD CMD packetthe server determines whether the download ispossible. This may include determination of thedesired file number from the current select list.

5.2.1 Dowdinking File Data

If the download is possible the server transmits thefile data beginning <byte offset > bytes from thebeginning of the file. If cbyte -offset> is greaterthan or equal to the file length, no data is trans-mitted. The file data bytes are transmitted as in-formation in DATA packets. These packe,ts maybe any size from 0 to 2047 bytes.

215

[If < lock destination > is not-zero, the server setsthe <DOWNLOAD TIME> associatedclock destination > bef&e beginning to sendDATA packets.]

Once the server has transmitted a DATA packetcontaining the last byte of the file, or if the<byte offset> was greater than or equal to thef i l e l eng th , the se rver t r ansmi t s a s ing leDATA END packet. After transmitting the endpacket,- t h e s e r v e r e x p e c t s to r e c e i v e aDL ACK CMD or DL NAK CMD.

5.2.2 Failure of Download Command

If the server cannot service the download com-mand, it responds with a DL ERROR RESPpacket.

Packet: DL ERROR RESPInformation: 1 byte

unsigned char err code;

<register destination > is an &bit unsigned integeridentify& one of the destinations in the PACSATFile Header of the downloaded l .file<register destination > should be 0 if the clientdoes not &I to register receipt of the file.

Upon receiving the DL ACK CMD packet, theserver completes the download process.

(If <register destination > is[If <register destination > is not 0, the appropriatenot 0 9

DESTINA~ON i t e m i nthe appropriate

DESTINA~ON i t e m i n t h e P A C S A T F i l ethe PACSAT FileH e a d e r i sH e a d e r i s l o c a t e d a nlocated and theId 1he associatedassociatedAX25 DOWNLOADERAX25 DOWNLOADER andandDOWNLOAD TIME item:DOWNLOAD TIME i t ems a re upda ted . I f; are: updated. Ifclock destination >clock destination > waswas non-n o n - z e r o i n t h ezero in theDOWNLOAD COMMANDDOWNLOAD COMMAND, the server locates1 thethe appropriate DESTINAthe appropriate DESTINATION item in the.iIOP

server locatesJ item in the

PACSAT File Header and uPACSAT File Header and updates the associatedpdate s the associatedDOWNLOAD TIME item.]DOWNLOAD TIME item.]

5.3.2 Unsuccessful or Aborted Download

If the client wishes to abort the download beforereceiving the DATA END packet from the server,or finds that the downloaded file fails some in-tegrity test after reception of the DATA ENDpacket, the client sends the DL NAKCMDpacket.

<err code > is an S-bit unsigned binary integerwill be one of:

ER SELECTION EMPTY if the selection list hasno more files in it or no select command waspreviously received.

ER NO SUCH FILE NUMBER if the file iden-tified by-c file no > do& not exist.

ER ALREADY LOCKED - <lock destination>wasnot 0, and the file is already l&ked for thespecified destination.

ER NO SUCH DESTINATION<l&k d&inati& > was not 0, and the file hasfewer-than <lock destination > DESTINATIONitems in its PACSKT File Header.]

Packet: DL NAK CMDInforma tioG none-

Upon receiving this packet, if the serveUpon receiving this packet, if the server has noter has notalready sent the DATA-END packet, italready sent the DATA END packet, it will do soudl do soand proceed to the final unsuccessfuland proceed to the f&l unsuccessful downloaddownloadhandshake (5.4.2). If DL NAK CMD ihandshake (5.4.2). If DL NAK CMD is receivedS receivedafter the server has transmitted&e DAafter the server has transmitted&e DATA END,T‘A ENDpacket, the server proceeds to the foalpacket, the server proceeds to the foal downloaddownloadhandshake.

5.4 Final Download Handshake

5.3 Client Accepting or RejectingDownloaded File

5.4.1 Completion of Successful Download

5.3.1 Successful Download

Upon reception of the DATA END packet from‘the server, the client performs any possible checkson the received file. If the file passes the checks,the client transmits a DL ACK CMD packet.

Packet: DL ACK CMDInformatioG 1 byte

unsigned char c register-destination >

[If the server receives the DL ACK CMD, it re-moves any <lock destination 3 lock horn the fileand sets <Ah5 DOWNLOADER > and<DOWNLOAD TIMi& f o r t h e s p e c i f i e d<DESTINATIO% > item.]

[If <register destination > in the DL ACK CMDis non-zero, the server at tempts-to Set the<AX25 DOWNLOADER > and<DOWNLOAD TIME> items associated withthe specified GESTINATION > item. If the

216

<register destination > does not exist, the servertransmits; DL ABORTED RESP packet.]

If <register destination > was 0, the server trans-mits a DL COMPLETED RESP packet, and re-turns its downlink state vansble to DL CMD OK.

Packet: DL COMPLETED RESPInforma t;oG none. -

This response tells the client that the server hascompleted processing the DL ACK CMD. Theclient downlink state variable should be set toDL CMD OK.

If the L2 link fails before the client receives theDL DONE RESP, the client cannot be sure theDL-ACK CMD was processed. This is importantif tb;: client had specified a <lock destination > ora <register destination >. In either of these cases,the client should treat the download as incompleteand continue it Iater. This assures that thePACSAT File Header has been properly modified.If both< register destina tisider the download

<lock destination > and#on> were 0, the clien t can con-complete.

5.4.2 Completion of Unsuccessful Download

A download is “unsucceceives the DL NAK CMc register destina tionS isnon-exist&t destination.

ssful” i fD fromnon-xx0

the server re-the client or ifand indicates a

If clock destination > was non-zero, the lock isremoved- and < DOWNLOAD-TIME > is up-dated.

The server transmits the DL ABORTED RESPpacket.

Packet: DL ABORTED RESPInformatioG n o n e -

The server downlink state variable returns to theDL CMD OK state.

Upon reception of the DL ABORTED RESP thec l i e n t downlink s t a t e - v a r i a b l e returns t oDL CMD OK.

.6.0 DIRECTORY

The client uses directory commands to getinformation about files on the server. Servers con-forming to the PACSAT File Header Definitionsend PACSAT File Headers as directory entries.“Long” directory en t r i e s a re the comple tePACSAT File Header and “short” directory en-tries are only the Mandatory File Header items.

The client can request a directory entry for a spe-cific file or for the files in the selection list. Theselection list can be scanned from oldest to newestfiles or from newest to oldest files.

6.1 Initiating a Directory

The client may request a directory whenever theclient downlink state variable is DL CMD OK.To request a directory, the client transmits either aDIR LONG CMD packet or aDIR-SHORT CMD packet.

Packet: DIR LONG CMDor DIR-SHORT CMD

Information:4 bytes -unsigned long file no;

<file no> is a 32.bit unsigned binary integeridentifying a file or files on the server. There arctwo reserved values: 0 and Oxffffffff. If <file-no>is Oxffffffff, the server will send directory entriesfor the next 10 files in the current selection list,moving from older files to newer files. If<file no > is 0, the server will send directory en-tries for the next 10 files in the current selectionlist, moving from newer files toward older files.

6.2 Server Responses to DirectoryCommands

6.2.1 Successful Directory Request

If the directory request can be serviced (there arefiles in the selection list, or a specified file exists)the server will transmit one or more PACSAT FileHeaders in a series of DATA packets followed bya DATA END packet. A maximum of 10 fileheaders &l be transmitted for each DIR com-mand.

6.2.2. Failed Directory Request

If the directory request cannot be serviced, aDL ERROR RESP packet is transmitted.

217

Packet: DL ERROR RESPInformation: 1 byte -


<byte offset > is a 32-bit unsigned binary integernumb& of bytes from the beginning of the file atwhich the client should begin file transmission.This will be 0 if the <continue file no > was zero.

<err code > will be one of:

ER SELECTION EMPTY - if the <file no>was-0 or Oxffffffff,and either there are no files leftin the selection list or there is no selection list.

After receiving the UPLOAD PROCEED RESPpacket, the client should adf;ance to the datatransmitting state described in Section 7.3.

7.2.2 Unsuccessful Upload RequestER NO SUCH FILE NUMBER - if <file no>is got 0 or dfffffff -and no file identified by<file no> exists on the server.

If the server cannot process the upload request, itwill transmit an UL ERROR RESP packet.

7. UPLOAD

7.1. Initiating an Upload

Packet: UL ERROR RESPInformatio; 1 byte -


<err code > must be one of:The client can initiate an upload any time theclient’s upload state variable is UL CMD OK.

Packet: UPLOAD CMDInformation: 8 bytes

ER NO SUCH PILE NUMBER.If

<c&i.n~e file no> isnot 0 and the file identifiedby <con&e tie no> does not exist. Continueis not possible- -

s t r u c t (unsigned long continue file no;unsigned long file-length; -

1

<continue file no> - a 32-bit unsigned integeridentifying the file to continue. Used to continuea previously-aborted upload. Must be 0 whencommencing a new upload.

< file-length > - 320bit unsigned integer indicatingthe number of bytes in the file.

ER BAD CONTINUE if <continue file no> isnot-0 and-the <file length > does nor agee withthe <file length > fieviously associated with thefile identified by <continue file no > . Continue isnot possible.

.ER PILE COMPLETE if <continue file no> isnot 0 and the lfile ident i f ied byc continue file no> was completely received on aprevious u$oa% Note - receipt of this commandshould be accepted by the client as confirmation offile receipt by the server.

7.2 Server Responses to Upload requests ER NO ROOM if the server does not have roomfor the file.

Downlink Packet: UL GO RESP orUL ERROR RESP After transmitting the CJL ERROR RESP packet.

t h e s e r v e r ’ s uplink staLe variable i s s e t t o7.2.1 Successful Upload Request UL CMD OK.

Packet: UL GO RESPInformation! 8 bytes

struct (unsigned long server file no:unsigned long byte-offset;

1

<server file no> is a 32-bit unsigned binary inte-ger ide&yGg the client’s file on the server.

7.2.3 Continuation of Uploads

Any file for which the client receives aUL GO RESP should be continued until aUL-ACK RESP or a non-recoverableUL-ERR-RESP or UL NAK RESP for that fileis r&eived. The server should be prepared tocontinue reception of any file for which it hastransmitted a UL-GO-RESP. Some file numberswill be allocatd~by the server and lost by link

218

failure before the UL GO RESP reaches theclient; a 32-bit file number &ace provides suffi-cient scope for some lost file numbers. To avoidsaving partial files for these lost file numbers, theserver should not reserve space for a message untilit has received at least one DATA packet from theclient.

73. Data Uplinking Stage

The client now uplinks the bytes from the file, inDATA packets. T h e uplinking should b e g i n<byte offset> bytes from the start of the file.After transmitting a DATA packet containing thelast byte in the file, the client should transmit aDATA END packet. The client should alsotranstiy a DATA END packe t if the<byte offset > was gr&er than or equal to thefile length.

The server may attempt to terminate the uploadby transmitting a UL NAK RESP at any timeduring the upload. -If the client receives aUL NAK RESP packet before transmitting aDA?A END packet the client must send aDATA-END packet.

DATA END checks ‘, itfall s e n d s t h eUL NAK RESP packet.

Information: 1 byteunsigned char err code;

cerr code> must be one of:

ER BAD HEADER - The file either has noPFH, or has a badly-formed PFH.

ER HEADER CHECK - The PFH checksumfailed. -

ER BODY CHECK - The PFH body checksumfailed. -

ER NO ROOM - The server ran out of room forfileitorage before the upload was complete. Theserver will implement procedures to avoid fre-quentiy running out of room, but this cannot beguaranteed.

After transmitting the UL NAK RESP packet,the server uplink state variable is UL CMD OK.After receiving the UL ERROR REST, the &entuplink state variable is CL CMD-OK.

7.4. Completion of Upload7.4.3 Link Failure During Upload

7.4.1 Successful Upload Completion

When the server receives the DATA END packetit will check the integrity of the file as far as possi-ble. If the chocks pass, the server will downlink aUL ACK RESP packet.

Packet: UL ACK RESPInformation none

After transmitting the UL ACK RESP the serveruplink state variable is EL CMD OK. Afterreceiving the UL ACK REST, the-client uplinkstate variable is Uz CM6 OK.

If the data link fails before the server receives theDATA END packet, the server retains the offsetof the next byte needed for the file. This valuewill be transmitted by the server as <byte offset >if the client Later continues the upload by speci-fying the < server-file no > in the<cont inue f i l e no> of an- UPLOAD CMDpacket. If&e iffset is not 0, the server niaysafel\-’retain a temporary file containing the data re-ceived so far. If the server retains files for whichthe <byte offset > is 0, these should be purgedafter some reasonable time, since the client maynot know the < server file no > of the file.

7.4.2 Failure Caused by Server Rejecting Upload8.0 TERMINATION OF SESSION

The server may reject an upload while the client issending DATA packets (due to file system prob-lems on the server) or after the client has sent theDATA END packet (due to corruption of thefde) .

The session is terminated by closing the data link.Either the client or the server may decide to closethe link when uplink state is UL CMD OK anddownlink state is DL CMD OK. -The l&k is alsoterminated if unexpected pa;kets are received.

If the server must abort the upload while receivingD A T A p a c k e t s o r after receiving the

219

If the link terminates when any state machine isnot in the CMD OKare taken. - -

state, appropriate actions

APPENDIX A - Use of the PACSAT FileHeader

The PACSAT File Header Definition defines astandard header which will be found at the begin-ning of every fde downloaded from PACSAT (orany fully compliant FIU server).

One purpose of the PACSAT File Header is toallow clients to determine the status of files on theserver. Specifically, the originating client maywish to find out if the file has been downloaded byits intended destination, and a Gateway client maywish to find out if a message still needs to bedownloaded for relay to a particular destination.Both of these tasks are done by examining a set ofPACSAT Fi le Header Items comprising<DESTINATION >,<AX25 DOWNLOADER > and< DOW%LOAD TIME > .

A gateway will examine <DESTINATION > tosee if it can relay or deliver the file. If so, it willexamine <DOWNLOAD TIME> and<AX25 DOWNLOADER> todetermine the de-livery status of the message:

If <DOWNLOAD TIME> is zero, the messagestill needs to be relayed.

If <DOWNLOAD TIME> is non-zero, but<AX25 DOWNLOADER> is blanks, the mes-sage is G the process of being downloaded, andthe download started at <DOWNLOAD TIME >.

If <DOWNLOAD TIME> is non-zero, and<AX25 DOWNLOADER> i s non-b lank , themessage-has been downloaded for relay to the<DESTINATION > .

A similar (but simpler) procedure is used to see ifa specific destinationceipt” of a file. Whenend of a

stationreceipt

has “registeredis registered (at

re-the

successful download),

c AX25 DOWNLOADER > and<DOWkOAD TIME> will both be correctly-set.

For these checks to work cone&y, the down-loading clients must use the proper command pro-cedures. Gateways mus t se t the cor rec tclock destination > in their DOWNLOAD CMDpacket%, and clients must set the correctc register destination > in the DL ACK CMD.The <lo& destination > procedure should be im-p lemented- by all ga teways . The < r eg i s -ter destination> procedure is optional for clientim$ementations.

The proper number for <register destination > orclock destination > is determinsas follows. If afile h& only one <DESTINATION > item, it isdestination 1. Any other destinations are num-bered sequentially in order of occurrence in thePACSAT File Header.

APPENDIX B - Server State TransitionDeftitions

SERVER STATE DEFINITIONS

The following pseudo code defines the transitionsof the Server state machines in FTLO. One statemachine is used for file uploading. The other statemachine is used for all other procedures.

It is assumed that the data link will be terminatedif there have been no packets transmitted orreceived for a period of time (TBD). If the link isterminated by this “activity timeout” both statemachines receive a “Data Link Terminated” event.“Data Link Terminated” is also generated if thelink fails for any reason.

When an unexpected packet is received by one ofthe state machines, that state machine terminatesthe data link and returns to an uninitialized state.The second state machine is notified of thisthrough a ‘Data Link Terminated” event, and alsoreturns to an uninitialized state. At this point, theFILO processing for this client ceases until theestablishment of another data Iink.

STARTUP

State variables are created when a data link is established between client and server. The server executes thefollowing:

Transmit LOGIN RESP packet.ul state:= UL CtiD OKdlstate : = D L C M D - O K

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 theievel 2link (from local or remote causes).

state UL CMD OK {

EVENT: Receive UPLOAD CMD packet{if ok to upload

Send UPLOAD GO RESP packet.d state <- UL I)AfA RX

else -Send UL ERROR RESP packet.ul state T- 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 2 - UL ABORT

else {Update file offset.ul state <-%L DATA RX

EVENT: Receive DATA END packet {Close file.if file passes checks {

221

Transmit UL ACK RESP packetul state c- fi CGD OK

else {file offset <- 0Save file offset and file numberTransmihJL NAK RfSP packetul state < - fi CGD OK

I1

EVENT: DEFAULT{if (file offset > 0)

Save fiIe offset and file number.if EVENT isnot “data link terminated”


state UL ABORT {

EVENT: Receive DATA packetul state <- UL ABORT

EVEhT: Receive DATA END packetul state C- UL CMD-OK


Terminate data link.ul state G 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

1else {

Transmit DL ERROR RESP packet.dl state <- 6 CMD OK

>>

EVENT: Receive DIR LONG CMD or DIR SHORT CMD packet {if there are directories to s&d

dl state <- DL DIR DATAelse {-

Transmit DL ERROR RESP packet.dl state <- fi CMD 6K

EVE.lf

NT: Receive DOWNLOAD CMD patrequest can be serviced { -

if <lock destination> < > 0set P-h3 DOWNLOAD TIME.

dl state c - DL FILE DATA

:ket (

>else {

Transmit DL ERROR RESP packet.dl state <- fi CMD 6K

EVENT: Receive DL NAK CMD packetdl state <- DL C6fD Ok


Terminate data link.dl state <- DL UNINIT

state DL DIR D.4TA {if there is more directory data to send {

Transmit directory data in DATA packets.dl state <- DL DIR DATA

>eke (

Transmit DATA END packet.dl state < - DL CMD OK

EVENT: Receive DL NAK CMD packet{Transmit DATA END packet.dl state <- DL CMD OK.

>



223

state DL FILE DATA {

if there is more file data to sendTransmit file data in DATA packets.dl state < - DL FILE DATA

else {Transmit DATA END packet.dl state <- DL tiLE END

EVENT: Receive DL NAK CMD packet {If lock destination-c > O-

unlock lock destination.Transmit DATk END packet.Transmit DL ABoRTED RESP packet.dl state <- DL CMD OK

EVENT: DEFAULT {If lock destination < > 0

u&k lock destination.if EVENT is not “data link

Terminate data link.dl state < - DL UNINIT

>

terminated”

state DL FILE END {

EVENT: Receive DL NAK CMD packet {dl state c - DL CMD OKTransmit DL KBORfED RESP packet.If lock destihon c > 0 -

u&&k lock destination.

>

EVENT: Receive DL ACK CMD packet {if register destination < T 0 and register destination exists {

set PFT. AX25 DOWNLOADER -set PFH DOW%LOAD TIMETransmit DL COMPLETED RESP packet.0

else if register destination < > 0 and it doesn’t exist {Transmit 6L ABORTED RESP.

else if lock destination c > 0 {unlock 6ck destination.set PFH A225 DOWNLOADER.set PFH DOtiOAD TIME.Transmit DL COMPLETED RESP packet.

dl state < - DL CMD OK

224

EVENT: DEFAULT {If lock destination < > 0

unl&k lock destination.if EVENT is not “data link terminated”


1

APPENDIX C - Client State Transition Definitions

Client Pseudo-code State diagrammes.

The following diagrammes indicate how an FI’LO client should react to different events when in differentstates.

“User Requests” come from the process using the FFLO 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 aperiod of time (TBD). If the link is terminated by this “activity timeout ” the state machines receive a “DataLink 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 processesare 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 UplinkEVENT: Data Link TerminatedEVENT: Receive UL GO RESPEVENT: Receive UL-ERROR RESPEVENT: Receive UL-ACK RESPEVE,NT: Receive UL-NAK-RESP

Where the “EVENT: DEFAULT” is indicated, this includes all events on the above list which have not al-ready been processed.

State UL UNINIT {

EVENT: User Requests File UploadRefuse.

EVENT: DEFAULTignore.

1

225

State UL CMD OK {

EVENT: User Requests File Upload {Transmit UL CMD packet, setting <continue file no> if necessary.ul state <- fi WAIT

1



>>

State UL WAIT {

EVENT: Receive UL GO RESP packet. {Associate <server-file number > with the file.Mark the file COh?TIh!UE.ul state <- UL DATA

>

EVENT: Receive UL ERROR RESP packet. {If error is unrecov&able, mafk the file IMPOSSIBLE.ul state <- UL CMD OK

>



State UL DATA {If there is data to send {

Transmit DATA packet.ul state C- UL DATA.

>else {

Transmit DATA END packet.d state C- UL END.

EVENT: Receive UL NAK RESP packet. {if error is unrecov&able mark file IMPOSSIBLE.Transmit DATA END packet.ul state < - UL CMD OK.

1



State UL END {

EVENT: Receive LJL ACK RESP packet. (Mark file COMPL~TE6ul state <- UL CMD OK

>

EVENT: Receive UL NAK RESP packet. {If error is unrecov&able%ark file IMPOSSIBLE.ul state c- UL CMD OK

DOU’NLINK STATE MACHINE

The client’s downlink state machine processes the following events:

EVENT: User requests downloadEVENT: CTser requests directoryEVENT: User requests selectionEVENT: User requests abortEVENT: Receive DL ABORTED RESP packet.EVENT: Receive DL-COMPLETED RESP packet.EVENT: Receive SELECT RESP packet.EVENT: Receive LOGIN I?ESP 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. Ail other requests are;ignored (perhaps queued) until dl state isDL CMD OK.

State DL UNINIT{

StateDL CMD OK{

EVENT: User requests download (Transmit DL CMD packet.dl state := Di WAIT.

EVENT: User requests directory {Transmit DIR LONG CMD or DIR SHORT CMD packet.dl state := DCDIR WAIT. - --

227

EVENT: User requests selection {Transmit SELECT CMD packet.dl state := DL SEL.

1

EVENT: User requests abort {ignore.dl state : = DL CMD OK

)

EVENT: DEFAIJLT(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 CfiD OK. -

EVENT: Receive DATA packet. {Store data.Mark file INCOMPLETE.dl state C- DL DATA.

1

EVENT: Receive DATA END packet. {If file at client is ok { -

Mark file DATA OK.Save ccontinue offset > equal to file length.Transmit DL AtK CMD.

Else {Mark file INCOMPLETE.Save <continue offset > of 0.Transmit DL N-m CMD.

1

dl state <- DL END.

1

EVENT: DEFAULT{if EVENT is not “data link terminated*’

Terminate data link.dl state c- UL UNINIT

>

228

State DL DATA{

EVENT: User requests abort {Save current offset as <continue offset >.

-Transmit DL NAK CMD.dJ state c - Di 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 c- DL END -

EVENT: DEFAULT{Save current offset as <continue offset >.if EVENT is not “data link term&ted”


State DL END{

EVENT: Receive DL ABORTED RESP packet. (dl state <- DL CMD OK. -

EVENT: Receive DL COMPLETED RESP packet. {Mark file COMPLkTE.dl state <- DL CMD OK.


Terminate data link.dl state C- UL UNINIT

State DL ABORT{

EVENT: Receive DATA packet. {Ignore.dl state c - DL ABORT.

I

229

EVENT: Receive DATA END packet. {dl state c- DL END.-

>



11

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 C%D OK. -

I

EVENT: DEFAULT{if EVENT is not “data link

Terminate data link.dl state c - UL UNINIT

terminated”

State DL DIR DATA{

EVENT: Receive DATA packet. {Send directory data to user.dl state c - DL DIR DATA

EVENT: Receive DATA END packet.{dl state c - DL CMD-OK



230

State DL SEL{

EVENT: Receive DL ERROR RESP packet. {dl state := D L UfiINIT -

>

EVENT: Receive SELECT RESP packet. {dl state := D L UMNI’f

1


Terminate data link.dl state c- UL UNINIT

APPENDIX D - Error Codes

N a m eValue1 ER ILL FORMED CMD2 ER-BAti CONTINUE3 ER-SERVER FSYS4 ER-NO SUCli FILE NUMBER5 ER-SEcECTIOk Ehii’N6 ER-MANDATOEY FIELD MISSING7 ER-NO PFH - -8 ER-POORLY FORMED SEL9 ER-ALREADY LOCKED10 ER-NO SUCH DESTINATION11 ER-SELECTIOi E M P N12 ER-FILE COMPLETE13 ER-NO ROOM14 ER-BAD HEADER15 ER-HEAbER CHECK16 ER-BODY CHECK

231