本章介绍如何使用 DM XA 接口。通常，用户在使用事务处理监视器的应用程序中使用此接口。XA 功能在事务与多个数据库交互的应用程序中最有用。
12.1 X/Open 分布式事务处理
X/Open 分布式事务处理英文全称为 X/Open Distributed Transaction Processing，简称 X/Open DTP。
X/Open DTP 体系结构定义了一个标准体系结构或者接口，该体系结构允许多个应用程序（AP）共享由多个相同或不同的资源管理器（RM）提供的资源。它将 AP 和 RM 之间的工作协调到 XA 事务（又称全局事务）中。
DM XA 接口符合 X/Open 的 XA 接口规范。DM XA 接口是一个外部接口，它使非 DM 客户端事务管理器的客户端管理器（TM）能够协调全局事务，因此，DM XA 允许在全局事务中包含非 DM 数据库的其他资源管理器。
12.1.1 DTP 术语
12.1.1.1 资源管理器 RM
资源管理器英文全称为 Resource Manager，简称为 RM。
资源管理器控制一个共享的、可恢复的资源，该资源在发生故障后可以返回到一致状态。DM 数据库是一个 RM，在发生故障后可以使用联机日志和回滚段返回到一个一致状态。
12.1.1.2 XA 事务
XA 事务又称全局事务，是一个客户端事务，涉及多个分布式资源的更新，并且需要分布式的 RM 全部成功或者全部失败。
12.1.1.3 分支
分支是一个 RM 中包含的工作单元。多个分支构成一个全局事务。对于 DM 数据库，每个分支映射到数据库服务器内的本地事务。
12.1.1.4 事务管理器 TM
事务管理器英文全称为 Transaction Manager，简称为 TM。
事务管理器提供了一个 API 来指定事务的边界，并管理提交和恢复。事务管理器在分布式的 RM 间实现了一个两阶段提交引擎，以实现分布式 RM 间事务的全部成功或者全部失败。
外部 TM 是驻留在 DM 数据库外部的中间层组件。通常，数据库是它自己的内部 TM，使用基于标准的 TM 使 DM 数据库能够在单个事务中与其他异构 RM 协作。
12.1.1.5 事务处理监视器 TPM
事务处理监视器英文全称为 Transaction Processing Monitor，简称为 TPM。
TM 通常由事务处理监视器（TPM）提供，例如：Oracle Tuxedo。TPM 协调发出请求的客户端进程和处理请求的后端服务器之间的事务请求流。基本上，TPM 协调需要几种不同类型后台进程服务的事务，例如分布在网络上的应用程序服务器和 RM。
TPM 同步完成分布式事务所需的任何提交或回滚。TPM 的 TM 部分负责控制何时发生分布式提交和回滚。因此，如果分布式应用程序利用 TPM，然后 TPM 的 TM 部分负责控制两阶段提交协议，RM 使 TM 能够执行此任务。
由于 TM 控制分布式提交或回滚，因此必须通过 XA 接口直接与 DM 数据库（或其他 RM）通信。基于它对事务中所有 RM 的了解，它使用“DM XA 库子程序”中描述的 DM XA 库子程序来告诉 DM 数据库如何处理事务。
12.1.1.6 两阶段提交协议
DM XA 接口遵循两阶段提交协议，各阶段内容如下：
- 在准备阶段，TM 要求每个 RM 保证它可以提交事务的任何一部分。如果这是可以的，则 RM 记录其准备状态并肯定的答复 TM。否则，RM 可能回滚任务工作，对 TM 作出否定答复，然后忘记事务。协议允许应用程序或任何 RM 单方面回滚事务，直到准备阶段完成。
- 在第二阶段，TM 记录提交决策，并向参与事务的所有 RM 发出提交或回滚。只有当所有 RM 都回复确定已进入第一阶段时，TM 才能为 RM 发出提交。
12.1.1.7 应用程序 AP
应用程序英文全称为 Application Program，简称为 AP。
应用程序定义事务边界并指定构成事务的操作。例如，AP 可以是预编译程序。AP 通过其本机接口对 RM 资源进行操作。
12.1.1.8 TX 接口
应用程序通过一个名为 TX 的接口通过 TM 启动并完成所有事务控制操作，AP 不直接使用 XA 接口。AP 不知道在中间层分叉的分支：应用程序线程不显式地加入、离开、挂起和恢复分支工作，而是 TPM 的 TM 部分为 AP 管理全局事务的分支。最终，AP 会调用 TM 来提交全部或不提交。
12.1.1.9 本地接口
本地接口为应用程序调用资源管理器程序的接口，由各 RM 厂商提供。比如达梦提供的 ODBC、JDBC 等多种数据库访问接口。
12.1.1.10 静态登记
DM 数据库支持静态登记。RM 可在开始任何工作之前通过调用 xa_start 来进行静态登记，当前事务不涉及的 RM 也可进行静态登记。
12.1.2 所需公共信息
作为资源管理器，DM 数据库提供的相关信息如表 12.1 所示。
| XA 特性 | DM 数据库相关信息 |
|---|---|
| xa_switch_t 结构 | DM 数据库中 xa_switch_t 结构的名称为 xadmsw，用于静态登记。该结构包含资源管理器的入口点和其他信息 |
| xa_switch_t 资源管理器 | DM 数据库中 xa_switch_t 资源管理器的名称为 DM_XA |
| 打开字符串 | DM 数据库中打开字符串的名称为 xa_open，关于该字符串的详细介绍请参考 12.3.3 打开字符串 xa_open |
| 关闭字符串 | DM 数据库中关闭字符串的名称为 xa_close，该字符串会被忽略，且可以为空串 |
| 库 | 使用 DM XA 链接应用程序所需的库，首先需要 dmxai 库（windows 下为 dmxai.dll，linux 下为 libdmxai.so），如果使用 PRO*C 编程则还需要 dmdpc 库，如果使用 DPI 编程则还需要 dmdpi 库。这几个动态库在安装 DM 时，已经被放到安装目录下 |
| 要求 | 无 |
12.2 DM XA 接口
DM XA 接口使得 TM 能够控制 DM 数据库的事务处理过程。通常由 AP 调用 tx_open 来打开资源，但一些 TM 可能在 AP 开始时隐式调用 xa_open 来打开资源。
类似地，当应用程序使用完资源时会发生关闭（使用 xa_close），关闭可能发生在 AP 调用 tx_close 或应用程序终止时。
TM 指示 RM 执行其他几个任务，包括：
- 启动事务并将其与事务 ID 关联
- 回滚事务
- 准备和提交事务
12.2.1 DM XA 接口常规功能
DM XA 接口如表 12.2 所示。
| XA 接口 | 描述 |
|---|---|
| xa_open | 连接到 RM |
| xa_close | 断开与 RM 的连接 |
| xa_start | 启动一个事务并将其与给定的事务 ID（XID）关联，或者将该进程与现有事务关联 |
| xa_end | 从给定的过程中分离 |
| xa_rollback | 回滚给定 XID 的事务 |
| xa_prepare | 准备给定 XID 的事务。这是两阶段提交协议的第一阶段 |
| xa_commit | 提交给定 XID 的事务。这是两阶段提交协议的第二阶段 |
| xa_recover | 检索已完成第一阶段预提交、第二阶段提交或已经回滚的事务。且内存中该事务信息尚未被清除的事务，已经被清除的检索不到 |
| xa_forget | 忽略给定 XID 的启发式完成事务 |
一般来说，AP 只需理解 xa_open 字符串的格式与功能。
12.2.2 DM XA 接口附加功能
DM 数据库的 XA 接口包括一些附加功能。
| 功能 | 说明 |
|---|---|
| int dxa_get_con(void** con) | 获取当前线程上的 DPI 连接句柄 |
12.2.3 DM XA 事务相关功能
XA 事务处理兼容策略可通过 INI 参数 XA_COMPATIBLE_MODE 控制，当其取值为 0 时，不兼容任何数据库，返回达梦错误码；当其取值为 1 时，兼容 ORACLE 的处理方式，返回和 ORACLE 一样的报错码；当其取值为 2 时，兼容 mysql 的 XA 事务处理策略，此时不支持使用 dbms_xa 系统包；默认情况下为不兼容。其中有关 dbms_xa 系统包的介绍参见《DM8 系统包使用手册》。
12.3 开发和安装 XA 应用程序
12.3.1 DBA 或者系统管理员的职责
DBA 或者系统管理员的职责如下：
- 在应用程序开发人员的帮助下，定义打开字符串。有关详细信息，参见“定义 XA_OPEN 打开字符串”。
- 使用打开字符串，将 RM 安装到 TPM 配置中。按照 TPM 供应商说明进行操作。
- 向系统写入 XA 跟踪文件和日志文件的目录授予用户 ID 的写入权限。
- 启动相关数据库实例以使 DM XA 应用程序处于联机状态。在启动 TPM 服务器之前执行此任务。
12.3.2 应用程序开发人员的职责
应用程序开发人员的职责如下：
- 在 DBA 或者系统管理员的帮助下定义打开字符串，如“定义 XA_OPEN 打开字符串”中描述。
- 开发应用程序。
- 根据 TPM 供应商的说明链接应用程序。
12.3.3 定义 XA_Open 打开字符串
事务监视器使用打开字符串打开数据库。
12.3.3.1 XA_Open 字符串的语法
语法：
{required_field}{+required_field...}
示例：
HOST=127.0.0.1+USER=test+PWD=Test_12345
12.3.3.2 XA_OPEN 字符串的必须字段
| 语法成分 | 说明 |
|---|---|
| HOST | 指定所要连接的 DM 数据库地址 |
| USER | 指定所要创建连接的登录用户名 |
| PWD | 指定所要创建连接的登录密码 |
12.4 XA 应用程序故障排除
12.4.1 访问 DM XA 的日志文件
DM XA 接口将所有错误信息记录到日志文件中，该错误信息有助于分析 XA 的出错原因。例如，通过错误信息可以得知 XA 打开失败的原因是打开字符串错误还是登录授权失败。
DM XA 接口的日志文件名称为 dm_dmxa_date.log，其中 date 表示生成该日志文件的日期。例如，dm_dmxa_202010.log 表示 2020 年 10 月的日志文件。DM XA 接口的日志文件默认存储于应用程序所在目录上层的 log 目录下。
12.4.2 访问 DM XA 的跟踪文件
DM XA 接口将 XA 接口的调用关系记录到跟踪文件中。通过分析该调用关系可以得知 XA 接口被调用的时间、调用进程名、调用线程名以及返回的结果等信息。
DM XA 接口的跟踪文件名称为 dm_dmxa_date.trc，其中，date 表示生成该跟踪文件的日期。例如，dm_dmxa_202010.trc 表示 2020 年 10 月的跟踪文件。DM XA 接口的跟踪文件默认存储于应用程序所在目录上层的 log 目录下。需要指出的是生成跟踪文件需要在 dm_svc.conf 文件中增加全局配置项 XA_TRACE=(1)。
