Tivoli Header

Tivoli Storage Manager Using the Application Program Interface

dsmGetNextQObj

The dsmGetNextQObj function call gets the next query response from a previous dsmBeginQuery call and places it in the caller's buffer. The dsmGetNextQObj call is called one or more times. Each time it is called, a single query record is retrieved. If the application client needs to end the query before retrieving all of the data, you can send a dsmEndQuery call.

The dataBlkPtr must point to a buffer that is defined with the qryResp*Data structure type. The context in which dsmGetNextQObj is called determines the type of structure that is entered on the query response.

Syntax

dsInt16_t dsmGetNextQObj  (dsUint32_t   dsmHandle,
   DataBlk *dataBlkPtr);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

DataBlk *dataBlkPtr (I/O)
Points to a structure that includes both a pointer to the buffer for the data to be received and the size of the buffer. This buffer is the qryResp*Data structure that is described below. On return, this structure contains the number of bytes that is actually transferred. See Appendix A, API Type Definitions Source File for the type definition of DataBlk. The structure associated with each type of query is:

Table 29. DataBlk Pointer Structure

Query Response Structure Fields
qtArchive qryRespArchiveData sizeEstimate. This field contains the value that is passed on a previous dsmSendObj call.
qtBackup qryRespBackupData restoreOrderExt. This field is of type dsUint16_t. Sort on this field when restoring several objects on a dsmBeginGetData call. An example of sorting code for this is in the API sample, dapiqry.c. See also Figure 16 for a sorting example.

sizeEstimate. This field contains the value that is passed on a previous dsmSendObj call.

qtBackupActive qryARespBackupData --
qtFilespace qryRespFSData backStartDate. This field contains the server's time stamp when the file space was updated with the backStartDate action.

backCompleteDate. This field contains the server time stamp when the filespace was updated with the backCompleteDate action.

qtMC qryRespMCData
qryRespMCDetailData
--

Return Codes

The return code numbers are provided in parentheses ( ).

Table 30. Return Codes for dsmGetNextQObj

Return Code Explanation
DSM_RC_ABORT_NO_MATCH (2) No match for the query was requested.
DSM_RC_FINISHED (121) Finished processing (start dsmEndQuery).
DSM_RC_UNKNOWN_FORMAT (122) The file that TSM attempted to restore or retrieve has an unknown format.
DSM_RC_COMM_PROTOCOL_ERROR (136) Communication protocol error.
DSM_RC_NULL_DATABLKPTR (2001) Pointer is not pointing to a data block.
DSM_RC_INVALID_MCNAME (2025) Invalid management class name.
DSM_RC_BAD_CALL_SEQUENCE (2041) The sequence of calls is invalid.
DSM_RC_WRONG_VERSION_PARM (2065) Application client's API version is different from the TSM library version.
DSM_RC_MORE_DATA (2200) There is more data to get.
DSM_RC_BUFF_TOO_SMALL (2210) Buffer is too small.


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