Backup Services API Definitions

General

The approach adopted in XBSA is to define a minimal, generic API that is able to adequately and efficiently support a wide range of backup applications and utilities. The API addresses portability issues across multiple backup products. It is not intended to address the interoperability of clients and backup servers across arbitrary networks; this is a responsibility of the underlying Backup Service product.

The following man pages describe the function calls used in the XBSA API. Many of the parameter values used in the XBSA calls are dependent on the specific Backup Service invoked from a particular vendor. Consequently, while some XBSA calls and structures are generic, any particular XBSA Application may need to determine the actual Backup Service being invoked in order to correctly use XBSA.

This chapter contains the C language definitions for all the Open Backup Services API procedures. Type Definitions and Data Structures gives the data type definitions used in the API.

In the descriptions in these man-pages:

(I)

indicates input

(O)

indicates output

(I/O)

indicates input and output

In many cases, the actual input parameter is a pointer to a data structure. In these cases the terms "I", "O" and "I/O" refer to changes in the value of the data structure rather than to changes in the value of the pointer itself.

Return Code Values

The return code [BSA_RC_SUCCESS] is returned on successful completion by all XBSA interfaces.

XBSA Function Definitions

NAME

BSABeginTxn - begin an API transaction

SYNOPSIS

#include <xbsa.h>

int BSABeginTxn(long bsaHandle)

DESCRIPTION

The BSABeginTxn() call indicates to Backup Service the beginning of one or more actions that will be executed as an atomic unit, that is, all the actions will succeed or none will succeed. An action can be assumed to be either a single API call or a series of API calls that are made for a particular purpose.

For example, a BSACreateObject() call followed by a number of BSASendData() calls and terminated by a BSAEndData() call can be considered to be a single action.

In normal use, a BSABeginTxn() call is always coupled with a subsequent BSAEndTxn() call. If BSATerminate() is called during a transaction, the transaction will be aborted.

Nested transactions are not supported.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_INVALID_CALL_SEQUENCE]

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

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSACreateObject - create a BSA object (either a backup or an archive copy)

SYNOPSIS

#include <xbsa.h>

int BSACreateObject(long bsaHandle,
                    BSA_ObjectDescriptor *objectDescriptorPtr,
                    BSA_DataBlock32 *dataBlockPtr)

DESCRIPTION

The BSACreateObject() call creates an an object within the Backup Service. All objects created are owned by the bsa_ObjectOwner creating the object. For backup and archive copy objects, duplicate BSA_ObjectNames are allowed.

The BSACreateObject() call is used to create an object when the object's data is passed in memory buffers. The dataBlockPtr parameter in the BSACreateObject() call allows the caller to obtain information about the buffer structure required by the Backup Service.

The object's data is passed through one or more BSASendData() calls. If there is no data to be sent, then a BSAEndData() call must be used to indicate completion of the object. The BSASendData() and BSAEndData() calls must follow the BSACreateObject() call and must be in the same transaction.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_ObjectDescriptor *objectDescriptorPtr (I/O)

This parameter is used to pass object attributes, including its name, copy type, and so on.

BSA_DataBlock32 *dataBlockPtr (O)

This parameter points to a structure that is used to obtain the details of the required buffer structure.

EXTENDED DESCRIPTION

Within the object descriptor, all fields must contain valid values. Enumerations must contain one of their enumerated values. Strings must be null-terminated. All other fields must be in the range of valid values for that field.

The following fields in the object descriptor are optional: objectOwner, objectDescription, and objectInfo. The optional value for either field of objectOwner and the field objectDescription is the empty string. The optional value for objectInfo is all zeros. If the bsa_ObjectOwner is empty it will default to the value specified in BSAInit().

The following fields in the object descriptor are mandatory: objectName, copyType, estimatedSize, resourceType, and objectType. For objectName this means that the pathName must contain a non-empty string. For copyType and objectType the enumeration value "ANY" is not allowed.

