db2Recover API - Restore and roll forward a database
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.
In a Db2® pureScale® environment, the db2Recover API can be called from any member.
Authorization
- SYSADM
- SYSCTRL
- SYSMAINT
- SYSADM
- SYSCTRL
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;
char *piEncrLibrary;
void *piEncrOptions;
db2Uint32 iEncrOptionsSize; struct sqleDbEncryptionOptions *piDbEncOpts;
} 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;
char *piEncrLibrary;
db2Uint32 iEncrLibraryLen;
void *piEncrOptions;
db2Uint32 iEncrOptionsSize; struct sqleDbEncryptionOptions *piDbEncOpts;
} 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 required.
- 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 rollforward 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 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.
- piEncrLibrary
- Input. Indicates the name of the external library to use to decrypt the backup image if the image is encrypted. The name must be a fully-qualified path that refers to a file on the server. If the value is a null pointer or a pointer to an empty string, the database manager attempts to use the library that is stored in the image. If the backup image is not encrypted, the value of this parameter is ignored. If the specified library is not found, the recovery operation will fail. This parameter must not be set if piComprLibrary is set.
- piEncrOptions
- Input. Describes a block of binary data that is passed to the initialization routine in the decryption library. Because the database manager passes this string directly from the client to the server, any byte reversal or code page conversion issues must be handled by the encryption library. If the first character of the data block is '@', the rest of the data is interpreted as the name of a file that resides on the server. The database manager then replaces the values of the piEncrOptions and iEncrOptionsSize parameters with the contents and size of this file and passes these new values to the initialization routine. The piEncrOptions parameter must not be set if piComprOptions is set.
- iEncrOptionsSize
- Input. A four-byte unsigned integer that represents the size of the block of data that is passed as piEncrOptions. The iEncrOptionsSize parameter must be zero if the piEncrOptions value is a null pointer.
- piDbEncOpts
- Input. A pointer to a structure containing the encryption options that are to be used when recovering into a new database.
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.
- iEncrLibraryLen
- Input. A four-byte unsigned integer that represents the length in bytes of the name of the library that is specified in the piEncrLibrary parameter. Set to zero if no library name is given.