forked from docs/doc-exports
Lu, Huayi
a24ca60074
Reviewed-by: Hasko, Vladimir <vladimir.hasko@t-systems.com> Co-authored-by: Lu, Huayi <luhuayi@huawei.com> Co-committed-by: Lu, Huayi <luhuayi@huawei.com>
57 lines
9.5 KiB
HTML
57 lines
9.5 KiB
HTML
<a name="EN-US_TOPIC_0000001098655180"></a><a name="EN-US_TOPIC_0000001098655180"></a>
|
|
|
|
<h1 class="topictitle1">SQLAllocHandle</h1>
|
|
<div id="body8662426"><div class="section" id="EN-US_TOPIC_0000001098655180__s16209aecb17648f99baea97873ffc9cd"><h4 class="sectiontitle">Function</h4><p id="EN-US_TOPIC_0000001098655180__a82b10c0a79c243a3aa9a7a98e9839ce4"><strong id="EN-US_TOPIC_0000001098655180__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_0000001098655180__b842352706171351">SQLAllocEnv</strong>, <strong id="EN-US_TOPIC_0000001098655180__b842352706171356">SQLAllocConnect</strong>, and <strong id="EN-US_TOPIC_0000001098655180__b84235270617140">SQLAllocStmt</strong>.</p>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001098655180__sa2d530f08ccd4985ae75aea0750a4259"><h4 class="sectiontitle">Prototype</h4><div class="codecoloring" codetype="Cpp" id="EN-US_TOPIC_0000001098655180__s4735cfadfbdf40539f4b549fd9fb38f5"><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><span class="w"></span>
|
|
</pre></div></td></tr></table></div>
|
|
|
|
</div>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001098655180__s440f995b44244a1b9d4e0aa3cbb84f11"><h4 class="sectiontitle">Parameter</h4>
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="EN-US_TOPIC_0000001098655180__t2dc2c0a9b8914fb8ac019bad54f24376" frame="border" border="1" rules="all"><caption><b>Table 1 </b>SQLAllocHandle parameters</caption><thead align="left"><tr id="EN-US_TOPIC_0000001098655180__r7b1b8d12cbd849a7accbf3de7bf0feb2"><th align="left" class="cellrowborder" valign="top" width="23.27%" id="mcps1.3.3.2.2.3.1.1"><p id="EN-US_TOPIC_0000001098655180__ad94671b3bb3f43f98519bdb7a484ccd0">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_0000001098655180__aa6edebe16730412bab431ab101a46ea4">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="EN-US_TOPIC_0000001098655180__ra2e494e6b7d64557bb6008d3255e4172"><td class="cellrowborder" valign="top" width="23.27%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001098655180__ac4d9cd646f8540a7963998b09ac1426d">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_0000001098655180__ae4763f319607424698d46ae136e7af0c">The type of handle to be allocated by SQLAllocHandle. The value must be one of the following:</p>
|
|
<ul id="EN-US_TOPIC_0000001098655180__u47b3d4d67dda45acad5a3aab347a160a"><li id="EN-US_TOPIC_0000001098655180__l629d1b186bcf4e36a8bf9f9fae9b6a5f">SQL_HANDLE_ENV (environment handle)</li><li id="EN-US_TOPIC_0000001098655180__l9e0af902c345403ba2784f2d9e29845f">SQL_HANDLE_DBC (connection handle)</li><li id="EN-US_TOPIC_0000001098655180__l86fb9cb7c0d343ff94acd364e7ee50b1">SQL_HANDLE_STMT (statement handle)</li><li id="EN-US_TOPIC_0000001098655180__lbd4a730665204f72a3930d14bef7921d">SQL_HANDLE_DESC (description handle)</li></ul>
|
|
<p id="EN-US_TOPIC_0000001098655180__afe5bd4b6e7154a26bcbb35569c71b606">The handle application sequence is: <strong id="EN-US_TOPIC_0000001098655180__b842352706171638">SQL_HANDLE_ENV</strong> > <strong id="EN-US_TOPIC_0000001098655180__b842352706171641">SQL_HANDLE_DBC</strong> > <strong id="EN-US_TOPIC_0000001098655180__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_0000001098655180__r4377cd4fb9674653b3f1b916ed4354ec"><td class="cellrowborder" valign="top" width="23.27%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001098655180__ad907d1c935b04dcd8d631bf7da8214bc">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_0000001098655180__a0abeef19a6bf4e2c948f278815431a8e">Existing handle to use as a context for the new handle being allocated.</p>
|
|
<ul id="EN-US_TOPIC_0000001098655180__u72d8bf99a61b4846bfde6612bbbeb02b"><li id="EN-US_TOPIC_0000001098655180__l79938393aef544bbaaa316491d199727">If <strong id="EN-US_TOPIC_0000001098655180__b842352706171827">HandleType</strong> is <strong id="EN-US_TOPIC_0000001098655180__b842352706171831">SQL_HANDLE_ENV</strong>, this is SQL_NULL_HANDLE.</li><li id="EN-US_TOPIC_0000001098655180__lefc51fe80d5b4974a3e26af40102592a">If <strong id="EN-US_TOPIC_0000001098655180__b842352706171819">HandleType</strong> is <strong id="EN-US_TOPIC_0000001098655180__b842352706171821">SQL_HANDLE_DBC</strong>, this must be an environment handle.</li><li id="EN-US_TOPIC_0000001098655180__l0504d38ce4744828aae8e1aa64429757">If <strong id="EN-US_TOPIC_0000001098655180__b842352706171833">HandleType</strong> is <strong id="EN-US_TOPIC_0000001098655180__b842352706171835">SQL_HANDLE_STMT</strong> or <strong id="EN-US_TOPIC_0000001098655180__b842352706171839">SQL_HANDLE_DESC</strong>, it must be a connection handle.</li></ul>
|
|
</td>
|
|
</tr>
|
|
<tr id="EN-US_TOPIC_0000001098655180__rdf5bbcaf1e4f4ed399e41a348e2e5b84"><td class="cellrowborder" valign="top" width="23.27%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001098655180__adb1a9f94d1624c098790d05bd96bb338">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_0000001098655180__ab2c5e216ca5949f9b994911d802666ad"><strong id="EN-US_TOPIC_0000001098655180__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_0000001098655180__s49026e8d635c4e9c9c2ce8505e65225f"><h4 class="sectiontitle">Return Values</h4><ul id="EN-US_TOPIC_0000001098655180__u7dcad80fdbe94ca591a284d5133cbd99"><li id="EN-US_TOPIC_0000001098655180__ld0483fbab34e44f89435f1f7a02dd6d6"><strong id="EN-US_TOPIC_0000001098655180__b842352706112950">SQL_SUCCESS</strong> indicates that the call succeeded.</li><li id="EN-US_TOPIC_0000001098655180__l3f132d9a472449f2b52eb88fd2fdc3e3"><strong id="EN-US_TOPIC_0000001098655180__b842352706112952">SQL_SUCCESS_WITH_INFO</strong> indicates some warning information is displayed.</li><li id="EN-US_TOPIC_0000001098655180__l9506ed79c1334d5d8d310a6022d429bb"><strong id="EN-US_TOPIC_0000001098655180__b842352706112954">SQL_ERROR</strong> indicates major errors, such as memory allocation and connection failures.</li><li id="EN-US_TOPIC_0000001098655180__l6458ee920fe141f88e007d723dfca8cf"><strong id="EN-US_TOPIC_0000001098655180__b842352706112956">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_0000001098655180__s2ad7a788a18c4554a43f3eb0fcbb1941"><h4 class="sectiontitle">Precautions</h4><p id="EN-US_TOPIC_0000001098655180__ab9799f81262e40c78613ce414a78bd20">When allocating a non-environment handle, if <strong id="EN-US_TOPIC_0000001098655180__abf982bb7372848bbaeaa66589487031d">SQLAllocHandle</strong> returns <strong id="EN-US_TOPIC_0000001098655180__a38c8bbdd92bd46c387811e1aaf101f81">SQL_ERROR</strong>, it sets <strong id="EN-US_TOPIC_0000001098655180__a7ea3d31a129e4484b09b861e30f7bd61">OutputHandlePtr</strong> to <strong id="EN-US_TOPIC_0000001098655180__a1997ed4828354d8294f6b8bb250acfb7">SQL_NULL_HENV</strong>, <strong id="EN-US_TOPIC_0000001098655180__a29c284e19c154594b60334bd1cf18e19">SQL_NULL_HDBC</strong>, <strong id="EN-US_TOPIC_0000001098655180__ab45d5aa81596455ba545ca21bf050672">SQL_NULL_HSTMT</strong>, or <strong id="EN-US_TOPIC_0000001098655180__aefc216e8e78b446ab6289fb41db21154">SQL_NULL_HDESC</strong>. The application can then call <a href="dws_04_0143.html">SQLGetDiagRec</a>, with <strong id="EN-US_TOPIC_0000001098655180__adf51077bc3ea4748baff5d90ccac407a">HandleType</strong> and <strong id="EN-US_TOPIC_0000001098655180__afb8338d65f1f430db6c8d6a3418e484f">Handle</strong> set to <strong id="EN-US_TOPIC_0000001098655180__ac75c63fdc1f84963a046d16bee7224c2">IntputHandle</strong>, to obtain the <strong id="EN-US_TOPIC_0000001098655180__a703f1328c77547668290bac182e0fffc">SQLSTATE</strong> value. The <strong id="EN-US_TOPIC_0000001098655180__a1ddce674009c474683a1646d29e28076">SQLSTATE</strong> value provides the detailed function calling information.</p>
|
|
</div>
|
|
<div class="section" id="EN-US_TOPIC_0000001098655180__sbdf14ce695cd4b3787c0786388c288f0"><h4 class="sectiontitle">Examples</h4><p id="EN-US_TOPIC_0000001098655180__a188f42d019d54f4f9614bd0e8332379c">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>
|
|
|