Remote MODULEs are a high-level concept built using the interprocess communication methods described in Chapter 7. The idea is to make an interaction with another process look like the creation of a new MAINSAIL MODULE instance (the “remote MODULE”) in the remote process. Intermodule PROCEDURE calls to the remote MODULE are called “remote PROCEDURE calls” (RPC).

The remote MODULE may be created in any process with which a program is communicating using STREAMS. Commonly, the remote MODULE is created in either a global server process, in a child process, or in a parent process.

In the discussion that follows, the process in which the remote MODULE actually runs is often termed the “RPC server”, and the process that makes the calls the “RPC client”. However, these processes need not be servers and clients in the senses given in Section 7.3. The server may be thought of as the “callee process” and the client as the “caller process”.

RPC clients may be written in MAINSAIL or in C. The MAINSAIL case is described first, but many of the MAINSAIL client concepts are applicable to C as well. RPC servers must be written in MAINSAIL.

To create a new instance of a remote MODULE, a MAINSAIL program must know how to open a stream that communicates with the process that is providing that remote MODULE, or else it must already have a stream that is open to that process. In the case of a remote MODULE provided by a global server, the user needs to know the name of the service and possibly the host system, if the service is provided on multiple systems.

5.1. Overview

In the case of a remote MODULE FOO, the FOO and FOOSRV MODULEs are compiled for the system that is to execute the remote MODULE, and FOOCLI is compiled for the system that will call the remote MODULE.

Figure 5–1 shows a process A creating a new instance of a remote MODULE FOO and calling a PROCEDURE proc1 in FOO.

The MODULE FOOCLI is a “stub” that runs in the “client” process. It has the same interface PROCEDUREs as FOO and it implements those PROCEDUREs by communicating with the “server” process, sending and receiving the arguments as necessary, and returning the values produced by the PROCEDURE call.

The MODULE FOOSRV is the companion stub to FOOCLI that runs in the server process. It communicates with FOOCLI to receive the arguments, then it invokes the correct PROCEDURE in the “real” MODULE, FOO, to do the actual work. It sends back the resultant modified arguments to FOOCLI.

The remote MODULE itself, FOO, is written much as any other MAINSAIL MODULE would be written, except that certain restrictions on the argument types of PROCEDUREs apply, argument transmission efficiency considerations must be taken into account, its interface declaration must use prefix CLASS $remoteModuleCls, and no MODULE interface variables are allowed.

When developing distributed applications, it is often useful to write the MODULE that will eventually be remote (e.g., FOO) as a local MODULE and debug it that way. Then, to distribute the application, the remote MODULE can be compiled with the RPC compiler and either installed into a server or made available to the process that is to provide it.

The call to $newRemoteModule in the process A actually creates a new instance of the MODULE FOOCLI in A's address space. Recall that FOOCLI was produced by the RPC compiler from the interface of the “real” FOO MODULE. In its INITIAL PROCEDURE, FOOCLI uses STREAMS to connect to the service abc in the process B. B creates a new instance of the FOOSRV MODULE. FOOSRV in turn creates a new instance of the FOO MODULE. The connection is maintained until the instance of FOO is disposed.

When the process A makes the intermodule call FOOCLI.proc1, FOOCLI.proc1 communicates with FOOSRV in B, telling it that proc1 is being called. FOOSRV in B invokes FOOSRV.proc1 to read the USES arguments from FOOCLI.proc1. FOOSRV.proc1 then calls the “real” proc1, FOO.proc1, and communicates the results back to FOOCLI.proc1, which returns them to the original caller in A.

During the call to proc1, the current coroutine in A is blocked, just as it would be for a local PROCEDURE call. Because STREAMS communication is used, other scheduled coroutines in A, if any, can run while FOOCLI.proc1 is waiting for the results from FOOSRV.proc1.

In the example above, B is a global server process that uses the $becomeServer PROCEDURE to become an RPC server that provides the MODULEs FOO and INFMOD under the service name abc. The $becomeServer call does not return until the server is killed.

5.2. Remote MODULE PROCEDUREs

$newRemoteModule creates a new remote instance of the MODULE named moduleName. It returns a POINTER to a new instance of the client end of the desired MODULE. If errorOK is set in ctrlBits, errors cause a NULLPOINTER return with msg set; otherwise, a fatal error message is issued.

By default, the instance of the server end of the MODULE is a nonbound MODULE. However, if the bit $rpcBindModules is set in ctrlBits, the instance of the server end is bound instead of nonbound.