The estimatedSize must contain a non-zero estimate if the XBSA Client intends to create a non-empty XBSA Object (that is, there will be XBSA Object Data). This size is in bytes. Although the actual XBSA Object Data may be more or less than the estimate, the Backup Service may return a failure if the XBSA Object Data is orders of magnitude larger than the estimatedSize. If the estimatedSize is zero, this call must be followed by an BSAEndData() without calling BSASendData() in between. The estimatedSize can be used by the Backup Service as a hint, for example to select the storage medium or storage device.

The Backup Service may return several values to the BSA Application through the objectDescriptorPtr for a newly created XBSA Object. The Backup Service returns either all or none of these values.

The copyId attribute is a persistent, fixed-length Object Identifier which remains unchanged throughout the life of the object.

It is the responsibility of the Backup Service to assign copyId values to objects. When objects are deleted, their copyIds are returned to the pool of available identifiers, but the Backup Service must choose an assignment policy that prevents their immediate reuse.

If the copyId field is non-zero, the Backup Service returned values for the copyId, createTime, restoreOrder, and objectStatus fields. If the copyId field is zero, the values for the createTime, restoreOrder, and objectStatus fields are undefined. The calling BSA Application must call BSAQueryObject() to obtain an updated object descriptor.

Note:

If the returned copyId is zero and the XBSA Client uses BSAQueryObject() to retrieve an updated BSA_ObjectDescriptor for the newly created object, the Backup Service cannot guarantee that the ObjectDesriptor returned by BSAQueryObject() is for the object created by this call to BSACreateObject().

The behavior of returning a copyId value of zero is permitted for backwards compatibility with existing implementations. This behavior is deprecated and it is not intended that it should be used in new implementations.

The createTime field is in UTC. The restoreOrder field is optional and can have the value zero, which means that the Backup Service did not specify a restore order.

The dataBlockPtr structure does not point to an actual buffer. All values in the dataBlockptr should be zero, and will be overwritten. The structure is used by the Backup Service to provide the BSA Application with the Backup Service's preference for the structure of the data blocks that will be used to pass the object's data. The BSA Application should examine the values returned in order to determine the buffer structure that it should create. The significance of the returned values is as follows:

bufferLen == 0	The Backup Service has no restrictions on the buffer length. No trailer portion is required.
bufferLen != 0	The Backup Service accepts buffers that are at least bufferLen bytes in length (minimum length). The length of the trailer portion of buffers is: trailerBytes >= (bufferLen - numBytes - headerBytes)
numBytes == 0	The Backup Service has no restrictions on the length of the data portion of the buffer.
numBytes != 0	The maximum length of the data portion of buffers accepted by the Backup Service must not exceed numBytes bytes.
headerBytes == 0	The Backup Service only accepts buffers with no header portion.
headerBytes != 0	The length of the header portion of buffers accepted by the Backup Service is headerBytes bytes.
bufferPtr	Not used

The values returned by the Backup Service must conform to the relationships defined in BSA_DataBlock32 .

The values returned by the call to BSACreateObject() remain in effect for the duration of the data transfer of the object being created, that is, until the next BSAEndData() call.

It is the responsibility of the XBSA Client to provide this guarantee, if so desired. For example, the XBSA Client could use a unique identifier in the objectDescription field of the BSA_ObjectDescriptor for such a purpose.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_ACCESS_FAILURE]

Cannot create object with given descriptor.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_DATABLOCK]

The BSA_DataBlock32 parameter contained an inconsistent value.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_INVALID_OBJECTDESCRIPTOR]

The BSA_ObjectDescriptor was invalid.

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSADeleteObject - delete a BSA object

SYNOPSIS

#include <xbsa.h>

int BSADeleteObject(long bsaHandle, BSA_UInt64 copyId)

DESCRIPTION

The BSADeleteObject() call deletes an XBSA object from the Backup Service. The value for copyId can be obtained from a previous BSAQueryObject() call. The copyId value is unique within the Backup Service. A bsa_ObjectOwner can only delete objects that it owns.

