db2ACSRetrieveMetaData - retrieve metadata about a recovery object generated using Db2 Advanced Copy Services (ACS)
Retrieves metadata about a recovery object that was created using Db2 Advanced Copy Services (ACS)
Include file
db2ACSApi.h
Syntax and data structures
db2ACS_RC db2ACSRetrieveMetaData(
db2ACS_MetaData * pMetaData,
db2ACS_ObjectID objectID,
db2ACS_CB * pControlBlock,
db2ACS_ReturnCode * pRC );
Parameters
- pMetaData
- Data type:
db2ACS_MetaData
db2ACS_MetaData
stores snapshot backup meta data.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 metadata stored in the data field of pMetaData is internal to the database manager, and might change over time, so the Db2 ACS API driver just treats this data as a binary stream.
- objectID
- Data type:
db2ACS_ObjectID
A
db2ACS_ObjectID
is a unique identifier for each stored object, which is returned by a query to the storage repository. Adb2ACS_ObjectID
is guaranteed to be unique and persistent only within the timeframe of a single Db2 ACS session.The database manager can use db2ACSQuery() to obtain a valid objectID to pass to db2ACSRetrieveMetaData().
- pControlBlock
- Data type:
db2ACS_CB *
db2ACS_CB
contains fundamental information required to initialize and terminate a Db2 ACS session.Before calling db2ACSRetrieveMetaData(), 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 adb2ACS_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
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 Db2 ACS API driver encountered an error. The database manager cannot use the Db2 ACS API session. |
- 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
None.