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


Example

See Code disclaimer information for information pertaining to code examples.

The following example shows how clnt_call() is used:

#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
Top | Remote Procedure Call (RPC) APIs | APIs by category