发行说明

38.7 db2XaListIndTrans（取代 sqlxphqr 的新 API）

db2XaListIndTrans — 列示不确定事务

为当前连接的数据库提供了所有不确定事务的列表。

作用域

此 API 仅影响在其上发出该 API 的节点。

权限

下列其中一项：

• sysadm
• dbadm

必需的连接

数据库

API 包含文件

db2ApiDf.h

C API 语法

   /* File: db2ApiDf.h */
   /* API: List Indoubt Transactions */
   /* ... */
   SQL_API_RC SQL_API_FN
   db2XaListIndTrans (
      db2Uint32 versionNumber,
      void * pParmStruct,
      struct sqlca * pSqlca);
 
   typedef SQL_STRUCTURE db2XaListIndTransStruct
   {
     db2XaRecoverStruct * piIndoubtData;
     db2Uint32            iIndoubtDataLen;
     db2Uint32            oNumIndoubtsReturned;
     db2Uint32            oNumIndoubtsTotal;
     db2Uint32            oReqBufferLen;
   } db2XaListIndTransStruct;
 
   typedef SQL_STRUCTURE db2XaRecoverStruct
   {
     sqluint32      timestamp;
     SQLXA_XID      xid;
     char           dbalias[SQLXA_DBNAME_SZ];
     char           applid[SQLXA_APPLID_SZ];
     char           sequence_no[SQLXA_SEQ_SZ];
     char           auth_id[SQL_USERID_SZ];
     char           log_full;
     char           connected;
     char           indoubt_status;
     char           originator;
     char           reserved[8];
   } db2XaRecoverStruct;

API 参数

versionNumber

输入。指定作为第二个参数 pParmStruct 传送的结构的版本和发行版级别。

pParmStruct

输入。指向 db2XaListIndTransStruct 结构的指针。

pSqlca

输出。指向 sqlca 结构的指针。有关此结构的更多信息，参见 Administrative API Reference。

piIndoubtData

输入。指向将在其中返回不确定数据的应用程序提供的缓冲区的指针。不确定数据为 db2XaRecoverStruct 格式。应用程序可通过使用 db2XaRecoverStruct 结构的大小，并从此参数提供的地址开始，遍历不确定事务的列表。

如果值为 NULL，DB2 将计算所需缓冲区的大小，并以 oReqBufferLen 的形式返回此值。oNumIndoubtsTotal 将包含不确定事务的总数。该应用程序可分配所需的缓冲区大小并再次发出该 API。

oNumIndoubtsReturned

输出。在由 pIndoubtData 指定的缓冲区中返回的不确定事务记录数。

oNumIndoubtsTotal

输出。调用 AIP 时可用的不确定事务记录总数。如果 piIndoubtData 缓冲区太小，难以容纳所有记录，则 oNumIndoubtsTotal 将大于 oNumIndoubtsReturned 的总数。应用程序可重新发出 API，以获取所有记录。

注意:

此数目可能会视不同的 API 调用而有所不同，这是由于自动的或试探性的不确定事务再同步，或是其它事务的状态变成不确定状态而造成的。

oReqBufferLen

输出。在 API 调用时保存所有不确定事务记录所需的缓冲区长度。应用程序可通过调用 API 并将 pIndoubtData 设置为 NULL 来用此值确定所需的缓冲区大小。然后，可用此值来分配所需缓冲区，并且将 pIndoubtData 设置为所分配缓冲区的地址来发出 API。

注意:

所需缓冲区大小可能会视各 API 调用的不同而有所不同，这是由于自动的或试探性的不确定事务再同步，或是由于其它事务的状态变成不确定状态而造成的。应用程序可分配更大的缓冲区来达到此目的。

timestamp

输出。指定事务变成不确定状态的时间。

xid

输出。指定由事务管理器分配的用以唯一地标识全局事务的 XA 标识符。

dbalias

输出。指定不确定事务所在的数据库的别名。

applid

输出。指定数据库管理器对此事务分配的应用程序标识符。

sequence_no

输出。指定由数据库管理器分配的作为 applid 的扩展的序列号。

auth_id

输出。指定运行事务的用户的授权标识。

log_full

输出。指示此事务是否导致了日志已满状态。有效值为：

SQLXA_TRUE

此不确定事务导致了日志已满状态。

SQLXA_FALSE

此不确定事务未导致日志已满状态。

connected

输出。指示是否连接了应用程序。有效值为：

SQLXA_TRUE

事务正在进行正常的同步点处理，且正在等待两阶段落实的第二阶段。

SQLXA_FALSE

由于较早前发生的故障，事务处于不确定状态，现在正等待与事务管理器的再同步。

indoubt_status

输出。指示此不确定事务的状态。有效值为：

SQLXA_TS_PREP

事务已准备就绪。连接的参数可用来确定事务是否正等待正常落实处理的第二阶段，或是否发生了错误，需要与事务管理器的再同步。

SQLXA_TS_HCOM

已试探性落实事务。

SQLXA_TS_HROL

已试探性回滚事务。

SQLXA_TS_MACK

未从分区数据库中的节点进行事务落实确认。

SQLXA_TS_END

事务在此数据库中结束。稍后此事务可能被重新激活、落实或回滚。还可能是事务管理器遇到了错误，事务将不能完成。如果出现这种情况，则此事务需要试探性操作，原因是它可能会挂起锁定并阻止其它应用程序存取数据。

使用说明

在设置了与数据库或分区数据库协调节点的当前连接之后，典型的应用程序将执行下列步骤：

1. 调用 db2XaListIndTrans，而 piIndoubtData 被设置为 NULL。这将在 oReqBufferLen 和 oNumIndoubtsTotal 中返回值。
2. 使用 oReqBufferLen 中的返回值来分配缓冲区。此缓冲区可能不够大（如果有其它不确定事务存在的话），原因是为获取 oReqBufferLen 而对此 API 进行了初始调用。该应用程序可提供大于 oReqBufferLen 的缓冲区。
3. 确定是否获得了所有的不确定事务记录。可通过将 oNumIndoubtsReturned 与 oNumIndoubtTotal 进行比较来完成此任务。如果 oNumIndoubtsTotal 大于 oNumIndoubtsReturned，应用程序可以重复上述步骤。

另见

Administrative API Reference 中的“sqlxhfrg - Forget Transaction Status”、“sqlxphcm - Commit an Indoubt Transaction”和“sqlxphrl - Roll Back an Indoubt Transaction”。