clnt_tp_create()--Create a Client Handle


  Syntax

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

 CLIENT *clnt_tp_create(const char *host,
                        const u_long prognum,
                        const u_long versnum,
                        const struct netconfig
                            *netconf);

  Service Program Name: QZNFTRPC

  Default Public Authority: *USE

  Threadsafe: No

The clnt_tp_create() API creates a client handle for the program prognum, the version versnum, and for the transport specified by netconf. The remote RPCBind service on the host machine host is consulted for the address of the remote service.


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.

netconf  (Input) 
The transport protocol to use.

Authorities

The caller of the clnt_tp_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 function returns a client handle.
NULL clnt_tp_create() was not successful. The rpc_createerr variable is set to indicate the reason.


Error Conditions

Upon failure, clnt_tp_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 is set to EUNKNOWN.
[RPC_N2AXLATEFAILURE] Name-to-address translation failed. The API cannot resolve the hostname given in host.
[RPC_PROGNOTREGISTERED] Remote program is not registered.
[RPC_RPCBFAILURE] A failure occurred in the RPCBind daemon.
[RPC_SYSTEMERROR] RPC error returned from 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 the transport endpoint cannot be bound to any local address. This API calls rpcb_getaddr() API in order to perform the API's task. It inherits all error conditions from clnt_tli_create() and rpcb_getaddr() APIs, except RPC_FAILED.
[EADDRNOTAVAIL] Address not available. This value is set when the address obtained by the rpcb_getaddr() is rejected by transport layer.
[EAGAIN] Operation would have caused the process to be blocked.
[EBADF] Bad file descriptor. This value is set when the transport endpoint created is not valid.
[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 the transport endpoint was opened with limited capabilities.
[EUNKNOWN] Unknown system state.
[RPC_UNKNOWNHOST] Unknown host.
[RPC_UNKNOWNPROTO] Unknown client/server protocol. The rpc_createerr.cf_error.re_errno variable is not applicable. 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.
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

The following example shows how clnt_tp_create() 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)0x3fffffff)
#define RMTPROGVER ((u_long)0x1)

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

main()
{
  CLIENT *client;
  struct netconfig *nconf;

  /* Returns a pointer to nconf corresponding to NETCONF */
  if ((nconf = getnetconfigent("UDP")) ==
               (struct netconfig *)NULL) {
    fprintf(stderr, "Cannot get netconfig entry for UDP\n");
    exit(1);
  }

  client = clnt_tp_create("as400.somewhere.ibm.com", RMTPROGNUM,
                                     RMTPROGVER, nconf);
  if (client == (CLIENT *)NULL) {
    fprintf(stderr, "Cannot create an RPC client\n");
    exit(1);
  }

  fprintf(stderr, "Successfully created a client handle\n"); 

  clnt_destroy(client);
}

API introduced: V4R2

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