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

Object descriptors

A NetBackup XBSA object has a BSA_ObjectDescriptor, that contains cataloging information and optional application-specific object metadata. Cataloging information is capable of interpretation and searching by the NetBackup XBSA interface. Application-specific object metadata is not interpretable by the NetBackup XBSA interface but it can be retrieved and interpreted by an application. Using an object's objectName or its assigned copyId identifier, the corresponding BSA_ObjectDescriptor and object data can be retrieved through the NetBackup XBSA interface.

A BSA_ObjectDescriptor consists of a collection of object attributes. The basic data types used for XBSA object attributes are:

  • Fixed-length character strings

  • Hierarchical character strings (with a specified delimiter, and a length limit on the overall string)

  • Enumerations

  • Integers (with a specified range limit)

  • Date-time (in a standard C TM structure) format and precision; for example, yyyymmddhhmm)

The attributes are shown in the following table:

Table: BSA_ObjectDescriptor Attributes

Attribute

Data Type

Searchable

objectOwner

(consisting of two parts)

Yes

bsa_ObjectOwner

[fixed-length character string]

app_ObjectOwner

[hierarchical character string]

objectName

(consisting of two parts)

Yes

objectSpaceName

[fixed-length character string]

pathName

[hierarchical character string]

createTime

[date-time]

Yes

copyType

[enumeration]

Yes

copyId

64-bit unsigned integer

No

restoreOrder

64-bit unsigned integer

No

resourceType

[fixed-length character string]

No

objectType

[enumeration]

Yes

objectStatus

[enumeration]

Yes

objectDescription

[fixed-length character string]

No

estimatedSize

[64-bit unsigned integer]

No

objectInfo

[fixed-length byte string]

No

Each NetBackup XBSA object is a copy of certain application object(s):

  • To preserve the semantics of the use of each copy within the BSA_ObjectDescriptor, each NetBackup XBSA object has a copyType of either backup or archive. The NetBackup XBSA interface recognizes the copyType so that the two types of objects can be managed differently and accessed separately.

    Note:

    It is up to the XBSA application to manage these types differently, as the NetBackup XBSA interface only keeps track of the type of the object.

  • Each NetBackup XBSA object also has an objectStatus of either most_recent or not_most_recent.

  • To capture an application object's type information, the corresponding NetBackup XBSA object can have a resourceType (for example, "filesystem") and a possible resource-specific BSA_ObjectType (for example, BSA_ObjectType_FILE).

An XBSA application can search for a NetBackup XBSA object within a certain search scope (for example, among objects in a certain objectSpaceName). It qualifies the search on the value of the appropriate searchable attributes.

On the other hand, non-searchable, application-specific attributes can be provided by an XBSA application for storage in the BSA_ObjectDescriptor, but the NetBackup XBSA interface does not interpret these attributes. They are stored in the NetBackup XBSA object attributes objectInfo, resourceType, and objectDescription.

The objectInfo field defaults to a character string. It can also be used to store binary data by using the NBBSA_OBJINFO_LEN XBSA environment variable.

Through these descriptor attributes, application-specific metadata can be stored in the catalog. Then, this metadata can be efficiently retrieved without retrieving the actual object data that is stored in the repository. An XBSA application can use these attributes to maintain inter-object relationships and dependencies. Some consideration should be given as to how much data is stored in the NetBackup Catalog. The amount of metadata that is stored with a few large objects can be larger than the amount that is stored for a million small objects.