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

Multiple object restore example

Here is an example of a multiple object restore. Examples of BSAQueryObject and BSAGetObject are included elsewhere in this document, so this example bypasses some of the error handling associated with those calls.

BSA_Handle                    BsaHandle;
BSA_ObjectOwner               BsaObjectOwner;
BSA_SecurityToken             *security_tokenPtr;
BSA_DataBlock32               *data_block;
BSA_QueryDescriptor           *query_desc;
BSA_ObjectDescriptor          *object_desc;
BSA_ObjectDescriptor          *object_desc_current;
NBBSA_DESCRIPT_LIST           *object_list = NULL;
NBBSA_DESCRIPT_LIST           *object_list_current;
BSA_UInt32                    EnvBufSz = 512;
BSA_UInt32                    Size;
char                          *envx[3];
char                          EnvBuf[512];
char                          ErrorString[512];
char                          msg[1024];
char                          *restore_location;
int                           total_bytes = 0;
int                           status;
.
.
BSAInit(&BsaHandle, security_tokenPtr, &BsaObjectOwner, envx);
.
.
BSABeginTxn(BsaHandle);

/* Populate the query descriptor of the object to be searched for. */

query_desc = (BSA_QueryDescriptor *)malloc(sizeof(BSA_QueryDescriptor));
object_desc = (BSA_ObjectDescriptor *)malloc(sizeof(BSA_ObjectDescriptor));
data_block = (BSA_DataBlock32 *)malloc(sizeof(BSA_DataBlock32));

query_desc->copyType = BSA_CopyType_BACKUP;
query_desc->objectType = BSA_ObjectType_FILE;
query_desc->objectStatus = BSA_ObjectStatus_MOST_RECENT;
strcpy(query_desc->objectOwner.bsa_ObjectOwner, "BSA Client");
strcpy(query_desc->objectOwner.app_ObjectOwner, "BSA App");
strcpy(query_desc->objectName.pathName, "/xbsa/sample/object1");
strcpy(query_desc->objectName.objectSpaceName, ""); 

/* Search for an object matching the query criteria.  */

status = BSAQueryObject(BsaHandle, query_desc, object_desc);
if (status != BSA_RC_SUCCESS) {
   /* handle error condition */
}

/* Start building the objectList by adding the object descriptor to the list.  */

status = NBBSAAddToMultiObjectRestoreList(BsaHandle, &object_list, object_desc);
if (status != BSA_RC_SUCCESS) {
    Size = 512;
    NBBSAGetErrorString(status, &Size, ErrorString);
    sprintf(msg, "ERROR: NBBSAAddToMultiObjectRestoreList() failed with error: %s", 
        ErrorString);
    NBBSALogMsg(BsaHandle, ERROR, msg, " Multiple Object Restore");
    BSATerminate(BsaHandle);
    exit(status);
    }

/* Search for a second object.  */

strcpy(query_desc->objectName.pathName, "/xbsa/sample/object2");
status = BSAQueryObject(BsaHandle, query_desc, object_desc);
if (status != BSA_RC_SUCCESS) {
   /* handle error condition */
}

/* Add the second object descriptor to the objectList.  */

status = NBBSAAddToMultiObjectRestoreList(BsaHandle, &object_list, object_desc);
if (status != BSA_RC_SUCCESS) {
    Size = 512;
    NBBSAGetErrorString(status, &Size, ErrorString);
    sprintf(msg, "ERROR: NBBSAAddToMultiObjectRestoreList() failed with error: %s", 
        ErrorString);
    NBBSALogMsg(BsaHandle, ERROR, msg, " Multiple Object Restore");
    BSATerminate(BsaHandle);
    exit(status);
}

/* Start the multiple object restore by passing in the object list. The object list 
 * will be evaluated and the restore job will be started.
 */

status = NBBSAGetMultipleObjects(BsaHandle, object_list);
if (status != BSA_RC_SUCCESS) {
    Size = 512;
    NBBSAGetErrorString(status, &Size, ErrorString);
    sprintf(msg, "ERROR: NBBSAGetMultipleObjects () failed with error: %s", 
        ErrorString);
    NBBSALogMsg(BsaHandle, ERROR, msg, "Multiple Object Restore");
    BSATerminate(BsaHandle);
    exit(status);
}

/* Create a pointer to the object list in order to keep track of the current object
 * being restored.  A list created by the application could also be used.
 * Point the object descriptor at the first object
 */
object_list_current = object_list;
object_desc_current = object_list_current->Descriptor;

/*  Get the first object.  */

