Digital TCP/IP Services for OpenVMS

Digital TCP/IP Services for OpenVMS

ONC RPC Programming


November 1995

This manual provides an overview of high-level programming with open network computing remote procedure calls (ONC RPC), describes how to use the RPCGEN protocol compiler to create applications, and describes the RPC programming interface.

Revision Information: This is a revised manual.

Operating System: OpenVMS VAX Version 6.0, 6.1, 6.2
OpenVMS Alpha Version 7.0

Software Version: Digital TCP/IP Services for OpenVMS Version 4.0





Digital Equipment Corporation Maynard, Massachusetts


November 1995

Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Digital conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Digital Equipment Corporation 1995. All rights reserved.

The following are trademarks of Digital Equipment Corporation:

ACMS, DECdtm, DDCMP, DEC, DECnet, DECNIS, DECserver, DECsystem, DECwindows, DIGITAL, DNA, InfoServer, LAT, OpenVMS, PATHWORKS, POLYCENTER, ULTRIX, VAX, VAXstation, VMS, VMScluster, and the DIGITAL logo.)

The following are third-party trademarks:

CRAY is a registered trademark of Cray Research, Inc.

HP and Hewlett-Packard are registered trademarks of Hewlett-Packard Company.

IBM and OS/2 are registered trademarks of International Business Machines Corporation.

MS-DOS is a registered trademark of Microsoft Corporation.

Macintosh is a registered trademark of Apple Computer, Inc.

MultiNet is a registered trademark of TGV, Inc.

OSF/1 is a registered trademark of Open Software Foundation, Inc.

OSI is a registered trademark of CA Management, Inc.

PATHways is a registered trademark of The Wollongong Group.

PostScript is a registered trademark of Adobe Systems, Inc.

SCO is a trademark of Santa Cruz Operations, Inc.

Sun, NFS, and PC-NFS are registered trademarks of Sun Microsystems, Inc.

TCPware is a registered trademark of Process Software Corporation.

UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.

All other trademarks and registered trademarks are the property of their respective holders.

ZK6528

This document is available on CD-ROM.


Contents


Preface

This manual provides an overview of high-level programming with open network computing remote procedure calls (ONC RPC), describes how to use the RPCGEN protocol compiler to create applications, and describes the RPC programming interface.

Intended Audience

This manual assumes a knowledge of network theory and is for experienced programmers who want to write network applications using ONC RPC without needing to know about the underlying network.

Document Structure

This manual contains eight chapters:
Chapter 1 Provides an overview of high-level programming through remote procedure calls (RPC), and discusses the RPC model and versions, external data representation, and RPC independence from network transport protocol.

This chapter is for anyone interested in ONC RPC.

Chapter 2 Describes how to write RPC client and server applications with the RPCGEN protocol compiler. It also provides some information on RPCGEN, client and server programming, debugging applications, the C preprocessor, and RPC language syntax. This chapter also describes how to create routines for external data representation (XDR).

This chapter is for programmers who want to use RPCGEN to write RPC-based network applications.

Chapter 3 Describes the RPC programming interface layers, XDR serialization defaults, raw RPC, and miscellaneous RPC features.

This chapter is for programmers who need to understand RPC mechanisms to write customized network applications.

Chapter 4 Contains information about the XDR library.

This chapter is for programmers who want to implement RPC and XDR on new systems.

Chapter 5 Contains descriptions of each of the RPC subroutine calls commonly used by client programs.
Chapter 6 Contains descriptions of each of the RPC subroutine calls used by both client and server programs to access the Portmapper service.
Chapter 7 Contains descriptions of each of the RPC subroutine calls commonly used by client programs.
Chapter 8 Contains descriptions of each of the XDR subroutine calls.

Related Documents

You might find these documents useful:

For a complete list of all manuals in the DIGITAL TCP/IP Services for OpenVMS documentation set, see the Digital TCP/IP Services for OpenVMS Concepts and Planning guide.

For additional information about DIGITAL TCP/IP Services for OpenVMS products and services, access the DIGITAL OpenVMS World Wide Web site. Use the following URL:

