7. RPCGEN Compiler

Introduction

This chapter is for RPC programmers.

What Is RPCGEN?

RPCGEN is the RPC Protocol Compiler. This compiler creates the network interface portion of a distributed application, effectively hiding from the programmer the details of writing and debugging low-level network interface code.

You are not required to use RPCGEN when developing a distributed application. If speed and flexibility are critical to your application, you can write the network interface code yourself, using RPC Run-Time Library (RTL) calls where they are needed.

Compiling with RPCGEN is one step in developing distributed applications. See Chapter 7, Building Distributed Applications, for a complete description of the application development process.

RPCGEN allows you to use the highest layer of the RPC programming interface. The RPC Fundamentals, Chapter 6, provides details on these layers.

Software Requirements

The following software must be installed on your system before you can use RPCGEN:

· OpenVMS 5.5 or higher

· HP C compiler V3.2 or later

Input Files

The RPCGEN compiler accepts as input programs called interface definitions, written in RPC Language (RPCL), an extension of XDR language. RFC 1057 and RFC 1014 describe these languages in detail.

An interface definition must always contain the following information:

· Remote program number

· Version number of the remote program

· Remote procedure number(s)

· Input and output arguments

Below is a sample interface definition:

/*
** RPCGEN input file for the print file RPC batching example.
**
** This file is used by RPCGEN to create the files PRINT.H and PRINT_XDR.C
** The client and server files were developed from scratch.
*/

const MAX_STRING_LEN = 1024; /* maximum string length */

/*
** This is the information that the client sends to the server

*/
struct a_record
{
string ar_buffer <MAX_STRING_LEN>;
};

program PRINT_FILE_PROG
{

version PRINT_FILE_VERS_1
{
void PRINT_RECORD(a_record) = 1;
u_long SHOW_COUNT(void) = 2;
} = 1;
} = 0x20000003;

/* end file PRINT.X */

The default extension for RPCGEN input files is .X.

You do not need to call the RPC RTL directly when writing an interface definition. RPCGEN inserts the necessary library calls in the output file.

Output Files

RPCGEN output files contain code in C language. The below table lists the RPCGEN output files and summarizes their purpose. You can edit RPCGEN output files during application development.

File	Purpose
Client and server stub calls	Interface between the network and the client and server programs. Stubs use RPC RTL to communicate with the network.
XDR routines	Convert data from a machine's local data format to XDR format, and vice versa.
Header	Contains common definitions, such as those needed for any structures being passed.

The Invoking RPC section explains how to request specific output files.

The below table shows the conventions you should use to name output files.

File	Output Filename
Client stub	inputname_CLNT.C
Server stub	inputname_SVC.C
Header file	inputname.H
XDR filter routines	inputname_XDR.C

inputname is the name of the input file. For example, if the input file is TEST.X, the server stub is TEST_SVC.C.

When you use the RPCGEN command to create all output files at once, RPCGEN creates the output filenames listed in the above table by default. When you want to create specific kinds of output files, you must specify the names of the output files in the command line.

Preprocessor Directives

RPCGEN runs the input files through the C preprocessor before compiling. You can use the macros listed in the below table with the #ifdef preprocessor directive to indicate that specific lines of code in the input file are to be used only for specific RPCGEN output files.

File	Macro
Client stub	RPC_CLNT
Server stub	RPC_SVC
Header file	RPC_HDR
XDR filter routines	RPC_XDR

Invoking RPCGEN

This section explains how to invoke RPCGEN to create:

· All output files at once

· Specific output files

· Server stubs for either the TCP or UDP transport

Creating All Output Files at Once

This command creates all four RPCGEN output files at once:

$ RPCGEN input

where input is the name of the file containing the interface definition.

In the following example, RPCGEN creates the output files PROGRAM.H, PROGRAM_CLNT.C, PROGRAM_SVC.C, and PROGRAM_XDR.C:

$ RPCGEN PROGRAM.X

Creating Specific Output Files

This command creates only the RPCGEN output file that you specify:

RPCGEN {-c | -h | -l | -m} [-o output] input

-c	Creates an XDR filter file (_XDR.C)
-h	Creates a header file (.H)
-l	Creates a client stub (_CLNT.C)
-m	Creates a server stub (_SVC.C) that uses both the UDP and TCP transports
-o	Specifies an output file (or the terminal if no output file is given)
output	Name of the output file
input	Name of an interface definition file with a .X extension

Follow these guidelines:

· Specify just one output file (-c, -h, -l, or -m) in a command line

· If you omit the output file, RPCGEN sends output to the terminal screen

Examples:

$ RPCGEN -h PROGRAM

RPCGEN accepts the file PROGRAM.X as input and sends the header file output to the screen, because no output file is specified.

$ RPCGEN -l -o PROGRAM_CLNT.C PROGRAM.X

RPCGEN accepts the PROGRAM.X file as input and creates the PROGRAM_CLNT.C client stub file.

$ RPCGEN -m -o PROGRAM_SVC.C PROGRAM.X

RPCGEN accepts the PROGRAM.X file as input and creates the PROGRAM_SVC.C server stub file. The server can use both the UDP and TCP transports.

Creating Server Stubs for TCP or UDP Transports

This command creates a server stub file for either the TCP or UDP transport:

RPCGEN -s {udp | tcp} [-o output] input

-s	Creates a server (_SVC.C) that uses either the UDP or TCP transport (with -s, you must specify either udp or tcp; do not also use -m)
udp	Creates a UDP server
tcp	Creates a TCP server
-o	Specifies an output file (or the terminal if no output file is given)
output	Name of the output file
input	Name of an interface definition file with a .X extension

If you omit the output file, RPCGEN sends output to the terminal screen.

In this example, RPCGEN accepts the PROGRAM.X file as input and creates the PROGRAM_SVC.C output file, containing a TCP server stub:

$ RPCGEN -s tcp -o PROGRAM_SVC.C PROGRAM.X

Error Handling

RPCGEN stops processing when it encounters an error. It indicates which line the error is on.

Restrictions

RPCGEN does not support the following:

· The syntax int x, y;. You must write this as int x; int y;