第 11 章 DSDL API 函數

本章列出並簡明描述了資料服務開發程式庫 (DSDL) API 的函數。請參閱個別 3HA 線上援助頁，以取得每個 DSDL 函數的完整說明。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 資源的狀態資訊。此資訊是透過使用為該資源定義的 Resource_dependencies 或 Resource_dependencies_weak 系統特性，從其所附屬的所有 SUNW.HAStoragePlus 資源狀態 (線上或其他狀態) 取得。請參閱 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) – 將除錯訊息寫入系統記錄檔。