Administrative API Reference

sqlubkp - Backup Database

Creates a backup copy of a database or a table space.

Scope

This API only affects the node on which it is executed.

Authorization

One of the following:

sysadm
sysctrl
sysmaint

Required Connection

Database. This API automatically establishes a connection to the specified database.
Note: If a connection to the specified database already exists, it will be used for the backup operation. The connection will be terminated at the completion of the backup.

Version

sqlutil.h

C API Syntax

/* File: sqlutil.h */
/* API: Backup Database */
/* ... */
SQL_API_RC SQL_API_FN
  sqlubkp (
    char * pDbAlias,
    sqluint32     BufferSize,
    sqluint32     BackupMode,
    sqluint32     BackupType,
    sqluint32     CallerAction,
    char * pApplicationId,
    char * pTimestamp,
    sqluint32     NumBuffers,
    struct sqlu_tablespace_bkrst_list * pTablespaceList,
    struct sqlu_media_list * pMediaTargetList,
    char * pUserName,
    char * pPassword,
    void * pReserved2,
    sqluint32 VendorOptionsSize,
    void * pVendorOptions,
    sqluint32 Parallelism,
    sqluint32 * pBackupSize,
    void * pReserved4,
    void * pReserved3,
    struct sqlca * pSqlca);
/* ... */

Generic API Syntax

/* File: sqlutil.h */
/* API: Backup Database */
/* ... */
SQL_API_RC SQL_API_FN
  sqlgbkp (
    unsigned short DbAliasLen,
    unsigned short UserNameLen,
    unsigned short PasswordLen,
    unsigned short * pReserved1,
    char * pDbAlias,
    sqluint32 BufferSize,
    sqluint32 BackupMode,
    sqluint32 BackupType,
    sqluint32 CallerAction,
    char * pApplicationId,
    char * pTimestamp,
    sqluint32 NumBuffers,
    struct sqlu_tablespace_bkrst_list * pTablespaceList,
    struct sqlu_media_list * pMediaTargetList,
    char * pUserName,
    char * pPassword,
    void * pReserved2,
    sqluint32 VendorOptionsSize,
    void * pVendorOptions,
    sqluint32 Parallelism,
    sqluint32 * pBackupSize,
    void * pReserved4,
    void * pReserved3,
    struct sqlca * pSqlca);
/* ... */

API Parameters

DbAliasLen

Input. A 2-byte unsigned integer representing the length in bytes of the database alias.

UserNameLen

Input. A 2-byte unsigned integer representing the length in bytes of the user name. Set to zero if no user name is provided.

PasswordLen

Input. A 2-byte unsigned integer representing the length in bytes of the password. Set to zero if no password is provided.

pReserved1.

Reserved for future use.

pDbAlias

Input. A string containing the database alias (as cataloged in the system database directory) of the database to back up.

BufferSize

Input. Backup buffer size in 4KB allocation units (pages). Minimum is 8 units. The default is 1024 units.

BackupMode

Input. Specifies the backup mode. Valid values (defined in sqlutil) are:

SQLUB_OFFLINE

Offline gives an exclusive connection to the database.

SQLUB_ONLINE

Online allows database access by other applications while the backup operation occurs.

Note: An online backup operation may time out if there is an IX lock on sysibm.systables, because the DB2 backup utility acquires S locks on SMS LOB objects and IN locks on all other objects.

BackupType

Input. Specifies the type of backup to be taken. Valid values (defined in sqlutil) are:

SQLUB_FULL: Full database backup.
SQLUB_TABLESPACE: Table space level backup. For a table space level backup, provide a list of table spaces in the pTablespaceList parameter.

CallerAction

Input. Specifies action to be taken. Valid values (defined in sqlutil) are:

SQLUB_BACKUP: Start the backup.
SQLUB_NOINTERRUPT: Start the backup. Specifies that the backup will run unattended, and that scenarios which normally require user intervention will either be attempted without first returning to the caller, or will generate an error. Use this caller action, for example, if it is known that all of the media required for the backup have been mounted, and utility prompts are not desired.
SQLUB_CONTINUE: Continue the backup after the user has performed some action requested by the utility (mount a new tape, for example).
SQLUB_TERMINATE: Terminate the backup after the user has failed to perform some action requested by the utility.
SQLUB_DEVICE_TERMINATE: Remove a particular device from the list of devices used by backup. When a particular medium is full, backup will return a warning to the caller (while continuing to process using the remaining devices). Call backup again with this caller action to remove the device which generated the warning from the list of devices being used.
SQLUB_PARM_CHECK: Used to validate parameters without performing a backup. This option does not terminate the database connection after the call returns. After successful return of this call, it is expected that the user will issue a call with SQLUB_CONTINUE to proceed with the action.
SQLUB_PARM_CHECK_ONLY: Used to validate parameters without performing a backup. Before this call returns, the database connection established by this call is terminated, and no subsequent call is required.

pApplicationId

Output. Supply a buffer of length SQLU_APPLID_LEN+1 (defined in sqlutil). The API will return a string identifying the agent servicing the application. Can be used to obtain information about the progress of the backup operation using the database monitor.

pTimestamp

Output. Supply a buffer of length SQLU_TIME_STAMP_LEN+1 (defined in sqlutil). The API will return the time stamp of the backup image.

