6. Building Distributed Applications with RPC

Introduction

This chapter is for RPC programmers. It explains:

· What components a distributed application contains

· How to use RPC to develop a distributed application, step by step

· How to get RPC information

Distributed Application Components

The below table lists the components of a distributed application.

Component	Description
Main program (client)	An ordinary main program that calls a remote procedure as if local
Network interface	Client and server stubs, header files, XDR routines for input arguments and results
Server procedure	Carries out the client's request (at least one is required)

These components may be written in any high-level language. The RPC Run-Time Library (RTL) routines are written in the C language.

What You Need to Do

The following steps summarize what you need to do to build a distributed application:

1. Design the application.

2. Write an RPC interface definition. Compile it using RPCGEN, then edit the output files as necessary. (This step is optional. An RPC interface definition is not required. If you do not write one, proceed to step 3.)

3. Write any necessary code that RPCGEN did not generate.

4. Compile the RPCGEN output files, server procedures, and main program using the appropriate language compiler(s). RPCGEN output files must be compiled using HP C.

5. Link the object code, making sure you link in the RPC RTL.

6. Start the Port Mapper on the server host.

7. Execute the client and server programs.

Step 1: Design the Application

You must write a main (client) program and at least one server procedure. The network interface, however, may be hand-written or created by RPCGEN. The network interface files contain client and server stubs, header files, and XDR routines. You may edit any files that RPCGEN creates.

When deciding whether to write the network interface yourself, consider these factors:

Is execution time critical?	Your hand-written code may execute faster than code that RPCGEN creates.
Which RPC interface layer do you want to use?	RPCGEN permits you to use only the highest layer interface. If you want to use the lower layers, you must write original code. The RPC Fundamentals, Chapter 6, describes the characteristics of each RPC interface layer.
Which transport protocol do you want to use?

You may write your own XDR programs, but it is usually best to let RPCGEN handle these.

Step 2: Write and Compile the Interface Definition

An interface definition is a program the RPCGEN compiler accepts as input. The RPCGEN Compiler, Chapter 8, explains exactly what interface definitions must contain.

Interface definitions are optional. If you write the all of the network interface code yourself, you do not need an interface definition.

You must write an interface definition if you want RPCGEN to generate network interface code.

After compiling the interface definition, edit the output file(s).

If you are not writing an interface definition, skip this step and proceed to step 3.

Step 3: Write the Necessary Code

Write any necessary code that RPCGEN did not create for you. The below table lists the texts you may use as references.

Reference	Purpose
RFC 1057	Defines the RPC language. Use for writing interface definitions.
RFC 1014	Defines the XDR language. Use for writing XDR filter routines.
The RPC RTL Client Routines chapter and those that follow	Defines each routine in the RPC RTL. Use for writing stub procedures and XDR filter routines.

Step 4: Compile All Files

Compile the RPCGEN output files, server procedures, and main program separately.

$ CC /STANDARD=RELAXED /WARNING=DISABLE=(IMPLICITFUNC) filename.C

Step 5: Link the Object Code

Link the object code files. Make sure you link in the RPC RTL. Use the following command.

$ LINK filenames, SYS$INPUT /OPTIONS
TCPIP$RPCXDR_SHR /SHARE
SYS$SHARE:DECC$SHR /SHARE
Ctrl+Z

After entering the command, press Ctrl+Z.

To avoid repetitive data entry, you may create an OpenVMS command procedure to execute these commands.

Step 6: Start the Port Mapper

The Port Mapper must be running on the server host. If it is not running, use the MULTINET CONFIGURE/SERVER command to start it.

Step 7: Execute the Client and Server Programs

Perform these steps:

1. Run the server program interactively to debug it, or using the /DETACHED qualifier. Refer to HP’s documentation for details.

2. Run the client main program.

Obtaining RPC Information

You can request a listing of all programs registered with a Port Mapper.

To request a listing of all programs that are registered with the Port Mapper, enter the MULTINET SHOW /RPC_PORTMAP command in the following format at the DCL prompt:

$ MULTINET SHOW /RPC_PORTMAP

If you add /REMOTE_HOST=hostname to this command:

$ MULTINET SHOW /RPC_PORTMAP /REMOTE_HOST=[host-name]

Specify the domain name of the host on which the Port Mapper resides. If you omit this parameter, RPC uses the name of the local host. Sample RPC information output:

$ MULTINET SHOW/RPC_PORTMAP
 MultiNet registered RPC programs:
  Program  Version  Protocol   Port
  -------  -------  --------   ----
  NLOCKMGR  3       TCP        2049
  NLOCKMGR  1       TCP        2049
  NLOCKMGR  3       UDP        2049
  NLOCKMGR  1       UDP        2049
  NFS       2       TCP        2049
  NFS       2       UDP        2049
  MOUNT     1       TCP        1024
  MOUNT     1       UDP        1028
  STATUS    1       TCP        1024
  STATUS    1       UDP        1024