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

BSAInit

Initialize the environment and set up a session.

SYNOPSIS

#include <xbsa.h>

int BSAInit(BSA_Handle *bsaHandlePtr, BSA_SecurityToken *tokenPtr, BSA_ObjectOwner *objectOwnerPtr,

char **environmentPtr)

DESCRIPTION

The BSAInit() call authenticates the XBSA application, sets up a session with the NetBackup XBSA interface and an environment for subsequent API calls for the caller. Nested sessions are not supported.

PARAMETERS

BSA_Handle *bsaHandlePtr (O)

This parameter is used to return the handle that identifies this session and must be used for subsequent API calls using this session.

BSA_SecurityToken *tokenPtr (I)

For NetBackup XBSA Version 1.1.0, this parameter is ignored. Client authentication is part of NetBackup functionality and is performed between the NetBackup XBSA interface and the NetBackup server.

BSA_ObjectOwner *objectOwnerPtr (I)

This parameter is a pointer to a structure used to specify both the bsa_ObjectOwner and the app_ObjectOwner. For NetBackup XBSA Version 1.1.0, the NetBackup XBSA interface and NetBackup determine object ownership. If the bsa_ObjectOwner field is specified, it is ignored. The app_ObjectOwner is optional and can be the empty string. The BSA_ObjectOwner established when the session is created is used in subsequent authorization checking.

char **environmentPtr (I)

This parameter is a pointer to a structure that contains the new NetBackup XBSA environment variables (keyword, value) pairs, for the session. The new NetBackup XBSA environment consists of a pointer to an array of strings. Each string consists of a keyword followed by an '=' and followed by a null-terminated value. No spaces are allowed around the '='. A NULL pointer terminates the array of pointers.

EXTENDED DESCRIPTION

See Environment variable definitions.

Variables defined by the XBSA application but not interpreted by the NetBackup XBSA interface are silently ignored and not added to the NetBackup XBSA environment. Variables required by the NetBackup XBSA interface and not specified by the application can result in a BSA_RC_INVALID_ENV error during a BSAInit() call. The BSAGetEnvironment() call only returns the NetBackup XBSA environment variables that are meaningful to the NetBackup XBSA interface. This allows the XBSA application to discover which variables specified in the call to BSAInit() the NetBackup XBSA interface interpreted.

When an XBSA application connects to a NetBackup XBSA interface, it can make an initial call to BSAQueryApiVersion() to determine the highest version of the specification supported. If the application supports that version, it should specify it when calling BSAInit(). If the application does not support that version, or did not call BSAQueryApiVersion(), the XBSA application should specify the version it requires. If a "version not supported" error is encountered, and the XBSA application supports other versions, the XBSA application may retry the call to BSAInit() specifying a different version.

BSAInit() can also determine the verbose level and open the log file if the log directory exists. Thus the XBSA application can start logging after BSAInit().

If BSA_SERVICE_HOST and NBBSA_FEATURE_ID are specified in the list of XBSA environment variables, the feature is checked for a valid license key. If a valid license is not found, the transaction returns a NBBSA_RC_FEATURE_NOT_LICENSED error and does not open the session.

RETURN VALUE

The following return codes are returned by this function:

BSA_RC_ABORT_SYSTEM_ERROR

System detected error, operation aborted.

BSA_RC_AUTHENTICATION_FAILURE

There was an authentication failure.

BSA_RC_INVALID_CALL_SEQUENCE

The sequence of API calls is incorrect. Nested sessions are not supported.

BSA_RC_INVALID_ENV

An entry in the environment structure is invalid or missing.

BSA_RC_NULL_ARGUMENT

A NULL pointer was encountered in one of the arguments.

NBBSA_RC_FEATURE_NOT_LICENSED

The license for the requested feature is not available.

BSA_RC_SUCCESS

The function succeeded.

BSA_RC_VERSION_NOT_SUPPORTED

The NetBackup XBSA interface does not support the specified version of the interface.