It is not possible to create and then delete the same object within a single transaction.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_UInt64 copyId (I)

This parameter is the unique id of the object to be deleted. The value(s) for a specific object can be obtained through a BSAQueryObject() call.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_ACCESS_FAILURE]

Cannot delete object with given copyId.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_COPYID]

The copyId field cannot be zero.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_OBJECT_NOT_FOUND]

The given copyId does not exist.

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAEndData - end a BSAGetData() or BSASendData() sequence

SYNOPSIS

#include <xbsa.h>

int BSAEndData(long bsaHandle)

DESCRIPTION

The caller issues BSAEndData() after a call to BSACreateObject() followed by zero or more BSASendData() calls, or after a call to BSAGetObject() followed by zero or more BSAGetData() calls to signify the end of data. When used with BSAGetObject() or BSAGetData() calls, BSAEndData() will not transfer any more data for the object to the caller. When used with BSACreateObject() or BSASendData() calls, BSAEndData() tells the Backup Service that the caller has finished sending data for a particular object. BSAEndData() signifies the end of data for the immediately preceding BSACreateObject(), BSAGetObject(), BSAGetData(), or BSASendData().

It is also required after a call to BSAGetObject() or BSACreateObject() if the object is empty.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAEndTxn - end a transaction

SYNOPSIS

#include <xbsa.h>

int BSAEndTxn(long bsaHandle, BSA_Vote vote)

DESCRIPTION

BSAEndTxn() is coupled with BSABeginTxn() to identify the API call or set of API calls that are to be treated as a transaction. The caller must specify as a parameter to the BSAEndTxn() call whether or not the transaction is to be committed.

The [BSA_RC_TRANSACTION_ABORTED] error can only be returned when a vote of BSA_Vote_COMMIT has been specified but an error has occurred which causes the transaction to be aborted.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_Vote vote (I)

This parameter indicates whether or not the caller wants to commit all the actions done between the previous BSABeginTxn() call and this call.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_INVALID_CALL_SEQUENCE]

There is no corresponding BSABeginTxn().

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_INVALID_VOTE]

The value specified for vote is invalid.

[BSA_RC_SUCCESS]

The function succeeded.

[BSA_RC_TRANSACTION_ABORTED]

The transaction was aborted.

NAME

BSAGetData - get a byte stream of data using buffers

SYNOPSIS

#include <xbsa.h>

int BSAGetData(long bsaHandle, BSA_DataBlock32 *dataBlockPtr)

DESCRIPTION

BSAGetData() allows the caller to request a buffer full of XBSA Object Data from the Backup Service. This call is used after a BSAGetObject() call or after other BSAGetData() calls.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_DataBlock32 *dataBlockPtr (I/O)

This parameter points to a structure that includes both a pointer to the buffer for the data that is to be received and the size of the buffer. Further, the API will return, in this structure, the number of bytes of data that have been sent to the caller for this call.

EXTENDED DESCRIPTION

The Backup Service overwrites the numBytes field to provide the actual values used. The Backup Service may not modify any other fields. The BSA Application may only use the data portion of the buffer, in which the object data is contained.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_DATABLOCK]

The BSA_DataBlock32 parameter contained an inconsistent value.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_NO_MORE_DATA]

There is no more data.

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAGetEnvironment - retrieve the current environment for the session

SYNOPSIS

#include <xbsa.h>

int BSAGetEnvironment(long bsaHandle, BSA_UInt32 *sizePtr,
                      char **environmentPtr)

DESCRIPTION

The BSAGetEnvironment() call returns the (keyword, value) pairs that are currently defined in the environment for the session. This call is used to retrieve environment variables from the Backup Service environment.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call. It identifies the session.

BSA_UInt32 *sizePtr (I/O)

This parameter contains the size of the environment buffer in bytes.

char **environmentPtr (O)

