DB2 Version 10.1 for Linux, UNIX, and Windows

db2ReadLog API - Read log records

Reads log records from the DB2® database logs, or queries the Log Manager for current log state information. This API can only be used with recoverable databases. A database is recoverable if the database configuration parameters logarchmeth1 or logarchmeth2, or both, are not set to OFF.

Authorization

One of the following authorities:

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 where all the propagatable log records read within the specified range are stored sequentially. This buffer must be large enough to hold a single log record. As a guideline, this buffer should be a minimum of 88 bytes. Its maximum size is dependent on the size of the requested range.

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 log buffer.

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

Output. The db2ReadLogFilterData structure holds metadata for the log record, as follows:

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

The db2LRI structure is a Log Record Identifier structure used to describe which log records the user wants to read and which log records have been read, as follows:

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 as part2 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 as part1 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.

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.

Note: db2ReadLog API can not be used to read logs written before a drop member operation. Attempting to read those logs will result in a SQL1273N.

To use the Asynchronous Log Reader, first query the database log for a valid starting LRI. Following the query call, the read log information structure (db2ReadLogInfoStruct) will contain a valid starting LRI (in the initialLRI member), to be used on a read call. The value used as the ending LRI on a read can be one of the following values:

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 DB2 logs. 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.

Calling the db2ReadLog API from an application can result in an error when the application disconnects from the database if a commit or rollback is not performed before the disconnect:

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 case Member Crash Recovery takes a long time to complete, SQL1015N will be returned. Users should resubmit the db2ReadLog call in this case.

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 DB2 V9.7 server, or use db2ReadLogStruct for DB2 Version 9.8 and pass it to a DB2 V9.8 or DB2 V10 server.