# Compaq TCP/IP Services for OpenVMS
ONC RPC Programming

Previous | Contents | Index

## 2.3.2 Implementing the Procedure Declared in the Protocol Specification

Example 2-6 (see SYS$COMMON:[SYSHLP.EXAMPLES.TCPIP.RPC]DIR_SERVER.C) consists of the `dir_server.c` program that implements the remote `READDIR` procedure from the previous RPC protocol specification file.

Example 2-6 Remote Procedure Implementation

    /*
    ** dir_server.c: remote OpenVMS readdir implementation
    */
    #include <errno.h>
    #include <rms.h>
    #include <rpc/rpc.h>   /* Always needed */
    #include "dir.h"       /* Created by RPCGEN */

    extern int SYS$PARSE(struct FAB *);
    extern int SYS$SEARCH(struct FAB *);

    extern char *malloc();

    readdir_res *
    readdir_1(dirname)
        nametype *dirname;
    {
        char   expanded_name[NAM$C_MAXRSS+1];
        struct FAB fab;
        struct NAM nam;
        namelist       nl;
        namelist      *nlp;
        static readdir_res res; /* must be static! */
        char   resultant_name[NAM$C_MAXRSS+1];
        int exit();

        /*
        ** Initialize the FAB.
        */
        fab = cc$rms_fab;
        fab.fab$l_fna = *dirname;
        fab.fab$b_fns = strlen(*dirname);
        fab.fab$l_dna = "SYS$DISK:[]*.*;*";
        fab.fab$b_dns = strlen(fab.fab$l_dna);

        /*
        ** Initialize the NAM.
        */
        nam = cc$rms_nam;
        nam.nam$l_esa = expanded_name;
        nam.nam$b_ess = NAM$C_MAXRSS;
        nam.nam$l_rsa = resultant_name;
        nam.nam$b_rss = NAM$C_MAXRSS;
        fab.fab$l_nam = &nam;

        /*
        ** Parse the specification and see if it works.
        */
        if (SYS$PARSE(&fab) & 1) {
     /*
     ** Free previous result
     */
     xdr_free(xdr_readdir_res, &res);

            /*
            ** Collect directory entries.
            ** Memory allocated here will be freed by xdr_free
            ** next time readdir_1 is called
            */
            nlp = &res.readdir_res_u.list;
            while (SYS$SEARCH(&fab) & 1) {
         resultant_name[nam.nam$b_rsl] = '\0';
                nl = (namenode *) malloc(sizeof(namenode));
         *nlp = nl;
                nl->name = (char *) malloc(nam.nam$b_name +
                                           nam.nam$b_type +
                                           nam.nam$b_ver + 1);
         strcpy(nl->name, nam.nam$l_name);
                nlp = &nl->next;
                }
            *nlp = NULL;

            /*
            ** Return the result
            */
            res.Errno = 0;
            } /* SYS$PARSE() */
        else
            res.Errno = fab.fab$l_sts;

        return &res;
        }

## 2.3.3 The Client Program that Calls the Remote Procedure

Example 2-7 (see SYS$COMMON:[SYSHLP.EXAMPLES.TCPIP.RPC]RLS.C) shows the client program, `rls.c` , that calls the remote server procedure.

Example 2-7 Client Program that Calls the Server

    /*
    * rls.c: Remote directory listing client
    */
    #include <errno.h>
    #include <rms.h>
    #include <stdio.h>
    #include <rpc/rpc.h>    /* always need this */
    #include "dir.h"

    main(argc, argv)
         int   argc;
         char *argv[];
    {
         CLIENT *cl;
         char   *dir;
         namelist nl;
         readdir_res *result;
         char   *server;
         int exit();

        if (argc != 3) {
            fprintf(stderr, "usage: %s host directory\n", argv[0]);
            exit(1);
            }

        server = argv[1];
        dir = argv[2];

        /*
        ** Create client "handle" used for calling DIRPROG on
        ** the server designated on the command line.  Use
        ** the tcp protocol when contacting the server.
        */
        cl = clnt_create(server, DIRPROG, DIRVERS, "tcp");
        if (cl == NULL) {
            /*
            ** Couldn't establish connection with server.
            ** Print error message and stop.
            */
            clnt_pcreateerror(server);
            exit(1);
            }

        /*
        ** Call the remote procedure readdir on the server
        */
        result = readdir_1(&dir, cl);
        if (result == NULL) {
            /*
            ** An RPC error occurred while calling the server.
            ** Print error message and stop.
            */
            clnt_perror(cl, server);
            exit(1);
            }

        /*
        ** Okay, we successfully called the remote procedure.
        */
        if (result->Errno != 0) {
            /*
            ** A remote system error occurred.
            ** Print error message and stop.
            **/
            errno = result->Errno;
            perror(dir);
            exit(1);
            }

        /*
        ** Successfully got a directory listing.
        ** Print it out.
        */
        for (nl = result->readdir_res_u.list;
                 nl != NULL;
                     nl = nl->next)
            printf("%s\n", nl->name);
        exit(0);
        }

