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_HISTORY
- Select all of the records (backup, restore, load and unload) that pass the
other filters.
- SQLUH_LIST_BACKUP
- Select only the backup and restore 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 and unloads, because this
is the only information for tables in the history file.
- Specifying a table space will return records for backups, restores, loads,
and unloads 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 ]