clnt_call()--Call a Remote Procedure Associated with the Client

Syntax

 #include <rpc/rpc.h>

 enum clnt_stat clnt_call(CLIENT *clnt,
                          const u_long procnum,
                          const xdrproc_t inproc,
                          const caddr_t in,
                          const xdrproc_t outproc,
                          caddr_t out,
                          const struct timeval tout);

  Service Program Name: QZNFTRPC

  Default Public Authority: *USE

  Threadsafe: No

The clnt_call() API calls the remote procedure that is associated with the client handle pointed to by the clnt parameter.

The caller of the clnt_call() API must pass a valid client handle obtained from a successful call to the clnt_create() API.

Parameters

clnt (Input): A pointer to the client handle structure that results from calling a client creation function that uses a Remote Procedure Call (RPC) such as the clnt_create() API.
procnum (Input): The procedure on the host machine.
inproc (Input): The name of the XDR procedure that encodes the procedure parameters.
in (Input): The address of the procedure arguments.
outproc (Input): The name of the XDR procedure that decodes the procedure results.
out (Output): The address where results are placed.
tout (Input): The time allowed for the server to respond.

Authorities

None.

Return Value

RPC_SUCCESS (0)

Successful

Non-zero value

clnt_call() was not successful.

Error Conditions

Upon failure, clnt_call() sets a private field in the client handle. This field has a type 'struct rpc_err', and can be accessed by the clnt_geterr() function.

The re_status field can be set to one of the following values:

[RPC_AUTHERROR]

Authentication error. Server's response did not pass authentication validation.

[RPC_CANTDECODERES]

The outproc XDR function has failed.

[RPC_CANTENCODEARGS]

The inproc XDR function has failed.

[RPC_CANTRECV]

Failure in receiving result. RPC is unable to receive server's response. The re_errno field is set to the value returned from the failed call.

[EBADF]

Bad file descriptor. This value is set when the client parameter is not valid or the file descriptor associated with it is already closed or damaged.

[EIO]

Input/output error. This value is set as a result of network transport failure. It indicates that RPC cannot handle an error that occurred in the lower transport levels.

[ENOMEM]

Out of memory.

[EOPNOTSUPP]

Operation is not supported. This value is set when client is not valid or the file descriptor associated with it has a limited capabilities.

[EUNKNOWN]

Unknown system state.

[RPC_CANTSEND]

Failure in sending call. RPC is unable to send a request. The re_errno field is set to the value returned from the failed call.

[EBADF]

Bad file descriptor. This value is set when the client parameter is not valid or the file descriptor associated with it is already closed or damaged.

[EIO]

Input/output error. This value is set as a result of network transport failure. It indicates that RPC cannot handle an error that occurred in the lower transport levels.

[ENOMEM]

Out of memory.

[EOPNOTSUPP]

Operation is not supported. This value is set when client is not valid or the file descriptor associated with it has a limited capabilities.

[EUNKNOWN]

Unknown system state.

[RPC_FAILED]

The tout parameter is not set properly.

[RPC_INTR]

Interrupted RPC call. An exception has occurred in the RPC API. The re_errno field is set to EUNKNOWN.

[RPC_TIMEDOUT]

RPC call is timed out. The client cannot receive a response in the specified timeout period.

[RPC_PROGVERSMISNATCH]

There are no registered versions for the program.

[RPC_PROGNOTREGISTERED]

The program is not registered with the server.

[RPC_PROGUNAVAIL]

The program is not registered with the server.

Error Messages

Message ID

Error Message Text

CPIA1B1 I

A problem was encountered in the RPC client.

CPIA1B2 I

TI-RPC encountered a problem in the transport protocol.

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.

Related Information

rpc_call()--Call a Remote Procedure on the Specified System

Example

The following example shows how clnt_call() is used.

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

#include <stdio.h>
#include <rpc/rpc.h>
#include <sys/time.h>

main()
{
  u_long procnum;
  CLIENT *clnt;
  enum clnt_stat cs;
  struct rpc_err client_error;
  struct timeval total_timeout;
  int intsend, intrecv;

  ...

  /* Call the remote procedure that is associated with client */
  cs = clnt_call(clnt, procnum, xdr_int,
                            (caddr_t)&intsend, xdr_int,
                            (caddr_t)&intrecv, total_timeout);

  if (cs != RPC_SUCCESS){
    clnt_geterr(client,&client_error);
    ...
    exit(1);
  }
}

API introduced: V4R2

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