DB2 Version 10.1 for Linux, UNIX, and Windows

db2InstanceStart API - Start instance

Starts 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 start 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
  db2InstanceStart (
             db2Uint32 versionNumber,
             void * pParmStruct,
             struct sqlca * pSqlca);

typedef SQL_STRUCTURE db2InstanceStartStruct
{
             db2int8 iIsRemote;
             char *piRemoteInstName;
             db2DasCommData * piCommData;
             db2StartOptionsStruct * piStartOpts;
} db2InstanceStartStruct;

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

typedef SQL_STRUCTURE db2StartOptionsStruct
{
             db2Uint32 iIsProfile;
             char *piProfile;
             db2Uint32 iIsNodeNum;
             db2NodeType iNodeNum;
             db2Uint32 iOption;
             db2Uint32 iIsHostName;
             char *piHostName;
             db2Uint32 iIsPort;
             db2PortType iPort;
             db2Uint32 iIsNetName;
             char *piNetName;
             db2Uint32 iTblspaceType;
             db2NodeType iTblspaceNode;
             db2Uint32 iIsComputer;
             char *piComputer;
             char *piUserName;
             char *piPassword;
             db2QuiesceStartStruct iQuiesceOpts;
} db2StartOptionsStruct;

typedef SQL_STRUCTURE db2QuiesceStartStruct
{
             db2int8 iIsQRequested;
             db2int8 iQOptions;
             char *piQUsrName;
             char *piQGrpName;
             db2int8 iIsQUsrGrpDef;
} db2QuiesceStartStruct;

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

typedef SQL_STRUCTURE db2gInstanceStStruct
{
             db2int8 iIsRemote;
             db2Uint32 iRemoteInstLen;
             char *piRemoteInstName;
             db2gDasCommData * piCommData;
             db2gStartOptionsStruct * piStartOpts;
} db2gInstanceStStruct;

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

typedef SQL_STRUCTURE db2gStartOptionsStruct
{
             db2Uint32 iIsProfile;
             char *piProfile;
             db2Uint32 iIsNodeNum;
             db2NodeType iNodeNum;
             db2Uint32 iOption;
             db2Uint32 iIsHostName;
             char *piHostName;
             db2Uint32 iIsPort;
             db2PortType iPort;
             db2Uint32 iIsNetName;
             char *piNetName;
             db2Uint32 iTblspaceType;
             db2NodeType iTblspaceNode;
             db2Uint32 iIsComputer;
             char *piComputer;
             char *piUserName;
             char *piPassword;
             db2gQuiesceStartStruct iQuiesceOpts;
} db2gStartOptionsStruct;

typedef SQL_STRUCTURE db2gQuiesceStartStruct
{
             db2int8 iIsQRequested;
             db2int8 iQOptions;
             db2Uint32 iQUsrNameLen;
             char *piQUsrName;
             db2Uint32 iQGrpNameLen;
             char *piQGrpName;
             db2int8 iIsQUsrGrpDef;
} db2gQuiesceStartStruct;

db2InstanceStart API parameters

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

db2InstanceStartStruct data structure parameters

iIsRemote: Input. An indicator set to constant integer value 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.
piStartOpts: Input. Pointer to the db2StartOptionsStruct 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 member or hostname.
piUserId: Input. The user name.
piUserPw: Input. The user password.

db2StartOptionsStruct data structure parameters

iIsProfile

Input. Indicates whether a profile is specified. If this field indicates that a profile is not specified, the file db2profile is used.

piProfile

Input. The name of the profile file to be executed at each member to define the DB2 environment (MPP only). This file is executed before any members are started. The default value is db2profile.

iIsNodeNum

Input. Indicates whether a member or CF number is specified. If specified, the start command only affects the specified member or CF.

iNodeNum

Input. The member or CF number.

iOption

Input. Specifies an action. Valid values for OPTION (defined in sqlenv header file, located in the include directory) are:

SQLE_NONE: Issue the normal db2start operation.
SQLE_ADDNODE: Issue the ADD NODE command. This option is not supported in a DB2 pureScale environment.
SQLE_RESTART: Issue the RESTART DATABASE command. This option is not supported in a DB2 pureScale environment.
SQLE_RESTART_PARALLEL: Issue the RESTART DATABASE command for parallel execution. This option is not supported in a DB2 pureScale environment.
SQLE_STANDALONE: Starts the node in STANDALONE mode.
SQLE_HOST: Starts up the instance on a host.

iIsHostName

Input. Indicates whether a host name is specified.

piHostName

Input. The system name.

iIsPort

Input. Indicates whether a port number is specified.

iPort

Input. The port number.

iIsNetName

Input. Indicates whether a net name is specified.

piNetName

Input. The network name, or a comma delimited list of network names.

iTblspaceType

Input. This parameter is used for ADD MEMBER operations only. Specifies the type of system temporary table space definitions to be used for the member being added. Valid values are:

SQLE_TABLESPACES_NONE: Do not create any system temporary table spaces.
SQLE_TABLESPACES_LIKE_NODE: The containers for the system temporary table spaces should be the same as those for the specified member.
SQLE_TABLESPACES_LIKE_CATALOG: The containers for the system temporary table spaces should be the same as those for the catalog member of each database.

iTblspaceNode

Input. Specifies the member number from which the system temporary table space definitions should be obtained. The member number must exist in the db2nodes.cfg configuration file, and is only used if the tblspace_type field is set to SQLE_TABLESPACES_LIKE_NODE.

iIsComputer

Input. Indicates whether a computer name is specified. Valid on the Windows operating system only.

piComputer

Input. Computer name. Valid on the Windows operating system only.

piUserName

Input. Logon account user name. Valid on the Windows operating system only.

piPassword

Input. The password corresponding to the logon account user name.

iQuiesceOpts

Input. A pointer to the db2QuiesceStartStruct structure.

db2QuiesceStartStruct data structure parameters

iIsQRequested

Input. An indicator set to TRUE or FALSE. This parameter should be set to TRUE if quiesce is requested.

iQOptions

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

DB2INSQUIESCE_RESTRICTEDACCESS: The instance is started in ADMIN MODE with the RESTRICTED ACCESS option to prevent databases being activated to do authorization checking.

piQUsrName

Input. The quiesced username.

piQGrpName

Input. The quiesced group name.

iIsQUsrGrpDef

Input. An indicator set to TRUE or FALSE. This parameter should be set to TRUE if a quiesced user or quiesced group is defined.

db2gInstanceStStruct 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.

db2gQuiesceStartStruct data structure specific parameters

iQUsrNameLen: Input. Specifies the length in bytes of piQusrName.
iQGrpNameLen: Input. Specifies the length in bytes of piQGrpName.

Examples

The following is an example of starting up an instance:

             struct sqlca sqlca;                                // sqlca to carry the sqlcode
             struct db2InstanceStartStruct instanceStartStruct;
             struct db2StartOptionsStruct  startOptions;
 
             instanceStartStruct.iIsRemote = FALSE;             // demo local instance
             instanceStartStruct.piRemoteInstName = NULL;
             instanceStartStruct.piStartOpts = &startOptions;

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:

Start the instance on a host

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

Start a member

        startOptions.iIsNodeNum = TRUE;
        startOptions.iNodeNum = 10;

Start a cluster caching facility

        startOptions.iIsNodeNum = TRUE;
        startOptions.iNodeNum = 40;

Perform a global db2start against the instance

        instanceStartStruct.piStartOpts = NULL;

Finally, you need to invoke the db2InstanceStart API to start the instance.

             db2InstanceStart(db2Version1010, &instanceStartStruct, &sqlca);