PreviousNextIndex

Chapter 3: Clinfo C++ API


The Clinfo C++ API is an object-oriented interface that you can use in a C++ application to get status information about an HACMP for AIX 5L cluster. This chapter describes the specific C++ language objects and methods available in the Clinfo C++ API.

In addition to this chapter read Chapter 2: Clinfo C API, which describes the C API. The C++ API routines call the C API routines.

See the IBM C for AIX C/C++ Language Reference for more information on C++ and the AIX XL C++ compiler.

Note: If you upgrade to HACMP 5.3 and will be using the new version of Clinfo, you do not need to recompile because HACMP 5.3 contains changes to Clinfo that incorporates version information.
Note: HACMP 5.3 eliminated cl_registerwithclsmuxpd() API. Any pre or post-script compiled with this API will fail to load. Use application monitoring instead of the cl_registerwithclsmuxpd() routine. Refer to the section on Application Monitoring in Chapter 2: Initial Cluster Planning in the Planning Guide.

Clinfo C++ Object Classes

The Clinfo C++ API has the following object classes: clusters, nodes, network interfaces, and resource groups. Each network interface belongs to a single node; each node and each resource group belongs to a single cluster; this dictates the class structure. The cluster class is the most general, and the interface class is the most specific.

The grouping of functions into classes depends on the data that the functions use, with functions being placed into the most general possible class. Note that there are functions named CL_getclusterid in both the network interface and cluster classes. These are separate functions with the same name but distinguished by class. This naming convention is standard in C++.

All values are passed to the caller using the normal function return values, rather than function parameters passed by reference. When these descriptions talk about data being passed in, it is implicit that this data is coming from the object of which the function is a member.

Status is always returned in a CL_status arg, which is passed by reference and should be checked for error conditions. Return values are always data. An exception to this is the CL_isavail() function, whose primary return data is status, so it returns status rather than using the CL_status arg.

The Clinfo C++ API includes two functions that do not belong to any of the classes stated above. CL_getallinfo operates on an array of clusters rather than a cluster object. It returns an array of clusters, and the array pointer is passed by reference. CL_getlocalid operates on the local node rather than on a node object. The local host returns it’s own name.

Using the Clinfo C++ API in an Application

This section describes how to use the Clinfo C++ API in an application.

HACMP for AIX 5L includes separate libraries for multi-threaded and for single-threaded applications. Be sure to link with the appropriate library for your application.

Linking to the Clinfo C API

It is possible for C++ programs to call the Clinfo C API by using appropriate linkage directives, for example:

extern "C" int cl_getclusterid (char *); 

See the AIX XL C++/6000 V1.1.1 Language Reference for more information.

Linkage directives that allow C++ programs to call the Clinfo C API are included in clinfo.h. However, if you want a C++ API that is more object oriented, you may use the Clinfo C++ API.

The Clinfo C++ API defines object classes for cluster, node, and network interface. All Clinfo C++ functions that retrieve data from these objects are member functions (sometimes called methods) of these classes.

Header Files

You must specify the following include directive in each source module that uses the Clinfo C++ API:

#include <cluster/clinfo.H> 

The libclpp.a and libclpp_r.a Libraries

You must add the following directives to the object load command of a single-threaded application that uses the Clinfo C++ API:

-lclpp -lcl -lclstr 

You must add the following directive to the object load command of a multi-threaded application that uses the Clinfo C API:

-lclpp_r -lcl_r  -lclstr_r 

The libclpp.a and libclpp_r.a libraries hold the routines that support the Clinfo C++ API; the libcl.a and libcl_r.a libraries contain the routines that support the Clinfo C API.

To compile a C++ program under AIX 5L, use the xlC compiler.

Note: Clinfo’s cluster.es.client.lib library now contains the libcl.a with both 32- and 64-bit objects. You must recompile/relink your application in a 64-bit environment to get a 64-bit application using the Clinfo API.

Constants

The Clinfo C++ API routines use the following constants, defined in the clinfo.h file:

CL_MAXNAMELEN
The maximum length of a character string naming a cluster, node, or interface (256). The value of CL_MAXNAMELEN is the same as MAXHOSTNAMELEN, defined in the sys/param.h file.
CL_MAX_EN_REQS
The maximum number of event notification requests allowed (10).
CL_ERRMSG_LEN
Maximum error message length (128 characters).
CLSMUXPD_SVC_PORT
The constants CL_MAXCLUSTERS, CL_MAXNODES, and CL_MAXNETIFS used in previous versions of the software are replaced by macros that provide the current sizes of the various arrays in the data structure. The macros have the same name as the constants they replace. These macros cannot be used as array bounds in declaration statements, as the constants were used.
CL_MAXCLUSTERS
Provides current size of space in shared memory for the array holding information about the number of clusters.
CL_MAXNODES
Provides current size of space in shared memory for the array holding information about the number of nodes in a cluster.
CL_MAXNETIFS
Provides current size of space in shared memory for the array holding information about the number of interfaces attached to a node.
CL_MAXGROUPS
Provides current size of space in shared memory for the array holding information about the number of resource groups.