Currently, when the POINTER returned from a call to $newRemoteModule with the $rpcBindModules bit set is disposed, the bound remote MODULE instance is also disposed. This has undefined consequences for any other client that may be communicating with the same bound remote MODULE. This behavior is likely to change in the future.

The first instance of $newRemoteModule takes a stream name that can be used to establish a connection with the desired server process or create the desired child process. It calls $openStream to open serviceStreamName and creates a new local instance of moduleName to talk to a new remote instance of moduleName created in the server.

The second instance of $newRemoteModule takes an already open stream that is connected to a process that is about to call or has already called $becomeServer on the other end of the stream. It creates a local instance of moduleName to talk to a new remote instance of moduleName created by the process at the other end of the stream st. This form of $newRemoteModule is useful for talking to child or parent processes when the streams are already open.

$becomeServer becomes a server for the remote MODULEs named by the elements of moduleNames. If errorOK is set in ctrlBits, errors in becoming a server cause a FALSE return with msg set; otherwise, a fatal error message is issued.

The first form of $becomeServer sets up one or more ports on which new clients are accepted as they connect to the service of which the name is given as part of servicePortName. This form is used by a global server process. For each client that connects, a service coroutine is started to provide one of the remote MODULEs to that client. The service coroutines run scheduled so that more than one client can be serviced at once. When the client disconnects, the service coroutine is killed automatically.

The port name may specify an explicit network protocol, e.g., tcp>abc, or it may specify the generic protocol service, e.g., service>abc, to serve clients using every network protocol that the server is declared to serve. The service abc must have been previously declared as a valid service name in the services table as described in Appendix A.

The second form of $becomeServer may be used by a process that wishes to provide a remote MODULE to the process at the other end of the stream st. It provides any of the remote MODULEs in moduleNames to the process at the other end of the stream st. The process on the other end of the stream must call $newRemoteModule to create a new remote MODULE. When the process at the other end disposes of the remote MODULE, the second form of $becomeServer returns with the stream still open.

In either case of $becomeServer, the server program can perform independent computation and/or stream I/O on its own in parallel by calling $becomeServer in an independent scheduled coroutine that it sets up.

The caller of $becomeServer should handle $killServerExcpt if any of the remote MODULEs might raise $killServerExcpt (see Section 5.12).

$becomeServer should be called at most once in a given MAINSAIL process; otherwise, the effects are undefined.

5.3. Remote MODULE Interfaces

• The MODULE interface must use the prefix CLASS $remoteModuleCls.

• The MODULE may have only interface PROCEDUREs; no interface variables are allowed.

• The data types ADDRESS and CHARADR are reserved for buffer passing (see below). The type of a PROCEDURE may not be ADDRESS or CHARADR.

• The Structure Blaster is used to process POINTERs and dynamic ARRAYs, so POINTERs and dynamic ARRAYs must be the roots of structures that can be legally read and written in PDF structure images by the Structure Blaster. (Note that this means that the Structure Blaster (which is a separately available component of MAINSAIL) must be installed in the MAINSAIL system at both the client and server ends in order for such parameters to be used.) Data sections should not be included in structures that might be sent to a server running on another system or another version of MAINSAIL (if a data section is to be valid in the RPC server, the RPC server must have access to the appropriate objmod).

• The MODULE must be written to operate as a nonbound MODULE unless $rpcBindModules is set in the call to $newRemoteModule.

• The macro $remoteModuleDefaults must be invoked at the end of the remote MODULE (see Example 5–6). This macro defines PROCEDURE bodies for two interface PROCEDUREs in the $remoteModuleCls prefix CLASS.

The semantics of USES, MODIFIES, and PRODUCES for POINTERs and dynamic ARRAYs is slightly different between local calls and remote calls. In local calls (standard MAINSAIL), a PRODUCES or MODIFIES POINTER or dynamic ARRAY means that the POINTER value itself can be changed. The object referred to by the POINTER or dynamic ARRAY can be changed even through a USES parameter. Since RPC involves a transfer of data, USES, MODIFIES, and PRODUCES refer to the entire structure being pointed to; i.e., a USES POINTER or dynamic ARRAY sends the structure to the remote MODULE, but does not read it back. A PRODUCES POINTER or dynamic ARRAY does not send a structure, but reads a structure back from the remote MODULE. A MODIFIES POINTER or dynamic ARRAY both writes and reads the structure.

5.4. STRING RPC Parameter Limitations

RPC currently does not handle $PROCVARs or inplace records or ARRAYs.

5.5. Buffer Passing Conventions

