JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Cluster Reference Manual
search filter icon
search icon

Document Information

Preface

Introduction

OSC33 1

OSC33 1cl

OSC33 1ha

OSC33 1m

OSC33 3ha

scds_calls(3HA)

scds_close(3HA)

scds_error_string(3HA)

scds_error_string_i18n(3HA)

scds_failover_rg(3HA)

scds_fm_action(3HA)

scds_fm_net_connect(3HA)

scds_fm_net_disconnect(3HA)

scds_fm_print_probes(3HA)

scds_fm_sleep(3HA)

scds_fm_tcp_connect(3HA)

scds_fm_tcp_disconnect(3HA)

scds_fm_tcp_read(3HA)

scds_fm_tcp_write(3HA)

scds_free_ext_property(3HA)

scds_free_netaddr_list(3HA)

scds_free_net_list(3HA)

scds_free_port_list(3HA)

scds_get_current_method_name(3HA)

scds_get_ext_property(3HA)

scds_get_netaddr_list(3HA)

scds_get_port_list(3HA)

scds_get_resource_group_name(3HA)

scds_get_resource_name(3HA)

scds_get_resource_type_name(3HA)

scds_get_rg_hostnames(3HA)

scds_get_rg_hostnames_zone(3HA)

scds_get_rs_hostnames(3HA)

scds_get_zone_name(3HA)

scds_hasp_check(3HA)

scds_initialize(3HA)

scds_pmf_get_status(3HA)

scds_pmf_restart_fm(3HA)

scds_pmf_signal(3HA)

scds_pmf_start(3HA)

scds_pmf_start_env(3HA)

scds_pmf_stop(3HA)

scds_pmf_stop_monitoring(3HA)

scds_print_netaddr_list(3HA)

scds_print_net_list(3HA)

scds_print_port_list(3HA)

scds_property_functions(3HA)

scds_restart_resource(3HA)

scds_restart_rg(3HA)

scds_simple_net_probe(3HA)

scds_simple_probe(3HA)

scds_svc_wait(3HA)

scds_syslog(3HA)

scds_syslog_debug(3HA)

scds_timerun(3HA)

scha_calls(3HA)

scha_cluster_close(3HA)

scha_cluster_get(3HA)

scha_cluster_getlogfacility(3HA)

scha_cluster_getnodename(3HA)

scha_cluster_getzone(3HA)

scha_cluster_open(3HA)

scha_control(3HA)

scha_control_zone(3HA)

scha_resource_close(3HA)

scha_resource_get(3HA)

scha_resourcegroup_close(3HA)

scha_resourcegroup_get(3HA)

scha_resourcegroup_open(3HA)

scha_resource_open(3HA)

scha_resource_setstatus(3HA)

scha_resource_setstatus_zone(3HA)

scha_resourcetype_close(3HA)

scha_resourcetype_get(3HA)

scha_resourcetype_open(3HA)

scha_strerror(3HA)

scha_strerror_i18n(3HA)

OSC33 4

OSC33 5

OSC33 5cl

OSC33 7

OSC33 7p

Index

scha_cluster_open

, scha_cluster_close

, scha_cluster_get

- access and obtain information about a cluster

Synopsis

cc [flags…] -I /usr/cluster/include file -L /usr/cluster/lib -l scha
#include <scha.h>

scha_err_t scha_cluster_open(scha_cluster_t *handle);
scha_err_t scha_cluster_get(scha_cluster_t handle, const char **tag, ...);
scha_err_t scha_cluster_close(scha_cluster_t handle);

Description

The scha_cluster_open(), scha_cluster_get(), and scha_cluster_close() functions are used together to obtain information about a cluster.

scha_cluster_open() initializes cluster access and returns an access handle to be used by scha_cluster_get(). The handle argument is the address of a variable to hold the value that is returned by the function call.

scha_cluster_get() accesses cluster information as indicated by the tag argument. If you call this function in a non-global zone, the zone name and the node name are returned. The handle argument is a value that is returned from a prior call to scha_cluster_open(). The tag argument is a string value that is defined by a macro in the scha_tags.h header file. The arguments that follow the tag depend on the value of the tag argument.

You might need to provide an additional argument after the tag argument to indicate a cluster node or zone from which the information is to be retrieved. The last argument in the argument list is to be of a type that is suitable to hold the information that is indicated by the tag argument. This argument is the output argument for the cluster information. No value is returned for the output argument if the function fails. Memory that is allocated to hold information that is returned by the scha_cluster_get() function remains intact until scha_cluster_close() is called on the handle that is used for the scha_cluster_get() function.

scha_cluster_close() takes a handle argument that is returned from a previous call to the scha_cluster_get() function. This function invalidates the handle and frees memory that is allocated to return values to scha_cluster_get() calls that were made with the handle. Note that memory, if needed to return a value, is allocated for each get call. Space allocated to return a value in one call is not overwritten and reused by subsequent calls.

