clnt_tli_create()--Create a Client Handle


  Syntax

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

 CLIENT *clnt_tli_create(const int fildes,
                         const struct netconfig
                            *netconf,
                         const struct netbuf *svcaddr,
                         const u_long prognum,
                         const u_long versnum,
                         const u_int sendsz,
                         const u_int recvsz);

  Service Program Name: QZNFTRPC

  Default Public Authority: *USE

  Threadsafe: No

The clnt_tli_create() API creates an RPC client handle for the remote program prognum and version versnum. The remote program is located at address svcaddr. The client uses the transport that is specified by netconf. Depending upon the type of the transport (connection-oriented or connectionless), clnt_tli_create() calls the appropriate client-creation functions.


Parameters

fildes  (Input) 
A file descriptor. The only permitted value is RPC_ANYFD. The API opens an internal file descriptor which is not accessible by the user applications.

netconf  (Input) 
The transport protocol.

svcaddr  (Input) 
A pointer to the address where the remote program is located.

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

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

sendsz  (Input) 
The size of the send buffer. When a value of zero is specified, a suitable default will be chosen by the system.

recvsz  (Input) 
The size of the receive buffer. When a value of zero is specified, a suitable default will be chosen by the system.

Authorities

No authorization is required.


Return Value

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


Error Conditions

Upon failure, clnt_tli_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_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 fildes cannot be bound to any local address.
[EADDRNOTAVAIL] Address not available. This value is set when svcaddr 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 the fildes parameter is not valid or cannot be used as a transport endpoint.
[ECONNREFUSED] TI-RPC encountered a problem in the transport. The client cannot connect to the server.
[EFAULT] The address used for an svcaddr 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 fildes represents a transport endpoint with limited capabilities.
[EUNKNOWN] Unknown system state.
[RPC_UNKNOWNADDR] Unknown remote address. The rpc_createerr.cf_error.re_errno variable is not applicable. This error is set when the svcaddr pointer is NULL.
[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_tli_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;
  struct netbuf *service_address;
  struct nd_addrlist *nas;
  struct nd_hostserv hs;

  /* 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);
  }

  hs.h_host = "as400.somewhere.ibm.com";
  hs.h_serv = "RPCBIN";
  if(netdir_getbyname(nconf,&hs,&nas) < 0
  || nas->n_cnt == 0) {
     fprintf(stderr, "Cannot translate host name or service name\n");
  service_address = nas->n_addrs;

  client = clnt_tli_create(RPC_ANYFD, nconf, service_address,
                       RMTPROGNUM, RMTPROGVER, 0, 0);
  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 ]