scha_calls(3HA) (Sun Cluster Reference Manual for Solaris OS)

Sun Cluster Reference Manual for Solaris OS

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 overwritten 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