dsmSendObj

The dsmSendObj call processes the data for the object as a byte stream passed in memory buffers. The dataBlkPtr parameter in the dsmSendObj call permits the application client to either:

• Pass the data and the attributes (the attributes are passed through the objAttrPtr ) of the object in a single call.
• Specify part of the object data through the dsmSendObj call and the remainder of the data through one or more dsmSendData calls.

Before dsmSendObj is called, a preceding dsmBindMC call must be made to properly bind a management class to the object that you want to back up or archive. The API keeps this binding so that it can associate the proper management class with the object when it is sent to the server. If you permit the management class that is bound on a dsmSendObj call to default for an object type of directory (DSM_OBJ_DIRECTORY), the default might not be the default management class. Instead, the management class with the greatest retention time is used. If more than one management class exists with this retention time, the first one that is encountered is used.

Follow all object data that is sent to storage with a dsmEndSendObj call. If you do not have object data to send to the server, or all data was contained within the dsmSendObj call, start a dsmEndSendObj call before you can start another dsmSendObj call. If multiple data sends were required through the dsmSendData call, the dsmEndSendObj follows the last send to indicate the state change.

Parameters

dsUint32_t dsmHandle (I)

The handle that associates this call with a previous dsmInitEx call.

dsmSendType sendType (I)

This parameter specifies the type of send that is being performed. Possible values include:

	Name	Description
	stBackup	A backup object that is sent to the server.
	stArchive	An archive object that is sent to the server.
	stBackupMountWait	A backup object for which you want the server to wait until the necessary device, such as a tape, is mounted.
	stArchiveMountWait	An archive object for which you want the server to wait until the necessary device, such as a tape, is mounted.

Note: Use the MountWait types if there is any possibility that your application user might send data to a tape.

void *sendBuff (I)

This parameter is a pointer to a structure that contains other information specific to the sendType on the call. Currently, only a sendType of stArchive has an associated structure. This structure is called sndArchiveData and it contains the archive description.

dsmObjName *objNameP (I)

This parameter is a pointer to the structure that contains the file space name, high-level object name, low-level object name, and object type. See Object names and IDs for more information.

ObjAttr *objAttrPtr (I)

This parameter passes object attributes of interest to the application. See API type definitions source files for the type definition.

The attributes are:

• owner refers to the owner of the object. Determining whether the owner is declared to be a specific name or an empty string is important when getting the object back from Tivoli Storage Manager storage. See Accessing objects as session owner for more information.
• sizeEstimate is a best estimate of the total size of the data object to send to the server. Be as accurate as possible on this size, because the server uses this attribute for efficient space allocation and object placement within its storage resources.
  If the size estimate that you specified is significantly smaller than the actual number of bytes that are sent, the server might have difficulty allocating enough space and end the transaction with a reason code of 11 (DSM_RS_ABORT_NO_REPOSIT_SPACE).

  Note: The size estimate is for the total size of the data object in bytes.

  Objects with a size smaller than DSM_MIN_COMPRESS_SIZE do not compress.

  If your object has no bit data (only the attribute information from this call), the sizeEstimate should be zero.

  Note: Starting with Version 5.1.0, the copy destination within a transaction is not checked for consistency on zero-length objects.
• objCompressed is a Boolean value that states whether or not the object data have already been compressed.

  If the object is compressed (object compressed=bTrue), Tivoli Storage Manager does not try to compress it again. If it is not compressed, Tivoli Storage Manager decides whether to compress the object, based on the values of the compression option set by the Tivoli Storage Manager administrator and set in the API configuration sources.

  If your application plans to use partial object restore or retrieve, you cannot compress the data while sending it. To enforce this, set ObjAttr.objCompressed to bTrue.

• objInfo saves information about the particular object.
  Note: Information is not stored here automatically. When this attribute is used, the attribute, objInfoLength, also must be set to show the length of objInfo.
• mcNameP contains the name of a management class that overrides the management class that is obtained from dsmBindMC.
• disableDeduplication is a Boolean value. When it is set to true, this object is not deduplicated by the client.

DataBlk *dataBlkPtr (I/O)

This parameter points to a structure that includes both a pointer to the buffer of data that is to be backed up or archived and the size of that buffer. This parameter applies to dsmSendObj only. If you want to begin sending data on a subsequent dsmSendData call, rather than on the dsmSendObj call, set the buffer pointer in the DataBlk structure to NULL. On return, this structure contains the number of bytes that is actually transferred. See API type definitions source files for the type definition.

Return codes

The return code numbers are provided in parentheses ( ).