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

# pg_exec

## Name

pg_exec -- send a command to the server

## Synopsis

    pg_exec [-paramarray arrayVar] [-variables] conn commandString ?args?

## Description

`pg_exec` submits a command to the PostgreSQL server and returns a result. Command result handles start with the connection handle and add a period and a result number.

Note that lack of a Tcl error is not proof that the command succeeded! An error message returned by the server will be processed as a command result with failure status, not by generating a Tcl error in `pg_exec`. Check for {[pg_result $result -status] == PGRES_COMMAND_OK}.

If the [-paramarray] flag is provided, then a substitution is performed on the query, securely replacing each back-quote delimited name with the corresponding entry from the named array. If the array does not contain the named element, then NULL is substituted (similarly to the way an array created by -withoutnulls is generated). Each such name must occur in a location where a value or field name could appear. See pg_select for more info.

If the [-variables] flag is provided, then embedded Tcl variables are passed as parameters. Variables can be flagged with ':' and array references and namespaces are supported. Complex variable names can usually be embedded with :{nasty-name-here} though no attempt at duplicating Tcl brace-escaping is made. If the variable does not exist, then NULL is substituted.

## Arguments

[-paramarray arrayname]

  Perform parameter substitution via `quoted` elements of the array using PQexecParams or PQSendQueryParams.

[-variables]

  Substitute Tcl variables found in the SQL string using PQexecParams or PQSendQueryParams.

`conn`

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

`commandString`

  The SQL command to execute.

`args`

  For PostgreSQL versions greater than 7.4, `args` consists of zero or more optional values that can be inserted, unquoted, into the SQL statement using $-style substitution. Nulls are represented by the string "NULL".

## Return Value

A result handle. A Tcl error will be returned if pgtcl was unable to obtain a server response. Otherwise, a command result object is created and a handle for it is returned. This handle can be passed to `pg_result` to obtain the results of the command.

## Example

    pg_exec $conn {select * from table1 where id = $1 and user = $2} $id $user

Prev | Home | Next
pg_conndefaults | Up | pg_exec_prepared