dsmGetObj

Edit online

The dsmGetObj function call obtains the requested object data from the IBM® Storage Protect data stream and places it in the caller's buffer. The dsmGetObj call uses the object ID to obtain the next object or partial object from the data stream.

The data for the indicated object is placed in the buffer to which DataBlk points. If more data is available, you must make one or more calls to dsmGetData to receive the remaining object data until a return code of DSM_RC_FINISHED is returned. Check the numBytes field in DataBlk to see whether any data remains in the buffer.

Objects should be asked for in the order that they were listed on the dsmBeginGetData call in the dsmGetList parameter. The exception is when the application client needs to pass over an object in the data stream to get to an object later in the list. If the object that is indicated by the object ID is not the next object in the stream, the data stream is processed until the object is located, or the stream is completed. Use this feature with care, because it might be necessary to process and discard large amounts of data to locate the requested object.

Requirement: If dsmGetObj returns a failure code (NOT FINISHED or MORE_DATA), the session must be terminated to stop the restore operation. This is especially important when you use encryption and receive a RC_ENC_WRONG_KEY. You must start a new session with the proper key.

Syntax

dsInt16_t dsmGetObj (dsUint32_t dsmHandle,
   ObjID    *objIdP,
   DataBlk  *dataBlkPtr);

Parameters

dsUint32_t dsmHandle (I): The handle that associates this call with a previous dsmInitEx call.
ObjID *objIdP (I): A pointer to the ID of the object to restore.
DataBlk *dataBlkPtr (I/O): A pointer to the buffer where the restored data are placed.

Return codes

The return code numbers are provided in parentheses ( ).

Table 1. Return codes for dsmGetObj
Return code	Explanation
DSM_RC_ABORT_INVALID_OFFSET (33)	The offset that is specified during a partial object retrieve is greater than the length of the object.
DSM_RC_ABORT_INVALID_LENGTH (34)	The length that is specified during a partial object retrieve is greater than the length of the object, or the offset in addition to the length extends past the end of the object.
DSM_RC_FINISHED (121)	Finished processing (start dsmEndGetObj).
DSM_RC_WRONG_VERSION_PARM (2065)	Application client's API version is different from the IBM Storage Protect library version.
DSM_RC_MORE_DATA (2200)	There is more data to get.
RC_ENC_WRONG_KEY (4580)	The key provided in the dsmInitEx call, or the saved key, does not match the key that was used to encrypt this object. Terminate the session and provide the proper key.