Veritas NetBackup™ DataStore SDK Programmer's Guide for XBSA 1.1.0

BSACreateObject

Create an XBSA object.

SYNOPSIS

#include <xbsa.h>

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

DESCRIPTION

The BSACreateObject() call creates an XBSA object within NetBackup. Duplicate BSA_ObjectNames are allowed.

The BSACreateObject() call is used to create an XBSA object based on the information in the objectDescriptor. This call initiates the communication between the NetBackup XBSA interface and the NetBackup server. The XBSA object data can then be passed in memory buffers. The dataBlockPtr parameter in the BSACreateObject() call allows the caller to obtain information about the buffer structure required by the NetBackup XBSA interface.

The XBSA object 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 XBSA object. The BSASendData() and BSAEndData() calls must follow the BSACreateObject() call and must be in the same transaction.

PARAMETERS

EXTENDED DESCRIPTION

Within the XBSA 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 XBSA 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 defaults to the value specified in BSAInit().

The following fields in the XBSA 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 application intends to create a non-empty XBSA object (that is, there is XBSA object data). This size is in bytes. If the estimatedSize is zero, this call must be followed by a BSAEndData() without calling BSASendData() in between. There are no resource allocations based on this estimate, only whether the object will have data or not, so the estimate does not need to be accurate.

The NetBackup XBSA interface can return several values to the XBSA application through the objectDescriptorPtr for a newly created XBSA object. The interface returns either all or none of these values.

The copyId attribute is a persistent, fixed-length object identifier that remains unchanged throughout the life of the XBSA object.

If the copyId field is non-zero, the NetBackup XBSA interface returned values for the copyId, createTime, restoreOrder, and objectStatus fields.

The createTime field is in UTC. The restoreOrder field can have the value zero, which means that the NetBackup XBSA interface did not specify a restore order.

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

The values returned by the call to BSACreateObject() remain in effect for the duration of the data transfer of the XBSA object being created, that is, until the next BSAEndData() call. The NetBackup XBSA interface currently does not have any header or trailer requirements, so the full buffer specified can be used by the XBSA application. This is documented for completeness with the XBSA specification and to allow for future use of these fields as specified by the XBSA specifications.

RETURN VALUE

The following return codes are returned by this function: