![Content starts here](http://welcome.hp-ww.com/img/s.gif) |
Compaq TCP/IP Services for OpenVMS
Compaq TCP/IP Services for OpenVMS
ONC RPC Programming
Order Number:
AA--Q06VF--TE
April 2002
This manual presents an overview of high-level programming using open
network computing remote procedure calls (ONC RPCs). This manual also
describes the RPC programming interface and how to use the RPCGEN
protocol compiler to create applications.
Revision/Update Information:
This manual supersedes Compaq TCP/IP Services for OpenVMS ONC RPC Programming, Version 5.0.
Software Version:
Compaq TCP/IP Services for OpenVMS Version 5.3
Operating Systems:
OpenVMS Alpha Versions 7.2-2, 7.3 OpenVMS VAX Versions 7.2, 7.3
Compaq Computer Corporation Houston, Texas
© 2002 Compaq Information Technologies Group, L.P.
Compaq, the Compaq logo, Alpha, OpenVMS, Tru64, VAX, VMS, and the
Digital logo are trademarks of Compaq Information Technologies Group,
L.P. in the U.S. and/or other countries.
All other product names mentioned herein may be trademarks of their
respective companies.
Confidential computer software. Valid license from Compaq required for
possession, use, or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
Compaq shall not be liable for technical or editorial errors or
omissions contained herein. The information in this document is
provided "as is" without warranty of any kind and is subject to change
without notice. The warranties for Compaq products are set forth in the
express limited warranty statements accompanying such products. Nothing
herein should be construed as constituting an additional warranty.
ZK6528
This document is available on CD-ROM.
Preface
The Compaq TCP/IP Services for OpenVMS product is the Compaq implementation of the TCP/IP
networking protocol suite and internet services for OpenVMS Alpha and
OpenVMS VAX systems.
TCP/IP Services provides a comprehensive suite of functions and
applications that support industry-standard protocols for heterogeneous
network communications and resource sharing.
This Compaq TCP/IP Services for OpenVMS ONC RPC Programming manual presents an overview of high-level programming
using open network computing remote procedure calls (ONC RPCs). This
manual also describes the RPC programming interface and how to use the
RPCGEN protocol compiler to create applications.
See the Compaq TCP/IP Services for OpenVMS Installation and Configuration manual for information about installing,
configuring, and starting this product.
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
Table 1 lists the documents available with this version of
TCP/IP Services.
Table 1 TCP/IP Services Documentation
Manual |
Contents |
Compaq TCP/IP Services for OpenVMS Concepts and Planning
|
This manual provides conceptual information about TCP/IP networking on
OpenVMS systems, including general planning issues to consider before
configuring your system to use the TCP/IP Services software.
This manual also describes the manuals in the TCP/IP Services
documentation set and provides a glossary of terms and acronyms for the
TCP/IP Services software product.
|
Compaq TCP/IP Services for OpenVMS Release Notes
|
The release notes provide version-specific information that supersedes
the information in the documentation set. The features, restrictions,
and corrections in this version of the software are described in the
release notes. Always read the release notes before installing the
software.
|
Compaq TCP/IP Services for OpenVMS Installation and Configuration
|
This manual explains how to install and configure the TCP/IP Services
product.
|
Compaq TCP/IP Services for OpenVMS User's Guide
|
This manual describes how to use the applications available with
TCP/IP Services such as remote file operations, email, TELNET, TN3270, and
network printing. This manual explains how to use these services to
communicate with systems on private internets or on the worldwide
Internet.
|
Compaq TCP/IP Services for OpenVMS Management
|
This manual describes how to configure and manage the TCP/IP Services
product.
Use this manual with the Compaq TCP/IP Services for OpenVMS Management Command Reference manual.
|
Compaq TCP/IP Services for OpenVMS Management Command Reference
|
This manual describes the TCP/IP Services management commands.
Use this manual with the Compaq TCP/IP Services for OpenVMS Management manual.
|
Compaq TCP/IP Services for OpenVMS Management Command Quick Reference Card
|
This reference card lists the TCP/IP management commands by component
and describes the purpose of each command.
|
Compaq TCP/IP Services for OpenVMS UNIX Command Reference Card
|
This reference card contains information about commonly performed
network management tasks and their corresponding TCP/IP management and
Compaq Tru64 UNIX command formats.
|
Compaq 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 RPCs). This manual also
describes the RPC programming interface and how to use the RPCGEN
protocol compiler to create applications.
|
Compaq TCP/IP Services for OpenVMS Sockets API and System Services Programming
|
This manual describes how to use the Sockets API and OpenVMS system
services to develop network applications.
|
Compaq TCP/IP Services for OpenVMS SNMP Programming and Reference
|
This manual describes the Simple Network Management Protocol (SNMP) and
the SNMP application programming interface (eSNMP). It describes the
subagents provided with TCP/IP Services, utilities provided for
managing subagents, and how to build your own subagents.
|
Compaq TCP/IP Services for OpenVMS Tuning and Troubleshooting
|
This manual provides information about how to isolate the causes of
network problems and how to tune the TCP/IP Services software for the best
performance.
|
Compaq TCP/IP Services for OpenVMS Guide to IPv6
|
This manual describes the IPv6 environment, the roles of systems in
this environment, the types and function of the different IPv6
addresses, and how to configure TCP/IP Services to access the 6bone
network.
|
For additional information about Compaq OpenVMS products and
services, access the Compaq website at the following location:
http://www.openvms.compaq.com/
|
For a comprehensive overview of the TCP/IP protocol suite, you might
find the book Internetworking with TCP/IP: Principles, Protocols,
and Architecture, by Douglas Comer, useful.
Reader's Comments
Compaq welcomes your comments on this manual. Please send comments to
either of the following addresses:
Internet
|
openvmsdoc@compaq.com
|
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 following World Wide Web address for information about how to
order additional documentation:
http://www.openvms.compaq.com/
|
Click Documentation under Quick Links on the left side
of the page.
If you need help deciding which documentation best meets your needs,
call 800-282-6672.
Conventions
The name TCP/IP Services means both:
- Compaq TCP/IP Services for OpenVMS Alpha
- Compaq TCP/IP Services for OpenVMS VAX
The name UNIX refers to the Compaq Tru64 UNIX operating system.
The following conventions are used in this manual. In addition, please
note that all IP addresses are fictitious.
Ctrl/
x
|
A sequence such as Ctrl/
x indicates that you must hold down the key labeled Ctrl while
you press another key or a pointing device button.
|
PF1
x
|
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
button.
|
[Return]
|
In examples, a key name enclosed in a box indicates that you press a
key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as
brackets, rather than a box.
|
...
|
A horizontal ellipsis in examples indicates one of the following
possibilities:
- Additional optional arguments in a statement have been omitted.
- The preceding item or items can be repeated one or more times.
- Additional parameters, values, or other information can be entered.
|
.
.
.
|
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
|
( )
|
In command format descriptions, parentheses indicate that you must
enclose choices in parentheses if you specify more than one.
|
[ ]
|
In command format descriptions, brackets indicate optional choices. You
can choose one or more items or no items. Do not type the brackets on
the command line. However, you must include the brackets in the syntax
for OpenVMS directory specifications and for a substring specification
in an assignment statement.
|
|
|
In command format descriptions, vertical bars separate choices within
brackets or braces. Within brackets, the choices are optional; within
braces, at least one choice is required. Do not type the vertical bars
on the command line.
|
{ }
|
In command format descriptions, braces indicate required choices; you
must choose at least one of the items listed. Do not type the braces on
the command line.
|
bold text
|
This typeface represents the introduction of a new term. It also
represents the name of an argument, an attribute, or a reason.
|
italic text
|
Italic text indicates important information, complete titles of
manuals, or variables. Variables include information that varies in
system output (Internal error
number), in command lines (/PRODUCER=
name), and in command parameters in text (where
dd represents the predefined code for the device type).
|
UPPERCASE TEXT
|
Uppercase text indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
|
Monospace text
|
Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the
following elements: keywords, the names of independently compiled
external functions and files, syntax summaries, and references to
variables or identifiers introduced in an example.
|
-
|
A hyphen at the end of a command format description, command line, or
code line indicates that the command or statement continues on the
following line.
|
numbers
|
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
indicated.
|
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:
- The caller places arguments to a procedure in a specific location
(such as an argument variable).
- The caller temporarily transfers control to the procedure.
- When the caller gains control again, it obtains the results of the
procedure from the specified location.
- 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:
- 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.
- When the client receives the reply message, it gets the results of
the procedure.
- 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 SHOW PORTMAPPER management
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 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:
- After the system manager starts the Portmapper, it listens for UDP
and TCP requests on port 111 of the host system.
- When an RPC server program activates on a system, it registers
itself with its local Portmapper. The Portmapper software keeps a table
of all registered services.
- 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.
- 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.
- The RPC client program then uses the provided port number in all
subsequent RPC calls.
Refer to the Compaq 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.
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 SHOW PORTMAPPER management command.
The
rpcinfo
or 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
Compaq TCP/IP Services for OpenVMS Management Command Reference 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:
- The procedures are idempotent; that is, the same procedure can be
executed more than once without any side effects. For example, reading
a block of data is idempotent; creating a file is not.
- The size of both the arguments and results is smaller than the UDP
packet size of 8K bytes.
- The server is required to handle as many as several hundred
clients. The UDP server can do so because it does not retain any
information about the client state. By contrast, the TCP server holds
state information for each open client connection and this limits its
available resources.
TCP (connection-oriented) is a good transport choice if the application
has any of the following characteristics:
- The application needs a reliable underlying transport.
- The procedures are non-idempotent.
- The size of either the arguments or the results exceeds 8K bytes.
|