## 2.3.4 Running RPCGEN

As with the simple example, you must run the RPCGEN protocol compiler on the RPC protocol specification file DIR.X:

    $ RPCGEN DIR.X

RPCGEN creates a header file, DIR.H, an output file of client skeleton routines, DIR_CLNT.C, and an output file of server skeleton routines, DIR_SVC.C. For this advanced example, RPCGEN also generates the file of XDR routines, DIR_XDR.C.

## 2.3.5 Compiling the File of XDR Routines

The next step is to compile the file of XDR routines, DIR_XDR.C:

    $ CC/DECC DIR_XDR

## 2.3.6 Compiling the Client and Server Programs

After the XDR compilation, use two CC and LINK sequences to create the client program and the server program:

- To create the client program called `rls` , compile the client program, RLS.C and the client skeleton program from the original RPCGEN compilation DIR_CLNT.C. Then link the two object files and the object file produced by the recent compilation of the file of XDR routines together with the RPC object library:

      $ CC/DECC RLS.C
      $ CC/DECC DIR_CLNT.C
      $ LINK RLS,DIR_CLNT,DIR_XDR,TCPIP$RPC:TCPIP$RPCXDR/LIBRARY

- To create the server program called `dir_server` , compile the remote `READDIR` implementation program, DIR_SERVER.C and the server skeleton program from the original RPCGEN compilation, DIR_SVC.C. Then link the two object files and the object file produced by the recent compilation of the file of XDR routines together with the RPC object library:

      $ CC/DECC DIR_SERVER.C
      $ CC/DECC DIR_SVC.C
      $ LINK DIR_SERVER,DIR_SVC,DIR_XDR,TCPIP$RPC:TCPIP$RPCXDR/LIBRARY

Note If you want to use the shareable version of the RPC object library, reference the shareable version of the library, SYS$SHARE:TCPIP$RPCXDR_SHR, in your LINK options file.

## 2.3.7 Copying the Server to a Remote System and Running It

Copy the server program `dir_server` to a remote system called `space` in this example. Then, run it as a detached process:

    $ RUN/DETACHED DIR_SERVER

From the local system `earth` invoke the RLS program to provide a directory listing on the system where `dir_server` is running in background mode. The following example shows the command and output (a directory listing of `/usr/pub` on system `space` ):

    $ MCR SYS$DISK:[]RLS "space" "/usr/pub"
    .
    ..
    ascii
    eqnchar
    kbd
    marg8
    tabclr
    tabs
    tabs4

Note Client code generated by RPCGEN does not release the memory allocated for the results of the RPC call. You can call `xdr_free` to deallocate the memory when no longer needed. This is similar to calling `free` , except that you must also pass the XDR routine for the result. For example, after printing the directory listing in the preceding example, you could call `xdr_free` as follows:
    xdr_free(xdr_readdir_res, result);

# 2.4 Debugging Applications

It is difficult to debug distributed applications that have separate client and server processes. To simplify this, you can test the client program and the server procedure as a single program by linking them with each other rather than with the client and server skeletons. To do this, you must first remove calls to client creation RPC library routines (for example, `clnt_create` ). To create the single debuggable file RLS.EXE, compile each file and then link them together as follows:

    $ CC/DECC RLS.C
    $ CC/DECC DIR_CLNT.C
    $ CC/DECC DIR_SERVER.C
    $ CC/DECC DIR_XDR.C
    % LINK RLS,DIR_CLNT,DIR_SERVER,DIR_XDR,TCPIP$RPC:TCPIP$RPCXDR/LIBRARY

The procedure calls are executed as ordinary local procedure calls and you can debug the program with a local debugger. When the program is working, link the client program to the client skeleton produced by RPCGEN and the server procedures to the server skeleton produced by RPCGEN.

There are two kinds of errors possible in an RPC call:

1. A problem with the remote procedure call mechanism.
   This occurs when a procedure is unavailable, the remote server does not respond, the remote server cannot decode the arguments, and so on. As in Example 2-7, an RPC error occurs if `result` is `NULL` .
   The program can print the reason for the failure by using `clnt_perror` , or it can return an error string through `clnt_sperror` .
