Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

dsmSendObj

The dsmSendObj function call starts a request to send a single object to storage. Multiple dsmSendObj calls and associated dsmSendData calls can be made within the bounds of a transaction for performance reasons.

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:

Alternatively, the application client can specify only the attributes through the dsmSendObj call and specify the object data through one or more calls to dsmSendData. For this method, set dataBlkPtr to NULL on the dsmSendObj call.

Note:
For certain object types, byte stream data might not be associated with the data; for example, a directory entry with no extended attributes.

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 will be used. If more than one management class exists with this retention time, the first one that is encountered will be 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.

Note:
If TSM returns code 157 (DSM_RC_WILL_ABORT), start a call to dsmEndTxn with a vote of DSM_VOTE_COMMIT. The application should then receive return code 2302 (DSM_RC_CHECK_REASON_CODE) and pass the reason code back to the application user. This will inform the user why the server is ending the transaction.

If the reason code is 11 (DSM_RS_ABORT_NO_REPOSIT_SPACE), it is possible that the sizeEstimate is too small for the actual amount of data. The application needs to determine a more accurate sizeEstimate and send the data again.

Syntax

dsInt16_t dsmSendObj  (dsUint32_t       dsmHandle,
   dsmSendType  sendType,
   void        *sendBuff,
   dsmObjName  *objNameP,
   ObjAttr     *objAttrPtr,
   DataBlk     *dataBlkPtr);

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:
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 filespace name, high-level object name, low-level object name, and object type. See Identifying the Object for more information.

ObjAttr *objAttrPtr (I)
This parameter passes object attributes of interest to the application. See Appendix A, API Type Definitions Source File for the type definition.

The attributes are:

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 Appendix A, API Type Definitions Source File for the type definition.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 42. Return Codes for dsmSendObj

Return Code Explanation
DSM_RC_NO_COMPRESS_MEMORY (154) Insufficient memory available to perform data compression or expansion.
DSM_RC_COMPRESS_GREW (155) During compression, the compressed data grew in size compared to the original data.
DSM_RC_WILL_ABORT (157) An unknown and unexpected error occurred, causing the transaction to be halted.
DSM_RC_TL_NOACG (186) The management class for this file does not have a valid copy group for the send type.
DSM_RC_NULL_OBJNAME (2000) Null object name.
DSM_RC_NULL_OBJATTRPTR (2004) Null object attribute pointer.
DSM_RC_INVALID_OBJTYPE (2010) Invalid object type.
DSM_RC_INVALID_OBJOWNER (2019) Invalid object owner.
DSM_RC_INVALID_SENDTYPE (2022) Invalid send type.
DSM_RC_WILDCHAR_NOTALLOWED (2050) Wildcard characters not allowed.
DSM_RC_FS_NOT_REGISTERED (2061) Filespace not registered.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different from the TSM library version.
DSM_RC_NEEDTO_ENDTXN (2070) Need to end transaction.
DSM_RC_OBJ_EXCLUDED (2080) The include-exclude list excluded the object.
DSM_RC_OBJ_NOBCG (2081) The object has no backup copy group, and it will not be sent to the server.
DSM_RC_OBJ_NOACG (2082) The object has no archive copy group, and it will not be sent to the server.
DSM_RC_DESC_TOOLONG (2100) Description is too long.
DSM_RC_OBJINFO_TOOLONG (2101) Object information is too long.
DSM_RC_HL_TOOLONG (2102) High-level qualifier is too long.
DSM_RC_FILESPACE_TOOLONG (2104) Filespace name is too long.
DSM_RC_LL_TOOLONG (2105) Low-level qualifier is too long.
DSM_RC_NEEDTO_CALL_BINDMC (2301) dsmBindMC must be called first.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]