SD Connections and Sessions

A client connects to a storage server by initiating a conventional TCP connection. The storage server accepts the connection unless its maximum number of connections has been reached or the specified host is not granted access to the storage server. Once a connection has been opened, the client may make any number of Query requests, and/or initiate (if permitted), one or more Append sessions (which transmit data to be stored by the storage daemon) and/or Read sessions (which retrieve data from the storage daemon).

Most requests and replies sent across the connection are simple ASCII strings, with status replies prefixed by a four digit status code for easier parsing. Binary data appear in blocks stored and retrieved from the storage. Any request may result in a single-line status reply of ``3201 Notification pending'', which indicates the client must send a ``Query notification'' request to retrieve one or more notifications posted to it. Once the notifications have been returned, the client may then resubmit the request which resulted in the 3201 status.

The following descriptions omit common error codes, yet to be defined, which can occur from most or many requests due to events like media errors, restarting of the storage daemon, etc. These details will be filled in, along with a comprehensive list of status codes along with which requests can produce them in an update to this document.

SD Append Requests

append open session = JobId [ Password ]

A data append session is opened with the Job ID given by JobId with client password (if required) given by Password. If the session is successfully opened, a status of 3000 OK is returned with a ``ticket = number'' reply used to identify subsequent messages in the session. If too many sessions are open, or a conflicting session (for example, a read in progress when simultaneous read and append sessions are not permitted), a status of ``3502 Volume busy'' is returned. If no volume is mounted, or the volume mounted cannot be appended to, a status of ``3503 Volume not mounted'' is returned.

append data = ticket-number

If the append data is accepted, a status of 3000 OK data address = IPaddress port = port is returned, where the IPaddress and port specify the IP address and port number of the data channel. Error status codes are 3504 Invalid ticket number and 3505 Session aborted, the latter of which indicates the entire append session has failed due to a daemon or media error.

Once the File daemon has established the connection to the data channel opened by the Storage daemon, it will transfer a header packet followed by any number of data packets. The header packet is of the form:

file-index stream-id info

The details are specified in the Daemon Protocol_ChapterStart2 section of this document.

*append abort session = ticket-number

The open append session with ticket ticket-number is aborted; any blocks not yet written to permanent media are discarded. Subsequent attempts to append data to the session will receive an error status of 3505 Session aborted.

append end session = ticket-number

The open append session with ticket ticket-number is marked complete; no further blocks may be appended. The storage daemon will give priority to saving any buffered blocks from this session to permanent media as soon as possible.

append close session = ticket-number

The append session with ticket ticket is closed. This message does not receive an 3000 OK reply until all of the content of the session are stored on permanent media, at which time said reply is given, followed by a list of volumes, from first to last, which contain blocks from the session, along with the first and last file and block on each containing session data and the volume session key identifying data from that session in lines with the following format:

Volume = Volume-id start-file start-block end-file end-block volume-session-idwhere Volume-id is the volume label, start-file and start-block are the file and block containing the first data from that session on the volume, end-file and end-block are the file and block with the last data from the session on the volume and volume-session-id is the volume session ID for blocks from the session stored on that volume.

SD Read Requests

Read open session = JobId Volume-id start-file start-block end-file end-block volume-session-id password

where Volume-id is the volume label, start-file and start-block are the file and block containing the first data from that session on the volume, end-file and end-block are the file and block with the last data from the session on the volume and volume-session-id is the volume session ID for blocks from the session stored on that volume.

If the session is successfully opened, a status of

3100 OK Ticket = number``

is returned with a reply used to identify subsequent messages in the session. If too many sessions are open, or a conflicting session (for example, an append in progress when simultaneous read and append sessions are not permitted), a status of ''3502 Volume busy`` is returned. If no volume is mounted, or the volume mounted cannot be appended to, a status of ''3503 Volume not mounted`` is returned. If no block with the given volume session ID and the correct client ID number appears in the given first file and block for the volume, a status of ''3505 Session not found`` is returned.

Read data = Ticket Block

The specified Block of data from open read session with the specified Ticket number is returned, with a status of 3000 OK followed by a ''Length = size`` line giving the length in bytes of the block data which immediately follows. Blocks must be retrieved in ascending order, but blocks may be skipped. If a block number greater than the largest stored on the volume is requested, a status of ''3201 End of volume`` is returned. If a block number greater than the largest in the file is requested, a status of ''3401 End of file`` is returned.

Read close session = Ticket

The read session with Ticket number is closed. A read session may be closed at any time; you needn't read all its blocks before closing it.

by John Walkerhttp://www.fourmilab.ch/ January 30th, MM