db2XaListIndTrans API - List indoubt transactions

Provides a list of all indoubt transactions for the currently connected database.

Scope

This API only affects the database partition on which it is issued.

Authorization

None

Required connection

Database

API include file

sqlxa.h

API and data structure syntax

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[30];
   char log_full;
   char connected;
   char indoubt_status;
   char originator;
   char reserved[8];
   sqluint32 rmn;
   rm_entry rm_list[SQLXA_MAX_FedRM];
   } db2XaRecoverStruct;

typedef SQL_STRUCTURE rm_entry
{
  char name[SQLQG_MAX_SERVER_NAME_LEN];
  SQLXA_XID xid;
} rm_entry;

db2XaListIndTrans API parameters

versionNumber: Input. Specifies the version and release level of the structure passed in as the second parameter, pParmStruct.
pParmStruct: Input. A pointer to the db2XaListIndTransStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2XaListIndTransStruct data structure parameters

piIndoubtData: Input. A pointer to the application supplied buffer where indoubt data will be returned. The indoubt data is in db2XaRecoverStruct format. The application can traverse the list of indoubt transactions by using the size of the db2XaRecoverStruct structure, starting at the address provided by this parameter.
If the value is NULL, Db2® will calculate the size of the buffer required and return this value in oReqBufferLen. oNumIndoubtsTotal will contain the total number of indoubt transactions. The application may allocate the required buffer size and issue the API again.
iIndoubtDataLen: Input. Size of the buffer pointed to by piIndoubtData parameter in bytes.
oNumIndoubtsReturned: Output. The number of indoubt transaction records returned in the buffer specified by pIndoubtData.
oNumIndoubtsTotal: Output. The Total number of indoubt transaction records available at the time of API invocation. If the piIndoubtData buffer is too small to contain all the records, oNumIndoubtsTotal will be greater than the total for oNumIndoubtsReturned. The application may reissue the API in order to obtain all records.
Note: This number may change between API invocations as a result of automatic or heuristic indoubt transaction resynchronization, or as a result of other transactions entering the indoubt state.
oReqBufferLen: Output. Required buffer length to hold all indoubt transaction records at the time of API invocation. The application can use this value to determine the required buffer size by calling the API with pIndoubtData set to NULL. This value can then be used to allocate the required buffer, and the API can be issued with pIndoubtData set to the address of the allocated buffer.
Note: The required buffer size may change between API invocations as a result of automatic or heuristic indoubt transaction resynchronization, or as a result of other transactions entering the indoubt state. The application may allocate a larger buffer to account for this.

db2XaRecoverStruct data structure parameters

timestamp

Output. Specifies the time when the transaction entered the indoubt state.

xid

Output. Specifies the XA identifier assigned by the transaction manager to uniquely identify a global transaction.

dbalias

Output. Specifies the alias of the database where the indoubt transaction is found.

applid

Output. Specifies the application identifier assigned by the database manager for this transaction.

sequence_no

Output. Specifies the sequence number assigned by the database manager as an extension to the applid.

auth_id

Output. Specifies the authorization ID of the user who ran the transaction.

log_full

Output. Indicates whether or not this transaction caused a log full condition. Valid values are:

SQLXA_TRUE: This indoubt transaction caused a log full condition.
SQLXA_FALSE: This indoubt transaction did not cause a log full condition.

connected

Indicates whether an application is connected.

Possible values for CONNECTED (defined in sqlxa) are:

SQLXA_TRUE: True. The transaction is undergoing normal syncpoint processing, and is waiting for the second phase of the two-phase commit.
SQLXA_FALSE: False. The transaction was left indoubt by an earlier failure, and is now waiting for re-sync from a transaction manager.

indoubt_status

Output. Indicates the status of this indoubt transaction. Valid values are:

