Home Explore Blog CI



postgresql

75th chunk of `doc/src/sgml/libpq.sgml`
c8d44d916821800c06a013c2e403338f5508c1808539f6d20000000100000fbf
       waiting for completion.
<synopsis>
int PQsendClosePrepared(PGconn *conn, const char *stmtName);
</synopsis>

       This is an asynchronous version of <xref linkend="libpq-PQclosePrepared"/>:
       it returns 1 if it was able to dispatch the request, and 0 if not.
       After a successful call, call <xref linkend="libpq-PQgetResult"/> to
       obtain the results.  The function's parameters are handled
       identically to <xref linkend="libpq-PQclosePrepared"/>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQsendClosePortal">
     <term><function>PQsendClosePortal</function><indexterm><primary>PQsendClosePortal</primary></indexterm></term>

     <listitem>
      <para>
       Submits a request to close specified portal, without waiting for
       completion.
<synopsis>
int PQsendClosePortal(PGconn *conn, const char *portalName);
</synopsis>

       This is an asynchronous version of <xref linkend="libpq-PQclosePortal"/>:
       it returns 1 if it was able to dispatch the request, and 0 if not.
       After a successful call, call <xref linkend="libpq-PQgetResult"/> to
       obtain the results.  The function's parameters are handled
       identically to <xref linkend="libpq-PQclosePortal"/>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQgetResult">
     <term><function>PQgetResult</function><indexterm><primary>PQgetResult</primary></indexterm></term>

     <listitem>
      <para>
       Waits for the next result from a prior
       <xref linkend="libpq-PQsendQuery"/>,
       <xref linkend="libpq-PQsendQueryParams"/>,
       <xref linkend="libpq-PQsendPrepare"/>,
       <xref linkend="libpq-PQsendQueryPrepared"/>,
       <xref linkend="libpq-PQsendDescribePrepared"/>,
       <xref linkend="libpq-PQsendDescribePortal"/>,
       <xref linkend="libpq-PQsendClosePrepared"/>,
       <xref linkend="libpq-PQsendClosePortal"/>,
       <xref linkend="libpq-PQsendPipelineSync"/>, or
       <xref linkend="libpq-PQpipelineSync"/>
       call, and returns it.
       A null pointer is returned when the command is complete and there
       will be no more results.
<synopsis>
PGresult *PQgetResult(PGconn *conn);
</synopsis>
      </para>

      <para>
       <xref linkend="libpq-PQgetResult"/> must be called repeatedly until
       it returns a null pointer, indicating that the command is done.
       (If called when no command is active,
       <xref linkend="libpq-PQgetResult"/> will just return a null pointer
       at once.) Each non-null result from
       <xref linkend="libpq-PQgetResult"/> should be processed using the
       same <structname>PGresult</structname> accessor functions previously
       described.  Don't forget to free each result object with
       <xref linkend="libpq-PQclear"/> when done with it.  Note that
       <xref linkend="libpq-PQgetResult"/> will block only if a command is
       active and the necessary response data has not yet been read by
       <xref linkend="libpq-PQconsumeInput"/>.
      </para>

      <para>
       In pipeline mode, <function>PQgetResult</function> will return normally
       unless an error occurs; for any subsequent query sent after the one
       that caused the error until (and excluding) the next synchronization point,
       a special result of type <literal>PGRES_PIPELINE_ABORTED</literal> will
       be returned, and a null pointer will be returned after it.
       When the pipeline synchronization point is reached, a result of type
       <literal>PGRES_PIPELINE_SYNC</literal> will be returned.
       The result of the next query after the synchronization point follows
       immediately (that is, no null pointer is returned after
       the synchronization point).
      </para>

      <note>
       <para>
        Even when <xref linkend="libpq-PQresultStatus"/> indicates a fatal
        error, <xref linkend="libpq-PQgetResult"/> should be called until it
        returns a null pointer, to allow <application>libpq</application>

Title: PQgetResult: Retrieving Asynchronous Results
Summary
`PQgetResult` waits for and returns the next result from prior asynchronous calls like `PQsendQuery`, `PQsendQueryParams`, `PQsendPrepare`, `PQsendQueryPrepared`, `PQsendDescribePrepared`, `PQsendDescribePortal`, `PQsendClosePrepared`, `PQsendClosePortal`, `PQsendPipelineSync`, or `PQpipelineSync`. It returns a null pointer when the command is complete. The function must be called repeatedly until a null pointer is returned, and each non-null result should be processed and then freed using `PQclear`. In pipeline mode, special results like `PGRES_PIPELINE_ABORTED` and `PGRES_PIPELINE_SYNC` are returned to indicate errors and synchronization points, respectively.