The CONNECT (TYPE 1) statement connects an activation group within an application process to the identified application server using the rules for remote unit of work. This server is then the current server for the activation group. This type of CONNECT statement is used if RDBCNNMTH(*RUW) was specified on the CRTSQLxxx command. Differences between the two types of statements are described in CONNECT (Type 1) and CONNECT (Type 2) differences. Refer to Application-directed distributed unit of work for more information about connection states.
This statement can only be embedded within an application program or issued interactively. It is an executable statement that cannot be dynamically prepared. It must not be specified in Java™ or REXX.
CONNECT is not allowed in a trigger, a function, or a procedure if the procedure is called on a remote application server.
The privileges held by the authorization ID of the statement must include communications-level security. (See the section about security in the Distributed Database Programming book.)
If the application server is DB2 UDB for iSeries, the user profile of the person issuing the statement must also be a valid user profile on the application server system, UNLESS:
When the CONNECT statement is executed, the specified server name or the server name contained in the variable must identify an application server described in the local directory and the activation group must be in the connectable state.
If the server-name is a local relational database and an authorization-name is specified, it must be the user of the job. If the specified authorization-name is different than the user of the job, an error occurs and the application is left in the unconnected state.
If a variable is specified,
If password is specified as a literal, it must be a character string. The maximum length is 128 characters. It must be left justified. The literal form of the password is not allowed in static SQL or REXX.
If a variable is specified,
Successful connection: If the CONNECT statement is successful:
For example, if the application server is Version 7 of DB2 UDB for z/OS, the value of SQLERRP is 'DSN07010'.
The SQLERRD(4) field of the SQLCA contains values indicating whether the application server allows commitable updates to be performed. For a CONNECT (Type 1) statement SQLERRD(4) will always contain the value 1. The value 1 indicates that commitable updates can be performed, and the connection:
Unsuccessful connection: If the CONNECT statement is unsuccessful, the DB2_MODULE_DETECTING_ERROR condition information item in the SQL Diagnostics Area (or the SQLERRP field of the SQLCA) is set to the name of the module at the application requester that detected the error. Note that the first three characters of the module name identify the product. For example, if the application requester is DB2 UDB LUW for Windows the first three characters are 'SQL'.
If the CONNECT statement is unsuccessful because the activation group is not in the connectable state, the connection state of the activation group is unchanged.
If the CONNECT statement is unsuccessful for any other reason:
An application in a connectable but unconnected state can only execute the CONNECT or SET CONNECTION statements.
Implicit connect:
When APPC is used for connecting to an RDB, implicit connect always sends the authorization-name of the application requester job and does not send passwords. If the authorization-name of the application server job is different, or if a password must be sent, an explicit connect statement must be used.
When TCP/IP is used for connecting to an RDB, an implicit connect is not bound by the above restrictions. Use of the ADDSVRAUTE and other -SVRAUTE commands allows one to specify, for a given user under which the implicit (or explicit) CONNECT is done, the remote authorization-name and password to be used in connecting to a given RDB.
In order for the password to be stored with the ADDSVRAUTE or CHGSVRAUTE command, the QRETSVRSEC system value must be set to '1' rather than the default of '0'. When using these commands for DRDA® connection, it is very important to realize that the value of the RDB name entered into the SERVER parameter must be in UPPER CASE. For more information, see Example 2 under Type 2 CONNECT.
For more information about implicit connect, refer to the SQL Programming book. Once a connection to a relational database for a user profile is established, the password, if specified, may not be validated again on subsequent connections to the same relational database with the same user profile. Revalidation of the password depends on if the conversation is still active. See the Distributed Database Programming book for more details.
Connection states: For a description of connection states, see Remote unit of work connection management. Consecutive CONNECT statements can be executed successfully because CONNECT does not remove the activation group from the connectable state.
A CONNECT to either a current or dormant connection in the application group is executed as follows:
CONNECT cannot execute successfully when it is preceded by any SQL statement other than CONNECT, COMMIT, DISCONNECT, SET CONNECTION, RELEASE, or ROLLBACK. To avoid an error, execute a commit or rollback operation before a CONNECT statement is executed.
If any previous current or dormant connections were established using protected conversations, then the CONNECT (Type 1) statement will fail. Either, a CONNECT (Type 2) statement must be used, or the connections using protected conversations must be ended by releasing the connections and successfully committing.
For more information about connecting to a remote relational database and the local directory, see the SQL Programming book and the Distributed Database Programming book.
SET SESSION AUTHORIZATION: If a SET SESSION AUTHORIZATION statement has been executed in the thread, a CONNECT to the local server will fail unless prior to the connect statement, the SYSTEM_USER value is the same as SESSION_USER.
This incudes an implicit connect due to invoking a program that specifies ACTGRP(*NEW).
Example 1: In a C program, connect to the application server TOROLAB.
EXEC SQL CONNECT TO TOROLAB;
Example 2: In a C program, connect to an application server whose name is stored in the variable APP_SERVER (VARCHAR(18)). Following a successful connection, copy the product identifier of the application server to the variable PRODUCT.
void main ()
{
char product[9] = " ";
EXEC SQL BEGIN DECLARE SECTION;
char APP_SERVER[19];
char username[11];
char userpass[129];
EXEC SQL END DECLARE SECTION;
EXEC SQL INCLUDE SQLCA;
strcpy(APP_SERVER,"TOROLAB");
strcpy(username,"JOE");
strcpy(userpass,"XYZ1";
EXEC SQL CONNECT TO :APP_SERVER
USER :username USING :userpass;
if (strncmp(SQLSTATE, "00000", 5) )
{ EXEC SQL GET DIAGNOSTICS CONDITION 1
product = DB2_PRODUCT_ID; }
...
return;
}