status = BSAGetObject(BsaHandle, object_desc_current, data_block);
if (status != BSA_RC_SUCCESS) {
    /* handle error condition */
}
 
restore_location = (char *)malloc((EnvBufSz + 1) * sizeof(char));
memset(restore_location, 0x00, EnvBufSz + 1);
 
data_block->bufferLen = EnvBufSz;
data_block->bufferPtr = EnvBuf;
memset(data_block->bufferPtr, 0x00, EnvBufSz);
 
/* Read data until the end of data. */
 
while ((status = BSAGetData(BsaHandle, data_block)) == BSA_RC_SUCCESS) {
 
    /* Move the retrieved data to where it is to be restored to and  *
     * reset the data_block buffer.                                  */
 
    memcpy(restore_location, data_block->bufferPtr, data_block->numBytes);
    total_bytes += data_block->numBytes;
 
    memset(restore_location, 0x00, EnvBufSz + 1);
    memset(data_block->bufferPtr, 0x00, EnvBufSz);
}
if (status == BSA_RC_NO_MORE_DATA) {
 
    memcpy(restore_location, data_block->bufferPtr, data_block->numBytes);
    total_bytes += data_block->numBytes;
 
    printf("Total bytes retrieved: %d\n", total_bytes);
} else {
    /* handle error condition */
}
  
/* Done retrieving data for the first object. */
 
status = BSAEndData(BsaHandle);
if (status != BSA_RC_SUCCESS) {
    /* handle error condition */
}     

/* Set the object descriptor to the next object in the list.  */
object_list_current = object_list_current->next;
object_desc_current = object_list_current->Descriptor;

if (object_desc_current == NULL) {
   /* handle error condition */
}

/*  Get the next object.  */

status = BSAGetObject(BsaHandle, object_desc_current, data_block);
if (status != BSA_RC_SUCCESS) {
    /* handle error condition */
}
 
restore_location = (char *)malloc((EnvBufSz + 1) * sizeof(char));
memset(restore_location, 0x00, EnvBufSz + 1);
 
data_block->bufferLen = EnvBufSz;
data_block->bufferPtr = EnvBuf;
memset(data_block->bufferPtr, 0x00, EnvBufSz);
 
/* Read data until the end of data. */
 
while ((status = BSAGetData(BsaHandle, data_block)) == BSA_RC_SUCCESS) {
 
    /* Move the retrieved data to where it is to be restored to and  *
     * reset the data_block buffer.                                  */
 
    memcpy(restore_location, data_block->bufferPtr, data_block->numBytes);
    total_bytes += data_block->numBytes;
 
    memset(restore_location, 0x00, EnvBufSz + 1);
    memset(data_block->bufferPtr, 0x00, EnvBufSz);
}
if (status == BSA_RC_NO_MORE_DATA) {
 
    memcpy(restore_location, data_block->bufferPtr, data_block->numBytes);
    total_bytes += data_block->numBytes;
 
    printf("Total bytes retrieved: %d\n", total_bytes);
} else {
    /* handle error condition */
}
 
/* Done retrieving data for the second object. */

status = BSAEndData(BsaHandle);
if (status != BSA_RC_SUCCESS) {
    /* handle error condition */
}

/* End the multiple object restore transaction. Set any references to objects 
 * in the object list to NULL as the memory associated to the list has been freed. 
 */

status = NBBSAEndGetMultipleObjects(BsaHandle, BSA_Vote_COMMIT, object_list);
if (status != BSA_RC_SUCCESS) {
    Size = 512;
    NBBSAGetErrorString(status, &Size, ErrorString);
    sprintf(msg, "ERROR: NBBSAEndGetMultipleObjects() failed with error: %s", 
        ErrorString);
    NBBSALogMsg(BsaHandle, ERROR, msg, "Multiple Object Restore");
    BSATerminate(BsaHandle);
    exit(status);
}
object_list_current = NULL;
object_desc_current = NULL; 

/* End the restore transaction. BSA_Vote_COMMIT and BSA_Vote_ABORT are 
 * equivalent as there is nothing to commit or abort for a restore transaction.
 */
 
status = BSAEndTxn(BsaHandle, BSA_Vote_COMMIT);
if (status != BSA_RC_SUCCESS) {
    Size = 512;
    NBBSAGetErrorString(status, &Size, ErrorString);
    sprintf(msg, "ERROR: BSAEndTxn() failed with error: %s", ErrorString);
    NBBSALogMsg(BsaHandle, ERROR, msg, " Multiple Object Restore");
    BSATerminate(BsaHandle);
    exit(status);
}