Name

txrx - manage Remote Procedure Call (RPC) protocol descriptions

Synopsis

txrx parse @file ?name?
txrx parse string ?name?
txrx delete name
txrx list


Description

Txrx is a Tcl command that creates and manages RPC protocol descriptions. A protocol description stores internally an RPC protocol. RPC protocols are defined using a data language called XDR, short for eXternal Data Representation. The most popular RPC protocol is NFS - the Network File System. Other protocols using RPC and XDR are ping, the lock manager, the quota daemon and the yellow pages network database protocols. Several vendors use RPC and XDR to implement specialized client-server services. With the advent of WebNFS(TM) - simplified NFS over TCP - as a class of network resources, it becomes important to have a simple and flexible tool like txrx that can help in the rapid and incremental development of TCP/IP based computing solutions.

For further information about XDR and RPC please read the Request For Comments (RFC) 1831 and 1832, available from the net. The official URL for RFCs is ftp://ftp.internic.net/rfc. In the following we assume knowledge of the terminology introduced by these RFC's. The term program denotes an RPC protocol. A program may have multiple versions representing the evolution of the protocol in time. For example, the same RPC server may service clients that understand different versions of the protocol. Each version of a protocol consists of a set of procedures where each procedure performs some useful processing on the server. Procedures, versions and programs are each identified by a number. Specifying a triplet procedure version program uniquely identifies which procedure should be called on the server when the client makes an RPC call.

Txrx accepts the following syntax:

txrx parse @file ?name?
txrx parse string ?name?
Create a new protocol description by parsing the contents of the file or string. The protocol description will be used to process incoming or outgoing RPC calls. The optional argument name is returned as result and represents the name of a new Tcl command that encapsulates the functionality of the protocol description. The default name of the command is txrxn. If the file does not exist or the contents cannot be parsed txrx returns an error. The contents of file/string are assumed to have been preprocessed by the C language precompiler cpp and contain no preprocessor directives. Lines that start with # in the file will be ignored.
txrx delete name
Delete a protocol description and all the information associated to it. Free up all memory buffers that may have been used to process RPC calls. The return value is an empty string.
txrx list
Return a list of the names of all protocol descriptions.

The command created by txrx can be used to process both client and server RPC requests. Note that no explicit conditions or processing options are set on the channel used by the command to communicate with its peer. The channels used in communication should be managed independently of the protocol description. At the very least, since binary data is exchanged, the channel should be set into binary mode using the -translation option of fconfigure. The current implementation of channels in Tcl 7.5 supports only file and TCP channels. As other implementations become available (UDP, IPX, broadcast) it should be possible for txrx to support these with a minimum of changes.

Since a protocol is managed independently of the channel the same channel can be used for RPC calls and to service remote requests. The remote procedure call model is extended this way to peer to peer communication. The underlying idea is to have data definition and processing independent of data transport. Total independence is not possible, as messages passed through stream channels (TCP) are separated using the record marking standard.

The commands accepted by a protocol description are used to invoke RPC calls and replies and to configure the processing of RPC calls. The syntax is:

 protocolName option ?arg arg ...?

Option and the arguments determine the type of processing and the bindings between protocol procedures and Tcl commands. The following are possible:

protocolName write typeName list
Write will convert a Tcl data structure into XDR format and stream the converted data to the data buffer. This provides a convenient way of sending data to a receiver and a means to define other data exchange protocols based on the XDR standard. The return value is an empty string. If an error occurs during send an error message will be returned.
protocolName read typeName
Read enables a process to read structured data from the network. The data received is converted from XDR format using the rules in the next section. The result of the call is a Tcl list. If an error occurs during conversion an error message is returned instead.
protocolName buffer cmd ?args?
Buffer is used to control the buffering of data during an RPC operation. Write and read described above should be used in conjunction with buffer. The subcommands accepted are:
init write channel
init read channel
to initialize a send or receive data operation. The channel argument of the command is a Tcl channel name.
reset
to cleanup a partially full send buffer or to skip to the end of the current input message.
flush
to actually send data to the network. A flush operation does not guarantee that data becomes available to the peer process. A flush on the channel is recommended to ensure data arrives to the other end of the pipe.

Data Type Mapping

The protocol description guides at all times the conversion from/to Tcl data structures to XDR format. The following are the rules used for conversion:

Keywords

remote procedure call, channel, data representation