db2ReadLog API - 读取日志记录

授权

需要的连接

数据库

API 包含文件

db2ApiDf.h

API 和数据结构语法

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;
   char *piStartTime;
} 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;
   db2LRI finalLRI;
} db2ReadLogInfoStruct;

typedef SQL_STRUCTURE db2TimeOfLog
{
   db2Uint32 seconds;
   db2Uint32 accuracy;
} db2TimeOfLog;

typedef SQL_STRUCTURE db2ReadLogFilterData
{
   db2LRI         recordLRIType1;
   db2LRI         recordLRIType2;
   db2Uint32      realLogRecLen;
   db2int32       sqlcode;
} db2ReadLogFilterData;

/******************************************************************************
** db2LRI data structure
** db2LRI data structure parameters
**
** lriType
** The type of LRI structure.  The following are the valid types:
**    - DB2READLOG_LRI_1 : part1 is the LFS and part2 is the LSN for
**                         the log record
**    - DB2READLOG_LRI_2 : part1 is the logStreamID and part2 is the LSO for
**                         the log record
** (See "Log record header" in Db2 documentation for the meaning of LFS, 
**  LSN, LSO.)
**    
** part1     
** Part 1 of the LRI structure.
**
** part2
** Part 2 of the LRI structure.
**
*******************************************************************************/
typedef SQL_STRUCTURE db2LRI
{
   db2Uint64       lriType;            /* LRI type                            */
   db2Uint64       part1;              /* Part 1 of the LRI structure         */
   db2Uint64       part2;              /* Part 2 of the LRI structure         */
} db2LRI;

/* db2LRI types                                                               */
#define DB2READLOG_LRI_1 1             /* LRI type 1                          */
#define DB2READLOG_LRI_2 2             /* LRI type 2                          */

db2ReadLog API 参数

db2ReadLogStruct 数据结构参数

db2ReadLogInfoStruct 数据结构参数

db2TimeOfLog 数据结构参数

db2ReadLogFilterData 数据结构参数

使用说明

如果请求的操作是读取日志，那么必须提供日志记录标识范围和缓冲区以保存日志记录。 此 API 按顺序读取由请求的 LRI 范围限定的日志，并返回与通过 DATA CAPTURE CHANGES 子句定义的表相关联的日志记录，以及具有当前活动日志信息的 db2ReadLogInfoStruct 结构。 如果请求的操作是对数据库日志的查询 (通过指定值 DB2READLOG_QUERY来指示) ，那么 API 将返回具有当前活动日志信息的 db2ReadLogInfoStruct 结构。

在起始和结束 LRI 范围内读取的可传播日志记录将在日志缓冲区中返回。 如果 iFilterOption 选项设置为 DB2READLOG_FILTER_ON，那么 LRI 将替换为缓冲区中的 db2ReadLogFilterData 数据结构。 可以在 "Db2 日志记录" 主题中找到 db2ReadLog 返回的各种 Db2 日志记录的描述。

要在初始读取后读取下一个顺序日志记录，请使用 db2ReadLogStruct 结构中返回的 nextStartLRI 字段。 请重新提交该调用，并使用此新启动的 LRI 和有效的结束 LRI。 然后读取下一个记录块。 sqlca 代码 SQLU_RLOG_READ_TO_CURRENT 表示日志阅读器已读取到当前活动日志的末尾。

此 API 从 Db2日志中读取数据。 不会在此类日志上实施基于标签的访问控制 (LBAC)。 因此，如果调用者具有调用此 API 的足够权限并且能够了解日志记录格式，那么调用此 API 的应用程序可以获取对表数据的访问权。

db2ReadLog API 适用于当前数据库连接。 如果使用同一进程创建了多个数据库连接，请使用并发访问 API 来管理多个上下文。

变通方法 1: 对于非嵌入式 SQL 应用程序，请在调用 db2ReadLog API 之前设置自动落实方式。

变通方法 2: 在调用 db2ReadLog API 之后并在与数据库断开连接之前发出 COMMIT 或 ROLLBACK 语句。

pureScale 环境中的 db2ReadLog 用法

