db2ACSPartition - group target data for a database partition together

Associates a group identifier with each of the paths listed by the database manager as belonging to a database partition.

Include file

db2ACSApi.h

Syntax and data structures


/* ==========================================================================
 * Partition
 * ========================================================================== */
db2ACS_RC db2ACSPartition(
               db2ACS_PathList         * pPathList,
               db2ACS_CreateObjectInfo * pCreateObjInfo,
               db2ACS_CB               * PControlBlock,
               db2ACS_ReturnCode       * pRC );

Parameters

pPathList
Data type: db2ACS_PathList

db2ACS_PathList contains a list of database paths, including some extra information about each of those paths specific to Db2 ACS operations.

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 entry field of the db2ACS_PathList structure is an array of elements of type db2ACS_PathEntry. db2ACS_PathEntry contains information about a database path.

Before calling db2ACSPartition, the database manager populates the following fields of each db2ACS_PathEntry entry in pPathList:

  • path
  • type
  • toBeExcluded

Every path identified by the database manager as belonging to this database partition is given a group identifier by the Db2 ACS API driver. The Db2 ACS API driver populates the groupID field of each db2ACS_PathEntry in pPathList before returning.

pCreateObjInfo
Data type: db2ACS_CreateObjectInfo

db2ACS_CreateObjectInfo contains information about the Db2 ACS backup object creation.

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 database manager populates the fields of pCreateObjInfo before calling db2ACSPartition.

pControlBlock
Data type: db2ACS_CB *

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

Before calling db2ACSPartition(), 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_INIT_FAILED The database manager attempted to initialize a Db2 ACS session, but the initialization failed.  
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_OUT_OF_SCOPE The database manager attempted to perform a Db2 ACS operation on a recovery object that is not managed by the Db2 ACS API driver.
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

Db2 Advanced Copy Services handles the data on a single database partition atomically. That is: the data for one database partition is backed up or restored together, and independently of other database partitions - even when the action is part of an operation involving multiple database partitions. db2ACSPartition groups database path information for a single database partition together.

The database manager calls db2ACSPartition before calling db2ACSSnapshot. The database manager will list all the paths associated with this database partition in the pPathList parameter. The database manager can perform a Db2 ACS operation on a subset of the paths listed in pPathList by specifying that subset of paths in the pReadList parameter passed to db2ACSSnapshot.