Returns the next item in a list of snapshot backup objects that are available to be used for a restore operation.
db2ACSApi.h
db2ACS_RC db2ACSGetNextObject(
db2ACS_QueryOutput * pQueryOutput,
db2ACS_CB * pControlBlock,
db2ACS_ReturnCode * pRC );
db2ACS_QueryOutput contains query result information about snapshot backup objects.
The database manager allocates the memory for this parameter, and passes a pointer to that instantiated object to the function. The database manager is responsible for freeing this memory.
The DB2® ACS API driver populates the fields of pQueryOutput before returning.
db2ACS_CB contains fundamental information required to initialize and terminate a DB2 ACS session.
Before calling db2ACSGetNextObject(), the database manager populates the following fields:
pControlBlock->handle
pControlBlock->vendorInfo
pControlBlock->options
db2ACS_ReturnCode contains diagnostic information including message text and error codes specific to the storage hardware. The contents of a db2ACS_ReturnCode parameter for a DB2 ACS API function call will be recorded in the database manager diagnostic logs.
The database manager allocates the memory for this parameter, and passes a pointer to that instantiated object to the function. The database manager is responsible for freeing this memory.
The DB2 ACS API driver populates the fields of pRC before returning.
Return code | Description | Notes |
---|---|---|
DB2ACS_RC_OK | The operation was successful. | |
DB2ACS_RC_INV_ACTION | The database manager requested an action from the DB2 ACS API driver that is invalid. | The DB2 ACS API driver encountered an error. The database manager cannot use the DB2 ACS API session. |
DB2ACS_RC_INV_DEV_HANDLE | The database manager passed a storage device handle that is invalid. | The DB2 ACS API driver encountered an error. The database manager cannot use the DB2 ACS API session. |
DB2ACS_RC_DEV_ERROR | There was an error with a storage device, such as a tape drive. | The DB2 ACS API driver encountered an error. The database manager cannot use the DB2 ACS API session. |
DB2ACS_RC_IO_ERROR | The DB2 ACS API driver encountered an error resulting from input or output operations. | The DB2 ACS API driver encountered an error. The database manager cannot use the DB2 ACS API session. |
DB2ACS_RC_OBJ_NOT_FOUND | The DB2 ACS API driver could not find the snapshot backup object specified by the database manager. | The function call didn't fail, but there are no snapshot backup objects that match the criteria passed to db2ACSBeginQuery(). |
DB2ACS_RC_END_OF_DATA | The DB2 ACS API driver cannot find any more snapshot backup objects. | The function call didn't fail, but there are no more snapshot backup objects that match the criteria passed to db2ACSBeginQuery(). |
DB2ACS_RC_MORE_DATA | There is more data to be transferred from the storage location to the database manager. | Information about a snapshot backup object that matches the criteria passed to db2ACSBeginQuery() is returned, and there are more snapshot backup objects that match the criteria passed to db2ACSBeginQuery(). |
For more information about DB2 ACS API return codes, see the topic: DB2 Advanced Copy Services (ACS) API return codes.
The database manager must call db2ACSBeginQuery() before calling db2ACSGetNextObject(). The database manager specifies the search criteria in the db2ACS_QueryInput parameter passed to db2ACSBeginQuery().
db2ACSGetNextObject() returns information about one snapshot backup object that matches the search criteria passed to db2ACSBeginQuery(). If db2ACSGetNextObject() returns DB2ACS_RC_MORE_DATA, the database manager can call db2ACSGetNextObject() again to receive information about another snapshot backup object that matches the search criteria. If db2ACSGetNextObject() returns DB2ACS_RC_END_OF_DATA, there are no more snapshot backup objects that match the search criteria.