Go to main content

Reference for Oracle Solaris Cluster 4.4

Exit Print View

Updated: August 2018
 
 

scha_calls (3HA)

Name

scha_calls - Oracle Solaris 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 Oracle Solaris Cluster library functions scha_resource_get(), scha_resourcetype_get(), scha_resourcegroup_get(), scha_cluster_get(), scha_control(), scha_strerror(), and scha_resource_setstatus() 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() function also has a tag argument that indicates a control operation, but does not return information in an output argument.

The scha_resource_setstatus 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() 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_rg_preemption_mode_t

An enum type that indicates a value for the Preemption_mode resource group property.

typedef enum scha_rg_preemption_mode {
    SCHA_HAS_PREEMPTION_COST = 0,
    SCHA_NO_PREEMPTION_COST,
    SCHA_NEVER_PREEMPT_RG
} scha_rg_preemption_mode_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().

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.

19 SCHA_ERR_CLUSTER

Unable to communicate with the other cluster.

20 SCHA_ERR_ZONE_CLUSTER

Invalid zone cluster.

21 SCHA_ERR_ZC_DOWN

Zone cluster not in a “Running” state.

22 SCHA_ERR_LOADLIMIT

Invalid load limit.

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(7) for descriptions of the following attributes:

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

See Also

scha_cluster_open(3HA), scha_control(3HA)scha_resource_open(3HA), scha_resource_setstatus(3HA), scha_resourcegroup_open(3HA), scha_resourcetype_open(3HA), scha_strerror(3HA), attributes(7), scha_cmds(8HA), scha_resource_setstatus(8HA)