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 sqleatin - Attach by permitting the optional change of the user password for the instance being attached. |
Authorization
None
Required Connection
This API establishes an instance attachment.
Version
sqlenv.h
C API Syntax
/* File: sqlenv.h */ /* API: Attach and Change Password */ /* ... */ SQL_API_RC SQL_API_FN sqleatcp ( char * pNodeName, char * pUserName, char * pPassword, char * pNewPassword, struct sqlca * pSqlca); /* ... */ |
Generic API Syntax
/* File: sqlenv.h */ /* API: Attach and Change Password */ /* ... */ SQL_API_RC SQL_API_FN sqlgatcp ( unsigned short NewPasswordLen, unsigned short PasswordLen, unsigned short UserNameLen, unsigned short NodeNameLen, struct sqlca * pSqlca, char * pNewPassword, char * pPassword, char * pUserName, char * pNodeName); /* ... */ |
API Parameters
REXX API Syntax
Calling this API directly from REXX is not supported. However, REXX programmers can utilize this function by calling the DB2 command line processor to execute the ATTACH command. For more information, see the REXX programming chapter in the Application Development Guide.
Sample Programs
Usage Notes
Note: | 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):
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 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 (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. For detailed information about authentication types, see the Administration Guide.
The node to which an attachment is to be made can also be specified by a call to sqlesetc - Set Client (see the SQL_ATTACH_NODE option in SQLE-CONN-SETTING).
See Also