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

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

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).

Running RPCGEN on DIR.X creates four output files:

• Header file (DIR.H)
• Client skeleton file (DIR_CLNT.C)
• Server skeleton file (DIR_SVC.C)
• File of XDR routines (DIR_XDR.C)

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 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 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

$ 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:

• 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

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

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

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

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:

• 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