DB2 Version 9.7 for Linux, UNIX, and Windows

sqlbstsc API - Set table space containers

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.

Authorization

One of the following:

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.

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.