db2ReadLogNoConn API - Read the database logs without a database connection

The db2ReadLogNoConn API extracts log records from the Db2® database logs, or queries the Log Manager for current log state information.

Before using this API, call the db2ReadLogNoConnInit API to allocate the memory that is passed as an input parameter to this API. After calling this API, call the db2ReadLogNoConnTerm API to deallocate the memory. 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

None

Required connection

None

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  db2ReadLogNoConn (
       db2Uint32 versionNumber,
       void * pDB2ReadLogNoConnStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2ReadLogNoConnStruct
{
   db2Uint32 iCallerAction;
   db2LSN *piStartLSN;
   db2LSN *piEndLSN;
   char *poLogBuffer;
   db2Uint32 iLogBufferSize;
   char *piReadLogMemPtr;
   db2ReadLogNoConnInfoStruct *poReadLogInfo;
} db2ReadLogNoConnStruct;

typedef SQL_STRUCTURE db2ReadLogNoConnInfoStruct
{
   db2LSN firstAvailableLSN;
   db2LSN firstReadLSN;
   db2LSN nextStartLSN;
   db2Uint32 logRecsWritten;
   db2Uint32 logBytesWritten;
   db2Uint32 lastLogFullyRead;
   db2TimeOfLog currentTimeValue;
} db2ReadLogNoConnInfoStruct;

db2ReadLogNoConn API parameters

versionNumber: Input. Specifies the version and release level of the structure passed as the second parameter, pDB2ReadLogNoConnStruct.
pDB2ReadLogNoConnStruct: Input. A pointer to the db2ReadLogNoConnStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2ReadLogNoConnStruct data structure parameters

iCallerAction

Input. Specifies the action to be performed. Valid values are:

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

piStartLSN

Input. The starting log sequence number specifies the starting relative byte address for the reading of the log. This value must be the start of an actual log record.

piEndLSN

Input. The ending log sequence number specifies the ending relative byte address for the reading of the log. This value must be greater than piStartLsn, and does not need to be the end of an actual log record.

poLogBuffer

Output. The buffer where all the propagatable log records read within the specified range. 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 of a eight-byte log sequence number (LSN), representing the LSN of the following log record.

iLogBufferSize

Input. Specifies the size, in bytes, of the poLogBuffer output buffer. This buffer must be large enough to hold a single log record.

piReadLogMemPtr

Input. Block of memory of size iReadLogMemoryLimit that was allocated in the initialization call. This memory contains persistent data that the API requires at each invocation. This memory block must not be reallocated or altered in any way by the caller.

poReadLogInfo

Output. A pointer to the db2ReadLogNoConnInfoStruct structure.

db2ReadLogNoConnInfoStruct data structure parameters

firstAvailableLSN: First available LSN in available logs.
firstReadLSN: First LSN read on this call.
nextStartLSN: Next readable LSN.
logRecsWritten: Number of log records written to the log buffer field, poLogBuffer.
logBytesWritten: Number of bytes written to the log buffer field, poLogBuffer.
lastLogFullyRead: Number indicating the last log file that was read to completion.
currentTimeValue: Reserved for future use.

Usage notes

The db2ReadLogNoConn API is not supported in Db2 pureScale® environments. Any attempts to call it will fail with SQL1419N.

The db2ReadLogNoConn API requires a memory block that must be allocated using the db2ReadLogNoConnInit API. The memory block must be passed as an input parameter to all subsequent db2ReadLogNoConn API calls, and must not be altered.

When requesting a sequential read of log, the API requires a log sequence number (LSN) range and the allocated memory . The API will return a sequence of log records based on the filter option specified when initialized and the LSN range. When requesting a query, the read log information structure will contain a valid starting LSN, to be used on a read call. The value used as the ending LSN on a read can be one of the following values:

A value greater than the caller-specified startLSN.
FFFF FFFF FFFF FFFF which is interpreted by the asynchronous log reader as the end of the available logs.

The propagatable log records read within the starting and ending LSN range are returned in the log buffer. A log record does not contain its LSN, it is contained in the buffer before the actual log record. Descriptions of the various Db2 log records returned by db2ReadLogNoConn can be found in the Db2 Log Records section.

After the initial read, in order to read the next sequential log record, use the nextStartLSN value returned in db2ReadLogNoConnInfoStruct. Resubmit the call, with this new starting LSN and a valid ending LSN and the next block of records is then read. An sqlca code of SQLU_RLOG_READ_TO_CURRENT means the log reader has read to the end of the available log files.

When the API will no longer be used, use db2ReadLogNoConnTerm to terminate the memory.

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 potentially gain access to table data if the caller has sufficient authority to call the API and is able to understand the log records format.

Note: This API does not support the formatting of compressed row images in log records, which requires a connection to the database. To do this, use the db2ReadLog API instead. Since the formatting of compressed row images is not supported, this API returns the compressed row image as is.

When the database is encrypted, a call to the db2ReadLogNoConn API returns an error. Use the db2ReadLog API instead.