Restores and rolls forward a database to a particular
point in time or to the end of the logs.
Scope
In a partitioned database environment,
this API can only be called from the catalog partition. If no database
partition servers are specified, it affects all database partition
servers that are listed in the db2nodes.cfg file. If a point in time
is specified, the API affects all database partitions.
Authorization
To recover an existing database,
one of the following:
To recover to a new database, one of the following:
Required connection
To recover an existing
database, a database connection is required. This API automatically
establishes a connection to the specified database and will release
the connection when the recover operation finishes. Instance and database,
to recover to a new database. The instance attachment is required
to create the database.
API include file
db2ApiDf.h
API and data structure syntax
SQL_API_RC SQL_API_FN
db2Recover (
db2Uint32 versionNumber,
void * pDB2RecovStruct,
struct sqlca * pSqlca);
typedef SQL_STRUCTURE db2RecoverStruct
{
char *piSourceDBAlias;
char *piUsername;
char *piPassword;
db2Uint32 iRecoverCallerAction;
db2Uint32 iOptions;
sqlint32 *poNumReplies;
struct sqlurf_info *poNodeInfo;
char *piStopTime;
char *piOverflowLogPath;
db2Uint32 iNumChngLgOvrflw;
struct sqlurf_newlogpath *piChngLogOvrflw;
db2int32 iAllNodeFlag;
db2int32 iNumNodes;
SQL_PDB_NODE_TYPE *piNodeList;
db2int32 iNumNodeInfo;
char *piHistoryFile;
db2Uint32 iNumChngHistoryFile;
struct sqlu_histFile *piChngHistoryFile;
char *piComprLibrary;
void *piComprOptions;
db2Uint32 iComprOptionsSize;
} db2RecoverStruct;
SQL_STRUCTURE sqlu_histFile
{
SQL_PDB_NODE_TYPE nodeNum;
unsigned short filenameLen;
char filename[SQL_FILENAME_SZ+1];
};
SQL_API_RC SQL_API_FN
db2gRecover (
db2Uint32 versionNumber,
void * pDB2gRecoverStruct,
struct sqlca * pSqlca);
typedef SQL_STRUCTURE db2gRecoverStruct
{
char *piSourceDBAlias;
db2Uint32 iSourceDBAliasLen;
char *piUserName;
db2Uint32 iUserNameLen;
char *piPassword;
db2Uint32 iPasswordLen;
db2Uint32 iRecoverCallerAction;
db2Uint32 iOptions;
sqlint32 *poNumReplies;
struct sqlurf_info *poNodeInfo;
char *piStopTime;
db2Uint32 iStopTimeLen;
char *piOverflowLogPath;
db2Uint32 iOverflowLogPathLen;
db2Uint32 iNumChngLgOvrflw;
struct sqlurf_newlogpath *piChngLogOvrflw;
db2int32 iAllNodeFlag;
db2int32 iNumNodes;
SQL_PDB_NODE_TYPE *piNodeList;
db2int32 iNumNodeInfo;
char *piHistoryFile;
db2Uint32 iHistoryFileLen;
db2Uint32 iNumChngHistoryFile;
struct sqlu_histFile *piChngHistoryFile;
char *piComprLibrary;
db2Uint32 iComprLibraryLen;
void *piComprOptions;
db2Uint32 iComprOptionsSize;
} db2gRecoverStruct;
db2Recover API parameters
- versionNumber
- Input. Specifies the version and release level of the structure
passed as the second parameter pDB2RecoverStruct.
- pDB2RecoverStruct
- Input. A pointer to the db2RecoverStruct structure.
- pSqlca
- Output. A pointer to the sqlca structure.
db2RecoverStruct data structure parameters
- piSourceDBAlias
- Input. A string containing the database alias of the database
to be recovered.
- piUserName
- Input. A string containing the user name to be used when attempting
a connection. Can be NULL.
- piPassword
- Input. A string containing the password to be used with the user
name. Can be NULL.
- iRecoverCallerAction
- Input. Valid values are:
- DB2RECOVER
- Starts the recover operation. Specifies that the recover will
run unattended, and that scenarios that normally require user intervention
will either be attempted without first returning to the caller, or
will generate an error. Use this caller action, for example, if it
is known that all of the media required for the recover have been
mounted, and utility prompts are not desired.
- DB2RECOVER_RESTART
- Allows the user to ignore a prior recover and start over from
the beginning.
- DB2RECOVER_CONTINUE
- Continue using the device that generated the warning message (for
example, when a new tape has been mounted).
- DB2RECOVER_LOADREC_TERM
- Terminate all devices being used by load recovery.
- DB2RECOVER_DEVICE_TERM
- Stop using the device that generated the warning message (for
example, when there are no more tapes).
- DB2RECOVER_PARM_CHK_ONLY
- Used to validate parameters without performing a recover operation.
Before this call returns, the database connection established by this
call is terminated, and no subsequent call is required.
- DB2RECOVER_DEVICE_TERMINATE
- Removes a particular device from the list of devices used by the
recover operation. When a particular device has exhausted its input,
recover will return a warning to the caller. Call the recover utility
again with this caller action to remove the device that generated
the warning from the list of devices being used.
- iOptions
- Input. Valid values are:
- - DB2RECOVER_EMPTY_FLAG
- No flags specified.
- - DB2RECOVER_LOCAL_TIME
- Indicates that the value specified for the stop time by piStopTime
is in local time, not GMT. This is the default setting.
- - DB2RECOVER_GMT_TIME
- This flag indicates that the value specified for the stop time
by piStopTime is in GMT (Greenwich Mean Time).
- poNumReplies
- Output. The number of replies received.
- poNodeInfo
- Output. Database partition reply information.
- piStopTime
- Input. A character string containing a time stamp in ISO format.
Database recovery will stop when this time stamp is exceeded. Specify
SQLUM_INFINITY_TIMESTAMP to roll forward as far as possible. May be
NULL for DB2ROLLFORWARD_QUERY, DB2ROLLFORWARD_PARM_CHECK, and any
of the load recovery (DB2ROLLFORWARD_LOADREC_) caller actions.
- piOverflowLogPath
- Input. This parameter is used to specify an alternate log path
to be used. In addition to the active log files, archived log files
need to be moved (by the user) into the location specified by the
logpath configuration parameter before they can be used by this utility.
This can be a problem if the user does not have sufficient space in
the log path. The overflow log path is provided for this reason. During
roll-forward recovery, the required log files are searched, first
in the log path, and then in the overflow log path. The log files
needed for table space rollforward recovery can be brought into either
the log path or the overflow log path. If the caller does not specify
an overflow log path, the default value is the log path.
In a
partitioned database environment, the overflow log path must be a
valid, fully qualified path; the default path is the default overflow
log path for each database partition. In a single-partition database
environment, the overflow log path can be relative if the server is
local.
- iNumChngLgOvrflw
- Input. Partitioned database environments only. The number of changed
overflow log paths. These new log paths override the default overflow
log path for the specified database partition server only.
- piChngLogOvrflw
- Input. Partitioned database environments only. A pointer to a
structure containing the fully qualified names of changed overflow
log paths. These new log paths override the default overflow log path
for the specified database partition server only.
- iAllNodeFlag
- Input. Partitioned database environments only. Indicates whether
the rollforward operation is to be applied to all database partition
servers defined in db2nodes.cfg. Valid values are:
- DB2_NODE_LIST
- Apply to database partition servers in a list that is passed in
piNodeList.
- DB2_ALL_NODES
- Apply to all database partition servers. piNodeList should be
NULL. This is the default value.
- DB2_ALL_EXCEPT
- Apply to all database partition servers except those in a list
that is passed in piNodeList.
- DB2_CAT_NODE_ONLY
- Apply to the catalog partition only. piNodeList should be NULL.
- iNumNodes
- Input. Specifies the number of database partition servers in the
piNodeList array.
- piNodeList
- Input. A pointer to an array of database partition server numbers
on which to perform the rollforward recovery.
- iNumNodeInfo
- Input. Defines the size of the output parameter poNodeInfo, which
must be large enough to hold status information from each database
partition that is being rolled forward. In a single-partition database
environment, this parameter should be set to 1. The value of this
parameter should be the same as the number of database partition servers
for which this API is being called.
- piHistoryFile
- History file.
- iNumChngHistoryFile
- Number of history files in list.
- piChngHistoryFile
- List of history files.
- piComprLibrary
- Input. Indicates the name of the external library to be used to
perform decompression of the backup image if the image is compressed.
The name must be a fully-qualified path referring to a file on the
server. If the value is a null pointer or a pointer to an empty string, DB2® will attempt to use the library
stored in the image. If the backup was not compressed, the value of
this parameter will be ignored. If the specified library is not found,
the restore will fail.
- piComprOptions
- Input. Describes a block of binary data that will be passed to
the initialization routine in the decompression library. DB2 will pass this string directly from the client
to the server, so any issues of byte-reversal or code-page conversion
will have to be handled by the compression library. If the first character
of the data block is '@', the remainder of the data will be interpreted
by DB2 as the name of a file
residing on the server. DB2 will
then replace the contents of piComprOptions and iComprOptionsSize
with the contents and size of this file respectively and will pass
these new values to the initialization routine instead.
- iComprOptionsSize
- Input. Represents the size of the block of data passed as piComprOptions.
iComprOptionsSize shall be zero if and only if piComprOptions is a
null pointer.
sqlu_histFile data structure parameters
- nodeNum
- Input. Specifies which database partition this entry should be
used for.
- filenameLen
- Input. Length in bytes of filename.
- filename
- Input. Path to the history file for this database partition. The
path must end with a slash.
db2gRecoverStruct data structure specific parameters
- iSourceDBAliasLen
- Specifies the length in bytes of the piSourceDBAlias parameter.
- iUserNameLen
- Specified the length in bytes of the piUsername parameter.
- iPasswordLen
- Specifies the length in bytes of the piPassword parameter.
- iStopTimeLen
- Specifies the length in bytes of the piStopTime parameter.
- iOverflowLogPathLen
- Specifies the length in bytes of the piOverflowLogPath parameter.
- iHistoryFileLen
- Specifies the length in bytes of the piHistoryFile parameter.
- iComprLibraryLen
- Input. Specifies the length in bytes of the name of the library
specified in the piComprLibrary parameter. Set to zero if no library
name is given.