213 lines
14 KiB
HTML
213 lines
14 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="SQLGetDiagField - Return diagnostic information (extensible)" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzadphdapi.htm" />
|
||
|
|
<meta name="DC.Relation" scheme="URI" content="rzadphddiag.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="rzadpfndfld" />
|
||
|
|
<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>SQLGetDiagField</title>
|
||
|
|
</head>
|
||
|
|
<body id="rzadpfndfld"><a name="rzadpfndfld"><!-- --></a>
|
||
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
||
|
|
<h1 class="topictitle1">SQLGetDiagField - Return diagnostic information (extensible)</h1>
|
||
|
|
<div><div class="section"></div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Purpose</h4> <p><samp class="codeph">SQLGetDiagField()</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, an error code, and a text
|
||
|
|
message. </p>
|
||
|
|
<p>Call <samp class="codeph">SQLGetDiagField()</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 SQLGetDiagField (SQLSMALLINT htype,
|
||
|
|
SQLINTEGER handle,
|
||
|
|
SQLSMALLINT recNum,
|
||
|
|
SQLSMALLINT diagId,
|
||
|
|
SQLPOINTER diagInfo,
|
||
|
|
SQLSMALLINT bLen,
|
||
|
|
SQLSMALLINT *sLen);</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. SQLDiagField arguments</caption><thead align="left"><tr><th align="left" valign="top" width="23.703703703703706%" id="d0e63">Data type</th>
|
||
|
|
<th align="left" valign="top" width="20.37037037037037%" id="d0e65">Argument</th>
|
||
|
|
<th align="left" valign="top" width="15.74074074074074%" id="d0e67">Use</th>
|
||
|
|
<th align="left" valign="top" width="40.18518518518518%" id="d0e69">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="23.703703703703706%" headers="d0e63 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20.37037037037037%" headers="d0e65 "><em>hType</em></td>
|
||
|
|
<td align="left" valign="top" width="15.74074074074074%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.18518518518518%" headers="d0e69 ">Handle type.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="23.703703703703706%" headers="d0e63 ">SQLINTEGER</td>
|
||
|
|
<td align="left" valign="top" width="20.37037037037037%" headers="d0e65 "><em>handle</em></td>
|
||
|
|
<td align="left" valign="top" width="15.74074074074074%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.18518518518518%" headers="d0e69 ">Handle for which the diagnostic information
|
||
|
|
is wanted.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="23.703703703703706%" headers="d0e63 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20.37037037037037%" headers="d0e65 "><em>recNum</em></td>
|
||
|
|
<td align="left" valign="top" width="15.74074074074074%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.18518518518518%" 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>
|
||
|
|
<tr><td align="left" valign="top" width="23.703703703703706%" headers="d0e63 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20.37037037037037%" headers="d0e65 "><em>diagId</em></td>
|
||
|
|
<td align="left" valign="top" width="15.74074074074074%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.18518518518518%" headers="d0e69 ">See <a href="#rzadpfndfld__fewt1">Table 2</a>.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="23.703703703703706%" headers="d0e63 ">SQLPOINTER</td>
|
||
|
|
<td align="left" valign="top" width="20.37037037037037%" headers="d0e65 "><em>diagInfo</em></td>
|
||
|
|
<td align="left" valign="top" width="15.74074074074074%" headers="d0e67 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40.18518518518518%" headers="d0e69 ">Buffer for diagnostic information.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="23.703703703703706%" headers="d0e63 ">SQLSMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="20.37037037037037%" headers="d0e65 "><em>bLen</em></td>
|
||
|
|
<td align="left" valign="top" width="15.74074074074074%" headers="d0e67 ">Input</td>
|
||
|
|
<td align="left" valign="top" width="40.18518518518518%" headers="d0e69 ">Length of <em>diagInfo</em>, if requested data
|
||
|
|
is a character string; otherwise, unused.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="23.703703703703706%" headers="d0e63 ">SQLSMALLINT *</td>
|
||
|
|
<td align="left" valign="top" width="20.37037037037037%" headers="d0e65 "><em>sLen</em></td>
|
||
|
|
<td align="left" valign="top" width="15.74074074074074%" headers="d0e67 ">Output</td>
|
||
|
|
<td align="left" valign="top" width="40.18518518518518%" headers="d0e69 ">Length of complete diagnostic information,
|
||
|
|
If the requested data is a character string; otherwise, unused.</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="tablenoborder"><a name="rzadpfndfld__fewt1"><!-- --></a><table cellpadding="4" cellspacing="0" summary="" id="rzadpfndfld__fewt1" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. DiagId types</caption><thead align="left"><tr><th align="left" valign="top" width="45.2513966480447%" id="d0e157">Descriptor</th>
|
||
|
|
<th align="left" valign="top" width="20.11173184357542%" id="d0e159">Type</th>
|
||
|
|
<th align="left" valign="top" width="34.63687150837989%" id="d0e161">Description</th>
|
||
|
|
</tr>
|
||
|
|
</thead>
|
||
|
|
<tbody><tr><td align="left" valign="top" width="45.2513966480447%" headers="d0e157 ">SQL_DIAG_MESSAGE_TEXT</td>
|
||
|
|
<td align="left" valign="top" width="20.11173184357542%" headers="d0e159 ">CHAR(254)</td>
|
||
|
|
<td align="left" valign="top" width="34.63687150837989%" headers="d0e161 ">The implementation-defined message text relating
|
||
|
|
to the diagnostic record.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="45.2513966480447%" headers="d0e157 ">SQL_DIAG_NATIVE</td>
|
||
|
|
<td align="left" valign="top" width="20.11173184357542%" headers="d0e159 ">INTEGER</td>
|
||
|
|
<td align="left" valign="top" width="34.63687150837989%" headers="d0e161 ">The implementation-defined error code relating
|
||
|
|
to the diagnostic record. Portable applications should not base their behavior
|
||
|
|
on this value.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="45.2513966480447%" headers="d0e157 ">SQL_DIAG_NUMBER</td>
|
||
|
|
<td align="left" valign="top" width="20.11173184357542%" headers="d0e159 ">INTEGER</td>
|
||
|
|
<td align="left" valign="top" width="34.63687150837989%" headers="d0e161 ">The number of diagnostic records available
|
||
|
|
for the specified handle.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="45.2513966480447%" headers="d0e157 ">SQL_DIAG_RETURNCODE</td>
|
||
|
|
<td align="left" valign="top" width="20.11173184357542%" headers="d0e159 ">SMALLINT</td>
|
||
|
|
<td align="left" valign="top" width="34.63687150837989%" headers="d0e161 ">Return code of the underlying function. Can
|
||
|
|
be SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, or SQL_ERROR.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="45.2513966480447%" headers="d0e157 ">SQL_DIAG_ROW_COUNT</td>
|
||
|
|
<td align="left" valign="top" width="20.11173184357542%" headers="d0e159 ">INTEGER</td>
|
||
|
|
<td align="left" valign="top" width="34.63687150837989%" headers="d0e161 ">The number of rows for the specified handle,
|
||
|
|
if the handle is a statement handle.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="45.2513966480447%" headers="d0e157 ">SQL_DIAG_SERVER_NAME</td>
|
||
|
|
<td align="left" valign="top" width="20.11173184357542%" headers="d0e159 ">CHAR(128)</td>
|
||
|
|
<td align="left" valign="top" width="34.63687150837989%" headers="d0e161 ">The server name that the diagnostic record
|
||
|
|
relates to, as it is supplied on the <samp class="codeph">SQLConnect()</samp> statement
|
||
|
|
that establishes the connection.</td>
|
||
|
|
</tr>
|
||
|
|
<tr><td align="left" valign="top" width="45.2513966480447%" headers="d0e157 ">SQL_DIAG_SQLSTATE</td>
|
||
|
|
<td align="left" valign="top" width="20.11173184357542%" headers="d0e159 ">CHAR(5)</td>
|
||
|
|
<td align="left" valign="top" width="34.63687150837989%" headers="d0e161 ">The 5-character SQLSTATE code relating to
|
||
|
|
the diagnostic record. The SQLSTATE code provides a portable diagnostic indication.</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 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">SQLGetDiagField()</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">SQLGetDiagField()</samp>. For each message retrieved, <samp class="codeph">SQLGetDiagField()</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.</p>
|
||
|
|
<p>Diagnostic
|
||
|
|
information stored under a given handle is cleared when a call is made to <samp class="codeph">SQLGetDiagField()</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">SQLGetDiagField()</samp> with
|
||
|
|
an associated but different handle type. For example, a call to <samp class="codeph">SQLGetDiagField()</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>szDiagFieldMsg</em>) is too short. This is because
|
||
|
|
the application is not able to retrieve the same error message by calling <samp class="codeph">SQLGetDiagField()</samp> again.
|
||
|
|
The actual length of the message text is returned in the <em>pcbDiagFieldMsg</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 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">SQLGetDiagField()</samp>.</p>
|
||
|
|
<p>SQL_ERROR is returned if
|
||
|
|
the argument <em>diagInfo</em> or <em>sLen</em> is a null pointer. </p>
|
||
|
|
</div>
|
||
|
|
<div class="section"><h4 class="sectiontitle">Diagnostics</h4><p>SQLSTATEs are not defined, because <samp class="codeph">SQLGetDiagField()</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<sup>®</sup> 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>
|
||
|
|
<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 class="relconcepts"><strong>Related concepts</strong><br />
|
||
|
|
<div><a href="rzadphddiag.htm" title="This topic deals with warning or error conditions generated within an application.">Diagnostics in a DB2 UDB CLI application</a></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|