|
- <?xml version="1.0" encoding="UTF-8" standalone="no"?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>33.5. Retrieving Query Results Row-by-Row</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="prev" href="libpq-async.html" title="33.4. Asynchronous Command Processing" /><link rel="next" href="libpq-cancel.html" title="33.6. Canceling Queries in Progress" /></head><body><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.5. Retrieving Query Results Row-by-Row</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-async.html" title="33.4. Asynchronous Command Processing">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 33. libpq - C Library">Up</a></td><th width="60%" align="center">Chapter 33. <span xmlns="http://www.w3.org/1999/xhtml" class="application">libpq</span> - C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 12.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-cancel.html" title="33.6. Canceling Queries in Progress">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="LIBPQ-SINGLE-ROW-MODE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.5. Retrieving Query Results Row-by-Row</h2></div></div></div><a id="id-1.7.3.12.2" class="indexterm"></a><p>
- Ordinarily, <span class="application">libpq</span> collects a SQL command's
- entire result and returns it to the application as a single
- <code class="structname">PGresult</code>. This can be unworkable for commands
- that return a large number of rows. For such cases, applications can use
- <code class="function">PQsendQuery</code> and <code class="function">PQgetResult</code> in
- <em class="firstterm">single-row mode</em>. In this mode, the result row(s) are
- returned to the application one at a time, as they are received from the
- server.
- </p><p>
- To enter single-row mode, call <code class="function">PQsetSingleRowMode</code>
- immediately after a successful call of <code class="function">PQsendQuery</code>
- (or a sibling function). This mode selection is effective only for the
- currently executing query. Then call <code class="function">PQgetResult</code>
- repeatedly, until it returns null, as documented in <a class="xref" href="libpq-async.html" title="33.4. Asynchronous Command Processing">Section 33.4</a>. If the query returns any rows, they are returned
- as individual <code class="structname">PGresult</code> objects, which look like
- normal query results except for having status code
- <code class="literal">PGRES_SINGLE_TUPLE</code> instead of
- <code class="literal">PGRES_TUPLES_OK</code>. After the last row, or immediately if
- the query returns zero rows, a zero-row object with status
- <code class="literal">PGRES_TUPLES_OK</code> is returned; this is the signal that no
- more rows will arrive. (But note that it is still necessary to continue
- calling <code class="function">PQgetResult</code> until it returns null.) All of
- these <code class="structname">PGresult</code> objects will contain the same row
- description data (column names, types, etc) that an ordinary
- <code class="structname">PGresult</code> object for the query would have.
- Each object should be freed with <code class="function">PQclear</code> as usual.
- </p><p>
- </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSETSINGLEROWMODE"><span class="term">
- <code class="function">PQsetSingleRowMode</code>
- <a id="id-1.7.3.12.5.1.1.1.2" class="indexterm"></a>
- </span></dt><dd><p>
- Select single-row mode for the currently-executing query.
-
- </p><pre class="synopsis">
- int PQsetSingleRowMode(PGconn *conn);
- </pre><p>
- </p><p>
- This function can only be called immediately after
- <code class="function">PQsendQuery</code> or one of its sibling functions,
- before any other operation on the connection such as
- <code class="function">PQconsumeInput</code> or
- <code class="function">PQgetResult</code>. If called at the correct time,
- the function activates single-row mode for the current query and
- returns 1. Otherwise the mode stays unchanged and the function
- returns 0. In any case, the mode reverts to normal after
- completion of the current query.
- </p></dd></dl></div><p>
- </p><div class="caution"><h3 class="title">Caution</h3><p>
- While processing a query, the server may return some rows and then
- encounter an error, causing the query to be aborted. Ordinarily,
- <span class="application">libpq</span> discards any such rows and reports only the
- error. But in single-row mode, those rows will have already been
- returned to the application. Hence, the application will see some
- <code class="literal">PGRES_SINGLE_TUPLE</code> <code class="structname">PGresult</code>
- objects followed by a <code class="literal">PGRES_FATAL_ERROR</code> object. For
- proper transactional behavior, the application must be designed to
- discard or undo whatever has been done with the previously-processed
- rows, if the query ultimately fails.
- </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-async.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-cancel.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.4. Asynchronous Command Processing </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 33.6. Canceling Queries in Progress</td></tr></table></div></body></html>
|
