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

NBBSAGetJobInfo

Obtain job information.

SYNOPSIS

#include <nbbsa.h>

int NBBSAGetJobInfo(BSA_Handle bsaHandle, int jobid, BSA_UInt32 length, char **jobInfo)

DESCRIPTION

NBBSAGetJobInfo() returns information about a job. The information obtained is equivalent to the information that is displayed by the following command:

bpdbjobs -jobid id -all_columns

See the NetBackup Commands Reference Guide for details. NBBSAGetJobInfo() can be called at any time during any transaction to obtain the job information for the job ID specified. The job information is returned in an array of pointers to character strings (for fields that have no information, the pointer is NULL). The NBBSAGetJobInfo() function allocates storage for each character string. After the application has completed its use of the job information, NBBSAFreeJobInfo() should be called to free the allocated storage.

The following #define constants are defined the include file nbbsa.h and should be used to obtain a specific piece of information for the specified job ID:

#define NBBSA_JOB_ID 0
#define NBBSA_JOB_TYPE 1
#define NBBSA_JOB_STATE 2
#define NBBSA_JOB_STATUS 3
#define NBBSA_JOB_POLICY_NAME 4
#define NBBSA_JOB_SCHEDULE_NAME 5
#define NBBSA_JOB_CLIENT_NAME 6
#define NBBSA_JOB_MEDIA_SERVER 7
#define NBBSA_JOB_START_TIME 8
#define NBBSA_JOB_ELAPSED_TIME 9
#define NBBSA_JOB_END_TIME 10
#define NBBSA_JOB_STORAGE_UNIT 11
#define NBBSA_JOB_NUMBER_OF_TRIES 12
#define NBBSA_JOB_OPERATION 13
#define NBBSA_JOB_DATA_WRITTEN 14
#define NBBSA_JOB_FILES_WRITTEN 15
#define NBBSA_JOB_LAST_WRITTEN_PATH 16
#define NBBSA_JOB_PERCENT_COMPLETE 17
#define NBBSA_JOB_PID 18
#define NBBSA_JOB_USER_ACCOUNT 19
#define NBBSA_JOB_SUBTYPE_CODE 20
#define NBBSA_JOB_POLICY_TYPE 21
#define NBBSA_JOB_SCHEDULE_TYPE 22
#define NBBSA_JOB_CONFIGURED_PRIORITY 23
#define NBBSA_JOB_SERVER_GROUP_NAME 24
#define NBBSA_JOB_MASTER_SERVER_NAME 25
#define NBBSA_JOB_RETENTION_LEVEL 26
#define NBBSA_JOB_RETENTION_PERIOD 27
#define NBBSA_JOB_COMPRESSION 28
#define NBBSA_JOB_ESTIMATED_KILOBYTES 29
#define NBBSA_JOB_ESTIMATED_FILES 30
#define NBBSA_JOB_FILE_LIST_COUNT 31
#define NBBSA_JOB_FILE_PATHS_WRITTEN 32
#define NBBSA_JOB_TRY_COUNT 33
#define NBBSA_JOB_TRY_PID 34
#define NBBSA_JOB_TRY_STORAGE_UNIT 35
#define NBBSA_JOB_TRY_SERVER 36
#define NBBSA_JOB_TRY_START_TIME 37
#define NBBSA_JOB_TRY_ELAPSED_TIME 38
#define NBBSA_JOB_TRY_END_TIME 39
#define NBBSA_JOB_TRY_STATUS_CODE 40
#define NBBSA_JOB_TRY_STATUS_DESCRIPTION 41
#define NBBSA_JOB_TRY_STATUS_LINES_COUNT 42
#define NBBSA_JOB_TRY_STATUS_LINES 43
#define NBBSA_JOB_TRY_DATA_WRITTEN 44
#define NBBSA_JOB_TRY_FILES_WRITTEN 45
#define NBBSA_JOB_PARENT_JOB_NUMBER 46
#define NBBSA_JOB_TRANSFER_SPEED 47
#define NBBSA_JOB_COPY_NUMBER 48
#define NBBSA_JOB_ROBOT 49
#define NBBSA_JOB_VAULT_ID 50
#define NBBSA_JOB_VAULT_PROFILE 51
#define NBBSA_JOB_VAULT_SESSION 52
#define NBBSA_JOB_TAPES_TO_EJECT 53
#define NBBSA_JOB_SOURCE_STORAGE_UNIT 54
#define NBBSA_JOB_SOURCE_MEDIA_SERVER 55
#define NBBSA_JOB_SOURCE_MEDIA_ID 56
#define NBBSA_JOB_DESTINATION_MEDIA_ID 57
#define NBBSA_JOB_STREAM_NUMBER 58
#define NBBSA_JOB_SUSPENDABLE 59
#define NBBSA_JOB_RESUMABLE 60
#define NBBSA_JOB_RESTARTABLE 61
#define NBBSA_JOB_DATA_MOVEMENT_TYPE 62
#define NBBSA_JOB_SNAPSHOT_OPERATION 63
#define NBBSA_JOB_BACKUP_ID 64
#define NBBSA_JOB_KILLABLE 65
#define NBBSA_JOB_CONTROLLING_HOST 66
#define NBBSA_JOB_OFF_HOST_TYPE 67
#define NBBSA_JOB_FIBER_TRANSPORT_USAGE 68
#define NBBSA_JOB_QUEUE_REASON 69
#define NBBSA_JOB_OPTIONAL_REASON 70
#define NBBSA_JOB_DEDUP_RATIO 71
#define NBBSA_JOB_ACCELERATOR_OPTIMIZATION 72
#define NBBSA_JOB_INSTANCE_DATABASE_NAME 73
#define NBBSA_JOB_LAST_FIELD 73

		The file paths for the NBBSA_JOB_FILE_PATHS_WRITTEN string will 
  be delimited by a newline character.
		The status lines for the NBBSA_JOB_TRY_STATUS_LINES string will
  be delimited by a newline character.

--- Sample code ---

char *job_info[NBBSA_JOB_LAST_FIELD+1];

Rc=NBBSAGetJobInfo(BsaHandle,job_id,NBBSA_JOB_LAST_FIELD+1,job_info);
if (Rc == BSA_RC_SUCCESS) {
    printf("Job Status: %s\n", job_info[NBBSA_JOB_STATUS]);

    Rc=NBBSAFreeJobInfo(job_info);
}

PARAMETERS

BSA_Handle bsaHandle (I)

The handle that associates this call with a previous BSAInit() call.

int jobId (I)

The job ID for which you want to obtain information.

BSA_UInt_32 length(I)

The length of the jobInfo parameter that is an array of pointers to the character strings. The length of this array should be NBBSA_JOB_LAST_FIELD+1.

char **JobInfo(O)

The job information is returned in this array of pointers to character strings. A specific piece of information can be obtained by indexing the arrays using one of the #define constants listed in the description. If there is no information for a given field, the pointer is NULL.

RETURN VALUE

The following return codes are returned by this function:

BSA_RC_NULL_ARGUMENT

A NULL pointer was encountered in one of the arguments.

BSA_RC_BUFFER_TOO_SMALL

The array pointed to by the JobInfo parameter is not large enough. The length parameter specifies the length of the array and it should be NBBSA_JOB_LAST_FIELD+1.

BSA_RC_ABORT_SYSTEM_ERROR

System detected error, operation was aborted.

BSA_RC_INVALID_HANDLE

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

BSA_RC_SUCCESS

The function succeeded.