db2ACSBeginQuery - begin a query about snapshot backup objects

Begins a Db2® Advanced Copy Services (ACS) query operation about snapshot backup objects that are available to be used for restore operations.

Include file

db2ACSApi.h

Syntax and data structures


db2ACS_RC db2ACSBeginQuery(
               db2ACS_QueryInput       * pQueryInput,
               db2ACS_CB               * pControlBlock,
               db2ACS_ReturnCode       * pRC );

Parameters

pQueryInput
Data type: db2ACS_QueryInput *

db2ACS_QueryInput has the same fields as db2ACS_ObjectInfo. db2ACS_ObjectInfo contains information about object created using the Db2 Advanced Copy Services (ACS) API.

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.

Before calling db2ACSBeginQuery(), the database manager populates the fields of pQueryInput.

The Db2 ACS API driver must support the use of the following wildcards in the query:

  • DB2ACS_WILDCARD in string fields
  • DB2ACS_ANY_PARTITIONNUM for database partition fields
  • DB2ACS_ANY_UINT32 for 32-bit unsigned integer (Uint32) fields
pControlBlock
Data type: db2ACS_CB *

db2ACS_CB contains fundamental information required to initialize and terminate a Db2 ACS session.

Before calling db2ACSBeginQuery(), the database manager populates the following fields:


     pControlBlock->handle
     pControlBlock->vendorInfo
     pControlBlock->options
pRC
Data type: db2ACS_ReturnCode *

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 Codes

Table 1. Return codes
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.
If the Db2 ACS API driver encounters an error, the driver might abort a Db2 ACS operation. The Db2 ACS session cannot be used for any action other than the following:
  • If a call to db2ACSBeginQuery() previously succeeded the database manager can call db2ACSEndQuery()
  • If a call to db2ACSBeginOperation() previously succeeded, the database manager can call db2ACSEndOperation()
  • If a call to db2ACSInitialize() previously succeeded, the database manager can call db2ACSTerminate()

For more information about Db2 ACS API return codes, see the topic: Db2 Advanced Copy Services (ACS) API return codes.

Usage notes

db2ACSBeginQuery() does not return any query data.