From 6f2c0d47f8fa718e0b2242380c4b22f031d3ec54 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Sat, 13 Apr 2002 01:42:44 +0000 Subject: [PATCH] This is a proposed patch to doc/src/sgml/libpgtcl.sgml which documents the libpgtcl "pg_execute" command. This was mentioned on pgsql-interfaces on Mar 3. I am posting it here in the hope that someone will check to see if it makes sense and is correct SGML-wise. I did run it through jade, but this is my first try at this sort of thing. ljb --- doc/src/sgml/libpgtcl.sgml | 199 +++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml index 7257062c00..eb7714bfbc 100644 --- a/doc/src/sgml/libpgtcl.sgml +++ b/doc/src/sgml/libpgtcl.sgml @@ -64,6 +64,9 @@ pg_select loop over the result of a SELECT statement + + pg_execute + send a query and optionally loop over the results pg_listen establish a callback for NOTIFY messages @@ -994,6 +997,202 @@ This would work if table table has fields control + + +pg_execute +PGTCL - Query Processing + + +pg_execute + + +send a query and optionally loop over the results + +pgtclquery +pg_execute + + + +2002-03-06 + + +pg_execute -array arrayVar -oid oidVar dbHandle queryString queryProcedure + + + + +2002-03-06 + +Inputs + + + + + -array arrayVar + + +Specifies the name of an array variable where result tuples are stored, +indexed by the field names. +This is ignored if queryString is not a SELECT statement. For SELECT +statements, if this option is not used, result tuples values are stored +in individual variables named according to the field names in the result. + + + + + + -oid oidVar + + +Specifies the name of a variable into which the OID from an INSERT +statement will be stored. + + + + + + dbHandle + + +Specifies a valid database handle. + + + + + + queryString + + +Specifies a valid SQL query. + + + + + + queryProcedure + + +Optional command to execute for each result tuple of a SELECT statement. + + + + + + + + + +2002-03-06 + +Outputs + + + + + ntuples + + + +The number of tuples affected or returned by the query. + + + + + + + + +2002-03-06 + +Description + + +pg_execute submits a query to the PostgreSQL backend. + + +If the query is not a SELECT statement, the query is executed and the +number of tuples affected by the query is returned. If the query is an +INSERT and a single tuple is inserted, the OID of the inserted tuple is +stored in the oidVar variable if the optional -oid +argument is supplied. + + +If the query is a SELECT statement, the query is executed. For each tuple +in the result, the tuple field values are stored in the +arrayVar variable, +if supplied, using the field names as the array indexes, else in variables +named by the field names, and then the optional +queryProcedure is executed if supplied. +(Omitting the queryProcedure probably makes sense +only if the query will return a single tuple.) +The number of tuples selected is returned. + + +The queryProcedure can use the Tcl +break, continue, and +return commands, with the expected behavior. +Note that if the queryProcedure executes +return, pg_execute does +not return ntuples. + + +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 backend-handled errors, pg_execute will +throw a Tcl error and return two element list. The first element +is an error code such as PGRES_FATAL_ERROR, and +the second element is the backend error text. For more serious +errors, such as failure to communicate with the backend, +pg_execute will throw a Tcl error and return +just the error message text. + + + + + +Usage + + +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 item and value fields 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" + + + + + + + + pg_listen