14. RPC RTL Management Routines

Introduction

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.

Management Routines

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.

Routine Name Conventions

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.

Header Files

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

Boolean Values

Many ONC RPC routines return TRUE or FALSE values. In C, FALSE is zero, and TRUE is any other value.

TCPware/Sun Implementation Differences

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.

Management Routines

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

 

 

 

 


 

get_myaddress

Returns the internet address of the local host.

 

Format

void get_myaddress(struct sockaddr_in *addr);

 

Argument

 

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).

 

Description

The get_myaddress routine returns the internet address of the local host without doing any name translation or DNS lookups.

 

 

 

 


 

getrpcbynumber

Gets an RPC entry. (DEC C only.)

 

Format

struct rpcent *getrpcbynumber(int number)

 

Argument

 

number

Program name or number.

 

Description

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.

 

Diagnostics

A NULL pointer is returned on EOF or error.

 

 

 

 

 


 

getrpcport

Gets an RPC port number. (DEC C only.)

 

Format

int getrpcport(char *host, int prognum, int versnum, int proto)

 

Arguments

 

host

Host running the RPC program.

 

prognum

Program number.

 

proto

Protocol name. Must be IPPROTO_TCP or IPPROTO_UDP.

 

Description

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.

 

 

 

 


 

ONCRPC_GET_CHAR

Returns the characteristic values of an RPC client or server process. (VAX C only.)

 

Format

u_long ONCRPC_GET_CHAR(u_long code, void *value)

 

Arguments

 

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.

 

Description

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.

 

Example

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.

 

Diagnostics

SS$_NORMAL

Routine executed successfully.

SS$_BADPARAM

code is invalid.

SS$_ACCVIO

value is a null address.

 

 

 

 

 


 

ONCRPC_GET_STATS

Returns counters for memory usage, the RPC server, or the RPC client. (VAX C only.)

 

Format

u_long ONCRPC_GET_STATS(u_long code, u_char *buffer)

 

Arguments

 

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;

 

Description

The ONCRPC_GET_STATS routine returns counters for this process only.

 

Example

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.

 

Diagnostics

SS$_NORMAL

Routine successfully returned the counters.

SS$_BADPARAM

code is invalid.

SS$_ACCVIO

buffer is a null address.

 

 

 

 

 


 

ONCRPC_SET_CHAR

Defines the values of characteristics for each RPC client and server process. (VAX C only.)

 

Format

u_long ONCRPC_SET_CHAR(u_long code, void *value)

 

Arguments

 

code

Characteristic being set. See the ONCRPC_GET_CHAR routine for a description of each code.

 

value

Address of the characteristic value.

 

Description

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.

 

Example

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.

Diagnostics

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.