libpgtcl.sgml

关系型数据库 Postgresql 6.5.2

<VARLISTENTRY>
<TERM>
-numTuples
</TERM>
<LISTITEM>
<PARA>
the number of tuples returned by the query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-numAttrs
</TERM>
<LISTITEM>
<PARA>
the number of attributes in each tuple.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-assign arrayName
</TERM>
<LISTITEM>
<PARA>
assign the results to an array, using subscripts of the form
(tupno,attributeName).
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-assignbyidx arrayName ?appendstr?
</TERM>
<LISTITEM>
<PARA>
assign the results to an array using the first attribute's value and
the remaining attributes' names as keys.  If appendstr is given then
it is appended to each key.  In short, all but the first field of each
tuple are stored into the array, using subscripts of the form
(firstFieldValue,fieldNameAppendStr).
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-getTuple tupleNumber
</TERM>
<LISTITEM>
<PARA>
returns the fields of the indicated tuple in a list.  Tuple numbers
start at zero.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-tupleArray tupleNumber arrayName
</TERM>
<LISTITEM>
<PARA>
stores the fields of the tuple in array arrayName, indexed by field names.
Tuple numbers start at zero.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-attributes
</TERM>
<LISTITEM>
<PARA>
returns a list of the names of the tuple attributes.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-lAttributes
</TERM>
<LISTITEM>
<PARA>
returns a list of sublists, {name ftype fsize} for each tuple attribute.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-clear 
</TERM>
<LISTITEM>
<PARA>
clear the result query object.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT3>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGRESULT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>
The result depends on the selected option, as described above.
</PARA>
</REFSECT2></REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGRESULT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA>
<FUNCTION>pg_result</FUNCTION> returns information about a query result
created by a prior <FUNCTION>pg_exec</FUNCTION>.
</Para>

<para>
You can keep a query result around for as long as you need it, but when
you are done with it, be sure to free it by
executing <FUNCTION>pg_result -clear</FUNCTION>.  Otherwise, you have
a memory leak, and Pgtcl will eventually start complaining that you've
created too many query result objects.
</PARA>
</REFSECT1>
</REFENTRY>

<!-- ********************************************************** -->

<REFENTRY ID="PGTCL-PGSELECT">
<REFMETA>
<REFENTRYTITLE>pg_select</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_select
</REFNAME>
<REFPURPOSE>
loop over the result of a SELECT statement
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGSELECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGSELECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_select <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
  <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGSELECT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid SQL select query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Array variable for tuples returned.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Procedure run on each tuple found.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>

</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGSELECT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
   the return result is either an error message or a handle for a query result.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2></REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGSELECT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA>
<FUNCTION>pg_select</FUNCTION> submits a SELECT query to the
<ProductName>Postgres</ProductName> backend, and executes a
given chunk of code for each tuple in the result.
  The <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
  must be a SELECT statement.  Anything else returns an error.
  The <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE>
  variable is an array name used in the loop.  For each tuple,
  <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> is filled in
  with the tuple field values, using the field names as the array
  indexes.  Then the
  <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE>
  is executed.
</PARA>
</REFSECT1>

<REFSECT1 ID="R1-PGTCL-PGSELECT-2">
<TITLE>Usage
</TITLE>
<PARA>
This would work if table "table" has fields "control" and "name"
(and, perhaps, other fields):
<ProgramListing>
	pg_select $pgconn "SELECT * from table" array {
		puts [format "%5d %s" array(control) array(name)]
	}
</ProgramListing>
</PARA>
</REFSECT1>

</REFENTRY>

<!-- ********************************************************** -->

