Search <book_title>...

Veritas NetBackup™ DataStore SDK Programmer's Guide for XBSA 1.1.0

Last Published: 2018-09-19

Product(s): NetBackup (8.2, 8.1.2)

Multiple object restore

If multiple objects are going to be restored in one session or transaction, the XBSA agent should consider using the NBBSAGetMultipleObjects function call. This is a NetBackup extension to the XBSA interface to optimize the retrieval of objects in a NetBackup environment. This is especially useful when retrieving many small objects.

The reason this provides a performance improvement is that each NetBackup restore operation creates a NetBackup job, which acquires resources and then frees them up when the job is complete. Each BSAGetObject call translates into one NetBackup job. The initial time required to start a NetBackup job and establish communication are minimal, especially when compared to the time to transfer large amounts of data. But if the objects are small and numerous, this overhead per object is noticeable. It is also possible on heavily loaded NetBackup systems that successive BSAGetObject calls may get queued up behind other NetBackup jobs and resource requests. Any of these could cause performance issues if the separate objects are all part of one restore.

To address this behavior of NetBackup, we have added a multiple object restore interface to the XBSA interface. This is an extension of the XBSA specification to enhance performance for the NetBackup XBSA applications. The use of this interface is not required and does not provide functionality on objects that are not available through the interfaces defined by XBSA.

Requirements

To do a multiple object restore, the XBSA application needs to have created the objects in ways that allow this and there are restrictions on how the objects can be retrieved.
All of the objects that are to be restored within a multiple object restore must be part of the same NetBackup image, which means that the objects were created in one transaction. This can be verified by checking that each object being restored has the same copyId.left.
The objects must be retrieved in the same order that they were created. Some objects in the image can be skipped, but the objects being retrieved must be ordered in a way that do not cause the media to have to position backwards. The ordering of objects can be determined by verifying that the copyId.right for each object is in ascending order.
While not all objects in an image need to be retrieved, all objects in the list created by NBBSAAddToMultiObjectRestoreList must be retrieved in the order in which they are listed. Objects cannot be skipped or added.
Each object in the list is retrieved with BSAGetObject followed by successive BSAGetData calls to retrieve all of the data. All of the data for an object must be retrieved before moving on to the next object.

Functions and use

There are three new functions provided as part of the XBSA interface that can be used to do multiple object restores.

NBBSAAddToMultiObjectRestoreList takes an object descriptor and it to a descriptor list. This function is called for each object that is to be retrieved as part of one restore job. It is highly recommended to use this function to create the list because it allows the XBSA interface to be in charge of memory allocation and deletion.
NBBSAGetMultipleObjects starts the multiple object restore job. It takes the list of descriptors built by NBBSAAddToMultiObjectRestoreList and submits a request to restore all objects.
NBBSAEndGetMultipleObjects ends the multiple object restore job. This function cleans up the memory from the object list and allows the application to COMMIT or ABORT the restore, which has no real effect on the data.

The process is very similar to the single object restores. First, all objectDescriptors to be retrieved are added to a list using the NBBSAAddToMultiObjectRestoreList. The objectDescriptors can be generated from BSAQueryObject or populated by the application. Once the list is ready, a call to NBBSAGetMultipleObjects initiates the restore process. Then, each object is retrieved using the standard BSAGetObject, BSAGetData, and BSAEndData function calls. The difference is that BSAGetObject knows it is part of a larger restore job. After all objects have been retrieved, NBBSAEndGetMultipleObjects is called to end the restore process. The transaction can then be ended. If an object is skipped or not all data is retrieved, the entire job fails.