Order Number: AA--Q06VE--TE

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 Alpha Versions 7.1, 7.2
OpenVMS VAX Versions 7.1, 7.2

Software Version: DIGITAL TCP/IP Services
for OpenVMS Version 5.0

Compaq Computer Corporation Houston, Texas

Compaq Computer 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 Compaq or an authorized sublicensor.

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

© Compaq Computer Corporation 1999. All rights reserved.

The following are trademarks of Compaq Computer Corporation: ACMS, Alpha, Compaq, DDCMP, DEC, DECdtm, DECnet, DECNIS, DECserver, DECsystem, DIGITAL, DIGITAL UNIX, DNA, InfoServer, LAT, OpenVMS, PATHWORKS, POLYCENTER, ULTRIX, VAX, VAXstation, VMS, and the Compaq 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.

Macintosh is a registered trademark of Apple Computer, Inc.

MS-DOS is a registered trademark of Microsoft Corporation.

MultiNet is a registered trademark of Process Software Corporation.

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

OSI is a registered trademark of CA Management, Inc.

PostScript is a registered trademark of Adobe Systems Incorporated.

SCO is a trademark of Santa Cruz Operations, Inc.

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

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.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents

Index

The DIGITAL TCP/IP Services for OpenVMS product is Compaq's implementation of the TCP/IP networking protocol suite and internet services for OpenVMS Alpha and OpenVMS VAX systems.

A layered software product, DIGITAL TCP/IP Services for OpenVMS provides a comprehensive suite of functions and applications that support industry-standard protocols for heterogeneous network communications and resource sharing.

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 eperienced programmers who want to write network applications using ONC RPC without needing to know about the underlying network.

New and Changed Features

DIGITAL TCP/IP Services for OpenVMS Version 5.0 provides a new kernel based on the IPv4 kernel ported from Compaq's DIGITAL UNIX Version 4.0D.¹

Other new features include:

• Dynamic Host Configuration Protocol (DHCP) that allows the system manager to provide dynamic allocation of IP addresses from a single OpenVMS host.
• Gateway routing daemon (GATED) server and a comprehensive suite of interior and exterior routing protocols that offer advanced routing options.
• Classless Inter-domain routing (CIDR) that allows networks to be built with variable-length subnetworks.
• PathMTU discovery, a mechanism that allows an IP host to determine the most efficient packet size for use on a particular path between the source to the destination host.
• UNIX management utilities to assist with the management of OpenVMS systems in a mixed UNIX and OpenVMS environment.
• New implementations of NTP, SNMP, and BIND.
• Improved online help and a new message database for use with the OpenVMS Help Message utility (MSGHLP).

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 Documentation

Table 1 lists the manuals available with this version of DIGITAL TCP/IP Services for OpenVMS.

Table 1 DIGITAL TCP/IP Services for OpenVMS Documentation

Manual	Contents
DIGITAL TCP/IP Services for OpenVMS Release Notes	This text file describes new features and changes to the software including installation, upgrade, configuration, and compatibility information. These notes also describe new and existing software problems and restrictions, and software and documentation corrections. Print this text file at the beginning of the installation procedure and read it before you install DIGITAL TCP/IP Services for OpenVMS.
DIGITAL TCP/IP Services for OpenVMS Installation and Configuration	This manual explains how to install and configure the DIGITAL TCP/IP Services for OpenVMS layered application product.
DIGITAL TCP/IP Services for OpenVMS User's Guide	This manual describes how to use the applications available with DIGITAL TCP/IP Services for OpenVMS such as remote file operations, e-mail, TELNET, TN3270, and network printing. This manual also explains how to use these services to communicate with systems on private internets or on the worldwide Internet.
DIGITAL TCP/IP Services for OpenVMS Management	This manual describes how to configure and manage the DIGITAL TCP/IP Services for OpenVMS product. Use this manual with the DIGITAL TCP/IP Services for OpenVMS Management Command Reference manual.
DIGITAL TCP/IP Services for OpenVMS Management Command Reference	This manual describes the DIGITAL TCP/IP Services for OpenVMS management commands. Use this manual with the DIGITAL TCP/IP Services for OpenVMS Management manual.
DIGITAL TCP/IP Services for OpenVMS ONC RPC Programming	This manual presents an overview of high-level programming using open network computing remote procedure calls (ONC RPC). This manual also describes the RPC programming interface and how to use the RPCGEN protocol compiler to create applications.
DIGITAL TCP/IP Services for OpenVMS System Services and C Socket Programming	This manual describes how to use the OpenVMS system services and C Socket programming interfaces to develop network-based applications.
DIGITAL TCP/IP Services for OpenVMS eSNMP Programming and Reference	This manual describes the Extensible Simple Network Management Protocol (eSNMP), the eSNMP application programming interface (API), and how to build additional subagents to manage vendor-specific equipment.

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

