<HTML
><HEAD
><TITLE
>Query Execution Functions</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.64
"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="libpq++ - C++ Binding Library"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Database Connection Functions"
HREF="libpqpp-connect.html"><LINK
REL="NEXT"
TITLE="Asynchronous Notification"
HREF="libpqpp-notify.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
NAME="creation"
CONTENT="2002-11-27T04:23:11"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
><SPAN
CLASS="APPLICATION"
>libpq++</SPAN
> - C++ Binding Library</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="libpqpp-connect.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="libpqpp-notify.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="libpqpp-exec"
>1.5. Query Execution Functions</A
></H1
>
<DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="libpqpp-exec-main"
>1.5.1. Main Routines</A
></H2
>
<P
>
<P
></P
></P><UL
><LI
> <P
> <TT
CLASS="FUNCTION"
>Exec</TT
>
sends a command to the backend server. It's probably more desirable to
use one of the next two functions.
</P><PRE
CLASS="SYNOPSIS"
>ExecStatusType PgConnection::Exec(const char* query)</PRE
><P>
Returns the result status of the command. The following status
results can be expected:
<TT
CLASS="SYMBOL"
>PGRES_EMPTY_QUERY</TT
>
<TT
CLASS="SYMBOL"
>PGRES_COMMAND_OK</TT
>, if the command was not a query
<TT
CLASS="SYMBOL"
>PGRES_TUPLES_OK</TT
>, if the query successfully returned tuples
<TT
CLASS="SYMBOL"
>PGRES_COPY_OUT</TT
>
<TT
CLASS="SYMBOL"
>PGRES_COPY_IN</TT
>
<TT
CLASS="SYMBOL"
>PGRES_BAD_RESPONSE</TT
>, if an unexpected response was received
<TT
CLASS="SYMBOL"
>PGRES_NONFATAL_ERROR</TT
>
<TT
CLASS="SYMBOL"
>PGRES_FATAL_ERROR</TT
>
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>ExecCommandOk</TT
> sends a non-query command
(one that does not return rows) to the backend server.
</P><PRE
CLASS="SYNOPSIS"
>int PgConnection::ExecCommandOk(const char *query)</PRE
><P>
Returns true (1) if the command succeeds.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>ExecTuplesOk</TT
>
Sends a query command (one that returns rows) to the backend server.
</P><PRE
CLASS="SYNOPSIS"
>int PgConnection::ExecTuplesOk(const char *query)</PRE
><P>
Returns true (1) if the query succeeds.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>ErrorMessage</TT
>
returns the last error message text.
</P><PRE
CLASS="SYNOPSIS"
>const char *PgConnection::ErrorMessage()</PRE
><P>
</P
>
</LI
></UL
><P>
</P
></DIV
>
<DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="libpqpp-exec-select-info"
>1.5.2. Retrieving SELECT Result Information</A
></H2
>
<P
></P
><UL
><LI
> <P
> <TT
CLASS="FUNCTION"
>Tuples</TT
>
returns the number of tuples (rows) in the query result.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::Tuples() const</PRE
><P>
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>Fields</TT
>
returns the number of fields (rows) in each tuple of the query result.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::Fields()</PRE
><P>
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>FieldName</TT
>
returns the field (column) name associated with the given field index.
Field indices start at 0.
</P><PRE
CLASS="SYNOPSIS"
>const char *PgDatabase::FieldName(int field_num) const</PRE
><P>
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>FieldNum</TT
>
returns the field (column) index associated with
the given field name.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::FieldNum(const char* field_name) const</PRE
><P>
-1 is returned if the given name does not match any field.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>FieldType</TT
>
returns the field type associated with the given field index. The
integer returned is an internal coding of the type. Field indices
start at 0.
</P><PRE
CLASS="SYNOPSIS"
>Oid PgDatabase::FieldType(int field_num) const</PRE
><P>
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>FieldType</TT
>
returns the field type associated with the given field name. The
integer returned is an internal coding of the type. Field indices
start at 0.
</P><PRE
CLASS="SYNOPSIS"
>Oid PgDatabase::FieldType(const char* field_name) const</PRE
><P>
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>FieldSize</TT
>
returns the size in bytes of the field associated with the given
field index. Field indices start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::FieldSize(int field_num) const</PRE
><P>
Returns the space allocated for this field in a database tuple
given the field number. In other words the size of the server's
binary representation of the data type. -1 is returned if the
field is variable size.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>FieldSize</TT
>
returns the size in bytes of the field associated with the given
field index. Field indices start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::FieldSize(const char *field_name) const</PRE
><P>
Returns the space allocated for this field in a database tuple
given the field name. In other words the size of the server's
binary representation of the data type. -1 is returned if the
field is variable size.
</P
>
</LI
></UL
>
</DIV
>
<DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="libpqpp-exec-select-values"
>1.5.3. Retrieving SELECT Result Values</A
></H2
>
<P
></P
><UL
><LI
> <P
> <TT
CLASS="FUNCTION"
>GetValue</TT
> returns a single field (column)
value of one tuple of a <TT
CLASS="STRUCTNAME"
>PGresult</TT
>.
Tuple and field indices start at 0.
</P><PRE
CLASS="SYNOPSIS"
>const char *PgDatabase::GetValue(int tup_num, int field_num) const</PRE
><P>
For most queries, the value returned by
<TT
CLASS="FUNCTION"
>GetValue</TT
> is a null-terminated string
representation of the attribute value. But if
<TT
CLASS="FUNCTION"
>BinaryTuples</TT
> is true, the value returned by
<TT
CLASS="FUNCTION"
>GetValue</TT
> is the binary representation of
the type in the internal format of the backend server (but not
including the size word, if the field is variable-length). It is
then the programmer's responsibility to cast and convert the
data to the correct C type. The pointer returned by
<TT
CLASS="FUNCTION"
>GetValue</TT
> points to storage that is part of
the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> structure. One should not
modify it, and one must explicitly copy the value into other
storage if it is to be used past the lifetime of the
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> structure itself.
<TT
CLASS="FUNCTION"
>BinaryTuples</TT
> is not yet implemented.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>GetValue</TT
> returns a single field (column)
value of one tuple of a <TT
CLASS="STRUCTNAME"
>PGresult</TT
>.
Tuple and field indices start at 0.
</P><PRE
CLASS="SYNOPSIS"
>const char *PgDatabase::GetValue(int tup_num, const char *field_name) const</PRE
><P>
For most queries, the value returned by
<TT
CLASS="FUNCTION"
>GetValue</TT
> is a null-terminated string
representation of the attribute value. But if
<TT
CLASS="FUNCTION"
>BinaryTuples</TT
> is true, the value returned by
<TT
CLASS="FUNCTION"
>GetValue</TT
> is the binary representation of
the type in the internal format of the backend server (but not
including the size word, if the field is variable-length). It is
then the programmer's responsibility to cast and convert the
data to the correct C type. The pointer returned by
<TT
CLASS="FUNCTION"
>GetValue</TT
> points to storage that is part of
the <TT
CLASS="STRUCTNAME"
>PGresult</TT
> structure. One should not
modify it, and one must explicitly copy the value into other
storage if it is to be used past the lifetime of the
<TT
CLASS="STRUCTNAME"
>PGresult</TT
> structure itself.
<TT
CLASS="FUNCTION"
>BinaryTuples</TT
> is not yet implemented.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>GetLength</TT
> returns the length of a field
(column) in bytes. Tuple and field indices start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::GetLength(int tup_num, int field_num) const</PRE
><P>
This is the actual data length for the particular data value,
that is the size of the object pointed to by
<TT
CLASS="FUNCTION"
>GetValue</TT
>. Note that for
character-represented values, this size has little to do with
the binary size reported by <TT
CLASS="FUNCTION"
>PQfsize</TT
>.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>GetLength</TT
> returns the length of a field
(column) in bytes. Tuple and field indices start at 0.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::GetLength(int tup_num, const char* field_name) const</PRE
><P>
This is the actual data length for the particular data value,
that is the size of the object pointed to by
<TT
CLASS="FUNCTION"
>GetValue</TT
>. Note that for
character-represented values, this size has little to do with
the binary size reported by <TT
CLASS="FUNCTION"
>PQfsize</TT
>.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>GetIsNull</TT
>
returns whether a field has the null value.
</P><PRE
CLASS="SYNOPSIS"
>bool GetIsNull(int tup_num, int field_num) const</PRE
><P>
Note that <TT
CLASS="FUNCTION"
>GetValue</TT
> will return the empty
string for null fields, not the NULL pointer.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>GetIsNull</TT
> returns whether a field has the
null value.
</P><PRE
CLASS="SYNOPSIS"
>bool GetIsNull(int tup_num, const char *field_name) const</PRE
><P>
Note that <TT
CLASS="FUNCTION"
>GetValue</TT
> will return the empty
string for null fields, not the NULL pointer.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>DisplayTuples</TT
> prints out all the tuples
and, optionally, the attribute names to the specified output
stream.
</P><PRE
CLASS="SYNOPSIS"
>void PgDatabase::DisplayTuples(FILE *out = 0, bool fillAlign = true,
const char* fieldSep = "|", bool printHeader = true, bool quiet = false) const</PRE
><P>
This function is obsolescent.
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>PrintTuples</TT
> prints out all the tuples and,
optionally, the attribute names to the specified output stream.
</P><PRE
CLASS="SYNOPSIS"
>void PgDatabase::PrintTuples(FILE *out = 0, bool printAttName = true,
bool terseOutput = false, bool fillAlign = false) const</PRE
><P>
This function is obsolescent.
</P
>
</LI
></UL
>
</DIV
>
<DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="libpqpp-exec-nonselect"
>1.5.4. Retrieving Non-SELECT Result Information</A
></H2
>
<P
></P
><UL
><LI
> <P
> <TT
CLASS="FUNCTION"
>CmdTuples</TT
> returns the number of rows
affected after an <TT
CLASS="COMMAND"
>INSERT</TT
>,
<TT
CLASS="COMMAND"
>UPDATE</TT
>, or <TT
CLASS="COMMAND"
>DELETE</TT
>. If the
command was anything else, it returns -1.
</P><PRE
CLASS="SYNOPSIS"
>int PgDatabase::CmdTuples() const</PRE
><P>
</P
>
</LI
><LI
> <P
> <TT
CLASS="FUNCTION"
>OidStatus</TT
>
</P><PRE
CLASS="SYNOPSIS"
>const char *PgDatabase::OidStatus() const</PRE
><P>
</P
>
</LI
></UL
>
</DIV
>
</DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="libpqpp-connect.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="libpqpp-notify.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Database Connection Functions</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
> </TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Asynchronous Notification</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
