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;