Resent-From: POSTGRES mailing list <postman@postgres.Berkeley.EDU>
Resent-Message-Id: <199407230312.UAA19586@nobozo.CS.Berkeley.EDU>
Sender: owner-postman@postgres.Berkeley.EDU
From: jimbo@crseo.ucsb.edu
Message-Id: <9407230312.AA01855@scorpii.s2k.ucsb.edu>
To: postgres@postgres.Berkeley.EDU
Subject: new Tcl interface to Postgres
Date: Fri, 22 Jul 94 20:12:17 -0700
Resent-To: postgres-redist@postgres.Berkeley.EDU
Resent-Date: Fri, 22 Jul 94 20:12:25 -0700
Resent-XMts: smtp


Hello,

After finally getting back to hacking on pgbrowse, I realized the Tcl
interface to Postgres I was using was a bit dated.  I wrote a new one
with many new features (see below).  You can get it in:

	ftp://ftp.crseo.ucsb.edu/pub/libpqtcl.tar.Z

The README file is attached below.  Try it out and let me know what you
think.

Cheers, -Jim

 __________________________________________________________
  Jim Davidson                     |  jimbo@crseo.ucsb.edu
  CSL / Center for Remote Sensing  |  jimbo@sbitp.bitnet
  University of California         |  Phone (805)893-8475
  Santa Barbara, CA 93106          |  Fax           -2578


Libpqtcl - Postgres libpq interface for Tcl


Jim Davidson
UCSB Center for Remote Sensing
jimbo@crseo.ucsb.edu
July 1994


o  What is it?

	Libpqtcl lets you access Postgres from within Tcl.


o  What's included?

	Source for the libpq interface commands and *AppInit's for
	tclpq and wishpqx interpreters.


o  What libpq functions does it support?

	All of them.


o  Does it support "copy <class> to/from stdout/stdin"?

	Yes.


o  Does it support asyncronous notifications?

	Yes.


o  Does it support Large Objects?

	Yes.


o  What kind of large objects?

	Just Unix for now (Inversion and External are a bit buggy anyway).


o  What does it run on?

	I did all my work on Alpha OSF/1 v2.0 and the latest Postgres
	v4.2.  It should port elsewhere but I haven't tried.


o  What do I need to compile it?

	Tcl7.3, Tk3.6, and TclX7.3.


o  How do I compile it?

	1.  Extract ftp://ftp.crseo.ucsb.edu/pub/libpqtcl.tar.Z somewhere.
	2.  Edit the Makefile as instructed
	3.  Type "make"


o  What if I can't get it to compile?

	Try harder, seek a guru's advice, or wait for me to produce
	pre-compiled binaries for Dec, Sun, RS6000, Alpha, and perhaps
	HP.

o  What if I just want to include libpqtcl in my own interpreter?

	1.  make libpqtcl.o
	2.  call (perhaps in your t*AppInit.c):
		if (TclPQ_Init(interp) == TCL_ERROR) {
			return TCL_ERROR;
		}
	3.  link with libpqtcl.o


o  Do you have any example scripts?

	Yes - there are some short ones in the examples/ directory.


o  What do I do if I find a bug or have a great idea?

	Send it to jimbo@crseo.ucsb.edu!