<REFENTRY ID="PGTCL-PGLISTEN">
<REFMETA>
<REFENTRYTITLE>pg_listen</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Asynchronous Notify</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_listen
</REFNAME>
<REFPURPOSE>sets or changes a callback for asynchronous NOTIFY messages
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLISTEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>notify</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLISTEN-2"><PRIMARY>notify</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-5-22</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_listen <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLISTEN-1">
<REFSECT2INFO>
<DATE>1998-5-22</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the notify condition name to start or stop listening to.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>If present and not empty, provides the command string to execute
when a matching notification arrives.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLISTEN-2">
<REFSECT2INFO>
<DATE>1998-5-22</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  None
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLISTEN-1">
<REFSECT1INFO>
<DATE>1998-5-22</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_listen</FUNCTION> creates, changes, or cancels a request
to listen for asynchronous NOTIFY messages from the
<ProductName>Postgres</ProductName> backend.  With a callbackCommand
parameter, the request is established, or the command string of an already
existing request is replaced.  With no callbackCommand parameter, a prior
request is canceled.
</PARA>

<para>
After a <FUNCTION>pg_listen</FUNCTION> request is established,
the specified command string is executed whenever a NOTIFY message bearing
the given name arrives from the backend.  This occurs when any
<ProductName>Postgres</ProductName> client application issues a NOTIFY command
referencing that name.  (Note that the name can be, but does not have to be,
that of an existing relation in the database.)
The command string is executed from the Tcl idle loop.  That is the normal
idle state of an application written with Tk.  In non-Tk Tcl shells, you can
execute <FUNCTION>update</FUNCTION> or <FUNCTION>vwait</FUNCTION> to cause
the idle loop to be entered.
</Para>

<para>
You should not invoke the SQL statements LISTEN or UNLISTEN directly when
using <FUNCTION>pg_listen</FUNCTION>.  Pgtcl takes care of issuing those
statements for you.  But if you want to send a NOTIFY message yourself,
invoke the SQL NOTIFY statement using <FUNCTION>pg_exec</FUNCTION>.
</PARA>
</REFSECT1>

</REFENTRY>

<!-- ********************************************************** -->

<REFENTRY ID="PGTCL-PGLOCREAT">
<REFMETA>
<REFENTRYTITLE>pg_lo_creat</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_creat
</REFNAME>
<REFPURPOSE>create a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOCREAT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>creating</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOCREAT-2"><PRIMARY>pg_lo_creat</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_creat <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOCREAT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the access mode for the large object</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOCREAT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The oid of the large object created.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOCREAT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_creat</FUNCTION> creates an Inversion Large Object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOCREAT-2">
<TITLE>Usage
</TITLE>
<PARA>
mode can be any OR'ing together of INV_READ, INV_WRITE, and INV_ARCHIVE. 
The OR delimiter character is "|".
<ProgramListing>
[pg_lo_creat $conn "INV_READ|INV_WRITE"]
</ProgramListing>
</PARA>
</REFSECT1>
</REFENTRY>

<!-- ********************************************************** -->

<REFENTRY ID="PGTCL-PGLOOPEN">
<REFMETA>
<REFENTRYTITLE>pg_lo_open</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_open
</REFNAME>
<REFPURPOSE>open a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOOPEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>opening</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOOPEN-2"><PRIMARY>pg_lo_open</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_open <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOOPEN-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid large object oid.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the access mode for the large object</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOOPEN-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A file descriptor for use in later pg_lo* routines.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOOPEN-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_open</FUNCTION> open an Inversion Large Object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOOPEN-2">
<TITLE>Usage
</TITLE>
<PARA>
Mode can be either "r", "w", or "rw".
</PARA>
</REFSECT1>
</REFENTRY>

<!-- ********************************************************** -->

<REFENTRY ID="PGTCL-PGLOCLOSE">
<REFMETA>
<REFENTRYTITLE>pg_lo_close</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_close
</REFNAME>
<REFPURPOSE>close a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOCLOSE-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>closing</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOCLOSE-2"><PRIMARY>pg_lo_close</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_close <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOCLOSE-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A file descriptor for use in later pg_lo* routines.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOCLOSE-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>None</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOCLOSE-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_close</FUNCTION> closes an Inversion Large Object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOCLOSE-2">
<TITLE>Usage
</TITLE>
<PARA>
</PARA>
</REFSECT1>
</REFENTRY>