Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

dsmBeginGetData

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.

If you use DSM_MAX_GET_OBJ, the list can contain every object that is defined. If you use DSM_MAX_PARTIAL_GET_OBJ, the list can contain partial objects.

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 get 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 is willing to wait for offline media to be mounted if the data that is needed is currently offline. If mountWait is true and the server device is not available, the server option, IDLETIMEOUT, will determine how long the application will wait.

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 19 and Appendix A, API Type Definitions Source File for more information on this structure.

See page *** for more information on partial object restore or retrieve.

Return Codes

The return code numbers are provided in parentheses ( ).

Table 17. 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 TSM library version.


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