vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/dws/dev/dws_04_0143.html
Lu, Huayi e6fa411af0 DWS DEV 830.201 version 
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>
2024-05-16 07:24:04 +00:00

153 lines
19 KiB
HTML
Raw Blame History

<a name="EN-US_TOPIC_0000001188482286"></a><a name="EN-US_TOPIC_0000001188482286"></a>
<h1 class="topictitle1">SQLGetDiagRec</h1>
<div id="body8662426"><div class="section" id="EN-US_TOPIC_0000001188482286__sc3cd4e0a2925417194793b3044b03571"><h4 class="sectiontitle">Function</h4><p id="EN-US_TOPIC_0000001188482286__a5d5e87a21f824cd180bd501cc620a3af"><strong id="EN-US_TOPIC_0000001188482286__b842352706151725">SQLGetDiagRec</strong> returns the current values of multiple fields of a diagnostic record that contains error, warning, and status information.</p>
</div>
<div class="section" id="EN-US_TOPIC_0000001188482286__s0104d3f00994487ab16c4a806200fa45"><h4 class="sectiontitle">Prototype</h4><div class="codecoloring" codetype="Cpp" id="EN-US_TOPIC_0000001188482286__s67ddfedaf97b414fb07c58020746cfe7"><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>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span>
<span class="normal">8</span></pre></div></td><td class="code"><div><pre><span></span><span class="n">SQLRETURN</span><span class="w"> </span><span class="nf">SQLGetDiagRec</span><span class="p">(</span><span class="n">SQLSMALLINT</span><span class="w"> </span><span class="n">HandleType</span>
<span class="w"> </span><span class="n">SQLHANDLE</span><span class="w"> </span><span class="n">Handle</span><span class="p">,</span>
<span class="w"> </span><span class="n">SQLSMALLINT</span><span class="w"> </span><span class="n">RecNumber</span><span class="p">,</span>
<span class="w"> </span><span class="n">SQLCHAR</span><span class="w"> </span><span class="o">*</span><span class="n">SQLState</span><span class="p">,</span>
<span class="w"> </span><span class="n">SQLINTEGER</span><span class="w"> </span><span class="o">*</span><span class="n">NativeErrorPtr</span><span class="p">,</span>
<span class="w"> </span><span class="n">SQLCHAR</span><span class="w"> </span><span class="o">*</span><span class="n">MessageText</span><span class="p">,</span>
<span class="w"> </span><span class="n">SQLSMALLINT</span><span class="w"> </span><span class="n">BufferLength</span>
<span class="w"> </span><span class="n">SQLSMALLINT</span><span class="w"> </span><span class="o">*</span><span class="n">TextLengthPtr</span><span class="p">);</span>
</pre></div></td></tr></table></div>
</div>
</div>
<div class="section" id="EN-US_TOPIC_0000001188482286__sd27712100afe423aa47e54daf4bf05ad"><h4 class="sectiontitle">Parameter</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="EN-US_TOPIC_0000001188482286__tf057683654334aef9065d1d7b0472ba9" frame="border" border="1" rules="all"><caption><b>Table 1 </b>SQLGetDiagRec parameters</caption><thead align="left"><tr id="EN-US_TOPIC_0000001188482286__r3d4dd0a9211e4c3c8f1c0a4aba581df4"><th align="left" class="cellrowborder" valign="top" width="19.12%" id="mcps1.3.3.2.2.3.1.1"><p id="EN-US_TOPIC_0000001188482286__a553bcd13f4fd49e19192ea00d93b0334">Keyword</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="80.88%" id="mcps1.3.3.2.2.3.1.2"><p id="EN-US_TOPIC_0000001188482286__a3209910b247042f69915c4a68878c90d">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="EN-US_TOPIC_0000001188482286__r49e5fb24665a4b8ab34aa5cc8db9f0d3"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__a6c72e396608742e495fcd5f7e09edefa">HandleType</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__a5db2d82ebb0d48219de70717239f0101">A handle-type identifier that describes the type of handle for which diagnostics are desired. The value must be one of the following:</p>
<ul id="EN-US_TOPIC_0000001188482286__u229539bc80d74387b86456c516bb2c3b"><li id="EN-US_TOPIC_0000001188482286__ld794f6fcbd8548358d4d7d823fb20184">SQL_HANDLE_ENV</li><li id="EN-US_TOPIC_0000001188482286__l1e4f139b49604464809c9c958a6df578">SQL_HANDLE_DBC</li><li id="EN-US_TOPIC_0000001188482286__la9c64e090b094f35a5b2bddcd5d52a64">SQL_HANDLE_STMT</li><li id="EN-US_TOPIC_0000001188482286__le438f3426aa84966a5a12404704603e5">SQL_HANDLE_DESC</li></ul>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__ra032a88bbfe14211ac74559ad08012bb"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__a82930b70ad404faa86579537f77585d6">Handle</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__afd0d3e1710de4592bcc314d5ade5c298">A handle for the diagnostic data structure. Its type is indicated by HandleType. If <strong id="EN-US_TOPIC_0000001188482286__b842352706152426">HandleType</strong> is <strong id="EN-US_TOPIC_0000001188482286__b842352706152428">SQL_HANDLE_ENV</strong>, <strong id="EN-US_TOPIC_0000001188482286__b842352706152434">Handle</strong> may be shared or non-shared environment handle.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r99c24240ca2b4b1dbd1df6f6453810a9"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__afd2461b0962448ec98e9e550a41ef0c8">RecNumber</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__a7d93b8006b394199a3fad945cc6109b6">Indicates the status record from which the application seeks information. RecNumber starts with 1.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r5f5be65ce7034c03a21a238108c0691c"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__a41b06339c2d846c986583f199653a336">SQLState</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__a99d8d0bb8fd84c3fb3c6aa5b07146aaa"><strong id="EN-US_TOPIC_0000001188482286__b842352706153247">Output parameter</strong>: pointer to a buffer that saves the 5-character <strong id="EN-US_TOPIC_0000001188482286__b842352706153252">SQLSTATE</strong> code pertaining to <strong id="EN-US_TOPIC_0000001188482286__b842352706153257">RecNumber</strong>.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r06041de5d2bd444e8c712aa7a33f131f"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__aa5445d9bb08f498183ca320316775499">NativeErrorPtr</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__a0d91bae318b745c8b543710176fdb5f4"><strong id="EN-US_TOPIC_0000001188482286__b84235270615336">Output parameter</strong>: pointer to a buffer that saves the native error code.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r6abe2996ba624bf08e0de46106dcde3a"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__a0d4ee005db8d4be9891c25113a5cd6ff">MessageText</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__a88f1e43272ec4f8fb8dc99dfde4cd586">Pointer to a buffer that saves text strings of diagnostic information.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__rd7f4f23840a246508264ba5da575f1e9"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__ad3a4de32a01f4689a7c1ce552c4c203f">BufferLength</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__add7098fdc41347fc8ce56e4d1fece7f2">Length of MessageText.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r044ac36311c746059a4cfcc15f9e23ea"><td class="cellrowborder" valign="top" width="19.12%" headers="mcps1.3.3.2.2.3.1.1 "><p id="EN-US_TOPIC_0000001188482286__a6427a8240ac344a1b26f03874c44cb42">TextLengthPtr</p>
</td>
<td class="cellrowborder" valign="top" width="80.88%" headers="mcps1.3.3.2.2.3.1.2 "><p id="EN-US_TOPIC_0000001188482286__a87af9c3a93574edf862f859f08f906c0"><strong id="EN-US_TOPIC_0000001188482286__b842352706153357">Output parameter</strong>: pointer to the buffer, the total number of bytes in the returned <strong id="EN-US_TOPIC_0000001188482286__b842352706153415">MessageText</strong>. If the number of bytes available to return is greater than <strong id="EN-US_TOPIC_0000001188482286__b842352706153423">BufferLength</strong>, then the diagnostics information text in <strong id="EN-US_TOPIC_0000001188482286__b842352706153428">MessageText</strong> is truncated to <strong id="EN-US_TOPIC_0000001188482286__b842352706153430">BufferLength</strong> minus the length of the null termination character.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="EN-US_TOPIC_0000001188482286__sde2c14bea3f744fb919579027b5b7994"><h4 class="sectiontitle">Return Values</h4><ul id="EN-US_TOPIC_0000001188482286__u073b1f5ab809472285d0e630de4a15e9"><li id="EN-US_TOPIC_0000001188482286__lce437c424be3427e9c3ce39647629563"><strong id="EN-US_TOPIC_0000001188482286__b842352706112950">SQL_SUCCESS</strong> indicates that the call succeeded.</li><li id="EN-US_TOPIC_0000001188482286__lafc60c95213e49c586daf445e071e66d"><strong id="EN-US_TOPIC_0000001188482286__b842352706112952">SQL_SUCCESS_WITH_INFO</strong> indicates some warning information is displayed.</li><li id="EN-US_TOPIC_0000001188482286__l64a32a7c018e4b06aafb12ba41c43310"><strong id="EN-US_TOPIC_0000001188482286__b842352706112954">SQL_ERROR</strong> indicates major errors, such as memory allocation and connection failures.</li><li id="EN-US_TOPIC_0000001188482286__l4afed2a205174c96ad0e6827ee20bb4c"><strong id="EN-US_TOPIC_0000001188482286__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_0000001188482286__s7d8d384e123a4cd79e32472da333427d"><h4 class="sectiontitle">Precautions</h4><p id="EN-US_TOPIC_0000001188482286__a0f0eadb4d9f84a269e8fdad4951784f8"><strong id="EN-US_TOPIC_0000001188482286__b16901252185411">SQLGetDiagRec</strong> does not release diagnostic records for itself. It uses the following returned values to report execution results:</p>
<ul id="EN-US_TOPIC_0000001188482286__ue5374e374c604f4fa155301959d48c37"><li id="EN-US_TOPIC_0000001188482286__l197a41110b1e4d0c942eb06121408598"><strong id="EN-US_TOPIC_0000001188482286__b56972406163848">SQL_SUCCESS</strong>: The function successfully returns diagnostic information.</li><li id="EN-US_TOPIC_0000001188482286__l023b528ff9ed4a9f8f0cf407f06b75c3"><strong id="EN-US_TOPIC_0000001188482286__b842352706153617">SQL_SUCCESS_WITH_INFO</strong>: The <strong id="EN-US_TOPIC_0000001188482286__b842352706153622">*MessageText</strong> buffer is too small to hold the requested diagnostic message. No diagnostic records are generated.</li><li id="EN-US_TOPIC_0000001188482286__lc349759455e54fcda783f56680abba95"><strong id="EN-US_TOPIC_0000001188482286__ae76297920fb2462698a5ad8ffb7c52a4">SQL_INVALID_HANDLE</strong>: The handle indicated by <strong id="EN-US_TOPIC_0000001188482286__a703cb78572cc49699a177546f17b6ecc">HandType</strong> and <strong id="EN-US_TOPIC_0000001188482286__a4c56049e35624f82b67df3530cae6755">Handle</strong> is not a valid handle.</li><li id="EN-US_TOPIC_0000001188482286__l536ba98da43748a2ae1b29fe2c91d6ee"><strong id="EN-US_TOPIC_0000001188482286__b842352706153635">SQL_ERROR</strong>: <strong id="EN-US_TOPIC_0000001188482286__b842352706153638">RecNumber</strong> is smaller than or equal to zero, or <strong id="EN-US_TOPIC_0000001188482286__b842352706153640">BufferLength</strong> is smaller than zero.</li></ul>
<p id="EN-US_TOPIC_0000001188482286__a0428d49df91343d2906d8a652fe6707d">If an ODBC function returns <strong id="EN-US_TOPIC_0000001188482286__b842352706153658">SQL_ERROR</strong> or <strong id="EN-US_TOPIC_0000001188482286__b84235270615370">SQL_SUCCESS_WITH_INFO</strong>, the application can then call <strong id="EN-US_TOPIC_0000001188482286__b842352706153713">SQLGetDiagRec</strong> and obtain the <strong id="EN-US_TOPIC_0000001188482286__b842352706153715">SQLSTATE</strong> value. The possible <strong id="EN-US_TOPIC_0000001188482286__b842352706153719">SQLSTATE</strong> values are listed as follows:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="EN-US_TOPIC_0000001188482286__t817eab2efee74c36b5aae5680488ad20" frame="border" border="1" rules="all"><caption><b>Table 2 </b>SQLSTATE values</caption><thead align="left"><tr id="EN-US_TOPIC_0000001188482286__r7f97b951a72f4f0789471c641ea2531e"><th align="left" class="cellrowborder" valign="top" width="20.352035203520348%" id="mcps1.3.5.5.2.4.1.1"><p id="EN-US_TOPIC_0000001188482286__ae59af2291b6a41b2aad4e329a069fb7c">SQLSATATE</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="31.983198319831978%" id="mcps1.3.5.5.2.4.1.2"><p id="EN-US_TOPIC_0000001188482286__a1442ff69382540eea186c52e2c013445">Error</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="47.66476647664767%" id="mcps1.3.5.5.2.4.1.3"><p id="EN-US_TOPIC_0000001188482286__ae7e0f1a2e9f24deeb94bc274698b96dd">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="EN-US_TOPIC_0000001188482286__rea5bb516854143f2ae2004bb10e35dcf"><td class="cellrowborder" valign="top" width="20.352035203520348%" headers="mcps1.3.5.5.2.4.1.1 "><p id="EN-US_TOPIC_0000001188482286__a5bb1ecc374064bc185c33d75d29c498b">HY000</p>
</td>
<td class="cellrowborder" valign="top" width="31.983198319831978%" headers="mcps1.3.5.5.2.4.1.2 "><p id="EN-US_TOPIC_0000001188482286__ae62f37253bd64ca3bc316fe654d70932">General error</p>
</td>
<td class="cellrowborder" valign="top" width="47.66476647664767%" headers="mcps1.3.5.5.2.4.1.3 "><p id="EN-US_TOPIC_0000001188482286__ae60b5d8460a344a19e852e1022686128">An error occurred for which there is no specific SQLSTATE.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r08946786b0b341fd97cd4287343ca519"><td class="cellrowborder" valign="top" width="20.352035203520348%" headers="mcps1.3.5.5.2.4.1.1 "><p id="EN-US_TOPIC_0000001188482286__aeb8fbe8985fe45a9b9b9965a6dbe0344">HY001</p>
</td>
<td class="cellrowborder" valign="top" width="31.983198319831978%" headers="mcps1.3.5.5.2.4.1.2 "><p id="EN-US_TOPIC_0000001188482286__af025aedc08a24da1bf6c4a3e04371de5">Memory allocation error</p>
</td>
<td class="cellrowborder" valign="top" width="47.66476647664767%" headers="mcps1.3.5.5.2.4.1.3 "><p id="EN-US_TOPIC_0000001188482286__a00f5b623dbfb4b219dbca1e728244d0d">The driver is unable to allocate memory required to support execution or completion of the function.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__rd1e61df0ecd64a6db24bb2554a3e83af"><td class="cellrowborder" valign="top" width="20.352035203520348%" headers="mcps1.3.5.5.2.4.1.1 "><p id="EN-US_TOPIC_0000001188482286__acdb2c00dd03944e8b02fd5b962295f93">HY008</p>
</td>
<td class="cellrowborder" valign="top" width="31.983198319831978%" headers="mcps1.3.5.5.2.4.1.2 "><p id="EN-US_TOPIC_0000001188482286__aaaba5551e3544f09a35038d4b5356dd0">Operation canceled</p>
</td>
<td class="cellrowborder" valign="top" width="47.66476647664767%" headers="mcps1.3.5.5.2.4.1.3 "><p id="EN-US_TOPIC_0000001188482286__ad029067d1bca40319a847acbebd689de">SQLCancel is called to terminate the statement execution, but the StatementHandle function is still called.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__rb359678926de4b1584b8e77405a8b5c2"><td class="cellrowborder" valign="top" width="20.352035203520348%" headers="mcps1.3.5.5.2.4.1.1 "><p id="EN-US_TOPIC_0000001188482286__a3ed5b3b6009f492faf178975753857e8">HY010</p>
</td>
<td class="cellrowborder" valign="top" width="31.983198319831978%" headers="mcps1.3.5.5.2.4.1.2 "><p id="EN-US_TOPIC_0000001188482286__a20260ad9c6b34415a57a222fbf870e18">Function sequence error</p>
</td>
<td class="cellrowborder" valign="top" width="47.66476647664767%" headers="mcps1.3.5.5.2.4.1.3 "><p id="EN-US_TOPIC_0000001188482286__a7aaf255096a04e6387811bff805e44fe">The function is called prior to sending data to data parameters or columns being executed.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r023b06d0fa6149408d79c201382cdefe"><td class="cellrowborder" valign="top" width="20.352035203520348%" headers="mcps1.3.5.5.2.4.1.1 "><p id="EN-US_TOPIC_0000001188482286__a64308dc66e1542ffb929cf109d7f9e16">HY013</p>
</td>
<td class="cellrowborder" valign="top" width="31.983198319831978%" headers="mcps1.3.5.5.2.4.1.2 "><p id="EN-US_TOPIC_0000001188482286__abfd47c44f357467d8904414134a26c7f">Memory management error</p>
</td>
<td class="cellrowborder" valign="top" width="47.66476647664767%" headers="mcps1.3.5.5.2.4.1.3 "><p id="EN-US_TOPIC_0000001188482286__aaa6155b310ef41e3932e07d8cd61fb5c">The function fails to be called. The error may be caused by low memory conditions.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r679f7175aeb449feb9e681b561024dcb"><td class="cellrowborder" valign="top" width="20.352035203520348%" headers="mcps1.3.5.5.2.4.1.1 "><p id="EN-US_TOPIC_0000001188482286__a27b96b7263434797b64314ce590e388d">HYT01</p>
</td>
<td class="cellrowborder" valign="top" width="31.983198319831978%" headers="mcps1.3.5.5.2.4.1.2 "><p id="EN-US_TOPIC_0000001188482286__af541a04c6411418fab56b5a2efcd92bc">Connection timed out</p>
</td>
<td class="cellrowborder" valign="top" width="47.66476647664767%" headers="mcps1.3.5.5.2.4.1.3 "><p id="EN-US_TOPIC_0000001188482286__af39799c45d8e4ccfa944dc2e956aa110">The timeout period expired before the application was able to connect to the data source.</p>
</td>
</tr>
<tr id="EN-US_TOPIC_0000001188482286__r1a1804f701ca4abfb7d14fd824b0302e"><td class="cellrowborder" valign="top" width="20.352035203520348%" headers="mcps1.3.5.5.2.4.1.1 "><p id="EN-US_TOPIC_0000001188482286__a5ac2b67803e84f71915c29e19888b4f7">IM001</p>
</td>
<td class="cellrowborder" valign="top" width="31.983198319831978%" headers="mcps1.3.5.5.2.4.1.2 "><p id="EN-US_TOPIC_0000001188482286__aefda36102b144a9788dc928e03d30960">Function not supported by the driver</p>
</td>
<td class="cellrowborder" valign="top" width="47.66476647664767%" headers="mcps1.3.5.5.2.4.1.3 "><p id="EN-US_TOPIC_0000001188482286__ac56f1cdfca6041f9aa00b6133ba1d37c">The called function is not supported by the StatementHandle driver.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="EN-US_TOPIC_0000001188482286__s5a36fefef22a49029271148bec999048"><h4 class="sectiontitle">Examples</h4><p id="EN-US_TOPIC_0000001188482286__a0b01cf21db8d4a4181c4dc0bacd77f9d">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>
View Git Blame Copy Permalink