Buffers containing characters are distinguished from buffers containing portable data by the name of the CHARADR parameter. Parameter names ending with pdf (case is not distinguished in parameter names) indicate portable data; other names indicate characters. Characters are translated by the remote PROCEDURE call interface automatically, while PDF and storage unit data are not.

The length of the buffer is given in parameters following the ADDRESS or CHARADR parameter. If the buffer contains storage units, the length and size are given in storage units; if the buffer contains characters or PDF data, the length and size are given in character units.

Like other PROCEDURE parameters, buffers may be USES, MODIFIES, or PRODUCES. A USES buffer passes the data in the buffer to the PROCEDURE. A PRODUCES buffer receives data from the PROCEDURE. A MODIFIES buffer passes data to the PROCEDURE and receives data back (the returned data overwrite the original data).

USES buffers are passed as a USES ADDRESS or CHARADR parameter followed by a USES LONG INTEGER buffer length. The caller is responsible for allocating and deallocating the buffer.

MODIFIES and PRODUCES buffers each come in two forms: in one form, a MODIFIES or PRODUCES ADDRESS or CHARADR parameter is followed by a single MODIFIES or PRODUCES LONG INTEGER length parameter (MODIFIES-ADDRESS and PRODUCES-ADDRESS buffers); in the other, a USES ADDRESS or CHARADR parameter is followed by two LONG INTEGERs, a USES parameter size and a MODIFIES or PRODUCES parameter length (MODIFIES-content and PRODUCES-content buffers).

A MODIFIES-ADDRESS buffer must originally be allocated by the caller of a remote PROCEDURE, but may be reallocated by the remote PROCEDURE; a PRODUCES-ADDRESS buffer is always originally allocated by the remote PROCEDURE. By contrast, MODIFIES-content and PRODUCES-content buffers are always allocated and deallocated by the caller of the remote PROCEDURE, never by the remote PROCEDURE itself.

Special PROCEDUREs must be used to allocate and deallocate MODIFIES-ADDRESS and PRODUCES-ADDRESS buffers. These special PROCEDUREs may optionally be used to allocate and deallocate the other kinds of buffers as well.

For USES, MODIFIES-content, and PRODUCES-content buffers, the ADDRESS or CHARADR parameter must itself be declared as a USES parameter. The caller of the PROCEDURE must thus supply a valid ADDRESS or CHARADR; i.e., the parameter may not be NULLADDRESS or NULLCHARADR.

A USES buffer is indicated by following the ADDRESS or CHARADR by a single USES LONG INTEGER parameter giving the amount of data supplied in the buffer. The parameter name must end with length.

PRODUCES-ADDRESS and MODIFIES-ADDRESS parameters are indicated by following the ADDRESS or CHARADR by a single LONG INTEGER parameter. Both parameter are qualified with MODIFIES in the case of a MODIFIES-ADDRESS buffer or PRODUCES in the case of a PRODUCES-ADDRESS buffer. The name of the LONG INTEGER parameter must end in length; it represents the amount of data in the buffer. In the case of a MODIFIES-ADDRESS parameter, the length parameter is originally set by the caller, and may be changed by the remote PROCEDURE if the amount of data to be sent back is different from amount originally set; the remote PROCEDURE may choose to reallocate the buffer to be of a different size in this case. In the case of a PRODUCES-ADDRESS parameter, the buffer is originally allocated by the remote PROCEDURE and the remote PROCEDURE sets the length parameter to tell how much information it is producing.

It is permissible for a MODIFIES-ADDRESS parameter to be NULLADDRESS and for a PRODUCES-ADDRESS buffer to produce NULLADDRESS. The length parameter should be zero in these cases.

PRODUCES-content and MODIFIES-content buffers are indicated by following the ADDRESS or CHARADR by two LONG INTEGER parameters. The first must be a USES parameter giving the allocated size of the buffer; its name must end with size. For PRODUCES buffers, the second parameter must be a PRODUCES parameter that will be set to the length of data supplied by the PROCEDURE call. For MODIFIES buffers, the second parameter must be a MODIFIES parameter that is initially set to the length of data in the buffer and is modified to the length of data supplied by the PROCEDURE call. In both cases, the name of the second parameter must end with length.

Example 5–3 shows an example MODULE declaration of a remote MODULE with USES, PRODUCES-ADDRESS, MODIFIES-ADDRESS, PRODUCES-content, and MODIFIES-content buffer parameters for storage unit, character, and portable data buffers.

5.5.1. When Buffers Are Allocated and Deallocated

