diff options
Diffstat (limited to 'doc/libpgtcl.doc')
| -rw-r--r-- | doc/libpgtcl.doc | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/doc/libpgtcl.doc b/doc/libpgtcl.doc new file mode 100644 index 00000000000..3ee5c6dfc09 --- /dev/null +++ b/doc/libpgtcl.doc @@ -0,0 +1,181 @@ + +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_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_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 +} + |