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 the logarchmeth1 database
configuration parameter or the logarchmeth2 database
configuration parameter must be set to a value other than OFF)
before the database can be recovered with rollforward recovery.
Scope
In a partitioned database environment, you must call this API
from the catalog partition. The partitions that are rolled forward
depend on what you specify in the
TO clause:
- A point-in-time rollforward call affects all database partition
servers that are listed in the db2nodes.cfg file.
- An END OF LOGS rollforward call affects the
database partition servers that are specified in the ON
DATABASE PARTITION clause. If no database partition servers
are specified, the rollforward call affects all database partition
servers that are listed in the db2nodes.cfg file.
- A database or table space rollforward call specifying end of backup
affects all database partitions servers that are listed in the db2nodes.cfg file.
If all of the transactions on a particular database partition
server have already been applied to the current database, and therefore
none of those transactions need to be rolled forward, that database
partition server is ignored.
When you roll forward a partitioned
table to a certain point in time, you must also roll forward the table
spaces that contain that table to the same point in time. However,
when you roll forward a table space, you do not have to roll forward
all the tables in that table space.
Authorization
One of the following authorities:
Required connection
None. This API establishes an exclusive database connection.
API include file
db2ApiDf.h
API and data structure syntax
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;
db2Uint32 oRollforwardFlags;
} db2RfwdOutputStruct;
SQL_STRUCTURE sqlurf_newlogpath
{
SQL_PDB_NODE_TYPE nodenum;
unsigned short pathlen;
char logpath[SQL_LOGPATH_SZ+SQL_LOGFILE_NAME_SZ+1];
};
typedef SQL_STRUCTURE sqlu_tablespace_bkrst_list
{
sqlint32 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;
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];
};
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;
typedef 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;
db2Rollforward 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.
db2RollforwardStruct data structure parameters
- piRfwdInput
- Input. A pointer to the db2RfwdInputStruct structure.
- poRfwdOutput
- Output. A pointer to the db2RfwdOutputStruct structure.
db2RfwdInputStruct data structure parameters
- 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 header
file, located in the include directory) are:
- DB2ROLLFORWARD_ROLLFWD
- Rollforward to the point in time specified by the piStopTime parameter.
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 rollforward recovery by rolling forward the database using
available log files and then rolling it back. Uncommitted transactions
are backed out and the rollforward-pending state of the database or
table spaces is turned off. A synonym for this value is DB2ROLLFORWARD_RFWD_COMPLETE.
- DB2ROLLFORWARD_RFWD_STOP
- Rollforward to the point in time specified by piStopTime,
and end rollforward recovery. The rollforward-pending state of the
database or table spaces is turned off. A synonym for this value 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. Can
be NULL.
- piPassword
- Input. A string containing the password of the supplied user name
(if any). Can 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 database 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 rollforward 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 header
file, located in the include directory) are:
- DB2ROLLFORWARD_OFFLINE
- Offline roll forward. This value must be specified for database
rollforward 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.
For partitioned tables, point in time (PIT) rollforward
of a table space containing any piece of a partitioned table must
also roll forward all of the other table spaces in which that table
resides to the same point in time. Roll forward to the end of the
logs for a single table space containing a piece of a partitioned
table is still allowed.
If a partitioned table has any attached,
detached or dropped data partitions, then PIT rollforward must include
all table spaces for these data partitions as well. To determine if
a partitioned table has any attached, detached, or dropped data partitions,
query the Status field of the SYSDATAPARTITIONS catalog table.
Because
a partitioned table can reside in multiple table spaces, it is generally
necessary to roll forward multiple table spaces. Data that is recovered
via dropped table recovery is written to the export directory specified
in the piExportDir parameter. It is possible
to roll forward all table spaces in one command, or do repeated rollforward
operations for subsets of the table spaces involved. A warning will
be written to the notify log if the db2Rollforward API
did not specify the full set of the table spaces necessary to recover
all the data for the table. A warning will be returned to the user
with full details of all partitions not recovered on the command found
in the administration notification log.
Allowing the roll forward
of a subset of the table spaces makes it easier to deal with cases
where there is more data to be recovered than can fit into a single
export directory.
- 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. This is the default value.
The piNodeList parameter must be set to NULL,
if this value is used.
- 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. The piNodeList parameter
must be set to NULL, if this value is used.
- 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.
- piDroppedTblID
- Input. A string containing the ID of the dropped table whose recovery
is being attempted. For partitioned tables, the drop-table-id identifies
the table as a whole, so that all data partitions of the table can
be recovered in a single rollforward command.
- piExportDir
- Input. The name of the directory into which the dropped table
data will be exported.
- iRollforwardFlags
- Input. Specifies the rollforward flags. Valid values (defined
in db2ApiDf header file, located in the include
directory) are:
- 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.
- DB2ROLLFORWARD_END_OF_BACKUP
- Specifies that the database should be rolled forward to the minimum
recovery time.
db2RfwdOutputStruct data structure parameters
- poApplicationId
- Output. The application ID.
- poNumReplies
- Output. The number of replies received.
- poNodeInfo
- Output. Database partition reply information.
- oRollforwardFlags
- Output. Rollforward output flags. Valid values are:
- DB2ROLLFORWARD_OUT_LOCAL_TIME
- Indicates to user that the last committed transaction timestamp
is displayed in local time rather than UTC. Local time is based on
the server's local time, not on the client's. In a partitioned database
environment, local time is based on the catalog partition's local
time.
sqlurf_newlogpath data structure parameters
- nodenum
- Input. The number of the database partition that this structure
details.
- pathlen
- Input. The total length of the logpath field.
- logpath
- Input. A fully qualified path to be used for a specific node for
the rollforward operation.
sqlu_tablespace_bkrst_list data structure parameters
- num_entry
- Input. The number of structures contained in the list pointed
to by the table space parameter.
- tablespace
- Input. A pointer to a list of sqlu_tablespace_entry structures.
sqlu_tablespace_entry data structure parameters
- reserve_len
- Input. Specifies the length in bytes of the tablespace_entry parameter.
- tablespace_entry
- Input. The name of the table space to rollforward.
- filler
- Filler used for proper alignment of data structure in memory.
sqlurf_info data structure parameters
- nodenum
- Output. The number of the database partition that this structure
contains information for.
- state
- Output. The current state of the database or table spaces that
were included in the rollforward on a database partition.
- nextarclog
- Output. If the rollforward has completed, this field will be empty.
If the rollforward has not yet completed, this will be the name of
the next log file which will be processed for the rollforward.
- firstarcdel
- Output. The first log file replayed by the rollforward.
- lastarcdel
- Output. The last log file replayed by the rollforward.
- lastcommit
- Output. The time of the last committed transaction.
db2gRfwdInputStruct data structure specific parameters
- 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.
- iDroppedTblIDLen
- Input. Specifies the length in bytes of the dropped table ID (piDroppedTblID parameter).
Set to zero if no dropped table ID is provided.
- iExportDirLen
- Input. Specifies the length in bytes of the dropped table export
directory (piExportDir parameter). Set to zero
if no dropped table export directory is provided.
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 before the call. This can be queried using db2CfgGet -
Get Configuration Parameters. The rollforward_pending flag is set
to DATABASE if the database is in rollforward 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 rollforward pending
state when this API is called, the database will be rolled forward.
Table spaces are returned to normal state after a successful database
rollforward, 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 rollforward 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 rollforward 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 lastcommit 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 rollforward 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
rollforward 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 rollforward 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 rollforward 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. 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.