DB2 Version 10.1 for Linux, UNIX, and Windows

db2HistoryOpenScan API - Start a database history records scan

Starts a database history records scan.

Note: This API is only supported in C, C++, or Java™ programming languages. It is no longer supported in COBOL, FORTRAN and REXX programming languages. You can issue a query to access database history records by using the DB_HISTORY administrative view.

Authorization

None

Required connection

Instance. If the database is cataloged as remote, call the sqleatin API before calling this API.

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  db2HistoryOpenScan (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2HistoryOpenStruct
{
   char *piDatabaseAlias;
   char *piTimestamp;
   char *piObjectName;
   db2Uint32 oNumRows;
   db2Uint32 oMaxTbspaces;
   db2Uint32 oMaxLogStreams;
   db2Uint16 iCallerAction;
   db2Uint16 oHandle;
} db2HistoryOpenStruct;

SQL_API_RC SQL_API_FN
  db2gHistoryOpenScan (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2gHistoryOpenStruct
{
   char *piDatabaseAlias;
   char *piTimestamp;
   char *piObjectName;
   db2Uint32 iAliasLen;
   db2Uint32 iTimestampLen;
   db2Uint32 iObjectNameLen;
   db2Uint32 oNumRows;
   db2Uint32 oMaxTbspaces;
   db2Uint32 oMaxLogStreams;
   db2Uint16 iCallerAction;
   db2Uint16 oHandle;
} db2gHistoryOpenStruct;

db2HistoryOpenScan API parameters

versionNumber: Input. Specifies the version and release level of the structure passed in as the second parameter, pParmStruct.
pParmStruct: Input or Output. A pointer to the db2HistoryOpenStruct data structure.
pSqlca: Output. A pointer to the sqlca structure.

db2HistoryOpenStruct data structure parameters

piDatabaseAlias

Input. A pointer to a string containing the database alias.

piTimestamp

Input. A pointer to a string specifying the time stamp to be used for selecting records. Records whose time stamp is equal to or greater than this value are selected. Setting this parameter to NULL, or pointing to zero, prevents the filtering of entries using a time stamp.

piObjectName

Input. A pointer to a string specifying the object name to be used for selecting records. The object may be a table or a table space. If it is a table, the fully qualified table name must be provided. Setting this parameter to NULL, or pointing to zero, prevents the filtering of entries using the object name.

oNumRows

Output. Upon return from the API call, this parameter contains the number of matching database history records entries.

oMaxTbspaces

Output. The maximum number of table space names stored with any history entry.

oMaxLogStreams

Output. The maximum number of log streams stored with any history entry.

iCallerAction

Input. Specifies the type of action to be taken. Valid values (defined in db2ApiDf header file, located in the include directory) are:

DB2HISTORY_LIST_HISTORY: Lists all events that are currently logged in the database history records.
DB2HISTORY_LIST_BACKUP: Lists backup and restore operations.
DB2HISTORY_LIST_ROLLFORWARD: Lists rollforward operations.
DB2HISTORY_LIST_DROPPED_TABLE: Lists dropped table records. The DDL field associated with an entry is not returned. To retrieve the DDL information for an entry, db2HistoryGetEntry must be called with a caller action of DB2HISTORY_GET_DDL immediately after the entry is fetched.
DB2HISTORY_LIST_LOAD: Lists load operations.
DB2HISTORY_LIST_CRT_TABLESPACE: Lists table space create and drop operations.
DB2HISTORY_LIST_REN_TABLESPACE: Lists table space renaming operations.
DB2HISTORY_LIST_ALT_TABLESPACE: Lists alter table space operations. The DDL field associated with an entry is not returned. To retrieve the DDL information for an entry, db2HistoryGetEntry must be called with a caller action of DB2HISTORY_GET_DDL immediately after the entry is fetched.
DB2HISTORY_LIST_REORG: Lists REORGANIZE TABLE operations. This value is not currently supported.

oHandle

Output. Upon return from the API, this parameter contains the handle for scan access. It is subsequently used in the db2HistoryGetEntry, and db2HistoryCloseScan APIs.

db2gHistoryOpenStruct data structure specific parameters

iAliasLen: Input. Specifies the length in bytes of the database alias string.
iTimestampLen: Input. Specifies the length in bytes of the timestamp string.
iObjectNameLen: Input. Specifies the length in bytes of the object name string.

Usage notes

The combination of time stamp, object name and caller action can be used to filter records. Only records that pass all specified filters are returned.

The filtering effect of the object name depends on the value specified:

Specifying a table will return records for load operations, because this is the only information for tables in the database history records.
Specifying a table space will return records for backup, restore, and load operations for the table space.

Note: To return records for tables, they must be specified as schema.tablename. Specifying tablename will only return records for table spaces.

A maximum of eight database history records scans per process is permitted.

To list every entry in the database history records, a typical application will perform the following steps:

Call the db2HistoryOpenScan API, which returns parameter value oNumRows.
Allocate a db2HistData structure with space for n oTablespace fields, where n is an arbitrary number.
Set the iNumTablespaces field of the db2HistoryData structure to n.
In a loop, perform the following actions:
- Call the db2HistoryGetEntry API to fetch from the database history records.
- If db2HistoryGetEntry API returns an SQLCODE value of SQL_RC_OK, use the oNumTablespaces field of the db2HistoryData structure to determine the number of table space entries returned.
- If db2HistoryGetEntry API returns an SQLCODE value of SQLUH_SQLUHINFO_VARS_WARNING, not enough space has been allocated for all of the table spaces that DB2® is trying to return; free and reallocate the db2HistoryData structure with enough space for oDB2UsedTablespace table space entries, and set iDB2NumTablespace to oDB2UsedTablespace.
- If db2HistoryGetEntry API returns an SQLCODE value of SQLE_RC_NOMORE, all database history records entries have been retrieved.
- Any other SQLCODE indicates a problem.
When all of the information has been fetched, call the db2HistoryCloseScan API to free the resources allocated by the call to db2HistoryOpenScan.

The macro SQLUHINFOSIZE(n) (defined in sqlutil header file) is provided to help determine how much memory is required for a db2HistoryData structure with space for n oTablespace entries.