Go to main content

Reference for Oracle Solaris Cluster 4.4

Exit Print View

Updated: August 2018
 
 

scha_resource_close (3HA)

Name

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(7)).

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(5) 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(5) 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(7) 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(7) 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_PRE_EVICT

The output argument type is boolean_t*.

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(7) 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(7) 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(7) 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(7) 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(7).

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(7) man page and the Global_zone_override property in the r_properties(7) 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(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
ha-cluster/developer/api
Interface Stability
Evolving

See Also

scha_calls(3HA), scha_strerror(3HA), rt_reg(5), attributes(7), r_properties(7), rt_properties(7), scha_resource_get(8HA)