scds_calls

- Oracle Solaris Cluster Data Services Development Library (DSDL) functions

Synopsis

cc [flags…] -I /usr/cluster/include file -L /usr/cluster/lib -l dsdev

#include <rgm/libdsdev.h>

Description

The Data Services Development Library (DSDL) is a set of higher-level library functions that encapsulate and extend the functionality of the scha library functions. The scha library functions are described in the scha_calls(3HA) man page.

DSDL functions are implemented in the libdsdev.so library.

DSDL functions are generally divided into the following categories.

• General-purpose functions

  General-purpose functions include initialization functions, retrieval functions, failover and restart functions, and execution functions. These functions enable you to perform the following operations:

  • Initialize the DSDL environment

  • Retrieve resource type, resource, and resource group names, and extension property values

  • Fail over and restart a resource group and restart a resource

  • Convert error strings to error messages

  • Execute a command under a timeout

• Property functions

  These functions provide convenience APIs for accessing specific properties of the relevant resource type, resource, and resource group, including some commonly used extension properties. The DSDL provides the scds_initialize() function to parse the command-line arguments. The library caches the various properties of the relevant resource type, resource, and resource group.

• Network resource access functions

  These functions manage network resources that are used by resources and resource groups. These functions handle host names, port lists, and network addresses, and they enable TCP-based monitoring.

• Process Monitor Facility (PMF) functions

  These functions encapsulate the Process Monitor Facility (PMF) functionality.

• Fault monitor functions

  These functions provide a predetermined model of fault monitoring by keeping the failure history and evaluating it in conjunction with the Retry_count and Retry_interval properties.

• Utility functions

  These functions enable you to write messages and debugging messages to the system log.

Initialization Functions

The following functions initialize the calling method:

• scds_initialize(3HA) – Allocates resources and initializes the DSDL environment.

• scds_close(3HA) – Frees resources that are allocated by the scds_initialize() function.

Retrieval Functions

The following functions retrieve information about zones, resource types, resources, resource groups, and extension properties:

• scds_get_zone_name(3HA) – Retrieves the name of the zone on whose behalf a method is running.

• scds_get_resource_type_name(3HA) – Retrieves the name of the resource type for the calling program.

• scds_get_resource_name(3HA) – Retrieves the name of the resource for the calling program.

• scds_get_resource_group_name(3HA) – Retrieves the name of the resource group for the calling program.

• scds_get_ext_property(3HA) – Retrieves the value of the specified extension property.

• scds_get_current_method_name(3HA) – Retrieves the last element of the path name by which the data service method was called. See the basename(3C) man page.

• scds_free_ext_property(3HA) – Frees the memory that is allocated by scds_get_ext_property().

The following function retrieves status information about the SUNW.HAStoragePlus resources that are used by a resource:

scds_hasp_check(3HA) – Retrieves status information about SUNW.HAStoragePlus resources that are used by a resource. This information is obtained from the state (online or otherwise) of all SUNW.HAStoragePlus resources on which the resource depends by using the Resource_dependencies or Resource_dependencies_weak system properties that are defined for the resource. See the SUNW.HAStoragePlus(5) man page for more information.

Failover and Restart Functions

The following functions fail over or restart a resource or resource group:

• scds_failover_rg(3HA) – Fails over a resource group.

• scds_restart_rg(3HA) – Restarts a resource group.

• scds_restart_resource(3HA) – Restarts a resource.

Execution Functions

The following functions execute a command under a timeout and convert an error code to an error message:

• scds_timerun(3HA) – Executes a command under a timeout value.

• scds_error_string(3HA) and scds_error_string_i18n(3HA) – Translates an error code to an error string. Strings that are returned by scds_error_string() are displayed in English. Strings that are returned by scds_error_string_i18n() are displayed in the native language that is specified by the LC_MESSAGES locale category.

• scds_svc_wait(3HA) - Waits for the specified timeout period for a monitored process to die.

Property Functions

These functions provide convenience APIs for accessing specific properties of the relevant resource type, resource, and resource group, including some commonly used extension properties. The DSDL provides the scds_initialize() function to parse the command-line arguments. The library caches the various properties of the relevant resource type, resource, and resource group.

The scds_property_functions(3HA) man page describes these functions, which include the following:

• scds_get_ext_property-name

• scds_get_rg_property-name

• scds_get_rs_property-name

• scds_get_rt_property-name

Network Resource Access Functions

You use these functions to manage network resources.

The following functions handle host names:

• scds_get_rs_hostnames(3HA) – Retrieves a list of host names that is used by the resource.

• scds_get_rg_hostnames(3HA) – Retrieves a list of host names that is used by the network resources in a resource group.

• scds_print_net_list(3HA) – Writes the contents of the host name list to syslog(3C). You typically use this function for debugging.

• scds_free_net_list(3HA) – Frees the memory that is allocated by scds_get_rs_hostnames() or scds_get_rg_hostnames().

The following functions handle port lists:

• scds_get_port_list(3HA) – Retrieves a list of port-protocol pairs that is used by a resource.

• scds_print_port_list(3HA) – Writes the contents of the port-protocol list to syslog(3C). You typically use this function for debugging.

• scds_free_port_list(3HA) – Frees the memory that is allocated by scds_get_port_list().

The following functions handle network addresses:

