This chapter is for RPC programmers. It introduces RPC Run-Time Library (RTL) conventions and documents the management routines in the RPC RTL. These routines are the programming interface to RPC.
There are two types of services with RTL:
· ONCRPC used with VAX C and the TCPware Socket Library
· RPCXDR used with DEC C and the HP Socket Library
The bold letters in the above list show the conventions this book uses to distinguish between the two services.
The RPC RTL contains:
· RPC management routines
· DEC C: RPC client and server routines for the UDP and TCP transport layers
· VAX C: RPC client and server routines for the UDP, UDPA, TCP, and TCPA transport layers
· DEC C: On VAX, Alpha and I64 systems, RPC provides a single shareable image accessed via the UCX$RPCXDR_SHR logical. This shareable image contains routines for all of the DEC C floating-point types. The correct routines will automatically be called based on the compiler options used to compile the RPC application. See the DEC C documentation for how to use the floating-point compiler options.
· VAX C: On VAX systems, RPC provides two shareable RTLs:
o A D_float library, for standard double-precision real numbers between 10-38 and 10+38. This library is in the SYS$SHARE:TCPWARE_RPCLIB_SHR.EXE file.
o A G_float library, for double-precision real numbers between 10-308 and 10+308. This library is in the SYS$SHARE:TCPWARE_RPCLIBG_SHR.EXE file.
· DEC C: On Alpha and I64 systems, ONC RPC provides three shareable RTLs:
o A D_float library, for standard double-precision real numbers between 10-38 and 10+38. This library is in the SYS$SHARE:TCPWARE_RPCLIBD_SHR.EXE file.
o A G_float library, for double-precision real numbers between 10-308 and 10+308. This library is in the SYS$SHARE:TCPWARE_RPCLIB_SHR.EXE file.
o A T_float library, for IEEE double-precision real numbers between 10-308 and 10+308. This library is in the SYS$SHARE:TCPWARE_RPCLIBT_SHR.EXE file.
· VAX C: Invoke these libraries by using the appropriate qualifiers when you compile your application programs. See your HP VAX documentation for instructions on compiling.
Chapter 13, Building Distributed Applications with RPC, explains how to link in the RPC RTL.
In this chapter, all routines are documented according to their standard UNIX names. Routines that are unique to TCPware have UNIX-style names.
If you are writing code in C language, you may use the routine names used in this chapter. If you are writing code in a different language, however, you must use the TCPware names defined in the SYS$COMMON:[TCPWARE.INCLUDE.RPCOLD]:ONCRPC_FUNC.H file. These names all begin with the letters ONCRPC.
All RPC programs include the file named RPC.H. Locations for this file are:
· VAX C: SYS$COMMON:[TCPWARE.INCLUDE.RPCOLD]: RPC.H
· DEC C: UCX$RPC:RPC.H
The RPC.H file includes the files listed in the below table.
|
Filename |
Purpose |
|
Pertains to DEC C and VAX C |
|
|
AUTH.H |
Used for authentication. |
|
AUTH_UNIX.H |
Contains XDR definitions for UNIX-style authentication. |
|
CLNT.H |
Contains various RPC client definitions. |
|
IN.H |
Defines structures for the internet and socket addresses (in_addr and sockaddr_in). This file is part of the C Socket Library. |
|
RPC_MSG.H |
Defines the RPC message format. |
|
SVC.H |
Contains various RPC server definitions. |
|
SVC_AUTH.H |
Used for server authentication. |
|
TYPES.H |
Defines UNIX C data types. |
|
XDR.H |
Contains various XDR definitions. |
|
Pertains to VAX C only |
|
|
ONCRPC_CONST.H |
Defines RPC characteristics and other constants. |
|
ONCRPC_FUNC.H |
Maps ONCRPC routine names with their UNIX counterparts. |
|
ONCRPC_STRUCT.H |
Defines structures for the RPC client and server counters. |
|
Pertains to DEC C only |
|
|
NETDB.H |
Defines structures and routines to parse /etc/rpc. |
There is an additional header file not included by RPC.H that is used by xdr_pmap and xdr_pmaplist routines. The file name is pmap_prot.h, and the location is:
VAX C: SYS$COMMON:[TCPWARE.INCLUDE.RPCOLD]:PMAP_PROT.H
DEC C: UCX$RPC:PMAP_PROT.H
Many ONC RPC routines return TRUE or FALSE values. In C, FALSE is zero, and TRUE is any other value.
ONC RPC services are based on the Open Network Computing Remote Procedure Call protocols originally developed by Sun Microsystems. This section lists the ways in which the TCPware's implementation of ONC RPC services differs from Sun's implementation of RPC.
· DEC C: TCPware provides the following management routines:
o get_myaddress
o getrpcbynumber
o getrpcport
· VAX C: TCPware provides the following management routines:
o ONCRPC_GET_CHAR
o ONCRPC_SET_CHAR
o ONCRPC_GET_STATS
These routines allow you to retrieve and maintain information that describes how a process is using ONC RPC. Sun does not provide these routines.
· VAX C: TCPware does not support the following Sun routines:
o svcstdio_create
o svcraw_create
o clntraw_create
These routines deal with transports that the OpenVMS environment does not support.
· The svcfd_create routine provided by TCPware supports only TCP sockets. The Sun version supports file descriptors, including stdin and stdout.
· In TCPware, the global variable svc_fdset contains an array of structures, where each element is a socket pointer and a service handle. Sun implements this variable as a bit mask with an associated array of service handles.
· The authunix_create_default routine provided by TCPware creates credentials based on the VAX C geteuid and getegid routines.
· TCPware provides the pmap_freemaps routine to free the memory that was allocated by the pmap_getmaps routine. Sun requires the programmer to know the internals of the pmaplist structure and free the memory himself.
· TCPware provides the xdr_netobj routine. This routine encodes and decodes netobj, an aggregate data structure that is opaque and contains a counted array of 1024 bytes.
· TCPware provides the xdr_netobj routine. This routine encodes and decodes netobj, an aggregate data structure that is opaque and contains a counted array of 1024 bytes.
· ONC: TCPware provides asynchronous transports, with the following routines:
o svctcpa_create
o svctcpa_getxdrs
o svcudpa_enablecache
o svctcpa_shutdown
o svcudpa_bufcreate
o svcudpa_freecache
o svctcpa_enablecache
o svcudpa_create
o svcudpa_getxdrs
o svctcpa_freecache
o svcudpa_shutdown
Sun does not provide asynchronous transports.
· VAX C: TCPware provides the following macros:
o svc_getchan
o svc_getport
Sun does not provide these macros.
· The TCPware RPCGEN compiler gives the input file a default extension of .X if no extension is specified. The Sun RPCGEN compiler requires you to enter the .X extension.
· The TCPware RPCGEN compiler accepts input only from a file, not from the terminal. The Sun RPCGEN compiler accepts both types of input.
· The TCPware RPCINFO command supports the TCP and UDP protocol for any request. The Sun version supports only the UDP protocol when you use RPCINFO to request a Port Mapper listing.
RPC management routines retrieve and maintain information that describes how a process is using RPC. This section describes each management routine and function in detail. The following information is provided for each routine:
· Format
· Arguments
· Description
· Diagnostics, or status codes returned, if any
Returns the internet address of the local host.
void get_myaddress(struct sockaddr_in *addr);
addr
Address of a sockaddr_in structure that will be loaded with the host internet address. The port number is always set to htons(PMAPPORT).
The get_myaddress routine returns the internet address of the local host without doing any name translation or DNS lookups.
Gets an RPC entry. (DEC C only.)
struct rpcent *getrpcbynumber(int number)
number
Program name or number.
The getrpcbynumber routine returns a pointer to an object with the following structure containing the broken-out fields of a line in the RPC program number database.
struct rpcent
{
char *r_name; /* name of server for this RPC program */
char **r_aliases; /* alias list */
long r_number; /* RPC program number */
};
The members of this structure are:
|
r_name |
Name of the server for this RPC program |
|
r_aliases |
Zero-terminated list of alternate names for the RPC program |
|
r_number |
RPC program number for this service |
The getrpcbynumber routine sequentially searches from the beginning of the file until a matching RPC program name or program number is found, or until an EOF is encountered.
A NULL pointer is returned on EOF or error.
Gets an RPC port number. (DEC C only.)
int getrpcport(char *host, int prognum, int versnum, int proto)
host
Host running the RPC program.
prognum
Program number.
proto
Protocol name. Must be IPPROTO_TCP or IPPROTO_UDP.
The getrpcport routine returns the port number for version versnum of the RPC program prognum running on host and using protocol proto.
It returns 0 if it cannot contact the portmapper, or if prognum is not registered. If prognum is registered but not with versnum, it still returns a port number (for some version of the program), indicating that the program is indeed registered. The version mismatch is detected on the first call to the service.
Returns the characteristic values of an RPC client or server process. (VAX C only.)
u_long ONCRPC_GET_CHAR(u_long code, void *value)
code
Characteristic being returned. The following text describes each code.
RPCCHAR_ _AC_SIZE - Alters the number of entries in the active cache. This code is for UDPA transports only. If you try to set RPCCHAR__AC_SIZE when a UDPA transport is active, then RPC_SET_CHAR returns the SS$_DEVACTIVE error code. The type is u_short *value. The default is 20.
RPCCHAR_ _CHECKSUM - Enables or disables checksums for outgoing packets. The receiver checks packets if the sender generates a checksum. Disabling checksums improves performance but reduces data integrity. This code is for UDPA servers only. Valid values are RPCCKSUM__ENABLE and RPCCKSUM__DISABLE. The type is u_long *value. The default is RPCCKSUM__ENABLE.
RPCCHAR_ _DEBUG - Enables the printing of messages that indicate what RPC is doing. All logging messages go to SYS$OUTPUT. The type is u_long *value. The default is 0.
These are the mask values for RPCCHAR__DEBUG:
|
RPCDBG_ _XDR |
Prints a message indicating which XDR routines are being used. |
|
RPCDBG_ _XID |
Prints a message each time the XID cache is referenced. The message indicates the type of operation being per formed on the XID cache. For UDP and UDPA servers only. |
|
RPCDBG_ _ACTIVE_CA |
Prints a message each time the active cache is referenced. The message indicates the type of operation being per formed on the active cache. For UDPA servers only. |
|
RPCDBG_ _GENERAL |
Prints general messages about the activities of RPC RTL routines. |
|
RPCDBG_ _RAW_RCV |
Prints, in hexadecimal and ASCII, the contents of packets that were received. |
|
RPCDBG_ _RAW_SEND |
Prints, in hexadecimal and ASCII, the contents of packets that were sent. |
|
RPCDBG_ _AUTH |
Prints authentication processing information. |
|
RPCDBG_ _MEMORY |
Tracks memory allocation for the RPC RTL. |
RPCCHAR_ _DEFPORTS - If an RPC program does not specify a port to use, RPC assigns it a port. The RPCCHAR_ _DEFPORTS code determines whether RPC tries to use privileged ports (600 to 1023) or non-privileged ports (1024 and greater). The type is u_long *value. Values are RPCPORTS_ _PRIVILEGE and RPCPORTS_NORMAL. RPCPORTS_PRIVILEGE is the default, which means the application uses a privileged port if it has sufficient privileges, otherwise it uses a non-privileged port.
RPCCHAR_ _FATALRTN - Calls an error-handling routine when the TCPA or UDPA transports detect a fatal error. The OpenVMS error status code is passed to the error-handling routine. If *value is zero, the default value is used. The type is void (**value)(u_long status). The default is SYS$EXIT.
value
Address where the routine places the characteristic value.
The characteristic values are defined as constants in the RPC_CONST.H file. Each process using the RPC library has its own copy of these values. The ONCRPC_GET_CHAR routine retrieves these values.
u_long debug;
oncrpc_get_char(
RPCCHAR__DEBUG, &debug);
printf( "The debugging value is %08X", debug);
This example prints a message that shows the present debugging value for RPC. The message goes to SYS$OUTPUT.
|
SS$_NORMAL |
Routine executed successfully. |
|
SS$_BADPARAM |
code is invalid. |
|
SS$_ACCVIO |
value is a null address. |
Returns counters for memory usage, the RPC server, or the RPC client. (VAX C only.)
u_long ONCRPC_GET_STATS(u_long code, u_char *buffer)
code
These codes are valid:
|
RPCSTAT_ _ZERO |
Zeros out the client or server counters. |
|
RPCSTAT_ _CLIENT |
Retrieves client counters. |
|
RPCSTAT_ _SERVER |
Retrieves server counters. |
|
RPCSTAT_ _MEMORY |
Retrieves memory counters. |
The below example shows how to use the RPCSTAT_ _ZERO code in combination with the other codes to zero-out the client and server counters after they are retrieved. You cannot zero-out memory counters.
buffer
Address of the structure to receive the requested counters. These structures are defined in the RPC_STRUCT.H file. The length of the buffer equals the size of the structures. These are the structures:
/*
** Statistics structure (server)
*/
typedef struct
{
time_tzero_time; /* # seconds since zeroed*/
u_longrecvs, /* # receives*/
recv_errs, /* # bad receives*/
xmits, /* # transmits*/
xmit_errs, /* # transmit errors*/
xerr_badlen /* # calls w/body too small*/
xerr_nullrecv, /* # empty calls*/
xerr_auth_weak, /* # weak auth errors*/
xerr_auth_other, /* # other auth errors*/
xerr_decode, /* # decode errors
xerr_noproc, /* # no procedure errors*/
xerr_noprog, /* # no program errors*/
xerr_novers, /* # no matching version errors*/
xerr_systemerr, /* # other system errors*/
xid_hits, /* # replies sent from xid cache*/
xid_saves, /* # replies cached*/
duprcvs; /* # calls found in active cache*/
} svc_counters;
/*
** Statistics structure (client)
*/
typedef struct
{
time_t zero_time; /* # seconds since zeroed*/
u_long recvs, /* # receives */
recv_errs, /* # receive errors*/
badxid, /* # xid mismatches*/
xmits, /* # transmits*/
xmit_errs /* # transmit errors*/
newcred, /* # new credentials (always 0)*/
retrans, /* # retransmissions*/
timeout, /* # timeouts*/
wait; /* (always 0)*/
} clnt_counters;
/*
** Memory statistics structure
*/
typedef struct
{
u_long no_mallocs, /* # times memory was allocated*/
no_frees, /* # times memory was freed*/
mem_in_use; /* # bytes of memory in use*/
} mem_counters;
The ONCRPC_GET_STATS routine returns counters for this process only.
clnt_counters cstats;
oncrpc_get_stats(
RPCSTAT__CLIENT | RPCSTAT__ZERO, &cstats);
/* cstats now contains the client statistics */
This example retrieves client counters, then zeros them out.
|
SS$_NORMAL |
Routine successfully returned the counters. |
|
SS$_BADPARAM |
code is invalid. |
|
SS$_ACCVIO |
buffer is a null address. |
Defines the values of characteristics for each RPC client and server process. (VAX C only.)
u_long ONCRPC_SET_CHAR(u_long code, void *value)
code
Characteristic being set. See the ONCRPC_GET_CHAR routine for a description of each code.
value
Address of the characteristic value.
Use the ONCRPC_SET_CHAR routine to define characteristic values for RPC processes. Each RPC process has its own values. Codes and values are defined as constants in the RPC_CONST.H file.
void exit_routine (u_long status)
{
exit( status);
}
main()
{
void (*fatal_routine)();
fatal_routine = exit_routine;
/* fatal_routine is the address of exit_routine */
oncrpc_set_char( RPCCHAR__FATALRTN, &fatal_routine);
}
Sets the exit routine to be called when the TCPA or UDPA transport detects a fatal error.
|
SS$_NORMAL |
Routine executed successfully. |
|
SS$_ACCVIO |
value is a null address. |
|
SS$_BADPARAM |
code is invalid. |
|
SS$_DEVACTIVE |
A process tried to change the size of the active cache while the UDPA transport was active. |