DB2 Version 9.7 for Linux, UNIX, and Windows

db2ACSInitialize - initialize a DB2 Advanced Copy Services (ACS) session

Initializes a new DB2® Advanced Copy Services (ACS) session. This call establishes communication between the database manager's DB2 ACS library and the DB2 ACS API driver for the storage hardware.

Include file

db2ACSApi.h

Syntax and data structures

/* ==========================================================================
 * Session Initialization
 * ========================================================================== */
db2ACS_RC db2ACSInitialize(
               db2ACS_CB               * pControlBlock,
               db2ACS_ReturnCode       * pRC );

Parameters

pControlBlock

Data type: db2ACS_CB *

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

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 db2ACSInitialize(), the database manager populates the following fields:

pControlBlock->session
pControlBlock->options

The DB2 ACS API driver populates the following fields before returning:

pControlBlock->handle
pControlBlock->vendorInfo

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_COMM_ERROR`	There was a communication 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_NO_DEV_AVAIL`	There is currently no storage device, such as a tape drive, available to use.	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

Before the database manager can make any DB2 ACS API calls, except calls to db2ACSQueryAPIVersion(), the database manager must call db2ACSInitialize(). Once the database manager establishes a DB2 ACS session by calling db2ACSInitialize(), then the database manager can perform any combination of DB2 ACS query, read, write, or delete operations. The database manager can terminate the DB2 ACS session by calling db2ACSTerminate().