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.
API Include File
sqlutil.h
C API Syntax
/* File: sqlutil.h */
/* API: Open Recovery History File Scan */
/* ... */
SQL_API_RC SQL_API_FN
sqluhops (
char * pDbAlias,
char * pTimestamp,
char * pObjectName,
unsigned short * pNumRows,
unsigned short * pHandle,
unsigned short CallerAction,
void * pReserved,
struct sqlca * pSqlca);
/* ... */
|
Generic API Syntax
/* File: sqlutil.h */
/* API: Open Recovery History File Scan */
/* ... */
SQL_API_RC SQL_API_FN
sqlghops (
unsigned short DbAliasLen,
unsigned short TimestampLen,
unsigned short ObjectNameLen,
char * pDbAlias,
char * pTimestamp,
char * pObjectName,
unsigned short * pNumRows,
unsigned short * pHandle,
unsigned short CallerAction,
void * pReserved,
struct sqlca * pSqlca);
/* ... */
|
API Parameters
- DbAliasLen
- Input. A 2-byte unsigned integer representing the length in bytes
of the database alias.
- TimestampLen
- Input. A 2-byte unsigned integer representing the length in bytes
of the time stamp. Set to zero if no time stamp is provided.
- ObjectNameLen
- Input. A 2-byte unsigned integer representing the length in bytes
of the object name. Set to zero if no object name is provided.
- pDbAlias
- Input. A string containing the database alias.
- pTimestamp
- Input. 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.
- pObjectName
- Input. 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.
- pNumRows
- Output. Upon return from the API, this parameter contains the
number of matching recovery history file entries.
- pHandle
- Output. Upon return from the API, this parameter contains the
handle for scan access. It is subsequently used in sqluhgne - Get Next Recovery History File Entry, and sqluhcls - Close Recovery History File Scan.
- CallerAction
- Input. Valid values (defined in sqlutil) are:
- SQLUH_LIST_ADM_HISTORY
- Select all of the records (backup, restore, and load) that pass the other
filters.
- SQLUH_LIST_ADM_BACKUP
- Select only the backup and restore records that pass the other
filters.
- SQLUH_LIST_ADM_ROLLFORWARD
- Select only the roll forward records that pass the other filters.
- SQLUH_LIST_ADM_RUNSTATS
- Select only the RUNSTATS records that pass the other filters.
- SQLUH_LIST_ADM_REORG
- Select only the reorganize table records that pass the other
filters.
- SQLUH_LIST_ADM_ALTER_TABLESPACE
- Select only the ALTER TABLESPACE records that pass the other
filters.
- SQLUH_LIST_ADM_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, sqluhgne - Get Next Recovery History File Entry must be called with a caller action of SQLUH_GET_DDL
immediately after the entry is fetched.
- SQLUH_LIST_ADM_LOAD
- Select only the load records that pass the other filters.
- pReserved
- Reserved for future use.
- pSqlca
- Output. A pointer to the sqlca structure. For
more information about this structure, see SQLCA.
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.
Sample Programs
- C
- \sqllib\samples\c\rechist.c
- COBOL
- \sqllib\samples\cobol\rechist.cbl
- FORTRAN
- \sqllib\samples\fortran\rechist.f
- REXX
- \sqllib\samples\rexx\rechist.cmd
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 loads, because this is the only
information for tables in the history file.
- Specifying a table space will return records for backups, restores, and
loads for the table space.
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 sqluhops, which will return pNumRows
- Allocate an sqluhinfo structure with space for n
tablespace fields, where n is an arbitrary number
- Set the sqln field of the sqluhinfo structure to
n
- In a loop, perform the following:
- Call sqluhgne to fetch from the history file.
- If sqluhgne returns an SQLCODE of SQL_RC_OK,
use the sqld field of the sqluhinfo structure to
determine the number of table space entries returned.
- If sqluhgne 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 sqluhinfo structure with enough space for
sqld table space entries, and set sqln to
sqld.
- If sqluhgne returns an SQLCODE of
SQLE_RC_NOMORE, all recovery history files have been
retrieved.
- Any other SQLCODE indicates a problem.
- When all of the information has been fetched, call sqluhcls - Close Recovery History File Scan to free the resources allocated by the call to
sqluhops.
The macro SQLUHINFOSIZE(n), defined in sqlutil, is
provided to help determine how much memory is required for an
sqluhinfo structure with space for n
tablespace fields.
See Also
sqluhcls - Close Recovery History File Scan
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
[ DB2 List of Books |
Search the DB2 Books ]