As an example, the following code fragment illustrates use of the constant CL_MAXNODES to size an array of cluster objects. An example of how to replace this with a call to the routine of the same name follows.

CL_cluster clusters[CL_MAXNODES]; 
CL_cluster *ret = &clusters[0]; 
ret = CL_getallinfo(ret, s); 
if (s < 0) 
cl_errmsg(s);
for (int i=0; i<CL_MAXNODES; i++) { 
printf("[%d] cl %d", i, ret[i].clc_clusterid);
printf(" st %d", ret[i].clc_state);
printf(" su %d", ret[i].clc_substate);
printf(" pr %d", ret[i].clc_primary);
printf(" na %s", ret[i].clc_name.name);
} 

You no longer use the constant CL_MAXNODES.

CL_cluster clusters[8]; 
CL_cluster *ret = &clusters[0]; 
int numclus; 
numclus = CL_getallinfo(ret, s);
if (s < 0) 
cl_perror(s, progname);
printf("number of clusters found: %d", numclus); 
for (int i=0; i<numclus; i++) { 
printf("[%d] cl %d", i, ret[i].clc_clusterid);
printf(" st %d", ret[i].clc_state);
printf(" su %d", ret[i].clc_substate);
printf(" pr %s", ret[i].clc_primary);
printf(" na %s", ret[i].clc_name.name);
} 

Data Types and Structures

The Clinfo C++ API uses the following data types and structures, defined in the clinfo.H file. The clinfo.H file also includes the sys/types.h, netinet/in.h, and clinfo.h files.

Basic Data Types and Class Definitions

The following data types translate the C data types defined in the clinfo.h file to C++.

typedef int CL_clusterid; 
typedef int CL_nodeid; 
typedef int CL_ifid; 
typedef struct sockaddr_in CL_ifaddr; 
typedef enum cls_state CL_state; 
typedef enum clss_substate CL_substate; 
typedef int CL_status; 
typedef int CL_groupid; 
typedef enum cl_rg_policies CL_rg_policies; 
typedef enum cl_resource_states CL_resource_states; 
class CL_clustername {public: char name[CL_MAXNAMELEN]; }; 
class CL_nodename {public: char name[CL_MAXNAMELEN]; }; 
class CL_ifname {public: char name[CL_MAXNAMELEN]; }; 
class CL_route { 
public:
CL_ifaddr localaddr;
CL_ifaddr remoteaddr;
}; 
class CL_groupname {public: char name[CL_MAXNAMELEN]; }; 
class CL_user_policy_name {public: char name[CL_MAXNAMELEN]; }; 

Cluster Object Class

Cluster class data and member functions:

class CL_cluster  { 
public:
CL_clusterid clc_clusterid; // Cluster Id
CL_state clc_state; // Cluster State
CL_substate clc_substate; // Cluster Substate
CL_nodename clc_primary; // Cluster Primary Node
CL_clustername clc_name; // Cluster Name
CL_node *clc_node; // Pointer to child node array
CL_group *clc_group; // pointer to child resource group array
int CL_getallinfo(CL_node*, CL_status&);
int CL_getgroupinfo(CL_group*, CL_status&);
CL_clusterid CL_getclusterid(CL_status&);
CL_cluster CL_getinfo(CL_status&);
CL_status CL_getprimary(CL_status&, CL_nodename);
CL_status CL_isavail();
CL_cluster& operator=(const struct cl_cluster&);
}; 

Network Interface Object Class

Network interface class data and member functions:

class CL_netif  { 
public:
CL_clusterid cli_clusterid; // Cluster Id
CL_nodeid cli_nodeid; // Cluster Node Id (internal)
CL_nodename cli_nodename; // Cluster Node name
CL_ifid cli_interfaceid; // Cluster Node Interface Id
CL_state cli_state; // Cluster Node Interface
// State
CL_ifname cli_name; // Cluster Node Interface
// Name
CL_ifaddr cli_addr; // Cluster Node Interface IP
// Address
CL_node *cli_pnode; // pointer to parent Node
// object
CL_clusterid CL_getclusterid(CL_status&);
CL_ifaddr CL_getifaddr(CL_status&);
CL_ifname CL_getifname(CL_status&);
CL_ifaddr CL_getnodeaddr(CL_status&);
CL_nodename CL_getnodenamebyif(CL_status&);
CL_status CL_isavail();
CL_netif& operator=(const struct cl_netif&);
}; 

Node Object Class

Node class data and member functions:

class CL_node  { 
public:
CL_clusterid cln_clusterid; // Cluster Id
CL_nodeid cln_nodeid; // Cluster Node Id (internal)
CL_nodename cln_nodename; // Cluster Node name
CL_state cln_state; // Cluster Node State
int cln_nif; // Cluster Node Number of
// Interfaces
CL_netif *cln_if; // Cluster Node
// interfaces
CL_cluster *cln_pcluster; // pointer to parent cluster
// object
CL_route CL_bestroute(CL_status&);
CL_node CL_getinfo(CL_status&);
CL_status CL_isavail();
CL_node& operator=(const struct cl_node&);
}; 
Note: The pointers to parent objects included in the object class data are provided in case you want to set up a tree structure of objects. These pointers are not filled by the Clinfo C++ API.

