Db2 call sequence for vendor APIs

APIs are defined to provide a data interface between Db2 and the vendor product.

The sequence of APIs that Db2 will call during a specific backup or restore operation depends on:
  • The number of sessions that will be utilized.
  • Whether it is a backup, a restore, a log archive, or a log retrieve operation.
  • The PROMPTING mode that is specified on the backup or restore operation.
  • The characteristics of the vendor device on which the data is stored.
  • The errors that may be encountered during the operation.

Number of sessions

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 APIs 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 APIs.

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 the sqluvint API.

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 Db2initialize 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. The record contains information that Db2 uses to identify the session during a restore operation. Db2 uniquely identifies each session by appending a sequence number to the name of the backup image. The number starts at one for the first session, and is incremented by one each time another session is initiated with an sqluvint call for a backup or a restore operation.

When the backup operation completes successfully, 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 operation. During a restore operation, this information is used to ensure all the sessions, or data streams, have been restored.

Operation with no errors, warnings, or prompting

For backing up an image to a vendor device, the following sequence of calls is issued by Db2 for each session: 
   db2VendorQueryApiVersion
followed by 1 
   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. 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.

Note: For backing up a log file to a vendor device, use action = SQLUV_ARCHIVE with the sqluvint call.
For restoring an image from a vendor device, the sequence of calls for each session is: 
   db2VendorQueryApiVersion
followed by 1 
   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. A sequence number is not supplied. Db2 expects that all backup objects (session outputs committed during a backup) will be returned. The first backup object returned is the object generated with sequence number 1, and all other objects are restored in no specific order. Db2 checks the media tail to ensure that all objects have been processed.

Note: For restoring a log file from a vendor device, use action = SQLUV_RETRIEVE with the sqluvint call.
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.
For searching a vendor device for an image or archived log file, the following sequence of calls is issued by Db2 for each session: 
   sqluvint, action = SQLUV_QUERY_IMAGES or SQLUV_QUERY_LOGS
followed by 1 to n 
   db2VendorGetNextObj
followed by 1 
   sqluvend, action = SQLUV_COMMIT

Prompting mode

When a backup or a restore operation is initiated, two prompting modes are possible:
  • WITHOUT PROMPTING or NOINTERRUPT, where there is no opportunity for the vendor product to write messages to the user, or for the user to respond to them.
  • PROMPTING or INTERRUPT, where the user can receive and respond to messages from the vendor product.
For PROMPTING mode, backup and restore define three possible user responses:
  • Continue

    The operation of reading or writing data to the device will resume.

  • Device terminate

    The device will receive no additional data, and the session is terminated.

  • Terminate

    The entire backup or restore operation is terminated.

The use of the PROMPTING and WITHOUT PROMPTING modes is discussed in the sections that follow.

Device characteristics

For purposes of the vendor device support APIs, two general types of devices are defined:
  • Limited capacity devices requiring user action to change the media; for example, a tape drive, diskette, or CDROM drive.
  • Very large capacity devices, where normal operations do not require the user to handle media; for example, a juke box, or an intelligent robotic media handling device.

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 operations. 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 a sqluvget (read) call, Db2:

  • Marks the last buffer sent to the session to be resent, if the call was sqluvput. It will be put to a session later.
  • Calls the session with sqluvend (action = SQLUV_COMMIT). If successful (SQLUV_OK return code), Db2:
    • Sends a vendor media handling message to the user from the return code structure that signaled the end-of-media condition.
    • Prompts the user for a continue, device terminate, or terminate response.
  • If the response is continue, Db2 initializes another session using the sqluvint call, and if successful, begins writing data to or reading data from the session. To uniquely identify the session when writing, Db2 increments the sequence number. The sequence number is available in the DB2-INFO structure used with sqluvint, and is in the media header record, which is the first data record sent to the session.

    Db2 will not start more sessions than requested when a backup or a restore operation is started, or indicated by the vendor product with a SQLUV_MAX_LINK_GRANT warning on an sqluvint call.

  • If the response is device terminate, Db2 does not attempt to initialize another session, and the number of active sessions is reduced by one. Db2 does not allow all sessions to be terminated by device terminate responses; at least one session must be kept active until the backup or restore operation completes.
  • If the response is terminate, Db2 terminates the backup or restore operation.

Because backup or restore performance is often dependent on the number of devices being used, it is important that parallelism be maintained. For backup operations, users are encouraged to respond with a continue, unless they know that the remaining active sessions will hold the data that is still to be written out. For restore operations, users are also encouraged to respond with a continue until all media have been processed.

If the backup or the 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 the restore operation is complete, the operation will fail. Because of this, WITHOUT PROMPTING should be used carefully with limited capacity devices; it does, however, make 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 assumes a successful restore operation, because 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 the knowledge of Db2. In this case, the order in which the media is processed during a restore operation is critical, because the vendor product will be responsible for returning reconstructed buffers from the multiple media to Db2. Failure to do so will result in a failed restore operation.

If error conditions are returned to Db2

When performing a backup or a restore operation, Db2 expects that all sessions will complete successfully; otherwise, the entire backup or restore operation fails. A session signals successful completion to Db2 with an SQLUV_OK return code on the sqluvend call, action = SQLUV_COMMIT.

If unrecoverable errors are encountered, the session is terminated by Db2. These can be Db2 errors, or errors returned to Db2 from the vendor product. Because all sessions must commit successfully to have a complete backup or restore operation, the failure of one causes Db2 to terminate the other sessions associated with the operation.

If the vendor product responds to a call from Db2 with an unrecoverable return code, the vendor product can optionally provide additional information, using message text placed in the description field of the RETURN-CODE structure. This message text is presented to the user, along with the Db2 information, so that corrective action can be taken.

There will be backup scenarios in which a session has committed successfully, and another session associated with the backup operation experiences an unrecoverable error. Because all sessions must complete successfully before a backup operation is considered 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 DB2-INFO structure will not contain a sequence number; sqluvdel will delete all backup objects that match the remaining parameters in the DB2-INFO structure.

Warning conditions

It is possible for Db2 to receive warning return codes from the vendor product; for example, if a device is not ready, or some other correctable condition has occurred. This is true for both read and write operations.

On sqluvput and sqluvget calls, the vendor can set the return code to SQLUV_WARNING, and optionally provide additional information, using message text placed in the description field of the RETURN-CODE structure. This message text is presented to the user so that corrective action can be taken. The user can respond in one of three ways: continue, device terminate, or terminate:

  • If the response is continue, Db2 attempts to rewrite the buffer using sqluvput during a backup operation. During a restore operation, Db2 issues an sqluvget call to read the next buffer.
  • If the response is device terminate or terminate, Db2 terminates the entire backup or restore operation in the same way that it would respond after an unrecoverable error (for example, it will terminate active sessions and delete committed sessions).