db2ReadLog API - Read log records
Authorization
- SYSADM
- DBADM
Required connection
Database
API include file
db2ApiDf.h
API and data structure syntax
SQL_API_RC SQL_API_FN
db2ReadLog (
db2Uint32 versionNumber,
void * pDB2ReadLogStruct,
struct sqlca * pSqlca);
typedef SQL_STRUCTURE db2ReadLogStruct
{
db2Uint32 iCallerAction;
db2LRI *piStartLRI;
db2LRI *piEndLRI;
char *poLogBuffer;
db2Uint32 iLogBufferSize;
db2Uint32 iFilterOption;
db2ReadLogInfoStruct *poReadLogInfo;
db2LRI *piMinRequiredLRI;
} db2ReadLogStruct;
typedef SQL_STRUCTURE db2ReadLogInfoStruct
{
db2LRI initialLRI;
db2LRI firstReadLRI;
db2LRI nextStartLRI;
db2LRI firstReusedLRI;
db2Uint32 logRecsWritten;
db2Uint32 logBytesWritten;
db2Uint32 timeOfLRIReuse;
db2TimeOfLog currentTimeValue;
db2Uint32 futureUse1;
db2LSN oldestInFlightLSN;
} db2ReadLogInfoStruct;
typedef SQL_STRUCTURE db2TimeOfLog
{
db2Uint32 seconds;
db2Uint32 accuracy;
} db2TimeOfLog;
typedef SQL_STRUCTURE db2ReadLogFilterData
{
db2LRI recordLRIType1;
db2LRI recordLRIType2;
db2Uint32 realLogRecLen;
db2int32 sqlcode;
} db2ReadLogFilterData;
typedef SQL_STRUCTURE db2LRI
{
db2Uint64 lriType;
db2Uint64 part1;
db2Uint64 part2;
} db2LRI;
#define DB2READLOG_LRI_1 1
#define DB2READLOG_LRI_2 2
db2ReadLog API parameters
- versionNumber
- Input. Specifies the version and release level of the structure passed as the second parameter, pDB2ReadLogStruct.
- pDB2ReadLogStruct
- Input. A pointer to the db2ReadLogStruct structure.
- pSqlca
- Output. A pointer to the sqlca structure.
db2ReadLogStruct data structure parameters
- iCallerAction
- Input. Specifies the action to be performed.
- DB2READLOG_READ
- Read the database log from the starting log sequence to the ending log sequence number and return log records within this range.
- DB2READLOG_READ_SINGLE
- Read a single log record (propagatable or not) identified by the starting log sequence number.
- DB2READLOG_QUERY
- Query the database log. Results of the query will be sent back via the db2ReadLogInfoStruct structure.
- piStartLRI
- Input. The starting LRI specifies the starting point for reading the log. This value does not need to be the start of an actual log record.
- piEndLRI
- Input. The ending LRI specifies the end point for reading the log. This value must be greater than the piStartLRI parameter, and does not need to be the start or end of an actual log record.
- poLogBuffer
- Output. The buffer holds log records returned by the db2ReadLog API. The size
of the buffer is specified by the iLogBufferSize parameter. The log records
returned are stored sequentially in this buffer, each with a prefix that is based on
iFilterOption:
- If the iFilterOption is ON, the db2ReadLogFilterData structure will be prefixed to each log record.
- If the iFilterOption is OFF, each log record in the buffer is prefixed by two 24-byte db2LRI structures.
- iLogBufferSize
- Input. Specifies the size, in bytes, of the poLogBuffer buffer. This buffer must be large enough to hold a single log record.
- iFilterOption
- Input. Specifies the level of log record filtering to be used
when reading the log records. Valid values are:
- DB2READLOG_FILTER_OFF
- Read all log records in the given LRI range.
- DB2READLOG_FILTER_ON
- Reads only log records in the given LRI range marked as propagatable. This is the traditional behavior of the asynchronous log read API. The log records that are returned when this value is used are documented in the "Db2 log records" topic. All other log records are for IBM internal use only and are therefore not documented.
- poReadLogInfo
- Output. A structure detailing information regarding the call and the database log.
- piMinRequiredLRI
- Input. This field is for future functionality. The application should set this field to 0.
db2ReadLogInfoStruct data structure parameters
- initialLRI
- The first LRI used, or that will be used, by the database since it was activated.
- firstReadLRI
- The first LRI present in poLogBuffer parameter.
- nextStartLRI
- The start of the next log record the caller should read. Because some log records can be filtered and not returned in poLogBuffer parameter, using this LRI as the start of the next read instead of the end of the last log record in poLogBuffer parameter will prevent rescanning log records which have already been filtered.
- firstReusedLRI
- The first LRI to be reused due to a database restore or rollforward operation.
- logRecsWritten
- The number of log records written to poLogBuffer parameter.
- logBytesWritten
- The total number of bytes of data written to poLogBuffer parameter.
- timeOfLRIReuse
- The time at which the LRI represented by firstReusedLRI was reused. The time is the number of seconds since January 1, 1970.
- currentTimeValue
- The current time according to the database.
- futureUse1
- This field is for future functionality. The current version of Db2 always returns a value of 0.
- oldestInFlightLSN
- The LSN of the oldest inflight transaction.
db2TimeOfLog data structure parameters
- seconds
- The number of seconds since January 1, 1970.
- accuracy
- A high accuracy counter which allows callers to distinguish the order of events when comparing timestamps that occurred within the same second.
db2ReadLogFilterData data structure parameters
- recordLRI
- LRI of the following log record. There are two LRIs in the db2ReadLogFilterData structure:
- recordLRIType1 LRI of the log record. This is a type 1 LRI.
- recordLRIType2 LRI of the log record. This is a type 2 LRI.
- realLogRecLen
- The physical log record length in the Db2 logs.
- sqlcode
- This field will be non-zero if an error occurred while trying to decompress the compressed row image in the log record. If an error occurred, it will contain an integer representing the SQL code associated with the error. For permanent errors, SQL0204N will most likely be returned. Resubmitting the API request may return with the same error. For transient errors, the SQL code returned will correspond to the cause of the error, which may or may not require a user action to rectify.
db2LRI data structure parameters
- lriType
- There are two LRI types in the db2LRI structure
that the lriType can be set to:
- DB2READLOG_LRI_1 is used when reading sequentially
through the logs. This type uses an LFS as
part1
and an LSN aspart2
in the db2LRI structure. You use the DB2READLOG_LRI_1 lriType in db2LRI structures to read forward through a log file. - DB2READLOG_LRI_2 is used to uniquely identify
the log record within the log stream to which it belongs to. This
type uses the logStreamID as
part1
and an LSO aspart2
in the db2LRI structure. You use the DB2READLOG_LRI_2 lriType in db2LRI structures to read backwards through a log file.
Note: DB2READLOG_QUERY always returns DB2READLOG_LRI_1 db2LRI structures. To convert to a DB2READLOG_LRI_2 db2LRI structure, you must get the logStreamID and LSO of the current log record. You can get the LSO of the current log record by looking at the log header file. In a non-pureScale environment, the logStreamID is the same for all records in a single database. - DB2READLOG_LRI_1 is used when reading sequentially
through the logs. This type uses an LFS as
Usage notes
If the requested action is to read the log, you must provide a log record identifier range and a buffer to hold the log records. This API reads the log sequentially, bounded by the requested LRI range, and returns log records associated with tables defined with the DATA CAPTURE CHANGES clause, and a db2ReadLogInfoStruct structure with the current active log information. If the requested action is a query of the database log (indicated by specifying the value DB2READLOG_QUERY), the API returns a db2ReadLogInfoStruct structure with the current active log information.
- A value greater than initialLRI
- (0000 0000 0000 0001, FFFF FFFF FFFF FFFF, FFFF FFFF FFFF FFFF) (lriType, part1, part2) which is interpreted by the asynchronous log reader as the end of the current log.
The propagatable log records that are read within the starting and ending LRI range are returned in the log buffer. If the iFilterOption option is set to DB2READLOG_FILTER_ON, the LRI is replaced with the db2ReadLogFilterData data structure, in the buffer. Descriptions of the various Db2 log records returned by db2ReadLog can be found in the "Db2 log records" topic.
To read the next sequential log record after the initial read, use the nextStartLRI field returned in the db2ReadLogStruct structure. Resubmit the call, with this new starting LRI and a valid ending LRI. The next block of records is then read. An sqlca code of SQLU_RLOG_READ_TO_CURRENT means that the log reader has read to the end of the current active log.
This API reads data from the Db2logs. Label-based access control (LBAC) is not enforced on such logs. Thus, an application that calls this API can gain access to table data if the caller has sufficient authority to call the API and is able to understand the log records format.
The db2ReadLog API works on the current database connection. If multiple database connections are created with the same process, then use the concurrent access APIs to manage the multiple contexts.
- A CLI0116E error might be generated if the db2ReadLog API is called from a CLI application.
- A SQL0428N error might be generated if the db2ReadLog API is called from an embedded SQL application written in C.
Workaround 1: For non-embedded SQL applications, set autocommit mode on before calling the db2ReadLog API.
Workaround 2: Issue a COMMIT or ROLLBACK statement after calling the db2ReadLog API and before disconnecting from the database.
In a Db2 pureScale® environment, the call sequence for the db2ReadLog API remains unchanged from previous versions.
To begin reading log records, the caller can specify DB2READLOG_READ or DB2READLOG_READ_SINGLE. The LRI passed by the caller does not necessarily exist on a log steam, in which case the database manager returns the next log record.
The db2ReadLog API returns two LRI structures in the output buffer. The first LRI structure is used to read through the logs sequentially, and the second LRI structure identifies the log record within the log stream to which it belongs.
In a Db2 pureScale environment, the database has one log stream for each member. The db2ReadLog API supports reading all of the log streams and merging these to return the log records to the caller. This causes the data changes to be returned in the order in which they took effect.
The Db2 data server can still read the log files of inactive members or offline members. The db2ReadLog API may wait for Member Crash Recovery to complete on a member before returning with more log records.
In specific situations, the commit log record time might be slightly earlier than the commit occurred in the application.
Backward compatibility of the db2ReadLog API
Any application that passes a version of the db2ReadLogStruct, that precedes Db2 Version 9.8, to a Db2 Version 9.8 or later server will fail with SQL2032N, which indicates that the db2ReadLogStruct parameter is not valid. Due to the vast differences in log record structure and the introduction of db2LRI, old applications must be rewritten and recompiled using the new db2ReadLog structures.
Db2 clients can use the old db2ReadLogStruct from Db2 Version 9.7 and pass it to a V9.7 server, or use db2ReadLogStruct for Db2 Version 9.8 and pass it to a V9.8 or Db2 V10 server.