DB2 10.5 for Linux, UNIX, and Windows

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*:

Call db2SpmListIndTrans API 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 of 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 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.