201 lines
5.9 KiB
Plaintext
201 lines
5.9 KiB
Plaintext
|
|
pgtcl is a tcl package for front-end programs to interface with Postgres95
|
|
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
|
|
}
|
|
|