http://www.openvms.digital.com 

Terminology

This manual uses the following terminology:

Acronyms

The following acronyms are used throughout this book:
BIND Berkeley Internet Name Domain
FTP File Transfer Protocol
SNMP Simple Network Management Protocol
SMTP Simple Mail Transfer Protocol
TCP/IP Transmission Control Protocol/Internet Protocol
UCX Digital TCP/IP Services for OpenVMS
UDP User Datagram Protocol

See Appendix A for a full listing of Digital TCP/IP Services for OpenVMS acronyms.

Conventions

The name of OpenVMS AXP has been changed to OpenVMS Alpha. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha. All IP addresses in this book represent fictitious addresses. The following conventions apply to this book.
Convention Meaning
UPPERCASE TEXT Indicates names of OpenVMS and UCX commands, options, utilities, files, directories, hosts, and users.
lowercase special type Indicates UNIX system output or user input, commands, options, files, directories, utilities, hosts, and users.
italic type Indicates a variable.
[Return] Indicates that you press the Return key.
[Ctrl/] x Indicates that you press the Control key while you press the key noted by x.
[ ] In command format descriptions, indicates optional elements. The elements are separated by vertical bars (|). You can enter as many as you want.
{ } In command format descriptions, indicates you must enter at least one listed element. The elements are separated by bars (|).

Reader's Comments

DIGITAL welcomes your comments on this manual or any of the DIGITAL TCP/IP Services for OpenVMS documents. Send us your comments through any of the following channels:
Internet openvmsdoc@zko.mts.dec.com
Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Location Call Fax Write
U.S.A. DECdirect
800-DIGITAL
800-344-4825
Fax: 800-234-2298 Digital Equipment Corporation
Mailstop: TAY2-2/11D
153 Taylor Street
Littleton, MA 01460
Puerto Rico 787-781-0505 Fax: 787-749-8300 Local DIGITAL subsidiary
Canada DTN: 621-6005
800-DIGITAL
Fax: 613-592-1946 Digital Equipment of Canada, Ltd.
Box 13000
Kanata, Ontario, Canada K2K2A6
Attn: CICC
International --- --- Local DIGITAL subsidiary or
approved distributor
Internal Orders DTN: 261-2010
603-791-2010
Fax: 800-741-6970 U.S. Software Supply Business
Digital Equipment Corporation
8 Cotton Road
Nashua, NH 03063-1260


Chapter 1
Introduction to Remote Procedure Calls

1.1 Overview

High-level programming through open network computing remote procedure calls (ONC RPC) provides logical client-to-server communication for network application development---without the need to program most of the interface to the underlying network. With RPC, the client makes a remote procedure call that sends requests to the server, which calls a dispatch routine, performs the requested service, and sends back a reply before the call returns to the client.

RPC does not require the client to be knowledgeable about the underlying network. For example, a program can simply call a local C routine that returns the number of users on a remote system much like making a system call. You can make remote procedure calls between different processes on the same system.

1.2 The RPC Model

The remote procedure call model is similar to that of the local model, which works as follows:

  1. The caller places arguments to a procedure in a specific location (such as an argument variable).
  2. The caller temporarily transfers control to the procedure.
  3. When the caller gains control again, it obtains the results of the procedure from the specified location.
  4. The caller then continues program execution.

As Figure 1-1 shows, the remote procedure call is similar to the local model, in that one thread of control logically winds through two processes---that of the client (caller) and that of the server:

  1. The client process sends a call message to the server process and blocks (that is, waits) for a reply message. The call message contains the parameters of the procedure and the reply message contains the procedure results.
  2. When the client receives the reply message, it gets the results of the procedure.
  3. The client process then continues executing.

On the server side, a process is dormant---awaiting the arrival of a call message. When one arrives, the server process computes a reply that it then sends back to the requesting client. After this, the server process becomes dormant again.

Figure 1-1 shows a synchronous RPC call, in which only one of the two processes is active at a given time. The remote procedure call hides the details of the network transport. However, the RPC protocol does not restrict the concurrency model. For example, RPC calls may be asynchronous so the client can do another task while waiting for the reply from the server. Another possibility is that the server could create a task to process a certain type of request automatically, freeing it to service other requests. Although RPC provides a way to avoid programming the underlying network transport, it still allows this where necessary.

