Identifying the Current Node

The cmm_node_getid function, described in the cmm_node_getid(3CMM) man page, retrieves the nodeid of the current node, that is, the node on which your application is currently running. The nodeid is used in other CMM calls as a parameter.

If the current node is a nonpeer node, the cmm_node_getid function returns the CMM_ECONN message. For further details on return values, see TABLE 8-1.

The following example demonstrates how to use the cmm_node_getid function:

**EXAMPLE 5-1 `current_node.c`**
#include <stdio.h> #include <stdlib.h> int main(void) { cmm_nodeid_t curr_node; cmm_error_t result; result = cmm_node_getid(&currnode) if (result != CMM_OK printf("Couldn’t get node id: %s\n", cmm_strerror(result)); else printf("Current node id: %u\n",curr_node); return (result == CMM_OK ? 0 : 1); }

EXAMPLE 5-1 current_node.c

#include <stdio.h>
#include <stdlib.h>
 
 
int main(void)
{
    cmm_nodeid_t curr_node;
    cmm_error_t result;
 
    result = cmm_node_getid(&currnode)
    if (result != CMM_OK
        printf("Couldn’t get node id: %s\n",
        cmm_strerror(result));
    else
        printf("Current node id: %u\n",curr_node);
    return (result == CMM_OK ? 0 : 1);
}

Retrieving Information About the Master Node or Vice-Master Node

The cmm_master_getinfo function retrieves all of the available information about the master node in the cluster. This is similar to the cmm_member_getinfo function, but you do not need to provide the nodeid.

If there is no master node, the cluster is not in a valid state and the call returns the CMM_ENOCLUSTER error. During a failover triggered by the failure or disqualification of the master node, or during the cluster startup, there is a time during which no master exists. During this period, the CMM_ENOCLUSTER error is returned.

For more information about return values, see Return Values of the CMM API.

The cmm_vicemaster_getinfo function retrieves all of the available information about the vice-master node in the cluster. If there is no vice-master node, the function returns the CMM_ESRCH error. For information, see the cmm_vicemaster_getinfo(3CMM) man page.

These functions return the cmm_member_t structure. For information about the cmm_member_t structure, see Using the cmm_member_t Structure for Information About Member Nodes.

The following example demonstrates how to test for the presence of a vice-master node by using the cmm_vicemaster_getinfo function.

**EXAMPLE 5-2 `vicemaster_node.c`**
#include <stdio.h> #include <cmm/cmm.h> #include "common.h" int main(void) { cmm_member_t member_info; cmm_error_t result; result = cmm_vicemaster_getinfo(&member_info); switch (result) { case CMM_OK: printf("Current vicemaster node is: \n"); print_member(&member_info); break ; case CMM_ESRCH: printf("No vicemaster node currently in the cluster\n"); break ; default: printf("Couldn’t get vicemaster node information: %s\n", cmm_strerror(result)); break; } return (result == CMM_OK ? 0 : 1); }

EXAMPLE 5-2 vicemaster_node.c

#include <stdio.h>
#include <cmm/cmm.h>
 
#include "common.h"
 
int main(void)
{
    cmm_member_t  member_info;
    cmm_error_t  result;
 
    result = cmm_vicemaster_getinfo(&member_info);
    switch (result) {
    case CMM_OK:
        printf("Current vicemaster node is: \n");
        print_member(&member_info);
        break ;
    case CMM_ESRCH:
        printf("No vicemaster node currently in the cluster\n");
        break ;
    default:
        printf("Couldn’t get vicemaster node information: %s\n",
            cmm_strerror(result));
        break;
    }
    return (result == CMM_OK ? 0 : 1);
}

Retrieving Information About Any Node

The cmm_member_getinfo and cmm_potential_getinfo functions retrieve information about a specified node as explained in Identifying the Properties of a Node. The node must be identified by the nodeid argument. These functions return the cmm_member_t structure. For more information, see Using the cmm_member_t Structure for Information About Member Nodes.

If the cmm_member_getinfo function returns the CMM_ESRCH error, the node is out of the cluster. The cmm_potential_getinfo function will not fail in this situation and the member’s membership role will be CMM_OUT_OF_CLUSTER.

For more information about these functions, see the cmm_member_getinfo(3CMM) and cmm_potential_getinfo(3CMM) man pages.

The following code example demonstrates how to retrieve information about the current node by using the cmm_member_getinfo function:

**EXAMPLE 5-3 Retrieving Information About the Current Node Using the `cmm_member_getinfo` Function**
#include <stdio.h> #include <cmm/cmm.h> #include "common.h" int main(void) { cmm_member_t member_info; cmm_error_t result; cmm_nodeid_t current; result = cmm_member_getinfo(current, &member_info); if (result != CMM_OK) { printf("Failed to retrieve the current node’s id:\n %s", cmm_strerror(result)); return 1; } result = cmm_member_getinfo(current, &member_info); switch (result) { case CMM_OK: printf("Current member node is:\n"); print_member(&member_info); break; case CMM_ESRCH: printf("Current node is NOT in the cluster\n"); break; default: printf("Couldn’t get member node information: %s\n", cmm_strerror(result)); break; } return (result == CMM_OK ? 0 : 1); }

EXAMPLE 5-3 Retrieving Information About the Current Node Using the cmm_member_getinfo Function

#include <stdio.h>
#include <cmm/cmm.h>
 
#include "common.h"
 
int main(void)
{
    cmm_member_t  member_info;
    cmm_error_t result;
    cmm_nodeid_t current;
 
    result = cmm_member_getinfo(current, &member_info);
    if (result != CMM_OK) {
        printf("Failed to retrieve the current node’s id:\n %s",
                cmm_strerror(result));
        return 1;
    }
 
    result = cmm_member_getinfo(current, &member_info);
    switch (result) {
    case CMM_OK:
        printf("Current member node is:\n");
        print_member(&member_info);
        break;
    case CMM_ESRCH:
        printf("Current node is NOT in the cluster\n");
        break;
    default:
        printf("Couldn’t get member node information: %s\n",
            cmm_strerror(result));
        break;
    }
    return (result == CMM_OK ? 0 : 1);
}

Retrieving Information About All Nodes in the Cluster

The cmm_member_getcount and cmm_member_getall functions retrieve information for all peer nodes in the cluster.

The cmm_member_getcount function counts the number of peer nodes in the cluster.

The cmm_member_getall function fills an array of cmm_member_t structures.

Using the value returned by the cmm_member_getcount function, you can dynamically allocate the table. For more information, see the cmm_member_getcount(3CMM) man page.

The following example demonstrates how to retrieve information about all peer nodes in the cluster.

**EXAMPLE 5-4 `all_nodes.c`**
#include <stdio.h> #include <stdlib.h> #include <cmm/cmm.h> #include "common.h" int main(void) { cmm_member_t member_table; cmm_error_t result; uint32_t member_count ; uint32_t members_in_table; uint32_t i; result = cmm_member_getcount(&member_count); if (result != CMM_OK) { printf("Failed to get the node count: %s\n", cmm_strerror(result)); return 1; } member_table = (cmm_member_t ) calloc(member_count, sizeof(cmm_member_t)); if (member_table == NULL) { printf("Failed to allocate memory\n"); return 1; } result = cmm_member_getall(member_count, member_table, &members_in_table); if (result != CMM_OK) { printf("Failed to get the node’s information: %s\n, cmm_strerror(result)); return 1 ; } for (i = 0; i < members_in_table; i++) print_member(&member_table[i]); return 0; }

EXAMPLE 5-4 all_nodes.c

#include <stdio.h>
#include <stdlib.h>
#include <cmm/cmm.h>
 
#include "common.h"
 
 
int main(void)
{
    cmm_member_t *member_table;
    cmm_error_t  result;
    uint32_t     member_count ;
    uint32_t     members_in_table;
    uint32_t     i;
 
    result = cmm_member_getcount(&member_count);
    if (result != CMM_OK) {
        printf("Failed to get the node count: %s\n",
                cmm_strerror(result));
       return 1;
    }
 
member_table = (cmm_member_t *) calloc(member_count,
                                       sizeof(cmm_member_t));
 
    if (member_table == NULL) {
        printf("Failed to allocate memory\n");
        return 1;
    }
 
    result = cmm_member_getall(member_count, member_table,
                               &members_in_table);
    if (result != CMM_OK) {
            printf("Failed to get the node’s information: %s\n,
            cmm_strerror(result));
        return 1 ;
    }
 
    for (i = 0; i < members_in_table; i++)
        print_member(&member_table[i]);
 
    return 0;
}

Identifying the Role of a Node

The cmm_potential_getinfo and cmm_member_getinfo functions retrieve information about a node identified by its nodeid. For details on the roles that a node can have, see Membership Roles.

To find the nodeid of a node, see EXAMPLE 5-1.

The following functions retrieve specific information about the role of a node:

`cmm_member_ismaster`	This function tests whether the node identified by the cmm_member_t structure is master. See the `cmm_member_ismaster`(3CMM) man page.
`cmm_member_isvicemaster`	This function tests whether the node identified by the cmm_member_t structure is vice-master. See the `cmm_member_isvicemaster`(3CMM) man page.
`cmm_member_isoutofcluster`	This function tests whether a node is out of the cluster. See the `cmm_member_isoutofcluster`(3CMM) man page.

If the tested condition is false, the functions in the preceding list return 0. Otherwise, these functions return a value other than 0. These functions are used in EXAMPLE 4-1.

You can also find the role of a node from the command line by using the nhcmmrole command on the node. For details about this command, see the nhcmmrole(1M) man page, or for the Linux OS, refer to the nhcmmrole(8) man page.

Note - The role of a node is also specified in the sflag field of the cmm_member_t structure returned by these functions. See Using the sflag Field of the cmm_member_t Structure. To get node information, it is better to use the CMM API. Do not to attempt direct extraction of node information from the sflag field of the cmm_member_t structure.

Identifying the Properties of a Node

The eligibility of a node to become master is determined by properties such as its master-eligibility, qualification level, and synchronization state. The qualification level of a node, relevant only for master-eligible nodes, determines if the node can participate in a master or vice-master election. For information about qualification levels that a node can have, see Qualification Levels. The following functions retrieve information about the eligibility and qualification level of a node:

cmm_member_getinfo
cmm_potential_getinfo
cmm_member_iseligible
cmm_member_isdesynchronized
cmm_member_isqualified
cmm_member_isdisqualified

The cmm_member_getinfo function returns information for any peer node that is master, vice-master, or in the cluster.

The cmm_potential_getinfo function returns information for all peer nodes, even if the node has the CMM_OUT_OF_CLUSTER role and has not yet entered the cluster.

If a node is disqualified, it cannot become master or vice-master until it is requalified. Further information can be found in the relevant man pages, such as cmm_member_iseligible(3CMM). For an example that demonstrates how to requalify a node, see Setting the Qualification of a Node.

The function cmm_member_isdesynchronized tests if the master and vice-master nodes are synchronized. If the master and vice-master nodes are not synchronized, the vice-master node cannot become the master if the master fails. Similarly, at cluster startup, a desynchronized node cannot be elected master even if it is master-eligible and qualified. For more information about synchronization, see the definition of CMM_FLAG_SYNCHRO_NEEDED in Administrative Attributes. For more information about the cmm_member_isdesynchronized function, see the cmm_member_isdesynchronized(3CMM) man page.

The cmm_member_getinfo and cmm_potential_getinfo functions retrieve information about a node identified by nodeid. To find the nodeid, see EXAMPLE 5-1. Both functions retrieve this information from the cmm_member_t structure. For information about these functions, see the cmm_member_getinfo(3CMM) and cmm_potential_getinfo(3CMM) man pages.

Using the cmm_member_t Structure for Information About Member Nodes

The cmm_member_t structure, contained within the CMM API, is an important source of information about member nodes. This structure contains the following fields:

`nodeid`	The unique identifier of a node.
`name`	The user-visible string that identifies a node and is used to format display messages.
`addr`	Stores the dotted-decimal notation of the node Carrier Grade Transport Protocol (CGTP) address in a string that can be used as a parameter on any architecture. The size of this string is sufficient for IPv4 and IPv6 addresses.
`incarnation_number`	The instant of the last reboot expressed as the number of seconds elapsed since 00:00:00 UTC, January 1, 1970. The `incarnation_number` is computed locally by every node and sent to the master node, which dispatches it. Nodes use this field to detect whether another node has rebooted within an interval of time.
`sflag`	State information about the node. This is a concatenation of the administrative attributes, membership role, and qualification levels. For more detailed information about the `sflag` field, see Using the sflag Field of the cmm_member_t Structure.
`domainid`	The unique ID of the cluster that the node can join or has joined. All peer nodes in a cluster have the same `domainid`. A node can belong to only one cluster and the ID of this cluster is the cluster `domainid` of the current node.
`software_load_id`	This field is set at `1`.
`initial_election`	The election number when the node joined the cluster. The election number is increased with each change in the cluster state. This means that two nodes that joined the cluster at the same time can have the same initial election number. However, when two nodes join the cluster at different times, the second one will have an initial election number higher than that of the first node.

Using the `sflag` Field of the cmm_member_t Structure

As explained in Using the cmm_member_t Structure for Information About Member Nodes, the sflag part of the cmm_member_t structure stores information about a node's administrative attributes, membership role, and qualification levels. This information is stored in a bit mask in the sflag. The following functions extract information from the sflag field:

`cmm_member_isdesynchronized`	Determines whether a master-eligible node is desynchronized. While the node has the `CMM_OUT_OF_CLUSTER` role, the qualification level and `CMM_FLAG_SYNCHRO_NEEDED` flag are meaningless.
`cmm_member_isdisqualified`	Determines whether a master-eligible node has the `CMM_DISQUALIFIED_MEMBER` qualification level. While the node has the `CMM_OUT_OF_CLUSTER` role, the qualification level and `CMM_FLAG_SYNCHRO_NEEDED` flag are meaningless.
`cmm_member_isqualified`	Determines whether a master-eligible node has the `CMM_QUALIFIED_MEMBER` qualification level. While the node has the `CMM_OUT_OF_CLUSTER` role, the qualification level and `CMM_FLAG_SYNCHRO_NEEDED` flag are meaningless.
`cmm_member_iseligible`	Determines whether a node has the `CMM_ELIGIBLE_MEMBER` attribute.
`cmm_member_isexcluded`	Determines whether a node has the `CMM_EXCLUDED_MEMBER` attribute.
`cmm_member_isfrozen`	Determines whether a node has a `CMM_FROZEN_MEMBER` attribute.
`cmm_member_isoutofcluster`	Determines whether a node has the `CMM_OUT_OF_CLUSTER` role. While a node has the `CMM_OUT_OF_CLUSTER` role, the qualification level and synchronization flag of the node are meaningless.
`cmm_member_isvicemaster`	Determines whether a node has the `CMM_VICEMASTER` role.
`cmm_member_ismaster`	Determines whether a node has the `CMM_MASTER` role.

Note - It is safer to use the cmm_member_is... functions than to rely on direct extraction of node information from these extract flags.

Note - For more information about the cmm_member_is... functions, see Identifying the Current Node, and Identifying the Role of a Node. See also the cmm_member_iseligible(3CMM) and cmm_member_ismaster(3CMM) man pages.

Retrieving Node Information Using the CMM API