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.
Required connection
Database
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[SQLXA_USERID_SZ];
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 re-activated, 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 rollback 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.
- xid
- 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 rollback
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 the above steps.