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.

    `internal_position`

      This is the same as "position", but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client.

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

    `internal_query`

      This is the text of a failed internally generated command. This could be, for example, a SQL query issued by a PL/pgSQL function.

    `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.

  `-foreach `arrayName` `tclCode``

    Iterates through each row of the result, filling `arrayName` with the columns and their values and executing `tclCode` for each row in turn. Null columns will be not be present in the array.

  `-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)`.

  `-foreach `arrayName` `code``

    For each resulting row assigns the results to the named array, using subscripts matching the column names, then executes the code body.

  `-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. If a field's value is null, sets an empty string or the default string, if a default string has been defined.

  `-tupleArrayWithoutNulls `rowNumber` `arrayName``

    Stores the columns of the row in array `arrayName`, indexed by column names. Row numbers start at zero. If a field's value is null, unsets the column from the array.

  `-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