Five functions are defined to interface DB2 and the vendor product:
DB2 will call these functions, and they should be provided by the vendor product in a shared library on UNIX based systems, or in a DLL on OS/2 or the Windows operating system.
| Note: | The shared library or DLL code will be run as part of the database engine code. Therefore, it must be reentrant and thoroughly debugged. An errant function may compromise data integrity of the database. |
The sequence of functions that DB2 will call in a specific backup or restore session depends on these factors:
DB2 supports the backup and restore of database objects using one or more data streams or sessions. A backup or restore using three sessions would require three physical or logical devices to be available. When vendor device support is being used, it is the vendor's functions that are responsible for managing the interface to each physical or logical device. DB2 simply sends or receives data buffers to or from the vendor provided functions.
The number of sessions to be used is specified as a parameter by the application that calls the backup or restore database function. This value is provided in the INIT-INPUT structure used by sqluvint (see sqluvint - Initialize and Link to Device).
DB2 will continue to initialize sessions until the specified number is reached, or it receives an SQLUV_MAX_LINK_GRANT warning return code from an sqluvint call. In order to warn DB2 that it has reached the maximum number of sessions that it can support, the vendor product will require code to track the number of active sessions. Failure to warn DB2 could lead to a DB2 initialize session request that fails, resulting in a termination of all sessions and the failure of the entire backup or restore operation.
When the operation is backup, DB2 writes a media header record at the beginning of each session. It contains information that DB2 utilizes to identify the session during a restore. DB2 uniquely identifies each session by appending a sequence number to the name of the backup. It starts at 1 (one) for the first session and is incremented by one each time another session is initiated with an sqluvint call for a backup or restore operation. For more details, see INIT-INPUT.
When the backup is successfully completed, DB2 writes a media trailer to the last session it closes. This trailer includes information that tells DB2 how many sessions were used to perform the backup. During restore, this information is used to ensure all the sessions, or data streams, have been restored.
For backup, the following sequence of calls will be issued by DB2 for each session.
sqluvint, action = SQLUV_WRITE
followed by 1 to n
sqluvput
followed by 1
sqluvend, action = SQLUV_COMMIT
When DB2 issues an sqluvend call (action SQLUV_COMMIT), it expects the vendor product to appropriately save the output data. A return code of SQLUV_OK to DB2 indicates success.
The DB2-INFO structure, used on the sqluvint call, contains the information required to identify the backup (see DB2-INFO). A sequence number is supplied. The vendor product may choose to save this information. DB2 will use it during restore to identify the backup that will be restored.
For restore, the sequence of calls for each session is:
sqluvint, action = SQLUV_READ
followed by 1 to n
sqluvget
followed by 1
sqluvend, action = SQLUV_COMMIT
The information in the DB2-INFO structure used on the sqluvint call will contain the information required to identify the backup. Sequence number is not supplied. DB2 expects that all backup objects (session outputs committed during backup) will be returned, and is not sensitive to the order in which they are restored, but does check the media tail to ensure that they have all been processed.
| Note: | Not all vendor products will keep a record of the names of the backup objects. This is most likely when the backups are being done to tapes, or other media of limited capacity. During the initialization of restore sessions, the identification information can be utilized to stage the necessary backup objects so that they are available when required; this may be most useful when juke boxes or robotic systems are used to store the backups. DB2 will always check the media header (first record in each session's output) to ensure that the correct data is being restored. |
When a backup or restore is initiated, two prompting modes are possible:
For PROMPTING mode, backup and restore define three possible user responses:
The operation of writing or reading data to the device will resume.
The device will receive no additional data and the session is terminated.
The entire backup or restore operation is terminated.
The use of the PROMPTING and WITHOUT PROMPTING modes is discussed in the sections that follow.
For the purposes of the vendor device support APIs, two general types of devices are defined:
A limited capacity device may require that the user be prompted to load additional media during the backup or restore operation. Generally DB2 is not sensitive to the order in which the media is loaded for either backup or restore. It also provides facilities to pass vendor media handling messages to the user. This prompting requires that the backup or restore operation be initiated with PROMPTING on. The media handling message text is specified in the description field of the return code structure.
If PROMPTING is on and DB2 receives an SQLUV_ENDOFMEDIA or an SQLUV_ENDOFMEDIA_NO_DATA return code from a sqluvput (write) or sqluvget (read) call, then DB2 will:
Based on the user response, DB2 will:
DB2 will not start more sessions than requested when backup or restore is started or indicated by the vendor product with a SQLUV_MAX_LINK_GRANT warning on an sqluvint.
Since the performance of backup or restore is often dependent on the number of devices being used, it is important that parallelism be maintained. For backup, users should be encouraged to respond to the prompting with a continue, unless they know that the remaining active sessions will hold the data that is still to be written out. For restore, users should use the continue response until all media has been processed or is being processed (for example, all the tapes have been read or are being read).
If the backup or restore mode is WITHOUT PROMPTING and DB2 receives an SQLUV_ENDOFMEDIA or an SQLUV_ENDOFMEDIA_NO_DATA return code from a session, it will terminate the session and not attempt to open another session. If all sessions return end-of-media to DB2 before the backup or restore is complete, then the backup or restore operation will fail. Because of this, WITHOUT PROMPTING should be used carefully with limited capacity devices. However, it makes sense to operate in this mode with very large capacity devices.
It is possible for the vendor product to hide media mounting and switching actions from DB2, so that the device appears to have infinite capacity. Some very large capacity devices operate in this mode. In these cases, it is critical that all the data that was backed up be returned to DB2 in the same order when a restore operation is in progress. Failure to do so could result in missing data, but DB2 would assume a successful restore operation, since it has no way of detecting the missing data.
DB2 writes data to the vendor product with the assumption that each buffer will be contained on one and only one media (for example, a tape). It is possible for the vendor product to split these buffers across multiple media without DB2's knowledge. In these cases, the order in which the media is processed during a restore is critical, since the vendor product will be responsible for returning reconstructed buffers from the multiple media to DB2. Failure to do so will result in a failure of the restore operation.
When performing a backup or restore operation, DB2 expects that all sessions will complete successfully, or the entire backup or restore operation fails. A session signals completed correctly (for example, committed) to DB2 with an SQLUV_OK return code on the call sqluvend, action = SQLUV_COMMIT.
If unrecoverable errors are encountered, the session will be terminated by DB2. These can be DB2 errors, or errors returned to DB2 from the vendor product. Since all sessions must commit successfully to have a complete backup or restore, the failure of one will cause DB2 to terminate the other sessions associated with the operation.
If the vendor product decides to respond to a call from DB2 with an unrecoverable return code, the vendor product can optionally provide additional information to the user using message text placed in the description field of the RETURN-CODE structure. This message text will be presented to the user along with the DB2 information, so that corrective action may be taken.
There will be backup scenarios where a session has committed successfully, and another session associated with the backup operation experiences an unrecoverable error. Since all sessions must complete successfully before a backup operation is successful, DB2 must delete the output data in the committed sessions: DB2 issues a sqluvdel call to request deletion of the object. This call is not considered an I/O session, and is responsible for initializing and terminating any connection that may be necessary to delete the backup object.
The information in the DB2-INFO structure will contain a valid sequence number during the initialization call to uniquely identify the object (committed session output) to be deleted.
It is possible for DB2 to receive warning return codes from the vendor product; for example, under the condition that a device is not ready or some other correctable condition has occurred. This is true for both read and write operations.
On the sqluvput and sqluvget calls, the vendor can set the return code to SQLUV_WARNING and optionally provide additional information to the user using message text placed in the description field of the return code structure. This message text will be presented to the user, so that corrective action may be taken. Again the user can respond in one of three ways: continue, device terminate, or terminate. The mechanism used to accomplish communication with the user is the same as for end-of-media conditions.
DB2's actions will be:
Details about possible return codes for each function call and DB2 reactions are specified in the following API sections.