DIGITAL TCP/IP Services for OpenVMS
ONC RPC Programming


Previous Contents Index

2.2.6 Copying the Server to a Remote System and Running It

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


$ RUN/DETACHED MSG_SERVER 

Note

You can invoke servers generated by RPCGEN from the command line as well as with port monitors such as INETd, if you generate them with the /INET_SERVICE option.

From a local system (earth) you can now print a message on the console of the remote system space:


$ MCR SYS$DISK:[]RPRINTMSG "space" "Hello out there..." 

The message Hello out there... appears on the console of the system space. You can print a message on any console (including your own) with this program if you copy the server to that system and run it.

2.3 Advanced Example: Using RPCGEN to Generate XDR Routines

Section 2.2 explained how to use RPCGEN to generate client and server RPC code automatically to convert a simple procedure to one that runs remotely over the network. The RPCGEN protocol compiler can also generate the external data representation (XDR) routines that convert local data structures into network format (and vice versa).

The following sections present a more advanced example of a complete RPC service---a remote directory listing service that uses RPCGEN to generate both the client and server skeletons as well as XDR routines.

2.3.1 The RPC Protocol Specification

As with the simple example, you must first create an RPC protocol specification file. This file, DIR.X, is shown in Example 2-5 (see SYS$COMMON:[SYSHLP.EXAMPLES.TCPIP.RPC]DIR.X).

Note

You can define types (such as readdir_res in Example 2-5) by using the struct, union, and enum keywords, but do not use these keywords in later variable declarations of those types. For example, if you define union results, you must declare it later by using results, not union results. The RPCGEN protocol compiler compiles RPC unions into C structures, so it is an error to declare them later by using the union keyword.

Running RPCGEN on DIR.X creates four output files:

The first three files have already been described. The fourth file, DIR_XDR.C, contains the XDR routines that convert the declared data types into XDR format (and vice versa). For each data type present in the .X file, RPCGEN assumes that the RPC/XDR library contains a routine with the name of that data type prefixed by xdr_, for example, xdr_int. If the .X file defines the data type, then RPCGEN generates the required XDR routines (for example, DIR_XDR.C). If the .X file contains no such data types, then RPCGEN does not generate the file. If the program uses a data type but does not define it, then you must provide that XDR routine. This enables you to create your own customized XDR routines.

Example 2-5 RPC Protocol Specification File---Advanced Example

/* 
 * dir.x: Remote directory listing protocol 
 */ 
 
/* maximum length of a directory entry */ 
const MAXNAMELEN = 255; 
/* a directory entry */ 
typedef string nametype<MAXNAMELEN>; 
 
/* a link in the listing */ 
typedef struct namenode *namelist; 
/* 
 * A node in the directory listing 
 */ 
struct namenode { 
     nametype name;          /* name of directory entry */ 
     namelist next;          /* next entry */ 
}; 
 
/* 
 * The result of a READDIR operation. 
 */ 
union readdir_res switch (int Errno) { 
case 0: 
     namelist list;  /* no error: return directory listing */ 
 
default: 
     void;           /* error occurred: nothing else to return */ 
}; 
/* 
 * The directory program definition 
 */ 
program DIRPROG { 
     version DIRVERS { 
          readdir_res 
          READDIR(nametype) = 1; 
     } = 1; 
} = 0x20000076; 

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 side 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 skeletons 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:

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 previous 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 example 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:

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.


Previous Next Contents Index