2. A problem with the server itself.
   As in Example 2-6, an error occurs if `opendir` fails; that is why `readdir_res` is of type `union` . The handling of these types of errors is the responsibility of the programmer.

# 2.5 The C Preprocessor

The C preprocessor, CC/DECC/PREPROCESSOR, runs on all input files before they are compiled, so all the preprocessor directives are legal within an .X file. RPCGEN may define up to five macro identifiers, depending on which output file you are generating. The following table lists these macros:

Identifier | Usage
--- | ---
`RPC_HDR` | For header file output
`RPC_XDR` | For XDR routine output
`RPC_SVC` | For server skeleton output
`RPC_CLNT` | For client skeleton output
`RPC_TBL` | For index table output

Also, RPCGEN does some additional preprocessing of the input file. Any line that begins with a percent sign ( `%` ) passes directly into the output file, without any interpretation. Example 2-8 demonstrates this processing feature.

Example 2-8 Using the Percent Sign to Bypass Interpretation of a Line

    /*
     * time.x: Remote time protocol
     */
    program TIMEPROG {
         version TIMEVERS {
              unsigned int TIMEGET(void) = 1;
         } = 1;
    } = 44;

    #ifdef RPC_SVC
    %int *
    %timeget_1()
    %{
    %    static int thetime;
    %
    %    thetime = time(0);
    %    return (&thetime);
    %}
    #endif

Using the percent sign feature does not guarantee that RPCGEN will place the output where you intend. If you have problems of this type, do not use this feature.

# 2.6 RPCGEN Programming

The following sections contain additional RPCGEN programming information about network types, defining symbols, INETd support, and dispatch tables.

## 2.6.1 Network Types

By default, RPCGEN generates server code for both UDP and TCP transports. The /TRANSPORT option creates a server that responds to requests on the specified transport. The following command creates a UDP server from a file called PROTO.X:

    $ RPCGEN /TRANSPORT=UDP PROTO.X

## 2.6.2 User-Provided Define Statements

The RPCGEN protocol compiler provides a way to define symbols and assign values to them. These defined symbols are passed on to the C preprocessor when it is invoked. This facility is useful when, for example, invoking debugging code that is enabled only when you define the `DEBUG` symbol. For example, to enable the DEBUG symbol in the code generated from the PROTO.X file, use the following command:

    $ RPCGEN /DEFINE=DEBUG PROTO.X

## 2.6.3 INETd Support

The RPCGEN protocol compiler can create RPC servers that INETd can invoke when it receives a request for that service. For example, to generate INETd support for the code generated for the PROTO.X file, use the following command:

    $ RPCGEN /INET_SERVICE PROTO.X

The server code in `proto_svc.c` supports INETd. For more information on setting up entries for RPC services, see Section 3.7.

In many applications, it is useful for services to wait after responding to a request, on the chance that another will soon follow. However, if there is no call within a certain time (by default, 120 seconds), the server exits and the port monitor continues to monitor requests for its services. You can use the /TIMEOUT_SECONDS option to change the default waiting time. In the following example, the server waits only 20 seconds before exiting:

    $ RPCGEN /INET_SERVICE /TIMEOUT_SECONDS=20 PROTO.X

If you want the server to exit immediately, use /TIMEOUT_SECONDS = 0; if you want the server to wait forever (a normal server situation), use /TIMEOUT_SECONDS = -1.

## 2.6.4 Dispatch Tables

Dispatch tables are often useful. For example, the server dispatch routine may need to check authorization and then invoke the service routine, or a client library may need to control all details of storage management and XDR data conversion. The following RPCGEN command generates RPC dispatch tables for each program defined in the protocol description file, PROTO.X, and places them in the file PROTO_TBL.I (the suffix .I indicates index):

    $ RPCGEN /TABLE PROTO.X

Each entry in the table is a `struct rpcgen_table` defined in the header file, PROTO.H, as follows:

                   struct rpcgen_table {
                       char        *(*proc)();
                       xdrproc_t   inproc;
                       unsigned    len_in;
                       xdrproc_t   outproc;
                       unsigned    len_out;
                   };

In this definition:

- `proc` is a pointer to the service routine.
- `inproc` is a pointer to the input (arguments) XDR routine.
- `len_in` is the length in bytes of the input argument.
- `outproc` is a pointer to the output (results) XDR routine.
- `len_out` is the length in bytes of the output result.

