dsmGetNextQObj

Edit online

The dsmGetNextQObj function call gets the next query response from a previous dsmBeginQuery call and places the response in the caller buffer.

The dsmGetNextQObj call is called one or more times. Each time the function is called, either a single query record is retrieved, or an error or a DSM_RC_FINISHED reason code is returned. If DSM_RC_FINISHED is returned, there is no more data to process. When all query data is retrieved, or if no more query data is needed, send the dsmEndQuery call to end the query process.

The dataBlkPtr parameter 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 response structure. On return, this structure contains the number of bytes that is transferred. The structure that is associated with each type of query is described in the following table. For more information about the type definition of DataBlk, see the following topic: API type definitions source files.

Table 1. DataBlk pointer structure
Query	Response structure	Fields of special interest
qtArchive	qryRespArchiveData	sizeEstimate Contains the value that is passed on a previous dsmSendObj call. mediaClass Can have a value of `MEDIA_FIXED` if the object is on disk, or `MEDIA_LIBRARY` if the object is on tape. clientDeduplicated Indicates whether this object is deduplicated by the client.
qtBackup	qryRespBackupData	restoreOrderExt Is of type `dsUint16_t`. Sort on this field when several objects are restored on a dsmBeginGetData call. An example of sorting code for this call is in the API sample, `dapiqry.c`. For a sorting example, see the following topic: Figure 1. sizeEstimate Contains the value that is passed on a previous dsmSendObj call. mediaClass Can have a value of `MEDIA_FIXED` if the object is on disk or `MEDIA_LIBRARY` if the object is on tape. clientDeduplicated Indicates whether this object is deduplicated by the client.
qtBackupActive	qryARespBackupData
qtBackupGroups	qryRespBackupData	dsBool_t isGroupLeader If true, signifies this object is a group leader.
qtOpenGroups	qryRespBackupData	dsBool_t isOpenGroup; If true, signifies this group is open and not complete.
qtFilespace	qryRespFSData	backStartDate Contains the server time stamp when the file space is updated with the backStartDate action. backCompleteDate Contains the server time stamp when the file space is updated with the backCompleteDate action. lastReplStartDate Contains the time stamp for the last time that replication was started on the server. lastReplCmpltDate Contains the time stamp for the last time that replication was completed, even if there was a failure. lastBackOpDateFromServer Contains the last store time stamp that was saved on the server. lastBackOpDateFromLocal Contains the last store time stamp that was saved on the client.
qtMC	qryRespMCData qryRespMCDetailData
qtProxyNodeAuth	qryRespProxyNodeData targetNodeName peerNodeName hlAddress llAddress
qtProxyNodePeer	qryRespProaxyNodeData targetNodeName peerNodeName hlAddress llAddress

Return codes

The following table describes the return codes for the dsmGetNextQObj function call.

Table 2. Return codes for the dsmGetNextQObj function call
Return code	Return code number	Description
`DSM_RC_ABORT_NO_MATCH`	2	No match for the query was requested.
`DSM_RC_FINISHED`	121	Finished processing (start dsmEndQuery). There is no more data to process.
`DSM_RC_UNKNOWN_FORMAT`	122	The file that IBM® Storage Protect 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	The version of the application client API is different from the IBM Storage Protect library version.
`DSM_RC_MORE_DATA`	2200	There is more data to get.
`DSM_RC_BUFF_TOO_SMALL`	2210	Buffer is too small.