IBM Books

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:

Required Connection

Database. This API automatically establishes a connection to the specified database.

Version

sqlutil.h

C API Syntax 



/* File: sqlutil.h */
/* API: Backup Database */
/* ... */
SQL_API_RC SQL_API_FN
  sqlubkp (
    char * pDbAlias,
    unsigned long BufferSize,
    unsigned long BackupMode,
    unsigned long BackupType,
    unsigned long CallerAction,
    char * pApplicationId,
    char * pTimestamp,
    unsigned long NumBuffers,
    struct sqlu_tablespace_bkrst_list * pTablespaceList,
    struct sqlu_media_list * pMediaTargetList,
    char * pUserName,
    char * pPassword,
    void * pReserved2,
    unsigned long VendorOptionsSize,
    void * pVendorOptions,
    unsigned long Parallelism,
    unsigned long * 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,
    unsigned long BufferSize,
    unsigned long BackupMode,
    unsigned long BackupType,
    unsigned long CallerAction,
    char * pApplicationId,
    char * pTimestamp,
    unsigned long NumBuffers,
    struct sqlu_tablespace_bkrst_list * pTablespaceList,
    struct sqlu_media_list * pMediaTargetList,
    char * pUserName,
    char * pPassword,
    void * pReserved2,
    unsigned long VendorOptionsSize,
    void * pVendorOptions,
    unsigned long Parallelism,
    unsigned long * 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 (used if zero is specified).

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 requires an S lock on objects containing LOBs.

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_ADSM_MEDIA
ADSM. 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 ADSM shared library provided with DB2 is used. If a different version of the ADSM 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.

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 ADSM [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 ADSM 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

FORTRAN
\sqllib\samples\fortran\backrest.f

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 | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]