Chapter 11 DSDL API Functions

This chapter lists and briefly describes the Data Service Development Library (DSDL) API functions. See the individual 3HA man pages for a complete description of each DSDL function. The DSDL provides a C interface only. A script-based DSDL interface is not available.

This chapter covers the following topics:

• General-Purpose Functions

• Property Functions

• Network Resource Access Functions

• PMF Functions

• Fault Monitor Functions

• Utility Functions

General-Purpose Functions

The functions in this section provide a broad range of functionality.

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

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

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_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

The functions listed in this section retrieve, print, and free the network resources that are used by resources and resource groups. The scds_get_ functions in this section provide a convenient way of retrieving network resources without using the RMAPI functions to query specific properties, such as Network_resources_used and Port_list. The scds_print_name() functions print values from the data structures that are returned by the scds_get_name() functions. The scds_free_name() functions free the memory that is allocated by the scds_get_name() functions.

Host Name Functions

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

Port List Functions

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

Network Address Functions

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

Fault Monitoring Using TCP Connections Functions

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 disconnect from the service.

These functions include the following:

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

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