在 Db2 pureScale® 环境中， db2ReadLog API 的调用顺序与先前版本保持不变。

要开始读取日志记录，调用者可以指定 DB2READLOG_READ 或 DB2READLOG_READ_SINGLE。 调用者传递的 LRI 不一定存在于日志流中，在这种情况下，数据库管理器将返回下一个日志记录。

db2ReadLog API 在输出缓冲区中返回两个 LRI 结构。 第一个 LRI 结构用于按顺序读取日志，第二个 LRI 结构标识它所属的日志流中的日志记录。

在 Db2 pureScale 环境中，数据库针对每个 成员具有一个日志流。 db2ReadLog API 支持读取所有日志流并合并这些日志流以将日志记录返回给调用者。 这将导致按数据更改生效的顺序返回数据更改。

Db2 数据服务器仍可以读取不活动 成员 或脱机 成员的日志文件。 db2ReadLog API 可能会等待成员崩溃恢复在 成员 上完成，然后返回更多日志记录。

在特定情况下，落实日志记录时间可能略早于应用程序中发生的落实时间。

分区数据库环境中的 db2ReadLog 用法

在分区数据库环境中，数据库分为数据库分区，每个分区都有自己的日志流。 db2ReadLog API 仅从应用程序连接到的特定数据库分区返回日志记录。 要查看和处理数据库中的所有日志记录，应用程序必须连接到每个数据库分区，并在每个流上合并从 db2ReadLog API 返回的日志记录。

分区数据库环境中的事务可以对多个数据库分区上的数据进行更改。 在每个分区上，事务的日志记录由日志记录头中的事务标识标识。 此事务标识仅在此数据库分区中有意义，而另一数据库分区上的同一事务的日志记录可以在日志记录头中具有不同的事务标识。 确定这些日志记录属于同一用户事务的唯一方法是检查 MPP 次母准备日志记录和 MPP 协调程序落实日志记录的 MPP identifier of the transaction field 。

db2ReadLog 用于将开始时间映射到 LRI

从 Db2 11.5.8.0开始，在所有环境中， db2ReadLog API 可以将开始时间映射到 LRI。 通过使用调用者操作 DB2READLOG_QUERY， piStartTime 字段可以指定指向 ISO 格式的全球标准时间 (UTC) 时间戳记的指针。 API 尝试查找匹配或早于提供的时间戳记的日志记录，并返回关联的 LRI。 如果找到匹配项，那么将设置 nextStartLRI 。 然后，可以将此 LRI 用作后续日志数据读取调用的 API 的启动 LRI。

注：

• 使用 db2Version11580 API 时，如果指定有效 piStartTime 的 Db2 11.5.8.0 客户机尝试与版本低于 Db2 11.5.8.0的任何 Db2 服务器进行通信，那么该客户机将失败。
• Db2 11.5.8.0 服务器支持来自任何Db2 11.5.8.0 之前的客户机的请求。 来自这些客户机的请求没有 piStartTime 参数，因此其行为保持不变。
• db2ReadLog API 的下限与映射的回溯程度相同。 如果提供的开始时间戳记太旧，并且 db2ReadLog API 无法将其映射到 LRI ，那么 API 将返回 SQL2650N rc=21。
• 为了实现高效的时间戳记到日志记录映射， API 将使用 DB2TSCHG.HIS 文件。 对于将 Db2 注册表变量 DB2_COLLECT_TS_REC_INFO 设置为 OFF的用户，启动时间映射可能效率较低。

db2ReadLog API 的向后兼容性

将 Db2 V 9.8之前的 db2ReadLogStruct版本传递到 Db2 V 9.8 或更高版本服务器的任何应用程序都将失败，并返回 SQL2032N 错误，指示 db2ReadLogStruct 参数无效。 由于日志记录结构的巨大差异以及 db2LRI的引入，必须使用新的 db2ReadLog 结构来重写和重新编译旧应用程序。

Db2 客户机可以使用 Db2 Version 9.7 中的旧 db2ReadLogStruct 并将其传递到 V9.7 服务器，或者使用 db2ReadLogStruct for Db2 Version 9.8 并将其传递到 V9.8 或 Db2 V10 服务器。