208 lines
9.9 KiB
HTML
208 lines
9.9 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="SQLAllocConnect - Allocate connection handle" />
|
||
|
|
<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="rzadpfnacon" />
|
||
|
|
<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>SQLAllocConnect - Allocate connection handle</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzadpfnacon"><a name="rzadpfnacon"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">SQLAllocConnect - Allocate connection handle</h1>
|
||
|
|
<div><div class="section"></div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLAllocConnect()</samp> allocates
|
||
|
|
a connection handle and associated resources within the environment identified
|
||
|
|
by the input environment handle. Call <samp class="codeph">SQLGetInfo()</samp> with <samp class="codeph">fInfoType</samp> set
|
||
|
|
to SQL_ACTIVE_CONNECTIONS, to query the number of connections that can be
|
||
|
|
allocated at any one time.</p>
|
||
|
|
<p><samp class="codeph">SQLAllocEnv()</samp> must be called
|
||
|
|
before calling this function.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4> <pre>SQLRETURN SQLAllocConnect (SQLHENV henv,
|
||
|
|
SQLHDBC *phdbc);</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. SQLAllocConnect arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="20%" id="d0e65">Data type</th>
|
||
|
|
<th align="left" valign="bottom" width="20%" id="d0e67">Argument</th>
|
||
|
|
<th align="left" valign="bottom" width="20%" id="d0e69">Use</th>
|
||
|
|
<th align="left" valign="bottom" width="40%" id="d0e71">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="20%" headers="d0e65 ">SQLHDBC *</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e67 "><em>phdbc</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e69 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e71 ">Pointer to connection handle</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="20%" headers="d0e65 ">SQLHENV</td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e67 "><em>henv</em></td>
|
||
|
|
<td align="left" valign="top" width="20%" headers="d0e69 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40%" headers="d0e71 ">Environment handle</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4> <p>The output connection handle is used by DB2<sup>®</sup> UDB
|
||
|
|
CLI to reference all information related to the connection, including general
|
||
|
|
status information, transaction state, and error information.</p>
|
||
|
|
<p>If the
|
||
|
|
pointer to the connection handle (<em>phdbc</em>) points to a valid connection
|
||
|
|
handle allocated by <samp class="codeph">SQLAllocConnect()</samp>, the original value
|
||
|
|
is overwritten as a result of this call. This is an application programming
|
||
|
|
error and is not detected by DB2 UDB CLI</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Return codes</h4> <ul><li>SQL_SUCCESS</li>
|
||
|
|
<li>SQL_ERROR</li>
|
||
|
|
<li>SQL_INVALID_HANDLE</li>
|
||
|
|
</ul>
|
||
|
|
<p>If SQL_ERROR is returned, the <em>phdbc</em> argument
|
||
|
|
is set to SQL_NULL_HDBC. The application should call <samp class="codeph">SQLError()</samp> with
|
||
|
|
the environment handle (<em>henv</em>), with <em>hdbc</em> set to SQL_NULL_HDBC,
|
||
|
|
and with <em>hstmt</em> set to SQL_NULL_HSTMT.</p>
|
||
|
|
</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. SQLAllocConnect SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="25%" id="d0e160">CLI SQLSTATE</th>
|
||
|
|
<th align="left" valign="bottom" width="25%" id="d0e162">Description</th>
|
||
|
|
<th align="left" valign="bottom" width="50%" id="d0e164">Explanation</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="25%" headers="d0e160 "><strong>HY</strong>001</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e162 ">Memory allocation failure</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e164 ">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="d0e160 "><strong>HY</strong>009</td>
|
||
|
|
<td align="left" valign="top" width="25%" headers="d0e162 ">Argument value that is not valid</td>
|
||
|
|
<td align="left" valign="top" width="50%" headers="d0e164 "><em>phdbc</em> is a null pointer.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Example</h4></div>
|
||
|
|
<div class="example" id="rzadpfnacon__xmacon"><a name="rzadpfnacon__xmacon"><!-- --></a> <p>The following example shows how to
|
||
|
|
obtain diagnostic information for the connection and the environment. For
|
||
|
|
more examples of using <samp class="codeph">SQLError()</samp>, refer to <a href="rzadpxminter.htm#rzadpxminter">Example: Interactive SQL and the equivalent DB2 UDB CLI function calls</a> for
|
||
|
|
a complete listing of <samp class="codeph">typical.c</samp>. </p>
|
||
|
|
<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>
|
||
|
|
<div class="p"> <pre>/*******************************************************************
|
||
|
|
** initialize
|
||
|
|
** - allocate environment handle
|
||
|
|
** - allocate connection handle
|
||
|
|
** - prompt for server, user id, & password
|
||
|
|
** - connect to server
|
||
|
|
*******************************************************************/
|
||
|
|
|
||
|
|
int initialize(SQLHENV *henv,
|
||
|
|
SQLHDBC *hdbc)
|
||
|
|
{
|
||
|
|
SQLCHAR server[SQL_MAX_DSN_LENGTH],
|
||
|
|
uid[30],
|
||
|
|
pwd[30];
|
||
|
|
SQLRETURN rc;
|
||
|
|
|
||
|
|
SQLAllocEnv (henv); /* allocate an environment handle */
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
|
||
|
|
|
||
|
|
SQLAllocConnect (*henv, hdbc); /* allocate a connection handle */
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
|
||
|
|
|
||
|
|
printf("Enter Server Name:\n");
|
||
|
|
gets(server);
|
||
|
|
printf("Enter User Name:\n");
|
||
|
|
gets(uid);
|
||
|
|
printf("Enter Password Name:\n");
|
||
|
|
gets(pwd);
|
||
|
|
|
||
|
|
if (uid[0] == '\0')
|
||
|
|
{ rc = SQLConnect (*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS);
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
|
||
|
|
}
|
||
|
|
else
|
||
|
|
{ rc = SQLConnect (*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS);
|
||
|
|
if (rc != SQL_SUCCESS )
|
||
|
|
check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc);
|
||
|
|
}
|
||
|
|
}/* end initialize */
|
||
|
|
|
||
|
|
|
||
|
|
/*******************************************************************/
|
||
|
|
int check_error (SQLHENV henv,
|
||
|
|
SQLHDBC hdbc,
|
||
|
|
SQLHSTMT hstmt,
|
||
|
|
SQLRETURN frc)
|
||
|
|
{
|
||
|
|
SQLRETURN rc;
|
||
|
|
|
||
|
|
print_error(henv, hdbc, hstmt);
|
||
|
|
|
||
|
|
switch (frc){
|
||
|
|
case SQL_SUCCESS : break;
|
||
|
|
case SQL_ERROR :
|
||
|
|
case SQL_INVALID_HANDLE:
|
||
|
|
printf("\n ** FATAL ERROR, Attempting to rollback transaction **\n");
|
||
|
|
rc = SQLTransact(henv, hdbc, SQL_ROLLBACK);
|
||
|
|
if (rc != SQL_SUCCESS)
|
||
|
|
printf("Rollback Failed, Exiting application\n");
|
||
|
|
else
|
||
|
|
printf("Rollback Successful, Exiting application\n");
|
||
|
|
terminate(henv, hdbc);
|
||
|
|
exit(frc);
|
||
|
|
break;
|
||
|
|
case SQL_SUCCESS_WITH_INFO :
|
||
|
|
printf("\n ** Warning Message, application continuing\n");
|
||
|
|
break;
|
||
|
|
case SQL_NO_DATA_FOUND :
|
||
|
|
printf("\n ** No Data Found ** \n");
|
||
|
|
break;
|
||
|
|
default :
|
||
|
|
printf("\n ** Invalid Return Code ** \n");
|
||
|
|
printf(" ** Attempting to rollback transaction **\n");
|
||
|
|
SQLTransact(henv, hdbc, SQL_ROLLBACK);
|
||
|
|
terminate(henv, hdbc);
|
||
|
|
exit(frc);
|
||
|
|
break;
|
||
|
|
}
|
||
|
|
return(SQL_SUCCESS);
|
||
|
|
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">References</h4> <ul><li><a href="rzadpfnaenv.htm#rzadpfnaenv">SQLAllocEnv - Allocate environment handle</a></li>
|
||
|
|
<li><a href="rzadpfnconn.htm#rzadpfnconn">SQLConnect - Connect to a data source</a></li>
|
||
|
|
<li><a href="rzadpfndconn.htm#rzadpfndconn">SQLDisconnect - Disconnect from a data source</a></li>
|
||
|
|
<li><a href="rzadpfnfconn.htm#rzadpfnfconn">SQLFreeConnect - Free connection handle</a></li>
|
||
|
|
<li><a href="rzadpfngcona.htm#rzadpfngcona">SQLGetConnectAttr - Get the value of a connection attribute</a></li>
|
||
|
|
<li><a href="rzadpfnscono.htm#rzadpfnscono">SQLSetConnectOption - Set connection option</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>
|