Sophie: coda-doc-5.2.0-4mdk noarch

coda-doc-5.2.0-4mdk.noarch.rpm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
 <TITLE> RPC2 User Guide and Reference Manual: SFTP: A Side Effect for Bulk Data Transfer</TITLE>
 <LINK HREF="rpc2_manual-6.html" REL=next>
 <LINK HREF="rpc2_manual-4.html" REL=previous>
 <LINK HREF="rpc2_manual.html#toc5" REL=contents>
</HEAD>
<BODY>
<A HREF="rpc2_manual-6.html">Next</A>
<A HREF="rpc2_manual-4.html">Previous</A>
<A HREF="rpc2_manual.html#toc5">Contents</A>
<HR>
<H2><A NAME="SFTPChapter"></A> <A NAME="s5">5. SFTP: A Side Effect for Bulk Data Transfer</A></H2>

<H2><A NAME="ss5.1">5.1 General Usage</A>
</H2>

<P>SFTP is a protocol that allows a byte stream to be transferred efficiently from point A to point B, using optimizations such as streaming for large files and piggybacking for small files. These optimizations are completely transparent to the programmer. The byte stream to be transferred can be a file in the file system or a file in virtual memory. A file in VM at one end need not be transferred into a file in VM at the other end; any combination is possible. An SFTP transfer can take place from either an RPC2 server to an RPC2 client or the other way around.  However the request for the transfer is always initiated by the client.  To avoid confusion, we will refer to the sending entity <EM>source</EM> and the receiving entity <EM>sink</EM>. 
<P>
<P>The average user of SFTP need not be aware of the details of SFTP related to
acknowledgements, flow control etc. All he needs to specify are the details of the file transfer such as the name of the file, the transmission direction etc. These are specified by the user in a data structure called a <EM>Side Effect Descriptor</EM>. The side effect descriptor (shown in Appendix 
<@@ref>se.hXXX</A> is used both at the client and the server ends to describe the details of the byte stream transfer. The side effect descriptor is not transmitted: each side provides its own local version. 
<P>
<P>
<P>The most relevant of the side effect descriptors fields are given below.
<DL>
<DT><B>Tag</B><DD><P>This describes the type of side effect used. Currently the only side effect that has been implemented is the SFTP file transfer side effect.
<P>
<DT><B>Value</B><DD><P>This is a union containing descriptor definitions for each type of side effect.  The Tag field serves as the discriminant of the  union.  Currently, there is only one member of the union, corresponding to SFTP.
<P>
<DT><B>Value.SmartFTPD.TransmissionDirection</B><DD><P>specifies if the transfer is from the server to the client (SERVERTOCLIENT) or from the client to the server (CLIENTTOSERVER).
<P>
<DT><B>Value.SmartFTPD.SeekOffset</B><DD><P>specifies the initial position from where a file should be read from, or written to. This is useful, for instance, when bytes are appended to a file.
<P>
<DT><B>Value.SmartFTPD.ByteQuota</B><DD><P>specifies the  maximum number of data bytes
to be sent or received.  A value of -1 implies a limit of infinity.
The RPC call fails if an attempt is made to transfer more bytes.
<P>
<DT><B>Value.BytesTransferred</B><DD><P>is an output parameter.  On completion of the file transfer, it specifies the number of bytes actually transferred.
<P>
<DT><B>Value.SmartFTPD.Tag</B><DD><P>indicates whether the file to be transferred is specified by its name, its inode number, or by its VM address.
<P>
<DT><B>Value.SmartFTPD.FileInfo</B><DD><P>is a union type, discriminated by the previous Tag field, that specifies the  local identity of the file to be transferred.  Note that there is no information of the remote identity of the file.
</DL>
<P>
<H2><A NAME="ss5.2">5.2 An Example</A>
</H2>

<P>
<A NAME="Example-rcat"></A> 
An example of an RPC subsystem which uses SFTP is given in the following section. In describing the use of SFTP, we will refer to this example and outline the steps used. The client-server code using SFTP is very similar to that of an RPC which does not use SFTP.  Hence , we will only describe the additional steps needed when making an RPC which uses SFTP.
<P>
<H3>rcat Subsystem Interface (<EM>in file rcat.rpc</EM>)</H3>

<P>
<P>
<BLOCKQUOTE><CODE>
include(rcat.rpc.mss)
</CODE></BLOCKQUOTE>
<P>
<H3>Server Code (<EM>in file rcat_srv.c</EM>)</H3>

<P>
<P>
<OL>
<LI>Initialize the SFTP package.  This is done by first declaring a data structure of type SFTP_Initializer.<P>The fields of the SFTP_Initializer specify parameters of the SFTP file transfer protocol, and include items such as the window size, packet size etc. These can be set by the user, or can be set to default values by calling the <EM>SFTP_SetDefaults</EM> primitive. The SFTP_Initializer is then activated using the <EM>SFTP_Activate</EM> primitive. Note that the SFTP package should be activated before the RPC2 package is initialized.
<P>
</LI>
<LI>The routine which actually transfers the file does so by first declaring a data structure of type SE_Descriptor and filling in the values.   It then initiates the file transfer by calling the <EM>RPC2_InitSideEffect</EM> primitive.
</LI>
<LI>The <EM>RPC2_CheckSideEffect</EM> primitive can then be used to check the status of the side effect.  Note that in the case of SFTP, the actual file transfer only occurs on this call.</LI>
</OL>
<P>
<BLOCKQUOTE><CODE>
include(rcat_srv.c.mss)
</CODE></BLOCKQUOTE>
<P>
<H3>Client Code (<EM>in file rcat_clnt.c</EM>)</H3>

<P>
<OL>
<LI>As with the server, the SFTP package is initialized by declaring an SFTP_Initializer, and by calling the <EM>SFTP_SetDefaults</EM> and <EM>SFTP_Activate</EM> primitives.
</LI>
<LI>Set the SideEffectType field in RPC2_BindParms to SMARTFTP.
</LI>
<LI>Declare a data structure of type SE_Descriptor.
Set the Tag field to SMARTFTP, and fill in the rest of the fields.
</LI>
<LI>Make the RPC.</LI>
</OL>
<P>
<BLOCKQUOTE><CODE>
include(rcat_clnt.c.mss)
</CODE></BLOCKQUOTE>
<P>
<P>
<P>
<P>
<P>
<P>
<P>
<P>
<P>
<P>
<HR>
<A HREF="rpc2_manual-6.html">Next</A>
<A HREF="rpc2_manual-4.html">Previous</A>
<A HREF="rpc2_manual.html#toc5">Contents</A>
</BODY>
</HTML>