Administrative API Reference

sqluvend - Unlink the Device and Release its Resources

Ends or unlinks the device, and frees all its related resources. The vendor has to free or release unused resources before returning to DB2 (for example, allocated space and file handles).

Authorization

One of the following:

• sysadm
• dbadm

Required Connection

Database

Version

sql.h

C API Syntax

/* File: sqluvend.h */ /* API: Unlink the Device and Release its Resources */ /* ... */ int sqluvend ( sqlint32 action, void * pVendorCB, struct Init_output *, struct Return_code *); /* ... */

API Parameters

action

Input. Used to commit or abort the session:

• SQLUV_COMMIT ( 0 = to commit )
• SQLUV_ABORT ( 1 = to abort )

pVendorCB

Input. Pointer to the Init_output structure.

Init_output

Output. Space for Init_output de-allocated. The data has been committed to stable storage for a backup if action is to commit. The data is purged for a backup if the action is to abort.

Return code

Output. The return code from the API call.

Usage Notes

This function will be called for each session opened.

There are two possible action codes:

• Commit

  Output of data to this session, or the reading of data from the session, is complete.

  For a write (BACKUP) session, if the vendor returns to DB2 with a return code of SQLUV_OK, DB2 will assume that the output data has been appropriately saved by the vendor's product, and can be accessed if referenced in a later sqluvint call.

  For a read (RESTORE) session, if the vendor returns to DB2 with a return code of SQLUV_OK, the data should not be deleted, because it may be needed again.

  If the vendor returns SQLUV_COMMIT_FAILED, DB2 must assume that there are problems with the entire backup or restore. All active sessions will be terminated by sqluvend calls with action = SQLUV_ABORT. For a backup operation, committed sessions will receive a sqluvint, sqluvdel, and sqluvend sequence of calls (see If Error Conditions Are Returned to DB2).

• Abort

  A problem has been encountered by DB2, and there will be no more reading of data or writing of data to the session.

  For a write (BACKUP) session, the vendor should delete the partial output dataset, and use a SQLUV_OK return code if the partial output is deleted. Also, DB2 assumes that there are problems with the entire backup. All active sessions will be terminated by sqluvend calls with action = SQLUV_ABORT, and committed sessions will receive a sqluvint, sqluvdel, and sqluvend sequence of calls (see If Error Conditions Are Returned to DB2).

  For a read (RESTORE) session, the vendor should not delete the data (because it may be needed again), but should clean up and return to DB2 with a SQLUV_OK return code. DB2 will terminate all the restore sessions by sqluvend calls with action = SQLUV_ABORT. If the vendor returns SQLUV_ABORT_FAILED to DB2, the caller will not be notified of this error, because DB2 returns the first fatal failure and ignores subsequent failures. In this case, for DB2 to have called sqluvend with action = SQLUV_ABORT, an initial fatal error must have occurred.

Return Codes

Table 86. Valid Return Codes for sqluvend and Resulting DB2 Action

Literal in Header File	Description	Probable Next Call	Other Comments
SQLUV_OK	Operation successful.	no further calls	Free all memory allocated for this session and terminate.
SQLUV_COMMIT_FAILED	Commit request failed.	no further calls	Free all memory allocated for this session and terminate.
SQLUV_ABORT_FAILED	Abort request failed.	no further calls