1This is the pgtcl-ng Source Release Historical README 2Last updated for pgtcl-1.5.0 on 2004-02-29 3The project home page is: http://gborg.postgresql.org/project/pgtclng/ 4----------------------------------------------------------------------------- 5 6This file contains historical information about the PostgreSQL Tcl 7Interface. README files distributed with predecessor projects can be found 8below. Not all of this information applies to the current release, and the 9Reference Manual and current README should be considered definitive. 10 11============================================================================= 12 README from Gborg "pgtcl" project unbundled interface release 1.4b3 13----------------------------------------------------------------------------- 14libpgtcl is a library that implements Tcl commands for front-end 15clients to interact with Postgresql 7.2 (and perhaps later) 16backends. See libpgtcl.doc for details. 17 18 Id: README,v 1.6 2002/11/16 01:10:51 karl Exp 19 20This is pgtcl version 1.4 beta 3 21 22CHANGES IN 1.4 BETA 3 23 24Fixed all known memory leaks. Fixed bug in "pg_result -assignbyidx". 25Fixed notifier bug in pg_listen. 26 27VERSION 1.4 28 29With version 1.4, Pgtcl has been internally overhauled and brought up to 30date with the latest Tcl C-interface technology, while maintaining 31nearly 100% compatibility with the pg_* Tcl interface provided by Pgtcl 1.3. 32 33Most Tcl programs that used Pgtcl 1.3 will work without modification 34under Pgtcl 1.4. 35 36This is a transitional release, as pgtcl is moving out the of core and 37into its own distribution. This means that documentation also must be 38collected and included. This has not yet been done. 39 40CONFIGURING 41 42Pgtcl is now Tcl Extension Architecture (TEA) compliant, shipping with 43a standard "configure" script. It no longer needs to reside in a specific 44place within the Postgres source tree in order to build. 45 46You need to specify a path to the Postgres include files 47using --with-postgres-include and to the Postgres libraries 48using --with-postgres-lib 49 50If you had PostgreSQL installed into /usr/postgres and a Tcl build in 51/usr/pptcl, you might use something like 52 53./configure --prefix=/usr/pptcl --with-postgres-include=/usr/postgres/include --with-postgres-lib=/usr/postgres/lib 54 55BUILDING 56 57Do a "make". If all goes well, libpgtcl will be compiled and linked. 58 59INSTALLING 60 61Do a "make install". 62 63USING IT 64 65With version 1.4, Pgtcl is a standard package and can be loaded with 66"package require" instead of the shared library load routine, "load". 67 68Fire up your tclsh: 69 70tclsh8.4 71% package require Pgtcl 721.4 73 74You should use package require instead of load because there will be 75additional Tcl code shipped in future versions of Pgtcl, and using 76package require will make that code available to your application. 77 78 79CHANGES 80 81The main changes are: 82 83 o Support has been dropped for Tcl 7.x. We now support Tcl 8.0 and above, 84 preferably Tcl 8.3 and above. 85 86 o All commands have now been converted to use Tcl 8-style Tcl objects. 87 88 The result is a probable increase in performance in all routines, with 89 potentially huge performance increases in pg_select and pg_execute when 90 used with complex Tcl code bodies. 91 92 o A new experimental asynchronous interface has been added 93 94 Requests can be issued to the backend without waiting for the 95 results, allowing for user interfaces to still work, etc. 96 Also, requests can now be cancelled while they're in process. 97 98 o pg_* call arguments are now checked much more rigorously. 99 100 Code previously using atoi() for integer conversions now 101 uses Tcl_GetIntFromObj, etc. 102 103 pg_* calls with too many arguments were often accepted without 104 complaint. These now generate standard Tcl "wrong # args" 105 messages, etc. 106 107 o Error reporting has been brought into more compliance with the 108 Tcl way of doing things. 109 110 o TEA-compliant build and install. 111 112So some programs that might have been working properly but had certain 113syntatically incorrect pg_* commands will now fail until fixed. 114 115pg_result -assign and pg_result -assignbyidx used to return the array 116name, which was superfluous because the array name was specified on the 117command line. They now return nothing. *** POTENTIAL INCOMPATIBILITY *** 118 119============================================================================= 120 README.async from Gborg "pgtcl" unbundled interface project 121----------------------------------------------------------------------------- 122 Id: README.async,v 1.1 2002/11/04 16:53:38 karl Exp 123 124Experimental Tcl interface to PostgreSQL asynchronous query processing 125 126 by Karl Lehenbauer (karl@procplace.com) 10/30/2002 127 128RATIONALE 129 130From the C-interface docs: 131 132The PQexec function is adequate for submitting commands in simple 133synchronous applications. It has a couple of major deficiencies however: 134 135 * PQexec waits for the command to be completed. The application may 136 have other work to do (such as maintaining a user interface), in which 137 case it won't want to block waiting for the response. 138 139 * Since control is buried inside PQexec, it is hard for the frontend 140 to decide it would like to try to cancel the ongoing command. (It 141 can be done from a signal handler, but not otherwise.) 142 143 * PQexec can return only one PGresult structure. If the submitted 144 command string contains multiple SQL commands, all but the last 145 PGresult are discarded by PQexec. 146 147WHAT THIS IS 148 149A handful of new pg_* commands have been added to support asynchronous 150operation, including cancelling requests that are currently being 151processed and obtaining results from each SQL command when a 152query contains multiple commands. 153 154EXPERIMENTAL IN NATURE 155 156This is a new Tcl interface to asynchronous query processing capabilities that 157have been made available through the Postgres C interface. 158 159We're calling it experimental because we think we'll want to evolve and change 160the interface, perhaps simplifying it, as we gain experience with it. So 161if you use it, understand that we are not promising to provide the same 162interface or backwards compatibility to this interface in future releases. 163 164ASYNCHRONOUS QUERY PROCESSING COMMANDS 165 166 pg_sendquery connection query 167 168This works like pg_exec, except that the query is issued asynchronously 169and pg_sendquery returns immediately without providing a result handle. 170 171To get result handles resulting from the execution of pg_sendqery (and there 172may be more than one if there are multiple SQL commands in the query), you 173need to repeatedly call 174 175 pg_getresult connection 176 177This will return the same sort of result handle that pg_exec returns. 178 179If there is no query currently being processed or all of the results have 180been obtained, pg_getresult returns nothing. 181 182 183 pg_isbusy connection 184 185pg_getresult can block if results aren't yet available. To avoid this, 186you can use pg_isbusy to check to see if the connection is busy processing 187a query. 188 189If this returns 1, pg_getresult will block if called. If it's 0, you can 190safely call pg_getresult and it won't block. 191 192 pg_blocking 193 194This sets whether a connection is set for blocking or nonblocking, and 195allows that state to be changed. 196 197 syntax: 198 pg_blocking connection - returns the current state, 1 = blocking, 0 = non 199 pg_blocking connection 1 - sets the connection to blocking 200 pg_blocking connection 0 - sets the connection to nonblocking 201 202Note - I'm not sure about all of the ramifications of setting a connection 203nonblocking. Even with a connection in the (default) blocking state, 204pg_isbusy seems to work OK and can be used in conjunction with pg_getresult 205to keep from blocking while processing query results. 206 207 208 pg_cancelrequest connection 209 210This request that postgresql abandon processing of the current command 211issued via pg_sendquery. 212 213There is no guarantee that the request will be cancelled. If it is and 214you were in the middle of a transaction, the entire transaction is cancelled. 215 216You still need to call pg_getresult repeatedly until it doesn't return 217anything, and handle (and discard) all of the returned result handles. 218 219 220HOW TO USE IT 221 222We really need some example code. Probably we need some Tcl code that will 223be part of the libary, pulled in with "package require Pgtcl", that will 224issue a pg_sendrequest and iteratively call pg_isbusy on a timer, then 225looping through passed-in Tcl code for each result until none are found. 226 227You'll want to write something that issues the request via pg_sendquery. 228Then you'll want a proc that does a pg_isbusy and if it is busy, calls 229itself to run again after, oh, a tenth of a second or so, via "after". 230If pg_isbusy returns 0, you can safely call pg_getresult to get a result. 231(Use pg_result to examine the result, as in the past.) If pg_getresult 232returns an empty string, there is no more work to be done. 233 234If you want to cancel a request that is currently in progress, use 235pg_cancelrequest. Note that you still need to do the pg_getresult 236thing repeatedly until it returns nothing. For more information, read 237the C interface docs in the PostgreSQL documentation. 238 239I know you'd like some example code. We don't have any yet. That's why we 240call it an alpha release. 241 242LICENSE 243 244Berkeley License. Freely redistributable for any use including resale, 245without royalty or other sucky GPL restrictions. Don't sue us if it 246kills your dog. 247 248============================================================================= 249 README from PostgreSQL-7.4.1 bundled interfaces/libpgtcl: 250----------------------------------------------------------------------------- 251libpgtcl is a library that implements Tcl commands for front-end 252clients to interact with the Postgresql 6.3 (and perhaps later) 253backends. See libpgtcl.doc for details. 254 255For an example of how to build a new tclsh to use libpgtcl, see the 256directory ../bin/pgtclsh 257 258Note this version is modified by NeoSoft to have the following additional 259features: 260 2611. Postgres connections are a valid Tcl channel, and can therefore 262 be manipulated by the interp command (ie. shared or transfered). 263 A connection handle's results are transfered/shared with it. 264 (Result handles are NOT channels, though it was tempting). Note 265 that a "close $connection" is now functionally identical to a 266 "pg_disconnect $connection", although pg_connect must be used 267 to create a connection. 268 2692. Result handles are changed in format: ${connection}.<result#>. 270 This just means for a connection 'pgtcl0', they look like pgtcl0.0, 271 pgtcl0.1, etc. Enforcing this syntax makes it easy to look up 272 the real pointer by indexing into an array associated with the 273 connection. 274 2753. I/O routines are now defined for the connection handle. I/O to/from 276 the connection is only valid under certain circumstances: following 277 the execution of the queries "copy <table> from stdin" or 278 "copy <table> to stdout". In these cases, the result handle obtains 279 an intermediate status of "PGRES_COPY_IN" or "PGRES_COPY_OUT". The 280 programmer is then expected to use Tcl gets or read commands on the 281 database connection (not the result handle) to extract the copy data. 282 For copy outs, read until the standard EOF indication is encountered. 283 For copy ins, puts a single terminator (\.). The statement for this 284 would be 285 puts $conn "\\." or puts $conn {\.} 286 In either case (upon detecting the EOF or putting the `\.', the status 287 of the result handle will change to "PGRES_COMMAND_OK", and any further 288 I/O attempts will cause a Tcl error. 289----------------------------------------------------------------------------- 290