Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### 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`(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_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`(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.

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

ATTRIBUTE TYPE | ATTRIBUTE VALUE
--- | ---
Availability | `ha-cluster/developer/api`
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)

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |