sqluvend API - Unlink a vendor device and release its resources

Unlinks a vendor device and frees all of its related resources. All unused resources (for example, allocated space and file handles) must be released before the sqluvend API call returns to Db2®.

Authorization

None

Required connection

Database

API include file

sqluvend.h

API and data structure syntax

int sqluvend ( sqlint32             action,
               void *hdle,
               struct Init_output *in_out,
               struct Return_code *return_code);

sqluvend API parameters

action

Input. Used to commit or abort the session:

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

hdle

Input. Pointer to the Init_output structure.

in_out

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 API is called for each session that has been 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 assumes that the output data has been appropriately saved by the vendor 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 assumes that there are problems with the entire backup or restore operation. All active sessions are terminated by sqluvend calls with action = SQLUV_ABORT. For a backup operation, committed sessions receive a sqluvint, sqluvdel, and sqluvend sequence of calls.

Abort

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

For a write (backup) session, the vendor should delete the partial output data set, and use a SQLUV_OK return code if the partial output is deleted. Db2 assumes that there are problems with the entire backup. All active sessions are terminated by sqluvend calls with action = SQLUV_ABORT, and committed sessions receive a sqluvint, sqluvdel, and sqluvend sequence of calls.

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 terminates all the restore sessions by sqluvend calls with action = SQLUV_ABORT.

If the vendor returns SQLUV_ABORT_FAILED to Db2, the caller is not 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 1. 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