The exact sequence of allocations and deallocations for the four types of buffers is shown in Table 5–4. The figure shows the sequence of events (including allocations and deallocations) that takes place with each kind of buffer. Allocations or deallocations for which “client program” or “remote PROCEDURE” appears in the “Whose Responsibility” column must be done explicitly in the client or server code; allocations and deallocations done by the client or server stub are done automatically.

Although it is possible to call newPage or newScratch directly to allocate USES, MODIFIES-content, and PRODUCES-content RPC buffers, rpcNewBuffer is better because it can be redirected to a user-provided MODULE to improve performance if buffers are large or allocation is frequent; this is not possible if calls to newPage and newScratch are hardwired.

rpcNewBuffer sets buffer to NULLADDRESS or NULLCHARADR if bufSize is less than or equal to zero. rpcDisposeBuffer does not do anything if buffer is Zero or bufSize is less than or equal to zero.

5.5.3. Redirecting Calls to rpcNewBuffer and rpcDisposeBuffer

In order to redirect calls to rpcNewBuffer and rpcDisposeBuffer to your own MODULE and to cause the allocations that occur in the client or server also to be redirected to your MODULE, you must set the bufferMgrModule field of $remoteModuleCls to point to a data section of your MODULE:

POINTER($rpcBufferMgrCls) bufferMgrModule;  # Set by user

Once you set the bufferMgrModule interface field of a MODULE, all allocations of MODIFIES-ADDRESS and PRODUCES-ADDRESS buffers in that MODULE must go through that MODULE's bufferMgrModule field. In the client, this will happen if you pass p (where p is the POINTER to the remote MODULE) as the rem parameter to rpcNewBuffer and rpcDisposeBuffer; in the remote MODULE, it will happen if you pass thisDataSection as the rem parameter.

The CLASS $rpcBufferMgrCls is defined as:

CLASS $rpcBufferMgrCls (

    BOOLEAN
    PROCEDURE   rpcNewBufferAdr     (PRODUCES ADDRESS buffer;
                                     LONG INTEGER bufSize);

    PROCEDURE   rpcDisposeBufferAdr (ADDRESS buffer;
                                     LONG INTEGER bufSize);

    BOOLEAN
    PROCEDURE   rpcNewBufferChr     (PRODUCES CHARADR buffer;
                                     LONG INTEGER bufSize);

    PROCEDURE   rpcDisposeBufferChr (CHARADR buffer;
                                     LONG INTEGER bufSize);
);

If you want to provide your own allocation and deallocation PROCEDUREs, you must write a MODULE with this interface. The interface PROCEDUREs should not be called directly but should be called through rpcNewBuffer and rpcDisposeBuffer and implicitly through the client or server stub.

A potentially useful thing to do if you have your own $rpcBufferMgrCls MODULE is allocating storage from a pool that you maintain instead of calling newPage or newScratch (to prevent garbage collection from being triggered by such calls).

You can have a bufferMgrModule in either the client or the server or both (but see below if you are actually calling the “remote” MODULE from within the same process). Assume that you have a MODULE myMod of $rpcBufferMgrCls that you want to perform allocation in both the client and the server. To set it up as bufferMgrModule in the client, set the client's bufferMgrModule field immediately after the call to $newRemoteModule:

p := $newRemoteModule(...);
p.bufferMgrModule := bind(myMod);

Once you do this, all automatic buffer allocations in the client stub go through myMod.

To set it up as bufferMgrModule in the server, set the interface variable in the remote MODULE's INITIAL PROCEDURE:

INITIAL PROCEDURE; # of remote MODULE
...
bufferMgrModule := bind(myMod);
...

Once you do this, all automatic buffer allocations in the server stub go through myMod.

If you are calling a MODULE that is written as a remote MODULE from within the same process as the client, the client and “remote” MODULEs' bufferMgrModule fields must be the same. If you allocate bufferMgrModule as a bound MODULE and use the same MODULE name as shown above, you will get the desired effect.

5.5.4. Low-Level Forms of rpcNewBuffer and rpcDisposeBuffer

BOOLEAN PROCEDURE rpcNewBuffer (
    PRODUCES ADDRESS                buffer;
    LONG INTEGER                    bufSize;
    OPTIONAL POINTER($rpcBufferMgrCls) p);

BOOLEAN PROCEDURE rpcNewBuffer (
    PRODUCES CHARADR                buffer;
    LONG INTEGER                    bufSize;
    OPTIONAL POINTER($rpcBufferMgrCls) p);

