Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Data Services Developer's Guide Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

## RMAPI Access Methods

The API provides functions to access resource type, resource, and resource group properties, and other cluster information. These functions are provided both in the form of shell commands and C functions, which enable you to implement control programs as shell scripts or as C programs.

### RMAPI Shell Commands

Shell commands are used in shell script implementations of the callback methods for resource types that represent services that are controlled by the cluster's RGM.

You can use these commands to complete the following tasks:

- Access information about resource types, resources, resource groups, and clusters.

- With a monitor, set the `Status` and `Status_msg` properties of a resource.

- Request the restart or relocation of a resource group.

Note - Although this section provides brief descriptions of the shell commands, the 1HA man pages provide the definitive reference for the shell commands. A man page of the same name is associated with each command, unless otherwise noted.

#### RMAPI Resource Commands

You can access information about a resource or set the `Status` and `Status_msg` properties of a resource with these commands.

`scha_resource_get`

  Accesses information about a resource or resource type that is under the control of the RGM. This command provides the same information as the `scha_resource_get()` C function. For details, see the `scha_resource_get`(1HA) man page.

`scha_resource_setstatus`

  Sets the `Status` and `Status_msg` properties of a resource that is under the control of the RGM. This command is used by the resource's monitor to indicate the state of the resource as perceived by the monitor. This command provides the same functionality as the `scha_resource_setstatus()` C function. This command is described in more detail in the `scha_resource_setstatus`(1HA) man page.

  Note - Although `scha_resource_setstatus()` is of particular use to a resource monitor, any program can call it.

#### Resource Type Command

`scha_resourcetype_get`

  Accesses information about a resource type that is registered with the RGM. This command provides the same functionality as the `scha_resourcetype_get()` C function. This command is described in more detail in the `scha_resourcetype_get`(1HA) man page.

#### Resource Group Commands

You can access information about or restart a resource group with these commands.

`scha_resourcegroup_get`

  Accesses information about a resource group that is under the control of the RGM. This command provides the same functionality as the `scha_resourcegroup_get()` C function. This command is described in more detail in the `scha_resourcegroup_get`(1HA) man page.

`scha_control`

  Requests the restart of a resource group that is under the control of the RGM or its relocation to a different node. This command provides the same functionality as the `scha_control()` and `scha_control_zone()` C functions. This command is described in more detail in the `scha_control`(1HA) man page.

#### Cluster Command

`scha_cluster_get`

  Accesses information about a cluster, such as the cluster name, node name, zone name, IDs, states, and resource groups. This command provides the same information as the `scha_cluster_get()` C function. This command is described in more detail in the `scha_cluster_get`(1HA) man page.

### C Functions

C functions are used in C program implementations of the callback methods for resource types that represent services that are controlled by the cluster's RGM.

You can use these functions to complete the following tasks:

- Access information about resource types, resources, resource groups, and clusters.

- Set the `Status` and `Status_msg` properties of a resource.

- Request the restart or relocation of a resource group.

- Convert an error code to a related error message.

Note - Although this section provides brief descriptions of the C functions, the 3HA man pages provide the definitive reference for the C functions. A man page of the same name is associated with each function, unless otherwise noted. See the `scha_calls`(3HA) man page for information about the output arguments and return codes of the C functions.

#### Resource Functions

These functions access information about a resource that is managed by the RGM or indicate the state of the resource as perceived by the monitor.

`scha_resource_open()`, `scha_resource_get()`, and `scha_resource_close()`

  These functions access information about a resource that is managed by the RGM. The `scha_resource_open()` function initializes access to a resource and returns a handle for `scha_resource_get()`, which accesses the resource information. The `scha_resource_close()` function invalidates the handle and frees memory that is allocated for `scha_resource_get()` return values.

  A resource can change, through cluster reconfiguration or administrative action, after `scha_resource_open()` returns the resource's handle. As a result, the information that `scha_resource_get()` obtains through the handle might be inaccurate. In cases of cluster reconfiguration or administrative action on a resource, the RGM returns the `scha_err_seqid` error code to `scha_resource_get()` to indicate that information about the resource might have changed. This error message is nonfatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the resource.

  One man page describes these three functions. You can access this man page through any of the individual functions `scha_resource_open`(3HA), `scha_resource_get`(3HA), or `scha_resource_close`(3HA).

`scha_resource_setstatus()`

  Sets the `Status` and `Status_msg` properties of a resource that is under the control of the RGM. The resource's monitor uses this function to indicate the resource's state.

  Note - Although `scha_resource_setstatus()` is of particular use to a resource monitor, any program can call it.

