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

Search Scope:

- This Document
- Entire Library

### scha_resource_open

### , scha_resource_open_zone

### , scha_resource_get

### , scha_resource_get_zone

### , scha_resource_close

- resource information access functions

### Synopsis

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

    scha_err_t scha_resource_open(const char *rname, const char *rgname,
         scha_resource_t *handle);

    scha_err_t scha_resource_open_zone(const char *cluster, const char *rs_name,
         const char *rg_name, scha_resource_t *handlep);

    scha_err_t scha_resource_get(scha_resource_t handle, const char *tag,...);

    scha_err_t scha_resource_get_zone(const char *cluster, scha_resource_t handlep,
         const char *rs_tag, ...);

    scha_err_t scha_resource_close(scha_resource_t handle);

## Description

The `scha_resource_open()`, `scha_resource_get()`, and `scha_resource_close()` functions are used together to access information about a resource that is managed by the Resource Group Manager (RGM) cluster facility.

`scha_resource_open()` initializes access of the resource and returns a handle to be used by `scha_resource_get()`.

The rname argument of `scha_resource_open()` names the resource to be accessed. The rgname argument is the name of the resource group in which the resource is configured. The rgname argument may be `NULL` if the group name is not known. However, the execution of the function is more efficient if it is provided. The handle argument is the address of a variable to hold the value returned from the function call.

`scha_resource_get()` accesses resource information as indicated by the tag argument. The tag argument should be a string value defined by a macro in the `scha_tags.h` header file. Arguments following the tag depend on the value of tag. An additional argument following the tag might be needed to indicate a cluster node from which the information is to be retrieved, or other information that is specific to the tag. The last argument in the argument list is to be of a type that is suitable to hold the information that is indicated by tag. This argument is the output argument for the resource information. No value is returned for the output argument if the function fails.

Memory that is allocated to hold information returned by `scha_resource_get()` remains intact until `scha_resource_close()` is called on the handle used for the `scha_resource_get()`. Note that repeated calls to `scha_resource_get()` with the same handle and tag cause new memory to be allocated. Space allocated to return a value in one call will not be overwritten and reused by subsequent calls.

The `scha_resource_close()` function takes a handle argument that is returned from a previous call to `scha_resource_open()`. It invalidates the handle and frees memory allocated to return values to `scha_resource_get()` calls that were made with the handle.

Macros defined in `scha_tags.h` that might be used as tag arguments to `scha_resource_get()` follow.

The type of the output argument and any additional arguments are indicated. Structure and `enum` types are described in `scha_calls`(3HA).

The `scha_resource_open_zone()` and `scha_resource_get_zone()` functions serve the same purpose as `scha_resource_open()` and `scha_resource_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_resource_open_zone()` or `scha_resource_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_resource_open()` or `scha_resource_get()`, respectively.

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

### Tag Arguments

Macros that name resource properties are listed below. The value of the property of the resource is output. The `SCHA_RESOURCE_STATE`, `SCHA_STATUS`, `SCHA_NUM_RG_RESTARTS`, and `SCHA_NUM_RESOURCE_RESTARTS` properties refer to the value on the node where the command is executed (see `r_properties`(5)).

The type of output argument and any additional arguments are indicated.

Extension properties

  These properties are declared in the Resource Type Registration (RTR) file of the resource's type. The implementation of the resource type defines these properties.

`SCHA_AFFINITY_TIMEOUT`

  The output argument type is `int*`.

`SCHA_ALL_EXTENSIONS`

  The output argument type is `scha_str_array_t**`. Returns the names of all extension properties of the resource.

`SCHA_APPLICATION_USER`

  The output argument type is `char**`.

`SCHA_BOOT_TIMEOUT`

  The output argument type is `int*`.

`SCHA_CHEAP_PROBE_INTERVAL`

  The output argument type is `int*`.

`SCHA_EXTENSION`

  The output argument type is `scha_extprop_value_t**`. Requires an additional argument of type `char*`, which provides the name of an extension property. Returns the type of property and its value for the local node.

  When a user requests the value of this property on a node for which an explicit value has not been assigned, the default value that is declared in the RTR file is returned. See the `rt_reg`(4) man page.

`SCHA_EXTENSION_NODE`

  The output argument type is `scha_extprop_value_t**`. Requires two additional arguments of type `char*`. The first argument provides the name of the extension property and the second argument names a cluster node. Returns the type of property and its value for the named node.

  When a user requests the value of this property on a node for which an explicit value has not been assigned, the default value that is declared in the RTR file is returned. See the `rt_reg`(4) man page.

`SCHA_FAILOVER_MODE`

  The output argument type is `scha_failover_mode_t*`.

`SCHA_FINI_TIMEOUT`

  The output argument type is `int*`.

`SCHA_GLOBAL_ZONE_OVERRIDE`

  The output argument type is `boolean_t*`.

`SCHA_GROUP`

  The output argument type is `char**`. Returns the name of the resource group in which the resource is configured.

`SCHA_INIT_TIMEOUT`

  The output argument type is `int*`.

`SCHA_LOAD_BALANCING_POLICY`

  The output argument type is `char**`.

`SCHA_LOAD_BALANCING_WEIGHTS`

  The output argument type is `scha_str_array_t**`.

`SCHA_MONITOR_CHECK_TIMEOUT`

  The output argument type is `int*`.

`SCHA_MONITOR_START_TIMEOUT`

  The output argument type is `int*`.

`SCHA_MONITOR_STOP_TIMEOUT`

  The output argument type is `int*`.

`SCHA_MONITORED_SWITCH`

  The output argument type is `scha_switch_t*`. The return value indicates if the resource is monitored on the local node.

`SCHA_MONITORED_SWITCH_NODE`

  The output argument type is `scha_switch_t*`. Requires an additional argument of type `char*`, which names a cluster node. The return value indicates if the resource is monitored on the specified node.

`SCHA_NETWORK_RESOURCES_USED`

  The output argument type is `scha_str_array_t**`.

`SCHA_NUM_RESOURCE_RESTARTS`

  The output argument type is `int*`. Returns the number of resource restart requests that have occurred for this resource in the zone in which the query is executed. For further details, see the `r_properties`(5) man page.

`SCHA_NUM_RG_RESTARTS`

  The output argument type is `int*`. Returns the number of resource group restart requests that have occurred for this resource in the zone in which the query is executed. For further details, see the `r_properties`(5) man page.

`SCHA_ON_OFF_SWITCH`

  The output argument type is `scha_switch_t*`. The return value indicates if the resource is enabled on the local node.

`SCHA_ON_OFF_SWITCH_NODE`

  The output argument type is `scha_switch_t*`. Requires an additional argument of type `char*`, which names a cluster node. The return value indicates if the resource is enabled on the specified node.

`SCHA_PORT_LIST`

  The output argument type is `scha_str_array_t**`.

`SCHA_POSTNET_STOP_TIMEOUT`

  The output argument type is `int*`.

`SCHA_PRENET_START_TIMEOUT`

  The output argument type is `int*`.

`SCHA_R_DESCRIPTION`

  The output argument type is `char**`.

`SCHA_RESOURCE_DEPENDENCIES`

  The output argument type is `scha_str_array_t**`. The return value lists the dependencies that are applicable on the local node.

`SCHA_RESOURCE_DEPENDENCIES_NODE`

  The output argument type is `scha_str_array_t**`. Requires an additional argument of type `char*`, which names a cluster node. The return value lists the dependencies that are applicable on the specified node.

`SCHA_RESOURCE_DEPENDENCIES_OFFLINE_RESTART`

  The output argument type is `scha_str_array_t**`. The return value lists the dependencies that are applicable on the local node.

`SCHA_RESOURCE_DEPENDENCIES_OFFLINE_RESTART_NODE`

  The output argument type is `scha_str_array_t**`. Requires an additional argument of type `char*`, which names a cluster node. The return value lists the dependencies that are applicable on the specified node.

