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/rzadpfndvcon.htm

283 lines
17 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="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>-+-------------->&lt;
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, &amp;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>
Reference in New Issue Copy Permalink