scha_calls(3HA) (Sun Cluster 3.1 10/03 Reference Manual)

Sun Cluster 3.1 10/03 Reference Manual

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>

handle-type

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), and scha_strerror(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 and all have the same general signature in that they take a handle-type argument returned from a previous call to an "open" function that 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 in the variable argument list and the type of a final "out" argument through which the requested information is returned. Repeated "get" calls can be made using the same handle until a "close" call which invalidates the handle and frees any memory allocated for values 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 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 below.

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 the RETURN VALUES section.

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

Enum type indicating an On_Off_switch or Monitor_switch resource property value

typedef enum scha_switch {
    SCHA_SWITCH_DISABLED = 0,
    SCHA_SWITCH_ENABLED
} scha_switch_t;

scha_rsstate_t

Enum type indicating 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_t;

scha_rgstate_t

An enum type indicating 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_t;

scha_failover_mode_t

An enum type indicating a value for the Failover_Mode resource property

typedef enum scha_failover_mode {
    SCHA_FOMODE_NONE = 0,
    SCHA_FOMODE_HARD,
    SCHA_FOMODE_SOFT
} scha_failover_mode_t;

scha_initnodes_flag_t

An enum type indicating 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 indicating 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

This is 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_OK = 0,
    SCHA_RSSTATUS_OFFLINE,
    SCHA_RSSTATUS_FAULTED,
    SCHA_RSSTATUS_DEGRADED,
    SCHA_RSSTATUS_UNKNOWN
} scha_rsstatus_t;

status: holds an enum value indicating the resource status as set by the resource monitor

scha_extprop_value_t

This is 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_CHECK: sanity-checks failed
17 SCHA_ERR_RSTATUS: bad resource status
18 SCHA_ERR_INTERNAL: internal error was encountered

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