DSDL Functions

The following subsections provide a brief overview to each category of DSDL functions. However, the individual 3HA man pages are the definitive reference for DSDL functions.

General Purpose Functions

The functions in this section provide a broad range of functionality. These functions enable you to

• Initialize the DSDL environment

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

• Failover and restart a resource group and restart a resource

• Convert error strings to error messages

• Execute a command under a timeout

The following functions initialize the calling method.

• scds_initialize – allocate resources and initialize the DSDL environment.

• scds_close – free resources allocated by scds_initialize.

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

• scds_get_resource_name – retrieve the name of the resource for the calling program.

• scds_get_resource_type_name – retrieve the name of the resource type for the calling program.

• scds_get_resource_group_name – retrieve the name of the resource group for the calling program.

• scds_get_ext_property – retrieve the value of the specified extension property.

• scds_free_ext_property – free the memory allocated by scds_get_ext_property.

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

• scds_hasp_check – retrieves status information about SUNW.HAStoragePlus resources used by a resource. This information is obtained from the state (online or otherwise) of all SUNW.HAStoragePlus resources that the resource depends upon using the Resource_dependencies or Resource_dependencies_weak system properties defined for the resource.

  See “pmfadm” in Sun Cluster Data Services Guide for information on SUNW.HAStoragePlus.

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

• scds_failover_rg – fail over a resource group.

• scds_restart_rg – restart a resource group.

• scds_restart_resource – restart a resource.

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

• scds_timerun – execute a command under a timeout value.

• scds_error_string – translate an error code to an error string.

Property Functions

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

A single man page, scds_property_functions(3HA) describes all of these functions. This section contains the following functions

• scds_get_rs_property_name

• scds_get_rg_property_name

• scds_get_rt_property_name

• scds_get_ext_property_name

Network Resource-Access Functions

The functions listed in this section retrieve, print, and free network resources used by resources and resource groups. The scds_get_* functions in this section provide a convenient way of retrieving network resources without querying specific properties such as Network_resources_used, and Port_list using the RMAPI functions. The scds_print_* functions print values from the data structures returned by the scds_get_* functions. The scds_free_* functions free the memory allocated by the scds_get_* functions.

The following functions are concerned with hostnames.

• scds_get_rg_hostnames – retrieve a list of hostnames used by the network resources in a resource group.

• scds_get_rs_hostnames – retrieve a list of hostnames used by the resource.

• scds_print_net_list – print the contents of the list of hostnames returned by scds_get_rg_hostnames or scds_get_rs_hostnames.

• scds_free_net_list – free the memory allocated by scds_get_rg_hostnames or scds_get_rs_hostnames.

The following functions are concerned with port lists.

• scds_get_port_list – retrieve a list of port-protocol pairs used by a resource.

• scds_print_port_list – print the contents of the list of port-protocol pairs returned by scds_get_port_list.

• scds_free_port_list – free the memory allocated by scds_get_port_list.

The following functions are concerned with network addresses.

• scds_get_netaddr_list – retrieve a list of network addresses used by a resource.

• scds_print_netaddr_list – print the contents of the list of network addresses returned by scds_get_netaddr_list.

• scds_free_netaddr_list – free the memory allocated by scds_get_netaddr_list.

Fault Monitoring Using TCP Connections

The functions in this section 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 then disconnect from the service.

This section contains the following functions.

• scds_tcp_connect – establish a TCP connection to a process.

• scds_tcp_read – use a TCP connection to read data from the process being monitored.

• scds_tcp_write – use a TCP connection to write data to a process being monitored.

• scds_simple_probe – probe a process by establishing and terminating a TCP connection to the process.

• scds_tcp_disconnect – terminate the connection to a process being monitored.

PMF Functions

These functions encapsulate the PMF functionality. The DSDL model for monitoring through PMF creates and uses implicit tag values for pmfadm(1M). The PMF facility also uses implicit values for the Restart_interval, Retry_count and action_script (the -t, -n and -a options to pmfadm(1M)). Most importantly, the DSDL ties the process death history, as discovered by PMF, into the application failure history as detected by the fault monitor to compute the restart or failover decision.

This section contains the following functions.

• scds_pmf_get_status – determine if the specified instance is being monitored under PMF control.

• scds_pmf_restart_fm – restarts the fault monitor using PMF.

• scds_pmf_signal – send the specified signal to a process tree running under PMF control.

• scds_pmf_start – execute a specified program (including a fault monitor) under PMF control.

• scds_pmf_stop – terminate a process running under PMF control.

• scds_stop_monitoring — stop monitoring a process running under PMF control.

Fault Monitor Functions

The functions in this section 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 section contains the following functions.

• scds_fm_sleep – wait for a message on a fault monitor control socket.

• scds_fm_action – take action after completion of a probe.

• scds_fm_print_probes – write probe status information to the system log.

Utility Functions

The functions in this section enable you to write messages and debugging messages to the system log. This section contains the following two functions.

• scds_syslog – write messages to the system log.

• scds_syslog_debug – write a debugging message to the system log.