MAINHACK

Viewing / Editing File: libpq-single-row-mode.html

File is not writable. Editing disabled.
<!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.2.24 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="2017-11-06T22:43:11"></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.2.24 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
>
Cancel / Back
[ MAINHACK ]

Viewing / Editing File: libpq-single-row-mode.html

Server Info

System Features

User Info