PROCEDURE rpcDisposeBuffer  (
    MODIFIES CHARADR                buffer;
    LONG INTEGER                    bufSize;
    OPTIONAL POINTER($rpcBufferMgrCls) p);

PROCEDURE rpcDisposeBuffer (
    MODIFIES ADDRESS                buffer;
    LONG INTEGER                    bufSize;
    OPTIONAL POINTER($rpcBufferMgrCls) p);

It should rarely be necessary for a program to use the low-level forms of rpcNewBuffer and rpcDisposeBuffer; the forms that take a $remoteModuleCls POINTER should be satisfactory for most applications.

5.6. Example of Remote MODULEs between a Parent and Child Process

Examples 5–7 and 5–8 are an example of the use of FOO by executing it in a child and calling it from a parent.

In its INITIAL PROCEDURE, the parent, shown in Example 5–7, creates a child process running the MODULE CHILD under the current version of MAINSAIL. It sets up a coroutine to multiplex the child's TTY (for error messages and debugging) to the parent's TTY. It then creates a new instance of the remote MODULE FOO in the child and calls the PROCEDURE hello in the remote MODULE. Eventually it disposes the remote MODULE, and kills the child process.

Example 5–8 shows how the MODULE CHILD might be written. It becomes a server for the remote MODULE FOO.

A generic MODULE RPCSRV (see Section 5.13) is supplied with the RPC package. The RPCSRV MODULE provides the functionality of the child shown in Example 5–8 in a generic way.

5.7. Example Clients and Servers Using Remote MODULEs

Examples 5–10 and 5–11 are examples of a server program that provides FOO, and a client program that executes FOO remotely.

The client is written like the parent in the previous section, except that it asks to talk to the server named foo instead of creating a child process. The server process is written like the child in the previous section, except that it becomes a server to service>foo instead of to its parent.

The server shown in Example 5–11 keeps accepting and servicing new clients indefinitely.

5.8. The Fields of $remoteModuleCls

$remoteModuleCls provides several user-visible fields, as shown in Figure 5–12.

The version field is used to provide a user-defined version number for the service provided by the remote MODULE, as described in Section 5.9. oldestVersion and newestVersion specify the oldest and newest semantics the server is willing to provide to the client; see Example 5–13.

The two fields $maxExec and $nto specify timeouts for the remote MODULE.

$maxExec is the longest expected execution time for the remote PROCEDURE. If the remote PROCEDURE executes for longer than $maxExec, the client will time out and abort execution of the remote PROCEDURE. The default value for $maxExec is quite long, since it is difficult to predict how long a remote PROCEDURE may require in order to finish.

$nto is a short timeout used when setting up a remote PROCEDURE call. Programmers will not usually need to adjust $nto. However, where client-server communication is unexpectedly slow, it is possible that $nto may be unnecessarily exceeded and the remote PROCEDURE call aborted by a timeout. In this case, $nto should be increased to avoid the timeout.

To set the a timeout, set the appropriate field of $remoteModuleCls immediately after allocating a remote MODULE; e.g., for $maxExec:

m := $newRemoteModule(...);
m.$maxExec := <new timeout value>;

You must set the $maxExec field before making any calls to the remote MODULE; the effect of setting it after the first call is made is undefined.

5.9. Use of Version Numbers

• the declaration for the remote MODULE,

• a description of the semantics of the PROCEDUREs in the remote MODULE declaration, and

• a service version number identifying the version of the remote MODULE to which the accompanying description applies.

The declaration of the remote MODULE allows the client program to declare a POINTER to the remote MODULE's CLASS so that PROCEDURE calls can be made using MAINSAIL's p.f construct.

The description of the semantics of the PROCEDUREs allows the client to make use of the remote MODULE to do useful work.

The service version number allows the client to identify the semantics it is expecting to the server. If a new version of the server is written that accepts new or additional semantics in addition to the old semantics, the server may be written so that it can also service older clients.

When a remote MODULE is written for use in a server, it may set two version parameters in its INITIAL PROCEDURE, as shown in Example 5–13.

These numbers describe the oldest and newest semantics the server is willing to provide to the client, thus allowing servers to be updated with new semantics while still providing the older semantics to older clients.

newestVersion is the current version of the remote MODULE semantics. oldestVersion is the oldest backward-compatible version that the server provides.

If a server provides no version numbers, the default for both version numbers is 0L.

If the code in the remote MODULE wishes to adapt to the client's actual version, it may access the LONG INTEGER interface variable version. This interface variable is declared in $remoteModuleCls, as shown in Figure 5–12. It is set to the value of the cliVersion parameter in the call to $newRemoteModule.

