sqlbstsc API - Set table space containers
Authorization
- SYSADM
- SYSCTRL
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.
- 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.
This sequence of actions 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).