dsmBeginGetData

Edit online

The dsmBeginGetData function call starts a restore or retrieve operation on a list of objects in storage. This list of objects is contained in the dsmGetList structure. The application creates this list with values from the query that preceded a call to dsmBeginGetData.

The caller first must use the restore order fields that are obtained from the object query to sort the list that is contained in this call. This ensures that the objects are restored from storage in the most efficient way possible without rewinding or remounting data tapes.

When getting whole objects, the maximum dsmGetList.numObjID is DSM_MAX_GET_OBJ. When getting partial objects, the maximum is DSM_MAX_PARTIAL_GET_OBJ.

Follow the call to dsmBeginGetData with one or more calls to dsmGetObj to obtain each object within the list. After each object is obtained, or additional data for the object is not needed, the dsmEndGetObj call is sent.

When all objects are obtained, or the dsmEndGetObj is canceled, the dsmEndGetData call is sent. You then can start the cycle again.

Syntax

dsInt16_t dsmBeginGetData (dsUint32_t       dsmHandle,
   dsBool_t     mountWait,
   dsmGetType   getType,
   dsmGetList  *dsmGetObjListP);

Parameters

dsUint32_t dsmHandle (I)

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

dsBool_t mountWait (I)

A Boolean true or false value indicates whether or not the application client waits for offline media to be mounted if the data that is needed is currently offline. If mountWait is true, the application waits for the server to mount the required media. The application waits until the media is mounted or the request is canceled.

dsmGetType getType (I)

An enumerated type consisting of gtBackup and gtArchive that indicates what type of object to get.

dsmGetList *dsmGetObjListP (I)

The structure that contains information about the objects or partial objects to restore or retrieve. The structure points to a list of object IDs and, in the case of a partial object restore or retrieve, a list of associated offsets and lengths. If your application uses the partial object restore or retrieve function, set the dsmGetList.stVersion field to dsmGetListPORVersion. In a partial object restore or retrieve, you cannot compress data while sending it. To enforce this, set ObjAttr.objCompressed to bTrue.

See Figure 1 and API type definitions source files for more information on this structure.

See Partial object restore or retrieve for more information on partial object restore or retrieve.

Return codes

The return code numbers are provided in parentheses ( ).

Table 1. Return codes for dsmBeginGetData
Return code	Explanation
DSM_RC_ABORT_INVALID_OFFSET (33)	The offset that was specified during a partial object retrieve is greater than the length of the object.
DSM_RC_ABORT_INVALID_LENGTH (34)	The length that was 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_NO_MEMORY (102)	There is no RAM remaining to complete the request.
DSM_RC_NUMOBJ_EXCEED (2029)	The dsmGetList.numObjId is greater than DSM_MAX_GET_OBJ.
DSM_RC_OBJID_NOTFOUND (2063)	The object ID was not found. The object was not restored.
DSM_RC_WRONG_VERSION_PARM (2065)	The API version of the application client is different from the IBM® Storage Protect library version.