db2ACSSnapshot - perform a Db2 Advanced Copy Services (ACS) operation

Performs a Db2 Advanced Copy Services (ACS) operation.

Include file

db2ACSApi.h

Syntax and data structures

typedef union db2ACS_ReadList
{
   db2ACS_GroupList           group;
} db2ACS_ReadList;


db2ACS_RC db2ACSSnapshot(
               db2ACS_Action             action,
               db2ACS_ObjectID           objectID,
               db2ACS_ReadList         * pReadList,
               db2ACS_CB               * pControlBlock,
               db2ACS_ReturnCode       * pRC );

Parameters

action

Data type: db2ACS_Action

The type of Db2 ACS action to perform. Values:

     DB2ACS_ACTION_WRITE
     DB2ACS_ACTION_READ_BY_OBJECT
     DB2ACS_ACTION_READ_BY_GROUP

The database manager passes action in to db2ACSSnapshot().

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. A db2ACS_ObjectID is guaranteed to be unique and persistent only within the timeframe of a single Db2 ACS session.

If the database manager specified DB2ACS_OP_READ or DB2ACS_OP_DELETE as operation in the call to db2ACSBeginOperation(), then the database manager passes the value for objectID in to db2ACSSnapshot().

pReadList

Data type: db2ACS_ReadList *

db2ACS_ReadList contains a list of groups.

pReadList is only used if action is DB2ACS_ACTION_READ_BY_GROUP.

If action is DB2ACS_ACTION_READ_BY_GROUP, then the database manager is responsible for allocating memory for and populating the fields of pReadLIst before calling db2ACSSnapshot(), and for freeing the memory for pReadList afterwards.

pControlBlock

Data type: db2ACS_CB *

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

Before calling db2ACSSnapshot(), 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

The database manager calls db2ACSBeginOperation() before calling db2ACSPartition(), db2ACSPrepare(), and then db2ACSSnapshot(). The database manager specifies the type of Db2 ACS operation that the Db2 ACS API driver should perform in the operation parameter in the call to db2ACSBeginOperation().