Figure 1-1 Basic Network Communication with Remote Procedure Call



1.3 RPC Procedure Versions

Each RPC procedure is defined uniquely by program and procedure numbers. The program number specifies a group of related remote procedures, each of which has a different procedure number. Each program also has a version number so, when a minor change is made to a remote service (adding a new procedure, for example), a new program number does not have to be assigned. When you want to call a procedure to find the number of remote users, you must know the appropriate program, version, and procedure numbers to use to contact the service. You can find this information in several places. On UNIX systems, the /etc/rpc file lists some RPC programs and the RPCINFO command lists the registered RPC programs and corresponding version numbers running on a particular system. On OpenVMS systems, the UCX SHOW PORTMAPPER command serves the same purpose as the RPCINFO command.

Typically, a service provides a protocol description so you can write client applications that call the service. The RPC Administrator at Sun Microsystems, Inc. has a list of programs that have been registered with Sun (that is, have received port numbers from them), but you can write your own local RPC programs. Knowing the program and procedure numbers is useful only if the program is running on a system to which you have access.

1.4 Using Portmapper to Determine the Destination Port Number of RPC Packets

The UCX software starts the Portmapper network service when it receives the first network request for the Portmapper port. Interaction between RPC programs and the Portmapper occurs as follows:

  1. After the system manager starts the Portmapper, it listens for UDP and TCP requests on port 111 of the host system.
  2. When a RPC server program activates on a system, it registers itself with its local Portmapper. The Portmapper software keeps a table of all registered services.
  3. To access the services available on a system, RPC client programs send RPC call messages to a system's Portmapper specifying the program and version number with which they wish to communicate.
  4. The Portmapper program examines its local cache of registered RPC servers. If the server is registered, then the Portmapper uses an RPC reply message to return the port number that the RPC client program should use to communicate with the RPC server.
  5. The RPC client program then uses the provided port number in all subsequent RPC calls.

Refer to the Digital TCP/IP Services for OpenVMS Management manual for more information about the Portmapper service.

1.4.1 Portmapper Notes for UCX

The Portmapper service on UCX differs from Portmapper software on other hosts in the following ways:

1.4.2 Displaying Registered RPC Servers

You can display current RPC registration information known to the Portmapper program. On UNIX systems use the rpcinfo command. On OpenVMS systems use the UCX SHOW PORTMAPPER command. The rpcinfo or UCX SHOW PORTMAPPER commands can also find the RPC services registered on a specific host and report their port numbers and the transports for which the services are registered. For more information, see the Digital TCP/IP Services for OpenVMS Management manual.

1.5 RPC Independence from Transport Protocol

The RPC protocol is concerned only with the specification and interpretation of messages; it is independent of transport protocols because it needs no information on how a message is passed among processes.

Also, RPC does not implement any kind of reliability; the application itself must be aware of the transport protocol type underlying RPC. With a reliable transport, such as TCP/IP, the application need not do much else. However, an application must use its own retransmission and timeout policy if it is running on top of an unreliable transport, such as UDP/IP.

Because of transport independence, the RPC protocol does not actively interpret anything about remote procedures or their execution. Instead, the application infers required information from the underlying protocol (where such information should be specified explicitly). For example, if RPC is running on top of an unreliable transport (such as UDP/IP) and the application retransmits RPC messages after short timeouts, and if the application receives no reply, then it can infer only that a certain procedure was executed zero or more times. If it receives a reply, then the application infers that the procedure was executed at least once.

With a reliable transport, such as TCP/IP, the application can infer from a reply message that the procedure was executed exactly once, but if it receives no reply message, it cannot assume the remote procedure was not executed.


Note

Even with a connection-oriented protocol such as TCP, an application still needs timeouts and reconnection procedures to handle server crashes.

ONC RPC is currently supported on both UDP/IP and TCP/IP transports. The selection of the transport depends on the application requirements. The UDP transport, which is connectionless, is a good choice if the application has the following characteristics:

TCP (connection-oriented) is a good transport choice if the application has any of the following characteristics:

1.6 External Data Representation (XDR)

RPC can handle arbitrary data structures, regardless of the byte order or structure layout convention on a particular system. It does this by converting them to a network standard called external data representation (XDR) before sending them over the network. XDR is a system-independent description and encoding of data that can communicate between diverse systems, such as a VAX, Sun workstation, IBM PC, or CRAY.

Converting from a particular system representation to XDR format is called serializing; the reverse process is deserializing.

1.7 Assigning Program Numbers

Program numbers are assigned in groups of 0x20000000 according to the following chart:
0x00000000--- 0x1fffffff Defined by Sun Microsystems
0x20000000--- 0x3fffffff Defined by user
0x40000000--- 0x5fffffff Transient
0x60000000--- 0x7fffffff Reserved
0x80000000--- 0x9fffffff Reserved
0xa0000000--- 0xbfffffff Reserved
0xc0000000--- 0xdfffffff Reserved
0xe0000000--- 0xffffffff Reserved

Sun Microsystems administers the first range of numbers, which should be identical for all ONC RPC users. An ONC RPC application for general use should have an assigned number in this first range. The second range of numbers is for specific, user-defined customer applications, and is primarily for debugging new programs. The third, called the Transient group, is reserved for applications that generate program numbers dynamically. The final groups are reserved for future use, and are not used.

To register a protocol specification, send a request by network mail to rpc@sun.com, or write to:

               RPC Administrator 
               Sun Microsystems 
               2550 Garcia Ave. 
               Mountain View, CA 94043 

Include a compilable RPCGEN .X file describing your protocol. You will then receive a unique program number. See Chapter 2 for more information about RPCGEN .X files.


Chapter 2
Writing RPC Applications with the RPCGEN Protocol Compiler

2.1 The RPCGEN Protocol Compiler

The RPCGEN protocol compiler accepts a remote program interface definition written in RPC language, which is similar to C. It then produces C language output consisting of: client skeleton routines, server skeleton routines, XDR filter routines for both arguments and results, a header file that contains common definitions, and optionally, dispatch tables that the server uses to invoke routines that are based on authorization checks.

The client skeleton interface to the RPC library hides the network from the client program, and the server skeleton hides the network from the server procedures invoked by remote clients. You compile and link output files from RPCGEN as usual. The server code generated by RPCGEN supports INETd. You can start the server via INETd or at the command line.

You can write server procedures in any language that has system calling conventions. To get an executable server program, link the server procedure with the server skeleton from RPCGEN. To create an executable client program, write an ordinary main program that makes local procedure calls to the client skeletons, and link the program with the client skeleton from RPCGEN. If necessary, the RPCGEN options enable you to suppress skeleton generation and specify the transport to be used by the server skeleton.

The RPCGEN protocol compiler helps to reduce development time in the following ways:

Refer to the RPCGEN command description at the end of this chapter for more information about programming applications that use remote procedure calls or for writing XDR routines that convert procedure arguments and results into their network format (or vice versa). For a discussion of RPC programming without RPCGEN, see Chapter 3.

2.2 Simple Example: Using RPCGEN to Generate Client and Server RPC Code

This section shows how to convert a simple routine ---one that prints messages to the system console on a single system (OPCOM on OpenVMS)---to an ONC RPC application that runs remotely over the network. To do this, the RPCGEN protocol compiler is used to generate client and server RPC code. Example 2-1 (see file SYS$EXAMPLES:[UCX.RPC]PRINTMSG.C) shows the routine before conversion.

Compile and run the program shown in the example (you will need OPER privileges):

$ CC/DECC PRINTMSG 
$ LINK PRINTMSG 
$ MCR SYS$DISK:[]PRINTMSG "Red rubber ball" 
%%%%%%%%%%%  OPCOM  27-SEP-1995 14:39:22.59  %%%%%%%%%%% 
Message from user GEORGE on BOSTON 
Message Delivered! 
$ 


Next | Contents