11. ONC RPC Fundamentals

Introduction

TCPware provides two sets of ONC RPC Services for network programming:

• ONC RPC Services to be used with the DEC C Socket Library for DEC C

• ONC RPC Services to be used with TCPware's Socket Library for VAX C or DEC C

This chapter is for RPC programmers. It provides basic information you need to know before using ONC RPC Services to write distributed applications, including:

• What ONC RPC Services are

• What components are in ONC RPC Services

• How ONC RPC clients and servers communicate

• Important ONC RPC concepts and terms

What Are ONC RPC Services?

ONC RPC Services are a set of software development tools that allow you to build distributed applications on OpenVMS systems. These services are part of TCP-OpenVMS.

TCPware provides two types of ONC RPC Services:

– ONC RPC used with VAX C and the TCPware Socket Library

– RPC XDR used with DEC C and the DEC C Socket Library

The bold letters in the above list show the conventions this book uses to distinguish between the two services.

TCPware Implementation

ONC RPC Services are based on the Open Network Computing Remote Procedure Call (RPC) protocols developed by Sun Microsystems, Inc. These protocols are defined in the following Requests for Comments (RFCs):

• RPC: Remote Procedure Call Protocol Specification, Version 2 (RFC 1057)

• XDR: External Data Representation Standard (RFC 1014)

Distributed Applications

A distributed application executes different parts of its programs on different hosts in a network. Computers on the network share the processing workload, with each computer performing the tasks for which it is best equipped.

For example, a distributed database application might consist of a central database running on a VAX server and numerous client workstations. The workstations send requests to the server. The server carries out the requests and sends the results back to the workstations. The workstations use the results in other modules of the application.

RPCs allow programs to invoke procedures on remote hosts as if the procedures were local. ONC RPC Services hides the networking details from the application.

ONC RPC Services facilitates distributed processing because it relieves the application programmer of performing low-level network tasks such as establishing connections, addressing sockets, and converting data from one machine's format to another.

Components of ONC RPC Services

ONC RPC Services comprises the following components:

Run-time libraries (RTLs)

RPCGEN compiler

Port Mapper

RPCINFO command

Run-Time Libraries (RTLs)

XDR:  ONC RPC Services provides a single shareable RTL. The library contains:

• ONC RPC client and server routines

• XDR routines

ONC:  ONC RPC Services provides two shareable RTLs, one for D_float numbers and one for G_float numbers. Both libraries contain:

• ONC RPC client and server routines

• XDR routines

• Additional management routines that are unique to ONC RPC Services

The ONC RPC RTL Management Routines, Chapter 16, and the chapters that follow it describe the RTLs in detail.

RPCGEN Compiler

RPCGEN is a compiler that creates the network interface portion of a distributed application. It effectively hides from the programmer the details of writing and debugging low-level network interface code. The RPCGEN Compiler, Chapter 14 , describes how to use RPCGEN.

Port Mapper

The Port Mapper helps ONC RPC client programs connect to ports that are being used by ONC RPC servers. A Port Mapper runs on each host that implements ONC RPC Services. These steps summarize how the Port Mapper works:

1. ONC RPC servers register with the Port Mapper by telling it which ports they are using.

2. When an ONC RPC client needs to reach a particular server, it supplies the Port Mapper with the numbers of the remote program and program version it wants to reach. The client also specifies a transport protocol (UDP or TCP). (Identifying Remote Programs and Procedures provides details on these numbers.)

3. The Port Mapper provides the correct port number for the requested service. This process is called binding.

Once binding has taken place, the client does not have to call the Port Mapper for subsequent calls to the same server. A service can register for different ports on different hosts. For example, a server can register for port 800 on Host A and port 1000 on Host B. The Port Mapper is itself an ONC RPC server and uses the ONC RPC RTL. It uses the UDPA and TCPA protocols for transports. The Port Mapper plays an important role in disseminating messages for broadcast RPC. The Port Mapper is part of the Network Control Process (NETCP). See the Broadcast RPC section for details.

RPCINFO Command

Use the RPCINFO command to:

• Request a listing of all programs that are registered with the Port Mapper

• Call the null routine of any program

You enter this command at the DCL prompt. (See RPCINFO Utility in Chapter 13, Building Distributed Applications, for details.)

Client-Server Relationship

In ONC RPC, the terms client and server do not describe particular hosts or software entities. Rather, they describe the roles of particular programs in a given transaction. Every ONC RPC transaction has a client and a server. The client is the program that calls a remote procedure; the server is the program that executes the procedure on behalf of the caller.

