NetBackup™ DataStore SDK Programmer's Guide for XBSA 1.1.0

Creating an object

An object descriptor defines an XBSA object. The XBSA application defines the attributes of the object so that the application knows how to restore the object. For example, if the XBSA application wants to implement an incremental type of backup, sufficient information needs to be kept in the object descriptor to identify if the object is full or incremental and any other information that is required to restore the object.

The following fields of an object descriptor are user-defined and need to be defined by the XBSA application before the descriptor is passed to BSACreateObject().

See Object descriptors. for more definitions of the BSA_ObjectDescriptor.

The fields that are defined as strings can be empty strings, except for the pathName, which must have a valid path. The fields that are enumerations cannot have the ANY value. The estimatedSize field must have a value greater than zero if the object has data and zero if there is no data. It is good practice to have the estimated size field be as accurate as possible, but it does not affect how NetBackup stores the object.

The following are the required BSA.ObjectDescriptor fields:

objectOwner
   bsa_objectOwner
   app_objectOwner
objectName
   pathName
   objectSpaceName
copyType
resourceType
objectType
objectDescription
estimatedSize
objectInfo

The NetBackup XBSA interface populates the other fields in the object descriptor.

The other structure that is required before creating an object is the BSA_DataBlock32 structure. The structure does not need to be populated because BSACreateObject() populates the select fields with values that define how the data needs to be passed in buffers.

for more information.

Those are the two parameters to BSACreateObject(). The BSACreateObject() function creates the object and prepares NetBackup to be able to accept data. This includes mounting a tape if that is required. When BSACreateObject() has successfully created the object and returns, the object descriptor has the copyId field populated. This is the unique identifier that is associated with this object. If the XBSA application is going to keep any information about an object in an application catalog, this copyId should be a key value. It can be used to restore or delete this object.

There are four environmental variables that are created during BSACreateObject(). These are NBBSA_CLIENT_READ_TIMEOUT, NBBSA_MEDIA_MOUNT_TIMEOUT, NBBSA_MULTIPLEXING, and NBBSA_SERVER_BUFFSIZE. These variables are part of the NetBackup configuration and can be used to determine if the XBSA application is successful. The NBBSA_CLIENT_READ_TIMEOUT and NBBSA_MEDIA_MOUNT_TIMEOUT values can be reset by the XBSA application if it knows it needs to override the default NetBackup configuration.

NBBSA_CLIENT_READ_TIMEOUT is the amount of time, in seconds, the NetBackup server waits for data to be received. If the time between when the NetBackup server starts the backup and the time the transmission of data starts exceeds this time-out value, the backup job fails. This ensures that a hung or failed process on the client does not cause the job to wait, and take up resources, indefinitely. If the XBSA application knows that it takes longer than this to prepare the data to be sent, reset this value to a higher value.

NBBSA_MEDIA_MOUNT_TIMEOUT is the amount of time the NetBackup client waits for the media to be mounted. If the time between when the NetBackup server starts the backup and the time the media is mounted exceeds this time-out value, the XBSA interface returns a fail condition.

NBBSA_MULTIPLEXING is the number of streams that can be accepted by NetBackup. This value cannot be changed, but if the XBSA application is processing multiple streams, it should be evaluated to ensure that NetBackup accepts all of the streams that are being sent.

NBBSA_SERVER_BUFFSIZE is the size configured for NET_BUFF_SZ. This value cannot be changed but, if the XBSA application has the ability to modify the size of the buffers it uses, these could be modified to enhance performance of the transfer of data.

If everything is OK so far, data can be sent to the NetBackup XBSA interface by buffers by BSASendData(). The buffers are defined by the BSA_DataBlock32 structure. The key fields to set are the numBytes, which contains the number of bytes being sent, bufferLen, which contains the length of the buffer in bytes, and bufferPtr, which is a pointer to the buffer. The number of bytes must equal the buffer length except for the last buffer, which can be only partially full. BSASendData() can be called any number of times to pass all the data from an object.

Once all data has been sent, BSAEndData() must be called to signal to the NetBackup XBSA interface that the object is complete.

If multiple objects are to be created, this whole process can be repeated multiple times. The most efficient way to create multiple objects is to repeat this within one transaction. It is also possible to create multiple objects by creating one object per transaction and doing multiple transactions.

Once all objects for a transaction have been created, the transaction is completed with BSAEndTxn(). BSAEndTxn() can either commit or abort the transaction. If the transaction is aborted, all objects that were created in the transaction are not saved. If the transaction is committed, the object(s) are saved in the NetBackup catalog and can at a future point be restored. The BSATerminate() function also acts as an abort to the transaction.