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