A program can be a client or a server at different times. The program's role merely depends on whether it is making the call or servicing the call.

External Data Representation (XDR)

External Data Representation (XDR) is a standard that solves the problem of converting data from one machine's format to another.

ONC RPC Services uses the XDR data description language to describe and encode data. Although similar to C language, XDR is not a programming language. It merely describes the format of data, using implicit typing. XDR: External Data Representation Standard (RFC 1014) defines the XDR language.

ONC RPC Processing Flow

Remote and local procedure calls share some similarities. In both cases, a calling process makes arguments available to a procedure. The procedure uses the arguments to compute a result, then returns the result to the caller. The caller uses the results of the procedure and resumes execution.

Figure 2-1 shows the underlying processing that makes a remote procedure call different from a local call.

The following steps describe the processing flow during a remote procedure call:

2 The client program passes arguments to the client stub procedure. (See Chapter 14, RPCGEN Compiler, for details on how to create stubs.)

2 The client stub marshals the data by:

• Calling the XDR routines to convert the arguments from the local representation to XDR

• Placing the results in a packet

Using ONC RPC RTL calls, the client stub sends the packet to the UDP or TCP layer for transmission to the server.

3 The packet travels on the network to the server, up through the layers to the server stub.

4 The server stub un-marshals the packet by converting the arguments from XDR to the local representation. Then it passes the arguments to the server procedure.

Figure 12-1     ONC RPC Processing Flow

Local Calls versus Remote Calls

This section describes some of the ways in which local and remote procedure calls handle system crashes, errors, and call semantics.

Handling System Crashes

Local procedure calls involve programs that reside on the same host. Therefore, the called procedure cannot crash independently of the calling program.

Remote procedure calls involve programs that reside on different hosts. Therefore, the client program does not necessarily know when the remote host has crashed.

Handling Errors

If a local procedure call encounters a condition that prevents the call from executing, the local operating system usually tells the calling procedure what happened.

If a remote procedure call cannot be executed for some reason (e.g., errors occur on the network or remote host), the client might not be informed of what happened. You may want to build a signaling or condition-handling mechanism into the application to inform the client of such errors.

ONC RPC returns certain types of errors to the client, such as those that occur when it cannot decode arguments. The RPC server must be able to return processing-related errors, such as those that occur when arguments are invalid, to the client. However, the RPC server may not return errors during batch processing or broadcast RPC.

Call Semantics

Call semantics determine how many times a procedure executes.

Local procedures are guaranteed to execute once and only once.

Remote procedures have different guarantees, depending on which transport protocol is used.

XDR:  The TCP transport guarantees execution once and only once as long as the server does not crash. The UDP transport guarantees execution at least once. It relies on the XID cache to prevent a remote procedure from executing multiple times.

ONC:  The TCP and TCPA transports guarantee execution once and only once as long as the server does not crash. The UDP and UDPA transports guarantee execution at least once. They rely on the XID cache to prevent a remote procedure from executing multiple times.

See XID Cache for details on the XID cache.

Programming Interface

The ONC RPC RTL is the programming interface to RPC. You may think of this interface as containing multiple levels.

The ONC RPC RTL reference chapters describe each routine.

The sample programs listed in the ONC RPC Sample Programs, Chapter 20, show how ONC RPC routines are used at each level.

High-Level Routines

The higher-level RPC routines provide the simplest RPC programming interface. These routines call lower-level RPC routines using default arguments, effectively hiding the networking details from the application programmer.

When you use high-level routines, you sacrifice control over such tasks as client authentication, port registration, and socket manipulation, but you gain the benefits of using a simpler programming interface. Programmers using high-level routines can usually develop applications faster than they can using low-level RPC routines.

You can use the RPCGEN compiler only when you use the highest-level RPC programming interface.

Mid-Level Routines

The mid-level routines provide the most commonly used RPC interface. They give the programmer some control over networking tasks, but not as much control as the low-level routines permit.

For example, you can control memory allocation, authentication, ports, and sockets using mid-level routines.

The mid-level routines require you to know procedure, program, and version numbers, as well as input and output types. Output data is available for future use. You can use the registerrpc and callrpc routines.

Low-Level Routines

The low-level routines provide the most complicated RPC interface, but they also give you the most control over networking tasks such as client authentication, port registration, and socket manipulation. These routines are used for the most sophisticated distributed applications.

ONC:  These routines also allow you to use the TCPA and UDPA transports, as described below.

Transport Protocols

XDR and ONC RPC Services use the transport protocols listed in Table 12-1. The RPC client and server must use the same transport protocol for a given transaction.

Table 12-1     XDR and ONC RPC Transport Protocols

