Skip Navigation Links
Exit Print View
| Oracle Solaris Cluster Reference Manual Oracle Solaris Cluster 4.1

Search Scope:

- This Document
- Entire Library

### 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 resource types, resources, resource groups, and extension properties:

- `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:

ATTRIBUTE TYPE | ATTRIBUTE VALUE
--- | ---
Availability | `ha-cluster/developer/api`
Interface Stability | Evolving

## 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), b`scds_timerun`(3HA), `scha_calls`(3HA), `SUNW.HAStoragePlus`(5), `attributes`(5)

Copyright © 2000, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |