DB2 Version 10.1 for Linux, UNIX, and Windows

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

To recover an existing database, one of the following authorities:

SYSADM
SYSCTRL
SYSMAINT

To recover to a new database, one of the following authorities:

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;
} 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 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.

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.