clnt_create_vers Subroutine

Purpose

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

Library

Network Services Library (libnsl.a)

Syntax

#include <rpc/rpc.h>
clnt_create_vers(host, prognum, progver_out, progver_low, progver_high, nettype)
const char *host;
const rpcprog_t prognum;
rpcvers_t *progver_out;
const rpcvers_t progver_low;
const rpcvers_t progver_high;
const char *nettype;

Description

The clnt_create_vers 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 that is specified by the nettype parameter. The clnt_create_vers subroutine uses first successful transport from the NETPATH environment variable and then from the netconfig database if required. You can modify the default timeout value using the clnt_control subroutine.
Note: The subroutine returns a null value if no version is registered within the specified range.

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.

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

The clnt_create_vers subroutine returns failure when one or more of the following codes are true.

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_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;
    char hostname[255]; /* The Remote host on which the server resides */

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

     return 0;
}