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_TIMEOUT¹

(struct timeval *)

Set the retry time-out

CLGET_RETRY_TIMEOUT¹

(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

The following example shows how clnt_control() is used.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#include <rpc/rpc.h>

main()
{
  CLIENT *clnt;
  int fd;

  ...

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

}

Notes

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

[ Back to top | Remote Procedure Call (RPC) APIs | APIs by category ]