From 0a1c2805b35f59b3654d51c965d03699e60b50f7 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 8 Oct 1998 03:23:03 +0000 Subject: [PATCH] libpgtcl.sgml still needs work, but at least there are fewer errors than there were. --- doc/src/sgml/libpgtcl.sgml | 571 +++++++++++++++++++++++++++++---------------- 1 file changed, 373 insertions(+), 198 deletions(-) diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml index 7bc254ac77..245043d586 100644 --- a/doc/src/sgml/libpgtcl.sgml +++ b/doc/src/sgml/libpgtcl.sgml @@ -15,12 +15,6 @@ This package was originally written by Jolly Chen. Commands -The pg_lo* routines are interfaces to the Inversion Large Objects in Postgres. -The functions are designed to mimic the analogous file system functions in -the standard Unix file system interface. - - - PGTCL Commands @@ -110,7 +104,11 @@ These commands are described further on subsequent pages. -The pg_lo* routines should typically be used within a BEGIN/END transaction +The pg_lo* routines are interfaces to the Large Object features of +Postgres. +The functions are designed to mimic the analogous file system functions in +the standard Unix file system interface. +The pg_lo* routines should be used within a BEGIN/END transaction block because the file descriptor returned by pg_lo_open is only valid for the current transaction. pg_lo_import and pg_lo_export MUST be used in a BEGIN/END transaction block. @@ -137,6 +135,7 @@ proc getDBs { {host "localhost"} {port "5432"} } { for {set i 0} {$i < $ntups} {incr i} { lappend datnames [pg_result $res -getTuple $i] } + pg_result $res -clear pg_disconnect $conn return $datnames } @@ -167,14 +166,20 @@ proc getDBs { {host "localhost"} {port "5432"} } { pg_connect dbName -host hostName - -port portNumber -tty pqtty -options optionalBackendArgs + -port portNumber -tty + pqtty + -options optionalBackendArgs + +pg_connect -conninfo connectOptions 1997-12-24 -Inputs +<TITLE>Inputs (old style) @@ -227,6 +232,25 @@ pg_connect dbName -host < +1998-10-07 + +Inputs (new style) + + + + + connectOptions + + +A string of connection options, each written in the form keyword = value. + + + + + + + + 1997-12-24 Outputs @@ -238,8 +262,8 @@ pg_connect <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE> <OPTIONAL>-host < </TERM> <LISTITEM> <PARA> -The return result is either an error message or a handle for a database - connection. Handles start with the prefix "pgsql" +If successful, a handle for a database connection is returned. +Handles start with the prefix "pgsql". </PARA> </LISTITEM> </VARLISTENTRY> @@ -255,7 +279,15 @@ The return result is either an error message or a handle for a database </REFSECT1INFO> <TITLE>Description -pg_connect opens a connection to the Postgres backend. +pg_connect opens a connection to the +Postgres backend. + + +Two syntaxes are available. In the older one, each possible option +has a separate option switch in the pg_connect statement. In the +newer form, a single option string is supplied that can contain +multiple option values. See pg_conndefaults +for info about the available options in the newer syntax. @@ -338,10 +370,91 @@ pg_disconnect dbHandle + + + + + +pg_conndefaults +PGTCL - Connection Management + + +pg_conndefaults + +obtain information about default connection parameters + +pgtclconnecting +pg_conndefaults + + + +1998-10-07 + + +pg_conndefaults + + + + +1998-10-07 + +Inputs + + +None. + + + + + +1998-10-07 + +Outputs + + + + + option list + + + +The result is a list describing the possible connection options and their +current default values. +Each entry in the list is a sublist of the format: + + {optname label dispchar dispsize value} + +where the optname is usable as an option in pg_connect -conninfo. + + + + + + + + + +1998-10-07 + +Description + +pg_conndefaults returns info about the connection +options available in pg_connect -conninfo and the +current default value for each option. + + + +Usage + +pg_conndefaults + + + + pg_exec -PGTCL - Connection Management +PGTCL - Query Processing pg_exec @@ -399,11 +512,14 @@ pg_exec dbHandle - queryHandle + resultHandle - the return result is either an error message or a handle for a query result. +A Tcl error will be returned if Pgtcl was unable to obtain a backend +response. Otherwise, a query 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 query. @@ -421,116 +537,240 @@ pg_exec dbHandle +Note that lack of a Tcl error is not proof that the query succeeded! +An error message returned by the backend will be processed +as a query result with failure status, not by generating a Tcl error +in pg_exec. - + -pg_listen -PGTCL - Asynchronous Notify +pg_result +PGTCL - Query Processing -pg_listen +pg_result -sets or changes a callback for asynchronous NOTIFY messages + +get information about a query result -pgtclnotify -notify +pgtclconnecting +pg_connect -1998-5-22 +1997-12-24 -pg_listen dbHandle notifyName callbackCommand +pg_result resultHandle resultOption - - + -1998-5-22 +1997-12-24 Inputs - dbHandle + resultHandle -Specifies a valid database handle. + + The handle for a query result. - notifyName + resultOption -Specifies the notification name to start or stop listening to. + +Specifies one of several possible options. + + + +Options + + - callbackCommand +-status -If present and not empty, provides the command string to execute -when a matching notification arrives. + +the status of the result. - - - - - -1998-5-22 - -Outputs - - - None +-error + + + +the error message, if the status indicates error; otherwise an empty string. + + + + + +-conn + + + +the connection that produced the result. + + + + + +-oid + + + +if the command was an INSERT, the OID of the +inserted tuple; otherwise an empty string. + + + + + +-numTuples + + + +the number of tuples returned by the query. + + + + + +-numAttrs + + + +the number of attributes in each tuple. + + + + + +-assign arrayName + + + +assign the results to an array, using subscripts of the form +(tupno,attributeName). + + + + + +-assignbyidx arrayName ?appendstr? + + + +assign the results to an array using the first attribute's value and +the remaining attributes' names as keys. If appendstr is given then +it is appended to each key. In short, all but the first field of each +tuple are stored into the array, using subscripts of the form +(firstFieldValue,fieldNameAppendStr). + + + + + +-getTuple tupleNumber + + + +returns the fields of the indicated tuple in a list. Tuple numbers +start at zero. + + + + + +-tupleArray tupleNumber arrayName + + + +stores the fields of the tuple in array arrayName, indexed by field names. +Tuple numbers start at zero. + + + + + +-attributes + + + +returns a list of the names of the tuple attributes. + + + + + +-lAttributes +returns a list of sublists, {name ftype fsize} for each tuple attribute. + + + + + +-clear + + + +clear the result query object. + - - + + +1997-12-24 + +Outputs + + +The result depends on the selected option, as described above. + + + + -1998-5-22 +1997-12-24 Description -pg_listen creates, changes, or cancels a request -to listen for asynchronous NOTIFY messages from the -Postgres backend. With a callbackCommand -parameter, the request is established, or the command string of an already -existing request is replaced. With no callbackCommand parameter, a prior -request is canceled. - + +pg_result returns information about a query result +created by a prior pg_exec. -After a pg_listen request is established, -the specified command string is executed whenever a NOTIFY message bearing -the given name arrives from the backend. This occurs when any -Postgres client application issues a NOTIFY command -referencing that name. (Note that the name can be, but does not have to be, -that of an existing relation in the database.) -The command string is executed from the Tcl idle loop. That is the normal -idle state of an application written with Tk. In non-Tk Tcl shells, you can -execute update or vwait to cause -the idle loop to be entered. +You can keep a query result around for as long as you need it, but when +you are done with it, be sure to free it by +executing pg_result -clear. Otherwise, you have +a memory leak, and Pgtcl will eventually start complaining that you've +created too many query result objects. - @@ -538,7 +778,7 @@ the idle loop to be entered. pg_select -PGTCL - Connection Management +PGTCL - Query Processing pg_select @@ -614,7 +854,7 @@ pg_select dbHandle - queryHandle + resultHandle @@ -632,14 +872,18 @@ pg_select dbHandle Description -pg_select submits a query to the Postgres backend. - and returns the results. +pg_select submits a SELECT query to the +Postgres backend, and executes a +given chunk of code for each tuple in the result. The queryString - must be a select statement. Anything else returns an error. + must be a SELECT statement. Anything else returns an error. The arrayVar - variable is an array name used in the loop. It is filled - out with the result of the query for each tuple using the field - names as the associative indices. + variable is an array name used in the loop. For each tuple, + arrayVar is filled in + with the tuple field values, using the field names as the array + indexes. Then the + queryProcedure + is executed. @@ -647,13 +891,12 @@ pg_select dbHandle Usage +This would work if table "table" has fields "control" and "name" +(and, perhaps, other fields): - set DB "mydb" - set conn [pg_connect $DB] - pg_select $conn "SELECT * from table" array { + pg_select $pgconn "SELECT * from table" array { puts [format "%5d %s" array(control) array(name)] } - pg_disconnect $conn @@ -662,187 +905,119 @@ pg_select dbHandle - + -pg_result -PGTCL - Connection Management +pg_listen +PGTCL - Asynchronous Notify -pg_result +pg_listen - -get information about a query result +sets or changes a callback for asynchronous NOTIFY messages -pgtclconnecting -pg_connect +pgtclnotify +notify -1997-12-24 +1998-5-22 -pg_result queryHandle resultOption +pg_listen dbHandle notifyName callbackCommand - + + -1997-12-24 +1998-5-22 Inputs - queryHandle - - - - The handle for a query result. - - - - - - resultOption - - - -Specifies one of several possible options. - - - - - - -Options - - - - --status - - - -the status of the result. - - - - - --oid - - - -if the last query was an insert, returns the oid of the -inserted tuple - - - - - --conn - - - -the connection that produced the result - - - - - --assign arrayName - - - -assign the results to an array - - - - - --assignbyidx arrayName ?appendstr? - - - -assign the results to an array using the first field as a key -and optionally append appendstr to the key name. Useful for -creating pseudo-multi dimensional arrays in tcl. - - - - - --numTuples - - - -the number of tuples in the query - - - - - --attributes + dbHandle - -returns a list of the name/type pairs of the tuple attributes +Specifies a valid database handle. --getTuple tupleNumber + notifyName - -returns the values of the tuple in a list +Specifies the notify condition name to start or stop listening to. --clear + callbackCommand - -clear the result buffer. Do not reuse after this +If present and not empty, provides the command string to execute +when a matching notification arrives. - - + -1997-12-24 +1998-5-22 Outputs - queryHandle + None - the return result is either an error message or a handle for a query result. - + + - + -1997-12-24 +1998-5-22 Description - -pg_result returns information about a query. +pg_listen creates, changes, or cancels a request +to listen for asynchronous NOTIFY messages from the +Postgres backend. With a callbackCommand +parameter, the request is established, or the command string of an already +existing request is replaced. With no callbackCommand parameter, a prior +request is canceled. + + + +After a pg_listen request is established, +the specified command string is executed whenever a NOTIFY message bearing +the given name arrives from the backend. This occurs when any +Postgres client application issues a NOTIFY command +referencing that name. (Note that the name can be, but does not have to be, +that of an existing relation in the database.) +The command string is executed from the Tcl idle loop. That is the normal +idle state of an application written with Tk. In non-Tk Tcl shells, you can +execute update or vwait to cause +the idle loop to be entered. + + +You should not invoke the SQL statements LISTEN or UNLISTEN directly when +using pg_listen. Pgtcl takes care of issuing those +statements for you. But if you want to send a NOTIFY message yourself, +invoke the SQL NOTIFY statement using pg_exec. + -- 2.11.0