第 11 章 資料服務開發程式庫參考

本章列出並簡明描述了資料服務開發程式庫 (DSDL) API 的函式。請參閱個別 3HA 線上援助頁，以取得每個 DSDL 函式的完整說明。DSDL 僅定義了 C 介面。基於程序檔的 DSDL 介面無法使用。

DSDL 提供下列類型的函式：

• 通用函式

• 特性函式

• 網路資源存取函式

• PMF 函式

• 故障監視器函式

• 公用程式函式

DSDL 函式

以下子節簡明介紹了每種 DSDL 函式。不過，個別 3HA 線上援助頁是 DSDL 函式的決定性參考。

通用函式

本節中的函式提供廣泛功能。這些函式可讓您執行下列作業：

• 初始化 DSDL 環境

• 擷取資源、資源類型、資源群組名稱以及延伸特性值。

• 故障轉移並重新啟動資源群組以及重新啟動資源

• 將錯誤字串轉換為錯誤訊息

• 在逾時控制下執行指令

下列函式初始化呼叫方法：

• scds_initialize(3HA) – 配置資源並初始化 DSDL 環境。

• scds_close( 3HA) – 釋放 scds_initialize 配置的資源。

下列函式擷取關於資源、資源類型、資源群組與延伸特性的資訊：

• scds_get_resource_name(3HA) – 擷取呼叫程式的資源名稱。

• scds_get_resource_type_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(5) 資源的狀態資訊。此項資訊是從所有 SUNW.HAStoragePlus 資源的狀態 (線上或其他狀態) 取得，其中資源視所採用為其定義的 Resource_dependencies 或 Resource_dependencies_weak 系統特性而定。

下列函式重新啟動資源或資源群組，或對其進行防故障備用：

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

• scds_get_rg_property_name

• scds_get_rt_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_rg_hostnames(3HA) – 擷取資源群組中網路資源所使用的主機名稱清單。

• scds_get_rs_hostnames(3HA) – 擷取資源所使用的主機名稱清單。

• scds_print_net_list(3HA) – 列印 scds_get_rg_hostnames() 或 scds_get_rs_hostnames() 傳回的主機名稱清單之內容。

• scds_free_net_list(3HA) – 釋放 scds_get_rg_hostnames() 或 scds_get_rs_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) – 將建立 TCP 連線以連接至使用 IPv4 或 IPv6 定址的程序。

• 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(1M) 的隱含 tag 值。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) – 在系統日誌檔中寫入除錯訊息。