`SCHA_RESOURCE_DEPENDENCIES_Q`

  The output argument type is `scha_str_array_t**`.

  The “Q” version of the `SCHA_RESOURCE_DEPENDENCIES` tag also returns the scope, or qualifier, if any, that was declared for the resource dependency. The `{LOCAL_NODE}`, `{ANY_NODE}`, `{FROM_RG_AFFINITIES}`, and `@node` qualifiers are described in the `r_properties`(5) man page.

`SCHA_RESOURCE_DEPENDENCIES_Q_OFFLINE_RESTART`

  The output argument type is `scha_str_array_t**`.

  The “Q” version of the `SCHA_RESOURCE_DEPENDENCIES_OFFLINE_RESTART` tag also returns the scope, or qualifier, if any, that was declared for the resource dependency. The `{LOCAL_NODE}`, `{ANY_NODE}`, `{FROM_RG_AFFINITIES}`, and `@node` qualifiers are described in the `r_properties`(5) man page.

`SCHA_RESOURCE_DEPENDENCIES_Q_RESTART`

  The output argument type is `scha_str_array_t**`.

  The “Q” version of the `SCHA_RESOURCE_DEPENDENCIES_RESTART` tag also returns the scope, or qualifier, if any, that was declared for the resource dependency. The `{LOCAL_NODE}`, `{ANY_NODE}`, `{FROM_RG_AFFINITIES}`, and `@node` qualifiers are described in the `r_properties`(5) man page.

`SCHA_RESOURCE_DEPENDENCIES_Q_WEAK`

  The output argument type is `scha_str_array_t**`.

  The “Q” version of the `SCHA_RESOURCE_DEPENDENCIES_WEAK` tag also returns the scope, or qualifier, if any, that was declared for the resource dependency. The `{LOCAL_NODE}`, `{ANY_NODE}`, `{FROM_RG_AFFINITIES}`, and `@node` qualifiers are described in the `r_properties`(5) man page.

`SCHA_RESOURCE_DEPENDENCIES_RESTART`

  The output argument type is `scha_str_array_t**`. The return value lists the dependencies that are applicable on the local node.

`SCHA_RESOURCE_DEPENDENCIES_RESTART_NODE`

  The output argument type is `scha_str_array_t**`. Requires an additional argument of type `char*`, which names a cluster node. The return value lists the dependencies that are applicable on the specified node.

`SCHA_RESOURCE_DEPENDENCIES_WEAK`

  The output argument type is `scha_str_array_t**`. The return value lists the dependencies that are applicable on the local node.

`SCHA_RESOURCE_DEPENDENCIES_WEAK_NODE`

  The output argument type is `scha_str_array_t**`. Requires an additional argument of type `char*`, which names a cluster node. The return value lists the dependencies that are applicable on the specified node.

`SCHA_RESOURCE_PROJECT_NAME`

  The output argument type is `char**`.

`SCHA_RESOURCE_STATE`

  The output argument type is `scha_rsstate_t*`. Returns the value of the resource's `RESOURCE_STATE` property for the local node.

`SCHA_RESOURCE_STATE_NODE`

  The output argument type is `scha_rsstate_t*`. Requires an additional argument of type `char*`, which names a cluster node. Returns the value of the resource's `RESOURCE_STATE` property for the named node.

`SCHA_RETRY_COUNT`

  The output argument type is `int*`.

`SCHA_RETRY_INTERVAL`

  The output argument type is `int*`.

`SCHA_SCALABLE`

  The output argument type is `boolean_t*`.

`SCHA_START_TIMEOUT`

  The output argument type is `int*`.

`SCHA_STATUS`

  The output argument type is `scha_status_value_t**`. Returns the value of the resource's `STATUS` property for the local node.

`SCHA_STATUS_NODE`

  The output argument type is `scha_status_value_t**`. Requires an additional argument of type `char*`, which names a cluster node. Returns the value of the resource's `STATUS` property for the named node.

`SCHA_STOP_TIMEOUT`

  The output argument type is `int*`.

`SCHA_THOROUGH_PROBE_INTERVAL`

  The output argument type is `int*`.

`SCHA_TYPE`

  The output argument type is `char**`.

`SCHA_TYPE_VERSION`

  The output argument type is `char**`.

`SCHA_UDP_AFFINITY`

  The output argument type is `boolean_t*`.

