Using the Application Program Interface

dsmSendObj

Use dsmSendObj to initiate a request to send a single object to ADSM 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 allows the application client to either:

• pass the data and the attributes (the attributes are passed via 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.

An alternative is for the application client to specify only the attributes through the dsmSendObj call and to specify the object data through one or more calls to dsmSendData. For this latter alternative, set dataBlkPtr on the dsmSendObjcall to NULL. Note that for certain object types, byte stream data might not be associated with the data at all. An example of such an object could be a directory entry with no extended attributes.

Before dsmSendObj can be called, a preceding dsmBindMC call must be made to properly bind a management class to the object being backed up or archived. The ADSM API retains this binding so that it can associate the proper management class with the object when it is sent to the server.

All object data sent to ADSM storage must be followed by a dsmEndSendObj call. Thus, if you do not have object data to send to the server or all data was contained within the dsmSendObj call, you must issue a dsmEndSendObj call before another dsmSendObj call can be made. If multiple data sends were required via the dsmSendData call, the dsmEndSendObj follows the last send to indicate the state change.

Note:

If ADSM returns code 157 (DSM_RC_WILL_ABORT), issue a call to dsmEndTxn with a vote of DSM_VOTE_COMMIT. The application should then get back return code 2302 (DSM_RC_CHECK_REASON_CODE) and pass the reason code back to the application user. This will tell the user why the server is aborting 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 dsmSendObj  (dsUint32       dsmHandle,
   dsmSendType  sendType,
   void        *sendBuff,
   dsmObjName  *objNameP,
   ObjAttr     *objAttrPtr,
   DataBlk     *dataBlkPtr);

Parameters

dsUint32 dsmHandle (I)

This parameter is the handle that associates this call with a previous dsmInit call.

dsmSendType sendType (I)

This parameter specifies the type of send being performed. Possible values are:

stBackup

Specifies that this is a backup object being sent to the server

stArchive

Specifies that this is an archive object being sent to the server

stBackupMountWait

Specifies that this is a backup object for which you want the server to wait until the necessary device, such as a tape, is mounted

stArchiveMountWait

Specifies that this is 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 your application user may 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 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 "Identifying the Object" for more information.

ObjAttr *objAttrPtr (I)

This parameter is used to pass object attributes of interest to the application. See Appendix A. "API Type Definitions Source File" for the type definition.

The attributes of particular interest are:

• owner -- This attribute refers to the owner of the object. Whether the owner is declared to be a specific name or an empty string is important when getting the object back from ADSM storage. See "Accessing Objects" for more information.

• sizeEstimate -- The size estimate attribute is a best estimate of the total size of the data object to be sent to the server. It is important that you try to be as accurate as possible on this size, because the ADSM server uses this attribute for efficient space allocation and object placement within its storage resources. Not specifying this value can result in performance degradation on the server because allocations will have to be made on a best guess basis.

  If the size estimate specified is significantly smaller than the actual number of bytes sent, the server may have difficulty allocating enough space and abort the transaction with a reason code 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 will not be compressed.

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

• objCompressed -- This attribute is a boolean value that states whether or not the object data has already been compressed.

  If the object is compressed, ADSM does not try to compress it again. If it is not compressed, ADSM decides whether to compress the object, based on the values of the COMPRESSION option set by the ADSM administrator and set in the API configuration file and the client option files (dsm.sys in UNIX and dsm.opt in Windows).

  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 -- This attribute can be used to save information about the particular object. Note that no information is stored here automatically. When this attribute is used, the attribute objInfoLength must also be set to show the length of objInfo.

• mcNameP -- This attribute contains the name of a management class that overrides the default management class obtained from dsmBindMC.

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 wish 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 actually transferred. See Appendix A. "API Type Definitions Source File" for the type definition.

Return Codes

Figure 44. Return Codes for dsmSendObj

Return Code	Explanation
DSM_RC_NO_COMPRESS_MEMORY (154)	Insufficient memory available to do 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)	File space not registered.
DSM_RC_WRONG_VERSION_PARM (2065)	Application client's API version is different than the ADSM library version.
DSM_RC_NEEDTO_ENDTXN (2070)	Need to end transaction.
DSM_RC_OBJ_EXCLUDED (2080)	The object is excluded by the include-exclude list.
DSM_RC_OBJ_NOBCG (2081)	The object has no backup copy group and will not be sent to the server.
DSM_RC_OBJ_NOACG (2082)	The object has no archive copy group and 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)	File space 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.