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