IBM Books

Administrative API Reference

sqlurlog - Asynchronous Read Log

Provides the caller with the ability to extract certain log records from the DB2 Common Server database logs, and to query the Log Manager for current log state information. This API can only be used on databases with recoverable database logs (the configuration parameters LOGRETAIN or USEREXIT enabled).

Authorization

One of the following:

Required Connection

Database

Version

sqlutil.h

C API Syntax 



/* File: sqlutil.h */
/* API: Asynchronous Read Log */
/* ... */
SQL_API_RC SQL_API_FN
  sqlurlog (
    unsigned long CallerAction,
    SQLU_LSN * pStartLsn,
    SQLU_LSN * pEndLsn,
    char * pLogBuffer,
    unsigned long LogBufferSize,
    SQLU_RLOG_INFO * pReadLogInfo,
    struct sqlca * pSqlca);
/* ... */

API Parameters

CallerAction
Input. Specifies the action to be performed.

SQLU_RLOG_READ
Read the database log from the starting log sequence to the ending log sequence number and return all propagatable log records within this range.

SQLU_RLOG_READ_SINGLE
Read a single log record (propagatable or not) identified by the starting log sequence number.

SQLU_RLOG_QUERY
Query the database log. Results of the query will be sent back via the SQLU_RLOG_INFO structure (see SQLU-RLOG-INFO).

pStartLsn
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.

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

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

LogBufferSize
Output. Specifies the size, in bytes, of the log buffer.

pReadLogInfo
Output. A structure detailing information regarding the call and the database log. For more information about this structure, see SQLU-RLOG-INFO.

pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

Sample Programs

C
\sqllib\samples\c\asynrlog.sqc

Usage Notes

If the requested action is to read the log, the caller will provide a log sequence number range and a buffer to hold the log records. The ASYNCHRONOUS READ LOG API reads the log sequentially, bounded by the requested LSN range, and returns log records associated with tables having the DATA CAPTURE option CHANGES, and an SQLU_RLOG_INFO structure with the current active log information. If the requested action is query, the API returns an SQLU_RLOG_INFO structure with the current active log information.

To use the Asynchronous Log Reader, first query the database log for a valid starting LSN. Following the query call, the read log information structure (SQLU-RLOG-INFO) will contain a valid starting LSN (in the initialLSN member), to be used on a read call. The end of the current active log will be in the curActiveLSN member of the read log information structure. The value used as the ending LSN on a read can be one of the following:

For more information about the read log information structure, see SQLU-RLOG-INFO.

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 Common Server log records returned by sqlurlog can be found in Appendix G. DB2 Common Server Log Records.

After the initial read, in order to read the next sequential log record, add 1 to the last read LSN returned in SQLU-RLOG-INFO. Resubmit the call, with this new starting LSN and a valid ending LSN. 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 current active log.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]