http://www.openvms.digital.com

You might find the Internetworking with TCP/IP: Principles, Protocols, and Architecture by Douglas Comer useful if you are looking for a comprehensive overview of the TCP/IP protocol suite.

Terminology

DIGITAL TCP/IP Services for OpenVMS Version 5.0 completes the change initiated several releases ago when the product name changed from "ULTRIX Connection (UCX)" to "DIGITAL TCP/IP Services for OpenVMS." To complete this change, the identifier "UCX" is replaced with "TCPIP" in the following cases:

• Registered product facility code
• Management command prompt
• All messages, examples, and banners
• All product file names and databases
• All logical names, except those retained for compatibility
• All associated product documentation

DIGITAL TCP/IP Services for OpenVMS is used to mean both:

• DIGITAL TCP/IP Services for OpenVMS Alpha
• DIGITAL TCP/IP Services for OpenVMS VAX

The auxiliary server is the DIGITAL TCP/IP Services for OpenVMS implementation of the UNIX internet daemon (inetd).

NFS is the DIGITAL TCP/IP Services for OpenVMS implementation of the NFS protocols, including the NFS server, the NFS client, and PC-NFS.

TN3270 means the TELNET client software that emulates IBM 3270 model terminals.

The term UNIX refers to the DIGITAL UNIX operating system. DIGITAL UNIX is fully compatible with Version 4.3 and Version 4.4 of the Berkeley Software Distribution (BSD).

Host and node both mean a system connected to an internet.

The term Internet refers to the global interconnection of networks, as defined by RFC 1208, which consists of large networks using TCP/IP to provide universal connectivity, reaching the Defense Advanced Projects Research Internet, MILNET, NSFnet, CERN, and many worldwide universities, government research labs, military installations, and business enterprises.

The term internet refers to private interconnected networks that use TCP/IP to connect together and function as one, virtual network.

Acronyms

The following acronyms are used throughout this manual:

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
UDP	User Datagram Protocol

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

Conventions

All IP addresses in this manual represent fictitious addresses. The following conventions apply to this manual.

Convention	Meaning
UPPERCASE TEXT	Indicates names of OpenVMS and DIGITAL TCP/IP Services for OpenVMS 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.
bold text	Indicates a new term.
italic text	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 the enclosed element is optional. You can enter as many as you want.
{ }	In command format descriptions, indicates you must enter at least one listed element. For readability, each element is either listed on a separate line or separated by vertical bars (|). Unless otherwise instructed, use a space to separate these elements when using them with commands.
...	Horizontal ellipsis points in examples indicate additional optional arguments have been omitted.
. . .	Vertical ellipsis points indicate omission of items from a code example or display example; the items are omitted because they are not important to the topic being discussed.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

How To Order Additional Documentation

Visit the OpenVMS Documentation World Wide Web site at the following URL to learn how to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

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

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 TCP/IP Services 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 TCP/IP Services

The Portmapper service on TCP/IP Services differs from Portmapper software on other hosts in the following ways:

• When an RPC server that is registered with the Portmapper exits, the Portmapper purges any registrations for that server program.
• An RPC process can only register or unregister its own Portmapper entries. Any attempt to remove a registration for another RPC server will fail.
• The Portmapper includes its own mappings (on the UDP and TCP port 111). These mappings are available using the pmap_getmaps routine.
• All data structures used for the RPC pmap_xxxx routines are identical to other RPC implementations with the exception of the two additional structures pmap_vms and pmaplist_vms. These structures include the field pm_pid which is the OpenVMS process ID.