Macros That You Can Use for tag Arguments

Macros that are defined in scha_tags.h that you can use as tag arguments follow. The type of the output argument and any additional arguments are indicated. Structure and enum types are described in scha_calls(3HA).

SCHA_ALL_LOADLIMITS

The output argument type is scha_str_array_t**.

This macro returns all the loadlimit names defined in the cluster.

SCHA_ALL_NODEIDS

The output argument type is scha_uint_array_t**.

This macro returns numeric node identifiers of all the nodes in the cluster.

SCHA_ALL_NODENAMES

The output argument type is scha_str_array_t**.

This macro returns the names of all nodes in the cluster.

SCHA_ALL_NONGLOBAL_ZONES

The output argument type is scha_str_array_t**.

This macro returns zone names of all the non-global zones on all nodes in the cluster. The format of the zone name that is returned is nodename: zonename.

Non-global zones that are not currently included in any resource-group or resource-type node list and also are not in the RUNNING state might be excluded from the output.

SCHA_ALL_NONGLOBAL_ZONES_NODEID

The output argument type is scha_str_array_t**.

This macro returns zone names of all the non-global zones on the cluster node whose numeric node identifier is given as the argument. The format of the zone name that is returned is nodename: zonename.

Non-global zones that are not currently included in any resource-group or resource-type node list and also are not in the RUNNING state might be excluded from the output.

SCHA_ALL_PRIVATELINK_HOSTNAMES

The output argument type is scha_str_array_t**.

This macro returns the host names for all cluster nodes or zones by which the nodes or zones are addressed on the cluster interconnect.

SCHA_ALL_RESOURCEGROUPS

The output argument type is scha_str_array_t**.

This macro returns the names of all the resource groups that are being managed on the cluster.

SCHA_ALL_RESOURCETYPES

The output argument type is scha_str_array_t**.

This macro returns the names of all the resource types that are registered on the cluster.

SCHA_ALL_ZONES

The output argument type is scha_str_array_t**.

This macro returns zone names of all zones, including the global zone, on all nodes in the cluster. The format of the zone name that is returned is nodename: zonename.

Non-global zones that are not currently included in any resource-group or resource-type node list and also are not in the RUNNING state might be excluded from the output.

SCHA_ALL_ZONES_NODEID

The output argument type is scha_str_array_t**.

This macro returns zone names of all zones, including the global zone, on the cluster node whose numeric node identifier is given as the argument. The format of the zone name that is returned is nodename: zonename.

Non-global zones that are not currently included in any resource-group or resource-type node list and also are not in the RUNNING state might be excluded from the output.

SCHA_CLUSTERNAME

The output argument is type char**.

This macro returns the name of the cluster.

SCHA_HARD_LOADLIMIT

The output argument type is scha_str_array_t**.

This macro returns the hard load limit values for all nodes in the cluster, for a specified limit name. It requires an additional argument of the type char * that is a load limit name string.

Each element of the string array output is of the format "%s=%d", where the left-side string is a nodename or nodename: zonename, and the right-side integer is the hard load limit value for the specified limit name on that node or zone. If no hard limit is specified, the value of -1 is displayed for the hard limit.

SCHA_LOADLIMIT_PROPS

The output argument type is scha_str_array_t**.

This macro returns the hard and soft load limit values (delimited by /) for all nodes in the cluster, for a specified limit name. It requires an additional argument of the type char * that is a load limit name string.

Each element of the string array output is a string of the format "%s=%d/%d", where the left-side string is a nodename or nodename: zonename, the first integer is the soft limit, and the second integer is the hard limit. If no hard limit is specified, the value of -1 is displayed for the hard limit. If no soft limit is specified, the value 0 is displayed for the soft limit.

SCHA_LOADLIMITS_NODE

The output argument type is scha_str_array_t**.

This macro returns the load limits (delimited by /) and limit names for a specific node or zone. It requires an additional argument of the type char * that is a nodename or nodename: zonename.

Each element of the string array output is a string of the format "%s=%d/%d", where the string is a limitname defined on the specified node or zone, the first, integer is the soft limit value, and the second integer is the hard limit value. If no hard limit is specified, the value of -1 is displayed for the hard limit. If no soft limit is specified, the value 0 is displayed for the soft limit.

SCHA_NODEID_LOCAL

The output argument type is uint_t*.

This macro returns the numeric node identifier for the node where the command is executed.

SCHA_NODEID_NODENAME

The output argument type is uint_t*. An additional argument is of type char *. The macro requires an additional argument that is a name of a cluster node.

This macro returns the numeric node identifier of the node indicated by the name.

SCHA_NODENAME_LOCAL

The output argument type is char**.

This macro returns the name of the cluster node where the function is executed.

