第 11 章 DSDL API 函数

本章列举并简单介绍了数据服务开发库 (DSDL) API 函数。有关每一个 DSDL 函数的完整介绍，请参阅各个 3HA 手册页。DSDL 仅提供 C 接口。基于脚本的 DSDL 接口不可用。

本章包括以下主题：

• 通用函数

• 属性函数

• 网络资源访问函数

• PMF 函数

• 故障监视器函数

• 实用程序函数

通用函数

本节中的函数可提供各种功能。使用这些函数您可以执行以下操作：

• 初始化 DSDL 环境

• 检索资源类型、资源、资源组名称和扩展属性值

• 故障转移和重新启动资源组，以及重新启动资源

• 将错误字符串转换成错误消息

• 在超时值定义的时间之内执行命令

初始化函数

以下函数用于初始化调用方法：

• scds_initialize(3HA) – 分配资源和初始化 DSDL 环境。

• scds_close(3HA) – 释放由 scds_initialize() 分配的资源。

检索函数

以下函数用于检索关于资源类型、资源、资源组和扩展属性的信息：

• scds_get_resource_type_name(3HA) – 检索用于调用程序的资源类型的名称。

• scds_get_resource_name(3HA) – 检索用于调用程序的资源的名称。

• scds_get_resource_group_name(3HA) – 检索用于调用程序的资源组的名称。

• scds_get_ext_property(3HA) – 检索指定扩展属性的值。

• scds_free_ext_property(3HA) – 释放由 scds_get_ext_property() 分配的内存。

以下函数用于检索关于资源所使用的 SUNW.HAStoragePlus 资源的状态信息：

scds_hasp_check(3HA) – 检索关于资源所使用的 SUNW.HAStoragePlus 资源的状态信息。此信息来自资源所依赖的所有 SUNW.HAStoragePlus 资源的状态（联机或脱机），是通过使用为该资源定义的 Resource_dependencies 或 Resource_dependencies_weak 系统属性获得的。有关更多信息，请参见 SUNW.HAStoragePlus(5) 手册页。

故障转移和重新启动函数

以下函数用来进行故障转移或重新启动资源或资源组：

• scds_failover_rg(3HA) – 故障转移资源组。

• scds_restart_rg(3HA) – 重新启动资源组。

• scds_restart_resource(3HA) – 重新启动资源。

执行函数

以下函数在超时值定义的时间内执行命令，并将错误代码转换成错误消息：

• scds_timerun(3HA) – 在超时值定义的时间内执行命令。

• scds_error_string(3HA) – 将错误代码翻译为错误字符串。

属性函数

这些函数提供了公用 API，可用于访问相关资源类型、资源和资源组的具体属性，其中包括一些常用的扩展属性。DSDL 提供了 scds_initialize() 函数以解析命令行参数。该库用于高速缓存相关资源类型、资源和资源组的各种属性。

scds_property_functions(3HA) 手册页介绍了这些函数，包括：

• scds_get_rt_property-name

• scds_get_rs_property-name

• scds_get_rg_property-name

• scds_get_ext_property-name

网络资源访问函数

本节列出的函数用于检索、打印和释放由资源和资源组使用的网络资源。本节中的 scds_get_ 函数提供了一种便捷的检索网络资源的方法，该方法无需使用 RMAPI 函数即可查询具体属性（例如 Network_resources_used 和 Port_list）。scds_print_name() 函数用于打印来自 scds_get_name () 函数所返回的数据结构的值。scds_free_name () 函数用于释放 scds_get_ name() 函数所分配的内存。

主机名函数

以下函数用于处理主机名：

• scds_get_rs_hostnames(3HA) – 检索由资源使用的主机名列表。

• scds_get_rg_hostnames(3HA) – 检索由资源组中的网络资源使用的主机名列表。

• scds_print_net_list(3HA) – 打印由 scds_get_rs_hostnames() 函数或 scds_get_rg_hostnames() 函数返回的主机名列表的内容。

