clnt_create_vers_timed Subroutine

Purpose

Creates and returns a generic client handle for a remote program and the registered version number that is the highest in the specified range with the specified timeout.

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>

clnt_create_vers_timed(host, prognum, progver_out, progver_low, progver_high, nettype, timeout)
const char *host;
const rpcprog_t prognum;
rpcvers_t *progver_out;
const rpcvers_t progver_low;
const rpcvers_t progver_high;
const char *nettype;
const struct timeval *timeout;

Description

The clnt_create_vers_timed subroutine creates and returns a generic client handle for the specified program and the highest registered version that falls within the range bounded by the values specified by the progver_low and progver_high parameters. You must specify the progver_low and progver_high parameters. When the function returns successfully, the value of the progver_out parameter is set to the highest registered version within the specified range (progver_low <= progver_out <= progver_high). The subroutine returns a generic client handle from the remote host where server is located. The operation is done with the available transport service of the class specified by the nettype parameter. The clnt_create_vers_timed subroutine uses first successful transport from the NETPATH environment variable and then from the netconfig database if required. The value of the timeout parameter indicates the maximum amount of time that is spent for each transport class.

Note: The subroutine returns a null value if no version is registered within the specified range or when the timeout value expires.

Parameters

Item	Description
host	Specifies the host name where the server resides.
prognum	Specifies the program number of the remote program.
versnum	Specifies the version number of the remote program.
progver_out	The highest version number that is registered at the server. The version number is returned within the specified range.
progver_low	The lower limit of the version number specified by the application.
progver_high	The upper limit of the version number specified by the application.
nettype	Defines a class of transports that can be used for a particular application.
timeout	Specifies the maximum time that is spent for each transport class in the nettype class.

Return Values

Item	Description
a generic client handle that is valid	successful
a null value	unsuccessful

Note: You can use the clnt_pcreateerror subroutine to obtain the reason for failure.

Error Codes

Item	Description
RPC_UNKNOWNPROTO	The value specified by the nettype parameter is not valid. The value specified by the nettype parameter is set to netpath, and the NETPATH environment variable is set to a transport service that is not valid.
RPC_UNKNOWNHOST	The host name is not valid.
RPC_PROGVERSMISMATCH	No version is registered at the server within the range bounded by the values specified by the progver_low and progver_high parameters.
RPC_TIMEDOUT	The timeout value has expired.
RPC_PROGNOTREGISTERED	The program number is not valid.

Examples

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

int main()
{
    CLIENT *cl;
    rpcprog_t PROGNUM = 0x3fffffffL;
    rpcvers_t PROGVER_OUT ;
    char *nettype = "visible";
    rpcvers_t PROGVER_LOW = 1;
    rpcvers_t PROGVER_HIGH = 10;
    struct timeval tv;
    char hostname[255] ; /* The Remote host on which the server resides */

    tv.tv_sec = 25;
    tv.tv_usec = 0;
      /*
    * make the clnt_create_vers_timed call with this nettype and
    * observe the result
    */
    if ((cl=clnt_create_vers_timed( hostname, PROGNUM, &PROGVER_OUT,
            PROGVER_LOW, PROGVER_HIGH, nettype, &tv)) == NULL)
    {
        fprintf(stdout, "clnt_create_vers_timed : failed.\n");
        exit(EXIT_FAILURE);
    }
    /* 
     * Make a call to clnt_call() subroutine 
     */
    /* Destroy the client handle at the end */
    clnt_destroy(cl);

     return 0;
}