scha_calls(3HA) Sun Cluster HA and Data Services scha_calls(3HA)
NAME
scha_calls - Sun Cluster library functions used in the implementation of callback methods and monitors of resource types
SYNOPSIS
cc [flags...] -I /usr/cluster/include file -L /usr/cluster/lib -l scha
#include <scha.h>
scha_err_t scha_get_function(handle, const char *tag...);
scha_err_t scha_control(const char *tag...
DESCRIPTION
The Sun Cluster library functions scha_resource_get(3HA), scha_resourcetype_get(3HA), scha_resourcegroup_get(3HA), scha_cluster_get(3HA),
scha_control(3HA), scha_strerror(3HA), and scha_resource_setstatus(3HA) provide an interface to be used in the implementation of callback
methods and monitors of resource types. The resource types represent services that are controlled by the cluster's Resource Group Manager
(RGM) facility.
The "get" functions access cluster configuration information. All these functions have the same general signature. These functions take a
handle argument that is returned from a previous call to an "open" function. This handle indicates the object in the cluster configuration
that is to be accessed. A tag argument indicates the property of the object that is to be accessed. The value of tag determines whether
additional arguments are needed and the type of a final "out" argument through which the requested information is returned. You can make
repeated "get" calls with the same handle until a "close" call, which invalidates the handle and frees memory that is allocated for values
that are returned from the "get" calls.
Memory, if needed to return a value, is allocated for each "get" call. Space allocated to return a value in one call will not be overwrit-
ten and reused by subsequent calls.
The scha_control(3HA) function also has a tag argument that indicates a control operation, but does not return information in an output
argument.
The scha_resource_setstatus(1HA) command sets the Status and Status_msg properties of a resource that is managed by the RGM.
The man pages for the individual functions should be referred to for the macro values accepted as tag argument values for each function,
and variable argument types for each tag. The types of output arguments are described in the next section.
There is one set of scha_err_t enum-type return values for the scha functions. The enum symbols, integer values, and meaning of the exit
codes are described in RETURN VALUES.
The scha_strerror(3HA) function converts an scha_err_t code returned by an scha function to the appropriate error message.
Output Argument Data Types
uint_t
An unsigned integer type. This type is defined in the system header file <sys/types.h>.
boolean_t
This type is defined in the system header file <sys/types.h>.
typedef enum { B_FALSE, B_TRUE } boolean_t;
scha_switch_t
An enum type that indicates an On_Off_switch or Monitored_switch resource property value.
typedef enum scha_switch {
SCHA_SWITCH_DISABLED = 0,
SCHA_SWITCH_ENABLED
} scha_switch_t;
scha_rsstate_t
An enum type that indicates a resource state.
typedef enum scha_rsstate {
SCHA_RSSTATE_ONLINE = 0,
SCHA_RSSTATE_OFFLINE,
SCHA_RSSTATE_START_FAILED,
SCHA_RSSTATE_STOP_FAILED,
SCHA_RSSTATE_MONITOR_FAILED,
SCHA_RSSTATE_ONLINE_NOT_MONITORED,
SCHA_RSSTATE_STARTING,
SCHA_RSSTATE_STOPPING
} scha_rsstate_t;
scha_rgstate_t
An enum type that indicates a resource group state.
typedef enum scha_rgstate {
SCHA_RGSTATE_UNMANAGED = 0,
SCHA_RGSTATE_ONLINE,
SCHA_RGSTATE_OFFLINE,
SCHA_RGSTATE_PENDING_ONLINE,
SCHA_RGSTATE_PENDING_OFFLINE,
SCHA_RGSTATE_ERROR_STOP_FAILED
SCHA_RGSTATE_ONLINE_FAULTED,
SCHA_RGSTATE_PENDING_ONLINE_BLOCKED
} scha_rgstate_t;
scha_rgmode_t
An enum type that indicates if the mode of a resource group is failover or scalable.
typedef enum scha_rgmode {
RGMODE_NONE = 0,
RGMODE_FAILOVER,
RGMODE_SCALABLE
} scha_rgmode_t;
scha_failover_mode_t
An enum type that indicates a value for the Failover_Mode resource property.
typedef enum scha_failover_mode {
SCHA_FOMODE_NONE = 0,
SCHA_FOMODE_HARD,
SCHA_FOMODE_SOFT,
SCHA_FOMODE_RESTART_ONLY,
SCHA_FOMODE_LOG_ONLY
} scha_failover_mode_t;
scha_initnodes_flag_t
An enum type that indicates a value for the Init_nodes resource type property.
typedef enum scha_initnodes_flag {
SCHA_INFLAG_RG_PRIMARIES = 0,
SCHA_INFLAG_RT_INSTALLED_NODES
} scha_initnodes_flag_t;
scha_node_state_t
An enum type that indicates whether a node is up or down.
typedef enum scha_node_state {
SCHA_NODE_UP = 0,
SCHA_NODE_DOWN
} scha_node_state_t;
scha_str_array_t
A structure that holds the value of a list of strings.
typedef struct scha_str_array {
uint_t array_cnt;
boolean_t is_ALL_value;
char **str_array;
} scha_str_array_t;
array_cnt Gives the number elements in the list.
is_ALL_value If a property is set to the "all" value, also known as the wild card or asterisk (*) character,
is_ALL_value is set to B_TRUE and str_array is NULL. As a result, str_array is ignored.
str_array A pointer to an array of array_cnt strings.
scha_uint_array_t
A structure that holds the value of a list of unsigned integers.
typedef struct scha_uint_array {
uint_t array_cnt;
uint_t *int_array;
} scha_uint_array_t;
array_cnt The number of elements in the list.
int_array A pointer to an array of array_cnt unsigned integers.
scha_status_value_t
The structure for returning the status and status message of a resource.
typedef struct scha_status_value {
scha_rsstatus_t status;
char *status_msg;
} scha_status_value_t;
typedef enum scha_rsstatus {
SCHA_RSSTATUS_ONLINE = 0,
SCHA_RSSTATUS_OFFLINE,
SCHA_RSSTATUS_FAULTED,
SCHA_RSSTATUS_DEGRADED,
SCHA_RSSTATUS_UNKNOWN
} scha_rsstatus_t;
status Holds an enum value that indicates the resource status as set by the resource monitor.
scha_extprop_value_t
The structure that is used for returning the value of an extension property.
The prop_type structure member indicates the type of the extension property and determines which element of the union is used for the
prop_type field and the return values:
SCHA_PTYPE_STRING val_str
SCHA_PTYPE_INT val_int
SCHA_PTYPE_ENUM val_enum
SCHA_PTYPE_BOOLEAN val_boolean
SCHA_PTYPE_STRINGARRAY val_strarray
typedef struct scha_extprop_value {
scha_prop_type_t prop_type;
union {
char *val_str;
int val_int;
char *val_enum;
boolean_t val_boolean;
scha_str_array_t *val_strarray;
} val;
} scha_extprop_value_t;
RETURN VALUES
The following is a list of the scha_err_t error numbers and the error codes returned by scha_strerror(3HA).
0 SCHA_ERR_NOERR No error was found.
1 SCHA_ERR_NOMEM Not enough swap.
2 SCHA_ERR_HANDLE Invalid resource management handle.
3 SCHA_ERR_INVAL Invalid input argument.
4 SCHA_ERR_TAG Invalid API tag.
5 SCHA_ERR_RECONF Cluster is reconfiguring.
6 SCHA_ERR_ACCESS Permission denied.
7 SCHA_ERR_SEQID Resource, resource group, or resource type has been updated since last scha_*_open call.
8 SCHA_ERR_DEPEND Object dependency problem.
9 SCHA_ERR_STATE Object is in wrong state.
10 SCHA_ERR_METHOD Invalid method.
11 SCHA_ERR_NODE Invalid node.
12 SCHA_ERR_RG Invalid resource group.
13 SCHA_ERR_RT Invalid resource type.
14 SCHA_ERR_RSRC Invalid resource.
15 SCHA_ERR_PROP Invalid property.
16 SCHA_ERR_CHECKS Sanity checks failed.
17 SCHA_ERR_RSTATUS Bad resource status.
18 SCHA_ERR_INTERNAL Internal error was encountered.
31 SCHA_ERR_TIMEOUT Operation timed out.
32 SCHA_ERR_FAIL Failover attempt failed.
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_cmds(1HA), scha_resource_setstatus(1HA)scha_cluster_get(3HA), scha_control(3HA), scha_resource_get(3HA), scha_resourcegroup_get(3HA),
scha_resource_setstatus(3HA), scha_resourcetype_get(3HA), scha_strerror(3HA), attributes(5)
Sun Cluster 3.2 7 Sep 2007 scha_calls(3HA)