5.10. Writing Adaptable Clients

When the server and client establish a connection at the time of the call to $newRemoteModule, the underlying communication code determines if there is an overlap between the versions provided by the server and the versions acceptable to the client, and if so, uses the highest common version number. This highest number is then made available to the “true” remote MODULE in the LONG INTEGER MODULE interface variable version.

A client may ask for a range of service version numbers when it calls $newRemoteModule. It may then obtain the actual remote MODULE version provided by the server and adapt to the published semantic and syntactic specifications of the returned version.

If different versions provide different MODULE interfaces, the client must not call any PROCEDUREs of which the interface has changed (this requirement is enforced by runtime checking).

5.11. The Server Log File

Entries are made automatically into server.log when the following activities occur in a network server (i.e., a server that is available to processes other than its parent):

• The server is started with the first form of $becomeServer.

• A client connects and starts a remote MODULE.

• A client disposes a remote MODULE or disconnects.

• An unhandled error occurs in a remote MODULE (the call stack is listed). An entry is made in this case for a child server as well as a network server.

If multiple servers are run from the same directory, a MAINEX ENTER subcommand can be used in each server to cause the log files to have different names, if desired.

A sample server.log file:

29-Feb-88 14:21:
    Server service>srv Started, RPC 1 MAINSAIL 11.20
29-Feb-88 14:21:
    Client: bob@Poseidon.1 foo  5 3  29-Feb-88 14:21
29-Feb-88 14:32:
    Finish: bob@Poseidon.1 foo  5 3  29-Feb-88 14:21

5.12. Terminating a Global Server: $killServerExcpt

$HANDLE $becomeServer(...)
$WITH
    IF $exceptionName = $killServerExcpt THENB
        ... clean up...
        exit END;

The generic RPC server RPCSRV obeys this convention (see Section 5.13).

5.13. Generic RPC Server: the RPCSRV MODULE

RPCSRV accepts a command line of the form:

rpcsrv servicePortName rm₁ rm₂ rm₃ ...

to start a global server on the port named servicePortName, or:

rpcsrv - rm₁ rm₂ rm₃ ...

to start a parent server on $parent. In both cases, the names rm₁, rm₂, etc., are names of remote MODULEs to supply to the clients or parent.

Using the RPCSRV MODULE, a server named foo that provides the RPC MODULEs foo and infMod can be started using the UNIX shell command:

/mslDirectory/mainsa rpcsrv service\>foo foo infMod<eol>

where mslDirectory is the MAINSAIL directory. Note that under the UNIX shell, you must quote the > used in the service port name with the shell escape character \.

Using the RPCSRV MODULE, a child process that provides the RPC MODULE FOO can be started using the $openStream PROCEDURE in a MAINSAIL program:

$openStream(chTty,chCtl,"process>" & $executableBootName &
            " rpcsrv - foo");

A server process must do a $becomeServer before a client process can call $newRemoteModule to talk to that server. This restriction is not severe because server processes are often started automatically when the node on which they run comes up (see Section A.4).

5.15. RPC Efficiency Considerations

For example, in a typical configuration, the wall clock time to bind a remote MODULE may vary from a fraction of a second to seconds, depending on whether the server process is paged out. Once the remote MODULE is bound, the wall clock time to complete a trivial remote PROCEDURE call is typically about 0.2 seconds. This time is almost entirely due to TCP communications overhead.

