RPC Clients

A LayGO RPC client is simply a LayGO program which has been linked using an RPC enabled version of the LayGO API libraries. In programming terms, access to LayGO protocol stack on the remote system is completely transparent to the application, with one exception: the client must explicitly make a connection to the server before the first standard LayGO API function call is made and must explicitly disconnect from the server after the last standard LayGO API function call has been made. Connecting to a server must be done explicitly because more than one LayGO RPC Server may be available, and the client has a choice of which one to connect to. The client can locate a server in one of 3 ways:

1. Using RPC name service, via the server's stack number and whatever network protocol is available.
2. Using TCP/IP, via the IP address of the host.
3. Using interprocess communication, connecting to the server on the local host.

(One or more of these ways may not be available, depending on your network configuration.) Each of these ways corresponds to a LayGO API function:

1. lgo_ConnectServer()
2. lgo_ConnectServerIp()
3. lgo_ConnectServerLocal()

Regardless of the method used to connect to the server, the client calls lgo_DisconnectServer() to close the connection. The following sample code illustrates the process:

LServerId  serverId = 13;
LResult    result;

if ((result = lgo_ConnectServer(serverId)) < 0)
{
    printf("Failure connecting to LayGO RPC Server %d: %s\n",
                (int) serverId, lgo_ErrorMessage(result));
    exit(EXIT_FAILURE);
}
else
{
	/* Process... */

    lgo_DisconnectServer();
}

Only one RPC server connection can be active at any time. All CIDs must be closed and the server disconnected before connecting to another server.

The only other issue which must be expicitly considered in an RPC client is whether the client should do stack initialization and shutdown. Using the standard API, the application is always expected to do these tasks. Using the RPC API, they can either be done centrally by the server itself or by one (or more) client programs.

Static Linking - Choosing RPC at Build-time

The simplest way to RPC enable a client application is to statically link it with the LayGO RPC API. The standard LayGO API is exported by laygo32a.lib (Win32), liblaygosola.so (Solaris) and liblaygolnxa.so (Linux). The RPC enabled LayGO API is exported by laygo32r.lib (Win32), liblaygosolr.so (Solaris), and liblaygolnxr.so (Linux). The functions exported are identical, but the implementation is different. The full correspondence of standard and RPC enabled libraries is shown below:

The LayGO Message API exported by laygo32m.lib (Win32), liblaygosolm.so (Solaris) and liblaygolnxm.so (Linux) does not have an RPC version.

Dynamic Linking - Choosing RPC at Run-time

The LayGO Toolkit supports type-safe dynamic loading of the LayGO libraries via the LaygoDll library. Both the standard and RPC enabled versions of the LayGO API can be loaded in this way with the choice made at runtime. This means that a client can be written to use either RPC or the standard API. (In the standard API, the functions which connect to and disconnect from the server exist but simply return an error code.) LayGO for Java uses this method to support both the standard and RPC APIs in a single JNI implementation. See the LayGO Dynamic Loading API for details.