forked from docs/doc-exports
Lu, Huayi
e6fa411af0
Reviewed-by: Pruthi, Vineet <vineet.pruthi@t-systems.com> Co-authored-by: Lu, Huayi <luhuayi@huawei.com> Co-committed-by: Lu, Huayi <luhuayi@huawei.com>
57 lines
9.6 KiB
HTML
57 lines
9.6 KiB
HTML
<a name="EN-US_TOPIC_0000001188323564"></a><a name="EN-US_TOPIC_0000001188323564"></a>
|
|
|
|
<h1 class="topictitle1">SQLAllocHandle</h1>
|
|
<div id="body8662426"><div class="section" id="EN-US_TOPIC_0000001188323564__s38b5b483faf546cd8835045ec2de4269"><h4 class="sectiontitle">Function</h4><p id="EN-US_TOPIC_0000001188323564__a33f5aa294ea944bca79407a62872c608"><strong id="EN-US_TOPIC_0000001188323564__b842352706171321">SQLAllocHandle</strong> allocates environment, connection, or statement handles. This function is a generic function for allocating handles that replaces the deprecated ODBC 2.x functions <strong id="EN-US_TOPIC_0000001188323564__b842352706171351">SQLAllocEnv</strong>, <strong id="EN-US_TOPIC_0000001188323564__b842352706171356">SQLAllocConnect</strong>, and <strong id="EN-US_TOPIC_0000001188323564__b84235270617140">SQLAllocStmt</strong>.</p>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001188323564__s412ef59a58b147608e588003d94f1fc0"><h4 class="sectiontitle">Prototype</h4><div class="codecoloring" codetype="Cpp" id="EN-US_TOPIC_0000001188323564__s256ead0928ef4544972f08eeb3a543c5"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
|
|
<span class="normal">2</span>
|
|
<span class="normal">3</span></pre></div></td><td class="code"><div><pre><span></span><span class="n">SQLRETURN</span><span class="w"> </span><span class="nf">SQLAllocHandle</span><span class="p">(</span><span class="n">SQLSMALLINT</span><span class="w"> </span><span class="n">HandleType</span><span class="p">,</span><span class="w"> </span>
|
|
<span class="w"> </span><span class="n">SQLHANDLE</span><span class="w"> </span><span class="n">InputHandle</span><span class="p">,</span><span class="w"> </span>
|
|
<span class="w"> </span><span class="n">SQLHANDLE</span><span class="w"> </span><span class="o">*</span><span class="n">OutputHandlePtr</span><span class="p">);</span>
|
|
</pre></div></td></tr></table></div>
|
|
|
|
</div>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001188323564__s507baa5fa7c7496e8cdecf0e96ebe295"><h4 class="sectiontitle">Parameter</h4>
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="EN-US_TOPIC_0000001188323564__t0d4910c942154745837dfa85177f3167" frame="border" border="1" rules="all"><caption><b>Table 1 </b>SQLAllocHandle parameters</caption><thead align="left"><tr id="EN-US_TOPIC_0000001188323564__r59119f94d26b4176b7c01f42177a24dc"><th align="left" class="cellrowborder" valign="top" width="23.27%" id="mcps1.3.3.2.2.3.1.1"><p id="EN-US_TOPIC_0000001188323564__a78d3cb080a2b411ab32cf5c9dbdcceca">Keyword</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="76.73%" id="mcps1.3.3.2.2.3.1.2"><p id="EN-US_TOPIC_0000001188323564__ab97dfdcd2f164f9dade3959977ce15cf">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="EN-US_TOPIC_0000001188323564__racbffbbfef2e4fef93a8912e7d106868"><td class="cellrowborder" valign="top" width="23.27%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188323564__a7e09ea9293da4c20ba20afbfa33941e8">HandleType</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="76.73%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188323564__a74aaef5484644d9f8a8e862a9cf7d7b1">The type of handle to be allocated by SQLAllocHandle. The value must be one of the following:</p>
|
|
<ul id="EN-US_TOPIC_0000001188323564__ucfe408da9d6b4075b02f694345336b0d"><li id="EN-US_TOPIC_0000001188323564__la59247d92a5a46adab3ee67f5c84e951">SQL_HANDLE_ENV (environment handle)</li><li id="EN-US_TOPIC_0000001188323564__l733bebe9f2b140d8aee2ba9ddcab236b">SQL_HANDLE_DBC (connection handle)</li><li id="EN-US_TOPIC_0000001188323564__ld381ad0ac6b9471e833f90eeda64d989">SQL_HANDLE_STMT (statement handle)</li><li id="EN-US_TOPIC_0000001188323564__lb9a25f4f86c740a5b51bc48ad695b1fd">SQL_HANDLE_DESC (description handle)</li></ul>
|
|
<p id="EN-US_TOPIC_0000001188323564__a33635347f5d8480abda63daf8c4d3127">The handle application sequence is: <strong id="EN-US_TOPIC_0000001188323564__b842352706171638">SQL_HANDLE_ENV</strong> > <strong id="EN-US_TOPIC_0000001188323564__b842352706171641">SQL_HANDLE_DBC</strong> > <strong id="EN-US_TOPIC_0000001188323564__b842352706171647">SQL_HANDLE_STMT</strong>. The handle applied later depends on the handle applied prior to it.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="EN-US_TOPIC_0000001188323564__r1bf317e27dc7413a8142e9a42a1b9da9"><td class="cellrowborder" valign="top" width="23.27%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188323564__a9c3b2c2e82474819b02069e26c84ea17">InputHandle</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="76.73%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188323564__a7e264449e6e34f74996c913df229406a">Existing handle to use as a context for the new handle being allocated.</p>
|
|
<ul id="EN-US_TOPIC_0000001188323564__ud2d234c90dde4803adcf3e0e2b8c176b"><li id="EN-US_TOPIC_0000001188323564__le4f36bcc31234d2c9e66b629b5384fed">If <strong id="EN-US_TOPIC_0000001188323564__b842352706171827">HandleType</strong> is <strong id="EN-US_TOPIC_0000001188323564__b842352706171831">SQL_HANDLE_ENV</strong>, this is SQL_NULL_HANDLE.</li><li id="EN-US_TOPIC_0000001188323564__l245a5cee8fea4326979a4dd87960484b">If <strong id="EN-US_TOPIC_0000001188323564__b842352706171819">HandleType</strong> is <strong id="EN-US_TOPIC_0000001188323564__b842352706171821">SQL_HANDLE_DBC</strong>, this must be an environment handle.</li><li id="EN-US_TOPIC_0000001188323564__l912e43c41ae14b63a5d5b68d8cf8481d">If <strong id="EN-US_TOPIC_0000001188323564__b842352706171833">HandleType</strong> is <strong id="EN-US_TOPIC_0000001188323564__b842352706171835">SQL_HANDLE_STMT</strong> or <strong id="EN-US_TOPIC_0000001188323564__b842352706171839">SQL_HANDLE_DESC</strong>, it must be a connection handle.</li></ul>
|
|
</td>
|
|
</tr>
|
|
<tr id="EN-US_TOPIC_0000001188323564__r98c21810476943b0979e186546370a56"><td class="cellrowborder" valign="top" width="23.27%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188323564__aed5176c91cbc45178aae397d86ee1d01">OutputHandlePtr</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="76.73%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188323564__af677ff303a7d4dba9461d18e4efb2a39"><strong id="EN-US_TOPIC_0000001188323564__b842352706171914">Output parameter</strong>: Pointer to a buffer in which to return the handle to the newly allocated data structure.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001188323564__sc421b19f67794739b9611ea3db979018"><h4 class="sectiontitle">Return Values</h4><ul id="EN-US_TOPIC_0000001188323564__ufc2666f3c8fa4d338e61ef60300bb199"><li id="EN-US_TOPIC_0000001188323564__l796deb1f252a43dfbacbbe06a840ccee"><strong id="EN-US_TOPIC_0000001188323564__b28272845941156">SQL_SUCCESS</strong> indicates that the call succeeded.</li><li id="EN-US_TOPIC_0000001188323564__l212edd7d305c463389d6a14f2e2e8ffc"><strong id="EN-US_TOPIC_0000001188323564__b131863155641156">SQL_SUCCESS_WITH_INFO</strong> indicates some warning information is displayed.</li><li id="EN-US_TOPIC_0000001188323564__lfd2996918e6448e98c1c34e8613d0834"><strong id="EN-US_TOPIC_0000001188323564__b210188214241156">SQL_ERROR</strong> indicates major errors, such as memory allocation and connection failures.</li><li id="EN-US_TOPIC_0000001188323564__l4544f9ead5f047f089fb39c21fde0c91"><strong id="EN-US_TOPIC_0000001188323564__b158717479341156">SQL_INVALID_HANDLE</strong> indicates that invalid handles were called. Values returned by other APIs are similar to the preceding values.</li></ul>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001188323564__s5841983c41a848e18770e07b94399f5d"><h4 class="sectiontitle">Precautions</h4><p id="EN-US_TOPIC_0000001188323564__a6bb4f94a2cd04af58391506fcc280e50">When allocating a non-environment handle, if <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b2989655616014">SQLAllocHandle</strong> returns <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b16162908154540">SQL_ERROR</strong>, it sets <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b28466141154547">OutputHandlePtr</strong> to <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b45968952154553">SQL_NULL_HENV</strong>, <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b57761530154559">SQL_NULL_HDBC</strong>, <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b3776344015466">SQL_NULL_HSTMT</strong>, or <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b51534710154615">SQL_NULL_HDESC</strong>. The application can then call <a href="dws_04_0143.html">SQLGetDiagRec</a>, with <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b1879303154633">HandleType</strong> and <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b60588960154639">Handle</strong> set to <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b61968690154647">IntputHandle</strong>, to obtain the <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b4172250815472">SQLSTATE</strong> value. The <strong id="EN-US_TOPIC_0000001188323564__en-us_topic_0058965238_b6246890815479">SQLSTATE</strong> value provides the detailed function calling information.</p>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001188323564__sfa32a2e131c44b64a86f5b8435aeab03"><h4 class="sectiontitle">Examples</h4><p id="EN-US_TOPIC_0000001188323564__a0c0d4b06069142cfa00b8d50b65c86c3">See <a href="dws_04_0123.html">Examples</a>.</p>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="dws_04_0124.html">ODBC Interfaces</a></div>
|
|
</div>
|
|
</div>
|
|
|