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

Restoring an object

When restoring an XBSA object, the logon user must be the owner of the XBSA object or a root admin. (The owner of an object is the logon user of the process that created the object.) If a different user tries to restore the object, the NetBackup XBSA interface returns a BSA_RC_OBJECT_NOT_FOUND error. This error could also be returned if the host on which the restore is being done is different from the host which backed up the object.

See Redirected restore to a different client.

The XBSA application is responsible for recreating the object. The NetBackup XBSA interface sends a stream of data to the XBSA application. It is up to the XBSA application to ensure that the correct permissions exist for restoring the object, recreating all attributes, and so on. If any of these attributes are stored in the object descriptor of the XBSA object, the object descriptor needs to be retrieved with a BSAQueryObject() call. The call to BSAGetObject() does not populate the object attributes.

To restore an XBSA object, the NetBackup XBSA interface needs to have an object descriptor that contains the copyId of the object being restored. This copyId can be obtained from either a query process or from information stored by the XBSA application. It is permissible to mix query operations in a restore transaction.

The other structure that is required before restoring an object is the BSA_DataBlock32 structure. The structure does not need to be populated as BSAGetObject() populates select fields with values that define how the data buffers are used.

See Buffers.

The restore is initiated with a call to BSAGetObject() with this object descriptor and data block as parameters. This function starts the process of retrieving the object. If BSAGetObject() returns with good status, BSAGetData() can retrieve the object data from the NetBackup XBSA interface by buffers. The buffers are defined by the BSA_DataBlock32 structure. It is the responsibility of the XBSA application to allocate the buffers. BSAGetObject() fills the buffers with data and sets the numBytes field of the BSA_DataBlock32 with the number of bytes in the buffer. When the last buffer of data for the object has been passed, BSAGetObject() returns BSA_NO_MORE_DATA. BSAEndData() should then be called to signal to the NetBackup XBSA interface that the object is restored and that it can free up the resources. The NetBackup XBSA interface requires that all data for an object is retrieved or the return status of the NetBackup server would be an error status. This does not affect the XBSA application, but may affect how a user of the application interprets the results of the restore.

After the object(s) have been restored, the transaction should be closed. From the NetBackup XBSA interface point of view, a committed or aborted transactions are handled the same, as there is nothing for NetBackup to commit.