We believe that the overhead per PROCEDURE call could be improved with a faster UNIX network protocol such as UDP. In addition, on operating systems that support faster mechanisms, the overhead may be considerably less. However, if the remote PROCEDURE does a nontrivial amount of computation (e.g., several seconds' worth), even the communication overhead of TCP is not a significant factor.

5.16. Parallel Processing Using RPC Calls

The model for exception handling is that the remote PROCEDURE execution is taking place in the client, so exceptions go up to the PROCEDURE invocation in the server stub, then are raised in the client stub. Certain exceptions are considered local to the server (mainly $abortProcedureExcpt). These are not raised in the client.

$exceptionPointerArg is always set to NULLPOINTER in the client, since it would be undesirable to pass a large structure when an exception occurred.

$systemExcpt is handled specially. If a remote PROCEDURE call causes a $systemExcpt, errMsg is called in the client with some extra registered exceptions: remote calls to see the remote calls stack, remote PRNTCO to see the output of PRNTCO run in the server, and remote debug to debug the server. $exceptionStringArg1 is prefixed with RPC: when $systemExcpt is raised, so that RPC: appears in any error message displayed to the user.

Debugging the server currently means that a call to $debugExec is made in the server. If the server is running on a terminal or terminal emulator, it can be debugged.

5.18. C RPC

RPC clients written in C are similar to those written in MAINSAIL except:

• The server (written in MAINSAIL) must be compiled with the RPC C subcommand (i.e., the RPC subcommand followed by the argument C). This produces a header file and a client stub function file; the latter is analogous to the FOOCLI MODULE in Figure 5–1. The base of the two file names is derived from the remote MODULE name by appending cli to the remote MODULE name converted to lower case. The header file has the extension .h and the client stub function file the extension .c; for example, foocli.h and foocli.c would be produced for a remote MODULE FOO.

• The RPC client source file must include (with #include directives) a file <mrpc.h>, which is shipped with the MAINSAIL STREAMS package, and, for each remote MODULE in which it calls a PROCEDURE, the header file generated when the remote MODULE was compiled with the RPC C subcommand.

• Instead of opening a stream to the RPC server, the client calls the function connectServer (provided by the file mrpc.o, which resides on the MAINSAIL directory).

• Instead of calling $newRemoteModule, the C client calls a function called by the name of the remote MODULE (in lower case) with _init added to it, e.g., foo_init, with the int value returned by connectServer as one of the arguments, to initialize the connection. This special function is called the remote MODULE's _init function.

• The remote PROCEDUREs, instead of being called with a direct POINTER call, as in MAINSAIL, are called with the PROCEDURE name converted to lower case and prefixed by the remote MODULE name and an underscore, e.g., foo_proc1, and with the value returned from the _init function as the first argument.

• When the connection is to be closed, the C program calls a _final function, analogous to the _init function, instead of $closeStream, and then the function disconnserver must be called for the value returned from connectServer.

• MAINSAIL server PROCEDUREs with POINTER arguments or return values cannot be called. STRING and dynamic ARRAY arguments must be handled specially as described below.

• The client must be linked with the client stub functions and with the file mrpc.o from the MAINSAIL directory.

The correspondence between C client arguments and MAINSAIL remote MODULE parameters is shown in Table 5–14. The data types for return values are the same as those for return parameters, except that the caller is responsible for freeing returned pointers (as if they were PRODUCES parameters).

5.18.1. Data Type Rules

typedef struct mainsail_array_descr {
    char    *ary_first_elem;
    long    ary_lb1,ary_ub1,
            ary_lb2,ary_ub2,
            ary_lb3,ary_ub3;
    short   ary_dims, ary_type;
    long    ary_alloc_status;
    } ARRAY;

When a C function passes an array to a remote PROCEDURE, it must first set all the relevant fields of the ARRAY struct. The meanings of the fields are shown in Table 5–15. Since MAINSAIL ARRAYs, unlike C arrays, are not necessarily zero-origin, lower bounds as well as upper bounds of each dimension must be specified.

The ary_type field is the data type of the MAINSAIL ARRAY. It should be set to one of the following constants defined in <mrpc.h>:

ARRAYs of POINTERs or $PROCVARs are not allowed.

The elements of the array should be stored as the C data type corresponding to the MAINSAIL data type of the ARRAY; i.e., they do not have to be stored as MAINSAIL or PDF data types.

A NULLARRAY is represented by an ARRAY with ary_dims or ary_first_elem equal to zero. A USES NULLARRAY can also be passed as null C pointer.

The array elements returned in MODIFIES and PRODUCES ARRAY parameters are automatically allocated with malloc by RPC. The C client must deallocate the elements by calling dispose_array as described in Section 5.18.5.

5.18.2. connectServer and the _init Function

int connectServer (serviceName)
char *serviceName;

connectServer accepts a null-terminated string of the form hostName:serviceName or serviceName. If you omit the hostName (which may be a raw internet address for services accessed through TCP/IP; e.g., 192.9.200.5), connectServer looks in the services table for the named service. If the service is supported on a unique host, it connects to the named service on that host.

connectServer returns a descriptor for the service. If the descriptor is nonnegative, it must be passed to the appropriate _init function to initialize a connection with the specified service; if negative, an error occurred and no connection is established.

The _init function for a remote MODULE has the name of the remote MODULE (in lower case) with _init added to it, e.g., foo_init for a remote MODULE FOO. The interface of an _init function is as follows:

MRPCMOD *foo_init(descr,cliver,oldestsrvver,msg)
int descr;
long cliver, oldestsrvver;
char *msg;

descr is the descriptor returned from a successful connserver call. If the _init function is successful, it returns a nonzero value (the opaque handle MRPCMOD *) which must be specified as the first parameter to all remote PROCEDURE calls to FOO. If the _init function fails, it returns a zero value. msg is set to an error message if a failure occurs. cliver and oldestsrvver correspond to the cliVersion and oldestSrvVersion parameters to $newRemoteModule; see Section 5.2.

5.18.2.1. connserver

int connserver(hostname,servername)
char *hostname,*servername;

The parameters hostname and servername are null-terminated strings that are the name of a host and the name of a service available on that host. connserver("a","b") acts like connectServer("a:b").

New programs should call connectServer instead.

5.18.3. Calling Remote PROCEDUREs

5.18.4. The _final Function and disconnserver

After the _final function is called, the function disconnserver must be called for the descriptor returned from the connserver call. It takes a single int parameter:

int disconnserver(descr)
int descr;

It returns 0 on success, nonzero on error.

After disconnserver is called, the program should free the MRPCMOD struct allocated by the _init function.

5.18.5. dispose_array

dispose_array is declared as follows:

dispose_array(a)
ARRAY *a;

void rpc_register_jump(s,env)
char *s;
jmp_buf env;

A longjmp is made to env when the exception occurs. Before execution falls out of the if part of a C RPC exception handler normally (i.e., not due to an exception that causes a less nested handler to be invoked), the program must call rpc_clear_all(env), where env is the handler's environment argument passed to setjmp:

void rpc_clear_all(env)
jmp_buf env;

This clears all registered exceptions for the handler's environment env and removes the handler from the stack of active handlers. In particular, if the if part contains any conditional logic or statements that transfer control out of the if part, the programmer must be sure that rpc_clear_all is called for all such paths.

More than one exception may be handled by the same environment (i.e., the same jmp_buf may be passed to rpc_register_jump several times to handle several different exceptions in the same place).

The current exception is given by the char pointer function rpc_exception_name; it tells which exception name caused the else part of a handler to be entered. The function takes as an argument the jmp_buf variable env passed to setjmp:

char *rpc_exception_name(env)
jmp_buf env;

rpc_exception_name is guaranteed not to return NULL. If env's else part was not entered or env is invalid, it returns "", which is never a valid exception name.

Here is an example of a C RPC exception handler that catches two exceptions, E1 and E2:

#include <setjmp.h>
char *excptName;
jmp_buf env;

if (! setjmp(env)) {        /* equivalent to MAINSAIL's "$HANDLE" */
    rpc_register_jump(E1,env);  /* catch exception E1 */
    rpc_register_jump(E2,env);  /* catch exception E2 */

    ... code normally executed...

    rpc_clear_all(env);         /* stop catching exceptions */
}
else {                      /* equivalent to MAINSAIL's "$WITH" */
    /* When execution gets here, all exceptions registered for this
     * handler have been cleared and rpc_exception_name(env)
     * contains a copy of the exception that caused this handler to
     * be entered.
     */

    excptName = rpc_exception_name(env);
    if (! strcmp(excptName,E1)) {

        ... code to handle the exception E1...

    }
    else if (! strcmp(excptName,E2)) {

        ... code to handle the exception E2...

    }
}

In previous releases, a function rpc_clear_jump was used instead of rpc_clear_all, and a variable ms_exception was used instead of the function rpc_exception_name. These identifiers still exist, but their use will produce incorrect results under some circumstances, so it is best to change any code that uses them immediately. These identifiers may be removed in some future release.

rpc_clear_jump took an exception name instead of a jmp_buf:

rpc_clear_jump(s)
char *s;

ms_exception was a char * variable, not a function like rpc_exception_name;

char *ms_exception;

Appendix D shows a C client that calls remote PROCEDUREs with a greater range of parameter types to demonstrate the correspondence between C client arguments and MAINSAIL server parameters.

The default version of the C MPRC file mrpc.o is not a shared object. However, if you wish to build a shared object to use in place of mrpc.o, the C source files mrpcpi.c and mrpcgd.c, which were compiled to produce mrpc.o, reside on the MAINSAIL directory. The file mrpcpi.c contains no initialized global data, and is therefore suitable for compilation to produce position-independent code on systems where the C compiler requires that C files to be compiled into position-independent code contain no initialized global data. mrpcgd.c contains the initialized global data used by mrpcpi.c.

The names of the files and their locations may change in the future. XIDAK may, in some future release, start shipping a version of mrpc.o already compiled as a shared object, in which case source files will no longer be available.