The table `dirprog_1_table` is indexed by procedure number. The variable `dirprog_1_nproc` contains the number of entries in the table. The `find_proc` routine in the following example shows how to locate a procedure in the dispatch tables.

    struct rpcgen_table *
    find_proc(proc)
         long    proc;
    {
         if (proc >= dirprog_1_nproc)

              /* error */
         else
              return (&dirprog_1_table[proc]);
    }

Each entry in the dispatch table (in the file input_file_TBL.I) contains a pointer to the corresponding service routine. However, the service routine is not defined in the client code. To avoid generating unresolved external references, and to require only one source file for the dispatch table, the actual service routine initializer is `RPCGEN_ACTION(proc_ver)` . The following example shows the dispatch table entry for the procedure `printmessage` with a procedure number of 1:

         .....
         (char *(*)())RPCGEN_ACTION(printmessage_1),
         xdr_wrapstring,       0,
         xdr_int,              0,
         .....

With this feature, you can include the same dispatch table in both the client and the server. Use the following `define` statement when compiling the client:

    #define RPCGEN_ACTION(routine)  0

Use the following `define` statement when compiling the server:

    #define RPCGEN_ACTION(routine)  routine

# 2.7 Client Programming

The following sections contain client programming information about default timeouts and client authentication.

## 2.7.1 Timeout Changes

A call to `clnt_create` sets a default timeout of 25 seconds for RPC calls. RPC waits for 25 seconds to get the results from the server. If it does not get any results, then this usually means that one of the following conditions exists:

- The server is not running.
- The remote system has failed.
- The network is unreachable.

In such cases, the function returns `NULL` ; you can print the error with `clnt_perrno` .

Sometimes you may need to change the timeout value to accommodate the application or because the server is slow or far away. Change the timeout by using `clnt_control` . The code segment in the following example demonstrates the use of `clnt_control` .

    struct timeval tv;
    CLIENT *cl;

    cl = clnt_create("somehost", SOMEPROG, SOMEVERS, "tcp");
    if (cl == NULL) {
         exit(1);
    }
    tv.tv_sec = 60; /* change timeout to 1 minute */
    tv.tv_usec = 0; /* this should always be set  */
    clnt_control(cl, CLSET_TIMEOUT, &tv);

## 2.7.2 Client Authentication

By default, client creation routines do not handle client authentication. Sometimes, you may want the client to authenticate itself to the server. This is easy to do, as shown in the following code segment:

    CLIENT *cl;

    cl = clnt_create("somehost", SOMEPROG, SOMEVERS, "udp");
    if (cl != NULL) {
         /* To set UNIX style authentication */
         cl->cl_auth = authunix_create_default();
    }

For more information on authentication, see Section 3.6.

# 2.8 Server Programming

The following sections contain server programming information about system broadcasts and passing data to server procedures.

## 2.8.1 Handling Broadcasts

Sometimes, clients broadcast to determine whether a particular server exists on the network, or to determine all the servers for a particular program and version number. You make these calls with `clnt_broadcast` (for which there is no RPCGEN support). Refer to Section 3.5.2.

When a procedure is known to be called with broadcast RPC, it is best for the server not to reply unless it can provide useful information to the client. Otherwise, servers could overload the network with useless replies. To prevent the server from replying, a remote procedure can return `NULL` as its result; the server code generated by RPCGEN can detect this and prevent a reply.

In the following example, the procedure replies only if it acts as an NFS server:

    void *
    reply_if_nfsserver()
    {
         char notnull;   /* just here so we can use its address */
         if (access("/etc/exports", F_OK) < 0) {
              return (NULL);  /* prevent RPC from replying */
         }
         /*
          * return non-null pointer so RPC will send out a reply
          */
         return ((void *)&notnull);
    }

If a procedure returns type `void *` , it must return a nonnull pointer if it wants RPC to reply for it.

## 2.8.2 Passing Data to Server Procedures

Server procedures often need to know more about an RPC call than just its arguments. For example, getting authentication information is useful to procedures that want to implement some level of security. This information is supplied to the server procedure as a second argument. (For details, see the structure of `svc_req` in Section 3.6.2.) The following code segment shows the use of `svc_req` , where the first part of the previous `printmessage_1` procedure is modified to allow only root users to print a message to the console:

    int *
    printmessage_1(msg, rqstp)
         char **msg;
         struct svc_req  *rqstp;
    {
         static int result;      /* Must be static */
         FILE *f;
         struct authunix_parms *aup;

         aup = (struct authunix_parms *)rqstp->rq_clntcred;
         if (aup->aup_uid != 0) {
              result = 0;
              return (&result);
         }
    /* Same code as before */

Previous | Next | Contents | Index