Extracts log records from the DB2® database logs, or queries the Log Manager
for current log state information. Prior to 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 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:
- 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.