<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> <!--Converted with LaTeX2HTML 2008 (1.71) original version by: Nikos Drakos, CBLU, University of Leeds * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan * with significant contributions from: Jens Lippmann, Marek Rouchal, Martin Wilck and others --> <HTML> <HEAD> <TITLE>SD Connections and Sessions</TITLE> <META NAME="description" CONTENT="SD Connections and Sessions"> <META NAME="keywords" CONTENT="developers"> <META NAME="resource-type" CONTENT="document"> <META NAME="distribution" CONTENT="global"> <META NAME="Generator" CONTENT="LaTeX2HTML v2008"> <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> <LINK REL="STYLESHEET" HREF="developers.css"> <LINK REL="next" HREF="SD_Data_Structures.html"> <LINK REL="previous" HREF="SD_Development_Outline.html"> <LINK REL="up" HREF="Storage_Daemon_Design.html"> <LINK REL="next" HREF="SD_Data_Structures.html"> </HEAD> <BODY > <!--Navigation Panel--> <A NAME="tex2html968" HREF="SD_Data_Structures.html"> <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> <A NAME="tex2html962" HREF="Storage_Daemon_Design.html"> <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> <A NAME="tex2html956" HREF="SD_Development_Outline.html"> <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> <A NAME="tex2html964" HREF="Contents.html"> <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> <A NAME="tex2html966" HREF="GNU_Free_Documentation_Lice.html"> <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> <BR> <B> Next:</B> <A NAME="tex2html969" HREF="SD_Data_Structures.html">SD Data Structures</A> <B> Up:</B> <A NAME="tex2html963" HREF="Storage_Daemon_Design.html">Storage Daemon Design</A> <B> Previous:</B> <A NAME="tex2html957" HREF="SD_Development_Outline.html">SD Development Outline</A> <B> <A NAME="tex2html965" HREF="Contents.html">Contents</A></B> <B> <A NAME="tex2html967" HREF="GNU_Free_Documentation_Lice.html">Index</A></B> <BR> <BR> <!--End of Navigation Panel--> <!--Table of Child-Links--> <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A> <UL> <LI><A NAME="tex2html970" HREF="SD_Connections_Sessions.html#SECTION00931000000000000000">SD Append Requests</A> <LI><A NAME="tex2html971" HREF="SD_Connections_Sessions.html#SECTION00932000000000000000">SD Read Requests</A> </UL> <!--End of Table of Child-Links--> <HR> <H1><A NAME="SECTION00930000000000000000"></A> <A NAME="2118"></A> <A NAME="2119"></A> <BR> SD Connections and Sessions </H1> <P> 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). <P> 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 ``<TT>3201 Notification pending</TT>'', 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. <P> 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. <P> <H2><A NAME="SECTION00931000000000000000"></A> <A NAME="2125"></A> <A NAME="2126"></A> <BR> SD Append Requests </H2> <P> <DL> <DT><STRONG>append open session = JobId [ Password ] </STRONG></DT> <DD><A NAME="2135"></A> A data append session is opened with the Job ID given by <I>JobId</I> with client password (if required) given by <I>Password</I>. If the session is successfully opened, a status of <TT>3000 OK</TT> is returned with a ``<TT>ticket = </TT><I>number</I>'' 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 ``<TT>3502 Volume busy</TT>'' is returned. If no volume is mounted, or the volume mounted cannot be appended to, a status of ``<TT>3503 Volume not mounted</TT>'' is returned. <P> </DD> <DT><STRONG>append data = ticket-number </STRONG></DT> <DD><A NAME="2145"></A> If the append data is accepted, a status of <TT>3000 OK data address = IPaddress port = port</TT> is returned, where the <TT>IPaddress</TT> and <TT>port</TT> specify the IP address and port number of the data channel. Error status codes are <TT>3504 Invalid ticket number</TT> and <TT>3505 Session aborted</TT>, the latter of which indicates the entire append session has failed due to a daemon or media error. <P> 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: <P> <TT>file-index stream-id info</TT> <P> The details are specified in the Daemon Protocol_ChapterStart2 section of this document. <P> </DD> <DT><STRONG>*append abort session = ticket-number </STRONG></DT> <DD><A NAME="2164"></A> The open append session with ticket <I>ticket-number</I> 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 <TT>3505 Session aborted</TT>. <P> </DD> <DT><STRONG>append end session = ticket-number </STRONG></DT> <DD><A NAME="2169"></A> The open append session with ticket <I>ticket-number</I> 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. <P> </DD> <DT><STRONG>append close session = ticket-number </STRONG></DT> <DD><A NAME="2173"></A> The append session with ticket <I>ticket</I> is closed. This message does not receive an <TT>3000 OK</TT> 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: <P> <TT><TT>Volume = </TT>Volume-id start-file start-block end-file end-block volume-session-id</TT>where <I>Volume-id</I> is the volume label, <I>start-file</I> and <I>start-block</I> are the file and block containing the first data from that session on the volume, <I>end-file</I> and <I>end-block</I> are the file and block with the last data from the session on the volume and <I>volume-session-id</I> is the volume session ID for blocks from the session stored on that volume. </DD> </DL> <P> <H2><A NAME="SECTION00932000000000000000"></A> <A NAME="2197"></A> <A NAME="2198"></A> <BR> SD Read Requests </H2> <P> <DL> <DT><STRONG>Read open session = JobId Volume-id start-file start-block end-file end-block volume-session-id password </STRONG></DT> <DD><A NAME="2219"></A> where <I>Volume-id</I> is the volume label, <I>start-file</I> and <I>start-block</I> are the file and block containing the first data from that session on the volume, <I>end-file</I> and <I>end-block</I> are the file and block with the last data from the session on the volume and <I>volume-session-id</I> is the volume session ID for blocks from the session stored on that volume. <P> If the session is successfully opened, a status of <P> <TT><TT>3100 OK Ticket = </TT><I>number</I>``</TT> <P> 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 ''<TT>3502 Volume busy</TT>`` is returned. If no volume is mounted, or the volume mounted cannot be appended to, a status of ''<TT>3503 Volume not mounted</TT>`` 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 ''<TT>3505 Session not found</TT>`` is returned. <P> </DD> <DT><STRONG>Read data = Ticket Block </STRONG></DT> <DD><A NAME="2236"></A> The specified Block of data from open read session with the specified Ticket number is returned, with a status of <TT>3000 OK</TT> followed by a ''<TT>Length = </TT><I>size</I>`` 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 ''<TT>3201 End of volume</TT>`` is returned. If a block number greater than the largest in the file is requested, a status of ''<TT>3401 End of file</TT>`` is returned. <P> </DD> <DT><STRONG>Read close session = Ticket </STRONG></DT> <DD><A NAME="2244"></A> 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. </DD> </DL> <P> <I>by John Walkerhttp://www.fourmilab.ch/ January 30th, MM </I> <P> <HR> <!--Navigation Panel--> <A NAME="tex2html968" HREF="SD_Data_Structures.html"> <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A> <A NAME="tex2html962" HREF="Storage_Daemon_Design.html"> <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A> <A NAME="tex2html956" HREF="SD_Development_Outline.html"> <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A> <A NAME="tex2html964" HREF="Contents.html"> <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A> <A NAME="tex2html966" HREF="GNU_Free_Documentation_Lice.html"> <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A> <BR> <B> Next:</B> <A NAME="tex2html969" HREF="SD_Data_Structures.html">SD Data Structures</A> <B> Up:</B> <A NAME="tex2html963" HREF="Storage_Daemon_Design.html">Storage Daemon Design</A> <B> Previous:</B> <A NAME="tex2html957" HREF="SD_Development_Outline.html">SD Development Outline</A> <B> <A NAME="tex2html965" HREF="Contents.html">Contents</A></B> <B> <A NAME="tex2html967" HREF="GNU_Free_Documentation_Lice.html">Index</A></B> <!--End of Navigation Panel--> <ADDRESS> 2012-01-24 </ADDRESS> </BODY> </HTML>