`scha_resource_setstatus_zone()`

  Like the `scha_resource_setstatus()` function, sets the `Status` and `Status_msg` properties of a resource that is under the control of the RGM. The resource's monitor uses this function to indicate the resource's state. However, this function also specifies the name of the zone in which the method is configured to run.

  Note - Although `scha_resource_setstatus_zone()` is of particular use to a resource monitor, any program can call it.

#### Resource Type Functions

These functions access information about a resource type that is registered with the RGM.

`scha_resourcetype_open()`, `scha_resourcetype_get()`, and `scha_resourcetype_close()`

  The `scha_resourcetype_open()` function initializes access to a resource and returns a handle for `scha_resourcetype_get()`, which accesses the resource type information. The `scha_resourcetype_close()` function invalidates the handle and frees memory that is allocated for `scha_resourcetype_get()` return values.

  A resource type can change, through cluster reconfiguration or administrative action, after `scha_resourcetype_open()` returns the resource type's handle. As a result, the information that `scha_resourcetype_get()` obtains through the handle might be inaccurate. In cases of cluster reconfiguration or administrative action on a resource type, the RGM returns the `scha_err_seqid` error code to `scha_resourcetype_get()` to indicate that information about the resource type might have changed. This error message is nonfatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the resource type.

  One man page describes these three functions. You can access this man page through any of the individual functions `scha_resourcetype_open`(3HA), `scha_resourcetype_get`(3HA), or `scha_resourcetype_close`(3HA).

#### Resource Group Functions

You can access information about a resource group or restart a resource group with these functions.

`scha_resourcegroup_open()`, `scha_resourcegroup_get()`, and `scha_resourcegroup_close()`

  These functions access information about a resource group that is managed by the RGM. The `scha_resourcegroup_open()` function initializes access to a resource group and returns a handle for `scha_resourcegroup_get()`, which accesses the resource group information. The `scha_resourcegroup_close()` function invalidates the handle and frees memory that is allocated for `scha_resourcegroup_get()` return values.

  A resource group can change, through cluster reconfiguration or administrative action, after `scha_resourcegroup_open()` returns the resource group's handle. As a result, the information that `scha_resourcegroup_get()` obtains through the handle might be inaccurate. In cases of cluster reconfiguration or administrative action on a resource group, the RGM returns the `scha_err_seqid` error code to `scha_resourcegroup_get()` to indicate that information about the resource group might have changed. This error message is nonfatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the resource group.

  One man page describes these three functions. You can access this man page through any of the individual functions `scha_resourcegroup_open`(3HA), `scha_resourcegroup_get`(3HA), and `scha_resourcegroup_close`(3HA).

`scha_control()` and `scha_control_zone()`

  Requests the restart of a resource group that is under the control of the RGM or its relocation to a different node. These functions are described in more detail in the `scha_control`(3HA) and `scha_control_zone`(3HA) man pages.

#### Cluster Functions

These functions access or return information about a cluster.

`scha_cluster_open()`, `scha_cluster_get()`, and `scha_cluster_close()`

  These functions access information about a cluster, such as the cluster name, node name, zone name, IDs, states, and resource groups.

  A cluster can change, through reconfiguration or administrative action, after `scha_cluster_open()` returns the cluster's handle. As a result, the information that `scha_cluster_get()` obtains through the handle might be inaccurate. In cases of reconfiguration or administrative action on a cluster, the RGM returns the `scha_err_seqid` error code to `scha_cluster_get()` to indicate that information about the cluster might have changed. This error message is nonfatal. The function returns successfully. You can choose to ignore the message and accept the returned information. Alternatively, you can close the current handle and open a new handle to access information about the cluster.

  One man page describes these three functions. You can access this man page through any of the individual functions `scha_cluster_open`(3HA), `scha_cluster_get`(3HA), and `scha_cluster_close`(3HA).

`scha_cluster_getlogfacility()`

  Returns the number of the system log facility that is being used as the cluster log. Uses the returned value with the `syslog()` Oracle Solaris function to record events and status messages to the cluster log. This function is described in more detail in the `scha_cluster_getlogfacility`(3HA) man page.

`scha_cluster_getnodename()`

  Returns the name of the cluster node on which the function is called. This function is described in more detail in the `scha_cluster_getnodename`(3HA) man page.

#### Utility Function

This function converts an error code to an error message.

`scha_strerror()`

  Translates an error code that is returned by one of the `scha_` functions to a corresponding error message. Use this function with the `logger` command to log messages in the Oracle Solaris system log (`syslog`). This function is described in more detail in the `scha_strerror`(3HA) man page.

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