DB2 Version 10.1 for Linux, UNIX, and Windows

db2InstanceStop API - Stop instance

Stops the local or remote DB2® instance.

Scope

This API can be issued against a single member, list of members or, globally against all members. In a DB2 pureScale® environment, this API may be issued against a specific host to stop the instance services on that machine.

Authorization

One of the following authorities:

SYSADM
SYSCTRL
SYSMAINT

Required connection

None

API include file

db2ApiDf.h

API and data structure syntax

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

typedef SQL_STRUCTURE db2InstanceStopStruct
{
             db2int8 iIsRemote;
             char *piRemoteInstName;
             db2DasCommData * piCommData;
             db2StopOptionsStruct * piStopOpts;
} db2InstanceStopStruct;

typedef SQL_STRUCTURE db2DasCommData
{
             db2int8 iCommParam;
             char *piNodeOrHostName;
             char *piUserId;
             char *piUserPw;
} db2DasCommData;

typedef SQL_STRUCTURE db2StopOptionsStruct
{
             db2Uint32 iIsProfile;
             char *piProfile;
             db2Uint32 iIsNodeNum;
             db2NodeType iNodeNum;
             db2Uint32 iIsHostName;
             char *piHostName;
             db2Uint32 iStopOption;
             db2Uint32 iCallerac;
             db2Sint32 iQuiesceDeferMinutes;
} db2StopOptionsStruct;

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

typedef SQL_STRUCTURE db2gInstanceStopStruct
{
             db2int8 iIsRemote;
             db2Uint32 iRemoteInstLen;
             char *piRemoteInstName;
             db2gDasCommData * piCommData;
             db2StopOptionsStruct * piStopOpts;
} db2gInstanceStopStruct;

typedef SQL_STRUCTURE db2gDasCommData
{
             db2int8 iCommParam;
             db2Uint32 iNodeOrHostNameLen;
             char *piNodeOrHostName;
             db2Uint32 iUserIdLen;
             char *piUserId;
             db2Uint32 iUserPwLen;
             char *piUserPw;
} db2gDasCommData;

db2InstanceStop API parameters

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

db2InstanceStopStruct data structure parameters

iIsRemote: Input. An indicator set to TRUE or FALSE. This parameter should be set to TRUE if this is a remote start.
piRemoteInstName: Input. Pointer to the name of the remote instance.
piCommData: Input. Pointer to the db2DasCommData structure.
piStopOpts: Input. Pointer to the db2StopOptionsStruct structure.

db2DasCommData data structure parameters

iCommParam: Input. An indicator set to TRUE or FALSE. This parameter should be set to TRUE if this is a remote start.
piNodeOrHostName: Input. The database partition or hostname.
piUserId: Input. The user name.
piUserPw: Input. The user password.

db2StopOptionsStruct data structure parameters

iIsProfile

Input. Indicates whether a profile is specified. Possible values are TRUE and FALSE. If this field indicates that a profile is not specified, the file db2profile is used.

piProfile

Input. The name of the profile file that was executed at startup to define the DB2 environment. If a profile for the db2InstanceStart API was specified, the same profile must be specified here.

iIsNodeNum

Input. Indicates whether a member number is specified. Possible values are TRUE and FALSE. If specified, the stop command only affects the specified member.

iNodeNum

Input. The member number.

iIsHostName

Input. Indicates whether a host name is specified.

piHostName

Input. Pointer to the host name.

iStopOption

Input. Option. Valid values are:

SQLE_NONE: Issue the normal db2stop operation.
SQLE_FORCE: Issue the FORCE APPLICATION (ALL) command.
SQLE_DROP: Drop the member from the db2nodes.cfg configuration file.
SQLE_QUIESCE: Quiesce the specified member.
SQLE_HOST: Shuts down the instance on a host.

iCallerac

Input. This field is valid only for the SQLE_DROP value of the OPTION field. Valid values are:

SQLE_DROP: Initial call. This is the default value.
SQLE_CONTINUE: Subsequent call. Continue processing after a prompt.
SQLE_TERMINATE: Subsequent call. Terminate processing after a prompt.

iQuiesceDeferMinutes

Input. Indicates the number of minutes after which applications will be forced off the member.

db2gInstanceStopStruct data structure specific parameters

iRemoteInstLen: Input. Specifies the length in bytes of piRemoteInstName.

db2gDasCommData data structure specific parameters

iNodeOrHostNameLen: Input. Specifies the length in bytes of piNodeOrHostName.
iUserIdLen: Input. Specifies the length in bytes of piUserId.
iUserPwLen: Input. Specifies the length in bytes of piUserPw.

Examples

The following is an example of shutting down an instance.

             struct sqlca sqlca;                             // sqlca to carry the sqlcode
             struct db2InstanceStopStruct instanceStopStruct;
             struct db2StopOptionsStruct  stopOptions;
 
             instanceStopStruct.iIsRemote = FALSE;           // demo local instance
             instanceStopStruct.piRemoteInstName = NULL;
             instanceStopStruct.piStopOpts = &stopOptions;

In a DB2 pureScale environment, you can set individual options depending on what type of operation you want to run against the instance. For example:

Shut down the instance on a host

        stopOptions.iOption = SQLE_HOST;
        stopOptions.iIsHostName = TRUE;
        strcpy(stopOptions.piHostName, "ca1");

Shut down a host with the force option

        stopOptions.iOption = SQLE_HOST | SQLE_FORCE;
        stopOptions.iIsHostName = TRUE;
        strcpy(stopOptions.piHostName, "ca1");

Shut down a member

        stopOptions.iIsNodeNum = TRUE;
        stopOptions.iNodeNum = 10;

Shut down a member with the force option

        stopOptions.iOption = SQLE_FORCE;
        stopOptions.iIsNodeNum = TRUE;
        stopOptions.iNodeNum = 10;

Shut down a cluster caching facility

        stopOptions.iIsNodeNum = TRUE;
        stopOptions.iNodeNum = 40;

Shut down a cluster caching facility with the force option

        stopOptions.iOption = SQLE_FORCE;
        stopOptions.iIsNodeNum = TRUE;
        stopOptions.iNodeNum = 40;

Perform a global db2stop against the instance

        instanceStopStruct.piStopOpts = NULL;

Perform a global db2stop with the force option

        stopOptions.iOption = SQLE_FORCE;

Finally, you need to invoke the db2InstanceStop API to shut down the instance.

             db2InstanceStop(db2Version1010, &instanceStopStruct, &sqlca);