friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.cli_5.4.0.1/rzadpfnconn.htm

209 lines
13 KiB
HTML
Raw Permalink Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<?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>
Reference in New Issue Copy Permalink