NumBuffers

Input. Specifies number of backup buffers to be used.

pTablespaceList

Input. List of table spaces to be backed up. Required for table space level backup only. See structure SQLU-TABLESPACE-BKRST-LIST.

pMediaTargetList

Input. This structure allows the caller to specify the destination for the backup operation. The information provided depends on the value of the media_type field. The valid values for media_type (defined in sqlutil) are:

SQLU_LOCAL_MEDIA: Local devices (a combination of tapes, disks, or diskettes). Provide a list of sqlu_media_entry structures. On OS/2 or the Windows operating system, the entries can be directory paths only, not tape device names.
SQLU_TSM_MEDIA: TSM. If an sqlu_media_entry structure is not being used to specify a path for the backup image, initialize the media pointer in the sqlu_media_list_targets structure to NULL. The TSM shared library provided with DB2 is used. If a different version of the TSM shared library is desired, use SQLU_OTHER_MEDIA and provide the shared library name.
SQLU_OTHER_MEDIA: Vendor product. Provide the shared library name in an sqlu_vendor structure.
SQLU_USER_EXIT: User exit. No additional input is required (available on OS/2 only).

For more information, see structure SQLU-MEDIA-LIST, and the Administration Guide.

pUserName

Input. A string containing the user name to be used when attempting a connection.

pPassword

Input. A string containing the password to be used with the user name.

pReserved2

Reserved for future use.

VendorOptionsSize

Input. The length of the pVendorOptions field which cannot exceed 65535 bytes.

pVendorOptions

Input. Used to pass information from the application to the vendor functions. This data structure must be flat; that is, no level of indirection is supported. Note that byte-reversal is not done, and code page is not checked for this data.

Parallelism

Input. Degree of parallelism (number of buffer manipulators).

pBackupSize

Output. Size of the backup image (in MB). Can be set to NULL.

pReserved4

Reserved for future use.

pReserved3

Reserved for future use.

pSqlca

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

REXX API Syntax

BACKUP DATABASE dbalias USING :value [USER username USING password] [TABLESPACE :tablespacenames] [ONLINE] [LOAD vendor-library [OPTIONS vendor-options] [OPEN num-sessions SESSIONS] | TO :target-area | USE TSM [OPEN num-sessions SESSIONS] | USER_EXIT] [ACTION caller-action] [WITH num-buffers BUFFERS] [BUFFERSIZE buffer-size] [PARALLELISM parallelism-degree]

REXX API Parameters

dbalias

Alias of the database to be backed up.

value

A compound REXX host variable to which the database backup information is returned. In the following, XXX represents the host variable name:

XXX.0: Number of elements in the variables (always 2)
XXX.1: The time stamp of the backup image
XXX.2: An application ID that identifies the agent that serves the application.

username

Identifies the user name under which to back up the database.

password

The password used to authenticate the user name.

tablespacenames

A compound REXX host variable containing a list of table spaces to be backed up. In the following, XXX is the name of the host variable:

XXX.0: Number of table spaces to be backed up
XXX.1: First table space name
XXX.2: Second table space name
XXX.3: and so on.

vendor-library

The name of the shared library (DLL on OS/2 or the Windows operating system) containing the vendor backup and restore I/O functions to be used. It may contain the full path. If the full path is not given, defaults to the path on which the user exit program resides.

vendor-options

Information required by the vendor functions.

num-sessions

The number of I/O sessions to be used with TSM or the vendor product.

target-area

Local devices. Allows a combination of tapes, disks or diskettes. Provide a list in SQLU-MEDIA-LIST. On OS/2 or the Windows operating system, the entries can be directory paths only, not tape device names.

caller-action

Specifies action to be taken. Valid values are:

SQLUB_BACKUP: Start the backup.
SQLUB_NOINTERRUPT: Start the backup. Specifies that the backup will run unattended, and that scenarios which normally require user intervention will either be attempted without first returning to the caller, or will generate an error. Use this caller action, for example, if it is known that all of the media required for the backup have been mounted, and utility prompts are not desired.
SQLUB_CONTINUE: Continue the backup after the user has performed some action requested by the utility (mount a new tape, for example).
SQLUB_TERMINATE: Terminate the backup after the user has failed to perform some action requested by the utility.
SQLUB_DEVICE_TERMINATE: Remove a particular device from the list of devices used by backup. When a particular medium is full, backup will return a warning to the caller (while continuing to process using the remaining devices). Call backup again with this caller action to remove the device which generated the warning from the list of devices being used.
SQLUB_PARM_CHECK: Used to validate parameters without performing a backup.

num-buffers

Number of backup buffers to be used.

buffer-size

Backup buffer size in allocation units of 4KB. Minimum is 8 units.

parallelism-degree

Number of buffer manipulators.

Sample Programs

C: \sqllib\samples\c\backrest.c
COBOL: \sqllib\samples\cobol\backrest.cbl

Usage Notes

For information about database level backup, table space level backup, online and offline backup, backup file names, and supported devices, see the Command Reference.

For a general discussion of backup, see "Recovering a Database" in the Administration Guide.

See Also

sqlemgdb - Migrate Database

sqluroll - Rollforward Database

sqlurestore - Restore Database.

[ Top of Page | Previous Page | Next Page ]