DB2 Version 10.1 for Linux, UNIX, and Windows

db2HADRTakeover API - Instruct a database to take over as the high availability disaster recovery (HADR) primary database

Instructs a standby database to take over as the primary database. This API can be called against a standby database only.

Authorization

One of the following authorities:

SYSADM
SYSCTRL
SYSMAINT

Required connection

Instance. The API establishes a database connection if one does not exist, and closes the database connection when the API completes.

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  db2HADRTakeover (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2HADRTakeoverStruct
{
   char *piDbAlias;
   char *piUserName;
   char *piPassword;
   db2Uint16 iByForce;
} db2HADRTakeoverStruct;

SQL_API_RC SQL_API_FN
  db2gHADRTakeover (
       db2Uint32 versionNumber,
       void * pParmStruct,
       struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2gHADRTakeoverStruct
{
   char *piDbAlias;
   db2Uint32 iAliasLen;
   char *piUserName;
   db2Uint32 iUserNameLen;
   char *piPassword;
   db2Uint32 iPasswordLen;
   db2Uint16 iByForce;
} db2gHADRTakeoverStruct;

db2HADRTakeover API parameters

versionNumber: Input. Specifies the version and release level of the structure passed as the second parameter pParmStruct.
pParmStruct: Input. A pointer to the db2HADRTakeoverStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2HADRTakeoverStruct data structure parameters

piDbAlias

Input. A pointer to the database alias.

piUserName

Input. A pointer to the user name under which the command will be executed.

piPassword

Input. A pointer to a string containing the password.

iByForce

Input. Valid values are:

DB2HADR_NO_FORCE: Specifies that a takeover occurs only if the two systems are in peer state with communication established; this results in a role reversal between the HADR primary and HADR standby databases.
DB2HADR_FORCE: Specifies that the standby database takes over as the primary database without waiting for confirmation that the original primary database has been shut down. Forced takeover must be issued when the standby database is in either remote catchup pending or peer state.
DB2HADR_FORCE_PEERWINDOW: When this option is specified, there will not be any committed transaction loss if the command succeeds and the primary database is brought down before the end of the peer window period (set the database configuration parameter hadr_peer_window to a non-zero value). Not bringing down the primary database before the peer window expires, will result in split brain or dual primary. If executed when the HADR pair is not in a peer or disconnected peer state (the peer window has expired), an error is returned.
You cannot use this option when the synchronization mode is set to ASYNC or SUPERASYNC.

Note: The takeover operation with the DB2HADR_FORCE_PEERWINDOW parameter may behave incorrectly if the primary database clock and the standby database clock are not synchronized to within 5 seconds of each other. That is, the operation may succeed when it should fail, or fail when it should succeed. You should use a time synchronization service (for example, NTP) to keep the clocks synchronized to the same source.

/* Values for iByForce                                               */
#define DB2HADR_NO_FORCE           0    /* Do not perform START or   */
                                        /* TAKEOVER HADR operation   */
                                        /* by force                  */
#define DB2HADR_FORCE              1    /* Do perform START or       */
                                        /* TAKEOVER HADR operation   */
                                        /* by force                  */
#define DB2HADR_FORCE_PEERWINDOW   2    /* Perform TAKEOVER HADR     */
                                        /* operation by force inside */
                                        /* the Peer Window only      */

db2gHADRTakeoverStruct data structure specific parameters

iAliasLen: Input. Specifies the length in bytes of the database alias.
iUserNameLen: Input. Specifies the length in bytes of the user name.
iPasswordLen: Input. Specifies the length in bytes of the password.