177 lines
11 KiB
HTML
177 lines
11 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="SQLExtendedFetch - Fetch array of rows" />
|
|
<meta name="DC.subject" content="SQLExtendedFetch, function, description, Extended Fetch, function" />
|
|
<meta name="keywords" content="SQLExtendedFetch, function, description, Extended Fetch, function" />
|
|
<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="rzadpfnexfet" />
|
|
<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>SQLExtendedFetch</title>
|
|
</head>
|
|
<body id="rzadpfnexfet"><a name="rzadpfnexfet"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">SQLExtendedFetch - Fetch array of rows</h1>
|
|
<div><div class="section"><h4 class="sectiontitle">Purpose</h4><p><samp class="codeph">SQLExtendedFetch()</samp> extends
|
|
the function of <samp class="codeph">SQLFetch()</samp> by returning a block of data containing
|
|
multiple rows (called a <span class="synph"><span class="var">rowset</span></span>), in the form of
|
|
an array, for each bound column. The size of the rowset is determined by the
|
|
SQL_ROWSET_SIZE attribute on an <samp class="codeph">SQLSetStmtAttr()</samp> call.</p>
|
|
<p>To
|
|
fetch one row of data at a time, an application should call <samp class="codeph">SQLFetch()</samp>.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Syntax</h4><pre>SQLRETURN SQLExtendedFetch (SQLHSTMT StatementHandle,
|
|
SQLSMALLINT FetchOrientation,
|
|
SQLINTEGER FetchOffset,
|
|
SQLINTEGER *RowCountPtr,
|
|
SQLSMALLINT *RowStatusArray);</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. SQLExtendedFetch arguments</caption><thead align="left"><tr><th align="left" valign="bottom" width="17.59259259259259%" id="d0e62">Data type</th>
|
|
<th align="left" valign="bottom" width="23.51851851851852%" id="d0e64">Argument </th>
|
|
<th align="left" valign="bottom" width="11.851851851851853%" id="d0e66">Use </th>
|
|
<th align="left" valign="bottom" width="47.03703703703704%" id="d0e68">Description </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e62 ">SQLHSTMT </td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e64 "><em>StatementHandle</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e66 ">Input </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e68 ">Statement handle.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e62 ">SQLINTEGER *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e64 "><em>RowCountPtr</em></td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e66 ">Output </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e68 ">Number of the rows actually fetched. If an
|
|
error occurs during processing, <span class="synph"><span class="var">RowCountPtr</span></span> points
|
|
to the ordinal position of the row (in the rowset) that precedes the row where
|
|
the error occurred. If an error occurs retrieving the first row <span class="synph"><span class="var">RowCountPtr</span></span> points
|
|
to the value 0.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e62 ">SQLINTEGER</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e64 "><em>FetchOffset</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e66 ">Input </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e68 ">Row offset for relative positioning.</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e62 ">SQLSMALLINT *</td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e64 "><em>RowStatusArray</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e66 ">Output </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e68 ">An array of status values. The number of
|
|
elements must equal the number of rows in the rowset (as defined by the SQL_ROWSET_SIZE
|
|
attribute). A status value for each row fetched is returned: <ul><li>SQL_ROW_SUCCESS</li>
|
|
</ul>
|
|
<p>If the number of rows fetched is less than the number of elements
|
|
in the status array (that is, less than the rowset size), the remaining status
|
|
elements are set to SQL_ROW_NOROW.</p>
|
|
<div class="p">DB2<sup>®</sup> UDB CLI cannot detect whether a row
|
|
has been updated or deleted since the start of the fetch. Therefore, the following
|
|
ODBC defined status values are not reported: <ul><li>SQL_ROW_DELETED</li>
|
|
<li>SQL_ROW_UPDATED</li>
|
|
</ul>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="17.59259259259259%" headers="d0e62 ">SQLSMALLINT </td>
|
|
<td align="left" valign="top" width="23.51851851851852%" headers="d0e64 "><em>FetchOrientation</em> </td>
|
|
<td align="left" valign="top" width="11.851851851851853%" headers="d0e66 ">Input </td>
|
|
<td align="left" valign="top" width="47.03703703703704%" headers="d0e68 ">Fetch orientation. See <a href="rzadpfetchsc.htm#rzadpfetchsc__tfetch">Table 2</a> for
|
|
possible values.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Usage</h4><p><samp class="codeph">SQLExtendedFetch()</samp> is used
|
|
to perform an array fetch of a set of rows. An application specifies the size
|
|
of the array by calling <samp class="codeph">SQLSetStmtAttr()</samp> with the SQL_ROWSET_SIZE
|
|
attribute.</p>
|
|
<p>Before <samp class="codeph">SQLExtendedFetch()</samp> is called the
|
|
first time, the cursor is positioned before the first row. After <samp class="codeph">SQLExtendedFetch()</samp> is
|
|
called, the cursor is positioned on the row in the result set corresponding
|
|
to the last row element in the rowset just retrieved.</p>
|
|
<p>For any columns
|
|
in the result set that have been bound by the <samp class="codeph">SQLBindCol()</samp> function, DB2 UDB
|
|
CLI converts the data for the bound columns as necessary and stores it in
|
|
the locations bound to these columns. The result set must be bound in a row-wise
|
|
fashion. This means that the values for all the columns of the first row are
|
|
contiguous, followed by the values of the second row, and so on. Also, if
|
|
indicator variables are used, they are all returned in one contiguous storage
|
|
location.</p>
|
|
<p>When using this procedure to retrieve multiple rows, all columns
|
|
must be bound, and the storage must be contiguous. When using this function
|
|
to retrieve rows from an SQL procedure result set, only the SQL_FETCH_NEXT
|
|
orientation is supported. The user is responsible for allocating enough storage
|
|
for the number of rows that are specified in SQL_ROWSET_SIZE.</p>
|
|
<p>The cursor
|
|
must be a scrollable cursor for <samp class="codeph">SQLExtendedFetch()</samp> to use
|
|
any orientation other than SQL_FETCH_NEXT. See <a href="rzadpfnsstma.htm#rzadpfnsstma">SQLSetStmtAttr - Set a statement attribute</a> for
|
|
information about setting the SQL_ATTR_CURSOR_SCROLLABLE attribute.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Return codes</h4><div class="p"> <ul><li>SQL_SUCCESS</li>
|
|
<li>SQL_SUCCESS_WITH_INFO</li>
|
|
<li>SQL_ERROR</li>
|
|
<li>SQL_INVALID_HANDLE</li>
|
|
<li>SQL_NO_DATA_FOUND</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Error conditions</h4>
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="hsides" border="1" rules="rows"><caption>Table 2. SQLExtendedFetch SQLSTATEs</caption><thead align="left"><tr><th align="left" valign="bottom" width="12.962962962962962%" id="d0e221">SQLSTATE </th>
|
|
<th align="left" valign="bottom" width="29.074074074074076%" id="d0e223">Description </th>
|
|
<th align="left" valign="bottom" width="57.96296296296296%" id="d0e225">Explanation </th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e221 "><strong>HY</strong>009 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e223 ">Argument value that is not valid</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e225 "> <p>The argument value <em>RowCountPtr</em> or <em>RowStatusArray</em> is
|
|
a null pointer.</p>
|
|
<p>The value specified for the argument FetchOrientation
|
|
is not recognized.</p>
|
|
</td>
|
|
</tr>
|
|
<tr><td align="left" valign="top" width="12.962962962962962%" headers="d0e221 "><strong>HY</strong>010 </td>
|
|
<td align="left" valign="top" width="29.074074074074076%" headers="d0e223 ">Function sequence error</td>
|
|
<td align="left" valign="top" width="57.96296296296296%" headers="d0e225 "><samp class="codeph">SQLExtendedFetch()</samp> is called
|
|
for an StatementHandle after <samp class="codeph">SQLFetch()</samp> is called and before <samp class="codeph">SQLFreeStmt()</samp> has
|
|
been called with the SQL_CLOSE option. <p>The function is called before calling <samp class="codeph">SQLPrepare()</samp> or <samp class="codeph">SQLExecDirect()</samp> for the <span class="synph"><span class="var">StatementHandle</span></span>.</p>
|
|
<p>The function is
|
|
called while in a data-at-processing (<samp class="codeph">SQLParamData()</samp>, <samp class="codeph">SQLPutData()</samp>)
|
|
operation.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Restrictions</h4><p>None.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">References</h4><div class="p"> <ul><li><a href="rzadpfnbindc.htm#rzadpfnbindc">SQLBindCol - Bind a column to an application variable</a></li>
|
|
<li><a href="rzadpfnexec.htm#rzadpfnexec">SQLExecute - Execute a statement</a></li>
|
|
<li><a href="rzadpfnexecd.htm#rzadpfnexecd">SQLExecDirect - Execute a statement directly</a></li>
|
|
<li><a href="rzadpfnfetch.htm#rzadpfnfetch">SQLFetch - Fetch next row</a></li>
|
|
</ul>
|
|
</div>
|
|
</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> |