第 4 章 资源管理 API 参考
本章提供组成资源管理 API (RMAPI) 的存取函数和回调方法的参考信息，其中列出并简单介绍了每一个函数和方法。但是，RMAPI 手册页才是有关这些函数和方法的权威参考。
-
RMAPI 存取方法 – 以 shell 脚本命令和 C 函数的形式
-
scha_resource_get(1HA)、scha_resource_close(3HA)、 scha_resource_get(3HA)、scha_resource_open(3HA)
-
scha_resourcetype_get(1HA)、scha_resourcetype_close(3HA)、 scha_resourcetype_get(3HA)、scha_resourcetype_open(3HA)
-
scha_resourcegroup_get(1HA)、scha_resourcegroup_get(3HA)、 scha_resourcegroup_close(3HA)、scha_resourcegroup_open(3HA)
-
scha_cluster_get(1HA)、scha_cluster_close(3HA)、 scha_cluster_get(3HA)、scha_cluster_open(3HA)
-
-
RMAPI 回调方法 – 在 rt_callbacks(1HA) 手册页中进行了介绍。
-
Start
-
Stop
-
Init
-
Fini
-
Boot
-
Prenet_start
-
Postnet_stop
-
Monitor_start
-
Monitor_stop
-
Monitor_check
-
Update
-
ValidateS
-
RMAPI 存取方法
API 提供可用来存取资源、资源类型和资源组特性以及其他群集信息的函数。这些函数以 shell 命令和 C 函数的形式提供，从而使资源类型提供者可以实现 shell 脚本或 C 程序形式的控制程序。
RMAPI Shell 命令
shell 命令用于资源类型的回调方法的 shell 脚本实现，这些资源类型表示群集的 RGM 所控制的服务。您可以使用这些命令执行以下操作：
-
存取关于资源、资源类型、资源组和群集的信息
-
与监视器配套使用以设置资源的 Status 和 Status_msg 特性
-
请求重新启动或重定位资源组
注意 –
虽然本节中提供了对 shell 命令的简单介绍，但是 1HA 一节中各个手册页提供的信息才是有关 shell 命令的权威参考。每个命令都对应一个具有相同名称的手册页，除非另外注明。
RMAPI 资源命令
您可以使用下面这些命令存取资源的信息或设置资源的 Status 和 Status_msg 特性。
- scha_resource_get
-
存取关于 RGM 所控制的资源和资源类型的信息。它提供与 scha_resource_get() 函数相同的信息。
- scha_resource_setstatus
-
设置 RGM 所控制的资源的 Status 和 Status_msg 特性。资源的监视器用它来指示监视器探测到的资源状态。它提供的功能与 scha_resource_setstatus() C 函数相同。
注意 –虽然对于资源监视器来说 scha_resource_setstatus() 有特定用途，但是任何程序都可以调用该函数。
资源类型命令
- scha_resourcetype_get
-
此命令提供与 scha_resourcetype_get() C 函数相同的功能。
资源组命令
- scha_resourcegroup_get
-
存取关于 RGM 所控制的资源组的信息。此命令提供与 scha_resourcetype_get() C 函数相同的功能。
- scha_control
-
请求重新启动 RGM 所控制的资源组或将其重定位到其他节点。此命令提供与 scha_control() C 函数相同的功能。
群集命令
下面的命令用来存取有关群集的信息，例如节点名称、节点 ID、节点状态、群集名称、资源组等。
- scha_cluster_get
-
此命令提供与 scha_cluster_get() C 函数相同的信息。
C 函数
C 函数用于资源类型的回调方法的 C 程序实现，该资源类型表示群集的 RGM 所控制的服务。您可以使用这些函数执行以下操作：
-
存取关于资源、资源类型、资源组和群集的信息
-
与监视器配套使用以设置资源的 Status 和 Status_msg 特性
-
请求重新启动或重定位资源组
-
将错误代码转换成相应的错误消息
注意 –
虽然本节中提供了对 C 函数的简单说明，但是各个 (3HA) 手册页中提供的信息才是有关 C 函数的权威参考。每个函数都对应一个具有相同名称的手册页，除非另外注明。有关 C 函数的输出参数和返回代码的信息，请参见 scha_calls( 3HA) 手册页。
资源函数
下面这些函数用来存取关于 RGM 所管理的资源的信息或用来指示监视器探测到的资源状态。
- scha_resource_open()、scha_resource_get () 和 scha_resource_close()
-
这些函数共同用于存取有关 RGM 所管理的资源的信息。scha_resource_open() 函数用来初始化对资源的存取并返回 scha_resource_get () 的句柄，用于存取资源信息。scha_resource_close() 函数可使该句柄无效并释放为 scha_resource_get() 的返回值分配的内存。
可以在 scha_resource_open() 返回该资源的句柄后通过群集重新配置或管理操作更改资源，这时 scha_resource_get() 通过该句柄获得信息可能会不准确。对资源进行群集重新配置或管理操作时，RGM 将向 scha_resource_get () 返回 scha_err_seqid 错误代码，以表明该资源的信息可能已更改。这是一个非致命性错误消息；函数将成功返回。您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取该资源的信息。
在单个手册页中描述了这三个函数。您可以通过以下任意一个函数存取此手册页：scha_resource_open(3HA)、scha_resource_get(3HA) 或 scha_resource_close(3HA)。
- scha_resource_setstatus()
-
设置 RGM 所控制的资源的 Status 和 Status_msg 特性。资源的监视器使用此函数指示该资源的状态。
注意 –虽然对于资源监视器来说 scha_resource_setstatus() 有特定用途，但是任何程序都可以调用该函数。
资源类型函数
下面这些函数共同用于存取通过 RGM 注册的资源类型的信息。
- scha_resourcetype_open()、scha_resourcetype_get()、scha_resourcetype_close()
-
scha_resourcetype_open() 函数用来初始化对资源类型的存取并返回 scha_resourcetype_get () 的句柄，用于存取资源类型的信息。 scha_resourcetype_close() 函数可使该句柄无效并释放为 scha_resourcetype_get() 的返回值分配的内存。
可以在 scha_resourcetype_open() 返回该资源的句柄后通过群集重新配置或管理操作更改资源类型，这时 scha_resource_get() 通过该句柄获得信息可能会不准确。对资源类型进行群集重新配置或管理操作时，RGM 将向 scha_resourcetype_get() 返回 scha_err_seqid 错误代码，以表明该资源类型的信息可能已更改。这是一个非致命性错误消息；函数将成功返回。您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取关于该资源类型的信息。
在单个手册页中描述了这三个函数。您可以通过以下任意一个函数存取此手册页：scha_resourcetype_open(3HA)、scha_resourcetype_get(3HA) 或 scha_resourcetype_close(3HA)。
资源组函数
- scha_resourcegroup_open(3HA)、scha_resourcegroup_get(3HA) 和 scha_resourcegroup_close(3HA)
-
这些函数共同用于存取有关 RGM 所管理的资源组的信息。scha_resourcegroup_open() 函数用来初始化对资源组的存取并返回 scha_resourcegroup_get () 的句柄，用于存取资源组信息。 scha_resourcegroup_close() 函数可使该句柄无效并释放为 scha_resourcegroup_get() 的返回值分配的内存。
可以在 scha_resourcegroup_open() 返回该资源的句柄后通过群集重新配置或管理操作更改资源类型，这时 scha_resourcegroup_get() 通过该句柄获得信息可能会不准确。对资源组进行群集重新配置或管理操作时，RGM 将向 scha_resourcegroup_get () 返回 scha_err_seqid 错误代码，以表明该资源组的信息可能已更改。这是一个非致命性错误消息；函数将成功返回。您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取关于该资源组的信息。
- scha_control(3HA)
-
请求重新启动 RGM 所控制的资源组或将其重定位到其他节点。
群集函数
- scha_cluster_open(3HA)、scha_cluster_get(3HA)、 scha_cluster_close(3HA)
-
这些函数共同用来存取群集信息，例如节点名称、节点 ID 和节点状态、群集名称、资源组等。
可以在 scha_cluster_open() 返回该资源的句柄后通过群集重新配置或管理操作更改资源，这时 scha_cluster_get() 通过该句柄获得信息可能会不准确。对群集进行群集重新配置或管理操作时，RGM 将向 scha_cluster_get() 返回 scha_err_seqid 错误代码，以表明该群集的信息可能已更改。这是一个非致命性错误消息；函数将成功返回。您可以选择忽略该消息并接受返回的信息；您也可以关闭当前句柄并打开一个新的句柄，以存取关于该群集的信息。
- scha_cluster_getlogfacility(3HA)
-
返回用作群集记录的系统记录工具的数量。使用返回值和 Solaris syslog() 函数将事件和状态消息记录到群集记录中。
- scha_cluster_getnodename(3HA)
-
返回在其上调用该函数的群集节点的名称。
实用程序函数
- scha_strerror(3HA)
-
将错误代码（由 scha_ 函数之一返回） 转换成相应的错误消息。使用此函数和 logger 可以将消息记录到系统日志 (syslog) 中。
RMAPI 回调方法
回调方法是 API 提供的用来实现资源类型的主要元素。当群集成员有所更改时（例如节点引导或崩溃），回调方法将启用 RGM 来控制该群集中的资源。
注意 –
RGM 以引导权限执行该回调方法，因为客户机程序将控制群集系统上的 HA 服务。安装和管理这些具有限制性文件拥有权和权限的方法。有时需要为它们指定特权属主，例如 bin 或 root，请不要使它们可写。
本节介绍回调方法参数和出口代码，还按以下分类列出并介绍了各个回调方法：
-
控制和初始化方法
-
管理支持方法
-
与网络相关的方法
-
监视器控制方法
注意 –
虽然本节提供了回调方法的简要说明（包括何时调用方法以及对资源的预期影响），但是 rt_callbacks( 1HA) 手册页才是有关回调方法的权威参考。
方法参数
method -R resource-name -T type-name -G group-name |
其中 method 是注册为 Start、Stop 或其他回调方法的程序的路径名。资源类型的回调方法在其注册文件中进行声明。
所有回调方法参数都作为标记值传送，-R 用来表示资源实例的名称，-T 用来表示资源的类型，-G 用来表示配置该资源的组。使用参数和存取函数来检索关于资源的信息。
Validate 方法通过附加参数（所调用资源和资源组的特性值）调用。
有关更多信息，请参见 scha_calls(3HA)。
出口代码
所有回调方法都定义了相同的出口代码，以指定方法调用对资源状态的影响。scha_calls (3HA) 手册页中介绍了所有这些出口代码。出口代码为：
-
0 — 方法成功
-
任意非零值 — 方法失败
RGM 还可处理回调方法执行过程中的不正常失败，例如超时和信息转储。
方法实现必须使用每个节点上的 syslog 输出失败信息。并不能保证写入 stdout 或 stderr 的输出信息一定会传送到用户（尽管它当前显示在本地节点的控制台中）。
控制和初始化回调方法
主要的控制和初始化回调方法用来启动和停止资源。其他方法用来执行对资源的初始化和终止代码。
- Start
-
当包含资源的资源组在群集节点上联机时，将对该群集节点调用此必需方法。此方法激活该节点上的资源。
在所激活的资源启动并且在本地节点上可用之前，Start 方法不应退出。因此，在退出之前，Start 方法应轮询该资源，以确定该资源是否已启动。此外，您应该为此方法设置足够长的超时值。例如，某些资源（例如数据库守护程序）需要较长的时间进行启动，因此，就要求该方法具有较长的超时值。
RGM 对 Start 方法失败的响应方式取决于 Failover_mode 特性的设置。
资源类型注册文件中的 START_TIMEOUT 特性用来设置资源的 Start 方法的超时值。
- Stop
-
当包含该资源的资源组在群集节点上脱机时，将对该群集节点调用此必需方法。如果该资源处于激活状态，则此方法可取消激活该资源。
在所控制资源在本地节点上完全停止所有活动并关闭所有文件描述符之前，Stop 方法不应退出，否则，因为 RGM 将认为该资源已经停止，而实际上它仍处于活动状态，就会导致数据被破环。避免数据被破坏的最可靠方法是终止与该资源有关的本地节点上的所有进程。
在退出之前，Stop 方法应该轮询该资源，以确定该资源是否停止。此外，您应该为此方法设置足够长的超时值。例如，某些资源（如数据库守护程序）需要较长的时间进行停止操作，因此，就要求该方法具有较长的超时值。
RGM 对 Stop 方法失败的响应方式取决于 Failover_mode 特性的设置（请参见资源特性）。
资源类型注册文件中的 STOP_TIMEOUT 特性用来设置资源的 Stop 方法的超时值。
- Init
-
当资源处于被管理状态时（一种情况是其所在的资源组从不受管理状态切换为被管理状态，另一种情况是在已处于被管理状态的资源组中创建该资源的情况）， 将调用此可选方法对该资源进行一次性初始化操作。对哪些节点调用该方法由 Init_nodes 资源特性决定。
- Fini
-
当资源处于不受管理状态时（一种情况是其所在的资源组转换为不受管理状态，另一种情况是该资源已从被管理资源组中删除），将调用此可选方法进行清除。对哪些节点调用该方法由 Init_nodes 资源特性决定。
- Fini
-
此可选方法与 Init 相似，在包含资源的资源组处于 RGM 的管理之下后调用此方法可初始化与群集相连接的节点上的资源。对哪些节点调用该方法由 Init_nodes 资源特性决定。引导或重新引导操作导致该节点连接或重新连接群集时，将调用 Boot 方法。
注意 –
Init、Fini 或 Boot 方法的失败将导致 syslog() 函数生成错误消息，但是不会影响该资源的 RGM 管理。
管理支持方法
对资源进行的管理操作包括设置和更改资源特性。Validate 和 Update 回调方法将启用资源类型实现来介入这些管理操作。
- Validate
-
当创建了资源且管理操作更新资源或其资源组的特性时，调用此可选方法。将对由资源类型的 Init_nodes 特性指定的一组群集节点调用此方法。将在应用创建或更新之前调用 Validate，方法对任意节点返回失败的出口代码都将导致创建或更新操作取消。
仅当通过管理操作更改资源或资源组特性时（而不是在 RGM 设置特性时或监视器设置资源组特性 Status 和 Status_msg 时），才调用 Validate。
- Update
-
调用此可选方法将特性已更改的消息通知正在运行的资源。在管理操作成功地设置了资源及其资源组后，将调用 Update。对资源处于联机状态的节点调用此方法。该方法将通过 API 存取函数来读取可能会影响活动资源的特性值并相应地调整正在运行的资源。
Update 方法的失败将导致 syslog() 函数生成错误消息，但是不会影响该资源的 RGM 管理。
与网络相关的回调方法
使用网络地址资源的服务可能要求按某种顺序（相对于网络地址配置）执行启动或停止步骤。以下可选回调方法 Prenet_start 和 Postnet_stop 使资源类型实现在配置/取消配置相关网络地址之前/之后执行特殊的启动和关闭操作。
- Prenet_start
-
在配置同一资源组中的网络地址之前，将调用此可选方法执行特殊的启动操作。
- Postnet_stop
-
在向下配置同一资源组中的网络地址之后，将调用此可选方法，执行特殊的关闭操作。
监视器控制回调方法
资源类型实现中可包含一个用来监视资源性能、报告其状态或针对资源失败情况进行操作的程序（可选）。在资源类型实现中，Monitor_start、Monitor_stop 和 Monitor_check 方法支持资源监视器的实现。
- © 2010, Oracle Corporation and/or its affiliates