IBM Books

Administrative API Reference

sqleatin - Attach

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:If a password change is required, use sqleatcp - Attach and Change Password instead of sqleatin.

Authorization

None

Required Connection

This API establishes an instance attachment.

Version

sqlenv.h

C API Syntax 



/* File: sqlenv.h */
/* API: Attach */
/* ... */
SQL_API_RC SQL_API_FN
  sqleatin (
    char * pNodeName,
    char * pUserName,
    char * pPassword,
    struct sqlca * pSqlca);
/* ... */

Generic API Syntax 



/* File: sqlenv.h */
/* API: Attach */
/* ... */
SQL_API_RC SQL_API_FN
  sqlgatin (
    unsigned short PasswordLen,
    unsigned short UserNameLen,
    unsigned short NodeNameLen,
    struct sqlca * pSqlca,
    char * pPassword,
    char * pUserName,
    char * pNodeName);
/* ... */

API Parameters

PasswordLen
Input. A 2-byte unsigned integer representing the length of the password in bytes. Set to zero if no password is supplied.

UserNameLen
Input. A 2-byte unsigned integer representing the length of the user name in bytes. Set to zero if no user name is supplied.

NodeNameLen
Input. A 2-byte unsigned integer representing the length of the node name in bytes. Set to zero if no node name is supplied.

pSqlca
Output. A pointer to the sqlca structure. For more information about this structure, see SQLCA.

pPassword
Input. A string containing the password for the specified user name. May be NULL.

pUserName
Input. A string containing the user name under which the attachment is to be authenticated. May be NULL.

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.

REXX API Syntax 



ATTACH [TO nodename [USER username USING password]]

REXX API Parameters

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

username
Name under which the user attaches to the instance.

password
Password used to authenticate the user name.

Sample Programs

C
\sqllib\samples\c\dbinst.c

COBOL
\sqllib\samples\cobol\dbinst.cbl

FORTRAN
\sqllib\samples\fortran\dbinst.f

REXX
\sqllib\samples\rexx\dbinst.cmd

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

  1. Country code of the application server

  2. Code page of the application server

  3. Authorization ID

  4. Node name (as specified on the API)

  5. Identity and platform type of the server (see the SQL Reference).

  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 partitions if the server is a partitioned database server.

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 depends 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

sqleatcp - Attach and Change Password

sqledtin - Detach

sqlesetc - Set Client.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]