pg_execute

PG_EXECUTE()	       PostgreSQL 7.4.19 Documentation		 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 sup-
       plied, 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	 fea-
       tures  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	 com-
	      mandString 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;"




				  2008-01-03			 PG_EXECUTE()