txrx - manage Remote Procedure Call (RPC) protocol descriptions
txrx parse @file ?name?
txrx parse string ?name?
txrx delete name
txrx list
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:
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:
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:
Numeric variables convert to/from a number string in Tcl. Hyper (64 bit integers) and quad (quadruple precision IEEE floating point) data is not supported.
typedef enum {RED = 0, BLUE = 2} Flag; Flag v;the Tcl representation of v will be one of the strings "RED" or "BLUE". Conversely a symbolic value will be converted to a number. If a numeric value is used instead of a string the number is converted without checking if it actually belongs to the set of permissible values. Using numbers instead of symbolic constants is discouraged as future versions of txrx may consider this an error.
Similarly, boolean values convert to either one of the strings "TRUE" or "FALSE". Tcl boolean values will be accepted for input whenever a boolean is expected.
Fixed or variable length strings convert to a quoted string, for example:
string dirName<>;
where dirName has value My test converts to string "My test". Non-printable characters convert to their backslash representation (\nnn).
Structures convert to/from a list of the components.
Discriminated unions convert to a list where the first element is the numeric or symbolic value of the discriminant and the remainder elements are the description of the matching union arm. Default values for the discriminant are represented as numeric values.
Arrays, either fixed or variable length, convert to a list where each component of the list is the representation of an element of the array.
Void values convert to an empty list.
Opaque data converts to a string where each individual character is the representation of a single byte of data. For example
opaque Val<3>;where Val has value "<CTRL-x><CTRL-s>f" converts to this Tcl string: "\030\023f" where each backslash sequence represents the corresponding octal value for each byte of the opaque. The C macro isprint is used to convert opaque data to a Tcl string. To convert a Tcl string to a sequence of bytes the function used is Tcl_Backslash. Note that the procedure allows the same opaque data (sequence of bytes) to have multiple representations as a string in Tcl. String comparison of Tcl strings representing the same opaque will nevertheless state the equality of the strings. For example assuming the same defintion for Val as above, if Val has value "\060\061\062" then another equivalent representation is "012".
Pointers -- optional data in RFC terminology -- convert to a nested list. If the value of the pointer is NULL then the nested list will be an empty list. Note that this conversion does not follow the model given in the RFC where a pointer converts to a two element list where the first element is either TRUE or FALSE and the second element is a list representing the data structure respectively an empty list.
remote procedure call, channel, data representation