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

Extended environment variable definitions

Table: Extended Environment Variables

Variable Name

Extended Description

BSA_API_VERSION

BSA_API_VERSION specifies the version of the XBSA specification. The XBSA application sets it as the version that the XBSA application requires. This value is required to be in the environmental variable list in the call to BSAInit(), where it is verified as a supported version of the NetBackup XBSA interface.

The current value of BSA_API_VERSION that is supported by the NetBackup XBSA interface can be retrieved with a call to BSAQueryApiVersion().

Once BSA_API_VERSION has been set in the XBSA environment, it cannot be changed by calls to NBBSAUpdateEnv() or NBBSASetEnv().

The version that is supported for this feature pack is "1.1.0."

BSA_DELIMITER

BSA_DELIMITER is the delimiter used in hierarchical character strings. The NetBackup XBSA interface sets this XBSA environment variable.

This feature pack uses the "/" delimiter. This value can be retrieved by BSAQueryServiceProvider().

BSA_SERVICE_HOST

BSA_SERVICE_HOST identifies the host system for the NetBackup server. If this variable is not provided, the currently configured server for the NetBackup client is used.

See the NetBackup System Administrator's Guide, Volume I, for information on how to use the bp.conf configuration file to specify the NetBackup servers.

This XBSA environment variable can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but cannot be set or modified after a transaction has begun.

BSA_SERVICE_PROVIDER

BSA_SERVICE_PROVIDER identifies the XBSA implementation. The NetBackup XBSA interface sets this XBSA environment variable.

It is defined as: Veritas/NetBackup/1.1.0.

BSAQueryServiceProvider() can also retrieve this value.

NBBSA_CLIENT_HOST

NBBSA_CLIENT_HOST identifies a specific host system as the NetBackup client. If this variable is not provided, the host on which the XBSA application is running is the client.

This variable is useful for queries and restores when restoring the data that was backed up from a host other than the host where the data was restored. For backups, if the NBBSA_CLIENT_HOST is logically different from the client host where the backup is being initiated from, this results in an error, as you cannot create objects from another host.

This XBSA environment variable can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but cannot be set or modified after a transaction has begun.

NBBSA_CLIENT_READ_TIMEOUT

NBBSA_CLIENT_READ_TIMEOUT is used to determine or reset the NetBackup CLIENT_READ_TIMEOUT value.

The NetBackup XBSA interface creates this XBSA environment variable in the function BSACreateObject() or BSAGetObject(). After BSACreateObject(), the NBBSA_CLIENT_READ_TIMEOUT value can be reset by the XBSA application by NBBSAUpdateEnv() or NBBSASetEnv(). Setting it at any other time has no effect.

See the NetBackup System Administrator's Guide for UNIX, Volume I, or NetBackup System Administrator's Guide for Windows, Volume I, for more information about CLIENT_READ_TIMEOUT.

NBBSA_DB_TYPE

NBBSA_DB_TYPE is an internal string representation of a NetBackup policy type. This is generally only used for NetBackup internal agents, but in certain instances it can be set up for external use. If this variable is not specified, it defaults to the SDK default of DataStore policy type. If this variable is used, the NBBSA_FEATURE_ID must also be specified.

NBBSA_FEATURE_ID

NBBSA_FEATURE_ID identifies a specific NetBackup licensed feature to be used for the session. If this variable is not provided, the default DataStore feature ID is used. In general, this environment variable does not need to be set, but it allows an application, working with NetBackup product management, to use a specific NetBackup license.

This value can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but cannot be set or modified after a transaction has begun.

NBBSA_KEYWORD

NBBSA_KEYWORD allows the XBSA application to specify a NetBackup keyword. This keyword is typically used to group images together and can speed up a search. If this variable is specified for a backup transaction, the keyword is stored with the image. If it is specified before a query or restore transaction, the keyword is used to help in the search process.

This value can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but cannot be set or modified after a transaction has begun.

NBBSA_LOG_DIRECTORY

NBBSA_LOG_DIRECTORY identifies the name of the directory that contains the log files of the NetBackup XBSA interface and possibly for the XBSA application. This directory is located in /usr/openv/netbackup/logs on UNIX and install_directory\VERITAS\NetBackup\Logs on Windows. If it is not specified, the directory name is exten_client.

All debug messages from the NetBackup XBSA interface and from function NBBSALogMsg() go to a dated log file in this directory.

This value can be set by the XBSA application by BSAInit(). It may not be modified after the call to BSAInit().

NBBSA_MEDIA_MOUNT_TIMEOUT

NBBSA_MEDIA_MOUNT_TIMEOUT is used to determine the NetBackup MEDIA_MOUNT_TIMEOUT value.

The NetBackup XBSA interface creates this XBSA environment variable in the function BSACreateObject() or BSAGetObject().

NBBSA_MEDIA_MOUNT_TIMEOUT cannot be modified by the XBSA application.

See the NetBackup System Administrator's Guide, Volume I, for more information about MEDIA_MOUNT_TIMEOUT.

NBBSA_MULTIPLEXING

NBBSA_MULTIPLEXING the number of streams that NetBackup has been configured to accept at one time.

The NetBackup XBSA interface creates this XBSA environment variable in the function BSACreateObject() or BSAGetObject(). The XBSA application cannot modify NBBSA_MULTIPLEXING.

