db2InstanceAttach API

The db2InstanceAttach API enables an application to specify the node at which instance-level functions, such as CREATE DATABASE and FORCE APPLICATION are to be executed. This node may be the current instance, as defined by the value of the DB2INSTANCE environment variable, another instance on the same workstation, or an instance on a remote workstation. The db2InstanceAttach API establishes a logical instance attachment to the node specified, and starts a physical communications connection to the node if one does not already exist.

Authorization

None

Required connection

None

API include file

db2ApiDf.h

API and data structure syntax

SQL_API_RC SQL_API_FN                        /* Instance Attach               */
  db2InstanceAttach (
             db2Uint32 versionNumber,        /* Version Number                */
             void * pParmStruct,             /* db2InstanceAttachStruct       */
                                             /* Pointer                       */
             struct sqlca * pSqlca);         /* SQLCA                         */

typedef SQL_STRUCTURE db2InstanceAttachStruct
{
             char          *piInstanceName;  /* Instance to attach to         */
             struct db2Credentials *pCredentials; /* Pointer to credentials   */
                                             /* struct                        */
} db2InstanceAttachStruct;

db2InstanceAttach 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 db2InstanceAttachStruct structure.
pSqlca
Output. A pointer to the sqlca structure.

db2AddContactData data structure parameters

piInstanceName
Input. A string containing the alias of the instance to which you want to attach. This instance must have a matching entry in the local node directory. The only exception is the local instance, as specified by the DB2INSTANCE environment variable, which can be specified as the object of an attachment, but cannot be used as a node name in the node directory. Can be NULL.
pCredentials
Input. A pointer to the db2Credentials structure containing the credentials to be used for the attach. Can be NULL if no credentials are used.

Usage notes

A node name in the node directory can be regarded as an alias for an instance.

If an attach request succeeds, the sqlerrmc field of the sqlca will contain 9 tokens separated by hexadecimal FF (similar to the tokens returned when a CONNECT request is successful):
  1. Country/region code of the application server.
  2. Code page of the application server.
  3. Authorization ID.
  4. Instance name (as specified on the API).
  5. Identity and platform type of the server.
  6. Agent ID of the agent which has been started at the server.
  7. Agent index.
  8. Node number of the server.
  9. Number of database partitions if the server is a partitioned database server.

If the instance name is a zero-length string or NULL, information about the current state of attachment is returned. If no attachment exists, sqlcode 1427 is returned. Otherwise, information about the attachment is returned in the sqlerrmc field of the sqlca (as outlined above).

If an attachment has not been made, instance-level APIs are executed against the current instance, specified by the DB2INSTANCE environment variable.

Certain functions, such as db2start, db2stop, and all directory services are never executed remotely. They affect only the local instance environment, as defined by the value of the DB2INSTANCE environment variable.

If an attachment exists, and the API is issued with an instance name, the current attachment is dropped, and an attachment to the new instance is attempted.

Where the user name and password are authenticated depends on the authentication type of the target instance.

The instance to which an attachment is to be made can also be specified by a call to the sqlesetc API.

Specifying a new password in the db2Credentials struct will attempt to change the user’s password. The Db2® database system provides support for changing passwords on AIX, Linux and Windows operating systems.