libpgtcl.doc

pgtcl is a tcl package for front-end programs to interface with PostgreSQL
backends.    PgTcl does not use the libpq library but communicates to
the backend directly via the frontend-backend protocol.  Thus, it is
more efficient than previous postgres->tcl bindings which are layered
on top of libpq.  In addition, pgtcl can handle multiple backend
connections from a single frontend application.

If you have any questions or bug reports, please send them to
Jolly Chen at jolly@cs.berkeley.edu.

-------------------------------------------------------------------


The pgtcl package provides the following commands. 

	pg_connect 	- opens a connection to the backend server
	pg_disconnect   - closes a connection
	pg_exec 	- send a query to the backend
	pg_select	- loop over the result of a select statement
	pg_result 	- manipulate the results of a query

	pg_lo_creat	- create a large object
	pg_lo_open	- open a large object
	pg_lo_close	- close a large object
	pg_lo_read	- read a large object
	pg_lo_write	- write a large object
	pg_lo_lseek	- seek to a position on a large object
	pg_lo_tell	- return the current seek position of a large object
	pg_lo_unlink	- delete a large object
	pg_lo_import	- import a Unix file into a large object
	pg_lo_export	- export a large object into a Unix file

1)  pg_connect:   opens a connection to the backend

   syntax:
        pg_connect dbName [-host hostName] [-port portNumber] [-tty pqtty] [-options optionalBackendArgs]]

   the return result is either an error message or a handle for a database
   connection.  Handles start with the prefix "pgp"


2)  pg_disconnect:	closes a connection

   syntax:
        pg_disconnect connection

   The argument passed in must be a connection pointer.

3)  pg_exec:		send a query string to the backend 

   syntax:
	pg_exec connection query

   the return result is either an error message or a handle for a query
   result.  Handles start with the prefix "pgp"

4)	pg_select:		loop over the result of a select statement

   syntax:
	pg_select connection query var proc

   The query must be a select statement.  Anything else returns an error.
   The var 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 indeces.  Proc is the procedure that is
   run for each tuple found.

   example: (DB is set to database name)
	set conn [pg_connect $DB]
	pg_select $conn "SELECT * from table" array {
		puts [format "%5d %s" array(control) array(name)]
	}
	pg_disconnect $conn

5)  pg_result:		get information about a query result

   syntax:
        pg_result result ?option? 
	       
    the options are:
         -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
	 -numTuples
	      the number of tuples in the query
	 -attributes
	      returns a list of the name/type pairs of the tuple attributes
	 -getTuple tupleNumber
	      returns the values of the tuple in a list
	 -clear 
	      clear the result buffer. Do not reuse after this

----------------------------------------------------------------------------
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.

The pg_lo* routines should typically be used within a BEGIN/END transaction
block becaus 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.

* pg_lo_creat:		create a large object

 syntax:
	g_lo_creat conn mode

mode can be any OR'ing together of INV_READ, INV_WRITE, and INV_ARCHIVE. 
The OR delimiter character is "|".
	e.g. [pg_lo_creat $conn "INV_READ|INV_WRITE"]

returns the oid of the large object created.

* pg_lo_open:		open a large object

 syntax:
	 pg_lo_open conn objOid mode 

 where mode can be either "r", "w", or "rw"

 returns a file descriptor for use in later pg_lo* routines

* pg_lo_close:		close a large object

 syntax:
	 pg_lo_close conn fd 

* pg_lo_read:		read a large object

 syntax:
	pg_lo_read conn fd bufVar len

reads at most len bytes from a large object into a variable named bufVar.
Note that the third argument should be a variable name.

* pg_lo_write:		write a large object

 syntax:
	pg_lo_write conn fd buf len

write at most len bytes to a large object.  
The third argument should be the actual string to write, not a variable name.

* pg_lo_lseek:		seek to a position on a large object

 syntax:
	pg_lo_lseek conn fd offset whence

whence can be "SEEK_CUR", "SEEK_END", or "SEEK_SET"

* pg_lo_tell:		return the current seek position of a large object

 syntax:
	pg_lo_tell conn fd

* pg_lo_unlink:		delete a large object 

 syntax:
	pg_lo_unlink conn lobjId

* pg_lo_import:		import a Unix file into a large object

 syntax:
	pg_lo_import conn filename

  pg_lo_import must be called within a BEGIN/END transaction block

* pg_lo_export:		export a large object into a Unix file
 
 syntax:
	pg_lo_export conn lobjId filename

  pg_lo_export must be called within a BEGIN/END transaction block

------------------------------------------------------------------
Here's a small example of how to use the routines:

# getDBs :
#   get the names of all the databases at a given host and port number
#   with the defaults being the localhost and port 5432
#   return them in alphabetical order
proc getDBs { {host "localhost"} {port "5432"} } {
    # datnames is the list to be result
    set conn [pg_connect template1 -host $host -port $port]
    set res [pg_exec $conn "SELECT datname FROM pg_database ORDER BY datname"]
    set ntups [pg_result $res -numTuples]
    for {set i 0} {$i < $ntups} {incr i} {
	lappend datnames [pg_result $res -getTuple $i]
    }
    pg_disconnect $conn
    return $datnames
}