o  What's the complete list of Tcl commands in the interface:

	From the top of the libpqtcl.c file:

 *  The entire libpq interface for Postgres v4.2 is included.  The commands
 *  generally take the same arguements as the like-named C functions which
 *  they call (with the exception of C functions which take PortalBuffers -
 *  the Tcl commands take the portal name instead).
 *
 *
 *  PQerrormsg
 *	return PQerrormsg (without the trailing newlines)
 *
 *  PQdb ?db?
 *	set and/or return the current database
 *
 *  PQhost ?host?
 *	set and/or return the current host (calls PQfinish)
 *
 *  PQport ?port?
 *	set and/or return the current port (calls PQfinish)
 *
 *  PQfinish
 *	close the communication port with the backend
 *
 *  PQreset
 *	reset the communication port with the backend in case of error
 *
 *  PQexec query
 *	send a query to the backend, returing the result code
 *	for all but fatal 'E' errors in which case PQexec will
 *	call PqError (see below).
 *
 *  PQFlush i
 *	sync the backend (see the libpq documentation)
 *
 *  PQnportals
 *	return the number of open portals
 *
 *  PQpnames
 *	return a list of the open portal names
 *	
 *  PQclear portal
 *	free memory used by a portal 
 *
 *  PQntuples portal
 *	return the number of tuples in a portal
 *
 *  PQngroups portal
 *	return the number of groups in a portal
 *
 *  PQntuplesGroup portal group
 *	return the number of tuples in a group
 *
 *  PQnfieldsGroup portal group
 *	return the number of fields in a group
 *
 *  PQfnameGroup portal group field
 *	return the name for a field index in a group
 *
 *  PQfnumberGroup portal group fieldname
 *	return the index for a field name in a group
 *
 *  PQgetgroup portal tuple
 *	return the group which contains a tuple
 *
 *  PQnfields portal tuple
 *	return the number of fields in a tuple
 *
 *  PQfnumber portal tuple fieldname
 *	return the index for a field name in a tuple
 *
 *  PQfname portal tuple field
 *	return the name of a field in a tuple
 *
 *  PQftype portal tuple field
 *	return the type code for a field in a tuple
 *
 *  PQsametype portal tuple1 tuple2
 *	return 1 if all the fields in two tuples are the same
 *
 *  PQgetvalue portal tuple field
 *	return the value of a field in a tuple
 *
 *  PQgetlength portal tuple field
 *	return the length of a field in a tuple (not too useful in Tcl)
 *
 *  PQtrace ?fileid?
 *	start tracing, setting debug_port to the open fileid if given
 *
 *  PQuntrace
 *	stop tracing
 *
 *  PQAsyncNotifyWaiting ?0?
 *	return the PQAsyncNotifyWaiting value, perhaps setting it to 0 first
 *
 *  PQnotifies
 *	return the backend pid and relation in the next available PQNotifyList
 *
 *  PQputline
 *	send a line to the backend during a "copy <class> from stdin".  A
 *	newline will be added by PQputline and you need to send a single "."
 *	to signal the end of copying, at which point PQputline will call
 *	PQendcopy().
 *
 *  PQgetline
 *	return the next line from the backend during a "copy <class> to
 *	stdout".  PQgetline will call PQendcopy when it sees a single . but
 *	you must watch for this as well to signal the end of copying.
 *
 *  PQlo cmd ?arg arg ...?
 *	A large object major command.  PQlo can only create Unix large
 *	objects - Inversion and External types are too buggy.  The following
 *	minor commands, which generally work like their Unix file
 *	counterparts, are recognized:
 *
 *	glob ?--nocomplain? pattern
 *		returns a list of LO file names matching pattern.
 *
 *	pwd
 *	cd dir
 *		return or change the current LO working directory.
 *
 *	mkdir dir
 *	rmdir dir
 *		create or remove a LO directory
 *
 *	stat lofname var
 *		p_stat a LO, leaving the results in an array named var
 *
 *	isdirectory lofname
 *		return 1 if lofname is a LO directory
 *
 *	isfile lofname
 *		return 1 if lofname is a regular LO
 *
 *	unlink lofname
 *		remove a LO
 *
 *	rename lofname newlofname
 *		rename a LO
 *
 *	open lofname ?access?
 *		opens a new large object with the specified access, creating
 *		it if required.  Like the "open" Tcl command, access can be
 *		one of:  r, r+, w, w+, a, a+ or a list of the POSIX flags
 *		RDONLY, RDWR, WRONLY, CREAT, and/or TRUNC.  Access defaults
 *		to r, or RDONLY.
 *
 *	close loid
 *		closes an open loid
 *
 *	copyin fileid loid ?bytes?
 *	copyout loid fileid
 *		copy bytes (default=all) from (to) the open Unix fileid
 *		to (from) the open LO loid
 *
 *	seek loid offset
 *		set the current LO offset of the open loid.
 *
 *	tell loid
 *		return the current LO offset of the open loid.

==============================================================================
   To add/remove yourself to/from the POSTGRES mailing list: send mail with 
   the subject line ADD or DEL to "postgres-request@postgres.Berkeley.EDU"

   If this fails, send mail to "post_questions@postgres.Berkeley.EDU" and
   a human will deal with it.  DO NOT post to the "postgres" mailing list.
==============================================================================