Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### scha_cluster_open

### , scha_cluster_open_zone

### , scha_cluster_get

### , scha_cluster_get_zone

### , scha_cluster_close

- 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_open_zone(const char *cluster, scha_cluster_t *handlep);

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

    scha_err_t scha_cluster_get_zone(const char *cluster, scha_cluster_t handlep,
         const char *cluster_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. 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 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.

The `scha_cluster_open_zone()` and `scha_cluster_get_zone()` functions serve the same purpose as `scha_cluster_open()` and `scha_cluster_get()` respectively, with an additional `cluster` argument specifying the name of a zone cluster in which the resource groups exist and on which you want to operate. These functions are useful when code is executed in the global zone but needs to operate on a specified zone cluster. They cannot be used within a zone cluster to access a different zone cluster.

If the `cluster` argument to `scha_cluster_open_zone()` or `scha_cluster_get_zone()` is NULL, the query is performed on the cluster within which the call is executed; in other words, the call with NULL argument is equivalent to `scha_cluster_open()` or `scha_cluster_get()`, respectively.

To close the handle returned by `scha_cluster_open_zone()`, use `scha_cluster_close()`. No `cluster` argument is required.

### 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_PRIVATELINK_HOSTNAMES`

  The output argument type is `scha_str_array_t**`.

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

`SCHA_ALL_PSTRINGS`

  The output argument type is `scha_str_array_t**`.

  This macro returns the names of all private strings that are defined in the cluster. For more information about private strings, see the `clpstring`(1CL) man page.

`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_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, and the right-side integer is the hard load limit value for the specified limit name on that node. 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, 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. It requires an additional argument of the type `char *` that is a nodename.

  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, 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 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 is addressed on the cluster interconnect.

`SCHA_PSTRING`

  The output argument type is `char**`.

  This macro returns the clear text value of a private string. It requires an additional argument of type `char*` that provides the name of a private string. Users other than superuser require `solaris.cluster.modify` role-based access control (RBAC) authorization to use this query tag. For more information about private strings, see the `clpstring`(1CL) man page.

`SCHA_RESOURCE_SECURITY`

  The output argument type is `char**`.

  This macro returns the current setting of the `resource_security` cluster property.

`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, and the right-side integer is the soft load limit value for the specified limit name on that node. 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.

## 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 where that limit was configured. The load limit values for each node are printed in the format: nodename=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 | `ha-cluster/developer/api`
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)

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |