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.

• With a monitor, 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.

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 non-fatal. 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.

---

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 non-fatal. 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 non-fatal. 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()

Requests the restart of a resource group that is under the control of the RGM or its relocation to a different node. This function is described in more detail in the scha_control(3HA) man page.

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 names, 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 non-fatal. 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() 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 Solaris system log (syslog). This function is described in more detail in the scha_strerror(3HA) man page.