This parameter is a pointer to an array of character pointers to the environment variables strings for the session. Each string consists of a keyword followed by an "=" followed by a null-terminated value. The array of pointers is terminated by a NULL pointer.

EXTENDED DESCRIPTION

If a buffer too small error is encountered, the required size is returned in the sizePtr parameter. If the sizePtr parameter is set to zero, this will force a buffer too small error, thus providing a mechanism to query the required size.

The following environment variables, to be returned by the Backup Service implementation, are defined as part of this Technical Standard.

Variable Name	Description	Format
BSA_DELIMITER	The delimiter used in hierarchical character strings (default "/")	A single character drawn from the POSIX.1 portable filename character set for example, ":"
BSA_SERVICE_PROVIDER	Identifies the BSA implementation. This is the same string that is returned by the BSAQueryServiceProvider() function call.	A hierarchical character string with at least 3 fields as follows: CompanyName/ProductName/ProductVersion[/...] Additional, delimiter-separated, implementation-specific fields are permitted for example, IBM/ADSM/2.1.3

Additional private variables are allowed. The BSAGetEnvironment() call only returns environment variables that are meaningful to the Backup Service. This allows the XBSA Application to discover which variables that it specified when it called BSAInit() were interpreted by the Backup Service.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_BUFFER_TOO_SMALL]

The size of the data buffer is invalid.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAGetLastError - return the last system error code

SYNOPSIS

#include <xbsa.h>

int BSAGetLastError(BSA_UInt32 *sizePtr, char *errorCodePtr)

DESCRIPTION

The BSAGetLastError() call returns a textual description of the last error encountered by the Backup Service implementation. It is used to return platform-specific information describing the underlying cause of the failure of the most recent XBSA call, for example, a network failure.

PARAMETERS

BSA_UInt32 sizePtr (I/O)

This parameter contains the size of the error buffer in bytes.

char *errorPtr (O)

This parameter points to a data area that contains a text string describing the last error encountered.

EXTENDED DESCRIPTION

If the Backup Service sets the sizePtr parameter to zero, the Backup Service is unable to return a string describing the last error. This indicates that the Backup Service has no record of what error occurred.

If a [BSA_RC_BUFFER_TOO_SMALL] error is encountered, the required size is returned in the sizePtr parameter. If the XBSA Application sets the sizePtr parameter to zero, this will force a [BSA_RC_BUFFER_TOO_SMALL] error, thus providing a mechanism to query the required size.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_BUFFER_TOO_SMALL]

The size of the data buffer is invalid.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAGetNextQueryObject - get the next object relating to a previous query

SYNOPSIS

#include <xbsa.h>

int BSAGetNextQueryObject(long bsaHandle,
                          BSA_ObjectDescriptor *objectDescriptorPtr)

DESCRIPTION

The BSAGetNextQueryObject() call returns the next object descriptor in response to a previous query. Successive calls to BSAGetNextQueryObject() will return these object descriptors.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_ObjectDescriptor *objectDescriptorPtr (O)

This parameter points to an object descriptor structure that will be filled with the values for each object returned in turn.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_NO_MORE_DATA]

There is no more data.

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAGetObject - get an object

SYNOPSIS

#include <xbsa.h>

int BSAGetObject(long bsaHandle,
                 BSA_ObjectDescriptor *objectDescriptorPtr,
                 BSA_DataBlock32 *dataBlockPtr)

DESCRIPTION

BSAGetObject() retrieves the BSA_ObjectDescriptor for the XBSA Object identified by the copyId and prepares the Backup Service to retrieve the XBSA Object Data.

The dataBlockPtr parameter in the BSAGetObject() call allows the caller to obtain information about the buffer structure required by the Backup Service. The caller obtains the object's data through subsequent BSAGetData() calls. The caller must terminate receipt of the data by using the BSAEndData() call.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_ObjectDescriptor *objectDescriptorPtr (I)

This parameter is a pointer to a data area used to pass the XBSA Object's copyId to the Backup Service.

BSA_DataBlock32 *dataBlockPtr (O)

