209 lines
13 KiB
HTML
209 lines
13 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 lang="en-us" xml:lang="en-us">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
|
<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="DC.Type" content="reference" />
|
||
|
|
<meta name="DC.Title" content="SQLConnect - Connect to a data source" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzadphdapi.htm" />
|
||
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 1999, 2006" />
|
||
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 1999, 2006" />
|
||
|
|
<meta name="DC.Format" content="XHTML" />
|
||
|
|
<meta name="DC.Identifier" content="rzadpfnconn" />
|
||
|
|
<meta name="DC.Language" 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. -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
||
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
||
|
|
<title>SQLConnect</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzadpfnconn"><a name="rzadpfnconn"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">SQLConnect - Connect to a data source</h1>
|
||
|
|
<div><div class="section"></div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLConnect()</samp> establishes a connection
|
||
|
|
to the target database. The application must supply a target SQL database,
|
||
|
|
and optionally an authorization-name, and an authentication-string.</p>
|
||
|
|
<p><samp class="codeph">SQLAllocConnect()</samp> must
|
||
|
|
be called before calling this function.</p>
|
||
|
|
<p>This function must be called
|
||
|
|
before calling <samp class="codeph">SQLAllocStmt()</samp>.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLConnect (SQLHDBC hdbc,
|
||
|
|
SQLCHAR *szDSN,
|
||
|
|
SQLSMALLINT cbDSN,
|
||
|
|
SQLCHAR *szUID,
|
||
|
|
SQLSMALLINT cbUID,
|
||
|
|
SQLCHAR *szAuthStr,
|
||
|
|
SQLSMALLINT cbAuthStr);</pre>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Function arguments</h4>
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="all"><caption>Table 1. SQLConnect arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="20%" id="d0e61">Data type</th>
|
||
|
|
<th align="left" valign="bottom" width="20%" id="d0e63">Argument</th>
|
||
|
|
<th align="left" valign="bottom" width="20%" id="d0e65">Use</th>
|
||
|
|
<th align="left" valign="bottom" width="40%" id="d0e67">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="20%" headers="d0e61 ">SQLCHAR *</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e63 "><em>szAuthStr</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e65 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e67 ">Authentication string (password).</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e61 ">SQLCHAR *</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e63 "><em>szDSN</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e65 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e67 ">Data source: name or alias name of the database.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e61 ">SQLCHAR *</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e63 "><em>szUID</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e65 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e67 ">Authorization name (user identifier).</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e61 ">SQLHDBC</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e63 "><em>hdbc</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e65 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e67 ">Connection handle.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e61 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e63 "><em>cbAuthStr</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e65 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e67 ">Length of contents of <em>szAuthStr</em> argument.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e61 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e63 "><em>cbDSN</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e65 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e67 ">Length of contents of <em>szDSN</em> argument.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e61 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e63 "><em>cbUID</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e65 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e67 ">Length of contents of <em>szUID</em> argument.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p>You can define various connection characteristics
|
||
|
|
(options) in the application using <samp class="codeph">SQLSetConnectOption()</samp>.</p>
|
||
|
|
<p>The
|
||
|
|
input length arguments to <samp class="codeph">SQLConnect()</samp> (<em>cbDSN</em>, <em>cbUID</em>, <em>cbAuthStr</em>)
|
||
|
|
can be set to the actual length of their associated data. This does not include
|
||
|
|
any null-terminating character or to SQL_NTS to indicate that the associated
|
||
|
|
data is null-terminated.</p>
|
||
|
|
<p>Leading and trailing blanks in the <em>szDSN</em> and <em>szUID</em> argument
|
||
|
|
values are stripped before processing unless they are enclosed in quotation
|
||
|
|
marks.</p>
|
||
|
|
<p>When <a href="rzadpsqlapd.htm#rzadpsqlapd">running in server
|
||
|
|
mode</a>, both <em>szUID</em> and <em>szAuthStr</em> must be passed in order
|
||
|
|
for the connection to run on behalf of a user ID other than the current user.
|
||
|
|
If either parameter is NULL or both are NULL, the connection is started using
|
||
|
|
the user ID that is in effect for the current job running the CLI program.</p>
|
||
|
|
<p>The data source must already be defined on the system for
|
||
|
|
the connect function to work. On the IBM<sup>®</sup> <span><img src="eserver.gif" alt="eServer" /></span> platform,
|
||
|
|
you can use the Work with Relational Database Directory Entries (WRKRDBDIRE)
|
||
|
|
command to determine which data sources have been defined already, and to
|
||
|
|
optionally define additional data sources.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Return codes</h4><ul><li>SQL_SUCCESS</li>
|
||
|
|
<li>SQL_SUCCESS_WITH_INFO</li>
|
||
|
|
<li>SQL_ERROR</li>
|
||
|
|
<li>SQL_INVALID_HANDLE</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Diagnostics</h4>
|
||
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. SQLConnect SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="top" width="25%" id="d0e227">SQLSTATE</th>
|
||
|
|
<th align="left" valign="top" width="25%" id="d0e229">Description</th>
|
||
|
|
<th align="left" valign="top" width="50%" id="d0e231">Explanation</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>08</strong>001</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Unable to connect to data source</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">The driver is unable to establish a connection
|
||
|
|
with the data source (server).</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>08</strong>002</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Connection in use</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">The specified <em>hdbc</em> has been used to
|
||
|
|
establish a connection with a data source and the connection is still open.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>08</strong>004</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Data source rejected establishment of connection</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">The data source (server) rejected the establishment
|
||
|
|
of the connection.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>28</strong>000</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Authorization specification that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">The value specified for the argument <em>szUID</em> or
|
||
|
|
the value specified for the argument <em>szAuthStr</em> violated restrictions
|
||
|
|
defined by the data source.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>58</strong>004</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">System error</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">Unrecoverable system error.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>HY</strong>001</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Memory allocation failure</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">The driver is unable to allocate memory required
|
||
|
|
to support the processing or completion of the function.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>HY</strong>009</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Argument value that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">The value specified for argument <em>cbDSN</em> is
|
||
|
|
less than 0, but not equal to SQL_NTS and the argument <em>szDSN</em> is not
|
||
|
|
a null pointer. <p>The value specified for argument <em>cbUID</em> is less
|
||
|
|
than 0, but not equal to SQL_NTS and the argument <em>szUID</em> is not a null
|
||
|
|
pointer.</p>
|
||
|
|
<p>The value specified for argument <em>cbAuthStr</em> is less
|
||
|
|
than 0, but not equal to SQL_NTS and the argument <em>szAuthStr</em> is not
|
||
|
|
a null pointer.</p>
|
||
|
|
<p>A nonmatching double quotation mark (") is found in
|
||
|
|
either the <em>szDSN</em>, <em>szUID</em>, or <em>szAuthStr</em> argument.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>HY</strong>013 <strong>*</strong></td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Memory management problem</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">The driver is unable to access memory required
|
||
|
|
to support the processing or completion of the function.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="25%" headers="d0e227 "><strong>HY</strong>501 <strong>*</strong></td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e229 ">Data source name that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e231 ">A data source name that is not valid is
|
||
|
|
specified in argument <em>szDSN</em>.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p>The implicit connection
|
||
|
|
(or default database) option for IBM DBMSs is not supported. <samp class="codeph">SQLConnect()</samp> must
|
||
|
|
be called before any SQL statements can be processed. i5/OS™ does not support multiple simultaneous
|
||
|
|
connections to the same data source in a single job.</p>
|
||
|
|
<div class="p">When you are using DB2<sup>®</sup> UDB
|
||
|
|
CLI on a newer release, <samp class="codeph">SQLConnect()</samp> can encounter an SQL0144
|
||
|
|
message. This indicates that the data source (the server) has obsolete SQL
|
||
|
|
packages that must be deleted. To delete these packages, run the following
|
||
|
|
command on the server system: <pre> DLTSQLPKG SQLPKG(QGPL/QSQCLI*)
|
||
|
|
</pre>
|
||
|
|
The next <samp class="codeph">SQLConnect()</samp> creates a new SQL package.</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Example</h4></div>
|
||
|
|
<div class="example" id="rzadpfnconn__xmconn"><a name="rzadpfnconn__xmconn"><!-- --></a><p>Refer to the example in <a href="rzadpfnaenv.htm"><samp class="codeph">SQLAllocEnv()</samp></a>.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">References</h4><ul><li><a href="rzadpfnacon.htm#rzadpfnacon">SQLAllocConnect - Allocate connection handle</a></li>
|
||
|
|
<li><a href="rzadpfnastmt.htm#rzadpfnastmt">SQLAllocStmt - Allocate a statement handle</a></li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div>
|
||
|
|
<div class="familylinks">
|
||
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="rzadphdapi.htm" title="This topic provides a description of each CLI function.">DB2 UDB CLI functions</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|