Explicit connection management

The CONNECT statement is used with a TO or RESET clause. A CONNECT statement with a TO clause allows you to specify connection to a particular AS relational database. The CONNECT statement with a RESET clause specifies connection to the local relational database.

When you issue (or the program issues) a CONNECT statement with a TO or RESET clause, the AS identified must be described in the relational database directory. The AR must also be in a connectable state for the CONNECT statement to be successful.

The CONNECT statement has different effects depending on the connection management method you use. For RUW connection management, the CONNECT statement has the following effects:

• When a CONNECT statement with a TO or RESET clause is successful, the following events take place:
  • Any open cursors are closed, any prepared statements are discarded, and any held resources are released from the previous AS if the application process was placed in the connectable state through the use of COMMIT HOLD or ROLLBACK HOLD SQL statement, or if the application process is running COMMIT(*NONE).
  • The application process is disconnected from its previous AS, if any, and connected to the identified AS.
  • The name of the AS is placed in the Current Server special register.
  • Information that identifies the system module that returned the error is placed in the SQLERRP field of the SQL communication area (SQLCA) or in DB2_MODULE_DETECTING_ERROR of the SQL diagnostic area.
• If the CONNECT statement is unsuccessful for any reason, the application remains in the connectable but unconnected state. An application in the connectable but unconnected state can only run the CONNECT statement.
• Consecutive CONNECT statements can be run successfully because CONNECT does not remove the AR from the connectable state. A CONNECT to the AS to which the AR is currently connected is run like any other CONNECT statement.
• If running with commitment control, the CONNECT statement cannot run successfully when it is preceded by any SQL statement other than CONNECT, SET CONNECTION, COMMIT, ROLLBACK, DISCONNECT, or RELEASE. To avoid an error, perform a COMMIT or ROLLBACK operation before a CONNECT statement is run. If running without commitment control, the CONNECT statement is always allowed.

For DUW connection management, the CONNECT statement has the following effects:

• When a CONNECT statement with a TO or RESET clause is successful, the following events take place:
  • The name of the AS is placed in the Current Server special register.
  • Information that identifies the system module that returned the error is placed in the SQLERRP field of the SQL communication area (SQLCA) or in DB2_MODULE_DETECTING_ERROR of the SQL diagnostic area.
  • Information on the type of connection is also placed into the SQLCA and SQL diagnostic area. Encoded in these is the following information:
    • Whether the application is in a connected or unconnected state can be found in SQLERRD(5) in the SQLCA or in DB2_CONNECTION_STATE in the SQL diagnostic area.
    • Whether a remote connection uses a protected or unprotected conversation is found in SQLERRD(4) in the SQLCA or in DB2_CONNECTION_TYPE in the SQL diagnostic area.
    • Whether the connection is always read-only, always capable of updates, or whether the ability to update can change between each unit of work is found in SQLERRD(4) in the SQLCA or in DB2_CONNECTION_STATUS in the SQL diagnostic area.

    See the SQL programming topic for more information about SQLERRD fields in the SQLCA and about connection information in the SQL diagnostic area.

• If the CONNECT statement with a TO or RESET clause is unsuccessful because the AR is not in the connectable state or the server-name is not listed in the local relational database directory, the connection state of the AR is unchanged.
• A connection to a currently connected AS results in an error.
• A connection without a TO or RESET clause can be used to obtain information about the current connection. This includes the following information:
  • Information that identifies the system module that returned the status is placed in the SQLERRP field of the SQL communication area (SQLCA) or in DB2_MODULE_DETECTING_ERROR of the SQL diagnostic area.
  • Other status information is described in the previous paragraphs discussing the contents of SQLERRD(4) and SQLERRD(5) and the corresponding information in the SQL diagnostic area.

It is a good practice for the first SQL statement run by an application process to be the CONNECT statement. However, when you have CONNECT statements embedded in your program you might want to dynamically change the AS name if the program connects to more than one AS. If you are going to run the application at multiple servers, you can specify the CONNECT statement with a host variable as shown here, so that the program can be passed the relational database name.

CONNECT TO  : host-variable

Without CONNECT statements, all you need to do when you change the AS is to recompile the program with the new relational database name.

The following example shows two forms of the CONNECT statement (1 and 2) in an application program:

CRTSQLxxx PGM(SPIFFY/FIXTOTAL) COMMIT(*CHG) RDB(KC105)
 
  PROC: FIXTOTAL;
  EXEC SQL   CONNECT TO KC105; 1
  
  EXEC SQL
    SELECT * INTO :SERVICE
             FROM REPAIRTOT;
  
  EXEC SQL COMMIT;
  
  EXEC SQL CONNECT TO MPLS03 USER :USERID USING :PW;  2
  
  EXEC SQL SELECT …
  
  EXEC SQL COMMIT;
  
  END FIXTOTAL;

The example (2) shows the use of the USER/USING form of the CONNECT statement. You must specify the user ID and password with host variables when this form of the CONNECT statement is embedded in a program. If you are using TCP/IP, a user ID and password can be extracted from a security object at connect time if you have used the Add Server Authentication Entry (ADDSVRAUTE) command with the appropriate parameters to store them.

The following example shows both CONNECT statement forms in Interactive SQL. Note that the password must be enclosed in single quotation marks.

Type SQL statement, press Enter.
Current connection is to relational database (RDB) KC105.
CONNECT TO KC000_________________________________________________________

COMMIT___________________________________________________________________
===> CONNECT TO MPLS03 USER JOE USING 'X47K'_____________________________
_________________________________________________________________________
_________________________________________________________________________