PACSAT PROTOCOL SUITE SPECIFICATION UPDATE 22 MARCH 1991

AND 

UOSAT/AMSAT IMPLEMENTATION NOTES

The following modifications should be made to the document

"PACSAT Protocol:  File Transfer Level 0"

[In section 4.0 SELECT, remove ambiguity by adding the paragraph ...]

In all cases, relational comparisons are treated as though the information 
from the PACSAT File Header were on the left hand of the relational operator 
and the constant provided by the client were on the right hand of the 
relational operator, as shown in the examples.

[In section 4.1 Client Issuing Select Command replace ...]

> <relop> is an 8-bit field encoding a relational operator:
> 
> bit 7
> -----
>     0


[with text ...]

> <relop> is an 8-bit field encoding a relational operator:
> 
> bit 7
> -----
>     1

[In Appendix C - In the DOWNLINK STATE MACHINE section, replace all references 
to the state UL_UNINIT with state DL_UNINIT.]

[In Appendix C - In the DOWNLINK STATE MACHINE section, State DL_SEL, replace]

>    EVENT: Receive SELECT_RESP packet.{
>         dl_state := UL_UNINIT
>    }

[with the correct state as ...]

>    EVENT: Receive SELECT_RESP packet.{
>         dl_state := UL_CMD_OK
>    }


[In Appendix D - Error Codes, the constant ER_SELECTION_EMPTY is assigned two 
values 5 and 11.  Replace the line ...]

> 11    ER_SELECTION_EMPTY

[with the new error code]

> 11    ER_PARTIAL_FILE

[END OF FTL0 PROTOCOL SPECIFICATION CORRECTIONS.]



--------------------------------------------------------
UOSAT / AMSAT PACSAT PROTOCOL SUITE IMPLEMENTATION NOTES
--------------------------------------------------------

Authors writing client software to be used with UO-14,AO-16 or LO-19 should 
also be aware of the following implementation details.

FTL0 PACKET FORMAT

The FTL0 specification allows a maximum of 2047 information bytes in a single 
FTL0 packet.  To conserve memory, the UoSAT/AMSAT implementation will not 
accept FTL0 packets with more than 256 information bytes.


PACSAT FILE HEADERS

The PACSAT File Header (PFH) Definition was designed to be as general and 
extensible as possible. The UoSAT/AMSAT FTL0 implementation will transport any 
file header which conforms to the Definition. Some fields, however, are not 
yet interpreted by the server. Implementation status is reviewed below.

All header items with ids between 1 and 0x0b are mandatory, as is upload_time. 
Failure to include all of thes fields on uploaded messages results in the 
error message ER_MANDATORY_FIELD_MISSING

Item-by-item Review. If an item does not appear below, it is implemented as 
defined in the Definition:

file_number - As defined. Read cautions below under 'New Files and Efficiency'

file_name - Files uploaded by ground users will always be named with an 8 
     character hexidecimal representation of the time that the file was 
     created.

file_ext - The onboard file system does not recognise or generate extensions.

create_time - as defined. If set by server, will match upload_time.

last_modified_time - set when PFH is modified by server, at completion of 
     uploading and downloading.

seu_flag - Not yet implemented.

file_type - 

     Delete file type 0x0a, "Simple ASCII text file, but compressed" from 
     Appendix A, PACSAT FILE TYPES. This type of file should be indicated by 
     file_type 0x00 and a non-zero compression_type item.

     Add file types as follows:
     0x0b      File and memory error logs
     0x0c      Activity logs

     Note that the PFHADD.EXE software written by myself (G0K8KA), 
     incorrectly uses 0x0c for "miscellaneous binary" files. This will be  
     corrected in the next release.

     file_type 0x01 is intended for a single message from a terrestrial BBS 
     which has been translated into a message with a PFH for final posting to 
     a user or users on PACSAT. The bbs_message_type and bulletin_id_number 
     items were specifically designed to receive the message type and BID for 
     such translated messages. 

     Alternatively, file_type 0x02 is intended for single or multiple 
     exported messages which are being forwarded from one BBS to another. In 
     this case, BID and message type are not applicable, as several messages 
     may be included in the file body.

body_checksum - IMPLEMENTED. If the file body experiences uncorrectable 
     corruption due to radiation or other memory failure, the body_checksum 
     may not match when the file is downloaded.

header_checksum - IMPLEMENTED. If the file header experiences uncorrectable 
     corruption (see above), the checksum will fail on the FIRST download 
     after the corruption. Subsequent downloads will find the header checksum 
     correct, but the header may still contain corrupted information.

upload_time - PROMOTED TO MANDATORY ITEM. If the upload is still in progress, 
     you will never receive the header for the file.

ax25_downloader - Not yet set by the server.

download_time - Not yet set by the server.

expire_time - This is currently set to upload_time plus 4 days. No user-
     override is available.

priority - Not interpreted by server.


FTL0 SELECT PROCEDURE

Select Context Saving

     The LOGIN_RESP packet can cope with servers which maintain selection 
     lists across several sessions between client and server. Because of 
     memory limitations, the UoSAT/AMSAT FTL0 server never does this.

Selection Equation Size

     The restriction above which limits acceptable FTL0 packets to 256 
     information bytes, also limits the length of a single select equation to 
     256 bytes.