Resource Group Object Class

Resource Group data and member functions:

class CL_group  { 
    public: 
    CL_clusterid clg_clusterid;         // Cluster Id 
    CL_groupid clg_group_id             // Resource Group Id 
    CL_groupname clg_name;              // Resource group name 
    /* The following field is deprecated in HACMP 5.2 and will not be 
     * used. The data field itself is not removed from the data 
     * structures to maintain the backward compatibility */ 
        
    CL_rg_policies clg_policy;          // Resource Group Policy 
    CL_rg_policies clg_startup_policy; 
    CL_rg_policies clg_fallover_policy; 
    CL_rg_policies clg_fallback_policy; 
    CL_rg_policies clg_site_policy;     // Resource Group site policy 
    CL_user_policy_name clg_user_policy_name; 
        // User defined policy 
     
    int clg_num_nodes; 
    int clg_node_ids[MAXNODES];         // Node ids in this group 
     
    CL_resource_states clg_node_states[MAXNODES];  
       //and their state 
    CL_cluster *cln_pcluster;           
       // pointer to parent cluster object 
    CL_group CL_getinfo(CL_status&); 
    CL_group& operator=(const struct cl_group&); 
}; 
Note: The pointers to parent objects included in the object class data are provided in case you want to set up a tree structure of objects. These pointers are not filled by the Clinfo C++ API.

Functions Not Included in Any Object Class

The following functions are not included in any object class:

int CL_getallinfo (CL_cluster *, CL_status&); 

This function is not a member function of class CL_cluster, since it returns the number of clusters, as well as information about all clusters rather than a particular cluster object.

CL_node CL_getlocalid(CL_status&); 

This function is not a member function of class CL_node, since it returns information about the local host.

Assigning Class CL_netif data: cli_addr and cli_name

The following code illustrates how to assign network names and addresses. These assignments are used in the examples included on the reference pages in this chapter.

To assign a cli_addr, given char *addr = “1.2.3.4”:

netif.cli_addr.sin_family = AF_INET;
netif.cli_addr.sin_addr.s_addr = inet_addr(addr);

To assign a cli_name:

strcpy(netif.cli_name.name, "node_name");

Overloaded Assignment Operator

The = assignment operators for the classes CL_cluster, CL_netif, CL_group, and CL_node, are overloaded in order to assign the C structures cl_cluster, cl_netif, cl_group, and cl_node to their corresponding C++ CL_ classes.

Functions Called Using the Clinfo C API

The following functions have not been translated from C to C++. You must call them using the Clinfo C API:

Event Functions

int cl_registereventnotify(int, struct cli_enr_req_t *); 
int cl_unregistereventnotify(int, struct cli_enr_req_t *); 
int cl_getevent(cli_en_msg_t *); 

Utility Functions

void cl_perror(int, char *); 
char *cl_errmsg (int status); 
    /*for single-threaded applications*/ 
char *cl_errmsg_r(int status, char cbuf); 
    /*for multi-threaded applications*/ 

Upgrading Applications from Earlier Clinfo Releases

Earlier releases of Clinfo used integers to identify cluster nodes (node IDs) instead of character strings (node names).

The following sections give you some examples of how to convert calls in your application to various Clinfo C++ API routines that previously used a nodeid parameter. For each routine, an example of its use with node IDs is followed by an example using node names.

CL_getlocalid

This is an example of the CL_getlocalid routine from an earlier release that uses node ID:

CL_status s; 
CL_node lnode;lnode = node.CL_getlocalid(s); 
if (s < 0) 
cl_errmsg(s);
printf("cluster id = %d, node id = %d", lnode.cln_clusterid, 
lnode.cln_nodeid);

In the new version of the example of the C++ API CL_getlocalid routine, note the change in the printf statement.

// This function is not a member of a class.  
CL_status s; 
CL_node lnode; 
char cbuf[CL_ERRMSG_LEN]; 
lnode = CL_getlocalid(s); 
if (s < 0) 
cl_errmsg_r(s, cbuf);
printf("cluster id = %d, node name = %s", lnode.cln_clusterid, 
lnode.cln_nodename.name);

CL_isavail

The following is an example of the CL_isavail routine from an earlier release that uses node ID:

CL_status s; 
CL_netif netif; 
netif.cli_clusterid = 2; 
netif.cli_nodeid = 2; 
netif.cli_addr.sin_family = AF_INET; 
netif.cli_addr.sin_addr.s_addr = inet_addr(addr); 
s = netif.CL_isavail(); 
printf("status = %d", s); 

The new version of the example of the C++ API CL_isavail routine changes the assignment statement, since the previous version used cli_nodeid; now it is cln_name.name.

CL_status s; 
CL_netif netif; 
netif.cli_clusterid = 2; 
strcpy(netif.cln_name.name, "moby"); 
netif.cli_addr.sin_family = AF_INET; 
netif.cli_addr.sin_addr.s_addr = inet_addr(addr); 
s = netif.CL_isavail(); 
printf("status = %d", s); 