- SQLXA_TS_PREP: The transaction is prepared. The connected parameter can be used to determine whether the transaction is waiting for the second phase of normal commit processing or whether an error occurred and resynchronization with the transaction manager is required.
- SQLXA_TS_HCOM: The transaction has been heuristically committed.
- SQLXA_TS_HROL: The transaction has been heuristically rolled back.
- SQLXA_TS_MACK: The transaction is missing commit acknowledgement from a node in a partitioned database.
- SQLXA_TS_END: The transaction has ended at this database. This transaction may be reactivated, committed, or rolled back at a later time. It is also possible that the transaction manager encountered an error and the transaction will not be completed. If this is the case, this transaction requires heuristic actions, because it may be holding locks and preventing other applications from accessing data.

When the originator parameter is set to the value SQLXA_ORIG_FXA, valid values for the indoubt_status parameter (defined in sqlxa.h located in the include directory) are:

SQLXA_TS_MFCACK: Indicates that the transaction is missing commit acknowledgement from one or more federated data sources.
SQLXA_TS_MFRACK: Indicates that the transaction is missing rollback acknowledgement from one or more federated data sources.

originator

Identifies the origin of an indoubt transaction.

Possible values for ORIGINATOR (defined in sqlxa.h located in the include directory) are:

SQLXA_ORIG_PE: Transaction originated by Db2 in MPP environment.
SQLXA_ORIG_XA: Transaction originated by XA.
SQLXA_ORIG_FXA: Transaction originated in the second phase of the federated two-phase commit process. It indicates that this transaction has entered the second phase of the two-phase commit protocol, however one or more federated data sources cannot complete the second phase or cannot communicate with the federated server.

reserved

The first byte is used to indicate the type of indoubt transaction: 0 indicates RM, and 1 indicates TM.

rmn

Output. Number of federated data sources that failed to commit or roll back a transaction.

rm_list

Output. List of failed federated data source entries, each of which contains a server name and a xid.

rm_entry data structure parameters

name: Output. Name of a federated data source.
pxid: Output. Specifies the XA identifier assigned by the federated database to a federated data source to uniquely identify a federated transaction.

Usage notes

SQLXA_MAX_FEDRM is defined to be 16. Most federated transactions involve less than 10 data sources. If more than 16 federated data sources fail to commit or roll back in a transaction, only 16 of them will be returned by the db2XaListIndTrans API for this indoubt transaction. For a non-federated indoubt transaction, rmn parameter will be set to 0, indicating that the indoubt transaction involves no federated data sources.

If a federated indoubt transaction involves more than 16 failed federated data sources, when the heuristic processing is invoked, all the data sources (regardless of whether they are returned by the db2XaListIndTrans API) will commit or roll back the indoubt transaction. Any federated data source that successfully committed or rolled back the indoubt transaction will be removed from the list of failed federated data sources for the federated indoubt transaction. On the next call to the db2XaListIndTrans API, only federated data sources that still failed to commit or roll back the indoubt transaction will remain in the list for the federated indoubt transaction.

To obtain the list of data sources in a federated indoubt transaction, you must compile applications using Db2 Version 9.1 header files and pass in a version number db2Version900 or higher (for later releases) to the db2XaListIndTrans API. If you pass in a lower version number, the API will still return a list of indoubt transactions, but federated data source information will be excluded. Regardless, the version of the header file used by the application must be in sync with the version number passed to the API. Otherwise, the results will be unpredictable.

A typical application will perform the following steps after setting the current connection to the database or to the partitioned database coordinator node:

Call db2XaListIndTrans with piIndoubtData set to NULL. This will return values in oReqBufferLen and oNumIndoubtsTotal.
Use the returned value in oReqBufferLen to allocate a buffer. This buffer may not be large enough if there are additional indoubt transactions because the initial invocation of this API to obtain oReqBufferLen. The application may provide a buffer larger than oReqBufferLen.
Determine if all indoubt transaction records have been obtained. This can be done by comparing oNumIndoubtsReturned to oNumIndoubtsTotal. If oNumIndoubtsTotal is greater than oNumIndoubtsReturned, the application can repeat these steps.