Administrative API Reference
Starts a recovery history file scan.
Authorization
None
Required Connection
Instance. It is not necessary to call ATTACH before calling this
API. If the database is cataloged as remote, an instance attachment to
the remote node is established.
Version
db2ApiDf.h
C API Syntax
/* File: db2ApiDf.h */
/* API: Open Recovery History File Scan */
/* ... */
SQL_API_RC SQL_API_FN
db2HistoryOpenScan (
db2Uint32 version,
void * pDB2HistoryOpenStruct,
struct sqlca * pSqlca);
typedef struct
{
char * piDatabaseAlias,
char * piTimestamp,
char * piObjectName,
db2Uint32 oNumRows,
db2Uint16 iCallerAction,
db2Uint16 oHandle
} db2HistoryOpenStruct;
/* ... */
|
Generic API Syntax
/* File: db2ApiDf.h */
/* API: Open Recovery History File Scan */
/* ... */
SQL_API_RC SQL_API_FN
db2GenHistoryOpenScan (
db2Uint32 version,
void * pDB2GenHistoryOpenStruct,
struct sqlca * pSqlca);
typedef struct
{
char * piDatabaseAlias,
char * piTimestamp,
char * piObjectName,
db2Uint32 oNumRows,
db2Uint16 iCallerAction,
db2Uint16 oHandle
} db2GenHistoryOpenStruct;
/* ... */
|
API Parameters
- version
- Input. Specifies the version and release level of the structure
passed in as the second parameter, pDB2HistoryOpenStruct.
- pDB2HistoryOpenStruct
- Input. A pointer to the db2HistoryOpenStruct
structure.
- pSqlca
- Output. A pointer to the sqlca structure. For
more information about this structure, see SQLCA.
- 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, this parameter contains the
number of matching recovery history file entries.
- iCallerAction
- Input. Specifies the type of action to be taken. Valid
values (defined in db2ApiDf) are:
- DB2HISTORY_LIST_HISTORY
- Select all of the records (backup, restore, and load) that pass the other
filters.
- DB2HISTORY_LIST_BACKUP
- Select only the backup and restore records that pass the other
filters.
- DB2HISTORY_LIST_ROLLFORWARD
- Select only the roll forward records that pass the other filters.
- DB2HISTORY_LIST_RUNSTATS
- Select only the RUNSTATS records that pass the other filters.
| Note: | This value is not currently supported.
|
- DB2HISTORY_LIST_REORG
- Select only the reorganize table records that pass the other
filters.
| Note: | This value is not currently supported.
|
- DB2HISTORY_LIST_ALT_TABLESPACE
- Select only the ALTER TABLESPACE records that pass the other
filters. The DDL field associated with an entry will not be
returned. To retrieve the DDL information for an entry, db2HistoryGetEntry - Get Next Recovery History File Entry must be called with a caller action of
DB2HISTORY_GET_DDL immediately after the entry is
fetched.
- DB2HISTORY_LIST_DROPPED_TABLE
- Select only the dropped table records that pass the other filters.
The DDL field associated with an entry will not be returned. To
retrieve the DDL information for an entry, db2HistoryGetEntry - Get Next Recovery History File Entry must be called with a caller action of
DB2HISTORY_GET_DDL immediately after the entry is
fetched.
- DB2HISTORY_LIST_LOAD
- Select only the load records that pass the other filters.
- DB2HISTORY_LIST_REN_TABLESPACE
- Select only the rename tablespace records that pass the other
filters.
- oHandle
- Output. Upon return from the API, this parameter contains the
handle for scan access. It is subsequently used in db2HistoryGetEntry - Get Next Recovery History File Entry, and db2HistoryCloseScan - Close Recovery History File Scan.
REXX API Syntax
OPEN [BACKUP] RECOVERY HISTORY FILE FOR database_alias
[OBJECT objname] [TIMESTAMP :timestamp]
USING :value
|
REXX API Parameters
- database_alias
- The alias of the database whose history file is to be listed.
- objname
- Specifies 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
prevents the filtering of entries using objname.
- timestamp
- Specifies 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 prevents the filtering of entries using
timestamp.
- value
- A compound REXX host variable to which recovery history file information
is returned. In the following, XXX represents the host variable
name.
- XXX.0
- Number of elements in the variable (always 2)
- XXX.1
- Identifier (handle) for future scan access
- XXX.2
- Number of matching recovery history file entries.
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 history file.
- Specifying a table space will return records for backups, restore
operations, 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 history file scans per process is permitted.
To list every entry in the history file, a typical application will perform
the following steps:
- Call db2HistoryOpenScan, which will return
oNumRows.
- Allocate an db2HistData structure with space for n
oTablespace fields, where n is an arbitrary number.
- Set the iDB2NumTablespace field of the db2HistData
structure to n.
- In a loop, perform the following:
- Call db2HistoryGetEntry to fetch from the history file.
- If db2HistoryGetEntry returns an SQLCODE of
SQL_RC_OK, use the sqld field of the
db2HistData structure to determine the number of table space entries
returned.
- If db2HistoryGetEntry returns an SQLCODE 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 db2HistData structure with enough space for
oDB2UsedTablespace table space entries, and set
iDB2NumTablespace to oDB2UsedTablespace.
- If db2HistoryGetEntry returns an SQLCODE of
SQLE_RC_NOMORE, all recovery history file entries have been
retrieved.
- Any other SQLCODE indicates a problem.
- When all of the information has been fetched, call db2HistoryCloseScan - Close Recovery History File Scan to free the resources allocated by the call to
db2HistoryOpenScan.
The macro SQLUHINFOSIZE(n), defined in sqlutil, is
provided to help determine how much memory is required for an
db2HistData structure with space for n oTablespace
fields.
See Also
db2HistoryCloseScan - Close Recovery History File Scan
db2HistoryGetEntry - Get Next Recovery History File Entry
db2Prune
db2HistoryUpdate - Update Recovery History File.
[ Top of Page | Previous Page | Next Page ]