clnt_create()--Create a Generic Client Handle


  Syntax

 #include <rpc/rpc.h>

 CLIENT *clnt_create(const char *host,
                    const u_long prognum,
                    const u_long versnum,
                    const char *nettype);

  Service Program Name: QZNFTRPC

  Default Public Authority: *USE

  Threadsafe: No

The clnt_create() API creates and returns a generic client handle for program prognum and version versnum on a remote host where the server is located. This is done using an available transport of the nettype class. The clnt_create() API tries all the transports of the nettype class available from the /etc/netconfig file, and chooses the first successful one. Transports are tried in top-to-bottom order in the netconfig database. A default time-out is set and can be modified using clnt_control().


Parameters

host  (Input) 
The name of the remote host where the server is located.

prognum  (Input) 
The program number of the remote program.

vernum  (Input) 
The version number of the remote program.

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 clnt_create() API must have execute (*X) authority to the /etc directory and must have read (*R) authority to the netconfig file.


Return Value

clnt Upon successful completion, this API returns a client handle.
NULL clnt_create() was not successful. The rpc_createerr variable is set to indicate the reason.


Error Conditions

Upon failure, clnt_create() sets the global structure rpc_createerr. The rpc_createerr.cf_stat variable contains 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:

[RPC_INTR] Interrupted RPC call. An exception has occurred in the RPC API. The rpc_createerr.cf_error.re_errno variable is set to EUNKNOWN.
[RPC_N2AXLATEFAILURE] Name-to-address translation failed. Cannot resolve the hostname given in host.
[RPC_SYSTEMERROR] An RPC error was returned from the system call. The rpc_createerr.cf_error.re_errno variable is set to the value returned from the failed call.
[EACCES] Permission denied.
[EADDRINUSE] Local address is in use. This value is set when host is not valid or the file descriptor associated with it cannot be bound to any local address.
[EADDRNOTAVAIL] Address not available. This value is set when the address obtained by the rpcb_getaddr() is rejected by the transport layer.
[EAGAIN] Operation would have caused the process to be blocked.
[EBADF] Bad file descriptor. This value is set when host is not valid or the file descriptor associated with it is already closed or damaged.
[ECONNREFUSED] TI-RPC encountered a problem in the transport. The client cannot connect to the server.
[EFAULT] The address created by the rpcb_getaddr() was not available.
[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 lower transport levels.
[ENOBUFS] There is not enough buffer space available for the API.
[ENOMEM] Out of memory.
[EOPNOTSUPP] Operation is not supported. This value is set when host is not valid or the file descriptor associated with it has limited capabilities.
[EUNKNOWN] Unknown system state.
[RPC_UNKNOWNHOST] Unknown host.
[RPC_UNKNOWNPROTO] Unknown client/server protocol. The rpc_createerr.cf_error.re_errno is set with the errno value returned by setnetconfig() or getnetconfig() call. This error is set when the netconf pointer is NULL.


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.
CPIA1B5 I An incorrect nettype was given.
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_create() is used:

/* Define remote program number and version */
#define RMTPROGNUM (u_long)0x3fffffffL
#define RMTPROGVER (u_long)0x1

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

main()
{
  CLIENT *client;

  /* Service request to host RPCSERVER_HOST */
  client = clnt_create("as400.somewhere.ibm.com", RMTPROGNUM,
                                  RMTPROGVER, "TCP");

  if (client == (CLIENT *)NULL) {
    fprintf(stderr,"Couldn't create client\n");
    exit(1);
  }
}

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