## TCPware V5.7 Programmer's Guide

- Introduction
- What Is RPCGEN?
- Software Requirements
- Input Files
- Output Files
- Preprocessor Directives
- Invoking RPCGEN
  - Creating All Output Files at Once
  - Creating Specific Output Files
  - Examples:
  - Creating Server Stubs for TCP or UDP Transports
- Error Handling
- Restrictions

Chapter 14

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 ONC RPC Run-Time Library (RTL) calls where they are needed.

Compiling with RPCGEN is one step in developing distributed applications. See Chapter 13, 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 ONC RPC Fundamentals, Chapter 12, provides details on these layers.

# Software Requirements

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

VMS Version 5.0 or later | DEC C compiler Version 3.2 or later

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

VMS Version 5.0 or later | VAX C compiler Version 3.0 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

Example 14-1 shows a sample interface definition from the TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC]PRINT.X file.

Example 14-1 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 ONC 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. Table 14-1 lists the RPCGEN output files and summarizes their purpose. You can edit RPCGEN output files during application development. The TCPWARE_ROOT:[TCPWARE.EXAMPLES.RPC] directory provides sample RPCGEN output files.

Table 14-1 RPCGEN Output Files (Continued)

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 for mat, and vice versa.
Header | Contains common definitions, such as those needed for any structures being passed.

Invoking RPC explains how to request specific output files.

Table 14-2 shows the conventions you should use to name output files.

Table 14-2 RPCGEN File Naming Conventions (Continued)

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 Table 14-2 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 Table 14-3 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.

Table 14-3 Macros

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:

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

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

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

• Asynchronous transports