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.
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 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 48 bytes. Its maximum size is dependent on the size
of the requested range.
Each log record in the buffer is prefixed
by a eight-byte log sequence number (LSN), representing the LSN of
the following log record.
- iLogBufferSize
- Input. Specifies the size, in bytes, of the log buffer.
- 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.