Resource Type Command

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

scha_resourcetype_get: This command provides the same functionality as the scha_resourcetype_get() C function.

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 under the control of the RGM. This command provides the same functionality as the scha_resourcetype_get() C function.
scha_control: 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() 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: This command provides the same information as the scha_cluster_get() 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

Note - 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(), scha_resource_get(), and scha_resource_close()

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()

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(), scha_resourcetype_get(), 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 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.

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), 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 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() 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 to log messages to the system log (syslog).

RMAPI Callback Methods

Callback methods are the key elements provided by the API for implementing a resource type. Callback methods enable the RGM to control resources in the cluster in the event of a change in cluster membership, such as a node boot or crash.

Note - The callback methods are executed by the RGM with root permissions because the client programs control HA services on the cluster system. Install and administer these methods with restrictive file ownership and permissions. Specifically, give them a privileged owner, such as bin or root, and do not make them writable.

This section describes callback method arguments and exit codes and lists and describes callback methods in the following categories:

Control and initialization methods
Administrative support methods
Net-relative methods
Monitor control methods

Note - Although this section provides brief descriptions of the callback methods, including the point at which the method is invoked and the expected effect on the resource, the rt_callbacks(1HA) man page is the definitive reference for the callback methods.


4. Resource Management API Reference RMAPI Access Methods RMAPI Shell Commands


	Resource Type Command This command accesses information about a resource type registered with the RGM. `scha_resourcetype_get` This command provides the same functionality as the `scha_resourcetype_get()` C function. 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 under the control of the RGM. This command provides the same functionality as the `scha_resourcetype_get()` C function. `scha_control` 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()` 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` This command provides the same information as the `scha_cluster_get()` 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 Note - 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()`, `scha_resource_get()`, and `scha_resource_close()` 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()` 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()`, `scha_resourcetype_get()`, `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 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. `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), `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 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()` 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` to log messages to the system log (`syslog`). RMAPI Callback Methods Callback methods are the key elements provided by the API for implementing a resource type. Callback methods enable the RGM to control resources in the cluster in the event of a change in cluster membership, such as a node boot or crash. Note - The callback methods are executed by the RGM with root permissions because the client programs control HA services on the cluster system. Install and administer these methods with restrictive file ownership and permissions. Specifically, give them a privileged owner, such as `bin` or `root`, and do not make them writable. This section describes callback method arguments and exit codes and lists and describes callback methods in the following categories: Control and initialization methods Administrative support methods Net-relative methods Monitor control methods Note - Although this section provides brief descriptions of the callback methods, including the point at which the method is invoked and the expected effect on the resource, the `rt_callbacks`(1HA) man page is the definitive reference for the callback methods.