db2Rollforward - Rollforward Database
Recovers a database by applying transactions recorded in the database log files. Called after a database or a table space backup has been restored, or if any table spaces have been taken offline by the database due to a media error. The database must be recoverable (that is, either logretain , userexit , or both of these database configuration parameters must be set on) before the database can be recovered with roll-forward recovery.
Scope
In a partitioned database environment, this API can only be called from the catalog partition. A database or table space rollforward call specifying a point-in-time affects all database partition servers that are listed in the db2nodes.cfg file. A database or table space rollforward call specifying end of logs affects the database partition servers that are specified. If no database partition servers are specified, it affects all database partition servers that are listed in the db2nodes.cfg file; if no roll forward is needed on a particular database partition server, that database partition server is ignored.
Authorization
One of the following:
- sysadm
- sysctrl
- sysmaint
Required connection
None. This API establishes a database connection.
API include file
db2ApiDf.h
C API syntax
| /* File: db2ApiDf.h */
| /* API: db2Rollforward */
| /* ... */
| SQL_API_RC SQL_API_FN
| db2Rollforward (
| db2Uint32 versionNumber,
| void *pDB2RollforwardStruct,
| struct sqlca *pSqlca);
|
| typedef SQL_STRUCTURE db2RollforwardStruct
| {
| struct db2RfwdInputStruct *piRfwdInput;
| struct db2RfwdOutputStruct *poRfwdOutput;
| } db2RollforwardStruct;
|
| typedef SQL_STRUCTURE db2RfwdInputStruct
| {
| sqluint32 iVersion;
| char *piDbAlias;
| db2Uint32 iCallerAction;
| char *piStopTime;
| char *piUserName;
| char *piPassword;
| char *piOverflowLogPath;
| db2Uint32 iNumChngLgOvrflw;
| struct sqlurf_newlogpath *piChngLogOvrflw;
| db2Uint32 iConnectMode;
| struct sqlu_tablespace_bkrst_list *piTablespaceList;
| db2int32 iAllNodeFlag;
| db2int32 iNumNodes;
| SQL_PDB_NODE_TYPE *piNodeList;
| db2int32 iNumNodeInfo;
| char *piDroppedTblID;
| char *piExportDir;
| db2Uint32 iRollforwardFlags;
| } db2RfwdInputStruct;
|
| typedef SQL_STRUCTURE db2RfwdOutputStruct
| {
| char *poApplicationId;
| sqlint32 *poNumReplies;
| struct sqlurf_info *poNodeInfo;
| } db2RfwdOutputStruct;
|
| typedef SQL_STRUCTURE sqlurf_newlogpath
| {
| SQL_PDB_NODE_TYPE nodenum;
| unsigned short pathlen;
| char logpath[SQL_LOGPATH_SZ+SQL_LOGFILE_NAME_SZ+1];
| } sqlurf_newlogpath;
|
| typedef SQL_STRUCTURE sqlu_tablespace_bkrst_list
| {
| long num_entry;
| struct sqlu_tablespace_entry *tablespace;
| } sqlu_tablespace_bkrst_list;
|
| typedef SQL_STRUCTURE sqlu_tablespace_entry
| {
| sqluint32 reserve_len;
| char tablespace_entry[SQLU_MAX_TBS_NAME_LEN+1];
| char filler[1];
| } sqlu_tablespace_entry;
|
| typedef SQL_STRUCTURE sqlurf_info
| {
| SQL_PDB_NODE_TYPE nodenum;
| sqlint32 state;
| unsigned char nextarclog[SQLUM_ARCHIVE_FILE_LEN+1];
| unsigned char firstarcdel[SQLUM_ARCHIVE_FILE_LEN+1];
| unsigned char lastarcdel[SQLUM_ARCHIVE_FILE_LEN+1];
| unsigned char lastcommit[SQLUM_TIMESTAMP_LEN+1];
| } sqlurf_info;
| /* ... */
Generic API syntax
| /* File: db2ApiDf.h */
| /* API: db2Rollforward */
| /* ... */
| SQL_API_RC SQL_API_FN
| db2gRollforward (
| db2Uint32 versionNumber,
| void *pDB2gRollforwardStruct,
| struct sqlca *pSqlca);
|
| typedef SQL_STRUCTURE db2gRollforwardStruct
| {
| struct db2gRfwdInputStruct *piRfwdInput;
| struct db2RfwdOutputStruct *poRfwdOutput;
| } db2gRollforwardStruct;
|
| SQL_STRUCTURE db2gRfwdInputStruct
| {
| db2Uint32 iDbAliasLen;
| db2Uint32 iStopTimeLen;
| db2Uint32 iUserNameLen;
| db2Uint32 iPasswordLen;
| db2Uint32 iOvrflwLogPathLen;
| db2Uint32 iDroppedTblIDLen;
| db2Uint32 iExportDirLen;
| sqluint32 iVersion;
| char *piDbAlias;
| db2Uint32 iCallerAction;
| char *piStopTime;
| char *piUserName;
| char *piPassword;
| char *piOverflowLogPath;
| db2Uint32 iNumChngLgOvrflw;
| struct sqlurf_newlogpath *piChngLogOvrflw;
| db2Uint32 iConnectMode;
| struct sqlu_tablespace_bkrst_list *piTablespaceList;
| db2int32 iAllNodeFlag;
| db2int32 iNumNodes;
| SQL_PDB_NODE_TYPE *piNodeList;
| db2int32 iNumNodeInfo;
| char *piDroppedTblID;
| char *piExportDir;
| db2Uint32 iRollforwardFlags;
| } db2gRfwdInputStruct;
|
| typedef SQL_STRUCTURE db2RfwdOutputStruct
| {
| char *poApplicationId;
| sqlint32 *poNumReplies;
| struct sqlurf_info *poNodeInfo;
| } db2RfwdOutputStruct;
|
| typedef SQL_STRUCTURE sqlurf_newlogpath
| {
| SQL_PDB_NODE_TYPE nodenum;
| unsigned short pathlen;
| char logpath[SQL_LOGPATH_SZ+SQL_LOGFILE_NAME_SZ+1];
| } sqlurf_newlogpath;
|
| typedef SQL_STRUCTURE sqlu_tablespace_bkrst_list
| {
| long num_entry;
| struct sqlu_tablespace_entry *tablespace;
| } sqlu_tablespace_bkrst_list;
|
| typedef SQL_STRUCTURE sqlu_tablespace_entry
| {
| sqluint32 reserve_len;
| char tablespace_entry[SQLU_MAX_TBS_NAME_LEN+1];
| char filler[1];
| } sqlu_tablespace_entry;
|
| typedef SQL_STRUCTURE sqlurf_info
| {
| SQL_PDB_NODE_TYPE nodenum;
| sqlint32 state;
| unsigned char nextarclog[SQLUM_ARCHIVE_FILE_LEN+1];
| unsigned char firstarcdel[SQLUM_ARCHIVE_FILE_LEN+1];
| unsigned char lastarcdel[SQLUM_ARCHIVE_FILE_LEN+1];
| unsigned char lastcommit[SQLUM_TIMESTAMP_LEN+1];
| } sqlurf_info;
| /* ... */
API parameters
-
versionNumber
- Input. Specifies the version and release level of the structure passed as the second parameter. pDB2RollforwardStruct
- Input. A pointer to the db2RollforwardStruct structure. pSqlca
- Output. A pointer to the sqlca structure. | piRfwdInput
- Input. A pointer to the db2RfwdInputStruct structure. | poRfwdOutput
- Output. A pointer to the db2RfwdOutputStruct structure. | iDbAliasLen
- Input. Specifies the length in bytes of the database alias. | iStopTimeLen
- Input. Specifies the length in bytes of the stop time parameter. Set to zero if no stop time is provided. | iUserNameLen
- Input. Specifies the length in bytes of the user name. Set to zero if no user name is provided. | iPasswordLen
- Input. Specifies the length in bytes of the password. Set to zero if no password is provided. | iOverflowLogPathLen
- Input. Specifies the length in bytes of the overflow log path. Set to zero if no overflow log path is provided. | iVersion
- Input. The version ID of the rollforward parameters. It is defined as SQLUM_RFWD_VERSION. | piDbAlias
- Input. A string containing the database alias. This is the alias that is cataloged in the system database directory. | iCallerAction
-
Input. Specifies action to be taken. Valid values (defined in
|
db2ApiDf.h ) are:
-
| DB2ROLLFORWARD_ROLLFWD
- Rollforward to the point in time specified by | piStopTime . For database rollforward, the database is left in rollforward-pending state. For table space rollforward to a point in time, the table spaces are left in rollforward-in-progress state. | DB2ROLLFORWARD_STOP
- End roll-forward recovery. No new log records are processed and uncommitted transactions are backed out. The rollforward-pending state of the database or table spaces is turned off. Synonym is | DB2ROLLFORWARD_RFWD_COMPLETE. | DB2ROLLFORWARD_RFWD_STOP
- Rollforward to the point in time specified by | piStopTime , and end roll-forward recovery. The rollforward-pending state of the database or table spaces is turned off. Synonym is | DB2ROLLFORWARD_RFWD_COMPLETE. | DB2ROLLFORWARD_QUERY
- Query values for | nextarclog , | firstarcdel , | lastarcdel , and | lastcommit . Return database status and a node number. | DB2ROLLFORWARD_PARM_CHECK
- Validate parameters without performing the roll forward. | DB2ROLLFORWARD_CANCEL
-
Cancel the rollforward operation that is currently running. The database or table space are put in recovery pending state.
-
Note:
- This option cannot be used while the rollforward is actually running. It can be used if the rollforward is paused (that is, waiting for a STOP), or if a system failure occurred during the rollforward. It should be used with caution.
Rolling databases forward may require a load recovery using tape devices. The rollforward API will return with a warning message if user intervention on a device is required. The API can be called again with one of the following three caller actions:
-
| DB2ROLLFORWARD_LOADREC_CONT
- Continue using the device that generated the warning message (for example, when a new tape has been mounted). | DB2ROLLFORWARD_DEVICE_TERM
- Stop using the device that generated the warning message (for example, when there are no more tapes). DB2ROLLFORWARD_LOAD_REC_TERM
- Terminate all devices being used by load recovery.
| 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_ xxx ) caller actions. | piUserName
- Input. A string containing the user name of the application. May be NULL. | piPassword
- Input. A string containing the password of the supplied user name (if any). May be NULL. | 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 logpath before they can be used by this utility. This can be a problem if the user does not have sufficient space in the logpath . The overflow log path is provided for this reason. During roll-forward recovery, the required log files are searched, first in the logpath , and then in the overflow log path. The log files needed for table space roll-forward recovery can be brought into either the logpath or the overflow log path. If the caller does not specify an overflow log path, the default value is the logpath . 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 node. 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. | iConnectMode
-
Input. Valid values (defined in
|
db2ApiDf.h ) are:
-
| DB2ROLLFORWARD_OFFLINE
- Offline roll forward. This value must be specified for database roll-forward recovery. | DB2ROLLFORWARD_ONLINE
- Online roll forward.
| piTablespaceList
- Input. A pointer to a structure containing the names of the table spaces to be rolled forward to the end-of-logs or to a specific point in time. If not specified, the table spaces needing rollforward will be selected. | 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 roll-forward 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 same as the number of database partition servers for which this API is being called. | piDroppedTblID
- Input. A string containing the ID of the dropped table whose recovery is being attempted. | piExportDir
- Input. The directory into which the dropped table data will be exported. RollforwardFlags
-
Input. Specifies the rollforward flags. Valid values (defined in
|
db2ApiDf.h ):
-
|
DB2ROLLFORWARD_EMPTY_FLAG
- | No flags specified. | DB2ROLLFORWARD_LOCAL_TIME
- Allows the user to rollforward to a point in time that is the user's local time rather than GMT time. This makes it easier for users to rollforward to a specific point in time on their local machines, and eliminates potential user errors due to the translation of local to GMT time. | DB2ROLLFORWARD_NO_RETRIEVE
- Controls which log files to be rolled forward on the standby machine by allowing the user to disable the retrieval of archived logs. By controlling the log files to be rolled forward, one can ensure that the standby machine is X hours behind the production machine, to prevent the user affecting both systems. This option is useful if the standby system does not have access to archive, for example, if TSM is the archive, it only allows the original machine to retrieve the files. It will also remove the possibility that the standby system would retrieve an incomplete log file while the production system is archiving a file and the standby system is retrieving the same file.
| poApplicationId
- Output. The application ID. | poNumReplies
- Output. The number of replies received. | poNodeInfo
- Output. Database partition reply information. | | nodenum
- | Node number. | | pathlen
- | The length of the new logpath. | | logpath
- | The new overflow log path. | | num_entry
- | Number of entries in the list pointed to by the tablespace | field. | | tablespace
- | A pointer to the sqlu_tablepsace_entry structure. | | reserve_len
- | Length of the character string provided in the tablespace_entry | field. For languages other than C. | | tablespace_entry
- | Table space name. | | state
- | State information. | | nextarclog
-
| A buffer to hold the returned name of the next archived log file
| required. If a caller action other than DB2ROLLFORWARD_QUERY is
| supplied, the value returned in this field indicates that an error occurred
| when accessing the file. Possible causes are:
|
- | The file was not found in the database log directory, nor on the path | specified by the overflow log path parameter
- | The user exit program failed to return the archived file. |
|
firstarcdel
-
| A buffer to hold the returned name of the first archived log file no
| longer needed for recovery. This file, and all files up to and
| including lastarcdel, can be moved to make room on the disk.
| For example, if the values returned in firstarcdel and lastarcdel are | S0000001.LOG and S0000005.LOG, the following log files can be | moved: |
- | S0000001.LOG
- | S0000002.LOG
- | S0000003.LOG
- | S0000004.LOG
- | S0000005.LOG |
|
lastarcdel
- | A buffer to hold the returned name of the last archived log file that can | be removed from the database log directory. | | lastcommit
- | A string containing a time stamp in ISO format. This value | represents the time stamp of the last committed transaction after the | rollforward operation terminates.
Usage notes
The database manager uses the information stored in the archived and the active log files to reconstruct the transactions performed on the database since its last backup.
The action performed when this API is called depends on the rollforward_pending flag of the database prior to the call. This can be queried using db2CfgGet - Get Configuration Parameters The rollforward_pending flag is set to DATABASE if the database is in roll-forward pending state. It is set to TABLESPACE if one or more table spaces are in SQLB_ROLLFORWARD_PENDING or SQLB_ROLLFORWARD_IN_PROGRESS state. The rollforward_pending flag is set to NO if neither the database nor any of the table spaces needs to be rolled forward.
If the database is in roll-forward pending state when this API is called, the database will be rolled forward. Table spaces are returned to normal state after a successful database roll-forward, unless an abnormal state causes one or more table spaces to go offline. If the rollforward_pending flag is set to TABLESPACE , only those table spaces that are in roll-forward pending state, or those table spaces requested by name, will be rolled forward.
-
Note:
- If table space rollforward terminates abnormally, table spaces that were being rolled forward will be put in SQLB_ROLLFORWARD_IN_PROGRESS state. In the next invocation of ROLLFORWARD DATABASE, only those table spaces in SQLB_ROLLFORWARD_IN_PROGRESS state will be processed. If the set of selected table space names does not include all table spaces that are in SQLB_ROLLFORWARD_IN_PROGRESS state, the table spaces that are not required will be put into SQLB_RESTORE_PENDING state.
If the database is not in roll-forward pending state and no point in time is specified, any table spaces that are in rollforward-in-progress state will be rolled forward to the end of logs. If no table spaces are in rollforward-in-progress state, any table spaces that are in rollforward pending state will be rolled forward to the end of logs.
This API reads the log files, beginning with the log file that is matched with the backup image. The name of this log file can be determined by calling this API with a caller action of | DB2ROLLFORWARD_QUERY before rolling forward any log files.
The transactions contained in the log files are reapplied to the database. The log is processed as far forward in time as information is available, or until the time specified by the stop time parameter.
Recovery stops when any one of the following events occurs:
- No more log files are found
- A time stamp in the log file exceeds the completion time stamp specified by the stop time parameter
- An error occurs while reading the log file.
Some transactions might not be recovered. The value returned in | lascommit indicates the time stamp of the last committed transaction that was applied to the database.
If the need for database recovery was caused by application or human error, the user may want to provide a time stamp value in piStopTime , indicating that recovery should be stopped before the time of the error. This applies only to full database roll-forward recovery, and to table space rollforward to a point in time. It also permits recovery to be stopped before a log read error occurs, determined during an earlier failed attempt to recover.
When the rollforward_recovery flag is set to DATABASE , the database is not available for use until roll-forward recovery is terminated. Termination is accomplished by calling the API with a caller action of | DB2ROLLFORWARD_STOP or | DB2ROLLFORWARD_RFWRD_STOP to bring the database out of roll-forward pending state. If the rollforward_recovery flag is TABLESPACE , the database is available for use. However, the table spaces in SQLB_ROLLFORWARD_PENDING and SQLB_ROLLFORWARD_IN_PROGRESS states will not be available until the API is called to perform table space roll-forward recovery. If rolling forward table spaces to a point in time, the table spaces are placed in backup pending state after a successful rollforward.
When the RollforwardFlags option is set to | DB2ROLLFORWARD_LOCAL_TIME , all messages returned to the user will also be in local time. All times are converted on the server, and on the catalog partition, if it is a partitioned database environment. The timestamp string is converted to GMT on the server, so the time is local to the server's time zone, not the client's. If the client is in one time zone and the server in another, the server's local time should be used. This is different from the local time option from the Control Center, which is local to the client. If the timestamp string is close to the time change of the clock due to daylight savings, it is important to know if the stop time is before or after the clock change, and specify it correctly.
扫一扫
3819
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
