README
1This is the pgtcl-ng Source Release README
2Last updated for pgtclng-2.1.1 on 2014-09-12
3The project home page is: http://sourceforge.net/projects/pgtclng/
4-----------------------------------------------------------------------------
5
6OVERVIEW:
7
8Pgtcl is the Tcl interface for the PostgreSQL Database Management System.
9It is a loadable Tcl module implementing commands which allow an
10application to interact with a PostgreSQL database. Pgtcl-ng is the "next
11generation" implementation of Pgtcl.
12
13This is a source release. With appropriate development tools on a compatible
14platform, you can build this on your system.
15
16The full documentation for pgtcl-ng is available at the site listed in the
17header of this file. This source release only contains the minimal
18documentation for building and installing.
19
20A binary release of pgtcl-ng for Windows is available on the site listed in
21the header of this file. If you are using pgtcl on Windows, you should
22consider using the binary release. For more information about the Windows
23binary release and its requirements, see the README.txt file inside the
24release.
25
26
27CONTENTS:
28
29 README ................... This file
30 COPYRIGHT ................ License file (Open Source)
31 INSTALL .................. Building and installing instructions
32 NEWS ..................... Release information and new features
33 ChangeLog* ............... Source change history files
34 README.historical ........ Historical READMEs from project predecessors
35 patches/ ................. Patches for building libpq on Windows (obsolete)
36 extra/ ................... Directory containing pgtclsh shell sources
37 Plus the source files and configure/build support files.
38
39
40REQUIREMENTS:
41
42Refer to the INSTALL file for details.
43
44This release has been successfully built on Linux with gcc-4.8.2,
45PostgreSQL-9.3.5 and 9.2.9, and Tcl-8.6.1. It was also successfully built
46on Ubuntu Linux with gcc-4.8.2, PostgreSQL libpq-9.3.5, and Tcl-8.5.15.
47
48It was tested against servers running PostgreSQL-9.3.5 and 9.2.9. It might
49build with other versions of PostgreSQL, and with older versions of Tcl,
50but these are not tested.
51
52This release has been successfully built on Windows XP-SP3 with the MinGW
53development system (gcc-4.8.1), EnterpriseDB PostgreSQL-9.3.4, and
54ActiveState ActiveTcl 8.6.1 and 8.5.15. The result has been tested against
55servers running PostgreSQL-9.3.5 and 9.2.9. The MinGW-built pgtcl-ng is
56available as a binary release for 32-bit Windows. It was built with Tcl8.5
57and uses the Tcl stubs mechanism, so the resulting DLL should work with
58different versions of Tcl.
59
60
61RELEASE ISSUES - all platforms:
62
63+ Refer to the NEWS file included in the release (and available on the
64 pgtclng web site) for important changes and compatibility issues in
65 this release and previous releases.
66
67+ If you are looking for the Tcl shells with PostgreSQL extensions (pgtclsh
68 and pgtksh), look in the "extra/" directory. The README file there explains
69 why you might be better off not using them, though.
70
71+ This release has not been built or tested on 64-bit systems.
72
73
74RELEASE ISSUES - Windows:
75
76+ Changes to the connection control environment variables (such as PGHOST,
77 PGDATABASE) are not seen once the DLL is loaded.
78
79+ Only TCP/IP is supported, not Unix Domain Sockets. So a hostname (or IP
80 address) must be provided when connecting. If you are trying to connect
81 to a PostgreSQL server running on your Windows PC, you need to specify
82 host=localhost or host=127.0.0.1 to connect to it.
83
README.historical
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