PostgreSQL Tcl Interface Documentation
Prev | Fast Backward |  | Fast Forward | Next

# pg_result

## Name

pg_result -- get information about a command result

## Synopsis

    pg_result resultHandle resultOption

## Description

`pg_result` returns information about a command result created by a prior `pg_exec`.

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 `pg_result -clear`. Otherwise, you have a memory leak, and pgtcl will eventually start complaining that you have created too many command result objects.

## Arguments

resultHandle

  The handle of the command result.

resultOption

  One of the following options, specifying which piece of result information to return:

  -status

    The status of the result.

  -error ?diagCode?

    The error message, if the status indicates an error, otherwise an empty string.

    diagCode, if specified, requests data for a specific diagnostic code:

    severity

      The severity; the field contents are `ERROR`, `FATAL`, or `PANIC`, in an error message, or `WARNING`, `NOTICE`, `DEBUG`, `INFO`, or `LOG`, in a notice message, or a localized translation of one of these.

    sqlstate

      The `SQLSTATE` code for the error. (See PostgreSQL manual Appendix A).

    primary

      The primary human-readable error message (typically one line).

    detail

      An optional secondary error message carrying more detail abhout the problem, which may run to multiple lines.

    hint

      An optional suggestion about what to do about the problem. This is intended to differ from detail in that it offers advice (potentially inappropriate) rather than hard facts.

      The result may run to multiple lines.

    position

      A string containing a decimal integer indicating an error cursor position as an index into the original statement string.

      The first character has index `1`, and positions are measured in characters not bytes.

    context

      An indication of the context in which the error occurred. Presently this includes a call stack traceback of active PL functions. The trace is one entry per line, most recent first.

    file

      The filename of the source code location where the error was reported.

    line

      The line number of the source code location where the error was reported.

    function

      The name of the source code function reporting the error.

  -conn

    The connection that produced the result.

  -oid

    If the command was an `INSERT`, the OID of the inserted row, otherwise 0.

  -numTuples

    The number of rows (tuples) returned by the query.

  -cmdTuples

    The number of rows (tuples) affected by the command. (This is similar to -numTuples but relevant to `INSERT` and `UPDATE` commands.)

  -numAttrs

    The number of columns (attributes) in each row.

  -assign arrayName

    Assign the results to an array, using subscripts of the form `(rowNumber, columnName)`.

  -assignbyidx arrayName ?appendstr?

    Assign the results to an array using the values of the first column and the names of the remaining column as keys. If appendstr 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 `(firstColumnValue, columnNameAppendStr)`.

  -getTuple rowNumber

    Returns the columns of the indicated row in a list. Row numbers start at zero.

  -tupleArray rowNumber arrayName

    Stores the columns of the row in array arrayName, indexed by column names. Row numbers start at zero.

  -attributes

    Returns a list of the names of the columns in the result.

  -lAttributes

    Returns a list of sublists, `{name typeOid typeSize}` for each column.

  -list

    Returns one list containing all the data returned by the query.

  -llist

    Returns a list of lists, where each embedded list represents a tuple in the result.

  -dict

    Returns a dict object with the results. This needs to have dictionary support built into Tcl (Tcl 8.5), and is experimental right now, since Tcl 8.5 has not been release yet, and the API could change. In order to enable this, you need to add `-DHAVE_TCL_NEWDICTOBJ` to the Makefile in the `DEFS` variable.

  -null_value_string ?string?

    Defines or retrieves the string that will be returned for null values in query results. Defaults to whatever was set by `pg_null_value_string` but can be set here and, in this case, affects only this query result.

  -clear

    Clear the command result object.

## Return Value

The result depends on the selected option, as described above.

Prev | Home | Next
pg_exec_prepared | Up | pg_select