# 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:

> - The TCP transport
> - A non-null authentication
> - More than one active client at the same time

> 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:

> - You want to save the string.
> - You do not want to use `fprintf` to print the message.
> - The message format is different from the one that `clnt_perrno` supports.

> 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 server does not have a `stderr` file; many servers do not.
> - You want to save the string.
> - You do not want to use `fprintf` to print the message.
> - The message format is different from the one that `clnt_perrno` supports.

> 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:

> - You want to save the string.
> - You do not want to use `fprintf` to print the message.
> - The message format is different from the one that `clnt_perrno` supports.

> 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