This parameter points to a structure that is used to obtain the details of the required buffer structure.

EXTENDED DESCRIPTION

It is mandatory that the copyId field in the BSA_ObjectDescriptor structure is set as this is the only field that is checked. A copyId value of zero cannot identify a valid object. BSAGetObject() matches the copyId field for equality.

The dataBlockPtr structure does not point to an actual buffer. All values in the dataBlockptr should be zero, and will be overwritten. The structure is used by the Backup Service to provide the XBSA Application with the Service's preference for the structure of the data blocks that will be used to pass the object's data. The XBSA Application should examine the values returned in order to determine the buffer structure that it should create. The significance of the returned values is as follows:

bufferLen == 0	The Backup Service has no restrictions on the buffer length. No trailer portion is required.
bufferLen != 0	The Backup Service accepts buffers that are at least bufferLen bytes in length (minimum length). The length of the trailer portion of buffers is: trailerBytes >= (bufferLen - numBytes - headerBytes)
numBytes == 0	The Backup Service has no restrictions on the length of the data portion of the buffer.
numBytes != 0	The minimum length of the data portion of buffers accepted by the Backup Service must be numBytes bytes. If the Backup Service provides a larger data portion, the Backup Service may take advantage of it.
headerBytes == 0	The Backup Service only accepts buffers with no header portion.
headerBytes != 0	The length of the header portion of buffers accepted by the Backup Service is headerBytes bytes.
bufferPtr	Not used

The values returned by the Backup Service must conform to the relationships defined in BSA_DataBlock32 .

The values returned by the call to BSAGetObject() remain in effect for the duration of the data transfer of the object being created, that is, until the next BSAEndData() call.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_ACCESS_FAILURE]

Access to the requested object is not possible. Cannot retrieve object with given copyId.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_COPYID]

The copyId cannot be zero.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_OBJECT_NOT_FOUND]

The given copyId does not exist.

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAInit - initialize the environment and set up a session

SYNOPSIS

#include <xbsa.h>

int BSAInit(long *bsaHandlePtr, BSA_SecurityToken *tokenPtr,
            BSA_ObjectOwner *objectOwnerPtr, char **environmentPtr)

DESCRIPTION

The BSAInit() call authenticates the XBSA Application, sets up a session with the Backup Service and an environment for subsequent API calls for the caller. Nested sessions, and concurrent sessions in the same address space are not supported.

PARAMETERS

long *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)

If a Backup Service implementation provides its own authentication and access control, this parameter points to a security token that is to be used to authenticate the XBSA Application. The authentication is valid for the session and all calls using the returned session handle will be assumed to be made by the same XBSA Application.

If a NULL security token pointer is provided, the Backup Service can use a default, implementation-dependent security mechanism.

If this call returns [BSA_RC_AUTHENTICATION_FAILURE] the XBSA Application should consult an implementation dependent security API to resolve the failure. The XBSA Application can use BSAQueryServiceProvider() to determine whether and what security API to use.

BSA_ObjectOwner *objectOwnerPtr (I)

This parameter points to a structure used to specify both the bsa_ObjectOwner and the app_ObjectOwner. Only the bsa_ObjectOwner field is mandatory and must be specified using a non-empty null-terminated string. 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. If the BSA_ObjectOwner.bsa_ObjectOwner field for any of the XBSA calls used in this session is empty, it will default to the value specified in this call.

char **environmentPtr (I)

This parameter points to a structure that contains the new environment variables (keyword, value) pairs, for the session. The 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. The array of pointers is terminated by a NULL pointer.

EXTENDED DESCRIPTION

The following environment variables, to be provided by the XBSA Client, are defined as part of this Technical Standard.