• scds_get_netaddr_list(3HA) – Retrieves a list of network addresses that is used by a resource.

• scds_print_netaddr_list(3HA) – Writes the contents of the network address list to syslog(3C). You typically use this function for debugging.

• scds_free_netaddr_list(3HA) – Frees the memory that is allocated by scds_get_netaddr_list().

The following functions enable TCP-based monitoring. Typically, a fault monitor uses these functions to establish a simple socket connection to a service, read and write data to the service to ascertain its status, and disconnect from the service.

This set of functions includes the following functions:

• scds_fm_tcp_connect(3HA) – Establishes a TCP connection to a process that uses IPv4 addressing only.

• scds_fm_net_connect(3HA) – Establishes a TCP connection to a process that uses either IPv4 or IPv6 addressing.

• scds_fm_tcp_read(3HA) – Uses a TCP connection to read data from the process that is being monitored.

• scds_fm_tcp_write(3HA) – Uses a TCP connection to write data to a process that is being monitored.

• scds_simple_probe(3HA) – Probes a process by establishing and terminating a TCP connection to the process. This function handles only IPv4 addresses.

• scds_simple_net_probe(3HA) – Probes a process by establishing and terminating a TCP connection to the process. This function handles either IPv4 or IPv6 addresses.

• scds_fm_tcp_disconnect(3HA) – Terminates the connection to a process that is being monitored. This function handles only IPv4 addresses.

• scds_fm_net_disconnect(3HA) – Terminates the connection to a process that is being monitored. This function handles either IPv4 or IPv6 addresses.

PMF Functions

These functions encapsulate the Process Monitor Facility (PMF) functionality. The DSDL model for monitoring through the PMF creates and uses implicit tag values for pmfadm. See the pmfadm(1M) man page for more information.

The PMF facility also uses implicit values for the Restart_interval, Retry_count, and action_script (the -t, -n, and -a options to pmfadm). Most important, the DSDL ties the process failure history, as determined by the PMF, into the application failure history as detected by the fault monitor to compute the restart or failover decision.

The set includes the following functions:

• scds_pmf_get_status(3HA) – Determines if the specified instance is being monitored under the PMF's control.

• scds_pmf_restart_fm(3HA) – Uses the PMF to restart the fault monitor.

• scds_pmf_signal(3HA) – Sends the specified signal to a process tree that is running under the PMF's control.

• scds_pmf_start(3HA) and scds_pmf_start_env(3HA) – Executes a specified program (including a fault monitor) under the PMF's control. In addition to performing the same operations as the scds_pmf_start() function, the scds_pmf_start_env() function also passes a provided environment to the executed program.

• scds_pmf_stop(3HA) – Terminates a process that is running under the PMF's control.

• scds_pmf_stop_monitoring(3HA) – Stops monitoring a process that is running under the PMF's control.

Fault Monitor Functions

These functions provide a predetermined model of fault monitoring by keeping the failure history and evaluating it in conjunction with the Retry_count and Retry_interval properties.

This set includes the following functions:

• scds_fm_sleep(3HA) – Waits for a message on a fault monitor control socket.

• scds_fm_action(3HA) – Takes action after a probe completes.

• scds_fm_print_probes(3HA) – Writes probe status information to the system log.

Utility Functions

The following functions enable you to write messages and debugging messages to the system log:

• scds_syslog(3HA) – Writes messages to the system log.

• scds_syslog_debug(3HA) – Writes debugging messages to the system log.

Files

/usr/cluster/include/scds.h

Include file

/usr/cluster/lib/libdsdev.so

Library

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

pmfadm(1M), scds_close(3HA), scds_error_string(3HA), scds_error_string_i18n(3HA), scds_failover_rg(3HA), scds_fm_action(3HA), scds_fm_net_connect(3HA), scds_fm_net_disconnect(3HA), scds_fm_print_probes(3HA), scds_fm_sleep(3HA), scds_fm_tcp_connect(3HA), scds_fm_tcp_disconnect(3HA), scds_fm_tcp_read(3HA), scds_fm_tcp_write(3HA), scds_free_ext_property(3HA), scds_free_net_list(3HA), scds_free_netaddr_list(3HA), scds_free_port_list(3HA), scds_get_ext_property(3HA), scds_get_netaddr_list(3HA), scds_get_port_list(3HA), scds_get_resource_group_name(3HA), scds_get_resource_name(3HA), scds_get_resource_type_name(3HA), scds_get_rg_hostnames(3HA), scds_get_rs_hostnames(3HA), scds_get_zone_name(3HA), scds_hasp_check(3HA), scds_initialize(3HA), scds_pmf_get_status(3HA), scds_pmf_restart_fm(3HA), scds_pmf_signal(3HA), scds_pmf_start(3HA), scds_pmf_stop(3HA), scds_pmf_stop_monitoring(3HA), scds_print_net_list(3HA), scds_print_netaddr_list(3HA), scds_print_port_list(3HA), scds_property_functions(3HA), scds_restart_resource(3HA), scds_restart_rg(3HA), scds_simple_net_probe(3HA), scds_simple_probe(3HA), scds_svc_wait(3HA), scds_syslog(3HA), scds_syslog_debug(3HA), bscds_timerun(3HA), scha_calls(3HA), SUNW.HAStoragePlus(5), attributes(5)