![]() |
![]() |
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.
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.
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.
dsInt16_t dsmSendObj (dsUint32_t dsmHandle, dsmSendType sendType, void *sendBuff, dsmObjName *objNameP, ObjAttr *objAttrPtr, DataBlk *dataBlkPtr);
Parameters
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. |
The attributes are:
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).
Objects with a size smaller than DSM_MIN_COMPRESS_SIZE will not compress.
If your object has no bit data (only the attribute information from this call), the sizeEstimate should be zero.
If the object is compressed (object compressed=bTrue), TSM does not try to compress it again. If it is not compressed, TSM decides whether to compress the object, based on the values of the compression option set by the TSM 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.
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. |