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

 #include <rpc/rpc.h>

 enum clnt_stat rpc_call(const char *host,
                         const u_long prognum,
                         const u_long versnum,
                         const u_log procnum,
                         const xdrproc_t inproc,
                         const char *in,
                         const xdrproc_t outproc,
                         char *out,
                         const char *nettype);

The rpc_call() API calls the remote procedure that is associated with prognum, versnum, and procnum on the machine, host. rpc_call() tries all the transports of the nettype class available from the netconfig database file, and chooses the first successful one. Transports are tried in top-to-bottom order in the netconfig database file. A default time-out is set and can be modified using clnt_control().

Parameters

host  (Input) 

A pointer to the program name of the remote machine.

prognum  (Input) 

The program number of the remote program.

vernum  (Input) 

The version number of the remote program.

procnum  (Input) 

The number of the procedure that is associated with the remote program being called.

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.

nettype  (Input) 

The following classes of transport protocol are valid and are represented as a string either in lowercase or in uppercase: NETPATH, VISIBLE, CIRCUIT_V, DATAGRAM_V, CIRCUIT_N, DATAGRAM_N, TCP, and UDP. When this parameter is NULL, NETPATH is assumed.

Authorities

The caller of the rpc_call() API must have execute (*X) authority to the /etc directory and must have read (*R) authority to the netconfig file.

Return Value

Error Conditions

Upon failure, rpc_call() sets the global structure rpc_createerr. The rpc_createerr.cf_stat variable has a status value that indicates the error reason. The rpc_createerr.cf_error.re_errno variable is meaningful when some status values are set.

The rpc_createerr.cf_stat variable can be set to one of the following values:

This API calls clnt_create() and clnt_call() APIs in order to perform its task. All error conditions from those APIs are inherited except RPC_FAILED from clnt_call().

Error Messages

Related Information

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

Example

The following example shows how rpc_call() is used.

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

/* Define remote program number and version */

#define RMTPROGNUM (u_long)0x3fffffffL
#define RMTPROGVER (u_long)0x1
#define RMTPROCNUM (u_long)0x1

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

main()
{
  int inproc=100, outproc;
  enum clnt_stat rstat;

  ...

  /* Service request to host RPCSERVER_HOST */
  if (rstat = rpc_call("as400.somewhere.ibm.com", RMTPROGNUM,
               RMTPROGVER, RMTPROCNUM, xdr_int, (char *)&inproc,
               xdr_int, (char *)&outproc, "VISIBLE")
               != RPC_SUCCESS){
    fprintf(stderr,"rpc_call() failed\n");
    exit(1);
  }
  ...
}

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