It is intended that programmers will write MODULEs of $rpcFileModuleCls to support access to special devices across a network. XIDAK does not currently supply any $rpcFileModuleCls MODULEs.

RPC files make it possible for a server to provide “logical files” to its clients, the contents of which can be computed in arbitrary ways. For example, a server could maintain a single physical file containing a number of structure images. Clients could access each image as a separate RPC file. The server would be able to enforce file locking between the clients and to permit client access to only limited portions of the physical file.

If simple access to a system-dependent file is desired on a remote system, the NET device MODULE (see Appendix E) provides a more transparent and convenient method than RPC files.

6.1. $openRpcFile

$openRpcFile opens an RPC file. The interpretation of fileName is completely up to the remote MODULE p.

The openBits can be any combination of input, output, create, random, keepNul, delete, alterOK, $pdf, and errorOK. The detailed interpretation of all but keepNul and errorOK is up to the remote MODULE p.

If the file can be opened, a POINTER to an open file is produced, and TRUE is returned.

If the file cannot be opened, and errorOK is set, then an error message is produced in errorMsg and FALSE is returned.

If the file cannot be opened, and errorOK is not set, then a fatal error is signaled with errMsg. This differs from a normal MAINSAIL open since the file names passed to $openRpcFile typically have meaning only to the remote MODULE, not to an interactive user.

RPC files support all of the MAINSAIL file system PROCEDUREs that actually perform I/O, and are closed with the normal MAINSAIL close PROCEDURE. At present, RPC files do not support MAINSAIL file system PROCEDUREs that do not actually perform I/O, e.g., $fileInfo.

6.2. $rpcFileModuleCls

MODULEs of the CLASS $rpcFileModuleCls are RPC MODULEs that supply the contents of RPC files. The PROCEDUREs in RPC file MODULEs are actually called by a device MODULE written by XIDAK. This device MODULE is used by the files returned by calls to $openRpcFile. Thus, normal application client code never calls the PROCEDUREs in an RPC file MODULE directly.

The declaration of $rpcFileModuleCls is shown in Figure 6–2.

$rpcFileOpen is called whenever a client attempts to open an RPC file by calling $openRpcFile. The fileName supplied to the $openRpcFile call is passed without modification to $rpcFileOpen. $openRpcFile maps a subset of its openBits into those shown in Table 6–3, and passes them to $rpcFileOpen. Other bits contained in $openRpcFile's openBits are not passed to $rpcFileOpen. This mapping is necessary since the MAINSAIL-defined bits passed to $openRpcFile may change across MAINSAIL versions, but the mapped bits are guaranteed to remain the same. This makes it possible for a client and a server to be running different MAINSAIL versions.

In addition to the bits shown in Table 6–3, the $rpcFileDataBit is set if the file is a data file, or the $rpcFileTextBit is set if the file is a text file.

The actual interpretation of the openBits passed to $rpcFileOpen is completely up to the RPC file MODULE. The remote MODULE may ignore any bits, but should give an error return if passed a bit it ignores. It is expected that if an RPC file MODULE supports one of these bits that the semantics will parallel that for the bit when passed to the normal MAINSAIL open PROCEDURE.

bufferSize is initialized by the device MODULE to a positive value that is the size of buffer the device MODULE prefers to use. For example, under SunOS TCP/IP this might be 16K, since this is the size for optimum performance. $rpcFileOpen modifies bufferSize to be the actual buffer size to be used by $rpcFileWriteBuffer, $rpcFileReadBuffer, and $rpcFileWriteThenReadBuffer.

eofPos is produced by $rpcFileOpen as the end-of-file position, in character units, of the file at the time is is opened if it can be computed by $rpcFileOpen. Otherwise it is produced as -1L.

If $rpcFileOpen can open the file, TRUE is returned and a positive LONG INTEGER is produced in fileDscr to identify the RPC file uniquely. The file descriptor is unique among all RPC files currently open by a given RPC file MODULE. If the file cannot be opened, FALSE is returned, and an error message is produced in errorMsg.

$rpcFileClose is called to close an RPC file. The only valid closeBit is $rpcFileDeleteBit, and its detailed interpretation is up to the RPC file MODULE. After an RPC file is closed, the LONG INTEGER used as its file descriptor may be reallocated by a subsequent $rpcFileOpen. If no errors occur, $rpcFileClose returns TRUE, otherwise it produces the error message in errorMsg, and returns FALSE.

$rpcFileWriteBuffer is called when the client wants to write a buffer to the RPC file indicated by fileDscr. bufferNumber indicates which buffer is to be written to the file (the first buffer in the file is buffer zero and contains character units 0L through bufferSize - 1L of the file). bufferPDF is the address of the buffer, and bufferLength is its size. bufferLength is normally equal to the bufferSize returned by $rpcFileOpen; it will be less than bufferSize only for the last buffer in the file, and will never be greater. If the buffer can be written to the file, TRUE is returned. If an error occurs, an error message is produced in errorMsg, and FALSE is returned.

$rpcFileReadBuffer is called when the client wants to read a buffer from the RPC file indicated by fileDscr. bufferNumber indicates which buffer is to be read from the file (the first buffer in the file is buffer zero). bufferPDF is the address of the buffer, and bufferLength is its size. bufferSize is equal to the bufferSize returned by $rpcFileOpen. If the buffer can be read from the file, TRUE is returned, the buffer contents are filled, and bufferLength indicates the actual amount of data read into the buffer (which must always be less than or equal to bufferSize). If the requested buffer position is beyond the end of the file, TRUE is returned, but bufferSize is 0L. If an error occurs, an error message is produced in errorMsg, and FALSE is returned.

$rpcFileWriteThenReadBuffer is an optimization for random access files. It acts exactly as the sequence $rpcFileWriteBuffer followed by $rpcFileReadBuffer, but requires only one remote PROCEDURE call.

The bufferPDF parameter in $rpcFileWriteBuffer, $rpcFileReadBuffer, and $rpcWriteThenReadBuffer is a CHARADR so that it can address character units or storage units. The identifier ends in PDF only to suppress character set translation by RPC, not to indicate that the buffer necessarily contains PDF text or data; it may, in fact, contain machine-dependent text or data.

$rpcFileModuleCls is subject to change, most likely by the addition of PROCEDUREs to provide additional file functionality (e.g., $fileInfo). It is possible that the name of the CLASS and/or its fields may also change. Users writing MODULEs of $rpcFileModuleCls must be prepared to track the applicable changes.