clnt_control()--Change Information about a Client Object


  Syntax

 #include <rpc/rpc.h>

 bool_t clnt_control(CLIENT *clnt,
                     const u_int req,
                     char *info);

  Service Program Name: QZNFTRPC

  Default Public Authority: *USE

  Threadsafe: No

The clnt_control() function is used to change or retrieve information about a client object. For both connectionless and connection-oriented transports, the supported values for req, their argument types, and what they do follow:

Values for the req Parameter Argument Type Function
CLSET_TIMEOUT (struct timeval *) Set total time out
CLGET_TIMEOUT (struct timeval *) Get total time out
CLGET_SERVER_ADDR (struct netbuf *) Get server's address
CLGET_SVC_ADDR (struct netbuf *) Get server's address
CLSET_SVC_ADDR (struct netbuf *) Set to new address
CLGET_FD (int *) Get the associated file descriptor
CLSET_FD_CLOSE (void) Close the file descriptor when the API destroys the client handle
CLSET_FD_NCLOSE (void) Do not close the file descriptor when the API destroys the client handle
CLGET_VERS (unsigned long *) Get the RPC program's version number that is associated with the client handle
CLSET_VERS (unsigned long *) Set the RPC program's version number that is associated with the client handle
CLGET_PROG (unsigned long *) Get the program number
CLSET_PROG (unsigned long *) Set the program number
CLGET_XID (unsigned long *) Get the XID of the previous RPC
CLSET_XID (unsigned long *) Set the XID of the next RPC
CLSET_RETRY_TIMEOUT1 (struct timeval *) Set the retry time-out
CLGET_RETRY_TIMEOUT1 (struct timeval *) Get the retry time-out
Note:
1   Valid only for connectionless transports.


Parameters

clnt  (Input) 
A pointer to the client handle structure.

req  (Input) 
The type of operation.

info  (Input/Output) 
A pointer to the information for request type. The info parameter is expected to be a pointer to an appropriate structure. The nature of the structure depends on the req parameter.

Authorities

No authorization is required.


Return Value

TRUE (1) Successful
FALSE (0) Unsuccessful


Error Conditions

Failure is returned only when a bad format of parameters is detected. For example, the info parameter is NULL, when a pointer to a timeval structure is expected.


Error Messages

Message ID Error Message Text
CPIA1B1 I A problem was encountered in the RPC client.
CPE3418 E Possible APAR condition or hardware failure.
CPF3CF2 E Error(s) occurred during running of &1 API.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.


Example

See Code disclaimer information for information pertaining to code examples.

The following example shows how clnt_control() is used:

#include <rpc/rpc.h>

main()
{
  CLIENT *clnt;
  int fd;

  ...

  /* Get the associated file descriptor */
  clnt_control(clnt, CLGET_FD, (int *)&fd);
  ...

}

Notes
  1. If the time-out is set using the clnt_control() API, the timeout parameter passed to the clnt_call() API will be ignored in all future calls.
  2. The retry time-out is the time that the connectionless RPC client waits for the server to reply before retransmitting the request.

API introduced: V4R2
Top | Remote Procedure Call (RPC) APIs | APIs by category