This API facilitates the provision of a redirected restore,
in which the user is restoring a database, and a different set of
operating system storage containers is desired or required. Use
this API when the table space is in a storage definition pending or
a storage definition allowed state. These states are possible during
a restore operation, immediately prior to the restoration of database
pages.
Required connection
Database
API include file
sqlutil.h
API and data structure syntax
SQL_API_RC SQL_API_FN
sqlbstsc (
struct sqlca * pSqlca,
sqluint32 SetContainerOptions,
sqluint32 TablespaceId,
sqluint32 NumContainers,
struct SQLB_TBSCONTQRY_DATA * pContainerData);
SQL_API_RC SQL_API_FN
sqlgstsc (
struct sqlca * pSqlca,
sqluint32 SetContainerOptions,
sqluint32 TablespaceId,
sqluint32 NumContainers,
struct SQLB_TBSCONTQRY_DATA * pContainerData);
sqlbstsc API parameters
- pSqlca
- Output. A pointer to the sqlca structure.
- SetContainerOptions
- Input. Use this field to specify additional options. Valid values
(defined in sqlutil) are:
- SQLB_SET_CONT_INIT_STATE
- Redo alter table space operations when performing a roll forward.
- SQLB_SET_CONT_FINAL_STATE
- Ignore alter table space operations in the log when performing
a roll forward.
- TablespaceId
- Input. Identifier for the table space which is to be changed.
- NumContainers
- Input. The number of rows the structure pointed
to by pContainerData holds. A value of 0 provided with a NULL pointer
for pContainerData indicates that the table space
is to be managed by automatic storage.
- pContainerData
- Input. Container specifications. Although the
SQLB_TBSCONTQRY_DATA structure is used, only the contType, totalPages,
name, and nameLen (for languages other than C) fields are used; all
other fields are ignored. A NULL value along with a 0 value for NumContainers indicates
that the table space is to be managed by automatic storage. This option
can also be used to provide better striping for existing automatic
storage enabled table spaces on the existing storage paths by redefining
the containers.
Note: The table space will be offline while being restored.
Usage notes
This API is used in conjunction
with db2Restore.
A backup of a database, or one or more table
spaces, keeps a record of all the table space containers in use by
the table spaces being backed up. During a restore, all containers
listed in the backup are checked to see if they currently exist and
are accessible. If one or more of the containers is inaccessible for
any reason, the restore will fail. In order to allow a restore in
such a case, the redirecting of table space containers is supported
during the restore. This support includes adding, changing, or removing
of table space containers. It is this API that allows the user to
add, change or remove those containers.
Typical use of this
API would involve the following sequence of actions:
- Invoke db2Restore with CallerAction set to DB2RESTORE_RESTORE_STORDEF.
The restore utility returns an sqlcode indicating that some of the
containers are inaccessible.
- Invoke sqlbstsc to set the table space container definitions with
the SetContainerOptions parameter set to SQLB_SET_CONT_FINAL_STATE.
- Invoke db2Restore a second time with CallerAction
set to DB2RESTORE_CONTINUE.
The above sequence will allow the restore to use the
new table space container definitions and will ignore table space
add container operations in the logs when db2Rollforward is called
after the restore is complete.
The user of this API should
be aware that when setting the container list, there must be sufficient
disk space to allow for the restore or rollforward operation to replace
all of the original data into these new containers. If there is not
sufficient space, such table spaces will be left in the recovery pending
state until sufficient disk space is made available. A prudent Database
Administrator will keep records of disk utilization on a regular basis.
Then, when a restore or rollforward operation is needed, the required
disk space will be known.
Using this API to
enable automatic storage for table spaces will cause all current containers
to be redefined to use the storage paths provided to the database.
Existing system-managed (SMS) table spaces cannot
be converted to use automatic storage.
SetContainerOptions is
ignored when a table space is being converted to use automatic storage
(NumContainers is 0, and pContainerData is
NULL).
A redirected restore of a table space
in a multi-partition environment using the
USING AUTOMATIC
STORAGE option of SET TABLESPACE CONTAINERS statement only
converts the table space to automatic storage on the partition being
restored. The containers on any other database partition are not redefined.
Note: Converting
the table space on only one of the partitions to automatic storage
as part of a redirected restore operation causes inconsistencies in
the definition of the table space. Unexpected results could also be
caused when adding new database partitions to the system or to the
database partition group. For example, if all of the database partitions
were subject to a redirected restore followed by using the USING AUTOMATIC
STORAGE option of the SET TABLESPACE CONTAINERS command,
then the table space will be converted to automatic storage on all
the database partitions. Adding another database partition later will
have the same definition for the table space as that found on the
other database partitions.