DB2 Version 10.1 for Linux, UNIX, and Windows

sqleatcp API - Attach to instance and change password

Enables an application to specify the node at which instance-level functions (CREATE DATABASE and FORCE APPLICATION, for example) 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. Establishes a logical instance attachment to the node specified, and starts a physical communications connection to the node if one does not already exist.

Note: This API extends the function of the sqleatin API by permitting the optional change of the user password for the instance being attached. The DB2® database system provides support for changing passwords on AIX®, Linux and Windows operating systems.

Authorization

None

Required connection

This API establishes an instance attachment.

API include file

sqlenv.h

API and data structure syntax

SQL_API_RC SQL_API_FN
  sqleatcp (
        char * pNodeName,
        char * pUserName,
        char * pPassword,
        char * pNewPassword,
        struct sqlca * pSqlca);

sqleatcp API parameters

pNodeName: Input. A string containing the alias of the instance to which the user wants 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. May be NULL.
pUserName: Input. A string containing the user name under which the attachment is to be authenticated. May be NULL.
pPassword: Input. A string containing the password for the specified user name. May be NULL.
pNewPassword: Input. A string containing the new password for the specified user name. Set to NULL if a password change is not required.
pSqlca: Output. A pointer to the sqlca structure.

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):

Country/region code of the application server
Code page of the application server
Authorization ID
Node name (as specified on the API)
Identity and platform type of the server
Agent ID of the agent which has been started at the server
Agent index
In a DB2 pureScale® environment, as indicated by SQLWARN0 being set to 'W' and SQLWARN4 being set to 'S', this value represents the member number. In a partitioned database environment, as indicated by token 10, this value represents the database partition number. If the database is neither in a partitioned environment nor in a DB2 pureScale environment, this value is always 0, if present.
In a DB2 pureScale environment, as indicated by SQLWARN0 being set to 'W' and SQLWARN4 being set to 'S', this value represents the number of members in a DB2 pureScale instance. If this value is non-zero, it represents the number of database partitions in a partitioned database environment. If the database is neither in a partitioned environment nor in a DB2 pureScale environment, this value is always 0. This token is present only with Version 5 or later.

If the node 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 previously).

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

Certain functions (db2start, db2stop, and all directory services, for example) are never executed remotely. That is, 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 a node name, the current attachment is dropped, and an attachment to the new node is attempted.

Where the user name and password are authenticated, and where the password is changed, depend on the authentication type of the target instance.

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

REXX API syntax

Calling this API directly from REXX is not supported. However, REXX programmers can use this function by calling the DB2 command line processor to execute the ATTACH command.