283 lines
17 KiB
HTML
283 lines
17 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="SQLDriverConnect - (Expanded) Connect to a data source" />
|
||
<meta name="DC.Relation" scheme="URI" content="rzadphdapi.htm" />
|
||
<meta name="DC.Relation" scheme="URI" content="rzadpfnconn.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="rzadpfndvcon" />
|
||
<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>SQLDriverConnect - (Expanded) Connect to a data source</title>
|
||
</head>
|
||
<body id="rzadpfndvcon"><a name="rzadpfndvcon"><!-- --></a>
|
||
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
<h1 class="topictitle1">SQLDriverConnect - (Expanded) Connect to a data source</h1>
|
||
<div><div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLDriverConnect()</samp> is an alternative
|
||
to <samp class="codeph">SQLConnect()</samp>. Both functions establish a
|
||
connection to the target database, but <samp class="codeph">SQLDriverConnect()</samp> uses
|
||
a connection string to determine the data source name, user ID and password.
|
||
The functions are the same; both are supported for compatibility purposes.</p>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLDriverConnect (SQLHDBC ConnectionHandle,
|
||
SQLHWND WindowHandle,
|
||
SQLCHAR *InConnectionString,
|
||
SQLSMALLINT StringLength1,
|
||
SQLCHAR *OutConnectionString,
|
||
SQLSMALLINT BufferLength,
|
||
SQLSMALLINT *StringLength2Ptr,
|
||
SQLSMALLINT DriverCompletion);</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. SQLDriverConnect arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="17.59259259259259%" id="d0e53">Data type</th>
|
||
<th align="left" valign="bottom" width="23.51851851851852%" id="d0e55">Argument </th>
|
||
<th align="left" valign="bottom" width="11.851851851851853%" id="d0e57">Use </th>
|
||
<th align="left" valign="bottom" width="47.03703703703704%" id="d0e59">Description </th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLCHAR *</td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">InConnectionString</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 "><p>A full, partial, or empty
|
||
(null pointer) connection string.</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLCHAR *</td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">OutConnectionString</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Output </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Pointer to buffer for the completed connection
|
||
string. <p> If the connection is established successfully, this buffer contains
|
||
the completed connection string.</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLHDBC </td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">ConnectionHandle</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Connection handle.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLHWND </td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">hwindow</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 "><p>For DB2
|
||
Universal Database™ for Linux<sup>®</sup>, UNIX<sup>®</sup>, and Windows<sup>®</sup>, this is the parent handle.
|
||
On i5/OS™,
|
||
it is ignored.</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLSMALLINT *</td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">StringLength2Ptr</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Output </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Pointer to the number of bytes available
|
||
to return in the <span class="synph"><span class="var">OutConnectionString</span></span> buffer. <p>If
|
||
the value of <span class="synph"><span class="var">StringLength2Ptr</span></span> is greater than or
|
||
equal to <span class="synph"><span class="var">BufferLength</span></span>, the completed connection
|
||
string in <span class="synph"><span class="var">OutConnectionString</span></span> is truncated to <span class="synph"><span class="var">BufferLength</span></span> -
|
||
1 bytes.</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLSMALLINT </td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">DriverCompletion</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Indicates when DB2<sup>®</sup> UDB CLI should prompt the user for more
|
||
information. <div class="p">Possible values: <ul><li>SQL_DRIVER_COMPLETE</li>
|
||
<li>SQL_DRIVER_COMPLETE_REQUIRED</li>
|
||
<li>SQL_DRIVER_NOPROMPT</li>
|
||
</ul>
|
||
</div>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLSMALLINT </td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">BufferLength</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Maximum size of the buffer pointed to by <span class="synph"><span class="var">OutConnectionString</span></span>.</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e53 ">SQLSMALLINT </td>
|
||
<td align="left" valign="top" width="23.51851851851852%" headers="d0e55 "><span class="synph"><span class="var">StringLength1</span></span> </td>
|
||
<td align="left" valign="top" width="11.851851851851853%" headers="d0e57 ">Input </td>
|
||
<td align="left" valign="top" width="47.03703703703704%" headers="d0e59 ">Length of <span class="synph"><span class="var">InConnectionString</span></span>.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Usage</h4><p>The connection string is used to pass one
|
||
or more values that are needed to complete a connection. The contents of the
|
||
connection string and the value of <span class="synph"><span class="var">DriverCompletion</span></span> determine
|
||
how the connection should be established.</p>
|
||
<pre><span><img src="./c.gif" border="0" alt="Read syntax diagram" longdesc="rzadpfndvconsyn1.htm" /></span><a href="#d0e230"><img src="./c.gif" border="0" alt="Skip visual syntax diagram" /></a>
|
||
.-,------------------------------------------.
|
||
V |
|
||
>>---| Connection string syntax |--=--<i>attribute</i>-+--------------><
|
||
|
||
Connection string syntax
|
||
|
||
|--+-DSN-------------------------+------------------------------|
|
||
+-UID-------------------------+
|
||
+-PWD-------------------------+
|
||
'-<i>DB2 UDB CLI-defined-keyword</i>-'
|
||
|
||
</pre><a name="d0e230"></a> <div class="p">Each keyword above has an attribute that is equal to: <dl><dt class="dlterm">DSN </dt>
|
||
<dd>Data source name. The name or alias-name of the database. The data source
|
||
name is required if <span class="synph"><span class="var">DriverCompletion</span></span> is equal to
|
||
SQL_DRIVER_NOPROMPT.</dd>
|
||
<dt class="dlterm">UID </dt>
|
||
<dd>Authorization-name (user identifier).</dd>
|
||
<dt class="dlterm">PWD </dt>
|
||
<dd>The password that corresponds to the authorization name. If there is no
|
||
password for the user ID, empty is specified (PWD=;).</dd>
|
||
</dl>
|
||
</div>
|
||
<p><span class="keyword">iSeries™</span> currently
|
||
has no DB2 UDB
|
||
CLI-defined keywords.</p>
|
||
<p>The value of <span class="synph"><span class="var">DriverCompletion</span></span> is
|
||
verified to be valid, but all result in the same behavior. A connection is
|
||
attempted with the information that is contained in the connection string.
|
||
If there is not enough information, SQL_ERROR is returned.</p>
|
||
<p>As soon as
|
||
a connection is established, the complete connection string is returned. Applications
|
||
that need to set up multiple connections to the same database for a given
|
||
user ID should store this output connection string. This string can then be
|
||
used as the input connection string value on future <samp class="codeph">SQLDriverConnect()</samp> calls.</p>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Return codes</h4><ul><li>SQL_SUCCESS</li>
|
||
<li>SQL_SUCCESS_WITH_INFO</li>
|
||
<li>SQL_NO_DATA_FOUND</li>
|
||
<li>SQL_INVALID_HANDLE</li>
|
||
<li>SQL_ERROR</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Error conditions</h4><p> All of the diagnostics that are
|
||
generated by <samp class="codeph">SQLConnect()</samp> can be returned here as well.
|
||
The following table shows the additional diagnostics that can be returned.</p>
|
||
|
||
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. SQLDriverConnect SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="12.962962962962962%" id="d0e326">SQLSTATE </th>
|
||
<th align="left" valign="bottom" width="29.074074074074076%" id="d0e328">Description </th>
|
||
<th align="left" valign="bottom" width="57.96296296296296%" id="d0e330">Explanation </th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e326 "><strong>01</strong>004 </td>
|
||
<td align="left" valign="top" width="29.074074074074076%" headers="d0e328 ">Data truncated</td>
|
||
<td align="left" valign="top" width="57.96296296296296%" headers="d0e330 ">The buffer <span class="synph"><span class="var">szConnstrOut</span></span> is
|
||
not large enough to hold the entire connection string. The argument <span class="synph"><span class="var">StringLength2Ptr</span></span> contains
|
||
the actual length of the connection string available for return. (Function
|
||
returns SQL_SUCCESS_WITH_INFO)</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e326 "><strong>01</strong>S00 </td>
|
||
<td align="left" valign="top" width="29.074074074074076%" headers="d0e328 ">Connection string attribute that is not valid</td>
|
||
<td align="left" valign="top" width="57.96296296296296%" headers="d0e330 ">A keyword or attribute value that is not
|
||
valid is specified in the input connection string, but the connection to the
|
||
data source is successful anyway because one of the following situations occurs:
|
||
<ul><li>The unrecognized keyword is ignored.</li>
|
||
<li>The attribute value that is not valid is ignored, the default value is
|
||
used instead.</li>
|
||
</ul>
|
||
<p>(Function returns SQL_SUCCESS_WITH_INFO)</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e326 "><strong>HY</strong>009</td>
|
||
<td align="left" valign="top" width="29.074074074074076%" headers="d0e328 ">Argument value that is not valid </td>
|
||
<td align="left" valign="top" width="57.96296296296296%" headers="d0e330 ">The argument <span class="synph"><span class="var">InConnectionString</span></span>, <span class="synph"><span class="var">OutConnectionString</span></span>,
|
||
or <span class="synph"><span class="var">StringLength2PTR</span></span> is a null pointer. <p>The
|
||
argument DriverCompletion is not equal to 1.</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e326 "><strong>HY</strong>090</td>
|
||
<td align="left" valign="top" width="29.074074074074076%" headers="d0e328 ">String or buffer length that is not valid</td>
|
||
<td align="left" valign="top" width="57.96296296296296%" headers="d0e330 ">The value specified for <span class="synph"><span class="var">StringLength1</span></span> is
|
||
less than 0, but not equal to SQL_NTS. <p>The value specified for <span class="synph"><span class="var">BufferLength</span></span> is
|
||
less than 0.</p>
|
||
</td>
|
||
</tr>
|
||
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e326 "><strong>HY</strong>110 </td>
|
||
<td align="left" valign="top" width="29.074074074074076%" headers="d0e328 ">Driver completion that is not valid</td>
|
||
<td align="left" valign="top" width="57.96296296296296%" headers="d0e330 ">The value specified for the argument <span class="synph"><span class="var">fCompletion</span></span> is
|
||
not equal to one of the valid values.</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p>None.</p>
|
||
</div>
|
||
<div class="section"><h4 class="sectiontitle">Example</h4></div>
|
||
<div class="example" id="rzadpfndvcon__xmdvcon"><a name="rzadpfndvcon__xmdvcon"><!-- --></a><div class="note"><span class="notetitle">Note:</span> By using the code examples, you agree to the terms
|
||
of the <a href="codedisclaimer.htm">Code license and disclaimer information</a>.</div>
|
||
<pre>/* From CLI sample drivrcon.c */
|
||
/* ... */
|
||
/********************************************************************
|
||
** drv_connect - Prompt for connect options and connect **
|
||
********************************************************************/
|
||
|
||
int
|
||
drv_connect(SQLHENV henv,
|
||
SQLHDBC * hdbc,
|
||
SQLCHAR con_type)
|
||
{
|
||
SQLRETURN rc;
|
||
SQLCHAR server[SQL_MAX_DSN_LENGTH + 1];
|
||
SQLCHAR uid[MAX_UID_LENGTH + 1];
|
||
SQLCHAR pwd[MAX_PWD_LENGTH + 1];
|
||
SQLCHAR con_str[255];
|
||
SQLCHAR buffer[255];
|
||
SQLSMALLINT outlen;
|
||
|
||
printf("Enter Server Name:\n");
|
||
gets((char *) server);
|
||
printf("Enter User Name:\n");
|
||
gets((char *) uid);
|
||
printf("Enter Password Name:\n");
|
||
gets((char *) pwd);
|
||
|
||
/* Allocate a connection handle */
|
||
SQLAllocHandle( SQL_HANDLE_DBC,
|
||
henv,
|
||
hdbc
|
||
);
|
||
CHECK_HANDLE( SQL_HANDLE_DBC, *hdbc, rc);
|
||
|
||
sprintf((char *)con_str, "DSN=%s;UID=%s;PWD=%s;",
|
||
server, uid, pwd);
|
||
|
||
rc = SQLDriverConnect(*hdbc,
|
||
(SQLHWND) NULL,
|
||
con_str,
|
||
SQL_NTS,
|
||
buffer, 255, &outlen,
|
||
SQL_DRIVER_NOPROMPT);
|
||
if (rc != SQL_SUCCESS) {
|
||
printf("Error while connecting to database, RC= %ld\n", rc);
|
||
CHECK_HANDLE( SQL_NULL_HENV, *hdbc, rc);
|
||
return (SQL_ERROR);
|
||
} else {
|
||
printf("Successful Connect\n");
|
||
return (SQL_SUCCESS);
|
||
}
|
||
}</pre>
|
||
</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 class="relref"><strong>Related reference</strong><br />
|
||
<div><a href="rzadpfnconn.htm">SQLConnect - Connect to a data source</a></div>
|
||
</div>
|
||
</div>
|
||
</body>
|
||
</html>
|