<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>pg_result</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="Pgtcl Reference Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Query Execution Commands"
HREF="pgtcl-ref-query.html"><LINK
REL="PREVIOUS"
TITLE="pg_exec_prepared"
HREF="pg-exec-prepared.html"><LINK
REL="NEXT"
TITLE="pg_escape_string"
HREF="pg-escape-string.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
NAME="creation"
CONTENT="2004-11-09T00:53:06"></HEAD
><BODY
CLASS="REFENTRY"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Pgtcl Reference Manual: The PostgreSQL Tcl Interface</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="pg-exec-prepared.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="pg-escape-string.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="PG-RESULT"
></A
>pg_result</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN1325"
></A
><H2
>Name</H2
>pg_result -- get information about a command result</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN1328"
></A
><H2
>Synopsis</H2
><PRE
CLASS="SYNOPSIS"
>pg_result <VAR
CLASS="PARAMETER"
>resultHandle</VAR
> <VAR
CLASS="PARAMETER"
>resultOption</VAR
></PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1332"
></A
><H2
>Description</H2
><P
><CODE
CLASS="FUNCTION"
>pg_result</CODE
> returns information about a command result
created by a prior <A
HREF="pg-exec.html"
>pg_exec</A
>, <A
HREF="pg-exec-prepared.html"
>pg_exec_prepared</A
>,
<A
HREF="pg-exec-params.html"
>pg_exec_params</A
>, or <A
HREF="pg-getresult.html"
>pg_getresult</A
>.
</P
><P
>You can keep a command result around for as long as you need it,
but when you are done with it, be sure to free it by executing
<CODE
CLASS="FUNCTION"
>pg_result -clear</CODE
>. Otherwise, you have a
memory leak, and <SPAN
CLASS="APPLICATION"
>pgtcl</SPAN
> will eventually start
complaining that you have created too many command result objects.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1343"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="REPLACEABLE"
>resultHandle</VAR
></DT
><DD
><P
> The handle of the command result.
</P
></DD
><DT
><VAR
CLASS="REPLACEABLE"
>resultOption</VAR
></DT
><DD
><P
> One of the following options, specifying which piece of result
information to return:
<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><VAR
CLASS="OPTION"
>-assign <VAR
CLASS="REPLACEABLE"
>arrayName</VAR
></VAR
></DT
><DD
><P
> Assign the results to an array, using subscripts of the form
<TT
CLASS="LITERAL"
>(rowNumber,columnName)</TT
>.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-assignbyidx</VAR
> <VAR
CLASS="REPLACEABLE"
>arrayName</VAR
> ?<SPAN
CLASS="OPTIONAL"
><VAR
CLASS="REPLACEABLE"
>appendstr</VAR
></SPAN
>?</DT
><DD
><P
> Assign the results to an array using the values of the
first column and the names of the remaining column as keys.
If <VAR
CLASS="REPLACEABLE"
>appendstr</VAR
> is given then it is appended to
each key. In short, all but the first column of each row
are stored into the array, using subscripts of the form
<TT
CLASS="LITERAL"
>(firstColumnValue,columnNameAppendStr)</TT
>.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-attributes</VAR
></DT
><DD
><P
> Returns a list of the names of the columns in the result.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-clear</VAR
></DT
><DD
><P
> Clear the command result object.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-cmdStatus</VAR
></DT
><DD
><P
> Returns the command status tag from the SQL command that
generated the result. This is the name of the SQL
command, such as <TT
CLASS="COMMAND"
>UPDATE</TT
>, often
followed by additional data such as the number of
rows affected. Note: This was added in
<SPAN
CLASS="APPLICATION"
>pgtclng-1.5.1</SPAN
> and in
<SPAN
CLASS="APPLICATION"
>pgintcl-2.0.1</SPAN
>.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-cmdTuples</VAR
></DT
><DD
><P
> Returns the number of rows (tuples) affected by the command.
This is appropriate to use for commands with completion
status <TT
CLASS="LITERAL"
>PGRES_COMMAND_OK</TT
>.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-conn</VAR
></DT
><DD
><P
> Returns the handle (name) of the connection that produced the result.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-error</VAR
> ?<SPAN
CLASS="OPTIONAL"
><VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
></SPAN
>?</DT
><DD
><P
> Returns the error message, if the status indicates an error,
otherwise an empty string.
Note: the optional <VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
>
parameter was added in
<SPAN
CLASS="APPLICATION"
>pgintcl-2.2.0</SPAN
> and
<SPAN
CLASS="APPLICATION"
>pgtclng-1.5.2</SPAN
>, making
<VAR
CLASS="OPTION"
>-error</VAR
> and <VAR
CLASS="OPTION"
>-errorField</VAR
>
synonymous.
If a <VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
> is supplied,
returns the value of an extended error code field.
Refer to the next option, <VAR
CLASS="OPTION"
>-errorField</VAR
>
for details.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-errorField</VAR
> ?<SPAN
CLASS="OPTIONAL"
><VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
></SPAN
>?</DT
><DD
><P
> Returns the error message, if no
<VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
> is supplied, or the
value of an extended error code field, if
<VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
> is supplied.
Note: the <VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
>
parameter was made optional in
<SPAN
CLASS="APPLICATION"
>pgintcl-2.2.0</SPAN
> and
<SPAN
CLASS="APPLICATION"
>pgtclng-1.5.2</SPAN
>, making
<VAR
CLASS="OPTION"
>-error</VAR
> and <VAR
CLASS="OPTION"
>-errorField</VAR
>
synonymous. Prior to those versions, <VAR
CLASS="OPTION"
>-error</VAR
>
was used to get the whole error message, and
<VAR
CLASS="OPTION"
>-errorField</VAR
> was used to get an extended
error code field value.
</P
><P
> <VAR
CLASS="REPLACEABLE"
>fieldCode</VAR
> selects the error code field
by full name or single character abbreviation, according to
the following table.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="PGTCL-RESULT-ERRORFIELD"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><COL><THEAD
><TR
><TH
>FieldCode</TH
><TH
>Abbreviated FieldCode</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
>SEVERITY</TD
><TD
>S</TD
><TD
>ERROR or FATAL, for example</TD
></TR
><TR
><TD
>SQLSTATE</TD
><TD
>C</TD
><TD
>5-character SQL State</TD
></TR
><TR
><TD
>MESSAGE_PRIMARY</TD
><TD
>M</TD
><TD
>Primary error message</TD
></TR
><TR
><TD
>MESSAGE_DETAIL</TD
><TD
>D</TD
><TD
>Optional detailed message</TD
></TR
><TR
><TD
>MESSAGE_HINT</TD
><TD
>H</TD
><TD
>Optional suggestion</TD
></TR
><TR
><TD
>STATEMENT_POSITION</TD
><TD
>P</TD
><TD
>Decimal integer cursor position</TD
></TR
><TR
><TD
>CONTEXT</TD
><TD
>W</TD
><TD
>Call Stack trace</TD
></TR
><TR
><TD
>SOURCE_FILE</TD
><TD
>F</TD
><TD
>PostgreSQL source code filename</TD
></TR
><TR
><TD
>SOURCE_LINE</TD
><TD
>L</TD
><TD
>PostgreSQL source code line number</TD
></TR
><TR
><TD
>SOURCE_FUNCTION</TD
><TD
>R</TD
><TD
>PostgreSQL source code function name</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
(Note: 'optional' means the value may or may not be
provided by the server.)
</P
><P
> In addition, the following field code aliases were added
to <SPAN
CLASS="APPLICATION"
>pgintcl-2.2.0</SPAN
> and
<SPAN
CLASS="APPLICATION"
>pgtclng-1.5.2</SPAN
>, for compatibility
with <SPAN
CLASS="APPLICATION"
>Gborg pgtcl</SPAN
>. All field
code names are accepted in upper or lower case.
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="PGTCL-RESULT-ERRORFIELD2"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>FieldCode Alias</TH
><TH
>Description</TH
></TR
></THEAD
><TBODY
><TR
><TD
>primary</TD
><TD
>Same as MESSAGE_PRIMARY</TD
></TR
><TR
><TD
>detail</TD
><TD
>Same as MESSAGE_DETAIL</TD
></TR
><TR
><TD
>hint</TD
><TD
>Same as MESSAGE_HINT</TD
></TR
><TR
><TD
>position</TD
><TD
>Same as STATEMENT_POSITION</TD
></TR
><TR
><TD
>file</TD
><TD
>Same as SOURCE_FILE</TD
></TR
><TR
><TD
>line</TD
><TD
>Same as SOURCE_LINE</TD
></TR
><TR
><TD
>function</TD
><TD
>Same as SOURCE_FUNCTION</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-getNull <VAR
CLASS="REPLACEABLE"
>rowNumber</VAR
></VAR
></DT
><DD
><P
> Returns a list of 1s and 0s for the indicated row, with 1
meaning the value of the column is NULL, and 0 meaning the
value of the column is not NULL.
Row numbers start at zero.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-getTuple <VAR
CLASS="REPLACEABLE"
>rowNumber</VAR
></VAR
></DT
><DD
><P
> Returns the values of the columns of the indicated row in a
list. Row numbers start at zero.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-lAttributes</VAR
></DT
><DD
><P
> Returns a list of attributes of the query result columns.
For each column, the list contains a sublist of
the form <TT
CLASS="LITERAL"
>{ColumnName TypeOid TypeSize}</TT
>.
More information on these values can be found in the
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL Libpq</SPAN
> documentation.
Note that <TT
CLASS="COMMAND"
>pg_result -lxAttributes</TT
>
returns a superset of this information.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-list</VAR
></DT
><DD
><P
> Returns the entire result as a list of values in row-major,
column-minor order.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-llist</VAR
></DT
><DD
><P
> Returns the entire result as a list of lists. The outer list
contains one element for each result row, and the inner lists
contain the values for each column of the row.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-lxAttributes</VAR
></DT
><DD
><P
> Returns an extended list of attributes of the query result
columns. For each column, the list contains a sublist of
the form <TT
CLASS="LITERAL"
>{ColumnName TypeOid TypeSize
TypeSizeModifier Format TableOID TableColumnIndex}</TT
>.
More information on these values can be found in the
<SPAN
CLASS="PRODUCTNAME"
>PostgreSQL Libpq</SPAN
> documentation.
Note that this is an extension of the information returned
by <TT
CLASS="COMMAND"
>pg_result -lAttributes</TT
>.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-numAttrs</VAR
></DT
><DD
><P
> Returns the number of columns (attributes) in each row.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-numTuples</VAR
></DT
><DD
><P
> Returns the number of rows (tuples) returned by the query.
This is appropriate to use for commands with completion
status <TT
CLASS="LITERAL"
>PGRES_TUPLES_OK</TT
>.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-oid</VAR
></DT
><DD
><P
> If the command was a single row <TT
CLASS="COMMAND"
>INSERT</TT
>,
returns the OID (Object ID) of the inserted row, otherwise
returns 0.
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-status</VAR
></DT
><DD
><P
> Returns the status of the result. This will be one of the
following strings:
<DIV
CLASS="INFORMALTABLE"
><P
></P
><A
NAME="PGTCL-RESULT-STATUS"
></A
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><COL><COL><THEAD
><TR
><TH
>Status</TH
><TH
>Meaning</TH
></TR
></THEAD
><TBODY
><TR
><TD
>PGRES_COMMAND_OK</TD
><TD
>Successful completion of a command returning no
data, such as <TT
CLASS="COMMAND"
>INSERT</TT
>.
</TD
></TR
><TR
><TD
>PGRES_TUPLES_OK</TD
><TD
>Successful completion of a command which returns
data (such as <TT
CLASS="COMMAND"
>SELECT</TT
> or
<TT
CLASS="COMMAND"
>SHOW</TT
>). Note this is the
status even if the <TT
CLASS="COMMAND"
>SELECT</TT
>
happens to return no rows.
</TD
></TR
><TR
><TD
>PGRES_COPY_OUT</TD
><TD
>Begin <TT
CLASS="COMMAND"
>COPY TO STDOUT</TT
>.</TD
></TR
><TR
><TD
>PGRES_COPY_IN</TD
><TD
>Begin <TT
CLASS="COMMAND"
>COPY FROM STDIN</TT
>.</TD
></TR
><TR
><TD
>PGRES_EMPTY_QUERY</TD
><TD
>The query string sent to the server was
empty.</TD
></TR
><TR
><TD
>PGRES_BAD_RESPONSE</TD
><TD
>The server's response was not understood.</TD
></TR
><TR
><TD
>PGRES_FATAL_ERROR</TD
><TD
>An error occurred. This includes any SQL
syntax errors, or errors processing the command
such as <TT
CLASS="COMMAND"
>SELECT</TT
> from a
non-existing table.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
>
</P
></DD
><DT
><VAR
CLASS="OPTION"
>-tupleArray <VAR
CLASS="REPLACEABLE"
>rowNumber</VAR
> <VAR
CLASS="REPLACEABLE"
>arrayName</VAR
></VAR
></DT
><DD
><P
> Stores the columns of the row in array
<VAR
CLASS="REPLACEABLE"
>arrayName</VAR
>, indexed by column names.
Row numbers start at zero.
</P
></DD
></DL
></DIV
><P>
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1618"
></A
><H2
>Return Value</H2
><P
> The result depends on the selected option, as described above.
</P
><P
> A Tcl error will be thrown if there is an error processing the
command, which is unlikely since no communication with the server
is involved.
</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1622"
></A
><H2
>Notes</H2
><P
> <A
HREF="pgtcl-example-results.html"
>Section 5.4</A
> contains examples of the
different ways to get query results with <CODE
CLASS="FUNCTION"
>pg_result</CODE
>.
</P
><P
> This command uses a variety of <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
>
<SPAN
CLASS="APPLICATION"
>libpq</SPAN
> functions described in the
<I
CLASS="CITETITLE"
>Command Execution Functions</I
> chapter
of the <SPAN
CLASS="APPLICATION"
>libpq</SPAN
> reference manual.
</P
></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="pg-exec-prepared.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="pg-escape-string.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>pg_exec_prepared</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="pgtcl-ref-query.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>pg_escape_string</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