Variable Name	Description	Format
BSA_API_VERSION	Mandatory. Specifies the version of the specification that the calling XBSA Application requires.	A string containing 3 numeric elements, (version, issue, level) separated by periods. For example, "1.1.0", identifies this document. See BSAQueryAPIVersion(). for example, 1.1.3
BSA_SERVICE_HOST	Optional. Identifies a specific host system on which the Backup Service is running. If this variable is not provided, an implementation-defined default host will be selected.	A string containing an implementation-defined host name. (Normally, this will depend on the underlying operating system environment.) for example, backup.xyz.com

Additional private variables are allowed as long as they are agreed upon by the XBSA Application and Backup Service. Variables defined by the XBSA Application but not interpreted by the Backup Service are silently ignored and not added to the Backup Service's environment variables. Variables required by the Backup Service and not specified by the client may result in a [BSA_RC_INVALID_ENV] error during a BSAInit() call. The BSAGetEnvironment() call only returns environment variables that are meaningful to the Backup Service. This allows the XBSA Application to discover which variables that it specified when calling BSAInit() were interpreted by the Backup Service. Since the XBSA Application is in control, it can always abort a session if it disagrees with the Backup Service about the environment.

When an XBSA Application connects to a Backup Service, it can make an initial call to BSAQueryApiVersion() to determine the highest version of the specification supported. If the client supports that version, it should specify it when calling BSAInit(). If the client 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 encounterered, and the BSA Application supports other versions, it may retry the call to BSAInit() specifying a different version.

All XBSA Application must set the BSA_API_VERSION environment variable in the environment structure used for the BSAInit() call. XBSA Applications that do not set this variable are assumed to be version 0.1.X clients by the Backup Service. The Backup Service will either reject such XBSA Application or provide a 0.1.X compatible API.

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. The BSA_SecurityToken or the BSA_ObjectOwner is invalid.

[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 encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

[BSA_RC_VERSION_NOT_SUPPORTED]

The Backup Service implementation does not support the specified version of the interface.

NAME

BSAQueryApiVersion - query for the current version of the API

SYNOPSIS

#include <xbsa.h>

int BSAQueryApiVersion(BSA_ApiVersion *apiVersionPtr)

DESCRIPTION

The BSAQueryApiVersion() call is used to determine the current version of the XBSA. The version information consists of the issue, version within the issue, and level within the version. If the Backup Services implementation supports more than one version, the latest version information will be returned.

PARAMETERS

BSA_ApiVersion *apiVersionPtr (O)

This parameter is a pointer to a structure that is to be used to return the current issue, version, and level, of the API.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_NULL_ARGUMENT]

A NULL apiVersion pointer was encountered.

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAQueryObject - query about object copies

SYNOPSIS

#include <xbsa.h>

int BSAQueryObject(long bsaHandle,
                   BSA_QueryDescriptor *queryDescriptorPtr,
                   BSA_ObjectDescriptor *objectDescriptorPtr)

DESCRIPTION

The BSAQueryObject() call initiates a request for information on object copies (for example, backup or archive) from a Backup Service. The results of the query will be determined by the search conditions specified in the queryDescriptor. The object descriptor for the first object satisfying the query search conditions is returned in the BSA_ObjectDescriptor (referenced by the BSA_ObjectDescriptorPtr parameter). The application can obtain the other object descriptors by successive calls to BSAGetNextQueryObject().

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_QueryDescriptor *queryDescriptorPtr (I)

This parameter is a pointer to a structure that contains the search conditions for the query.

BSA_ObjectDescriptor *objectDescriptorPtr (O)

This parameter is a pointer to a structure that is used to return the Object descriptor for the first object that satisfies the search condition specified in the query.

EXTENDED DESCRIPTION

This function may only be used as part of a retrieval transaction.

A limited wild-card capability is available as follows:

Data Type	Wild-card Options
string	"*" matches 0 or more characters "?" matches exactly one character "\*" matches a literal "*" "\?" matches a literal "?" "\\" matches a literal "\"
time	zero value = any time
enumerations	ANY value matches any value
BSA_ObjectOwner	defaults to value specified at session initialization

The following examples illustrate wild-card string matching:

BSA_ObjectName.pathName = /server/*	would match all objects for this server
BSA_ObjectName.pathName = /server/rootdbs/*	would match all levels of rootdbs
BSA_ObjectName.pathName = /server/????	would match all levels whose name is exactly 4 characters long

String matching is performed without any interpretation of the string contents. There is no implied knowledge of the structure of the string contents.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_ACCESS_FAILURE]

Access to the requested object descriptor is not permitted.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_INVALID_QUERYDESCRIPTOR]

The BSA_QueryDescriptor was invalid.

[BSA_RC_NO_MATCH]

No objects matched the given query.

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSAQueryServiceProvider - retrieve a string identifying the Backup Service provider

SYNOPSIS

#include <xbsa.h>

int BSAQueryServiceProvider(BSA_UInt32 *sizePtr, char *delimiter, 
                            char *providerPtr)

DESCRIPTION

The BSAQueryServiceProvider() call returns a hierarchical string identifying the Backup Service provider. The content of the string is implementation dependent.

PARAMETERS

BSA_UInt32 *sizePtr (I/O)

This parameter contains the size of the provider buffer in bytes.

char *delimiter (O)

This parameter points to the character that is used to delimit fields in the provider hierarchical string.

char *providerPtr (O)

This parameter points to a data area that contains an implementation-dependent hierarchical string which conveys information identifying the Backup Service provider.

EXTENDED DESCRIPTION

The format of the provider string is the same as that of the BSA_SERVICE_PROVIDER environment variable (see BSAGetEnvironment()). The delimiter character is returned in the delimiter parameter.

If a [BSA_RC_BUFFER_TOO_SMALL] error is encountered, the required size is returned in the sizePtr parameter. If the XBSA Application sets the sizePtr parameter to zero, this will force a [BSA_RC_BUFFER_TOO_SMALL] error, thus providing a mechanism to query the required size.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_BUFFER_TOO_SMALL]

The size of the data buffer is invalid.

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSASendData - send a byte stream of data in a buffer

SYNOPSIS

#include <xbsa.h>

int BSASendData(long bsaHandle, BSA_DataBlock32 *dataBlockPtr)

DESCRIPTION

BSASendData() sends a byte stream of data to a Backup Service in a buffer. The calling application can pass any data for storage in the XBSA system. BSASendData() can be called multiple times, in case the byte stream of data to be sent is large. This call may be used only after a BSACreateObject() or another BSASendData() call.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

BSA_DataBlock32 *dataBlockPtr (I)

This parameter points to a structure that includes both a pointer to the buffer from which the data is to be sent, as well as the size of the buffer.

EXTENDED DESCRIPTION

The Backup Service may not overwrite any of the fields in the BSA_DataBlock32 structure. The Backup Service may write into the header and trailer portions of the buffer.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_INVALID_CALL_SEQUENCE]

The sequence of API calls is incorrect.

[BSA_RC_INVALID_DATABLOCK]

The BSA_DataBlock32 parameter contained an inconsistent value.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_NULL_ARGUMENT]

A NULL pointer was encounterered in one of the arguments

[BSA_RC_SUCCESS]

The function succeeded.

NAME

BSATerminate - terminate a session

SYNOPSIS

#include <xbsa.h>

int BSATerminate(long bsaHandle)

DESCRIPTION

The BSATerminate() call terminates the session with the Backup Service that was set up by a previous BSAInit() call and is associated with the bsaHandle. It also releases any resources acquired to set up the environment for the session. The Backup Service should allow a grace period before deallocating devices or rewinding tapes. If BSATerminate() is called within a transaction, the transaction will be aborted.

PARAMETERS

long bsaHandle (I)

This parameter is the handle that associates this call with a previous BSAInit() call.

RETURN VALUE

The following return codes are returned by this function:

[BSA_RC_ABORT_SYSTEM_ERROR]

System detected error, operation aborted.

[BSA_RC_INVALID_HANDLE]

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

[BSA_RC_SUCCESS]

The function succeeded.