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.
|
||||||||||||||||||||||||
[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
The following example shows how clnt_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)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
[ Back to top | Remote Procedure Call (RPC) APIs | APIs by category ]