db2ACSBeginOperation - begin a Db2 Advanced Copy Services (ACS) operation.

Begins a Db2 Advanced Copy Services (ACS) operation.

Include file

db2ACSApi.h

Syntax and data structures


/* ==========================================================================
 * Operation Begin
 *
 * A valid ACS operation is specified by passing an ObjectType OR'd with one of
 * the following Operations, such as:
 *
 *    (DB2ACS_OP_CREATE | DB2ACS_OBJTYPE_SNAPSHOT)
 * ========================================================================== */
db2ACS_RC db2ACSBeginOperation(
               db2ACS_Operation           operation,
               db2ACS_CB               * pControlBlock,
               db2ACS_ReturnCode       * pRC );

Parameters

operation

Data type: db2ACS_Operation.

operation is a bitmask indicating the Db2 ACS operation to begin, and the type of object involved.

Operation types:

     DB2ACS_OP_CREATE
     DB2ACS_OP_READ
     DB2ACS_OP_DELETE

Object types:

     DB2ACS_OBJTYPE_BACKUP
     DB2ACS_OBJTYPE_LOG
     DB2ACS_OBJTYPE_LOADCOPY
     DB2ACS_OBJTYPE_SNAPSHOT

For example: ( DB2ACS_OP_CREATE | DB2ACS_OBJTYPE_SNAPSHOT ) or ( DB2ACS_OP_DELETE | DB2ACS_OBJTYPE_LOADCOPY ).

The database manager passes operation to the db2ACSBeginOperation() function call.

pControlBlock

Data type: db2ACS_CB *

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

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

     pControlBlock->handle
     pControlBlock->vendorInfo
     pControlBlock->options

If operation is DB2ACS_OP_CREATE or DB2ACS_OP_READ, then the database manager also populates the following field:

pControlBlock->operation

The information contained within pControlBlock->operation is only valid within the context of a particular Db2 ACS operation. pControlBlock->operation will be set during db2ACSBeginOperation(), and will remain unchanged until db2ACSEndOperation() returns. Neither the database manager nor the Db2 ACS API driver should reference pControlBlock->operation outside the scope of a Db2 ACS operation.

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_OPTIONS`	The database manager specified invalid options.
`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.

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

None.