CL_getprimary

The following is an example of the CL_getprimary routine from an earlier release that uses node ID:

CL_cluster clus; 
CL_status s; 
CL_nodeid nid; 
clus.clc_clusterid = 2; 
nid = clus.CL_getprimary(s); 
if (s < 0) 
cl_errmsg(s);
printf("nodeid = %d", nid); 

The new version of the example of the C++ API CL_getprimary routine changes because a primary node is now recognized by its name (a string) rather than by an integer.

CL_clusterid clusterid; 
CL_cluster clus; 
CL_status status; 
CL_nodename name; 
CL_node node; 
char cbuf[CL_ERRMSG_LEN]; 
clus.clc_clusterid = 2; 
status = clus.CL_getprimary(cluster.clc_clusterid); 
if (status < 0) 
cl_errmsg_r(status, cbuf);
printf( "Cluster %d's primary node is %s", 
cluster.clc_clusterid, cluster.clc_primary.name);

Requests

The Clinfo C++ API has the following types of requests:

  • Cluster Information Requests
  • Node Information Requests
  • Network Interface Information Requests
  • Resource Group Information Requests.
  • Cluster Information Requests

    The following cluster information requests return information about a cluster:

    CL_getallinfo
    Calls the C function cl_getnodemap. This request is a member function associated with the cl_cluster class. The request returns information about all nodes in a cluster, given a cluster ID. A pointer to an array of node objects is passed as a reference argument to the function.
    CL_getallinfo
    Calls the C function cl_getclusters. Returns the number of clusters found. A pointer to an array of cluster objects is passed as a reference argument to the function. (When CL_getallinfo is called to get info on all clusters, the function is not a member function of the class CL_cluster.)
    CL_getclusterid
    Calls the C function cl_getclusterid, returns the cluster ID given a cluster name.
    CL_getinfo
    Calls the C function cl_getcluster. Returns information about the cluster with the specified cluster ID.
    CL_getprimary
    Calls the C function cl_getprimary. Returns the node name of the user-defined primary Cluster Manager in the specified cluster.
    CL_isavail
    Calls the C function cl_isclusteravail. Returns the status of the cluster with the specified cluster ID.
    CL_getgroupinfo
    Calls the C function cl_getgroupmap. Returns the number of resource groups found. A pointer to an array of resource group objects is passed as a reference object.

    Node Information Requests

    The following node information requests return information about the nodes in the cluster:

    CL_bestroute
    Calls the C function cl_bestroute. Returns the local/remote IP address pair that offers the most direct route to the specified node.
    CL_getinfo
    Calls the C function cl_getnode. Returns information about the node specified by a cluster ID/node name pair.
    CL_getlocalid
    Calls the C function cl_getlocalid. Returns a CL_node object that contains the cluster ID and node name of the host making the request. (This function is not a member function of the class CL_node.)
    CL_isavail
    Calls the C function cl_isnodeavail. Returns the status of the specified node, given its cluster ID and node name.

    Network Interface Information Requests

    The following network interface information requests return information about the interfaces connected to a node:

    CL_getclusterid
    Calls the C function cl_getclusteridbyifaddr or cl_getclusteridbyifname. Returns the cluster’s network interface name if the address is specified; returns its network interface address if the name is specified.
    CL_getifaddr
    Calls the C function cl_getifaddr. Returns the network interface address of the interface with the specified cluster ID and network interface name.
    CL_getifname
    Calls the C function cl_getifname. Returns the interface name of the interface with the specified cluster ID and network interface address.
    CL_getnodeaddr
    Calls the C function cl_getnodeaddr. Returns the network interface address associated with the specified cluster ID and network interface name.
    CL_getnodenamebyif
    Calls the C function cl_getnodenamebyifaddr or cl_getnodenamebyifname. Returns the node name by calling cl_getnodenamebyifaddr if the interface address is known, or by calling cl_getnodenamebyifname otherwise.
    CL_isavail
    Calls the C function cl_isaddravail. Returns the status of the specified network interface, given its cluster ID, node name, and network interface address.

    Resource Group Information Requests

    The following resource group information request returns information about cluster resource groups:

    CL_getinfo
    Returns all information about the specific resource group in the specified cluster.

    Event Notification Requests

    The following event notification routines return information about cluster, node, or network events. You must call these routines from the Clinfo C API.

    cl_getevent
    Gets information when an event signal is received, and returns an event notification message received from Clinfo.
    cl_registereventnotify
    Registers a list of event notification requests with Clinfo, and returns a signal to the calling process when a registered event occurs.
    cl_unregistereventnotify
    Unregisters a list of event notification requests with Clinfo.

    CL_getallinfo Routine

    Syntax

    int CL_getallinfo (CL_cluster *clusters, CL_status s) 
    

    Description

    Returns information about known clusters.

    Required Input Object Data

    None.

    Return Value

    *clusters
    A pointer to an array of cluster objects is passed as a reference argument to the function.
    int
    The number of clusters found.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.

    Example

      CL_status status; 
      CL_cluster clusters[8]; 
      CL_cluster *ret = &clusters[0]; 
      int numclus; 
      numclus = CL_getallinfo(ret, status); 
      if (status < 0) { 
             cl_perror(status, progname); 
      } else { 
            printf("number of clusters found: %d\n", numclus); 
            for (int i=0; i<numclus; i++) { 
                    printf("[%d] cl %d", i, ret[i].clc_clusterid); 
                    printf(" st %d", ret[i].clc_state); 
                    printf(" su %d", ret[i].clc_substate); 
                    printf(" pr %s", ret[i].clc_primary.name); 
                    printf(" na %s\n", ret[i].clc_name.name); 
            } 
      } 
    

    CL_getlocalid Routine

    Syntax

    CL_node CL_getlocalid (CL_status s) 
    

    Description

    Returns a CL_node object that contains the cluster ID and the node name of the host making the request. This request returns an error status on nodes not currently active in the cluster.

    Required Input Object Data

    None.

    Return Value

    CL_node
    Node object with local cluster and node name.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVNODE
    Node is not a cluster node.

    Example

    This example uses the cl_errmsg routine to illustrate proper programming for a single-threaded application. If your program is multi-threaded, you must use the cl_errmsg_r routine.

      CL_status status; 
      CL_node lnode; 
      lnode = CL_getlocalid(status); 
      if (status < 0) { 
          cl_errmsg(status); 
      } else { 
          printf("cluster id = %d, node name = %s\n", lnode.cln_clusterid, 
              lnode.cln_nodename.name); 
      } 
    

    CL_cluster::CL_getallinfo Routine

    Syntax

    int *CL_cluster::CL_getallinfo (CL_node *nodes, CL_status s) 
    

    Description

    Returns information about all the nodes in a cluster.

    Required Input Object Data

    CL_cluster::clc_clusterid
    The cluster ID of the desired cluster.

    Return Value

    nodes
    A pointer to an array of node objects is passed as a reference argument to the function.
    int
    The number of nodes in the cluster.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

    CL_cluster cluster; 
    CL_status status; 
    CL_node nodes[8]; 
    CL_node *ret = &nodes[0]; 
    int numnodes; 
    cluster.clc_clusterid = 1113325332; 
    numnodes = cluster.CL_getallinfo(ret, status); 
    if (status < 0) { 
      cl_perror(status, progname); 
    } else { 
      printf("number of nodes in cluster: %d\n", numnodes); 
      for (int i=0; i<numnodes; i++) { 
          printf("[%d] clusterid %d", i, ret[i].cln_clusterid); 
          printf(" nodeid %d", ret[i].cln_nodeid); 
          printf(" state %d", ret[i].cln_state); 
          printf(" interfaces %d\n", ret[i].cln_nif); 
      } 
    } 
    

    CL_cluster::CL_getclusterid Routine

    Syntax

    CL_clusterid CL_cluster::CL_getclusterid(CL_status s) 
    

    Description

    The CL_getclusterid routine returns the cluster ID of the cluster with the specified name.

    Required Input Object Data

    CL_cluster::clc_name
    Name of target cluster.

    Return Value

    CL_clusterid
    The desired cluster ID.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERNAME
    The request specified an invalid cluster name.

    Example

        CL_cluster cluster; 
        CL_status status; 
        CL_clusterid clusterid; 
        char cbuf[CL_ERRMSG_LEN]; 
        strcpy(cluster.clc_name.name, "site1"); 
        clusterid = cluster.CL_getclusterid(status); 
        if (status < 0) { 
    	cl_errmsg(status); 
        } else { 
    	printf("clusterid = %d\n", clusterid); 
        } 
    } 
    

    CL_cluster::CL_getinfo Routine

    Syntax

    CL_cluster CL_cluster::CL_getinfo (CL_status s) 
    

    Description

    The CL_getinfo routine returns information about the cluster specified by the cluster ID.

    Required Input Object Data

    CL_cluster::clc_clusterid
    ID of target cluster.

    Return Value

    CL_cluster
    Information about the specified cluster.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

    CL_cluster cluster; 
    CL_status status; 
    CL_cluster ret; 
    char cbuf[CL_ERRMSG_LEN]; 
    cluster.clc_clusterid = 1113325332; 
    ret = cluster.CL_getinfo(status); 
    if (status < 0) { 
      cl_errmsg(status); 
    } else { 
      printf("clusterid %d ", ret.clc_clusterid); 
      printf("state %d ", ret.clc_state); 
      printf("substate %d ", ret.clc_substate); 
      printf("primary %s ", ret.clc_primary.name); 
      printf("name %s\n", ret.clc_name.name); 
    } 
    

    CL_cluster::CL_getprimary Routine

    Syntax

    CL_nodename CL_cluster::CL_getprimary (CL_status s) 
    

    Description

    Returns the node name of the user-designated primary Cluster Manager for the specified cluster.

    Required Input Object Data

    CL_cluster::clc_clusterid
    The cluster ID for which the primary ID is desired.

    Return Value

    CL_nodename
    The node name of the primary Cluster Manager.

    Status Value

    CL_status status
    Status passed by reference. Output parameter for the return codes.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_NOPRIMARY
    No primary information is available. This status usually indicates that the user has not designated a primary cluster manager.
    CLE_IVCLUSTER
    The cluster is not available.

    Example

    CL_cluster cluster;
    CL_status status;
    CL_nodename name;
    cluster.clc_clusterid = 1;
    name = cluster.CL_getprimary(status);
    if (status < 0) {
    cl_errmsg(status);
    } else {
    printf( "cluster %d's primary node is %s\n",
    cluster.clc_clusterid, cluster.clc_primary.name);
    }

    CL_cluster::CL_isavail Routine

    Syntax

    CL_status CL_cluster::CL_isavail() 
    

    Description

    Returns the status code CLE_OK if the specified cluster is available.

    Required Input Object Data

    CL_cluster::clc_clusterid
    The cluster ID of the desired cluster.

    Return Value

    CL_status
    Status of the specified cluster.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_IVCLUSTER
    The request specified an invalid cluster.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

    CL_status status; 
      CL_cluster cluster; 
      cluster.clc_clusterid = 1113325332; 
      status = cluster.CL_isavail(); 
      printf("status = %d\n", status); 
    

    CL_cluster::CL_getgroupinfo Routine

    Syntax

    int CL_cluster::CL_getgroupinfo (CL_group *groups, CL_status&); 
    

    Description

    Returns information about all the resource groups in the cluster.

    Required Input Object Data

    CL_cluster::clc_clusterid
    The cluster ID of the desired cluster.

    Return Value

    groups
    A pointer to a group of resource group objects is passed as a reference argument to the function.
    int
    The number of resource groups in the cluster

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

      CL_status status; 
      CL_cluster cluster; 
      CL_group groups[MAXGROUPS]; 
      int numgroups; 
      cluster.clc_clusterid = 1113325332; 
      numgroups = cluster.CL_getgroupinfo(&groups[0], status); 
      if (status < 0) { 
        cl_perror(status, progname); 
      } else { 
        printf("There are %d groups in cluster %d\n", numgroups, 
        cluster.clc_clusterid); 
        for (int i=0; i<numgroups; i++) { 
          printf("Group %d is id %d\n", i, groups[i].clg_group_id); 
          printf("Group %d is %s and has %d nodes\n", 
          i, groups[i].clg_name.name, groups[i].clg_num_nodes); 
        } 
      } 
    

    CL_group::CL_getinfo Routine

    Syntax

    CL_Group::CL_getinfo (CL_status s); 
    

    Description

    Returns a group object that contains information about the group, given a group object with the cluster ID and group name.

    Required Input Object Data

    CL_group::clg_clusterid
    Cluster ID of the desired resource group.
    CL_group::clg_name.name
    Name of the resource group.

    Return Value

    CL_group
    The desired resource group and its full information.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNODENAME
    The request specified an invalid node name.

    Example

      CL_status status; 
      CL_group group; 
      CL_group ret; 
      group.clg_clusterid = 1113325332; 
      strcpy(group.clg_name.name, "rg01"); 
      ret = group.CL_getinfo(status); 
      if (status < 0) { 
        cl_perror(status, progname); 
      } else { 
        printf("There are %d nodes in group %s\n", 
        ret.clg_num_nodes, ret.clg_name.name); 
      } 
    

    CL_netif::CL_getclusterid Routine

    Syntax

    CL_clusterid CL_netif::CL_getclusterid (CL_status s) 
    

    Description

    Returns the name of the cluster with the specified network interface address. Alternatively, returns the network interface address of a cluster given its network interface name.

    Required Input Object Data

    CL_netif::cli_addr
    The network interface address whose cluster ID is desired.

    or

    CL_netif::cli_name
    The network interface name whose cluster ID is desired.

    Return Value

    CL_clusterid
    The cluster ID (a non-negative integer).

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVADDRESS
    The request specified an invalid network interface address.
    CLE_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

    // example using interface name 
    CL_status status; 
    CL_clusterid clid; 
    CL_netif netif; 
    strcpy(netif.cli_name.name, "geotest9"); 
    netif.cli_addr.sin_addr.s_addr = NULL; 
    clid = netif.CL_getclusterid(status); 
    if (status < 0) { 
      cl_errmsg(status); 
    } else { 
      printf("clusterid = %d\n", clid); 
    } 
    // example using interface address 
      CL_status status; 
      CL_clusterid clusterid; 
      CL_netif netif; 
      char *addr = "1.1.1.7"; 
      netif.cli_addr.sin_family = AF_INET; 
      netif.cli_addr.sin_addr.s_addr = inet_addr(addr); 
      netif.cli_name.name[0] = NULL; 
      clusterid = netif.CL_getclusterid(status); 
      if (status < 0) { 
           cl_errmsg(status); 
      } else { 
           printf("clusterid = %d\n", clusterid); 
      } 
    

    CL_netif::CL_getifaddr Routine

    Syntax

    CL_ifaddr CL_netif::CL_getifaddr (CL_status s) 
    

    Description

    Returns the network interface address of the interface with the specified cluster ID and network interface name.

    Required Input Object Data

    CL_netif::cli_clusterid
    The cluster ID of the desired network interface.
    CL_netif::cli_name
    The name of the desired network interface.

    Return Value

    CL_ifaddr
    The network interface address desired.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. Usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

    CL_status status; 
    CL_ifaddr ifaddr; 
    CL_netif netif; 
    char cbuf[CL_ERRMSG_LEN]; 
    netif.cli_clusterid = 1113325332; 
    strcpy(netif.cli_name.name, "geotest9"); 
    ifaddr = netif.CL_getifaddr(status); 
    if (status < 0) { 
      cl_errmsg(status); 
    } else { 
      printf("ifaddr = %s\n", inet_ntoa(ifaddr.sin_addr)); 
    } 
    

    CL_netif::CL_getifname Routine

    Syntax

    CL_ifname CL_netif::CL_getifname (CL_status s) 
    

    Description

    Returns the network interface name, given a cluster ID and network interface address; or, given a cluster ID and node name, returns a network interface name.

    If the request specifies a cli_addr parameter, Clinfo examines the network portion of the address and seeks an interface on the same network. If a match is found, the CL_getifname routine returns the name associated with that interface.

    If the cli_addr parameter is NULL, Clinfo decides which interface on the specified node is most easily accessed from the local host, and the CL_getifname routine returns the name associated with that interface. If both interfaces are equally accessible from the local node, Clinfo chooses one and returns the name associated with that interface.

    In all cases, the CL_getifname routine returns the name as a NULL-terminated string.

    Required Input Object Data

    CL_netif::cli_clusterid, cli_addr
    The cluster ID of the desired network interface and the network interface address.

    or

    CL_netif::cli_clusterid, cli_nodename
    The cluster ID and node name of the desired network interface.

    Return Value

    CL_ifname
    The network interface name.

    Status Values

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVADDRESS
    The request specified an invalid network interface address.
    CLE_IVNODENAME
    The request specified an invalid node name.

    Example

    // CL_netif::CL_getifname get interfacename given clusterid and nodename 
      CL_status status; 
      char cbuf[CL_ERRMSG_LEN]; 
      CL_ifname ifname; 
      CL_netif netif; 
      netif.cli_addr.sin_addr.s_addr = NULL; 
      netif.cli_clusterid = 1113325332; 
      strcpy (netif.cli_nodename.name, "node1"); 
      ifname = netif.CL_getifname(status); 
      if (status < 0) { 
         cl_errmsg(status); 
      } else { 
         printf("ifname = %s\n", ifname.name); 
      } 
    

    CL_netif::CL_getnodeaddr Routine

    Syntax

    CL_ifaddr CL_netif::CL_getnodeaddr(CL_status s) 
    

    Description

    Returns the IP address associated with the specified cluster ID and network interface name.

    Required Input Object Data

    CL_netif::cli_clusterid
    The cluster ID of the desired network interface.
    CL_netif::cli_name
    The name of the desired network interface.

    Return Value

    CL_ifaddr
    Network interface address.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

    CL_status status; 
    CL_netif netif; 
    CL_ifaddr ifaddr; 
    char cbuf[CL_ERRMSG_LEN]; 
    netif.cli_clusterid = 1113325332; 
    strcpy(netif.cli_name.name, "geotest9"); 
    ifaddr = netif.CL_getnodeaddr(status); 
    if (status < 0) { 
      cl_errmsg(status); 
    } else { 
      printf("ifaddr = %s\n", inet_ntoa(ifaddr.sin_addr)); 
    } 
    

    CL_netif::CL_getnodenamebyif Routine

    Syntax

    CL_nodename CL_netif::CL_getnodenamebyif (CL_status s) 
    

    Description

    Returns the node name when given either a cluster ID and a network interface address or a cluster ID and a network interface name.

    If the network interface address is specified and cli_name is NULL, then cli_name is returned. Conversely, if cli_name is given and cli_addr is NULL, cli_addr is returned. If both cli_name and cli_addr are non-NULL, cli_addr takes precedence. If both are NULL, the error code CLE_ BADARGS is returned.

    Note: This routine replaces the CL_getnodename routine, which was available in previous releases.

    Required Input Object Data

    CL_netif::cli_clusterid, cli_addr
    The cluster ID of the desired node, and the network interface address of the node.

    or

    CL_netif::cli_clusterid, cli_name
    The cluster ID of the desired node, and the name of the network interface.

    Return Value

    CL_nodename
    The node name.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVADDRESS
    The request specified an invalid network interface address.
    CLE_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

    CL_status status; 
    char cbuf[CL_ERRMSG_LEN]; 
    CL_nodename nname; 
    CL_netif netif; 
    char *addr = "9.57.28.23"; 
    netif.cli_clusterid = 1113325332; 
    netif.cli_addr.sin_family = AF_INET; 
    netif.cli_addr.sin_addr.s_addr = inet_addr(addr); 
    netif.cli_name.name[0] = NULL; 
    nname = netif.CL_getnodenamebyif(status); 
    if (status < 0) { 
       cl_errmsg(status); 
    } else { 
       printf("node name = %s\n", nname.name); 
    } 
    

    CL_netif::CL_isavail Routine

    Syntax

    CL_status CL_netif::CL_isavail() 
    

    Description

    Returns the status code CLE_OK if the specified network interface is available.

    Required Input Object Data

    CL_netif::cli_clusterid
    The cluster ID of the desired network interface.
    CL_netif::cli_nodename
    The node name of the desired network interface.
    CL_netif::cli_addr
    The address of the desired network interface.

    Return Value

    CL_status
    Status of the specified network interface.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNODENAME
    The request specified an invalid node name.
    CLE_IVADDRESS
    The request specified an invalid interface address.
    CLE_IVNETIF
    The network interface is not available.

    Example

    CL_status status; 
    CL_netif netif; 
    char *addr = "9.57.28.23"; 
    netif.cli_clusterid = 1113325332; 
    strcpy(netif.cli_name.name, "geotest9"); 
    netif.cli_addr.sin_family = AF_INET; 
    netif.cli_addr.sin_addr.s_addr = inet_addr(addr); 
    strcpy(netif.cli_nodename.name, "node1"); 
    status = netif.CL_isavail(); 
    if (status < 0) { 
         cl_perror(status,"netif.CL_isavail failed"); 
    } 
    printf("status = %d\n", status); 
    

    CL_node::CL_bestroute Routine

    Syntax

    CL_route CL_node::CL_bestroute(CL_status s) 
    

    Description

    The CL_bestroute routine returns the local/remote IP address pair for the most direct route to the node specified in the object.

    The route returned by the CL_bestroute routine depends on the node making the request. Clinfo first builds a list of all working network interfaces on the local node, and then compares this list to the available interfaces on the specified node. The routine first compares HACMP-defined private interfaces (such as a serial optical channel) to local interfaces. If no match is found, the routine then compares HACMP-defined public interfaces to local interfaces. If there is still no match, the routine selects the first defined interface on the local node and the first defined interface on the remote node.

    If a pair of local and remote interfaces exist that are on the same network, they are returned in CL_route. Otherwise, an interface on the specified node is chosen as the remote interface, and the primary local interface is returned as the local end of the route.

    Required Input Object Data

    CL_node::cln_clusterid, cln_nodename
    Cluster ID and node name of target node.

    Return Value

    CL_route
    Local/remote IP address pair that indicates the most direct route to the specified node.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_NOROUTE
    No route available.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNODENAME
    The request specified an invalid node name.

    Example

    CL_status status; 
    CL_node node; 
    CL_route route; 
    char cbuf[CL_ERRMSG_LEN]; 
    node.cln_clusterid = 1113325332; 
    strcpy(node.cln_nodename.name, "node1"); 
    route = node.CL_bestroute(status); 
    if (status < 0) { 
      cl_errmsg(status); 
    } else { 
      // don't call inet_ntoa twice in one printf! 
      printf("local = %s  ", inet_ntoa(route.localaddr.sin_addr)); 
      printf("remote = %s\n", inet_ntoa(route.remoteaddr.sin_addr)); 
    } 
    

    CL_node::CL_getinfo Routine

    Syntax

    CL_node CL_node::CL_getinfo(CL_status s) 
    

    Description

    Returns a node object that contains information about the node, given a node object with a cluster ID and node name.

    Required Input Object Data

    CL_node::cln_clusterid
    Cluster ID of target node.
    CL_node::cln_nodename
    Node name of target node.

    Return Value

    CL_node
    The desired node and its information.

    Status Value

    CL_status s
    Status passed by reference. Output parameter that holds the return code.
    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for an output parameter address.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNODENAME
    The request specified an invalid node name.

    Example

    CL_status status; 
    CL_node node; 
    CL_node ret; 
    char cbuf[CL_ERRMSG_LEN]; 
    node.cln_clusterid = 1113325332; 
    strcpy(node.cln_nodename.name, "node1"); 
    ret = node.CL_getinfo(status); 
    if (status < 0) { 
        cl_errmsg(status); 
    } else { 
        printf("clusterid %d  ", ret.cln_clusterid); 
        printf("nodename %s  ", ret.cln_nodename.name); 
        printf("state %d  ", ret.cln_state); 
        printf("nif %d\n", ret.cln_nif); 
    } 
    

    CL_node::CL_isavail Routine

    Syntax

    CL_status CL_node::CL_isavail() 
    

    Description

    Returns the status code CLE_OK if the specified node is available.

    Required Input Object Data

    CL_node::cln_clusterid
    The cluster ID of the desired node.
    CL_node::cln_nodename
    The node name of the desired node.

    Return Value

    CL_status
    Status of the specified node.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNODENAME
    The request specified an invalid node name.
    CLE_IVNODE
    The node is not available.

    Example

    CL_status status; 
    CL_node node; 
    node.cln_clusterid = 1113325332; 
    strcpy(node.cln_nodename.name, "node1"); 
    status = node.CL_isavail(); 
    printf("status = %d\n", status); 
    

    PreviousNextIndex