db2SpmListIndTrans API - List SPM indoubt transactions

Provides a list of transactions that are indoubt at the Syncpoint Manager.

Scope

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

Authorization

None

Required connection

Connection to the Syncpoint Manager

API include file

sqlxa.h

API and data structure syntax

SQL_API_RC SQL_API_FN
db2SpmListIndTrans (
  db2Uint32 versionNumber,
  void * pParmStruct,
  struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2SpmListIndTransStruct
{
db2SpmRecoverStruct * piIndoubtData;
db2Uint32            iIndoubtDataLen;
db2Uint32            oNumIndoubtsReturned;
db2Uint32            oNumIndoubtsTotal;
db2Uint32            oReqBufferLen;
} db2XaListIndTransStruct;

typedef SQL_STRUCTURE db2SpmRecoverStruct
{
   SQLXA_XID    xid;
   char         luwid[SQLCSPQY_LUWID_SZ+1];
   char         corrtok[SQLCSPQY_APPLID_SZ+1];
   char         partner[SQLCSPQY_LUNAME_SZ+1];
   char         dbname[SQLCSPQY_DBNAME_SZ+1];
   char         dbalias[SQLCSPQY_DBNAME_SZ+1];
   char         role;
   char         uow_status;
   char         partner_status;
} db2SpmRecoverStruct;

db2SpmListIndTrans API parameters

versionNumber
Input. Specifies the version and release level.
pParmStruct
Input. A pointer to the db2SpmListIndTransStruct structure.
pSqlca
Output. A pointer to the sqlca structure.

db2SpmListIndTransStruct data structure parameters

piIndoubtData
Input. A pointer to the application supplied buffer where indoubt data will be returned. The indoubt data is in db2SpmRecoverStruct format. The application can traverse the list of indoubt transactions by using the size of the db2SpmRecoverStruct structure, starting at the address provided by this parameter. If the value is NULL, size of the required buffer is calculated and returned in oReqBufferLen. oNumIndoubtsTotal will contain the total number of indoubt transactions. The application may allocate the required buffer size and issue the API again.
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.

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.

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.

db2SpmRecoverStruct data structure parameters

xid
Output. Specifies the XA identifier assigned by the transaction manager to uniquely identify a global transaction.
luwid
Output. Specifies the Logical Unit of Work ID (LUWID) assigned by the Syncpoint Manager to identify the XA Identifier (XID) at the partner system.
corrtok
Output. Specifies the application identifier assigned by the Syncpoint manager for this transaction.
partner
Output. Specifies the name of the Partner system.
dbname
Output. Database of the partner system
dbalias
Output. Specifies the alias of the database where the indoubt transaction is found.
role
Output. Role of the Syncpoint manager.
SQLCSPQY_AR
Syncpoint Manager is an Application Requestor
SQLCSPQY_AS
Syncpoint manager is an Application Server
uow_status
Output. Indicates the status of this indoubt transaction at the Syncpoint Manager. Valid values are:
SQLCSPQY_STATUS_COM
The transaction is in commit status at the Syncpoint Manager. The transaction is waiting to be resynchronized with the partner system during the next resynchronization interval.
SQLCSPQY_STATUS_RBK
The transaction is in rollback status at the Syncpoint Manager. Waiting for the partner system to initiate resynchronization and resolve indoubt.
SQLCSPQY_STATUS_IDB
The transaction is in prepared state at the Syncpoint manager. 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.
SQLCSPQY_STATUS_HCM
The transaction has been heuristically committed.
SQLCSPQY_STATUS_HRB
The transaction has been heuristically rolled back.

Usage notes

A typical application will perform the following steps after setting the current connection to the Syncpoint Manager*:

  1. Call db2SpmListIndTrans API with piIndoubtData set to NULL. This will return values in oReqBufferLen and oNumIndoubtsTotal.
  2. Use the returned value in oReqBufferLen to allocate a buffer. This buffer may not be large enough if there are additional indoubt transactions because of the initial invocation of this API to obtain oReqBufferLen. The application may provide a buffer larger than oReqBufferLen.
  3. 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 the preceding steps.

* To connect to the Syncpoint Manager, determine the name of the Syncpoint Manager being used at the Db2 Connect server. This can be determined by querying the database configuration parameter, spm_name, at the Db2 Connect server. Issue a connect by specifying the spm_name as the database alias on the connect API.