![]() ![]() ![]() |
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:
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:
In addition to this list of include directives, specify the following include directive in each source module that uses the cl_registereventnotify routine:
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:
You must add the following directives to the object load command of a multi-threaded application that uses the Clinfo C API:
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:
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.
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
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.
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
The following cluster information requests return information about a cluster:
Node Information Requests
The following node information requests return information about the nodes in the cluster:
Network Interface Information Requests
The following network interface information requests return information about the interfaces connected to a node:
Network Information Requests
The following network information requests return information about networks that are part of a cluster:
Event Notification Requests
The following event notification routines return information about cluster, node, or
network events:
Resource Group Information Requests
The following resource group information requests return information about cluster resource groups:
Site Information Requests
The following site information requests return information about sites configured in an HACMP cluster:
Utilities
The Clinfo C API has the following utility routines:
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
Description
The cl_errmsg routine takes a status code returned by Clinfo and returns the text for that error code.
Parameters
Status Codes
A null-terminated error string.
For example, the string:
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
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:
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);printf("Can't lookup CLE_BADARGS");cl_perror Routine
Syntax
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:
yields the output:
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:
where n is the value of the specified status code.
Parameters
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
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
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
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
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
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
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
Status Codes
Example
See the example for the cl_getnodemap Routine.
cl_alloc_sitemap Routine
Syntax
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
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
Status Codes
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
Description
The cl_free_clustermap routine frees the storage previously allocated for the list of clusters by calling cl_alloc_clustermap.
Parameters
Example
See the example for the cl_getclusters Routine.
cl_free_groupmap Routine
Syntax
Description
The cl_free_groupmap routine frees the storage previously allocated by a call to cl_alloc_groupmap.
Parameters
Example
See the example for the cl_getgroupmap Routine.
cl_free_netmap Routine
Syntax
Description
Frees the storage previously allocated by a call to cl_alloc_netmap.
Parameters
Status Codes
None.
Example
See the example for the cl_getnetmap Routine.
cl_free_nodemap Routine
Syntax
Description
The cl_free_nodemap routine frees the storage previously allocated by calling the cl_alloc_nodemap routine.
Parameters
Example
See the example for the cl_getnodemap Routine.
cl_free_sitemap Routine
Syntax
Description
Frees the storage previously allocated by a call to cl_alloc_sitemap.
Parameters
Status Codes
None.
Example
See the example for the cl_getsitemap Routine.
cl_getcluster Routine
Syntax
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
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
Description
The cl_getclusterid routine returns the cluster ID of the cluster with the specified name.
Parameter
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
Description
Returns the cluster ID of the cluster with the specified network interface address.
Parameters
Status Codes
A non-negative number, which represents the cluster ID, signifies success. Otherwise, one of the following error status codes:
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
Description
Returns the cluster ID of the cluster with the specified network interface name.
Parameters
Status Codes
A non-negative number, which represents the cluster ID, signifies success. Otherwise, one of the following error status codes:
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
Description
Returns information about all working clusters.
Parameters
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
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
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
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
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
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
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
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
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
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
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
char *interfacename)Description
Returns the name of the interface with the specified cluster ID and IP address.
Parameters
Status Codes
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
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
Status Codes
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
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
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
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
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
Description
Returns information about any networks configured with the specified attribute (public, private or non-IP (serial)).
Parameters
Status Codes
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
Description
Returns information about any networks configured with the specified type (such as ether, token, hps).
Parameters
Status Codes
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
Description
Returns the state of the specified network on the specified node.
Parameters
Status Codes
Example
See the example for the cl_getnet Routine.
cl_getnode Routine
Syntax
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Description
Returns status of the cluster with the specified cluster ID.
Parameters
Status Codes
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
Description
Indicates whether the specified node is alive.
Parameters
Status Codes
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
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
Status Codes
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
cl_registereventnotify Routine
Syntax
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
Status Codes
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
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.
![]() ![]() ![]() |