<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-us"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="dc.language" scheme="rfc1766" content="en-us" /> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <meta name="dc.date" scheme="iso8601" content="2005-09-19" /> <meta name="copyright" content="(C) Copyright IBM Corporation 1998, 2006" /> <meta name="security" content="public" /> <meta name="Robots" content="index,follow"/> <meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' /> <meta name="keywords" content="CONNECT (Type 1), SQL statements, CONNECT (Type 1) statement, in CONNECT (Type 1) statement, variable, server-name, USER clause, authorization-name, USING clause, password, RESET clause" /> <title>CONNECT (Type 1)</title> <link rel="stylesheet" type="text/css" href="ibmidwb.css" /> <link rel="stylesheet" type="text/css" href="ic.css" /> </head> <body> <a id="Top_Of_Page" name="Top_Of_Page"></a><!-- Java sync-link --> <script language = "Javascript" src = "../rzahg/synch.js" type="text/javascript"></script> <a name="conj1"></a> <h2 id="conj1"><a href="rbafzmst02.htm#ToC_823">CONNECT (Type 1)</a></h2><a id="idx1564" name="idx1564"></a><a id="idx1565" name="idx1565"></a> <a name="aonj1"></a> <p id="aonj1">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 <a href="rbafzmstdiftab2.htm#rcncdif">CONNECT (Type 1) and CONNECT (Type 2) differences</a>. Refer to <a href="rbafzmstch2drda.htm#adduwmg">Application-directed distributed unit of work</a> for more information about connection states.</p> <a name="wq1159"></a> <h3 id="wq1159"><a href="rbafzmst02.htm#ToC_824">Invocation</a></h3> <p>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.</p> <p>CONNECT is not allowed in a trigger, a function, or a procedure if the procedure is called on a remote application server.</p> <a name="wq1160"></a> <h3 id="wq1160"><a href="rbafzmst02.htm#ToC_825">Authorization</a></h3> <p>The privileges held by the authorization ID of the statement must include communications-level security. (See the section about security in the <a href="../ddp/rbal1kickoff.htm">Distributed Database Programming</a> book.)</p> <p>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:</p> <ul> <li>User is specified. In this case, the USER clause must specify a valid user profile on the application server system.</li> <li>TCP/IP is used with a server authorization entry for the application server. In this case, the server authorization entry must specify a valid user profile on the application server system.</li></ul> <a name="wq1161"></a> <h3 id="wq1161"><a href="rbafzmst02.htm#ToC_826">Syntax</a></h3> <a href="rbafzmstconj1.htm#synsconct"><img src="c.gif" alt="Click to skip syntax diagram" /></a> <pre class="cgraphic"><span><img src="c.gif" alt="Read syntax diagram" longdesc="rbafzmstsyn266.htm" border="0" /></span><a href="#skipsyn-265"><img src="c.gif" alt="Skip visual syntax diagram" border="0" /></a>>>-CONNECT--+----------------------------------------+--------->< +-TO--+-<span class="italic">server-name</span>-+--+---------------+-+ | '-<span><span class="italic">variable</span></span>----' '-<span class="italic">authorization</span>-' | '-RESET----------------------------------' authorization: |--USER--+-<span class="italic">authorization-name</span>-+--USING--+-<span class="italic">password</span>-+------------| '-<span><span class="italic">variable</span></span>-----------' '-<span><span class="italic">variable</span></span>-' </pre> <a name="skipsyn-265" id="skipsyn-265"></a> <a name="synsconct"></a> <h3 id="synsconct"><a href="rbafzmst02.htm#ToC_827">Description</a></h3><a id="idx1566" name="idx1566"></a><a id="idx1567" name="idx1567"></a> <dl class="parml"> <dt class="bold">TO <var class="pv">server-name</var> <span class="base">or</span> <var class="pv">variable</var></dt> <dd>Identifies the application server by the specified server name or the server name contained in the variable. If a variable is specified: <ul> <li>It must be a character-string variable.</li> <li>It must not be followed by an indicator variable.</li> <li>The server name must be left-justified within the variable and must conform to the rules for forming an ordinary identifier.</li> <li>If the length of the server name is less than the length of the variable, it must be padded on the right with blanks.</li></ul> <p>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.</p> <p>If the <var class="pv">server-name</var> is a local relational database and an <var class="pv">authorization-name</var> is specified, it must be the user of the job. If the specified <var class="pv">authorization-name</var> is different than the user of the job, an error occurs and the application is left in the unconnected state.</p> </dd> <dt class="bold">USER <var class="pv">authorization-name or variable</var> </dt><a id="idx1568" name="idx1568"></a><a id="idx1569" name="idx1569"></a><a id="idx1570" name="idx1570"></a> <dd>Identifies the authorization name that will be used to connect to the application server. <p>If a <var class="pv">variable</var> is specified, </p> <ul> <li>It must be a character string variable.</li> <li>It must not be followed by an indicator variable.</li> <li>The authorization name must be left-justified within the variable and must conform to the rules of forming an authorization name.</li> <li>If the length of the authorization name is less than the length of the variable, it must be padded on the right with blanks.</li> <li>The value of the server name must not contain lowercase characters.</li></ul> </dd> <dt class="bold">USING <var class="pv">password or variable</var> </dt><a id="idx1571" name="idx1571"></a><a id="idx1572" name="idx1572"></a><a id="idx1573" name="idx1573"></a> <dd>Identifies the password that will be used to connect to the application server. <p>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.</p> <p>If a <var class="pv">variable</var> is specified, </p> <ul> <li>It must be a character-string variable.</li> <li>It must not be followed by an indicator variable.</li> <li>The password must be left-justified within the variable.</li> <li>If the length of the password is less than that of the variable, it must be padded on the right with blanks.</li></ul> </dd> <dt class="bold">RESET </dt><a id="idx1574" name="idx1574"></a> <dd>CONNECT RESET is equivalent to CONNECT TO x where x is the local server name. </dd> <dt class="bold">CONNECT <span class="base">with no operand</span></dt> <dd>This form of the CONNECT statement returns information about the current server and has no effect on connection states, open cursors, prepared statements, or locks. The connection information is returned in the connection information items in the SQL Diagnostics Area (or the SQLCA). </dd> </dl> <a name="wq1162"></a> <h3 id="wq1162"><a href="rbafzmst02.htm#ToC_828">Notes</a></h3> <p><span class="bold">Successful connection:</span> If the CONNECT statement is successful: </p> <ul> <li>All open cursors are closed, all prepared statements are destroyed, and all locks are released from the current connection.</li> <li>The activation group is disconnected from all current and dormant connections, if any, and connected to the identified application server.</li> <li>The name of the application server is placed in the CURRENT SERVER special register.</li> <li>Information about the application server is placed in the <var class="pv">connection-information-items</var> in the SQL Diagnostics Area.</li> <li>Information about the application server is also placed in the SQLERRP and SQLERRD(4) fields of the SQLCA. If the application server is an IBM® relational database product, the information in the SQLERRP field has the form <var class="pv">pppvvrrm</var>, where: <ul> <li><var class="pv">ppp</var> identifies the product as follows: <ul class="simple"> <li>ARI for DB2® for VM and VSE</li> <li>DSN for DB2 UDB for z/OS</li> <li>QSQ for DB2 UDB for iSeries</li> <li>SQL for all other DB2 UDB products</li></ul></li> <li><var class="pv">vv</var> is a two-digit version identifier such as '07'</li> <li><var class="pv">rr</var> is a two-digit release identifier such as '01'</li> <li><var class="pv">m</var> is a one-digit modification level such as '0'</li></ul> <p>For example, if the application server is Version 7 of DB2 UDB for z/OS, the value of SQLERRP is 'DSN07010'.</p> <p>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: </p> <ul> <li>Uses an unprotected conversation,<sup class="fn"><a href="rbafzmstconj1.htm#fn001">63</a></sup> or</li> <li>Is a connection to an application requester driver program using the *RUW connection method, or</li> <li>Is a local connection using the *RUW connection method.</li></ul></li> <li>Additional information about the connection is placed in the SQLERRMC field of the SQLCA. Refer to <a href="rbafzmstsqlcca.htm#sqlcca">Appendix C. SQLCA (SQL communication area)</a></li></ul> <p><span class="bold">Unsuccessful connection:</span> 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'.</p> <p>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.</p> <p>If the CONNECT statement is unsuccessful for any other reason: </p> <ul> <li>The activation group remains in a connectable, but unconnected state</li> <li>All open cursors are closed, all prepared statements are destroyed, and all locks are released from all current and dormant connections.</li></ul><p class="indatacontent"> An application in a connectable but unconnected state can only execute the CONNECT or SET CONNECTION statements.</p> <p><span class="bold">Implicit connect:</span></p> <ul> <li>When running in the default activation group, the SQL program implicitly connects to a remote relational database when: <ul> <li>The activation group is in a connectable state.</li> <li>The first SQL statement in the first SQL program on the program stack is executed.</li></ul></li> <li>When running in a non-default activation group, the SQL program implicitly connects to a remote relational database when the first SQL statement in the first SQL program for that activation group is executed.</li></ul> <a name="wq1163"></a> <div class="notetitle" id="wq1163">Note:</div> <div class="notebody">It is a good practice for the first SQL statement executed by an activation group to be the CONNECT statement.</div> <p>When APPC is used for connecting to an RDB, implicit connect always sends the <var class="pv">authorization-name</var> of the application requester job and does not send passwords. If the <var class="pv">authorization-name</var> of the application server job is different, or if a password must be sent, an explicit connect statement must be used.</p> <p>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.</p> <p>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.</p> <p>For more information about implicit connect, refer to the <a href="../sqlp/rbafykickoff.htm">SQL Programming</a> 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 <a href="../ddp/rbal1kickoff.htm">Distributed Database Programming</a> book for more details.</p> <p><span class="bold">Connection states:</span> For a description of connection states, see <a href="rbafzmstch2drda.htm#ruwcnst">Remote unit of work connection management</a>. Consecutive CONNECT statements can be executed successfully because CONNECT does not remove the activation group from the connectable state.</p> <p>A CONNECT to either a current or dormant connection in the application group is executed as follows: </p> <ul> <li>If the connection identified by the server-name was established using a CONNECT (Type 1) statement, then no action is taken. Cursors are not closed, prepared statements are not destroyed, and locks are not released.</li> <li>If the connection identified by the server-name was established using a CONNECT (Type 2) statement, then the CONNECT statement is executed like any other CONNECT statement.</li></ul> <p>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.</p> <p>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.</p> <p>For more information about connecting to a remote relational database and the local directory, see the <a href="../sqlp/rbafykickoff.htm">SQL Programming</a> book and the <a href="../ddp/rbal1kickoff.htm">Distributed Database Programming</a> book.</p> <p><span class="bold">SET SESSION AUTHORIZATION:</span> 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.</p> <p>This incudes an implicit connect due to invoking a program that specifies ACTGRP(*NEW).</p> <a name="wq1164"></a> <h3 id="wq1164"><a href="rbafzmst02.htm#ToC_829">Examples</a></h3> <p><span class="italic">Example 1:</span> In a C program, connect to the application server TOROLAB. </p> <pre class="xmp"> EXEC SQL <span class="bold">CONNECT TO</span> TOROLAB;</pre> <p><span class="italic">Example 2:</span> 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. </p> <pre class="xmp"> void main () { char product[9] = " "; EXEC SQL <span class="bold">BEGIN DECLARE SECTION</span>; char APP_SERVER[19]; char username[11]; char userpass[129]; EXEC SQL <span class="bold">END DECLARE SECTION</span>; EXEC SQL <span class="bold">INCLUDE SQLCA</span>; strcpy(APP_SERVER,"TOROLAB"); strcpy(username,"JOE"); strcpy(userpass,"XYZ1"; EXEC SQL <span class="bold">CONNECT TO</span> :APP_SERVER <span class="bold">USER</span> :username <span class="bold">USING</span> :userpass; if (strncmp(SQLSTATE, "00000", 5) ) { EXEC SQL <span class="bold">GET DIAGNOSTICS CONDITION</span> 1 product = <span class="bold">DB2_PRODUCT_ID</span>; } ... return; }</pre><a id="idx1575" name="idx1575"></a><a id="idx1576" name="idx1576"></a> <hr /><div class="fnnum"><a id="fn001" name="fn001">63</a>.</div> <div class="fntext">To reduce the possibility of confusion between network connections and SQL connections, in this book the term 'conversation' will be used to apply to network connections over TCP/IP as well as over APPC, even though it formally applies only to APPC connections.</div> <br /> <hr /><br /> [ <a href="#Top_Of_Page">Top of Page</a> | <a href="rbafzmstc4comit.htm">Previous Page</a> | <a href="rbafzmstcon2t.htm">Next Page</a> | <a href="rbafzmst02.htm#wq1">Contents</a> | <a href="rbafzmstindex.htm#index">Index</a> ] <a id="Bot_Of_Page" name="Bot_Of_Page"></a> </body> </html>