Compaq TCP/IP Services for OpenVMS
ONC RPC Programming


Previous Contents Index


clnt_call

A macro that calls a remote procedure.

Format

#include <rpc/rpc.h>

enum clnt_stat clnt_call(CLIENT *handle, u_long procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char *out, struct timeval timeout);


Arguments

handle

A pointer to a client handle created by any of the client-handle creation routines.

procnum

The procedure number associated with the remote procedure.

inproc

The XDR routine used to encode the remote procedure's arguments.

in

A pointer to the remote procedure's arguments.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

timeout

A structure describing the time allowed for results to return to the client. If you have previously used the clnt_control macro with the CLSET_TIMEOUT code, this value is ignored.

Description

Use the clnt_call macro after using one of the client-handle creation routines. After you are finished with the handle, return it using the clnt_destroy macro. Use the clnt_perror to print any errors that occurred.

Return Values

RPC_SUCCESS Indicates success.
clnt_stat Returns the buffer of type enum clnt_stat containing the status of the clnt_call operation.

clnt_control

A macro that changes or retrieves information about an RPC client process.

Format

#include <rpc/rpc.h>

bool_t clnt_control(CLIENT *handle, u_int code, char *info);


Arguments

handle

A pointer to a client handle created by any of the client-handle creation routines.

code

A code designating the type of information to be set or retrieved.

info

A pointer to a buffer containing the information for a SET operation or the results of a GET operation.

Description

For UDP and TCP transports specify any of the following for code :
CLSET_TIMEOUT struct timeval Set total timeout
CLGET_TIMEOUT struct timeval Get total timeout
CLGET_SERVER_ADDR struct sockaddr_in Get server address
CLGET_FD int Get associated socket
CL_FD_CLOSE void Close socket on clnt_destroy
CL_FD_NCLOSE void Leave socket open on clnt_destroy
If you set the timeout using clnt_control , ONC RPC ignores the timeout parameter in all future clnt_call calls. The default total timeout is 25 seconds.

For the UDP transport two additional options are available:
CLSET_RETRY_TIMEOUT struct timeval Set retry timeout
CLGET_RETRY_TIMEOUT struct timeval Get retry timeout

The timeout value in these two calls is the time that UDP waits for a response before retransmitting the message to the server. The default time is 5 seconds. The retry timeout controls when UDP retransmits the request; the total timeout controls the total time that the client should wait for a response. For example, with the default settings, UDP will retry the transmission four times at 5-second intervals.


Return Values

TRUE Success
FALSE Failure

clnt_create

Creates a client handle and returns its address.

Format

#include <rpc/rpc.h>

CLIENT *clnt_create(char *host, u_long prognum, u_long versnum, char *protocol);


Arguments

host

A pointer to the name of the remote host.

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure.

protocol

A pointer to a string containing the name of the protocol for transmitting and receiving RPC messages. Specify either tcp or udp .

Description

The clnt_create routine creates an RPC client handle for prognum . An RPC client handle is a structure containing information about the RPC client. The client can use the UDP or TCP transport protocol.

This routine uses the Portmapper. You cannot control the local port.

The default sizes of the send and receive buffers are 8800 bytes for the UDP transport, and 4000 bytes for the TCP transport. The retry time for the UDP transport is five seconds.

Use the clnt_create routine instead of the callrpc or clnt_broadcast routines if you want to use one of the following:

You can also use the clnttcp_create routine to use the TCP protocol, or the clntudp_create routine to use the UDP protocol.

The clnt_create routine uses the global variable rpc_createerr . rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed.

Note

If the requested program is available on the host but the program does not support the requested version number, this routine still succeeds. A subsequent call to the clnt_call routine will discover the version mismatch. Use the clnt_create_vers routine if you want to avoid this condition.

Return Values

CLIENT * Client handle containing the server information.
NULL Error occurred while creating the client handle. Use the clnt_pcreateerror or clnt_spcreateerror routine to obtain diagnostic information.

clnt_create_vers

Creates a client handle and returns its address. Seeks to use a server supporting the highest version number within a specified range.

Format

#include <rpc/rpc.h>

CLIENT *clnt_create_vers(char *host, u_long prognum, u_long *versnum, u_long min_vers, u_long max_vers, char *protocol);


Arguments

host

A pointer to the name of the remote host.

prognum

The program number associated with the remote procedure.

versnum

The version number associated with the remote procedure. This value is returned by the routine. The value is the highest version number supported by the remote server that is in the range of version numbers specified by min_vers and max_vers . The argument may remain undefined; see additional information in the Description section.

min_vers

The minimum acceptable version number for the remote procedure.

max_vers

The maximum acceptable version number for the remote procedure.

protocol

A pointer to a string containing the name of the protocol for transmitting and receiving RPC messages. Specify either tcp or udp .

Description

The clnt_create_vers routine creates an RPC client handle for prognum . An RPC client handle is a structure containing information about the RPC client. The client can use the UDP or TCP transport protocol.

This routine uses the Portmapper. You cannot control the local port.

The default sizes of the send and receive buffers are 8800 bytes for the UDP transport, and 4000 bytes for the TCP transport. The retry time for the UDP transport is 5 seconds.

The clnt_create_vers routine differs from the standard clnt_create routine in that it seeks out the highest version number supported by the server. If the server does not support any version numbers within the requested range, the routine returns NULL and the versnum variable is undefined.

The clnt_create_vers routine uses the global variable rpc_createerr . rpc_createerr is a structure that contains the most recent service creation error. Use rpc_createerr if you want the client program to handle the error. The value of rpc_createerr is set by any RPC client creation routine that does not succeed.


