RMAPI Access Methods

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

RMAPI Shell Commands

Shell commands are to be used in shell script implementations of the callback methods for resource types representing services controlled by the cluster's RGM. You can use these commands to:

• Access information about resources, resource types, resource groups, and clusters

• Use with a monitor to set the Status and Status_msg properties of a resource

• Request the restart or relocation of a resource group

Although this section provides brief descriptions of the shell commands, the individual (1HA) man pages provide the definitive reference for the shell commands. Each command has a man page of the same name 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(1HA) - Accesses information about a resource or resource type under the control of the RGM. It provides the same information as the scha_resource_get(3HA) function.

• scha_resource_setstatus(1HA) - Sets the Status and Status_msg properties of a resource under the control of the RGM. It is used by the resource's monitor to indicate the resource's state as perceived by the monitor. It provides the same functionality as the scha_resource_setstatus(3HA) C function.

  ---

  Note -

  Although scha_resource_setstatus is of particular use to a resource monitor, any program can call it.

  ---

Resource Type Command

This command accesses information about a resource type registered with the RGM.

• scha_resourcetype_get(1HA) - This command provides the same functionality as the scha_resourcetype_get(3HA) C function.

Resource Group Commands

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

• scha_resourcegroup_get(1HA) - Accesses information about a resource group under the control of the RGM. This command provides the same functionality as the scha_resourcetype_get(1HA) C function.

• scha_control(1HA) - Requests the restart of a resource group under the control of the RGM or its relocation to a different node. This command provides the same functionality as the scha_control(3HA) C function.

Cluster Command

This command accesses information about a cluster, such as node names, IDs, and states, the cluster name, resource groups, and so on.

• scha_cluster_get(1HA) - This command provides the same information as the scha_cluster_get(3HA) C function.

C Functions

C functions are to be used in C program implementations of the callback methods for resource types representing services controlled by the cluster's RGM. You can use these functions to do the following:

• Access information about resources, resource types, resource groups, and clusters

• Use with a monitor to set the Status and Status_msg properties of a resource

• Request the restart or relocation of a resource group

• Convert an error code to an appropriate error message

Although this section provides brief descriptions of the C functions, the individual (3HA) man pages provide the definitive reference for the C functions. Each function has a man page of the same name unless otherwise noted. See the scha_calls(3HA) man page for information on the output arguments and return codes of the C functions.

Resource Functions

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

• scha_resource_open(3HA), scha_resource_get(3HA), and scha_resource_close(3HA) - Together these functions access information on a resource 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 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, in which case the information scha_resource_get obtains through the handle could 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 information about the resource might have changed. This is a non-fatal error message--the function returns successfully. You can choose to ignore the message and accept the returned information, or you can close the current handle and open a new handle to access information about the resource.

  A single 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(3HA) - Sets the Status and Status_msg properties of a resource 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.

  ---

Resource Type Functions

Together these functions access information about a resource type registered with the RGM.

• scha_resourcetype_open(3HA), scha_resourcetype_get(3HA), scha_resourcetype_close(3HA)- 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 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, in which case the information scha_resourcetype_get obtains through the handle could 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 information about the resource type might have changed. This is a non-fatal error message--the function returns successfully. You can choose to ignore the message and accept the returned information, or you can close the current handle and open a new handle to access information about the resource type.

  A single 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 or restart a resource group with these functions.

• scha_resourcegroup_open(3HA), scha_resourcegroup_get(3HA), and scha_resourcegroup_close(3HA)-Together these functions access information on a resource group 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 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, in which case the information scha_resourcegroup_get obtains through the handle could 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 information about the resource group might have changed. This is a non-fatal error message--the function returns successfully. You can choose to ignore the message and accept the returned information, or you can close the current handle and open a new handle to access information about the resource group.

  A single 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), or scha_resourcegrooup_close(3HA)

• scha_control(3HA)- Requests the restart of a resource group under the control of the RGM or its relocation to a different node.

Cluster Functions

These functions access or return information about a cluster.

• scha_cluster_open(3HA), scha_cluster_get(3HA), and scha_cluster_close(3HA) - Together these functions access information about a cluster, such as node names, IDs, and states, cluster name, resource groups, and so on.

  A single 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), or scha_cluster_close(3HA)

  A cluster can change--through reconfiguration or administrative action--after scha_cluster_open returns the cluster's handle, in which case the information scha_cluster_get obtains through the handle could 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 information about the cluster might have changed. This is a non-fatal error message--the function returns successfully. You can choose to ignore the message and accept the returned information, or you can close the current handle and open a new handle to access information about the cluster.

• scha_cluster_getlogfacility(3HA) - Returns the number of the system log facility being used as the cluster log. Uses the returned value with the Solaris syslog(3) function to record events and status messages to the cluster log.

• scha_cluster_getnodename(3HA) - Returns the name of the cluster node on which the function is called.

Utility Function

This function converts an error code to an error message.

• scha_strerror(3HA) - Translates an error code--returned by one of the scha_ functions--to the appropriate error message. Use this function with logger(1) to log messages to the system log (syslog(3)).