190 lines
12 KiB
HTML
190 lines
12 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="SQLGetDiagRec - Return diagnostic information (concise)" />
|
||
|
|
<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="rzadpfndrec" />
|
||
|
|
<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>SQLGetDiagRec</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzadpfndrec"><a name="rzadpfndrec"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">SQLGetDiagRec - Return diagnostic information (concise)</h1>
|
||
|
|
<div><div class="section"></div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLGetDiagRec()</samp> returns
|
||
|
|
the diagnostic information associated with the most recently called DB2<sup>®</sup> UDB CLI function
|
||
|
|
for a particular statement, connection, or environment handle.</p>
|
||
|
|
<p>The information
|
||
|
|
consists of a standardized SQLSTATE, the error code, and a text message. Refer
|
||
|
|
to <a href="rzadphddiag.htm#rzadphddiag">Diagnostics in a DB2 UDB CLI application</a> for more information.</p>
|
||
|
|
<p>Call <samp class="codeph">SQLGetDiagRec()</samp> after
|
||
|
|
receiving a return code of SQL_ERROR or SQL_SUCCESS_WITH_INFO from another
|
||
|
|
function call.</p>
|
||
|
|
<div class="note"><span class="notetitle">Note:</span> Some database servers might provide product-specific
|
||
|
|
diagnostic information after returning SQL_NO_DATA_FOUND from the processing
|
||
|
|
of a statement.</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLGetDiagRec (SQLSMALLINT hType,
|
||
|
|
SQLINTEGER handle,
|
||
|
|
SQLSMALLINT recNum,
|
||
|
|
SQLCHAR *szSqlState,
|
||
|
|
SQLINTEGER *pfNativeError,
|
||
|
|
SQLCHAR *szErrorMsg,
|
||
|
|
SQLSMALLINT cbErrorMsgMax,
|
||
|
|
SQLSMALLINT *pcbErrorMsg);</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. SQLGetDiagRec arguments</caption><thead align="left"><tr><th align="left" valign="top" width="22.118959107806692%" id="d0e63">Data type</th>
|
||
|
|
<th align="left" valign="top" width="20.44609665427509%" id="d0e65">Argument</th>
|
||
|
|
<th align="left" valign="top" width="17.100371747211895%" id="d0e67">Use</th>
|
||
|
|
<th align="left" valign="top" width="40.33457249070632%" id="d0e69">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLCHAR *</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>szErrorMsg</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 ">Pointer to buffer to contain the implementation
|
||
|
|
defined message text. In DB2 UDB CLI, only the DBMS generated messages are returned; DB2 UDB
|
||
|
|
CLI itself does not return any message text describing the problem.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLCHAR *</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>szSqlState</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 ">SQLSTATE as a string of 5 characters terminated
|
||
|
|
by a null character. The first 2 characters indicate error class; the next
|
||
|
|
3 indicate subclass. The values correspond directly to SQLSTATE values defined
|
||
|
|
in the X/Open SQL CAE specification and the ODBC specification, augmented
|
||
|
|
with IBM<sup>®</sup> specific
|
||
|
|
and product specific SQLSTATE values.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLINTEGER *</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>pfNativeError</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 "><p>Error code. In DB2 UDB CLI, the <em>pfNativeError</em> argument
|
||
|
|
contains the SQLCODE value returned by the Database Management System (DBMS).
|
||
|
|
If the error is generated by DB2 UDB CLI and not the DBMS, then this field is set
|
||
|
|
to -99999.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLINTEGER</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>handle</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 ">Handle for which the diagnostic information
|
||
|
|
is wanted.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLSMALLINT *</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>pcbErrorMsg</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 ">Pointer to total number of bytes available
|
||
|
|
to return to the <em>szErrorMsg</em> buffer. This does not include the null
|
||
|
|
termination character.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>cbErrorMsgMax</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 ">Maximum (that is, the allocated) length of
|
||
|
|
the buffer <em>szErrorMsg</em>. The recommended length to allocate is SQL_MAX_MESSAGE_LENGTH
|
||
|
|
+ 1.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>hType</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 ">Handle type.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="22.118959107806692%" headers="d0e63 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20.44609665427509%" headers="d0e65 "><em>recNum</em></td>
|
||
|
|
<td align="left" valign="top" width="17.100371747211895%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.33457249070632%" headers="d0e69 ">If there are multiple errors, this indicates
|
||
|
|
which one should be retrieved. If header information is requested, this must
|
||
|
|
be 0. The first error record is number 1.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p>The SQLSTATEs are those defined by the X/OPEN
|
||
|
|
SQL CAE and the X/Open SQL CLI snapshot, augmented with IBM specific and
|
||
|
|
product specific SQLSTATE values.</p>
|
||
|
|
<p>If diagnostic information generated
|
||
|
|
by one DB2 UDB
|
||
|
|
CLI function is not retrieved before a function other than <samp class="codeph">SQLGetDiagRec()</samp> is
|
||
|
|
called with the same handle, the information for the previous function call
|
||
|
|
is lost. This is true whether diagnostic information is generated for the
|
||
|
|
second DB2 UDB
|
||
|
|
CLI function call.</p>
|
||
|
|
<p>Multiple diagnostic messages might be available after
|
||
|
|
a given DB2 UDB
|
||
|
|
CLI function call. These messages can be retrieved one at a time by repeatedly
|
||
|
|
calling <samp class="codeph">SQLGetDiagRec()</samp>. For each message retrieved, <samp class="codeph">SQLGetDiagRec()</samp> returns
|
||
|
|
SQL_SUCCESS and removes it from the list of messages available. When there
|
||
|
|
are no more messages to retrieve, SQL_NO_DATA_FOUND is returned, the SQLSTATE
|
||
|
|
is set to "00000", <em>pfNativeError</em> is set to 0, and <em>pcbErrorMsg</em> and <em>szErrorMsg</em> are
|
||
|
|
undefined.</p>
|
||
|
|
<p>Diagnostic information stored under a given handle is cleared
|
||
|
|
when a call is made to <samp class="codeph">SQLGetDiagRec()</samp> with that handle,
|
||
|
|
or when another DB2 UDB
|
||
|
|
CLI function call is made with that handle. However, information associated
|
||
|
|
with a given handle type is not cleared by a call to <samp class="codeph">SQLGetDiagRec()</samp>
|
||
|
|
with an associated but different handle type. For example, a call to <samp class="codeph">SQLGetDiagRec()</samp> with
|
||
|
|
a connection handle input does not clear errors associated with any statement
|
||
|
|
handles under that connection.</p>
|
||
|
|
<p>SQL_SUCCESS is returned even if the buffer
|
||
|
|
for the error message (<em>szErrorMsg</em>) is too short, because the application
|
||
|
|
is not able to retrieve the same error message by calling <samp class="codeph">SQLGetDiagRec()</samp> again.
|
||
|
|
The actual length of the message text is returned in the <em>pcbErrorMsg</em>.</p>
|
||
|
|
<p>To
|
||
|
|
avoid truncation of the error message, declare a buffer length of SQL_MAX_MESSAGE_LENGTH
|
||
|
|
+ 1. The message text is never be longer than this.</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>
|
||
|
|
<li>SQL_NO_DATA_FOUND</li>
|
||
|
|
</ul>
|
||
|
|
<p>SQL_NO_DATA_FOUND is returned if no diagnostic information is available
|
||
|
|
for the input handle, or if all of the messages have been retrieved through
|
||
|
|
calls to <samp class="codeph">SQLGetDiagRec()</samp>.</p>
|
||
|
|
<p>SQL_ERROR is returned if
|
||
|
|
the argument <samp class="codeph">szSqlState</samp>, <samp class="codeph">pfNativeError</samp>, <samp class="codeph">szErrorMsg</samp> ,
|
||
|
|
or <samp class="codeph">pcbErrorMsg</samp> is a null pointer. </p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Diagnostics</h4><p>SQLSTATEs are not defined because <samp class="codeph">SQLGetDiagRec()</samp> does
|
||
|
|
not generate diagnostic information for itself.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p>Although ODBC also returns X/Open SQL
|
||
|
|
CAE SQLSTATEs, only DB2 UDB CLI returns the additional IBM defined SQLSTATEs.
|
||
|
|
The ODBC Driver Manager also returns SQLSTATE values in addition to the standard
|
||
|
|
ones. For more information about ODBC specific SQLSTATEs refer to <cite>Microsoft<sup>®</sup> ODBC
|
||
|
|
Programmer's Reference</cite>.</p>
|
||
|
|
<p>Because of this, you should only build
|
||
|
|
dependencies on the standard SQLSTATEs. This means any branching logic in
|
||
|
|
the application should only rely on the standard SQLSTATEs. The augmented
|
||
|
|
SQLSTATEs are most useful for debugging purposes.</p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">References</h4><ul><li><a href="rzadpfndfld.htm#rzadpfndfld">SQLGetDiagField - Return diagnostic information (extensible)</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>
|