The SSI receives requests from client applications. There are no constraints on the method the SSI uses to do this; the interface may be either a function call or an IPC mechanism. There is an implied constraint, however, in that the SSI must be able to relate a response to a request so that the response can be sent to the appropriate application.
The StorageTek. SSI communicates with an application via a BSD socket IPC mechanism. In order to match a response with the application that issued the original request, it employs a queueing mechanism that stores the !PC return address of the application. In this case, the IPC return address is an application input socket number.
When the application request is frrst received, its return address is placed on the queue. The location on the queue is described by an integer returned from the queueing function. This integer is assigned to the ssi_identifier in the CSI_HEADER structure and is preserved by the CSI in its responses. When the SSI receives a Storage Server response, it uses the ssi _identifier to retrieve the application's IPC address from the queue, then it sends the response to the application at that IPC address.
For an example of how this mechanism works in the StorageTek SSI, see the CSI source file csi_lminput. c.
Formatting a Request Into a Storage Server Packet
Since there are no constraints with respect to the format and structure of messages sent to the SSI by an application, this requirement is to be defined by the customer.
The StorageTek SSI receives input as application-level Storage Server packets. They are distinguished from SSI-CSI Storage Server packets in that they have an IPC_HEADER at the topmost layer of the packet instead of a CSI HEADER.
Since all packets sent from the SSI across the network must contain a
CSI_HEADER, the IPC_HEADER is stripped off and replaced by a
CSI_HEADER containing the RPC return address of the SSI. See Input to the CS! From the SS! in Chapter 7 for a description of how to
initialize the CSI_HEADER. See the CSI "C" source fue csi_lminput. c
for a description of how the StorageTek SSI strips off the IPC _HEADER
and replaces it with a CSI_HEADER. See the CSI
"e"
source filecsi_rpccall. c for a description of how the CSI_HEADER is initialized prior to making an RPC call to the CSI.
SSI Requirements Programming an SSI
Sending a Storage Server Packet !In the NI
The requirements for an SSI issuing an RPC call to the CSI are as follows:
• The CSI HEADER must be initialized with the RPC return address of the SSI so that the CSI can send responses back to the SSI.
• The network buffer structure state information must be initialized properly before entry into xdrrequest ( ) .
• The SSI must obtain the network address and, optionally, the port number of the CSI.
• The SSI must implement an appropriate RPC timeout-retry algorithm.
• The SSI must initiate a connection to the remote CSI via a call to either clntudp_create () or clnttcp_create ().
• The SSI must call clnt_call () which sends the request packet to the CSI's RPC dispatcher.
• The SSI must block while waiting for the CSI to send an acknowledge via a svc _ sendreply () call.
• The SSI must call clnt_destroy () to terminate the connection to the CSI.
Initializing the CSI_HEADER
The SSI must initialize the top layer of a request, which is the
CSI_HEADER, with its return address so that the CSI can use this address in sending Storage Server responses to the SSI. See Input to the CSI From the SSI in Chapter 7 for a description of how to initialize the RPC return address.
The cs I _HEADER must also be stamped with a transaction ID (of type
CSI_XIO) consisting of the following:
• The SSI's return address (redundant for this implementation of the SSI/CSI, but not for future extensions)
• The current process ID
• A packet sequence number
This architecture was chosen so that the CSI can not only identify packet sequence, but also differentiate between SSIs running on
different hosts and multiple SSIs running on a single host. See Input to the CSI From the SSI in Chapter 7 for a description of how to initialize the CSI XID.
Programming an SSI SSI Requirements
Initializing the Network Buffer Structure
The SSI must initialize the network buffer structure (of type CSI_MSGBUF) before calling the clnt_call () RPC routine, since
clnt_call () calls the XDR translation routine csi_xdrrequest ().
See Message Translation Structures in Chapter 7 for details on the required state of the network buffer on entry to csi_xdrrequest ().
Obtaining the Network Address of the CSI
The SSI must obtain network address of the CSI before the SSI calls
clnt_call () in order to be able to properly initialize the frrst parameter on the interface. This parameter is a pointer to an Internet addressing structure (of type struct sockaddr_in).
The following are requirements for obtaining the remote address of the CSI:
• Prior knowledge of the name of the CSI host
• An entry for the CSI host in the SSI host's / etc/hosts file (or its equivalent)
• A system call, roughly equivalent to the UNIX system call
gethostbyname ( ) , which returns the address for a remote host.
Note: If the sinyort variable (the CSI port number in the Internet address structure used by the SSI on the clnt_call () interface) is set to 0, the portmapper will always be consulted to obtain a target remote CSI port number before packets are sent.
Implementing a Timeout-Retry Algorithm
It is necessary to implement a timeout and retry algorithm, due to variations in the quality of network service and load on both the SSI and Storage Server host. The SSI detects poor or failed network service by exercising a timeout on a particular send attempt.
Functionality for a timeout-retry scheme is provided within RPC.
Depending on the nature of the client application, however, it may be desirable to implement the timeout-retry algorithm at a higher level, since once invoked, the built-in RPC method is outside of user control.
the RPC method of timeout-retry is specified by declaring a per-try timeout when initiating a connection via the clntudp_create () RPC call, and an overall timeout on the subsequent clnt _call ( ) .
Effectively, the overall number of tries is equal to the overall timeout divided by the per-tty-timeout. For example, if the per-try-timeout passed to clntudp_create () is specified as 4 seconds, and the overall timeout passed to clnt_call () is specified as 20 seconds, then five tries at sending will be attempted within clnt_call (). If the
RPC_SUCCESS return status is not forthcoming and no other RPC error
SSt Requirements Programming an SSI
the full timeout has been attempted. The timeout factors need to be tailored to the individual computer installation.
The clnt_call () -embedded RPC retry scheme hypothetically could have various negative consequences on an SS!. One major
consequence is that neither application input nor network input can be detected until the call returns. Consequently, packets may be dropped at either the application or the network input endpoints.
In order to enhance input detection and prevent the dropping of packets, it may be desirable to implement the retry algorithm within the SSI program code, rather than within the RPC call.
Following are the requirements for recovering from poor network service:
• Specify a per-try timeout, either within SSI program code or within RPC as a parameter to clntudp_create ().
• Specify an overall timeout, either within SSI program code or within RPC as a parameter to clnt_call ().
• Provide a mechanism for RPC error detection and recovery in case of RPC failures or RPC timeouts which prevents packets from being dropped.
• Depending on the individual SSI application, provide a mechanism whereby sending network output will not block the detection of either application or network input.
In order to provide a robust system, StorageTek has chosen to favor input over output in both its SSI and its CSI. If input is detected during network transmissions, transmission is temporarily halted, and the packet is placed on a network output queue. The CSI or SSI then receives either application or network input. This prevents the dropping of packets.
After input has been read, if no more input is pending, the StorageTek SSI flushes its network output queue, sending currently queued packets to the appropriate target SSI, and then sends the most recently received packet.
In all cases, it is imperative that the ordering of packets between a specified CSII SSI pair be preserved. Packets must be sent in the correct order.
In the StorageTek SSI, environment variables are used to fine-tune the retry algorithm so that the values for timeout and number-of-tries need not be hard-coded. The StorageTek SSI has its retry algorithm
Programming an SSI SSI Requirements Initiating a Connection to the CSI
The SSI initiates a connection to the CSI by calling either
clnttcp_create () or clntudp_create (). The parameters in this call are set as follows:
• struct sockaddr in is initialized to the CSI Internet address. To get the CSI address may require a call to gethostbyname () or its equivalent. The /etc/hosts file must contain the CSI host network address.
• The program number is set to CSI_PROGRAM.
• The version number is set to either CSI TCPVERSION or
CS I_UDPVERS ION.
• The socket pointer is set to an open socket of the appropriate Internet family type, or to RPC_ANYSOCK which will cause RPC to create the socket.
• If using clntudp_create (), the timing parameter is set as
discussed in the "Implementing a Timeout-Retry ~lgorithm" topic in this section.
This call returns a client handle structure which will be used in the subsequent invocation of clnt_call ().
Sending a Request to the CSI
The SSI sends a message packet to the CSI RPC dispatcher via a call to clnt~call (). The parameters in this call are set as follows:
• The flISt parameter is set to the client handle returned from
clnttcp_create () or clntudp_create ().
• The procedure number is CSI_ACSLM_PROC.
• The XDR serialization procedure is csi_ xdrrequest () .
• The pointer to the network buffer is set to a structure of type
CSI MSGBUF.
• The XDR procedure for data returned is not used, therefore it is set to xdr_void().
• The network buffer for data returned is not used, therefore it is set to null.
• The overall timeout to be used is set as discussed in the Retry and Timeout section.
Invoking XDR Translation
In order to translate the request, the SSI issues a call to
svc_getargs (). One of the parameters to this function is the XDR translation function, in this case csi_xdrrequest (), and the other is the network buffer where the serialized packet and information
SSI Requirements Programming an SSI describing its size and state will be placed. See CSI Message
Processing in Chapter 5 for a description of the operation of
csi_xdrrequest (). See Message Translation Structures in Chapter 7 for a description of the status information returned in the network buffer.
Reading a Response From the NI
The SSI receives Storage Server responses via the NI. Input from the network is detected when a poll of input file descriptors yields a network file descriptor as being active.
Depending on the particular implementation of the SSI, this input will usually be in the form and structure of an XDR-encoded Storage Server response packet sent by the CSI. Typically, this means that one of the file descriptors in the svc_fds global fue descriptor mask, defined in the RPC library, has input pending. Following are the requirements for processing this input within the SSI:
• Detect network input as a result of input file descriptor polling.
• Issue a call to svc _get req () which transparently further demultiplexes the RPC input
• svc_getreq () calls the SSI's RPC dispatcher at a designated
proced~e number (the one originally specified by the SSI in the
CSI_HEADER portion of the request).
• Call svc_getargs () within the RPC dispatcher, to retrieve the packet from the NI.
• svc_getargs () calls the XDR translation function passed to it, in this case csi _ xdrresponse () to deserialize the packet.
• csi _ xdrresponse () decodes the packet and detennines if it is a duplicate of a previous transmission.
• Drop duplicate packets.
• Determine the address of the application destined to receive the packet
Detection of Network Input
As stated previously, the StorageTek SSI uses the select () system call to detect network input. In this case, detection of network input involves comparing the global RPC svc_fds mask of network-dedicated file descriptors that are currently being used to the one(s) returned from select ( ). If network input is active, the call to select ( )
returns a file descriptor mask with one or more bits set, indicating RPC input file descriptors.
Programming an SSI SSI Requirements Invoking RPC Handling of Input
Handling of RPC input is invoked by calling the svc_getreq () function.
This routine has no parameters and initiates handling of input in a somewhat transparent manner, since it calls the SSl's RPC dispatcher on behalf of the SSI. It knows which dispatcher to call because the SSI previously registered its dispatcher during initiation on call to
svc_register ().
Invoking the RPC Dispatcher
If the switch and case "C" coding construct has been used in construction of the SSI dispatcher, the switch trips on request-handle-->procedure-number, and the case entered will be at the value previously defined as the procedure number that the SSI originally defined in the CSI_HEADER. See the Sun Network Programming Manual for details on the switch and case construct.
Invoking XDR Translation
Within the procedure number specified by the SSl's RPC dispatcher, the SSI issues a call to svc _getargs () in order to have the network input translated and placed in the network buffer. One of the
parameters to this function is the XDR translation function, in this case, csi_xdrresponse (), and the other is the network buffer where·
the deserialized packet and information describing its size and state will be placed. See CSI Message Processing in Chapter 5 for a description of the operation of csi_xdrresponse (). See Message Translation Structures in Chapter 7 for a description of the status information returned in the network buffer.
Detecting Duplicate Packets
The SSI must be able to identify and handle duplicate message packets. Even if the SSI exercises a timeout, the original message may still reach the CSI, although later than expected. If this happens, it is likely that the CSlwill send a duplicate response to the request.
See the "Timing Considerations" topic in the CSI Message Processing section in Chapter 5 for a more detailed explanation of how duplicate packets occur.
csi_xdrresponse () detects duplicate packets using the CSI_XID in the CSI_HEADER: the address, process ID, and sequence number of the duplicate packet are identical to a previously received packet. Upon return from csi_xdrresponse (), the packet_status in the CSI_MSGBUF structure is set to CSI_PAKSTAT_DUPLICATE_PACKET for duplicate packets.
Depending on the implementation of the SSI, it may be desirable to
SSt Requirements Programming an SSI
duplicate packet in the initial phases of the de serialization process, returning immediately' upon detecting the condition. Only the
CSI_REQUEST_HEADER has been de serialized at this point. H duplicate packets are not to be dropped, then csi _xdrresponse () must be changed to completely deserialize the packet before returning.
Determining the Destination Application Address
There is no constraint with respect to communications between the SSI and the application. However there is a requirement that a response be paired with a particular request in order that the response can be sent to the appropriate application. See the "Receiving a Request"
topic in this section for details.
Formatting the Storage Server Response
The Storage Server packet received from the network must be
converted to a form that is intelligible by the client application. There is no constraint with respect to communications between the SSI and the application. The nature of this operation is detennined by the customer.