Return Values

CLIENT * Clien-thandle containing the server information.
NULL Error occurred while creating the client handle. Usually the error indicates that the server does not support any version numbers within the requested range. Use the clnt_pcreateerror or clnt_spcreateerror routine to obtain diagnostic information.

clnt_destroy

A macro that frees the memory associated with an RPC client handle.

Format

#include <rpc/rpc.h>

void clnt_destroy(CLIENT *handle);


Arguments

handle

A pointer to a client handle created by any of the client-handle creation routines.

Description

The clnt_destroy routine destroys the client's RPC handle by deallocating all memory related to the handle. The client is undefined after the clnt_destroy call.

If the clnt_create routine had previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_CLOSE, this routine closes the socket. If the clnt_create routine had not previously opened the socket associated with the client handle or the program had used the clnt_control routine to set CL_FD_NCLOSE, this routine leaves the socket open.


Return Values

None  

clnt_freeres

A macro that frees the memory that was allocated when the remote procedure's results were decoded.

Format

#include <rpc/rpc.h>

bool_t clnt_freeres(CLIENT *handle, xdrproc_t outproc, char *out);


Arguments

handle

A pointer to a client handle created by any of the client-handle creation routines.

outproc

The XDR routine used to decode the remote procedure's results.

out

A pointer to the remote procedure's results.

Description

The clnt_freeres routine calls the xdr_free routine to deallocate the memory where the remote procedure's results are stored.

Return Values

TRUE Success.
FALSE Error occurred while freeing the memory.

clnt_geterr

A macro that returns error information indicating why an RPC call failed.

Format

#include <rpc/rpc.h>

void clnt_geterr(CLIENT *handle, struct rpc_err *errp);


Arguments

handle

A pointer to a client handle created by any of the client-handle creation routines.

errp

A pointer to an rpc_err structure containing information that indicates why an RPC call failed. This information is the same information as clnt_stat contains, plus one of the following: the C error number, the range of server versions supported, or authentication errors.

Description

This macro copies the error information from the client handle to the structure referenced by errp . The macro is mainly for diagnostic use.

Return Values

None  

clnt_pcreateerror

Prints a message explaining why ONC RPC could not create a client handle.

Format

#include <rpc/rpc.h>

void clnt_pcreateerror(char *sp);


Arguments

sp

A pointer to a string to be used as the beginning of the error message.

Description

The clnt_pcreateerror routine prints a message to SYS$OUTPUT. The message consists of the sp parameter followed by an RPC-generated error message. Use this routine when the clnt_create , clnttcp_create , or clntudp_create routine fails.

Return Values

None  

clnt_perrno

Prints a message indicating why the callrpc or clnt_broadcast routine failed.

Format

#include <rpc/rpc.h>

void clnt_perrno(enum clnt_stat stat)

;


Arguments

stat

A buffer containing status information.

Description

Prints a message to standard error corresponding to the condition indicated by the stat argument.

The data type declaration for clnt_stat in rpc/rpc.h lists the standard errors.


Return Values

None  

clnt_perror

Prints a message explaining why an ONC RPC routine failed.

Format

#include <rpc/rpc.h>

void clnt_perror(CLIENT *handle, char *sp);


Arguments

handle

A pointer to the client handle used in the call that failed.

sp

A pointer to a string to be used as the beginning of the error message.

Description

Prints a message to standard error indicating why an ONC RPC call failed. The message is prepended with string sp and a colon.

Return Values

None  

clnt_spcreateerror

Returns a message indicating why RPC could not create a client handle.

Format

#include <rpc/rpc.h>

char *clnt_spcreateerror(char *sp);


Arguments

sp

A pointer to a string to be used as the beginning of the error message.

Description

The clnt_spcreateerror routine returns the address of a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use the clnt_spcreateerror routine when the clnt_create , clnttcp_create , or clntudp_create routine fails.

Use this routine if:

The address that clnt_spcreateerror returns is the address of its own internal string buffer. The clnt_spcreateerror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string.


Return Values

char * A pointer to the message string terminated with a NULL character.
NULL The routine was not able to allocate its internal buffer.

clnt_sperrno

Returns a message indicating why the callrpc or clnt_broadcast routine failed to create a client handle.

Format

#include <rpc/rpc.h>

char *clnt_sperrno(enum clnt_stat stat);


Arguments

stat

A buffer containing status information.

Description

The clnt_sperrno routine returns a pointer to a string.

Use this routine instead if:

The address that clnt_sperrno returns is a pointer to the error message string for the error. Therefore, you do not have to copy the string to your own buffer in order to save the string.


Return Values

char * A pointer to the message string terminated with a NULL character.

clnt_sperror

Returns a message indicating why an ONC RPC routine failed.

Format

#include <rpc/rpc.h>

char *clnt_sperror(CLIENT *handle, char *sp);


Arguments

handle

A pointer to the client handle used in the call that failed.

sp

A pointer to a string to be used as the beginning of the error message.

Description

The clnt_sperror routine returns a pointer to a message string. The message consists of the sp parameter followed by an error message generated by calling the clnt_sperrno routine. Use this routine when the clnt_call routine fails.

Use this routine if:

The address that clnt_sperror returns is a pointer to its own internal string buffer. The clnt_sperror routine overwrites this buffer with each call. Therefore, you must copy the string to your own buffer if you wish to save the string.


Return Values

char * A pointer to the message string terminated with a NULL character.
NULL The routine was not able to allocate its internal buffer.


Previous Next Contents Index