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

# pg_execute

## Name

pg_execute -- send a query and optionally loop over the results

## Synopsis

    pg_execute ?-array arrayVar? ?-oid oidVar? conn commandString ?procedure?

## Description

`pg_execute` submits a command to the PostgreSQL server.

If the command is not a `SELECT` statement, the number of rows affected by the command is returned. If the command is an `INSERT` statement and a single row is inserted, the OID of the inserted row is stored in the variable oidVar if the optional -oid argument is supplied.

If the command is a `SELECT` statement, then, for each row in the result, the row values are stored in the arrayVar variable, if supplied, using the column names as the array indices, else in variables named by the column names, and then the optional procedure is executed if supplied. (Omitting the procedure probably makes sense only if the query will return a single row.) The number of rows selected is returned.

The procedure can use the Tcl commands `break`, `continue`, and `return` with the expected behavior. Note that if the procedure executes `return`, then `pg_execute` does not return the number of affected rows.

`pg_execute` is a newer function which provides a superset of the features of `pg_select` and can replace `pg_exec` in many cases where access to the result handle is not needed.

For server-handled errors, `pg_execute` will throw a Tcl error and return a two-element list. The first element is an error code, such as `PGRES_FATAL_ERROR`, and the second element is the server error text. For more serious errors, such as failure to communicate with the server, `pg_execute` will throw a Tcl error and return just the error message text.

## Arguments

-array arrayVar

  Specifies the name of an array variable where result rows are stored, indexed by the column names. This is ignored if commandString is not a `SELECT` statement.

-oid oidVar

  Specifies the name of a variable into which the OID from an `INSERT` statement will be stored.

conn

  The handle of the connection on which to execute the command.

commandString

  The SQL command to execute.

procedure

  Optional procedure to execute for each result row of a `SELECT` statement.

## Return Value

The number of rows affected or returned by the command.

## Examples

In the following examples, error checking with `catch` has been omitted for clarity.

Insert a row and save the OID in result_oid:

    pg_execute -oid result_oid $pgconn "INSERT INTO mytable VALUES (1);"

Print the columns `item` and `value` from each row:

    pg_execute -array d $pgconn "SELECT item, value FROM mytable;" {
        puts "Item=$d(item) Value=$d(value)"
    }

Find the maximum and minimum values and store them in `$s(max)` and `$s(min)`:

    pg_execute -array s $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;"

Find the maximum and minimum values and store them in `$max` and `$min`:

    pg_execute $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;"

Prev | Home | Next
pg_select | Up | pg_listen