Selection List Size

     A maximum of MAXSEL files may be selected by one equation.  If the 
     equation would logically select more than MAXSEL files, the MAXSEL 
     oldest files meeting the critereon will be selected. MAXSEL is 50 on UO-
     14. MAXSEL is 30 on AO-16 and LO-19. 

     If the client makes a selection, and exactly MAXSEL files are returned 
     by that selection, the client must update the selection equation using 
     the date of the newest file returned, and issue the selection again. 
     Only by iterating this process can the client be sure to receive all 
     files which fit the selection. For example

     /* Assume that hightime comes from information stored during the */
     /* user's last login. To get all of the user's new files do this:*/
     do {
          Select ((DESTINATION=="mycall") && (UPLOAD_TIME>hightime))
          Receive SELECT_RESP
          Get directories for all files in selection
          hightime = newest UPLOAD_TIME from received directories
     } while (SELECT_RESP.no_of_files == MAXSEL) 
     store hightime for next session

Equation complexity: 

     The equation evaluation stack is 100 entries deep. Select equations 
     which would require more than a 100 entry stack to evaluate will 
     generate the error message ER_POORLY_FORMED_SEL.

String comparisons: 

     Only 'equal' and 'not equal' have meaning. Greater than and less than 
     are not supported.

     Wildcard characters are '*' and '?'.  '*' matches any group of 
     characters, including no characters.  '?' matches any single character.  
     There may be only 4 '*' wildcard characters in a constant. 

New Files and Efficiency: 

     Efficient client software will allow the user to select and receive 
     directories for "new" files. "New" must be defined properly so that the 
     user is certain to see all files on the satellite. The UoSAT/Microsat 
     file system assigns two unique tags to each  file: an upload time, and a 
     file number. The file number is assigned when the file is created; the 
     upload time is assigned when the file is 'posted' - e.g. completely 
     uploaded. 

     Only the upload time provides a safe and efficient value for defining 
     and selecting "new" files. For example, assume that the highest file 
     number on the satellite when I last logged in was file number 5. Since 
     my last logon, a user started uploading file number 6, but did not 
     finish. Another user completely uploaded file number 7. When the 
     satellite comes back to my groundstation, I select all files with file 
     number greater than 5. This selects file number 7, but misses file 
     number 6, because it is not complete. Thus, using the file number to 
     define "new files" is not guaranteed to work.

     Using upload time, this problem is avoided, since file number 6 will be 
     assigned its upload time when it is completely uploaded, hence it will 
     be newer than file number 7, which was already uploaded. Using upload 
     time produces the correct "new files" listing.

     Because upload time is the only safe way to get a new files list, the 
     UoSAT/Microsat file system and the server's FTL0 implementation are 
     optimized for directory searches with upload-time criterion. Processing 
     a select equation is more efficient if the equation restricts the range 
     of file upload times to be searched.  To take advantage of this, upload 
     time restrictions should be placed at the end of the equation, ANDed 
     onto the entire equation.  Four specific possibilities are recognized by 
     the spacecraft FTL0 implementation:

     [equation] (UPLOAD_TIME relop n) AND 

     [equation] (UPLOAD_TIME relop n) AND (UPLOAD_TIME relop n) AND

     (UPLOAD_TIME relop n) (UPLOAD_TIME relop n) AND

     (UPLOAD_TIME relop n)


     Where [equation] represents select terms providing any other desired 
     constraints.

     Selection equations which do not end with one of the forms shown above 
     will be correctly evaluated, but will have to be evaluated for EVERY 
     FILE ON THE SYSTEM.  


CONNECT PROCEDURES

The UoSAT/AMSAT FTL0 servers can accommodate only a limited number of 
simultaneous connections. UO-14 currently has a user limit of 2 while AO-16 
and LO-19 support 4 simultaneous users. If transactions with the satellite are 
carried out efficiently and in a "socialised" manner, these limits will 
actually improve the communications facilities available to satellite users.

If you are writing client software, it should not repeatedly attempt to 
connect to a server if the server responds with the AX.25 "BUSY signal" (DM). 
After receiving a DM, client software should monitor the downlink for UI 
frames from the server to BBSTAT. If the data in the UI frame says "Open: ... 
", a renewed connect request should be made. If no BBSTAT UI frames are heard 
or the frame says "CLOSED:" or "FULL:", no further connect requests should be 
transmitted. 

In general 'blind' transmission of SABMs contributes useless uplink 
congestion. The only occassion on which 'blind' connect requests should be 
made is when initially trying to find out whether LO-19 or AO-16 are "Open:". 
On these satellites, waiting for the first BBSTAT frame can take some time, 
and it is worth probing with an initial SABM. On UO-15, the BBSTAT frames are 
transmitted every five seconds, and whenever someone disconnects from the BBS, 
so probing on UO-15 is not recommended.


INACTIVITY TIMEOUT

If IDLE_TIME seconds pass with no client communications (no data received, 
none successfully transmitted) the AX.25 link will be disconnected. The only 
exception to this is when the satellite is processing a select equation for 
the client. IDLE_TIME is 60 currently seconds on all satellites.


SESSION LENGTH AND STRUCTURE

The satellite FTL0 servers are a shared resource. Many groundstations are 
usually waiting to use the satellites. Client software should strive to use a 
short, effective session, then relinquish the satellite for another station. 
There are no strict rules about how long session should be, and the satellites 
do not currently limit session length. 

Under no circumstances should client software wait for user input while 
connected to the satellite. User inputs should be gathered independently, 
before and after satellite connections, or by a "multitasking" system which 
never keeps the satellite waiting for user input. 

If possible, client software should operate the FTL0 protocol full-duplex; 
uploading can be multiplexed with selecting, directory downloading or file 
downloading. (PG.EXE currently does not support full-duplex, though PE1CHL's 
NET.EXE programs do.)

The model client software would perform one operation per session: select-and-
directory, upload or download. In practice, the implementation of full-duplex 
client software dictates a somewhat more complex approach, matching uplink 
transactions with downlink transactions. In any case, make your software 
sociable - limit transactions to a few minutes at the very most. 


[END]