SCHA_NODENAME_NODEID

The output argument type is char**. An additional argument is of type uint_t. The additional argument is a numeric cluster node identifier.

This macro returns the name of the node indicated by the numeric identifier.

SCHA_NODESTATE_LOCAL

The output argument type is scha_node_state_t*.

This macro returns SCHA_NODE_UP or SCHA_NODE_DOWN, depending on the state of the node where the command is executed.

SCHA_NODESTATE_NODE

The output argument type is scha_node_state_t*. An additional argument is type char*. The macro requires an additional unflagged argument that is the name of a cluster node.

This macro returns SCHA_NODE_UP or SCHA_NODE_DOWN, depending on the state of the named node.

SCHA_PRIVATELINK_HOSTNAME_LOCAL

The output argument type is char**.

This macro returns the host name by which the node or zone on which the command is run is addressed on the cluster interconnect.

SCHA_PRIVATELINK_HOSTNAME_NODE

The output argument type is char**. An additional argument is of type char *. This macro requires an additional unflagged argument that is the name of a cluster node.

This macro returns the host name by which the named node or zone is addressed on the cluster interconnect.

SCHA_SOFT_LOADLIMIT

The output argument type is scha_str_array_t**.

This macro returns the soft load limits for all nodes in the cluster, for a specified limit name. It requires an additional argument of the type char * that is a load limit name string.

Each element of the string array output is of the format "%s=%d", where the left-side string is a nodename or nodename: zonename, and the right-side integer is the soft load limit value for the specified limit name on that node or zone. If no soft limit is specified, the value 0 is displayed for the soft limit.

SCHA_SYSLOG_FACILITY

The output argument type is int*.

This macro returns the number of the syslog(3C) facility that the RGM uses for log messages. The value that is returned is 24, which corresponds to the LOG_DAEMON facility value.

SCHA_ZONE_LOCAL

The output argument type is scha_str_array_t**.

This macro returns the name of the zone from which the call is made. The format of the zone name that is returned is nodename: zonename.

Errors

SCHA_ERR_NOERR

The function succeeded.

See scha_calls(3HA) for a description of other error codes.

Examples

Example 1 Using the scha_cluster_get() Function

The following example uses the scha_cluster_get() function to get the names of all cluster nodes. The function also determines whether the node is up or down.

The code example also prints the soft and hard load limit settings that are configured for the limitname called mylimit for every cluster node or zone where that limit was configured. The load limit values for each node or zone are printed in the format: nodename[:zonename]=softlimit/[hardlimit], where the hardlimit value is unlimited (-1) if there is no hard limit set.

#include <scha.h>
#include <stdio.h>
#include <stdlib.h>

main()
{
        scha_err_t              err;
        scha_node_state_t       node_state;
        scha_str_array_t        *all_nodenames;
        scha_cluster_t          handle;
        int                     ix;
        const char              *str;
        scha_str_array_t        *load_limits;

        err = scha_cluster_open(&handle);
        if (err != SCHA_ERR_NOERR) {
                fprintf(stderr, "FAILED: scha_cluster_open()0);
                exit(err);
        }

        err = scha_cluster_get(handle, SCHA_ALL_NODENAMES, &all_nodenames);
        if (err != SCHA_ERR_NOERR) {
                fprintf(stderr, "FAILED: scha_cluster_get()0);
                exit(err);
        }

        for (ix = 0; ix < all_nodenames->array_cnt; ix++) {
                err = scha_cluster_get(handle, SCHA_NODESTATE_NODE,
                    all_nodenames->str_array[ix], &node_state);
                if (err != SCHA_ERR_NOERR) {
                        fprintf(stderr, "FAILED: scha_cluster_get()"
                            "SCHA_NODESTATE_NODE0);
                        exit(err);
                }

                switch (node_state) {
                case SCHA_NODE_UP:
                        str = "UP";
                        break;
                case SCHA_NODE_DOWN:
                        str = "DOWN";
                        break;
                }

                printf("State of node: %s value: %s\
",
                    all_nodenames->str_array[ix], str);
        }
        err = scha_cluster_get(handle, SCHA_LOADLIMIT_PROPS, "mylimit",
            &load_limits);

        printf("\
\
Load limits settings for limitname 'mylimit':\
\
");

        for (ix = 0; ix < load_limits->array_cnt; ix++) {
            printf("%s\
", load_limits->str_array[ix]);
        }
}

Files

/usr/cluster/include/scha.h

Include file

/usr/cluster/lib/libscha.so

Library

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
SUNWscdev
Interface Stability
Evolving

See Also

scha_cluster_get(1HA), scha_calls(3HA), scha_cluster_getlogfacility(3HA), scha_cluster_getnodename(3HA), scha_strerror(3HA), syslog(3C), attributes(5), rg_properties(5)