Protocols	Characteristics
UDP (XDR and ONC) UDPA (ONC only)	Unreliable datagram service Connectionless Used for broadcast RPC Maximum broadcast message size in either direction on an Ethernet line: 1500 Execution is guaranteed at least once (see XID Cache) Calls cannot be processed in batch
TCP (XDR and ONC) TCPA (ONC only)	Reliable Connection-oriented Can send an unlimited number of bytes per RPC call Execution is guaranteed once and only once Calls can be processed in batch No broadcasting

Note! XDR:  You must use the DEC C Socket Library with ONC RPC Services.

Note! ONC:  You must use the TCPware Socket Library with ONC RPC Services.

XID Cache

The XID cache stores responses the server has sent. When the XID cache is enabled, the server does not have to recreate every response to every request. Instead, the server can use the responses in the cache. Thus, the XID cache saves computing resources and improves the performance of the server.

XDR:  Only the UDP transports can use the XID cache. The reliability of the TCP transport generally makes the XID cache unnecessary. UDP is inherently unreliable.

ONC:  Only the UDP, UDPA, and TCPA transports can use the XID cache. The reliability of the TCP and TCPA transports generally makes the XID cache unnecessary. UDP is inherently unreliable.

Table 12-2 shows how the XID caches differ for the UDP and UDPA/TCPA transports.

Table 12-2     XID Cache Differences
UDP Transport	UDPA/TCPA Transports
Places every response in the XID cache	Allows the server to specify which responses are to be cached, using the svcudpa_enablecache and svctcpa_enablecache routines
XID cache cannot be disabled	Requires you to disable the XID cache after use

Cache Entries

Each entry in the XID cache contains:

• The encoded response that was sent over the network

• The internet address of the client that sent the request

• The transaction ID that the client assigned to the request

Cache Size

You determine the size of the XID cache. Consider these factors:

• How many clients are using the server.

• Approximately how long the cache should save the responses.

• How much memory you can allocate. Each entry requires about 8Kbytes.

The more active the server is, the less time the responses remain in the cache.

Execution Guarantees

As explained earlier in Local Calls Versus Remote Calls, remote procedures have different execution guarantees, depending on which transport protocol is used. The XID cache affects the execution guarantee.

XDR:  The TCP transport guarantees execution once and only once as long as the server does not crash. The UDP transport guarantees execution at least once. If the XID cache is enabled, a UDP procedure is unlikely to execute more than once.

ONC:  The TCP and TCPA transports guarantee execution once and only once as long as the server does not crash. The UDP and UDPA transports guarantee execution at least once. If the XID cache is enabled, a UDP or UDPA procedure is unlikely to execute more than once.

Enabling XID Cache

XDR:  Use the svcudp_enablecache routine to enable the XID cache. This routine is described in the ONC RPC RTL reference chapters.

ONC:  Use the svcudp_enablecache,svcudpa_enablecache and svctcpa_enablecache routines to enable the XID cache. Use the svcudpa_freecache and svctcpa_freecache routines to disable the cache for a UDPA/TCPA server. These routines are described in the ONC RPC RTL reference chapters.

Not enabling the XID cache saves memory.

Active Cache

The active cache maintains a list of active requests that the server is working on. All UDPA servers use the active cache. A UDP server does not need an active cache because it can work on only one request at a time.

XDR:  TCP servers do not need an active cache because they do not receive duplicate requests.

ONC:  TCP and TCPA servers do not need an active cache because they do not receive duplicate requests. When a UDPA server receives a request, it searches the active cache for a match. If no match is found, the server places the request in the active cache and processes it. If a match is found, the server ignores the new request because it is already processing the request. When the server sends a response, it removes the request from the active cache and may add it to the XID cache.

Broadcast RPC

Broadcast RPC allows the client to send a broadcast call to all Port Mappers on the network and wait for multiple replies from ONC RPC servers.

For example, a host might use a broadcast RPC message to inform all hosts on a network of a system shutdown.

Table 12-3 shows the differences between normal RPC and broadcast RPC.

Table 12-3     Normal RPC vs Broadcast RPC
Normal RPC	Broadcast RPC
Client expects one answer	Client expects many answers
Can use TCP or UDP	Requires UDP
Server always responds to errors	Server does not respond to errors; Client does not know when errors occur
Port Mapper is desirable, but not required if you use fixed port numbers	Requires Port Mapper services

Broadcast RPC sends messages to only one port–the Port Mapper port–on every host in the network. On each host, the Port Mappers pass the messages to the target ONC RPC server. The servers compute the results and send them back to the client. See Broadcast RPC Sample Programs in Chapter 20, ONC RPC Sample Programs, for a list of sample programs using broadcast RPC.

