DB2 Version 10.1 for Linux, UNIX, and Windows

db2InstanceQuiesce API - Quiesce instance

Forces all users off the instance, immediately rolls back all active transaction, and puts the instance into quiesce mode. This API provides exclusive access to the instance. During this quiesced period, system administration can be performed on the instance. After administration is complete, you can unquiesce the instance using the db2InstanceUnquiesce API. This API allows other users to connect to the databases within the instance without having to shut down and perform another instance start.

In this mode, only groups or users with DBADM, SYSADM, SYSMAINT, or SYSCTRL authority will have access to the database and its objects.

Authorization

One of the following authorities:

SYSADM
SYSCTRL

Required connection

None

API include file

db2ApiDf.h

API and data structure syntax

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

typedef SQL_STRUCTURE db2InsQuiesceStruct
{
             char *piInstanceName;
             char *piUserId;
             char *piGroupId;
             db2Uint32 iImmediate;
             db2Uint32 iForce;
             db2Uint32 iTimeout;
             db2Uint32 iQOptions;
} db2InsQuiesceStruct;

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

typedef SQL_STRUCTURE db2gInsQuiesceStruct
{
             db2Uint32 iInstanceNameLen;
             char *piInstanceName;
             db2Uint32 iUserIdLen;
             char *piUserId;
             db2Uint32 iGroupIdLen;
             char *piGroupId;
             db2Uint32 iImmediate;
             db2Uint32 iForce;
             db2Uint32 iTimeout;
             db2Uint32 iQOptions;
} db2gInsQuiesceStruct;

db2InstanceQuiesce 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 db2InsQuiesceStruct structure.
pSqlca: Output. A pointer to the sqlca structure.

db2InsQuiesceStruct data structure parameters

piInstanceName

Input. The instance name.

piUserId

Input. The name of a user who will be allowed access to the instance while it is quiesced.

piGroupId

Input. The name of a group that will be allowed access to the instance while the instance is quiesced.

iImmediate

Input. Valid values are:

TRUE=1: Force the applications immediately.
FALSE=0: Deferred force. Applications will wait the number of minutes specified by iTimeout parameter to let their current units of work be completed, and then will terminate. If this deferred force cannot be completed within the number of minutes specified by iTimeout parameter, the quiesce operation will fail.

iForce

Input. Reserved for future use.

iTimeout

Input. Specifies the time, in minutes, to wait for applications to commit the current unit of work. If iTimeout is not specified, in a single-partition database environment, the default value is 10 minutes. In a partitioned database environment the value specified by the start_stop_time database manager configuration parameter will be used.

iQOptions

Input. Specifies instance quiesce options. Valid values (defined in sqlenv header file, located in the include directory) are:

DB2INSQUIESCE_RESTRICTEDACCESS: The instance is quiesced with the RESTRICTED ACCESS option to prevent databases being activated to do authorization checking.

db2gInsQuiesceStruct data structure specific parameters

iInstanceNameLen: Input. Specifies the length in bytes of piInstanceName.
iUserIdLen: Input. Specifies the length in bytes of piUserID.
iGroupIdLen: Input. Specifies the length in bytes of piGroupId.