• scds_free_net_list(3HA) – 释放由 scds_get_rs_hostnames() 函数或 scds_get_rg_hostnames() 函数分配的内存。

端口列表函数

以下函数用于处理端口列表：

• scds_get_port_list(3HA) – 检索由资源使用的端口-协议对列表。

• scds_print_port_list(3HA) – 打印由 scds_get_port_list() 返回的端口-协议对列表的内容。

• scds_free_port_list(3HA) – 释放由 scds_get_port_list() 分配的内存。

网络地址函数

以下函数用于处理网络地址：

• scds_get_netaddr_list(3HA) – 检索由资源使用的网络地址列表。

• scds_print_netaddr_list(3HA) – 打印由 scds_get_netaddr_list() 返回的网络地址列表的内容。

• scds_free_netaddr_list(3HA) – 释放由 scds_get_netaddr_list() 分配的内存。

使用 TCP 连接进行故障监视

本节中的函数用于启用基于 TCP 的监视。通常，故障监视器使用这些函数来建立与服务之间的简单套接字连接、从服务中读取和向服务中写入数据以确定其状态，以及断开与服务的连接。

这些函数包括：

• scds_fm_tcp_connect(3HA) – 与仅使用 IPv4 寻址的进程建立 TCP 连接。

• scds_fm_net_connect(3HA) – 与使用 IPv4 或 IPv6 寻址的进程建立 TCP 连接。

• scds_fm_tcp_read(3HA) – 使用 TCP 连接从被监视的进程中读取数据。

• scds_fm_tcp_write(3HA) – 使用 TCP 连接向被监视的进程写入数据。

• scds_simple_probe(3HA) – 通过建立和终止与进程的 TCP 连接来探测进程。此函数只能处理 IPv4 地址。

• scds_simple_net_probe(3HA) – 通过建立和终止与进程的 TCP 连接来探测进程。此函数可以处理 IPv4 或 IPv6 地址。

• scds_fm_tcp_disconnect(3HA) – 终止与被监视进程的连接。此函数只能处理 IPv4 地址。

• scds_fm_net_disconnect(3HA) – 终止与被监视进程的连接。此函数可以处理 IPv4 或 IPv6 地址。

PMF 函数

这些函数封装了进程监视器工具 (PMF) 的功能。通过 PMF 进行监视的 DSDL 模型用于创建和使用 pmfadm 的隐含 tag 值。有关更多信息，请参见 pmfadm(1M) 手册页。

PMF 工具还使用 Restart_interval、Retry_count 和 action_script（pmfadm 的 -t、-n 和 -a 选项）的隐含值。最重要的是，DSDL 将由 PMF 确定的进程故障历史记录与由故障监视器检测到的应用程序故障历史记录相结合，来确定重新启动或故障转移决策。

此函数集包括以下函数：

• scds_pmf_get_status(3HA) – 确定指定实例是否正在 PMF 的控制下受到监视。

• scds_pmf_restart_fm(3HA) – 使用 PMF 来重新启动故障监视器。

• scds_pmf_signal(3HA) – 向在 PMF 的控制下运行的进程树发送指定信号。

• scds_pmf_start(3HA) – 执行在 PMF 的控制下的指定程序（包括故障监视器）。

• scds_pmf_stop(3HA) – 终止在 PMF 的控制下运行的进程。

• scds_pmf_stop_monitoring(3HA) – 停止监视在 PMF 的控制下运行的进程。

故障监视器函数

本节中的函数通过保留故障历史记录并将 Retry_count 和 Retry_interval 属性相结合对该历史记录进行评估，提供了预确定的故障监视模型。

此函数集包括以下函数：

• scds_fm_sleep(3HA) – 等待关于故障监视器控制套接字的消息。

• scds_fm_action(3HA) – 探测完成后采取措施。

• scds_fm_print_probes(3HA) – 向系统日志写入探测状态信息。

实用程序函数

使用以下函数，可以向系统日志写入消息和调试消息：

• scds_syslog(3HA) – 向系统日志写入消息。

• scds_syslog_debug(3HA) – 向系统日志写入调试消息。