Release Notes

Administrative API Reference

5.1 db2ConvMonStream

In the Usage Notes, the structure for the snapshot variable datastream type SQLM_ELM_SUBSECTION should be sqlm_subsection.

5.2 db2XaGetInfo (new API)

db2XaGetInfo - Get Information for Resource Manager

Extracts information for a particular resource manager once an xa_open call has been made.

Authorization

None

Required Connection

Database

Version

sqlxa.h

C API Syntax 



   /* File: sqlxa.h */
   /* API: Get Information for Resource Manager */
   /* ... */
   SQL_API_RC SQL_API_FN
   db2XaGetInfo (
      db2Uint32 versionNumber,
      void * pParmStruct,
      struct sqlca * pSqlca);
 
   typedef SQL_STRUCTURE db2XaGetInfoStruct
   {
     db2int32 iRmid;
     struct sqlca oLastSqlca;
   } db2XaGetInfoStruct;

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 db2XaGetInfoStruct structure.

pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see the Administrative API Reference.

iRmid
Input. Specifies the resource manager for which information is required.

oLastSqlca
Output. Contains the sqlca for the last XA API call.
Note:Only the sqlca that resulted from the last failing XA API can be retrieved.

5.3 db2XaListIndTrans (new API that supercedes sqlxphqr)

db2XaListIndTrans - List Indoubt Transactions

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

Scope

This API affects only the node on which it is issued.

Authorization

One of the following:

Required Connection

Database

Version

db2ApiDf.h

C API Syntax 



   /* 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 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. For more information about this structure, see the Administrative API Reference.

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.

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 resynchronisation, 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 resynchronisation, or as a result of other transactions entering the indoubt state. The application may allocate a larger buffer to account for this.

timestamp
Output. Specifies the time when the transaction entered the indoubt state. This is the number of seconds the local time zone is displaced from Coordinated Universal Time.

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
Output. Indicates whether or not the application is connected. Valid values are:

SQLXA_TRUE
The transaction is undergoing normal syncpoint processing, and is waiting for the second phase of the two-phase commit.

SQLXA_FALSE
The transaction was left indoubt by an earlier failure, and is now waiting for resynchronisation from the 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 resynchronisation 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.

Usage Notes

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

  1. Call db2XaListIndTrans 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 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 oNumIndoubtTotal. If oNumIndoubtsTotal is greater than oNumIndoubtsReturned, the application can repeat the above steps.

See Also

"sqlxhfrg - Forget Transaction Status", "sqlxphcm - Commit an Indoubt Transaction", and "sqlxphrl - Roll Back an Indoubt Transaction" in the Administrative API Reference.

5.4 sqlaintp - Get Error Message

The following usage note is to be added to the description of this API: 

   In a multi-threaded application, sqlaintp must be attached to a valid context;
   otherwise, the message text for SQLCODE -1445 cannot be obtained.

[ Top of Page | Previous Page | Next Page | Table of Contents ]