PreviousNextIndex

Chapter 2: Clinfo C API


The Clinfo C Application Programming Interface (API) is a high-level interface that you can use in an application to get status information about an HACMP cluster. This chapter describes the specific C language routines and utilities available in the Clinfo C API. It contains the following sections:

  • Using the Clinfo C API in an Application
  • Upgrading Applications from Earlier Clinfo Releases
  • Memory Allocation Routines
  • Requests
  • Utilities
  • Routines.
  • Note: HACMP 5.3 eliminated cl_registerwithclsmuxpd() API. Any application compiled with this API will fail to load. Use application monitoring instead of the cl_registerwithclsmuxpd() routine. See the section on Application Monitoring in Chapter 2: Initial Cluster Planning in the Planning Guide.

    Before reading this chapter, you should read Chapter 1: Cluster Information Program, which describes the types of information Clinfo maintains about an HACMP cluster.

    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.

    Note: The Clinfo cluster.es.client.lib library 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.

    Header Files

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

    #include <sys/types.h> 
    #include <netinet/in.h> 
    #include <cluster/clinfo.h> 
    

    In addition to this list of include directives, specify the following include directive in each source module that uses the cl_registereventnotify routine:

    #include <signal.h> 
    

    Compiler Preprocessor Directives for Applications Using Client APIs

    When compiling applications using client APIs, use the compiler flag --D__HAES__. This is required because of the #ifdef preprocessor directives used in the header files. This is due to previous support of another version of HACMP (HAS).

    Linking the libcl.a and libcl_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:

    -lcl  
    

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

    -lcl_r  
    

    The libcl.a and libcl_r.a libraries contain the routines that support the Clinfo C 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).

    Macros

    HACMP 5.2 replaced the constants CL_MAXCLUSTERS, CL_MAXNODES, and CL_MAXNETIFS with macros that provide the current sizes of the various arrays in the data structures. The macros have the same name as the constants they replace. You cannot use these macros as array bounds in declaration statements.

    CL_MAXCLUSTERS
    Provides current size of space in data structures for the array holding information about the number of clusters.
    CL_MAXNODES
    Provides current size of space in data structures for the array holding information about the number of nodes in a cluster.
    CL_MAXNETIFS
    Provides current size of space in data structures for the array holding information about the number of interfaces attached to a node.
    CL_MAXGROUPS
    Provides current size of space in data structures for the array holding information about the number of resource groups.

    Data Types and Structures

    The Clinfo C API uses the following data types and structures, defined in the clinfo.h file.

  • Enumerated Type Containing State Information
  • Enumerated Type Containing Substate Information
  • Enumerated Type Containing Resource Group State
  • Enumerated Type Containing Resource Group Policies
  • Enumerated Type Containing Interface Roles
  • Enumerated Type Containing Network Attribute
  • Enumerated Type Containing Site Priority
  • Enumerated Type Containing Site Backup Communication Methods
  • Data Structure Representing a Resource Group
  • Data Structure Representing a Network Interface
  • Data Structure Representing a Node
  • Data Structure Representing a Cluster
  • Data Structure Representing an Event Notification Registration Request
  • Data Structure Representing an Event Notification Message
  • Data Structure Representing a Cluster Network
  • Data Structure Representing a Cluster Site.
  • Enumerated Type Containing State Information

    The following enumerated data type describes the state of a cluster, node, interface, or event notification:

    enum cls_state { 
        CLS_INVALID, 
        CLS_VALID, 
        CLS_UP, 
        CLS_DOWN, 
        CLS_UNKNOWN, 
        CLS_GRACE, 
        CLS_JOINING, 
        CLS_LEAVING, 
        CLS_IN_USE, 
        CLS_PRIMARY 
    }; 
    

    Enumerated Type Containing Substate Information

    The following enumerated data type describes the substate of a cluster:

    enum cls_substate { 
        CLSS_UNKNOWN, 
        CLSS_STABLE, 
        CLSS_UNSTABLE, 
        CLSS_ERROR, 
        CLSS_RECONFIG 
        CLSS_NOT_CONFIGURED 
    }; 
    

    Enumerated Type Containing Resource Group State

    The following enumerated data type contains all states a resource group can be in on a node:

    enum cl_resource_states{ 
        CL_RGNS_INVALID=1, 
        CL_RGNS_ONLINE=2, 
        CL_RGNS_OFFLINE=4, 
        CL_RGNS_ACQUIRING=16, 
        CL_RGNS_RELEASING=32, 
        CL_RGNS_ERROR=64 
    }; 
    

    Enumerated Type Containing Resource Group Policies

    The following enumerated data type contains all resource group policies (both node and site):

    enum cl_rg_policies { 
        CL_RGP_INVALID = 0, 
        CL_RGP_ONLINE_ON_HOME_NODE = 1, 
        CL_RGP_ONLINE_ONFIRST_AVAILBLE_NODE = 2, 
        CL_RGP_ONLINE_USING_DISTRIBUTION_POLICY = 3, 
        CL_RGP_ONLINE_ALL_NODES = 4, 
        CL_RGP_FALLOVER_TO_PRIORITY_NODE = 5, 
        CL_RGP_FALLOVER_USING_DNP = 6, 
        CL_RGP_BRING_OFFLINE = 7, 
        CL_RGP_FALLBACK_TO_HIGHER_PRIORITY_NODE = 8, 
        CL_RGP_NEVER_FALLBACK = 9, 
        CL_RGP_PREFER_PRIMARY_SITE = 10, 
        CL_RGP_ONLINE_ON_EITHER_SITE = 11, 
        CL_RGP_ONLINE_ON_BOTH_SITES = 12, 
        CL_RGP_IGNORE_SITES = 13 
    }; 
    

    Enumerated Type Containing Interface Roles

    enum cl_interface_role {  
        CL_INT_ROLE_INVALID = 0,  
        CL_INT_ROLE_SERVICE = 16,  
        CL_INT_ROLE_STANDBY = 32,      /* deprecated */  
        CL_INT_ROLE_BOOT = 64,  
        CL_INT_ROLE_SH_SERVICE = 128,  /* deprecated */ 
    }; 
    

    Enumerated Type Containing Network Attribute

    The following enumerated data type specifies the attributes for a network:

    /*  
    * Enumeration of Network attributes. Note that the public/private attribute is for 
    use by Oracle only - HACMP does not use this attribute. 
    */  
    enum cl_network_attribute 
    { 
        CL_NET_ATTR_INVALID = 0, /* IP networks can be public or private */ 
        CL_NET_TYPE_PUBLIC = 1, 
        CL_NET_TYPE_PRIVATE = 2, /* non-IP (serial) networks are always */ 
        CL_NET_TYPE_SERIAL = 4  
    }; 
    

    Enumerated Type Containing Site Priority

    The following enumerated data type describes the priority for a site. Sites are defined as having a priority when processing resources.

    /*  
    * Enumeration of Site Priorities 
    */ 
    enum cl_site_priority 
    { 
        CL_SITE_PRI_NONE = 0, 
        CL_SITE_PRI_PRIMARY = 1, 
        CL_SITE_PRI_SECONDARY = 2, 
        CL_SITE_PRI_TERTIARY = 4 
    }; 
    

    Enumerated Type Containing Site Backup Communication Methods

    The following enumerated data type contains optional backup methods that can be configured for a site:

    /*  
    * Enumeration of Site Backup Communication Options 
    */  
    enum cl_site_backup 
    { 
        CL_SITE_BACKUP_NONE = 0, 
        CL_SITE_BACKUP_DBFS = 1, 
        CL_SITE_BACKUP_SGN = 2 
    }; 
    

    Data Structure Representing a Resource Group

    The following structure contains all information available for each resource group:

    struct cl_group { 
        int  clg_clusterid; 
        int  clg_group_id; 
        char clg_name[CL_MAXNAMELEN]; 
        enum cl_rg_policies clg_policy;          /* deprecated */ 
        enum cl_rg_policies clg_startup_policy; 
        enum cl_rg_policies clg_fallover_policy;  
        enum cl_rg_policies clg_fallback_policy; 
        enum cl_rg_policies clg_site_policy;  
        char clg_user_policy_name[CL_MAXNAMELEN]; 
        int  clg_num_nodes; 
        int  clg_node_ids[MAXNODES]; 
            /* list of nodes (ids) in this group */ 
        enum cl_resource_states clg_node_states[MAXNODES]; 
            /* state on each */ 
        int  clg_num_resources; 
        int  clg_resource_id[MAXRESOURCES];  
            /* list of resources (id) group */ 
        enum cl_resource_states clg_res_state[MAXRESOURCES]; /* state  
           */ int clg_vrmf;                      /* version of this client */ 
    };  
    

    Data Structure Representing a Network Interface

    The following data structure represents a network interface:

    struct cl_netif { 
        int cli_clusterid;               /* Cluster Id */  
        int cli_nodeid;                  /* Cluster node Id - used internally only */  
        char cli_nodename[CL_MAXNAMELEN];/* Cluster node name */ 
        int cli_interfaceid;             /* Cluster Node Interface Id */  
        enum cls_state cli_state;        /* Cluster Node Interface State */  
        char cli_name[CL_MAXNAMELEN];    /* Cluster Node Interface Name */  
        struct sockaddr_in cli_addr;     /* Cluster Node Interface IP Address */  
        int cli_active_nodeid;           /* Cluster node Id where addr is up */  
        enum cl_interface_role cli_role; /* Role of interface (boot/service)*/  
        int cli_networkid;               /* Cluster Network ID for this Interface */ 
        int cli_vrmf;        
    };  
    

    Data Structure Representing a Node

    The following data structure represents a cluster node:

    struct cl_node { 
        int cln_clusterid;                 /* Cluster Id */ 
        int cln_nodeid;                    /* Cluster node Id */ 
        char cln_nodename[CL_MAXNAMELEN];  /* Cluster node name */ 
        enum cls_state cln_state;          /* node state */ 
        int cln_nif;                       /* number of interfaces */ 
        struct cl_netif *cln_if;           /* interfaces */ 
        int cln_glidle;                    /* CPU.glidle */ 
        int cln_real_mem_free;             /* Paging space utilitization */ 
        int cln_disk_busy;                 /* disk busy */ 
        int cln_vrmf;                      /* version of this client */ 
    };  
    

    Data Structure Representing a Cluster

    The following data structure represents a cluster:

    struct cl_cluster{ 
        int  clc_clusterid;               /* cluster id*/ 
        enum cls_state clc_state;         /* Cluster State */ 
        enum cls_substate clc_substate;   /* Cluster Substate */ 
        char clc_primary[CL_MAXNAMELEN];  /* Cluster Primary Node */ 
        char clc_name[CL_MAXNAMELEN];     /* Cluster Name */ 
        int  clc_number_of_nodes;	      /* number of cluster nodes */ 
        int  clc_number_of_groups;	      /* number of resource groups */ 
        int  clc_number_of_networks;      /* number of networks */ 
        int  clc_number_of_sites;	      /* number of sites */ 
        int clc_vrmf;		      /* version of this client */ 
    }; 
    

    Data Structure Representing an Event Notification Registration Request

    The following data structure represents an event notification registration request:

    struct cli_enr_req_t { 
        int event_id;                  /* event id */ 
        int cluster_id;                /* cluster id */ 
        int node_id;                   /* node id(internal use only)*/ 
        char node_name[CL_MAXNAMELEN]; /* node name */ 
        int net_id;                    /* network id */ 
        int signal_id;                 /* signal id */ 
        int vrmf; 
    }; 
    

    Data Structure Representing an Event Notification Message

    The following data structure represents an event notification message:

    struct cli_en_msg_t { 
        int event_id;                  /* event id */ 
        int cluster_id;                /* cluster id */ 
        int node_id;                   /* node id(internal use only)*/ 
        char node_name[CL_MAXNAMELEN]; /* node name */ 
        int net_id;                    /* network id */ 
        int vrmf; 
    }; 
    

    Data Structure Representing a Cluster Network

    The following data structure contains information for each cluster network:

    /*  
    * Structure containing information relating to a network. 
    */  
    struct cl_net { 
        int clnet_clusterid;                  /* Cluster Id */ 
        char clnet_name[CL_MAXNAMELEN];       /* Cluster network name */ 
        int clnet_id;                         /* Cluster Network Id */ 
        char clnet_type[CL_MAXNAMELEN];       /* ether, token, etc */ 
        enum cl_network_attribute clnet_attr; /* public/serial */  
        enum cls_state clnet_state;           /* Cluster Network State */ 
            /* Note that this is the cluster wide or "global" network state */ 
            /* which may be different than the state of the network on any */ 
            /* particular node */ 
        int clnet_numnodes;           
            /* Number of nodes connected to this Network */ 
        int clnet_node_ids[MAXNODES]; 
            /* Node ids connected to this Network */ 
        enum cls_state clnet_node_states[MAXNODES];  
            /* Network State per Node */ 
        int clnet_vrmf;			  /* version of this client */ 
    }; 
    

    Data Structure Representing a Cluster Site

    The following data structure contains information for each site configured in an HACMP cluster. Note that site configuration is optional.

    /*  
    * Structure containing information relating to a site 
    */  
    struct cl_site { 
        int clsite_clusterid;                 /* Cluster Id */ 
        int clsite_id; 
        char clsite_name[CL_MAXNAMELEN]; 
        enum cl_site_priority clsite_priority; 
        enum cl_site_backup clsite_backup; 
        enum cls_state clsite_state;          /* Cluster Site State */ 
        int clsite_numnodes; 
        int clsite_nodeids[MAXNODES];         /* List of nodes (ids) in this group */ 
        int clsite_vrmf;                      /* version of this client */ 
    }; 
    

    Upgrading Applications from Earlier Clinfo Releases

    In prior releases of HACMP, the cluster ID was configured manually; it is now created automatically. There are several calls that will return the cluster ID, given the cluster name or other parameters:

  • cl_getclusterid—given a cluster name, returns cluster ID
  • cl_getclusteridbyifaddr—given a network interface address, returns cluster ID
  • cl_getclusteridbyifname—given a network interface name, returns cluster ID.
  • If your application uses API calls that require the cluster ID, you must add a call to one of these routines that return the cluster ID.

    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

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

    int clusterid, nodeid, status; 
    status = cl_getlocalid (&clusterid, &nodeid); 
    if (status != CLE_OK) { 
        if (status == CLE_IVNODE) { 
            printf ("This node is not a cluster member"); 
        } else { 
            cl_perror (status, "Can't get local cluster ID"); 
            } 
    } else { 
        printf ("member of cluster %d node %d",clusterid, nodeid); 
    } 
    

    In the new version of the example of the C API cl_getlocalid routine, note the change in the declaration statement. Where previously all variables were declared as int, now you must declare nodename as a character string and make the corresponding changes to the printf statements.

    int clusterid, status; 
    char nodename[CL_MAXNAMELEN]; 
    status = cl_getlocalid (&clusterid, nodename); 
    if (status != CLE_OK) { 
        if (status == CLE_IVNODE) { 
            printf ("This node is not a cluster member"); 
        } else { 
            cl_perror (status, "Can't get local cluster ID"); 
        } 
    } else { 
        printf ("member of cluster %d node %s",clusterid, nodename); 
    } 
    

    cl_getnodeidbyifname

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

    int clusterid, nodeid; 
    char *interfacename; 
    strcpy (interfacename,"editserver"); 
    clusterid = 1; 
    nodeid = cl_getnodeidbyifname (clusterid, interfacename); 
    if (nodeid < 0) { 
        cl_perror(nodeid,"Can't get node ID"); 
    } else { 
        printf("ID of %s on cluster %d is %d", interfacename, clusterid, nodeid); 
    } 
    

    In the new version of the example of the C API cl_getnodeidbyifname routine, note that the name of the routine itself has changed to cl_getnodenamebyifname. You must change the declaration to include nodename as a string, instead of nodeid as an int; then make the corresponding changes to the printf statements.

    int clusterid, status; 
    char nodename[MAXNAMELEN]; 
    char *interfacename[MAXNAMELEN]; 
    strcpy (interfacename,"editserver"); 
    clusterid = 1; 
    status = cl_getnodenamebyifname (clusterid, interfacename, nodename); 
    if (status != CLE_OK)  
        cl_perror(nodename,"Can't get node name"); 
    } else { 
        printf("name of %s on cluster %d is %s", interfacename, clusterid, nodename); 
    } 
    

    cl_getprimary

    Here is an example of the cl_getprimary routine, from an earlier release, using node ID:

    int clusterid, primary; /* clusterid is arbitrary.*/ 
    clusterid = 1; 
    primary = cl_getprimary (clusterid); 
    if (primary < 0) { 
        cl_perror (primary, "Can't get cluster primary"); 
    } else { 
        printf ("Primary node for cluster %d is %d", clusterid, primary); 
    } 
    

    In the new version of the C API cl_getprimary routine example, note the change in the declaration to nodename as a string instead of nodeid as an int, and the corresponding changes to the printf statements. Moreover, the if statement must be changed since the previous version depended on the fact that the desired information (nodeid) was an int; now it is a string (nodename).

    int clusterid, status; 
    char nodename[CL_MAXNAMELEN]; 
    /* clusterid is arbitrary. */ 
    clusterid = 1; 
    status = cl_getprimary (clusterid, nodename); 
    if (status != CLE_OK) { 
        cl_perror (status, "Can't get cluster primary"); 
    } else { 
        printf ("Primary node for cluster %d is %s", clusterid, nodename); 
    } 
    

    cl_isaddravail

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

    int clusterid, nodeid, status; 
    struct sockaddr_in addr;      /* clusterid, nodeid, and addr are arbitrary.*/ 
    clusterid = nodeid = 1; 
    addr.sin_family = AF_INET; 
    addr.sin_addr.s_addr = inet_addr ("1.1.1.1"); 
    status = cl_isaddravail (clusterid, nodeid, &addr); 
    if (status != CLE_OK) { 
        cl_perror (status, "Interface not available"); 
    } else { 
        printf ("Interface address for %s is available", inet_ntoa  
        (addr.sin_addr.s_addr)); 
    } 
    

    In the new version of the C API cl_isaddravail routine example, the declaration statement changes to use nodename instead of nodeid. See the corresponding changes to the printf statements. Moreover, the assignment statement changes to use strcpy for the nodename.

    int clusterid, status; 
    char nodename[CL_MAXNAMELEN]; 
    struct sockaddr_in addr;    /* clusterid, nodename, and addr are arbitrary. */ 
    clusterid = 1; 
    strcpy (nodename, "node1"); 
    addr.sin_family = AF_INET; 
    addr.sin_addr.s_addr = inet_addr ("1.1.1.1"); 
    status = cl_isaddravail (clusterid, nodename, &addr); 
    if (status != CLE_OK) { 
        cl_perror (status, "Interface not available"); 
    } else { 
        printf ("Interface address for %s is available", inet_ntoa  
        (addr.sin_addr.s_addr)); 
    } 
    

    Memory Allocation Routines

    The following routines allocate or free memory used to store cluster or node map information. You must call the appropriate memory allocation routines before the corresponding retrieval routine, and then call the free routine to release the storage when done.

    cl_alloc_clustermap
    Allocates storage for a list of four clusters of 32 nodes with 32
    interfaces each.
    cl_alloc_groupmap
    Allocates storage for a list of 64 resource groups.
    cl_alloc_netmap
    Allocates storage for a list of networks.
    cl_alloc_nodemap
    Allocates storage for a list of 32 nodes with 32 interfaces each.
    cl_alloc_sitemap
    Allocates storage for a list of sites.
    cl_free_clustermap
    Frees the storage for a list of clusters that was allocated by calling cl_alloc_clustermap.
    cl_free_groupmap
    Frees storage for a list of resource groups allocated with cl_alloc_groupmap.
    cl_free_netmap
    Frees the storage for a list of networks that was allocated by calling cl_alloc_netmap.
    cl_free_nodemap
    Frees the storage for a list of clusters that was allocated by calling cl_alloc_nodemap.
    cl_free_sitemap
    Frees the storage for a list of sites that was allocated by calling cl_alloc_sitemap.

    The following example illustrates how to use these routines. Note that you no longer use CL_MAXNODES to allocate storage for the returned information on the nodes in the cluster. For additional examples, see the reference pages for the cl_getclusters and cl_getnodemap routines.

    int status; 
    struct cl_cluster *clustermap; 
    cl_alloc_clustermap (&clustermap); 
    status = cl_getclusters(clustermap); 
    if (status < 0) { 
        cl_perror(status, "Can't get cluster information"); 
    } else {  
        printf("There are currently %d running clusters", status); 
    } 
    ... 
    cl_free_clustermap (clustermap); 
    

    There is an additional new API cl_node_free(), which frees storage associated with a single cl_node struct.

    Consider the following example:

    struct cl_node nodebuf; 
        cl_getnode(clusterid, "ppstest5", &nodebuf); 
        printf(“Node %s is id %d\n”, nodebuf.cln_nodename, 
    nodebuf.cln_nodeid); 
        cl_node_free(&nodebuf); 
    ); 
    

    After the call to cl_getnode(), the cln_if field is filled in with the list of network interface structs associated with the node. This list is dynamically allocated by cl_getnode() and must be freed to avoid a memory leak in a long-running program.

    cl_node_free() frees the network interface storage field of the cl_node structure. See the subsequent API description for cl_node_free() for more information.

    Requests

    The Clinfo C API has the following types of requests:

  • Cluster Information Requests
  • Node Information Requests
  • Network Interface Information Requests
  • Network Information Requests
  • Event Notification Requests.
  • Resource Group Information Requests
  • Site Information Requests.
  • Cluster Information Requests

    The following cluster information requests return information about a cluster:

    cl_getcluster
    Returns all known information about the cluster with the specified cluster ID.
    cl_getclusterid
    Returns the cluster ID of the cluster with the specified cluster name.
    cl_getclusteridbyifaddr
    Returns the cluster ID of the cluster with the specified network interface address.
    cl_getclusteridbyifname
    Returns the cluster ID of the cluster with the specified network interface name.
    cl_getclusters
    Returns information about all operational clusters.
    cl_isclusteravail
    Returns the status of the cluster with the specified cluster ID.

    Node Information Requests

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

    cl_bestroute
    Returns the local/remote IP address pair that indicates the most direct route to the specified node from the local machine.
    cl_getlocalid
    Returns the cluster ID and node name of the host making the request.
    cl_getnode
    Returns information about the node specified by a cluster ID/node name pair.
    cl_getnodeaddr
    Returns the IP address associated with the specified cluster ID/node name pair.
    cl_getnodenamebyifaddr
    Returns the name of the node with the specified cluster ID/interface address pair.
    cl_getnodenamebyifname
    Returns the name of the node with the specified cluster ID/interface name pair.
    cl_getnodemap
    Returns all known information about all the nodes in a specified cluster.
    cl_getprimary
    Returns the node name of the primary Cluster Manager for the specified cluster.
    cl_isnodeavail
    Returns the status of the specified node.

    Network Interface Information Requests

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

    cl_getifaddr
    Returns the interface address of the interface with the specified cluster ID and name.
    cl_getifname
    Returns the interface name of the interface with the specified cluster ID and address.
    cl_isaddravail
    Returns the status of the specified network interface.

    Network Information Requests

    The following network information requests return information about networks that are part of a cluster:

    cl_getnetmap
    Returns all known information about all the networks in the cluster.
    cl_getnet
    Returns information about a specific network.
    cl_getnetbyname
    Returns information about a specific, named network.
    cl_getnetsbytype
    Returns information about any networks configured with the specified type (such as ether, token, hps).
    cl_getnetsbyattr
    Returns information about any networks configured with the specified attribute (public, private, or non-IP (serial)).
    cl_getnetstatebynode
    Returns the state of the specified network on the specified node.

    Event Notification Requests

    The following event notification routines return information about cluster, node, or
    network events:

    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.

    Resource Group Information Requests

    The following resource group information requests return information about cluster resource groups:

    cl_getgroupmap
    Returns all known information about all the resource groups in the specified cluster.
    cl_getgroup
    Returns all information about the specific resource group in the specified cluster.
    cl_getgroupsbynode
    Returns all the resource groups in which the specified node is a member.
    cl_getgroupnodestate
    Returns the state of the specified group on the specified node.

    Site Information Requests

    The following site information requests return information about sites configured in an HACMP cluster:

    cl_getsitemap
    Returns all known information about all the sites in the cluster.
    cl_getsite
    Returns information about a specific site.
    cl_getsitebyname
    Returns information about a specific, named site.
    cl_getsitebypriority
    Returns information about any sites configured with the specified priority.

    Utilities

    The Clinfo C API has the following utility routines:

    cl_errmsg
    Returns the text for a cluster error code for a single-threaded application.
    cl_errmsg_r
    Returns the text for a cluster error code for a multi-threaded application.
    cl_perror
    Writes a message to standard error that describes the specified error code.

    cl_initialize Routine

    The cl_initialize() routine was used in prior releases to attach to shared memory. Beginning with HACMP 5.3, cl_initialize() no longer has any function and always returns CLE_OK. cl_initialize() is provided for backward compatibility only. Do not use this routine for new programs.

    cl_errmsg Routine

    Syntax

    char *cl_errmsg (int status) 
    

    Description

    The cl_errmsg routine takes a status code returned by Clinfo and returns the text for that error code.

    Parameters

    status
    A cluster information error status.

    Status Codes

    A null-terminated error string.

    For example, the string:

    "Invalid status" 
    

    if the status parameter does not describe a valid cluster error code.

    Example

      char *msg; 
      msg = cl_errmsg(CLE_BADARGS); 
      if (strcmp(msg, "Invalid status") != 0) { 
          printf("CLE_BADARGS means %s", msg); 
      } else { 
          printf("Can't lookup CLE_BADARGS"); 
      } 
    

    cl_errmsg_r Routine

    This is a thread-safe version of the cl_errmsg routine. If you have a multi-threaded application, you must use this routine.

    Syntax

    char *cl_errmsg_r (int status, char cbuf) 
    

    Description

    The cl_errmsg_r routine takes a status code returned by Clinfo and returns the text for that error code.

    Parameters

    status
    A cluster information error status.
    cbuf
    Storage for the returned message must be at least CL_ERRMSG_LEN long (enough for 128 characters).

    Status Codes

    A null-terminated error string.

    For example, the string:

    "Invalid status" 
    

    if the status parameter does not describe a valid cluster error code.

    Example

    char *msg; 
    char cbuf[CL_ERRMSG_LEN]; 
    msg = cl_errmsg_r(CLE_BADARGS, cbuf); 
    if (strcmp(msg, "Invalid status") != 0) { 
    
    printf("CLE_BADARGS means %s", msg);
    } else { 
    
    printf("Can't lookup CLE_BADARGS");
    } 
    

    cl_perror Routine

    Syntax

    void cl_perror (int status, char *message) 
    

    Description

    The cl_perror routine writes a message that describes a specified error code to standard error. cl_perror places the supplied error string before the error message, and places a colon following the error message.

    For example, specifying:

    cl_perror(CLE_IVNODENAME, "Can't service this request"); 
    

    yields the output:

    Can't service this request:Illeagle Node Name. 
    

    The cl_perror routine is useful for generating an error message from the status code returned by a Clinfo request. If a status is provided that is not a valid cluster error code, the cl_perror routine writes the string:

    Error n 
    

    where n is the value of the specified status code.

    Parameters

    status
    A cluster error code.
    message
    The message that will proceed the status description.

    Example

    struct cl_node nodebuf; 
      int clusterid = 99999999;      /* invalid cluster id */ 
      int status; 
      char nodename[CL_MAXNAMELEN]; 
      if ( (status = cl_getnode (clusterid, nodename, &nodebuf)) < 0 ) { 
          cl_perror(status, "can't get node information"); 
      } 
    

    cl_alloc_clustermap Routine

    Syntax

    int cl_alloc_clustermap (struct cl_cluster **clustermap) 
    

    Description

    The cl_alloc_clustermap routine allocates storage for a list of clusters. This routine must be called before calling the cl_getclusters routine.

    After calling the cl_getclusters routine, when you are done call the cl_free_clustermap routine to free the storage.

    Parameters

    clustermap
    The base pointer for the clustermap.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for the clustermap argument.

    Example

    See the example for the cl_getclusters Routine.

    cl_alloc_groupmap Routine

    Syntax

    int cl_alloc_groupmap (struct cl_group **groupmap); 
    

    Description

    The cl_alloc_groupmap routine allocates storage for a list of resource group descriptors. This routine must be called before calling the cl_getgroups routine.

    After calling the cl_getgroups routine, free the storage when you are done by calling the cl_free_groupmap routine.

    Parameters

    groupmap
    The base pointer for the group map.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for the groupmap argument.

    Example

    See the example for the cl_getgroupmap Routine.

    cl_alloc_netmap Routine

    Syntax

    int cl_alloc_netmap (struct cl_site **netmap) 
    

    Description

    Allocates storage for a series of network information structures.

    Parameters

    netmap
    A pointer to a structure cl_net pointer where a pointer to the newly allocated storage is returned.

    Status Codes

    CLE_OK
    The request complete successfully.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for the netmap parameter.

    Example

    See the example for the cl_getnetmap Routine.

    cl_alloc_nodemap Routine

    Syntax

    int cl_alloc_nodemap (struct cl_node **nodemap) 
    

    Description

    The cl_alloc_nodemap routine allocates storage for a list of nodes and the interfaces associated with each node. This routine should be called before calling the cl_getnodemap routine.

    After calling the cl_getnodemap routine, free the storage by calling the cl_free_nodemap routine when you are done.

    Parameters

    nodemap
    The base pointer for the nodemap.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_BADARGS
    Missing or invalid parameters.

    Example

    See the example for the cl_getnodemap Routine.

    cl_alloc_sitemap Routine

    Syntax

    int cl_alloc_sitemap (struct cl_net **sitemap) 
    

    Description

    Allocates storage for a series of site information structures.

    Parameters

    sitemap
    A pointer to a structure cl_site pointer where a pointer to the newly allocated storage is returned.

    Status Codes

    CLE_OK
    The request complete successfully.
    CLE_BADARGS
    Missing or invalid parameters. This status usually indicates that a NULL pointer was specified for the sitemap parameter.

    Example

    See the example for the cl_getsitemap Routine.

    cl_bestroute Routine

    Syntax

    int cl_bestroute (int clusterid, char *nodename,  
    
    struct sockaddr_in *laddr, struct sockaddr_in *raddr)

    Description

    The cl_bestroute routine returns the local/remote IP address pair for the most direct route to the specified node. This routine relies on the netmask value to match network interface pairs.

    The route returned by the cl_bestroute routine depends on the host 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 sorts interfaces by network and attempts to match the first working interface on the network with the first working interface on the network on the remote node. If private networks are defined, these networks are considered before non-private networks are considered.

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

    Parameters

    clusterid
    The cluster ID of the desired node.
    nodename
    The name of the desired node.
    laddr
    Storage for the returned local network interface address.
    raddr
    Storage for the returned remote network interface address.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_BADARGS
    Missing or invalid parameters.
    CLE_NOROUTE
    No route is available.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNODENAME
    The request specified an invalid node name.

    Example

    int clusterid = 1113325332; 
      int status; 
      char nodename[CL_MAXNAMELEN] = "node1"; 
      struct sockaddr_in laddr, raddr; 
      status = cl_bestroute(clusterid, nodename, &laddr, &raddr); 
      if (status != CLE_OK) { 
          cl_perror(status, "can't get route"); 
      } else { 
          printf("best route to node %s is from ", nodename); 
          printf("%s to ", inet_ntoa(laddr.sin_addr)); 
          printf("%s\n", inet_ntoa(raddr.sin_addr)); 
      } 
    

    cl_free_clustermap Routine

    Syntax

    void cl_free_clustermap (struct cl_cluster *clustermap) 
    

    Description

    The cl_free_clustermap routine frees the storage previously allocated for the list of clusters by calling cl_alloc_clustermap.

    Parameters

    clustermap
    A pointer to the clustermap to be freed.

    Example

    See the example for the cl_getclusters Routine.

    cl_free_groupmap Routine

    Syntax

    void cl_free_groupmap (struct cl_group *groupmap); 
    

    Description

    The cl_free_groupmap routine frees the storage previously allocated by a call to cl_alloc_groupmap.

    Parameters

    groupmap
    A pointer to the group map to be freed.

    Example

    See the example for the cl_getgroupmap Routine.

    cl_free_netmap Routine

    Syntax

    void cl_free_netmap (struct cl_net *netmap) 
    

    Description

    Frees the storage previously allocated by a call to cl_alloc_netmap.

    Parameters

    netmap
    A pointer to the netmap to be freed.

    Status Codes

    None.

    Example

    See the example for the cl_getnetmap Routine.

    cl_free_nodemap Routine

    Syntax

    int cl_free_nodemap (struct cl_node *nodemap) 
    

    Description

    The cl_free_nodemap routine frees the storage previously allocated by calling the cl_alloc_nodemap routine.

    Parameters

    nodemap
    A pointer to the nodemap to be freed.

    Example

    See the example for the cl_getnodemap Routine.

    cl_free_sitemap Routine

    Syntax

    void cl_free_sitemap (struct cl_site *sitemap) 
    

    Description

    Frees the storage previously allocated by a call to cl_alloc_sitemap.

    Parameters

    sitemap
    A pointer to the sitemap to be freed.

    Status Codes

    None.

    Example

    See the example for the cl_getsitemap Routine.

    cl_getcluster Routine

    Syntax

    int cl_getcluster (int clusterid, struct cl_cluster *clusterbuf) 
    

    Description

    The cl_getcluster returns information about the cluster specified by the cluster ID.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    clusterbuf
    Storage for the returned cluster information.

    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.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

      int clusterid = 1113325332; 
      int status; 
      struct cl_cluster cluster; 
      status = cl_getcluster(clusterid, &cluster); 
      if (status != CLE_OK) { 
         cl_perror(status, "Can't get cluster information"); 
      } else { 
              printf("cluster id: %d\n",cluster.clc_clusterid); 
              printf("cluster name: %s\n",cluster.clc_name); 
              printf("state= %d [%s]\n", 
                cluster.clc_state, 
                get_state(cluster.clc_state)); 
              printf("substate= %d\n",cluster.clc_substate); 
              printf("primary= %s\n",cluster.clc_primary); 
              printf("nodes= %d, sites= %d, groups= %d, networks= %d\n", 
                cluster.clc_number_of_nodes, 
                cluster.clc_number_of_sites, 
                cluster.clc_number_of_groups, 
                cluster.clc_number_of_networks); 
      } 
    

    cl_getclusterid Routine

    Syntax

    int cl_getclusterid (char *clustername) 
    

    Description

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

    Parameter

    clustername
    The name of the desired cluster.

    Status Codes

    A non-negative number, which represents the cluster ID, signifies success. Otherwise, one of the following error status codes:

    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters.
    CLE_IVCLUSTERNAME
    The request specified an invalid cluster name.

    Example

    int clusterid = 1113325332; 
      char clustername[CL_MAXNAMELEN] = "site1"; 
      clusterid = cl_getclusterid (clustername); 
      if (clusterid < 0) { 
          cl_perror (clusterid, "can't get cluster ID"); 
      } else { 
          printf ("cluster %s has id %d\n", clustername, clusterid); 
      } 
    

    cl_getclusteridbyifaddr Routine

    Syntax

    int cl_getclusteridbyifaddr (struct sockaddr_in *addr) 
    

    Description

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

    Parameters

    addr
    The network interface address whose cluster ID is desired.

    Status Codes

    A non-negative number, which represents the cluster ID, signifies success. Otherwise, one of the following error status codes:

    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.

    Example

    char ifaddr[CL_MAXNAMELEN] = "9.57.28.23"; 
      int clusterid; 
      struct sockaddr_in addr; 
      /* 
      * inet_addr converts addrs to 
      * Internet numbers. 
      */ 
      addr.sin_family = AF_INET; 
      addr.sin_addr.s_addr = inet_addr (ifaddr); 
      clusterid = cl_getclusteridbyifaddr (&addr); 
      if (clusterid < 0) { 
          cl_perror (clusterid,"can't get cluster ID"); 
      } else { 
          printf("cluster id w/ interface address %s is %d\n", 
          inet_ntoa (addr.sin_addr.s_addr), clusterid); 
      } 
    

    cl_getclusteridbyifname Routine

    Syntax

    int cl_getclusteridbyifname (char *interfacename) 
    

    Description

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

    Parameters

    interfacename
    The network interface name whose cluster ID is desired.

    Status Codes

    A non-negative number, which represents the cluster ID, signifies success. Otherwise, one of the following error status codes:

    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters.
    CLE_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

      int clusterid; 
      char interfacename[CL_MAXNAMELEN] = "geotest9"; 
      clusterid = cl_getclusteridbyifname (interfacename); 
      if (clusterid < 0) { 
          cl_perror (clusterid, "can't get cluster id"); 
      } else { 
          printf ("cluster id w/ interface named %s is %d\n", 
          interfacename, clusterid); 
      } 
    

    cl_getclusters Routine

    Syntax

    int cl_getclusters (struct cl_cluster *clustermap) 
    

    Description

    Returns information about all working clusters.

    Parameters

    clustermap
    Returned cluster information. You should allocate storage for this information by calling cl_alloc_clustermap before calling this routine. Then free this storage space by calling cl_free_clustermap when you are done.

    Status Codes

    The routine returns the number of active clusters. If the routine is unsuccessful, it returns one of the following error status codes:

    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters.

    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.

      int i; 
      int numClusters = -1; 
      char cbuf[CL_ERRMSG_LEN]; 
      struct cl_cluster *clustermap; 
      cl_alloc_clustermap (&clustermap); 
      numClusters = cl_getclusters(clustermap); 
      if(numClusters < 0) 
      { 
          printf("cl_getclusters: (failed) %s\n", 
          cl_errmsg(numClusters)); 
    /* 
    ** for threadsafe compilation use: 
          cl_errmsg_r(numClusters,cbuf)); 
    */ 
      } 
      else 
      { 
          printf("there are currently %d running clusters\n", numClusters); 
          for(i=0; i < numClusters; i++) 
    	{ 
              printf("\n  cluster id: %d\n",clustermap[i].clc_clusterid); 
              printf("  cluster name: %s\n",clustermap[i].clc_name); 
              printf("  state= %s\n",get_state(clustermap[i].clc_state)); 
              printf("  substate= %d\n",clustermap[i].clc_substate); 
              printf("  primary= %s\n",clustermap[i].clc_primary); 
              printf("  nodes= %d, sites= %d, groups= %d, networks= %d\n", 
                clustermap[i].clc_number_of_nodes, 
                clustermap[i].clc_number_of_sites, 
                clustermap[i].clc_number_of_groups, 
                clustermap[i].clc_number_of_networks); 
    	} 
      } 
      cl_free_clustermap(clustermap); 
    

    cl_getevent Routine

    Syntax

    int cl_getevent (struct cli_en_msg_t * en_msg) 
    

    Description

    The cl_getevent routine returns an event notification message. The caller should issue this request only after a signal, as specified in a previous cl_registereventnotify request, is received.

    Parameters

    en_msg
    An event notification message buffer, large enough to hold one event notification message. Upon successful return, this buffer contains the received event, cluster, and, if applicable, the network and node identifications.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.

    Example

    See the example for the cl_registereventnotify Routine.

    cl_getgroup Routine

    Syntax

    int cl_getgroup (int clusterid, char *groupname, 
    	 struct cl_group *groupbufp); 
    

    Description

    The cl_getgroup routine returns information about the specified resource group in the specified cluster.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    groupname
    The name of the resource group.
    groupbufp
    A pointer to a cl_group structure where the information is returned.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVNODENAME
    Invalid resource group name.

    Example

      int clusterid = 1113325332; 
      int status, j; 
      char* groupname = "rg01"; 
      struct cl_group group; 
      status = cl_getgroup(clusterid, groupname, &group); 
      if (status != CLE_OK){ 
          cl_perror(status, "can't get resource group information"); 
      } else { 
          printf("resource group %s has %d nodes.\n", 
          group.clg_name, 
          group.clg_num_nodes); 
          for(j=0; j < group.clg_num_nodes; j++){ 
                printf("node w/ id %d is in state %d [%s]\n", 
                group.clg_node_ids[j], 
                group.clg_node_states[j], 
    /* user defined function char* cvrt_rg_state(enum cl_resource_states 
    state) 
    ** to convert state id numbers to text 
    */ 
               cvrt_rg_state(group.clg_node_states[j])); 
          } 
      } 
    

    cl_getgroupmap Routine

    Syntax

    int cl_getgroupmap (int clusterid, struct cl_group *groupmap) 
    

    Description

    The cl_getgroupmap routine returns information about the resource groups in a cluster. You should call the cl_alloc_groupmap before calling this routine to reserve the storage in memory. You should call cl_free_groupmap after calling this routine.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    groupmap
    Storage for the returned resource group information.

    Status Codes

    The request completed successfully if it returns a non-negative number (number of groups in the cluster).

    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

      int i,j; 
      int clusterid = 1113325332; 
      int groups; 
      char cbuf[CL_ERRMSG_LEN]; 
      struct cl_group *groupmap; 
      cl_alloc_groupmap(&groupmap); 
      if (groupmap==NULL){ 
          printf("unable to allocate storage: cl_alloc_groupmap = NULL\n"); 
          exit(-1); 
      } 
      groups = cl_getgroupmap(clusterid, groupmap); 
      if(groups < 0) { 
          cl_perror(groups, "can't get resource group map"); 
      } else { 
          printf("cluster %d has %d resource groups\n", clusterid, groups); 
          for(i=0; i < groups; i++){ 
                printf("resource group %d [%s] has %d nodes\n", 
                groupmap[i].clg_group_id, 
                groupmap[i].clg_name, 
                groupmap[i].clg_num_nodes); 
                printf("policies:\n"); 
                printf("\tstartup  %d \n",groupmap[i].clg_startup_policy); 
                printf("\tfallover %d \n",groupmap[i].clg_fallover_policy);  
                printf("\tfallback %d \n",groupmap[i].clg_fallback_policy); 
                printf("\tsite     %d \n",groupmap[i].clg_site_policy); 
                printf("\tuser     %d \n",groupmap[i].clg_user_policy_name); 
                printf("node states:\n"); 
                for(j=0; j < groupmap[i].clg_num_nodes; j++){ 
                      printf("\tnode %d is in state %d \n", 
                          groupmap[i].clg_node_ids[j], 
                          groupmap[i].clg_node_states[j]); 
    		}  
                printf("resources %d\n",groupmap[i].clg_num_resources); 
                for(j=0; j < groupmap[i].clg_num_resources; j++){ 
                      printf("\tresource %d is in state %d\n", 
                          groupmap[i].clg_resource_id[j], 
                          groupmap[i].clg_res_state[j]); 
                } 
          } 
      } 
    

    cl_getgroupnodestate Routine

    Syntax

    enum cl_resource_states cl_getgroupnodestate (int clusterid, 
    	char *groupname, int nodeid); 
    

    Description

    The cl_getgroupnodestate routine returns the state of the specified group on the specified node.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    groupname
    Name of the resource group.
    nodeid
    The ID of the cluster node.

    Status Codes

    Returns one of the enumerated values in cl_resource_states. This enumeration is described in the earlier section Enumerated Type Containing Resource Group State in this chapter.

    Example

      enum cl_resource_states state; 
      int clusterid = 1113325332; 
      int nodeid = 1; 
      char groupname[CL_MAXNAMELEN] = "rg01"; 
      state = cl_getgroupnodestate(clusterid, groupname, nodeid); 
      if (state == CL_RGNS_INVALID){ 
    	cl_perror(state, "can't get group node state"); 
      } else { 
    	printf("node w/ id %d is currently in state %d in group %s\n", 
    	nodeid, state, groupname); 
      } 
    

    cl_getgroupsbynode Routine

    Syntax

    int cl_getgroupsbynode (int clusterid, int nodeid,
    	struct cl_group **groupbufp, int *groupcountp); 
    

    Description

    The cl_getgroupsbynode routine returns information for all resource groups of which the specified node is a member. Note that this routine allocates storage for the return information—the caller must free this storage.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    nodeid
    The ID of the cluster node.
    groupbufp
    A pointer to a cl_group structure where the information is returned.
    groupcountp
    A pointer to an integer where the number of groups returned is stored.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVNODENAME
    Invalid node ID.

    Example

      int clusterid = 1113325332; 
      int nodeid = 1; 
      int status; 
      int groupcount; 
      int j; 
      struct cl_group *groups; 
      status = cl_getgroupsbynode(clusterid, nodeid, &groups, &groupcount); 
      if (status != CLE_OK){ 
          cl_perror(status,"failed to get resource group information"); 
      } else { 
          printf("node %d is a member of %d groups:\n",nodeid, groupcount); 
          for(j=0; j < groupcount; j++){ 
              printf("node %d is in group %s\n",  
                      nodeid, groups[j].clg_name);} 
          if (groupcount) free (groups); 
      } 
    

    cl_getifaddr Routine

    Syntax

    int cl_getifaddr (int clusterid, char *interfacename,  
    
    struct sockaddr_in *addr)

    Description

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

    Parameters

    clusterid
    The cluster ID of the desired network interface.
    interfacename
    The name of the desired network interface.
    addr
    Storage for the returned network interface address.

    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.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

      int clusterid = 1113325332; 
      int status; 
      char* interfacename = "geotest9"; 
      struct sockaddr_in addr; 
      status = cl_getifaddr (clusterid, interfacename, &addr); 
      if (status != CLE_OK) { 
          cl_perror (status, "Can't find interface address"); 
      } else { 
          printf ("interface address w/ name %s is %s\n",interfacename, 
          inet_ntoa (addr.sin_addr.s_addr)); 
      } 
    

    cl_getifname Routine

    Syntax

    int cl_getifname (int clusterid, struct sockaddr_in *addr,  
    
    char *interfacename)

    Description

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

    Parameters

    clusterid
    The cluster ID of the desired network interface.
    addr
    The IP address of the desired network interface.
    interfacename
    Storage for the returned network interface name. The interfacename parameter should be no more than CL_MAXNAMELEN characters long.

    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_IVADDRESS
    The request specified an invalid network interface address.

    Example

      int clusterid = 1113325332; 
      int status; 
      struct sockaddr_in addr; 
      char interfacename[CL_MAXNAMELEN] = "9.57.28.23"; 
      addr.sin_family = AF_INET; 
      addr.sin_addr.s_addr = inet_addr (interfacename); 
       
      status = cl_getifname (clusterid, &addr, interfacename); 
      if (status != CLE_OK) { 
          cl_perror (status, "can't find interface name"); 
      } 
      else { 
          printf ("interface name w/ address %s is %s\n", 
                inet_ntoa (addr.sin_addr.s_addr), interfacename); 
      } 
    

    cl_getlocalid Routine

    Syntax

    int cl_getlocalid (int *clusterid, char *nodename) 
    

    Description

    Returns the cluster ID and the node name of the node making the request. This request returns an error status code for nodes not currently active in the cluster.

    Parameters

    clusterid
    Storage for the returned cluster ID.
    nodename
    Storage for the returned node name.

    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.
    CLE_IVNODE
    Node is not a cluster node.

    Example

      int clusterid, status; 
      char nodename[CL_MAXNAMELEN] = "node1"; 
      status = cl_getlocalid (&clusterid, nodename); 
      if (status != CLE_OK) { 
          if (status == CLE_IVNODE) { 
                printf("this node is not a cluster member\n"); 
          } else { 
                cl_perror(status, "can't get local cluster ID"); 
          } 
      } else { 
          printf ("this node [%s] is a member of cluster id %d\n", 
                    nodename,clusterid); 
      }  
    

    cl_getnet Routine

    Syntax

    int cl_getnet (int clusterid, int netid, struct cl_net *netbuf) 
    

    Description

    Returns information about a specified network.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    netid
    The ID of the network.
    netbuf
    A pointer to a cl_net structure where the information is returned.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVNETID
    Invalid network ID.

    Example

      int clusterid = 1113325332; 
      int netid = 1; 
      int status, j; 
      struct cl_net netmap; 
      status = cl_getnet(clusterid, netid, &netmap); 
      if (status == CLE_OK) 
      { 
            printf("information for cluster network %s (id %d):\n", 
                     netmap.clnet_name, netmap.clnet_id); 
            printf("network is type %s\n", netmap.clnet_type); 
            printf("network attribute is %d\n", netmap.clnet_attr); 
            printf("there are %d nodes on this network\n", 
                     netmap.clnet_numnodes); 
            for (j=0; j<netmap.clnet_numnodes; j++) 
            { 
                    enum cls_state node_state; 
                    printf("  node id = %d, state = %d,", 
                    netmap.clnet_node_ids[j], 
                    netmap.clnet_node_states[j]); 
                    cl_getnetstatebynode( clusterid, netmap.clnet_id, 
                    netmap.clnet_node_ids[j], &node_state); 
                    printf(" state (cl_getnetstatebynode) = %d\n", 
                             node_state); 
            } 
      } 
    

    cl_getnetbyname Routine

    Syntax

    int cl_getnetbyname (int clusterid, char *netname, 
    	struct cl_net *netbuf) 
    

    Description

    Returns information about a specific, named network.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    netname
    The name of the network.
    netbuf
    A pointer to a cl_net structure where the information is returned.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVNETNAME
    Invalid network name.

    Example

      char netname[CL_MAXNAMELEN]; 
      int clusterid = 1; 
      int status; 
      struct cl_net netmap; 
      status = cl_getnetbyname(clusterid,netname,&netmap); 
      if (status != CLE_OK) { 
            display_error(status,cmd); 
      } else { 
            printf("network %s is type %s: connected to %d nodes\n", 
            netmap.clnet_name, 
            netmap.clnet_type, 
            netmap.clnet_numnodes); 
      } 
    

    cl_getnetmap Routine

    Syntax

    int cl_getnetmap (int clusterid, struct cl_net *netmap) 
    

    Description

    Returns information about all the networks in the cluster.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    netmap
    Storage for the returned network information.

    Status Codes

    The request completed successfully if it returns a non-negative number (number of networks in the cluster).

    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

      int clusterid = 1113325332; 
      int num_nets; 
      int i,j; 
      struct cl_net *nm; 
      cl_alloc_netmap(&nm); 
      num_nets = cl_getnetmap(clusterid, nm); 
      printf("\n\ndumping netmap with %d nets for cluster %d\n\n", 
          num_nets, nm->clnet_clusterid); 
      for (i=0; i<num_nets; i++) 
      { 
          printf("info for network: %s (%d)\n", nm[i].clnet_name, 
                   nm[i].clnet_id); 
          printf(" type = %s\n", nm[i].clnet_type); 
          printf(" attribute = %d\n", nm[i].clnet_attr); 
          printf(" state = %d\n", nm[i].clnet_state); 
          printf(" number of nodes = %d\n", nm[i].clnet_numnodes); 
          for (j=0; j<nm[i].clnet_numnodes; j++) 
          { 
                printf(" node id = %d , state = %d\n", 
                nm[i].clnet_node_ids[j], 
                nm[i].clnet_node_states[j]); 
    	} 
      } 
      cl_free_netmap(nm); 
    

    cl_getnetsbyattr Routine

    Syntax

    int cl_getnetsbyattr (int clusterid, int *netattr, 
    	 struct cl_net **netbuf, int *netcount) 
    

    Description

    Returns information about any networks configured with the specified attribute (public, private or non-IP (serial)).

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    netattr
    Network attribute for list of networks to be retrieved.
    netbuf
    A pointer to a cl_net structure where the information is returned.
    netcount
    A pointer to an integer where the number of networks matching the specified type is returned.

    Status Codes

    CLE_OK
    Success. Note that this code may return even if no networks are returned, that is, no networks with the specified attribute exist.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVNETATTR
    Invalid network attribute.

    Example

      int status,i; 
      int netcount; 
      int clusterid = 1; 
      struct cl_net *netmap; 
      enum cl_network_attribute attr; 
      attr = CL_NET_TYPE_PRIVATE; 
      status = cl_getnetsbyattr(clusterid, attr, &netmap,&netcount); 
      if (status != CLE_OK) { 
         cl_perror(status,"cl_getnetsbyattr() failed"); 
      } else { 
         printf("there are %d private networks in this cluster.\n",netcount); 
         for (i=0; i<netcount; i++) 
         { 
           struct cl_net network; 
            status = cl_getnetbyname(clusterid, netmap[i].clnet_name, 
                                     &network); 
            if (status != CLE_OK) { 
          cl_perror(status,"cl_getnetbyname() failed"); 
           } else { 
          printf(" network %s is type %s: connected to %d nodes\n", 
                network.clnet_name, 
                network.clnet_type, 
                network.clnet_numnodes); 
            } 
         } 
      } 
    

    cl_getnetsbytype Routine

    Syntax

    int cl_getnetsbytype (int clusterid, char *nettype, 
    	 struct cl_net **netbuf, int *netcount) 
    

    Description

    Returns information about any networks configured with the specified type (such as ether, token, hps).

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    nettype
    Network type for list of networks to be retrieved. The types of networks are retrieved from the list of Network Interface Modules (NIMs) currently defined to HACMP.
    netbuf
    A pointer to a cl_net structure where the information is returned.
    netcount
    A pointer to an integer where the number of networks matching the specified type is returned.

    Status Codes

    CLE_OK
    Success. Note that this code may return even if no networks are returned, that is, no networks of the specified type exist.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVNETTYPE
    Invalid network type.

    Example

    char net_type[CL_MAXNAMELEN] = "ether"; 
      int status,i,j; 
      int netcount; 
      int clusterid = 1113325332; 
      struct cl_net *netmap; 
      status = cl_getnetsbytype(clusterid, net_type, &netmap, &netcount); 
      if (status != CLE_OK) exit(status); 
      printf("there are %d networks of type: %s.\n",netcount,net_type); 
      for (i=0; i<netcount; i++) 
      { 
        struct cl_net network; 
        status = cl_getnetbyname(clusterid, netmap[i].clnet_name, &network); 
        if (status != CLE_OK) exit(status); 
        printf("network %s has attribute %d and is connected to %d nodes\n", 
        network.clnet_name, 
        network.clnet_attr, 
        network.clnet_numnodes); 
      } 
    

    cl_getnetstatebynode Routine

    Syntax

    int cl_getnetstatebynode (int clusterid, int netid, 
    	int nodeid, enum cls_state *state) 
    

    Description

    Returns the state of the specified network on the specified node.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    netid
    The network ID for the network state to be retrieved.
    nodeid
    The node ID for the network state to be retrieved.
    netstate
    A pointer to an integer where the state of the specified network on the specified node is returned.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVNETID
    Invalid network ID.
    CLE_IVNODEID
    Invalid node ID. Note that this return can indicate that the ID is simply invalid (it is not a valid node ID for this cluster) or that the node is not connected (has no interfaces on) the specified network.

    Example

    See the example for the cl_getnet Routine.

    cl_getnode Routine

    Syntax

    int cl_getnode (int clusterid, char *nodename,  
    	struct cl_node *nodebuf); 
    

    Description

    Returns information about the node specified by a cluster ID/node name pair.

    Parameters

    clusterid
    The cluster ID of the desired node.
    nodename
    The node name of the desired node.
    nodebuf
    Storage for the returned node information.

    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.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNODENAME
    The request specified an invalid node name.

    Example

      int clusterid = 1113325332; 
      int status; 
      char* nodename = "node1"; 
      struct cl_node nodebuf; 
      status = cl_getnode (clusterid, nodename, &nodebuf); 
      if (status != CLE_OK) { 
          cl_perror(status, "can't get node info"); 
      } else { 
          printf("node named %s on cluster %d : id= %d, state= %d\n",  
            nodename,  
            clusterid, 
            nodebuf.cln_nodeid, 
            nodebuf.cln_state); 
      } 
      cl_node_free(&nodebuf); 
    

    cl_getnodeaddr Routine

    Syntax

    int cl_getnodeaddr (int clusterid, char *interfacename,  
    
    struct sockaddr_in *addr)

    Description

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

    Parameters

    clusterid
    The cluster ID of the desired network interface.
    interfacename
    The name of the desired network interface.
    addr
    Storage for the returned network interface address.

    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_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

      int clusterid = 1113325332; 
      int status; 
      char* interfacename = "geotest9"; 
      struct sockaddr_in addr; 
      status = cl_getnodeaddr(clusterid, interfacename, &addr); 
      if (status != CLE_OK) { 
          cl_perror(status, "can't get node addr"); 
      } else { 
          printf("address of interface %s on cluster %d is %s\n", 
          interfacename, clusterid, inet_ntoa(addr.sin_addr)); 
      } 
    

    cl_getnodemap Routine

    Syntax

    int cl_getnodemap (int clusterid, struct cl_node *nodemap) 
    

    Description

    The cl_getnodemap routine returns information about the nodes in a cluster. You should call cl_alloc_nodemap before calling this routine to reserve the storage in memory. You should call cl_free_nodemap after calling this routine.

    Parameters

    clusterid
    The cluster ID of the desired cluster.
    nodemap
    Storage for the returned node information.

    Status Codes

    The request completed successfully if it returns a non-negative number (number of nodes in the cluster).

    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.

    Example

      int clusterid = 1113325332; 
      int i; 
      int nodes; 
      struct cl_node *nodemap; 
      cl_alloc_nodemap (&nodemap); 
      if (nodemap==NULL){ 
          printf("unable to allocate storage: cl_alloc_nodemap = NULL\n"); 
          exit(-1); 
      } 
      nodes = cl_getnodemap(clusterid, nodemap); 
      if(nodes < 0) 
      { 
          cl_perror(nodes,"can't get node map"); 
      } else { 
        printf("cluster %d has %d nodes:\n", clusterid, nodes); 
        for(i=0; i < nodes; i++){ 
          printf("node %s in state %d has %d interfaces\n", 
          nodemap[i].cln_nodename, 
          nodemap[i].cln_state, 
          nodemap[i].cln_nif); 
          if(clusterid != nodemap[i].cln_clusterid){ 
                printf("structure has invalid cluster ID: %d", 
                nodemap[i].cln_clusterid); 
          } 
        } 
      } 
      cl_free_nodemap(nodemap); 
    

    cl_getnodenamebyifaddr Routine

    Syntax

    int cl_getnodenamebyifaddr (int clusterid, struct sockaddr_in *addrp,
    	char *nodename) 
    

    Description

    Returns the name of the node with the specified interface address. Clinfo scans the network interfaces on each node in the cluster. If a match is found, the node name for the node associated with that interface address is returned.

    Parameters

    clusterid
    The cluster ID of the desired node.
    addr
    The network interface address of the desired node.
    nodename
    The name of the desired node.

    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.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVADDRESS
    The request specified an invalid network interface address.

    Example

      int clusterid = 1113325332; 
      int status; 
      char nodename[CL_MAXNAMELEN]; 
      struct sockaddr_in addr; 
      addr.sin_family = AF_INET; 
      addr.sin_addr.s_addr = inet_addr ("9.57.28.23"); 
      status = cl_getnodenamebyifaddr (clusterid, &addr, nodename); 
      if (status !=CLE_OK) { 
          cl_perror(status,"can't get node name"); 
      } else { 
          printf("node name of interface w/ address %s on  
                  cluster %d is %s\n", 
          inet_ntoa(addr.sin_addr), clusterid, nodename); 
      } 
    

    cl_getnodenamebyifname Routine

    Syntax

    int cl_getnodenamebyifname (int clusterid, char *interfacename, 
    	char *nodename) 
    

    Description

    Returns the node name of the node with the specified interface name. Clinfo scans the network interfaces on each node in the cluster. If a match is found, the node name for that node is returned.

    Parameters

    clusterid
    The cluster ID of the desired node.
    interfacename
    The network interface name of the desired node.
    nodename
    The name of the desired node.

    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.
    CLE_IVCLUSTERID
    The request specified an invalid cluster ID.
    CLE_IVNETIFNAME
    The request specified an invalid network interface name.

    Example

      int clusterid = 1113325332; 
      int status; 
      char nodename[CL_MAXNAMELEN]; 
      char interfacename[CL_MAXNAMELEN] = "geotest9"; 
      status = cl_getnodenamebyifname (clusterid, interfacename, nodename); 
      if (status != CLE_OK) { 
          cl_perror(status,"can't get node name"); 
      } else { 
          printf("interface= %s\n",interfacename); 
          printf("node name of interface w/ name %s on cluster %d is %s\n", 
              interfacename, 
              clusterid, 
              nodename); 
      } 
    

    cl_getprimary Routine

    Syntax

    int cl_getprimary (int clusterid, char *nodename) 
    

    Description

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

    Parameters

    clusterid
    The cluster ID whose primary node name is desired.
    nodename
    The name of the node designated as the primary Cluster Manager node is returned in this argument.

    Status Codes

    CLE_OK
    The request completed successfully.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_NOPRIMARY
    No information is available about the primary Cluster Manager.
    CLE_IVCLUSTER
    The cluster is not available.

    Example

      int clusterid = 1113325332; 
      int status; 
      char nodename[CL_MAXNAMELEN] = "node1"; 
      status = cl_getprimary (clusterid, nodename); 
      if (status != CLE_OK) { 
          cl_perror(status,"can't get cluster primary"); 
      } else { 
          printf ("primary node for cluster %d is %s\n", 
          clusterid, nodename); 
      } 
    

    cl_getsite Routine

    Syntax

    int cl_getsite(int clusterid, int siteid, struct cl_site *sitebuf) 
    

    Description

    Returns information about a specific site.

    Parameters

    clusterid
    The desired cluster.
    siteid
    The ID of the cluster.
    sitebuf
    Holds the returned cl_site structure.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVSITEID
    Invalid site ID

    Example

      int clusterid = 1113325332; 
      int status; 
      int siteid = 1; 
      struct cl_site site; 
      status = cl_getsite(clusterid, siteid, &site); 
      if (status == CLE_OK) { 
          printf("site %s (%d) has %d nodes and is priority %d\n", 
                site.clsite_name, 
                site.clsite_id, 
                site.clsite_numnodes, 
                site.clsite_priority); 
      } else { 
          cl_perror(status,"can't get site information"); 
      } 
    

    cl_getsitebyname Routine

    Syntax

    int cl_getsitebyname (int clusterid, char *sitename, struct cl_site *sitebuf) 
    

    Description

    Returns information about a specific, named site.

    Parameters

    clusterid
    The desired cluster.
    sitename
    The name of the site to be returned.
    sitebuf
    Holds the returned cl_site structure.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVSITENAME
    Invalid site ID

    Example

    int clusterid = 1113325332;
    int status;
    char sitename[CL_MAXNAMELEN] = "geo9";
    struct cl_site site;
    status = cl_getsitebyname(clusterid, sitename, &site);
    if (status == CLE_OK)
    printf("site %s (%d) has %d nodes and is priority %d\n",
    site.clsite_name,
    site.clsite_id,
    site.clsite_numnodes,
    site.clsite_priority);

    cl_getsitebypriority Routine

    Syntax

    int cl_getsitebypriority (int clusterid, enum cl_site_priority, 
        priority, struct cl_site *sitebuf) 
    

    Description

    Returns information about any sites configured with the specified priority.

    Parameters

    clusterid
    The desired cluster.
    priority
    One of the enumerated site priority values.
    site_buf
    Holds the returned site information.

    Status Codes

    CLE_OK
    Success.
    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.
    CLE_IVSITEPRIORITY
    Invalid site priority.

    Example

      enum cl_site_priority priority = CL_SITE_PRI_PRIMARY; 
      int clusterid = 1113325332; 
      int status; 
      struct cl_site site; 
      status = cl_getsitebypriority(clusterid, priority, &site); 
      if (status == CLE_OK) 
          printf("site %s (%d) has %d nodes and is priority %d\n", 
              site.clsite_name, 
              site.clsite_id, 
              site.clsite_numnodes, 
              site.clsite_priority); 
    

    cl_getsitemap Routine

    Syntax

    int cl_getsitemap (int clusterid, struct cl_site *sitemap) 
    

    Description

    Returns all known information about all the sites in the cluster.

    Parameters

    clusterid
    The desired cluster.
    sitemap
    Storage must be allocated prior to the cl_getsitemap call using cl_alloc_sitemap(&sitemap).
    Storage must be freed using cl_free_sitemap(sitemap).

    Status Codes

    The request completed successfully if it returns a non-negative number (number of sites in the cluster).

    CLE_BADARGS
    Missing or invalid argument(s).
    CLE_SYSERR
    System error.
    CLE_NOCLINFO
    No cluster information available.
    CLE_IVCLUSTERID
    Invalid cluster ID.

    Example

      int clusterid = 1113325332; 
      int status; 
      int i,j; 
      int nbr_sites; 
      struct cl_site *sitemap; 
      cl_alloc_sitemap(&sitemap); 
      nbr_sites = cl_getsitemap(clusterid, sitemap); 
      printf("dumping sitemap with %d sites for cluster %d\n\n", 
          nbr_sites, sitemap->clsite_clusterid); 
      for (i=0; i<nbr_sites; i++) 
      { 
          printf("info for site %s (%d)\n", 
          sitemap[i].clsite_name, sitemap[i].clsite_id); 
          printf(" priority = %d \n", sitemap[i].clsite_priority); 
          printf(" backup = %d \n", sitemap[i].clsite_backup); 
          printf(" state = %d \n", sitemap[i].clsite_state); 
          printf(" number of nodes = %d\n", sitemap[i].clsite_numnodes); 
          for (j=0; j<sitemap[i].clsite_numnodes; j++) 
          { 
                printf(" node id = %d\n", 
                sitemap[i].clsite_nodeids[j]); 
          } 
      } 
      cl_free_sitemap(sitemap); 
    

    cl_isaddravail Routine

    Syntax

    int cl_isaddravail (int clusterid, char *nodename,  
    
    struct sockaddr_in *addr)

    Description

    Returns the status of the specified network interface.

    Parameters

    clusterid
    The cluster ID of the desired network interface.
    nodename
    The node name of the desired network interface.
    addr
    The address of the desired network interface.

    Status Codes

    CLE_OK
    The specified address is available from the given node.
    CLE_SYSERR
    System error. Check the AIX 5L global variable errno for additional information.
    CLE_BADARGS
    Missing or invalid parameters.
    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

      int clusterid = 1113325332; 
      int status; 
      char ifaddr[CL_MAXNAMELEN] = "9.57.28.23"; 
      char nodename[CL_MAXNAMELEN] = "node1"; 
      struct sockaddr_in addr; 
      addr.sin_family = AF_INET; 
      addr.sin_addr.s_addr = inet_addr (ifaddr); 
      status = cl_isaddravail (clusterid, nodename, &addr); 
      if (status != CLE_OK) { 
          cl_perror(status,"interface not available"); 
      } else { 
          printf ("interface address for %s is available\n", 
              inet_ntoa (addr.sin_addr.s_addr)); 
      } 
    

    cl_isclusteravail Routine

    Syntax

    int cl_isclusteravail (int clusterid) 
    

    Description

    Returns status of the cluster with the specified cluster ID.

    Parameters

    clusterid
    The cluster ID of the desired cluster.

    Status Codes

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

    Example

      int clusterid = 1113325332; 
      int status; 
      status = cl_isclusteravail (clusterid); 
      if (status != CLE_OK) { 
          cl_perror (status, "cluster is not available"); 
      } else { 
          printf ("cluster %d is available\n", clusterid); 
      } 
    

    cl_isnodeavail Routine

    Syntax

    int cl_isnodeavail (int clusterid, char *nodename) 
    

    Description

    Indicates whether the specified node is alive.

    Parameters

    clusterid
    The cluster ID of the desired node.
    nodename
    The node name of the desired node.

    Status Codes

    CLE_OK
    The node is available from the specified cluster.
    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

      int clusterid = 1113325332; 
      int status; 
      char nodename[CL_MAXNAMELEN] = "node1"; 
      status = cl_isnodeavail (clusterid, nodename); 
      if (status != CLE_OK) { 
          cl_perror(status,"node is unavailable"); 
      } else { 
          printf ("node %s on cluster %d is available\n", 
         nodename, clusterid); 
      } 
    

    cl_model_release Routine

    The cl_model_release() routine was used in prior releases to detach shared memory. Beginning with HACMP 5.3, cl_model_release() no longer has any function and always returns CLE_OK. cl_model_release() is provided for backward compatibility only. Do not use this routine for new programs.

    cl_node_free

    Syntax

    int cl_node_free 
    

    Description

    Deletes the storage previously allocated for the network interfaces associated with the node returned by a previous call to the cl_getnode routine. The member cln_if will be set to null:

    Parameters

    nodebifp
    node buffer

    Status Codes

    CLE_OK
    The request completed successfully.

    Sample Source

    int clusterid; 
    struct cl_node nodebuf;                 
    struct sockaddr_in addr; 
    addr.sin_family = AF_INET; 
    addr.sin_addr.s_addr = inet_addr("9.57.28.8"); 
    clusterid = cl_getclusteridbyifaddr (&addr); 
    cl_getnode(clusterid, "ppstest5", &nodebuf); 
    printf ("node id: %d has %d interfaces \n",  
    		 nodebuf.cln_nodeid, nodebuf.cln_nif); 
    /* call cl_node_free to release storage for the network */ 
    /* interfaces (part of the cl_node struct) which was    */ 
    /* allocated by cl_getnode */ 
    cl_node_free(&nodebuf); 
    printf ("after cl_node_free, node id: %d has %d interfaces \n",  
        nodebuf.cln_nodeid, nodebuf.cln_nif); 
    

    Sample Output

    node id: 1 has 5 interfaces  
    after cl_node_free, node id: 1 has 0 interfaces  
    

    cl_registereventnotify Routine

    Syntax

    #include <signal.h> 
    int cl_registereventnotify (int num_reqs, struct cli_enr_req_t*enr_list) 
    

    Description

    The cl_registereventnotify routine registers a list of event notification requests with Clinfo. Each request specifies an event ID, a cluster ID, a signal ID, and if applicable, a node name and/ or a network ID. If the routine is successful, Clinfo signals the calling process when an event occurs, which fits the specified description. When this signal is received, the cl_getevent routine may be called to get information about the event that just occurred.

    You can register to receive notification of all network and cluster events by specifying -1 as the event ID. If you register to receive notification of all such events, you cannot unregister notification of specific events; you must unregister all.

    Note that you cannot use the -1 event ID for events that include node name identification. Specify a NULL string to register for all node names. Currently you cannot specify an individual network ID. Use -1 as the event ID.

    This routine does not work with a cluster ID of 0. Assign another number as the cluster ID.

    Parameters

    num_reqs
    The number of event notification registration requests being made (limit is 10).
    enr_list
    The list of event notification registration requests. The events that may be requested include the following:
     
    CL_SWAPPING_ADAPTER. The specified adapters are being swapped. This event requires cluster, node, and network identification. A value of -1 for cluster and network identifications indicates all such components. Specify a NULL string for all node names. This corresponds to the swap_adapter event in hacmp.out.
     
    CL_SWAPPED_ADAPTER. The specified adapters have been swapped. This event requires cluster, node, and network identification. A value of -1 for cluster and network identifications indicates all such components. Specify a NULL string for all node names. This corresponds to the swap_adapter_complete event in hacmp.out.
     
    CL_JOINING_NETWORK. The specified network is in the process of joining. This event requires cluster and network identification. A value of -1 for either of these identifications indicates all such components. This corresponds to the network_up event in hacmp.out.
     
    CL_JOINED_NETWORK. The specified network is up. This event requires cluster and network identification. A value of -1 for either of these identifications indicates all such components. This corresponds to the network_up_complete event in hacmp.out.
     
    CL_FAILING_NETWORK. The specified network is going down. This event requires cluster and network identification. A value of -1 for either of these identifications indicates all such components. This corresponds to the network_down event in hacmp.out.
     
    CL_FAILED_NETWORK. The specified network is down. This event requires cluster and network identification. A value of -1 for either of these identifications indicates all such components. This corresponds to the network_down_complete event in hacmp.out.
     
    CL_JOINING_NODE. The specified node is coming up. This event requires cluster and node identification. This corresponds to the node_up event in hacmp.out.
     
    CL_JOINED_NODE. The specified node is up. This event requires cluster and node identification. This corresponds to the node_up_complete event in hacmp.out.
     
    CL_FAILING_NODE. The specified node is going down. This event requires cluster and node identification. This corresponds to the node_down event in hacmp.out.
     
    CL_FAILED_NODE. The specified node is down. This event requires cluster and node identification. This corresponds to the node_down_complete event in hacmp.out.
     
    CL_NEW_PRIMARY. The specified cluster has a new primary node. This event requires the cluster ID. Note that the concept of a primary node is an attribute from prior releases and may not correspond to the role of the node with respect to the application.
     
    CL_STABLE. The specified cluster has stabilized. This event requires cluster identification. A value of -1 indicates all such components.
     
    CL_UNSTABLE. The specified cluster has destabilized. This event requires cluster identification. A value of -1 indicates all such components.
    SIGNALS
    You may specify any appropriate UNIX signal; familiarity with signals is assumed. SIGUSR1 and SIGUSR2 are suggested.

    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_IVREQNUM
    An invalid number of event notification registration requests was specified (more than 10).
    CLE_IVNETID
    An invalid network identification was specified.
    CLE_IVEVENTID
    An invalid event identification was specified.

    Example

    The following example illustrates the use of the cl_registereventnotify, cl_unregistereventnotify, and cl_getevent routines in a simple test program.

    In this example, the application registers to be notified by a SIGUSR1 signal when any network connected to node2 of cluster 83 experiences problems serious enough to cause a FAILING_NETWORK event. After registering, the application waits for the event. When the event occurs, Clinfo sends the SIGUSR1 signal to the application; the application then sends for the information about the event using cl_getevent, and prints out the information received. Finally, the application unregisters for notification of this event.

    #include <stdio.h> 
    #include <sys/types.h> 
    #include <signal.h> 
    #include <cluster/clinfo.h> 
    volatile int no_signal = 1; 
    /* Signal handler for catching event notification signal */ 
    void 
    catch_sig(int sig) 
    { 
    
    no_signal = 0;
    } 
    int 
    main(int argc, char *argv[]) 
    { 
    	int ret_code, i; 
    	struct cli_enr_req_t en_req;  /*  Event notification request  */ 
    	struct cli_en_msg_t  en_msg;  /*  Event notification message */ 
    	en_req.event_id = CL_FAILING_NETWORK;	/* specify a failing 
    		network  event  */ 
    	en_req.cluster_id = 83;            
    	strcpy (en_req.node_name,"node2"); 
    	en_req.net_id = 1;			/*  no net id necessary 
    		for this event  */ 
    	en_req.signal_id = SIGUSR1;/*  Request to register for event
    		notification */ 
    	if(ret_code = cl_registereventnotify((int) 1, &en_req)!=CLE_OK ) 
    	{ 
    		printf("cl_en_test: cl_registereventnotify failed 
    		with error %d.",ret_code); 
    	exit(1); 
    	} 
    /* Set up a signal handler to catch the event notification 
       signal from Clinfo   */ 
    	ret_code = signal(SIGUSR1, catch_sig); 
    	if ( ret_code < 0 ){ 
    		perror("cl_en_test"); 
    		exit(1); 
    	} 
        /*  Wait for signal  */ 
    	printf("cl_en_test: waiting for signal from Clinfo."); 
    	while (no_signal){ 
    	pause();} 
        /*  Execution will start here after catch_sig executes when 
    the signal is received.  Get the event notification message.  */ 
    	if ( ret_code = cl_getevent(&en_msg) != CLE_OK ) 
        	{ 
    	printf("cl_en_test: cl_getevent failed with error %d.", 
                   ret_code); 
    	exit(1); 
        	} 
    /* Print out the event notification information received */ 
         
    	printf("cl_en_test: Event notification message received 
    		from Clinfo:"); 
    	printf("cl_en_test: Event id = %d", en_msg.event_id); 
    	printf("cl_en_test: Cluster id = %d", en_msg.cluster_id); 
    	printf("cl_en_test: Node name = %s", en_msg.node_name); 
    	printf("cl_en_test: Net id = %d", en_msg.net_id); 
    /*  Request to unregister the event notification  */ 
        if ( (ret_code = cl_unregistereventnotify((int) 1,&en_req))!=CLE_OK) 
    	{ 
    	printf("cl_en_test: cl_unregistereventnotify failed with 
    	error %d.", ret_code); 
    	exit(1); 
    	} 
    } 
    

    cl_unregistereventnotify Routine

    Syntax

    int cl_unregistereventnotify (int num_reqs,  
    	struct cli_enr_req_t *enr_list) 
    

    Description

    The cl_unregistereventnotify routine unregisters a list of event notification requests with Clinfo. Each request specifies an event identification, a cluster identification, a signal identification, and if applicable, a node and/or network identification. If the routine is successful, Clinfo deletes registration of all events that fit the specified description.

    If you registered to receive notification of all network or cluster events by specifying -1 as the event ID, you must unregister all. You cannot register for all, then unregister individual events. If you registered for specific events, then unregister for those events individually.

    Parameters

    See parameters for the cl_registereventnotify Routine.

    Status Codes

    See status codes for the cl_registereventnotify Routine.

    Example

    See the example for the cl_registereventnotify Routine.


    PreviousNextIndex