Administrative API Reference

sqlbstsc - Set Tablespace 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:

Required Connection

Database

Version

sqlutil.h

C API Syntax 



/* File: sqlutil.h */
/* API: Set Tablespace Containers */
/* ... */
SQL_API_RC SQL_API_FN
  sqlbstsc (
    struct sqlca * pSqlca,
    sqluint32 SetContainerOptions,
    sqluint32 TablespaceId,
    sqluint32 NumContainers,
    struct SQLB_TBSCONTQRY_DATA * pContainerData);
/* ... */

Generic API Syntax 



/* File: sqlutil.h */
/* API: Set Tablespace Containers */
/* ... */
SQL_API_RC SQL_API_FN
  sqlgstsc (
    struct sqlca * pSqlca,
    sqluint32 SetContainerOptions,
    sqluint32 TablespaceId,
    sqluint32 NumContainers,
    struct SQLB_TBSCONTQRY_DATA * pContainerData);
/* ... */

API Parameters

pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

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.

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.

Sample Programs

C
\sqllib\samples\c\backrest.c

COBOL
\sqllib\samples\cobol\backrest.cbl

Usage Notes

This API is used in conjunction with sqlurestore - Restore Database.

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. For more information, see the Administration Guide.

Typical use of this API would involve the following sequence of actions:

  1. Invoke sqlurestore - Restore Database with CallerAction set to SQLUD_RESTORE_STORDEF.

    The restore utility returns an sqlcode indicating that some of the containers are inaccessible.

  2. Invoke sqlbstsc to set the table space container definitions with the SetContainerOptions parameter set to SQLB_SET_CONT_FINAL_STATE.
  3. Invoke sqlurst a second time with CallerAction set to SQLUD_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 sqluroll - Rollforward Database 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.

See Also

sqlubkp - Backup Database

sqluroll - Rollforward Database

sqlurestore - Restore Database.

[ Top of Page | Previous Page | Next Page ]