<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Retrieving Query Results Row-By-Row</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.3.9 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="libpq - C Library"
HREF="libpq.html"><LINK
REL="PREVIOUS"
TITLE="Asynchronous Command Processing"
HREF="libpq-async.html"><LINK
REL="NEXT"
TITLE="Canceling Queries in Progress"
HREF="libpq-cancel.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2015-06-13T20:07:22"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.3.9 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Asynchronous Command Processing"
HREF="libpq-async.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 31. <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> - C Library</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Canceling Queries in Progress"
HREF="libpq-cancel.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="LIBPQ-SINGLE-ROW-MODE"
>31.5. Retrieving Query Results Row-By-Row</A
></H1
><P
> Ordinarily, <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> collects a SQL command's
entire result and returns it to the application as a single
<TT
CLASS="STRUCTNAME"
>PGresult</TT
>. 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
<I
CLASS="FIRSTTERM"
>single-row mode</I
>. 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
HREF="libpq-async.html"
>Section 31.4</A
>. If the query returns any rows, they are returned
as individual <TT
CLASS="STRUCTNAME"
>PGresult</TT
> objects, which look like
normal query results except for having status code
<TT
CLASS="LITERAL"
>PGRES_SINGLE_TUPLE</TT
> instead of
<TT
CLASS="LITERAL"
>PGRES_TUPLES_OK</TT
>. After the last row, or immediately if
the query returns zero rows, a zero-row object with status
<TT
CLASS="LITERAL"
>PGRES_TUPLES_OK</TT
> 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 <TT
CLASS="STRUCTNAME"
>PGresult</TT
> objects will contain the same row
description data (column names, types, etc) that an ordinary
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> object for the query would have.
Each object should be freed with <CODE
CLASS="FUNCTION"
>PQclear</CODE
> as usual.
</P
><P
> <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><A
NAME="LIBPQ-PQSETSINGLEROWMODE"
></A
><CODE
CLASS="FUNCTION"
>PQsetSingleRowMode</CODE
>
</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"
><P
></P
><TABLE
CLASS="CAUTION"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Caution</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><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
<TT
CLASS="LITERAL"
>PGRES_SINGLE_TUPLE</TT
> <TT
CLASS="STRUCTNAME"
>PGresult</TT
>
objects followed by a <TT
CLASS="LITERAL"
>PGRES_FATAL_ERROR</TT
> 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
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpq-async.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpq-cancel.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Asynchronous Command Processing</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="libpq.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Canceling Queries in Progress</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