ONC RPC Batch Facilities

Normally, an ONC RPC client sends a remote procedure call, stops processing, and waits for the server to reply. Some remote procedure calls, however, do not require a reply or acknowledgment. In these cases, the client wastes time waiting for the server to respond.

ONC RPC batch facilities solve this problem by allowing the client to send many remote procedure calls without waiting for replies.

ONC RPC Services performs batching by placing the client's messages to a particular server sequentially in a pipeline. The server knows it does not have to respond to these messages. The client sends a normal RPC call at the end of the batch sequence to "flush" the pipeline and let the server know there are no more batch calls.

Batching decreases the amount of communication overhead used by the client and server. The client can place many call messages in a buffer and send them to the server in one system call. The client can generate new calls while the server processes previous calls.

Batch Requirements

All ONC RPC batch calls must meet these requirements (see Batch RPC Sample Programs in Chapter 20, ONC RPC Sample Programs, for an example of batching):

• Specify that the result of the call is to be decoded by the XDR routine at address zero

• Have a timeout of zero

• Use the TCP transport

Identifying Remote Programs and Procedures

The ONC RPC client must uniquely identify the remote procedure it wants to reach. Therefore, all remote procedure calls must contain these three fields:

• A remote program number

• The version number of the remote program

• A remote procedure number

Remote Program Numbers

A remote program is a program that implements at least one remote procedure. Remote programs are identified by numbers that you assign during application development. Use Table 12-4 to determine which program numbers are available. The numbers are in groups of hexadecimal 20000000.

Table 12-4     Remote Program Numbers
Range	Purpose
0 to 1FFFFFFF	Defined and administered by Sun Microsystems. Should be identical for all sites. Use only for applications of general interest to the Internet community.
20000000 to 3FFFFFFF	Defined by the client application program. Site-specific. Use primarily for new programs.
40000000 to 5FFFFFFF	Use for applications that generate program numbers dynamically.
60000000 to FFFFFFFF	Reserved for the future. Do not use.

Remote Version Numbers

Multiple versions of the same program may exist on a host or network. Version numbers distinguish one version of a program from another. Each time you alter a program, remember to increment its version number.

Remote Procedure Numbers

A remote program may contain many remote procedures. Remote procedures are identified by numbers that you assign during application development. Follow these guidelines when assigning procedure numbers:

• Use 1 for the first procedure in a program. (Procedure 0 should do nothing and require no authentication to the server.)

• For each additional procedure in a program, increment the procedure number by one.

Additional Terms

Before writing RPC applications, you should be familiar with the terms in Table 12-5. 

Table 12-5     Additional Terms
XDR and ONC
Term	Definition
Channel	An OpenVMS term referring to a logical path that connects a process to a physical device, allowing the process to communicate with that device. A process requests OpenVMS to assign a channel to a device. Refer to HP’s documentation for more information on channels.
Client handle	Information that uniquely identifies the server to which the client is sending the request. Consists of the server's host name, program number, program version number, and transport protocol. See the following routines in the ONC RPC RTL Client Routines, Chapter 16:

XDR		ONC
Term	Definition	Term	Definition
Client handle	authnone_create authunix_create authunix_create_default clnt_create clnttcp_create clntudp_create clnt_perror	Client handle	authnone_create authunix_create authunix_create_default clnt_create clnttcp_create clntudp_create clnt_call clnt_control clnt_destroy clnt_freeres clnt_geterr clnt_perror

XDR and ONC
Term	Definition
Port	An abstract point through which a datagram passes from the host layer to the application layer protocols.

XDR
Term	Definition
Server handle	Information that uniquely identifies the server. Content varies according to the transport being used. See the following routines in Chapter 18, ONC RPC RTL Server Routines: svcudp_create             svctcp_create           svc_destroy svc_freeargs               svc_getargs               svc_getcaller svc_register                svc_sendreply           svcerr_ routines

ONC
Term	Definition
Server handle	Information that uniquely identifies the server. Content varies according to the transport being used. See the following routines in Chapter 18, ONC RPC RTL Server Routines: svcudp_create               svcudpa_create              svctcp_create svctcpa_create              svc_destroy                    svc_freeargs svc_getargs                   svc_register                    svc_sendreply svcerr_ routines

XDR and ONC
Term	Definition
Socket	An abstract point through which a process gains access to the Internet. A process must open a socket and bind it to a specific destination. Note: The TCPware Socket Library must be used with ONC RPC Services.