`SCHA_UPDATE_TIMEOUT`

  The output argument type is `int*`.

`SCHA_VALIDATE_TIMEOUT`

  The output argument type is `int*`.

`SCHA_WEAK_AFFINITY`

  The output argument type is `boolean_t*`.

Macros that name resource type properties are listed below. The value of the property of the resource's type is output. For descriptions of resource type properties, see `rt_properties`(5).

`SCHA_API_VERSION`

  The output argument type is `int*`.

`SCHA_BOOT`

  The output argument type is `char**`.

`SCHA_FAILOVER`

  The output argument type is `boolean_t*`.

`SCHA_FINI`

  The output argument type is `char**`.

`SCHA_GLOBAL_ZONE`

  The output argument type is `boolean_t*`.

`SCHA_INIT`

  The output argument type is `char**`.

`SCHA_INIT_NODES`

  The output argument type is `scha_initnodes_flag_t*`.

`SCHA_INSTALLED_NODES`

  The output argument type is `scha_str_array_t**`.

`SCHA_MONITOR_CHECK`

  The output argument type is `char**`.

`SCHA_MONITOR_START`

  The output argument type is `char**`.

`SCHA_MONITOR_STOP`

  The output argument type is `char**`.

`SCHA_PKGLIST`

  The output argument type is `scha_str_array_t**`.

`SCHA_POSTNET_STOP`

  The output argument type is `char**`.

`SCHA_PRENET_START`

  The output argument type is `char**`.

`SCHA_PROXY`

  The output argument type is `boolean_t*`.

`SCHA_RT_BASEDIR`

  The output argument type is `char**`.

`SCHA_RT_DESCRIPTION`

  The output argument type is `char**`.

`SCHA_RT_SYSTEM`

  The output argument type is `boolean_t*`.

`SCHA_RT_VERSION`

  The output argument type is `char**`.

`SCHA_SINGLE_INSTANCE`

  The output argument type is `boolean_t*`.

`SCHA_START`

  The output argument type is `char**`.

`SCHA_STOP`

  The output argument type is `char**`.

`SCHA_UPDATE`

  The output argument type is `char**`.

`SCHA_VALIDATE`

  The output argument type is `char**`.

If this resource's type declares the `GLOBAL_ZONE_OVERRIDE` resource property, the value that is retrieved by the `SCHA_GLOBAL_ZONE` optag is the current value of the `GLOBAL_ZONE_OVERRIDE` property, rather than the value of the `GLOBAL_ZONE` property. For more information, see the description of the `Global_zone` property in the `rt_properties`(5) man page and the `Global_zone_override` property in the `r_properties`(5) man page.

## Return Values

These functions return the following values:

`0`

  The function succeeded.

nonzero

  The function failed.

## Errors

`SCHA_ERR_NOERR`

  The function succeeded.

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

## Examples

Example 1 Using the `scha_resource_get()` Function

The following example uses `scha_resource_get()` to get the value of the `Retry_count` property of a resource, and the value of the extension property named `Loglevel`.

    main() {
      #include <scha.h>

      scha_err_t err;
      int retry_count_out;
      scha_extprop_value_t *loglevel_out;
      scha_resource_t handle;

    /* a configured resource */
      char * resource_name = "example_R";
    /* resource group containing example_R */
      char * group_name = "example_RG";

      err = scha_resource_open(resource_name, group_name, &handle);

      err = scha_resource_get(handle, SCHA_RETRY_COUNT, &retry_count_out);

    /* Given extension property must be defined in resourcetype RTR file. */
      err = scha_resource_get(handle, SCHA_EXTENSION, "LogLevel", &loglevel_out);

      err = scha_resource_close(handle);

      printf("The retry count for resource %s is %d\n", resource_name,
             retry_count_out);

      printf("The log level for resource %s is %d\n", resource_name,
             loglevel_out->val.val_int);
    }

## 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_resource_get`(1HA), `scha_calls`(3HA), `scha_strerror`(3HA), `attributes`(5), `r_properties`(5), `rt_properties`(5), `rt_reg`(4)

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