298 lines
18 KiB
HTML
298 lines
18 KiB
HTML
<?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>
|