See the NetBackup System Administrator's Guide, Volume I, for more information about multiplexing.

NBBSA_OBJECT_GROUP

NBBSA_OBJECT_GROUP can be used with variable NBBSA_USE_OBJECT_GROUP to define the group ownership of an object. When NBBSA_USE_OBJECT_GROUP = VxENV_OWNER, the name that is defined in this string becomes the group owner of an object that is created. This group should be a valid group name on the client.

This value can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv(). It can be modified within a transaction and each object that is created within one transaction can have a different group.

NBBSA_OBJECT_OWNER

NBBSA_OBJECT_OWNER can be used with variable NBBSA_USE_OBJECT_OWNER to define the ownership of an object. When NBBSA_USE_OBJECT_OWNER = VxENV_OWNER, the name that is defined in this string becomes the owner of an object that is created. This owner should be a valid user name on the client.

This value can be set by the VxBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv(). It can be modified within a transaction and each object that is created within one transaction can have a different owner.

NBBSA_OBJINFO_LEN

NBBSA_OBJINFO_LEN is used by BSACreateObject() to allow the objectInfo field of the object descriptor to contain non-ASCII values. If this variable is not specified, the objectInfo field is treated as a NULL terminated character string. You do not have to specify this variable for a query or restore transaction.

The XBSA application can modify this value at any time during a backup transaction using BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv(). If the length of the objectInfo field is different for each object, it can be changed before each BSACreateObject() call.

NBBSA_POLICY

NBBSA_POLICY identifies a specific NetBackup policy to be used for the transaction. If this variable is not provided, the NetBackup configuration is used to find the default policy. For backups, if a policy is configured in NetBackup on the client, that policy is used for the backup. For queries, restores, and deletes, the configured policy is not used.

See the NetBackup System Administrator's Guide, Volume I, for information on how to create and configure a NetBackup policy.

This value can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but cannot be set or modified after a transaction has begun.

NBBSA_SCHEDULE

NBBSA_SCHEDULE identifies a specific NetBackup schedule to be used. If this variable is not provided, the NetBackup configuration is used to find the default schedule to use. For backups, if a schedule is configured in NetBackup on the client, that schedule is used for the backup. For queries, restores, and deletes, the configured schedule is not used.

See the NetBackup System Administrator's Guide, Volume I, for information on how to create and configure a NetBackup schedule.

This value can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but cannot be set or modified after a transaction has begun.

NBBSA_SERVER_BUFFSIZE

NBBSA_SERVER_BUFFSIZE the NetBackup configured size of the

NET_BUFFER_SZ. This variable can be used by the XBSA application to help improve performance.

The NetBackup XBSA interface creates this XBSA environment variable in the function BSACreateObject() or BSAGetObject(). The XBSA application cannot modify NBBSA_SERVER_BUFFSIZE.

See the NetBackup System Administrator's Guide, Volume I, for more information about setting the buffer size.

NBBSA_USE_OBJECT_GROUP

NBBSA_USE_OBJECT_GROUP lets the agent define the group owner of objects that are created with VxBSACreateObject(). The default group of an object is the logon user of the process creating the object (not the primary group of the logon user, but the actual logon user). This variable allows the agent to specify the ownership as follows.

VxLOGIN_USER 0 - Default, group field is set to the logon user

VxLOGIN_GROUP 1 - Group field is set to the primary group of the logon user

VxBSA_OWNER 2 - Group field is set to objectDescriptor->objectOwner.bsa_ObjectOwner

VxAPP_OWNER 3 - Group field is set to objectDescriptor->objectOwner.app_ObjectOwner

VxENV_OWNER 4 - Group field is set to value of NBBSA_GROUP_OWNER variable

This value may be set by the BSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but may not be set or modified after a transaction has begun.

NBBSA_USE_OBJECT_OWNER

NBBSA_USE_OBJECT_OWNER allows the agent to define the owner of objects that are created with BSACreateObject(). The default ownership of an object is the logon user of the process creating the object. This variable allows the agent to specify the ownership as:

VxLOGIN_USER 0 - Default, owner field is set to the logon user

VxBSA_OWNER 2 - Owner field is set to objectDescriptor->objectOwner.bsa_ObjectOwner

VxAPP_OWNER 3 - Owner field is set to objectDescriptor->objectOwner.app_ObjectOwner

VxENV_OWNER 4 - Owner field is set to value of NBBSA_OBJECT_OWNER variable

This value can be set by the XBSA application by BSAInit(), NBBSASetEnv(), or NBBSAUpdateEnv() but cannot be set or modified after a transaction has begun.

NBBSA_VERBOSE_LEVEL

NBBSA_VERBOSE_LEVEL is the verbose level of the NetBackup debug logs. The verbose level can be configured through the Backup, Archive, and Restore interface or the NetBackup Administration Console.

This value can be useful if the XBSA application, using NBBSALogMsg(), wants to log different levels of messages to the NetBackup XBSA logs based on the verbose level that is configured in NetBackup.

The NetBackup XBSA interface originally sets this value in BSAInit(). The XBSA application can reset this environment variable, using NBBSASetEnv() or NBBSAUpdateEnv(), if it wants to change the level of logging.