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

Last Published:
Product(s): NetBackup (8.0)
  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 (via 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

BSACreateObject

Create an XBSA object.

SYNOPSIS

#include <xbsa.h>

int BSACreateObject(BSA_Handle bsaHandle, BSA_ObjectDescriptor *objectDescriptorPtr, BSA_DataBlock32 *dataBlockPtr)

DESCRIPTION

The BSACreateObject() call creates an XBSA object within NetBackup. Duplicate BSA_ObjectNames are allowed.

The BSACreateObject() call is used to create an XBSA object based on the information in the objectDescriptor. This call initiates the communication between the NetBackup XBSA interface and the NetBackup server. The XBSA object data can then be passed in memory buffers. The dataBlockPtr parameter in the BSACreateObject() call allows the caller to obtain information about the buffer structure required by the NetBackup XBSA interface.

The XBSA object data is passed through one or more BSASendData() calls. If there is no data to be sent, then a BSAEndData() call must be used to indicate completion of the XBSA object. The BSASendData() and BSAEndData() calls must follow the BSACreateObject() call and must be in the same transaction.

PARAMETERS

BSA_Handle bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_ObjectDescriptor *objectDescriptorPtr (I/O)

This parameter is used to pass XBSA object attributes, including its name, copy type, and so on.

BSA_DataBlock32 *dataBlockPtr (O)

This parameter is a pointer to a structure that is used to obtain the details of the required buffer structure.

EXTENDED DESCRIPTION

Within the XBSA object descriptor, all fields must contain valid values. Enumerations must contain one of their enumerated values. Strings must be null-terminated. All other fields must be in the range of valid values for that field.

The following fields in the XBSA object descriptor are optional: objectOwner, objectDescription, and objectInfo. The optional value for either field of objectOwner and the field objectDescription is the empty string. The optional value for objectInfo is all zeros. If the bsa_ObjectOwner is empty it will default to the value specified in BSAInit().

Note:

For NetBackup XBSA Version 1.1.0, the NetBackup XBSA interface and NetBackup determine the XBSA object ownership. If the bsa_ObjectOwner field is specified, it will be saved with the object but will not define ownership.

The following fields in the XBSA object descriptor are mandatory: objectName, copyType, estimatedSize, resourceType, and objectType. For objectName this means that the pathName must contain a non-empty string. For copyType and objectType the enumeration value "ANY" is not allowed.

The estimatedSize must contain a non-zero estimate if the XBSA application intends to create a non-empty XBSA object (that is, there will be XBSA object data). This size is in bytes. If the estimatedSize is zero, this call must be followed by a BSAEndData() without calling BSASendData() in between. There are no resource allocations based on this estimate, only whether the object will have data or not, so the estimate does not need to be accurate.

The NetBackup XBSA interface may return several values to the XBSA application through the objectDescriptorPtr for a newly created XBSA object. The interface returns either all or none of these values.

The copyId attribute is a persistent, fixed-length object identifier that remains unchanged throughout the life of the XBSA object.

Note:

For NetBackup XBSA Version 1.1.0, the copyId is only guaranteed to be unique on a given NetBackup master server.

If the copyId field is non-zero, the NetBackup XBSA interface returned values for the copyId, createTime, restoreOrder, and objectStatus fields.

The createTime field is in UTC. The restoreOrder field can have the value zero, which means that the NetBackup XBSA interface did not specify a restore order.

The dataBlockPtr structure does not point to an actual data buffer. All values in the dataBlockPtr should be zero, and will be overwritten. The structure is used by the NetBackup XBSA interface to provide the XBSA application with the interface preference for the structure of the data blocks that will be used to pass the NetBackup XBSA object's data. The XBSA application should examine the values returned in order to determine the buffer structure that it should create. The significance of the returned values is as follows:

bufferLen == 0

NetBackup has no restrictions on the buffer length. No trailer portion is required.

bufferLen != 0

NetBackup accepts buffers that are at least bufferLen bytes in length (minimum length). The length of the trailer portion of buffers is: trailerBytes >= (bufferLen - numBytes - headerBytes)

numBytes == 0

NetBackup has no restrictions on the length of the data portion of the buffer.

numBytes != 0

The maximum length of the data portion of buffers accepted by NetBackup must not exceed numBytes bytes.

headerBytes == 0

NetBackup only accepts buffers with no header portion.

headerBytes != 0

The length of the header portion of buffers accepted by NetBackup is headerBytes bytes.

bufferPtr

Not used

The values returned by the call to BSACreateObject() remain in effect for the duration of the data transfer of the XBSA object being created, that is, until the next BSAEndData() call. The NetBackup XBSA interface currently does not have any header or trailer requirements, so the full buffer specified can be used by the XBSA application. This is documented for completeness with the XBSA specification and to allow for future use of these fields as specified by the XBSA specifications.

RETURN VALUE

The following return codes are returned by this function:

BSA_RC_ABORT_SYSTEM_ERROR

System detected error, operation aborted.

BSA_RC_ACCESS_FAILURE

Cannot create the XBSA object with the given descriptor.

BSA_RC_INVALID_CALL_SEQUENCE

The sequence of API calls is incorrect.

BSA_RC_INVALID_DATABLOCK

The BSA_DataBlock32 parameter contained an inconsistent value.

BSA_RC_INVALID_HANDLE

The handle used to associate this call with a previous BSAInit() call is invalid.

BSA_RC_INVALID_OBJECTDESCRIPTOR

The BSA_ObjectDescriptor was invalid.

BSA_RC_NULL_ARGUMENT

A NULL pointer was encountered in one of the arguments

BSA_RC_SUCCESS

The function succeeded.