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

Last Published:
Product(s): NetBackup (8.2, 8.1.2)
  1. Introduction to NetBackup XBSA
    1.  
      About Introduction to NetBackup XBSA
    2.  
      What is NetBackup XBSA?
    3.  
      What does NetBackup XBSA do?
    4.  
      Terminology
    5.  
      Important concepts
    6.  
      Resources
  2. How to set up the SDK
    1.  
      System requirements
    2. Installing the SDK
      1.  
        Installation requirements
      2.  
        Installation instructions for UNIX platforms
      3.  
        Installation instructions for Windows platforms
    3.  
      Uninstalling the SDK
    4.  
      Configuration
    5.  
      Description of the XBSA SDK package
    6.  
      Library files
    7.  
      Header files
  3. Using the NetBackup XBSA interface
    1.  
      Getting help with the API
    2. NetBackup XBSA data structures
      1.  
        Object data
      2.  
        Object descriptors
      3.  
        Query descriptors
      4. Buffers
        1.  
          Buffer size
        2.  
          Private buffer space
        3.  
          Use of BSA_DataBlock32 in BSASendData()
        4.  
          Use of BSA_DataBlock32 in BSAGetData()
        5.  
          Shared memory
    3. NetBackup XBSA environment
      1.  
        Environment variable definitions
      2.  
        Extended environment variable definitions
    4. XBSA sessions and transactions
      1. Sessions
        1.  
          Initialization and termination
        2.  
          Authentication
      2. Transactions
        1.  
          Backup transaction
        2.  
          Restore transaction
        3.  
          Delete transaction
        4.  
          Query transaction
        5.  
          Media IDs transaction
    5. Creating a NetBackup XBSA application
      1. Initiating a session
        1.  
          Modifying the XBSA environment within a session
        2.  
          Session example
      2. Backup - creating an object
        1.  
          Creating an object
        2.  
          NetBackup object ownership
        3.  
          Creating an empty object
        4.  
          Backup example
      3. Query - finding an object descriptor
        1.  
          Querying for an object
        2.  
          Query example
      4. Restore - retrieving an object's data
        1.  
          Restoring an object
        2.  
          Redirected restore to a different client
        3.  
          Restore example
        4.  
          Multiple object restore
        5.  
          Multiple object restore example
      5. Delete - deleting an object or image
        1.  
          Delete example
      6. Media IDs - obtaining media IDs
        1.  
          Media ID example
      7.  
        Logging and NetBackup
      8.  
        Client in a cluster
      9.  
        Performance considerations
  4. How to build an XBSA application
    1.  
      Getting help
    2.  
      Flags and defines
    3.  
      How to build in debug mode
    4.  
      How to debug the application
    5.  
      Static libraries
    6.  
      Dynamic libraries
    7.  
      End-user configuration
  5. How to run a NetBackup XBSA application
    1. About How to run a NetBackup XBSA application
      1. Creating a NetBackup policy
        1.  
          Selecting a storage unit
        2.  
          Adding new schedules
        3.  
          Adding script files to the files list
        4.  
          Adding new clients
      2.  
        Running a NetBackup XBSA application
      3.  
        Backups and restores initiated by NetBackup (through a script)
      4.  
        Backups and restores from the command line
  6. API reference
    1.  
      Error messages
    2. Function calls
      1.  
        Conventions
    3. Function specifications
      1.  
        BSABeginTxn
      2.  
        BSACreateObject
      3.  
        BSADeleteObject
      4.  
        BSAEndData
      5.  
        BSAEndTxn
      6.  
        BSAGetData
      7.  
        BSAGetEnvironment
      8.  
        BSAGetLastError
      9.  
        BSAGetNextQueryObject
      10.  
        BSAGetObject
      11.  
        BSAInit
      12.  
        BSAQueryApiVersion
      13.  
        BSAQueryObject
      14.  
        BSAQueryServiceProvider
      15.  
        BSASendData
      16.  
        BSATerminate
      17.  
        NBBSAAddToMultiObjectRestoreList
      18.  
        NBBSADeleteImage
      19.  
        NBBSAEndGetMultipleObjects
      20.  
        NBBSAFreeJobInfo
      21.  
        NBBSAGetEnv
      22.  
        NBBSAGetErrorString
      23.  
        NBBSAGetJobId
      24.  
        NBBSAGetJobInfo
      25.  
        NBBSAGetMediaIds
      26.  
        NBBSAGetMultipleObjects
      27.  
        NBBSAGetServerError
      28.  
        NBBSALogMsg
      29.  
        NBBSASetEnv
      30.  
        NBBSAUpdateEnv
      31.  
        NBBSAValidateFeatureId
    4. Type definitions
      1. Enumerated types
        1.  
          BSA_CopyType
        2.  
          BSA_ObjectStatus
        3.  
          BSA_ObjectType
        4.  
          BSA_Vote
        5.  
          Constant values
      2. Data structures
        1.  
          BSA_ApiVersion
        2.  
          BSA_DataBlock32
        3.  
          BSA_ObjectDescriptor
        4.  
          BSA_ObjectName
        5.  
          BSA_ObjectOwner
        6.  
          BSA_QueryDescriptor
        7.  
          BSA_SecurityToken
  7. Process flow and troubleshooting
    1.  
      About Process flow and troubleshooting
    2. Backup
      1. Stream backup process flow description
        1.  
          Stream backup procedure
    3. Restore
      1. Stream restore process flow description
        1.  
          Stream restore procedure
  8. How to use the sample files
    1. What the sample files do
      1. Sample programs
        1.  
          Backup
        2.  
          Restore
        3.  
          Query
        4.  
          Delete
      2.  
        Sample scripts
    2.  
      Description of sample files
    3.  
      How to build the sample programs
  9. Support and updates
    1.  
      About Support and updates
  10. Appendix A. Register authorized locations
    1.  
      Registering authorized locations used by a NetBackup database script-based policy

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.

More Information

Buffers