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 the sqleatcp
API instead of the sqleatin API.
Required connection
This API establishes
an instance attachment.
API include file
sqlenv.h
API and data structure syntax
SQL_API_RC SQL_API_FN
sqleatin (
char * pNodeName,
char * pUserName,
char * pPassword,
struct sqlca * pSqlca);
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);
sqleatin 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. Can be NULL.
- pUserName
- Input. A string containing the user name under which the attachment
is to be authenticated. Can be NULL.
- pPassword
- Input. A string containing the password for the specified user
name. Can be NULL.
- pSqlca
- Output. A pointer to the sqlca structure.
sqlgatin API-specific 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.
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):
- 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
- Node number of the server
- Number of database 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.
The node to which an attachment
is to be made can also be specified by a call to the sqlesetc API.
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.