Skip to content

P
Postgres FD Implementation
Commit a457d335 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Markup and spell-check run over Programmer's Guide (rather incomplete still).

parent 51ba1c5a
Expand all Show whitespace changes
Inline Side-by-side
Showing with 845 additions and 806 deletions
doc/src/sgml/arch-pg.sgml
View file @ a457d335
......@@ -66,7 +66,7 @@ From that point on, the frontend process and the backend
in mind,
because the files that can be accessed on a client
machine may not be accessible (or may only be accessed
using a different filename) on the database server
using a different file name) on the database server
machine.
You should also be aware that the <Application>postmaster</Application> and
postgres servers run with the user-id of the <ProductName>Postgres</ProductName>
......
doc/src/sgml/ecpg.sgml
View file @ a457d335
This diff is collapsed.
doc/src/sgml/extend.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.10 2001/05/17 21:50:15 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.11 2001/09/10 21:58:46 petere Exp $
-->
<chapter id="extend">
......@@ -236,7 +236,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.10 2001/05/17 21:50:15 pete
<note>
<para>
We use the words <firstterm>procedure</firstterm>
and <firstterm>function</firstterm> more or less interchangably.
and <firstterm>function</firstterm> more or less interchangeably.
</para>
</note>
......
doc/src/sgml/indexcost.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/indexcost.sgml,v 2.7 2001/05/09 23:13:34 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/indexcost.sgml,v 2.8 2001/09/10 21:58:46 petere Exp $
-->
<chapter id="indexcost">
......@@ -154,7 +154,7 @@ amcostestimate (Query *root,
<para>
The index access costs should be computed in the units used by
src/backend/optimizer/path/costsize.c: a sequential disk block fetch
<filename>src/backend/optimizer/path/costsize.c</filename>: a sequential disk block fetch
has cost 1.0, a nonsequential fetch has cost random_page_cost, and
the cost of processing one index tuple should usually be taken as
cpu_index_tuple_cost (which is a user-adjustable optimizer parameter).
......
doc/src/sgml/jdbc.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.21 2001/08/16 16:24:15 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/jdbc.sgml,v 1.22 2001/09/10 21:58:46 petere Exp $
-->
<chapter id="jdbc">
......@@ -514,7 +514,7 @@ mycon.setAutoCommit(false);
There are two methods of using Large Objects. The first is the
standard <acronym>JDBC</acronym> way, and is documented here. The
other, uses <productname>PostgreSQL</productname> extensions to
the <acronym>API</acronym>, which presents the libpq large object
the <acronym>API</acronym>, which presents the <application>libpq</application> large object
<acronym>API</acronym> to Java, providing even better access to
large objects than the standard. Internally, the driver uses the
extension to provide large object support.
......@@ -674,7 +674,7 @@ import org.postgresql.fastpath.*;
...
Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI();
</programlisting>
where myconn is an open Connection to <productname>PostgreSQL</productname>.
where <varname>myconn</> is an open <classname>Connection</> to <productname>PostgreSQL</productname>.
</para>
<formalpara>
......@@ -709,21 +709,21 @@ import org.postgresql.largeobject.*;
...
LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
</programlisting>
where myconn is an open Connection to
where <varname>myconn</> is an open <classname>Connection</> to
<productname>PostgreSQL</productname>.
</para>
<formalpara>
<title>Returns:</title>
<para>
LargeObject object that implements the <acronym>API</acronym>
<classname>LargeObject</classname> object that implements the <acronym>API</acronym>
</para>
</formalpara>
<formalpara>
<title>Throws:</title>
<para>
SQLException by LargeObject when initializing for first time
<classname>SQLException</classname> by <classname>LargeObject</classname> when initializing for first time
</para>
</formalpara>
</listitem>
......@@ -735,9 +735,9 @@ public void addDataType(String type, String name)
</synopsis>
This allows client code to add a handler for one of
PostgreSQL's more unique data types. Normally, a data type not
known by the driver is returned by ResultSet.getObject() as a
PGobject instance. This method allows you to write a class
that extends PGobject, and tell the driver the type name, and
known by the driver is returned by <literal>ResultSet.getObject()</literal> as a
<classname>PGobject</> instance. This method allows you to write a class
that extends <classname>PGobject</>, and tell the driver the type name, and
class name to use. The down side to this, is that you must
call this method each time a connection is made.
</para>
......@@ -749,7 +749,7 @@ public void addDataType(String type, String name)
((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name");
...
</programlisting>
where myconn is an open Connection to
where <varname>myconn</varname> is an open <classname>Connection</> to
<productname>PostgreSQL</productname>. The handling class must
extend <classname>org.postgresql.util.PGobject</classname>.
</para>
......@@ -772,7 +772,7 @@ java.lang.Object
<para>
<classname>Fastpath</classname> is an <acronym>API</acronym> that
exists within the libpq C interface, and allows a client machine
exists within the <application>libpq</application> C interface, and allows a client machine
to execute a function on the database backend. Most client code
will not need to use this method, but it is provided because the
Large Object <acronym>API</acronym> uses it.
......@@ -825,11 +825,11 @@ public Object fastpath(int fnid,
<formalpara>
<title>Parameters:</title>
<para>
fnid - Function id
resulttype - True if the result is an integer, false
<parameter>fnid</> - Function id
<parameter>resulttype</> - True if the result is an integer, false
for
other results
args - FastpathArguments to pass to fastpath
<parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
</para>
</formalpara>
......@@ -855,7 +855,7 @@ public Object fastpath(String name,
<note>
<para>
The mapping for the procedure name to function id needs to
exist, usually to an earlier call to addfunction(). This is
exist, usually to an earlier call to <function>addfunction()</function>. This is
the preferred method to call, as function id's can/may change
between versions of the backend. For an example of how this
works, refer to org.postgresql.LargeObject
......@@ -865,11 +865,11 @@ public Object fastpath(String name,
<formalpara>
<title>Parameters:</title>
<para>
name - Function name
resulttype - True if the result is an integer, false
<parameter>name</> - Function name
<parameter>resulttype</> - True if the result is an integer, false
for
other results
args - FastpathArguments to pass to fastpath
<parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
</para>
</formalpara>
......@@ -899,8 +899,8 @@ public int getInteger(String name,
<formalpara>
<title>Parameters:</title>
<para>
name - Function name
args - Function arguments
<parameter>name</parameter> - Function name
<parameter>args</parameter> - Function arguments
</para>
</formalpara>
......@@ -912,7 +912,7 @@ public int getInteger(String name,
<formalpara>
<title>Throws:</title>
<para>
SQLException if a database-access error occurs or no result
<classname>SQLException</classname> if a database-access error occurs or no result
</para>
</formalpara>
</listitem>
......@@ -930,8 +930,8 @@ public byte[] getData(String name,
<formalpara>
<title>Parameters:</title>
<para>
name - Function name
args - Function arguments
<parameter>name</parameter> - Function name
<parameter>args</parameter> - Function arguments
</para>
</formalpara>
......@@ -943,7 +943,7 @@ public byte[] getData(String name,
<formalpara>
<title>Throws:</title>
<para>
SQLException if a database-access error occurs or no result
<classname>SQLException</classname> if a database-access error occurs or no result
</para>
</formalpara>
</listitem>
......@@ -984,7 +984,7 @@ public void addFunctions(ResultSet rs) throws SQLException
<para>
PostgreSQL stores the function id's and their corresponding
names in the pg_proc table. To speed things up locally,
names in the <classname>pg_proc</> table. To speed things up locally,
instead of querying each function from that table when
required, a <classname>Hashtable</classname> is used. Also, only the function's
required are entered into this table, keeping connection
......@@ -1002,7 +1002,7 @@ public void addFunctions(ResultSet rs) throws SQLException
<para>
Do not think that manually converting them to the oid's will
work. Okay, they will for now, but they can change during
work. OK, they will for now, but they can change during
development (there was some discussion about this for V7.0),
so this is implemented to prevent any unwarranted headaches
in the future.
......@@ -1023,8 +1023,8 @@ public int getID(String name) throws SQLException
</synopsis>
<para>
This returns the function id associated by its name If
addFunction() or addFunctions() have not been called for this
name, then an SQLException is thrown.
<function>addFunction()</function> or <function>addFunctions()</function> have not been called for this
name, then an <classname>SQLException</classname> is thrown.
</para>
</listitem>
</itemizedlist>
......@@ -1112,21 +1112,21 @@ public FastpathArg(byte buf[],
<para>
<variablelist>
<varlistentry>
<term>buf</term>
<term><parameter>buf</></term>
<listitem>
<simpara>source array</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>off</term>
<term><parameter>off</parameter></term>
<listitem>
<simpara>offset within array</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>len</term>
<term><parameter>len</parameter></term>
<listitem>
<simpara>length of data to include</simpara>
</listitem>
......@@ -1880,7 +1880,7 @@ Methods
</para>
<para>
The org.postgresql.largeobject package provides to Java the libpq
The org.postgresql.largeobject package provides to Java the <application>libpq</application>
C interface's large object <acronym>API</acronym>. It consists of
two classes, <classname>LargeObjectManager</classname>, which deals with creating,
opening and deleting large objects, and <classname>LargeObject</classname> which deals
......
doc/src/sgml/libpgeasy.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.5 2001/04/20 15:52:33 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.6 2001/09/10 21:58:46 petere Exp $
-->
<chapter id="pgeasy-chapter">
<title id="pgeasy">libpgeasy - Simplified C Library</title>
<title id="pgeasy"><application>libpgeasy</application> - Simplified C Library</title>
<note>
<title>Author</title>
......@@ -23,74 +23,74 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.5 2001/04/20 15:52
<para>
It consists of set of simplified C functions that encapsulate the
functionality of libpq.
functionality of <application>libpq</application>.
The functions are:
<itemizedlist>
<listitem>
<para>
<synopsis>
PGresult *doquery(char *query);
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
PGconn *connectdb(char *options);
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
void disconnectdb();
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
int fetch(void *param,...);
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
int fetchwithnulls(void *param,...);
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
void reset_fetch();
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
void on_error_continue();
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
void on_error_stop();
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
PGresult *get_result();
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
void set_result(PGresult *newres);
</para>
</synopsis>
</listitem>
<listitem>
<para>
<synopsis>
void unset_result(PGresult *oldres);
</para>
</synopsis>
</listitem>
</itemizedlist>
</para>
......@@ -118,7 +118,7 @@ void unset_result(PGresult *oldres);
<function>fetchwithnulls</function> allows you to retrieve the NULL
status of the field by passing an <literal>int*</literal>
after each result pointer, which returns true or false if the field is null.
You can always use libpq functions on the PGresult pointer returned
You can always use <application>libpq</application> functions on the <structname>PGresult</structname> pointer returned
by <function>doquery</function>.
<function>reset_fetch</function> starts the fetch back at the beginning.
</para>
......
doc/src/sgml/libpgtcl.sgml
View file @ a457d335
This diff is collapsed.
doc/src/sgml/libpq++.sgml
View file @ a457d335
This diff is collapsed.
doc/src/sgml/libpq.sgml
View file @ a457d335
This diff is collapsed.
doc/src/sgml/lobj.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.18 2001/09/10 04:15:41 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.19 2001/09/10 21:58:47 petere Exp $
-->
<chapter id="largeObjects">
......@@ -40,7 +40,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.18 2001/09/10 04:15:41 momjia
objects interchangeably to mean the same thing in this
section.)
Since <productname>PostgreSQL 7.1</productname> all large objects are placed in
one system table called pg_largeobject.
one system table called <classname>pg_largeobject</classname>.
</para>
</sect1>
......@@ -87,9 +87,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.18 2001/09/10 04:15:41 momjia
<function>lseek(2)</function>, etc. User
functions call these routines to retrieve only the data of
interest from a large object. For example, if a large
object type called mugshot existed that stored
object type called <type>mugshot</type> existed that stored
photographs of faces, then a function called beard could
be declared on mugshot data. Beard could look at the
be declared on <type>mugshot</type> data. Beard could look at the
lower third of a photograph, and determine the color of
the beard that appeared there, if any. The entire
large object value need not be buffered, or even
......@@ -110,13 +110,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.18 2001/09/10 04:15:41 momjia
Oid lo_creat(PGconn *<replaceable class="parameter">conn</replaceable>, int <replaceable class="parameter">mode</replaceable>)
</synopsis>
creates a new large object.
<replaceable class="parameter">mode</replaceable> is a bitmask
<replaceable class="parameter">mode</replaceable> is a bit mask
describing several different attributes of the new
object. The symbolic constants listed here are defined
in
<filename>$<envar>PGROOT</envar>/src/backend/libpq/libpq-fs.h</filename>
The access type (read, write, or both) is controlled by
OR ing together the bits <acronym>INV_READ</acronym> and
OR'ing together the bits <acronym>INV_READ</acronym> and
<acronym>INV_WRITE</acronym>. The low-order sixteen bits of mask are
the storage manager number on which the large object
should reside. For sites other than Berkeley, these
......@@ -137,7 +137,7 @@ inv_oid = lo_creat(INV_READ|INV_WRITE);
Oid lo_import(PGconn *<replaceable class="parameter">conn</replaceable>, const char *<replaceable class="parameter">filename</replaceable>)
</synopsis>
<replaceable class="parameter">filename</replaceable>
specifies the <acronym>Unix</acronym> pathname of
specifies the <acronym>Unix</acronym> path name of
the file to be imported as a large object.
</para>
</sect2>
......@@ -151,9 +151,9 @@ Oid lo_import(PGconn *<replaceable class="parameter">conn</replaceable>, const c
<synopsis>
int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <replaceable class="parameter">lobjId</replaceable>, const char *<replaceable class="parameter">filename</replaceable>)
</synopsis>
The lobjId argument specifies the Oid of the large
object to export and the filename argument specifies
the <acronym>UNIX</acronym> pathname of the file.
The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to export and the <parameter>filename</parameter> argument specifies
the <acronym>UNIX</acronym> path name of the file.
</para>
</sect2>
......@@ -165,9 +165,9 @@ int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <re
<synopsis>
int lo_open(PGconn *conn, Oid lobjId, int mode)
</synopsis>
The lobjId argument specifies the Oid of the large
object to open. The mode bits control whether the
object is opened for reading INV_READ), writing or
The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to open. The <parameter>mode</parameter> bits control whether the
object is opened for reading (<symbol>INV_READ</>), writing or
both.
A large object cannot be opened before it is created.
<function>lo_open</function> returns a large object descriptor
......@@ -185,7 +185,7 @@ int lo_open(PGconn *conn, Oid lobjId, int mode)
<programlisting>
int lo_write(PGconn *conn, int fd, const char *buf, size_t len)
</programlisting>
writes len bytes from buf to large object fd. The fd
writes <parameter>len</parameter> bytes from <parameter>buf</parameter> to large object <parameter>fd</>. The <parameter>fd</parameter>
argument must have been returned by a previous <function>lo_open</function>.
The number of bytes actually written is returned. In
the event of an error, the return value is negative.
......@@ -200,7 +200,7 @@ int lo_write(PGconn *conn, int fd, const char *buf, size_t len)
<programlisting>
int lo_read(PGconn *conn, int fd, char *buf, size_t len)
</programlisting>
reads len bytes from large object fd into buf. The fd
reads <parameter>len</parameter> bytes from large object <parameter>fd</parameter> into <parameter>buf</parameter>. The <parameter>fd</parameter>
argument must have been returned by a previous <function>lo_open</function>.
The number of bytes actually read is returned. In
the event of an error, the return value is negative.
......@@ -245,7 +245,7 @@ int lo_close(PGconn *conn, int fd)
<synopsis>
Oid lo_unlink(PGconn *<replaceable class="parameter">conn</replaceable>, Oid lobjId)
</synopsis>
The lobjId argument specifies the Oid of the large
The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to remove.
</para>
</sect2>
......@@ -278,20 +278,20 @@ SELECT lo_export(image.raster, '/tmp/motd') from image
</sect1>
<sect1 id="lo-libpq">
<title>Accessing Large Objects from LIBPQ</title>
<title>Accessing Large Objects from <application>Libpq</application></title>
<para>
Below is a sample program which shows how the large object
interface
in LIBPQ can be used. Parts of the program are
in <application>libpq</> can be used. Parts of the program are
commented out but are left in the source for the readers
benefit. This program can be found in
<filename>
../src/test/examples
</filename>
Frontend applications which use the large object interface
in LIBPQ should include the header file
libpq/libpq-fs.h and link with the libpq library.
in <application>libpq</application> should include the header file
<filename>libpq/libpq-fs.h</filename> and link with the <application>libpq</application> library.
</para>
</sect1>
......
doc/src/sgml/odbc.sgml
View file @ a457d335
This diff is collapsed.
doc/src/sgml/plperl.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.9 2001/06/22 21:37:14 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.10 2001/09/10 21:58:47 petere Exp $
-->
<chapter id="plperl">
......@@ -21,10 +21,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.9 2001/06/22 21:37:14 momji
<para>
The PL/Perl interpreter (when installed as trusted interpreter with
default name 'plperl') intepreter is a full Perl interpreter. However, certain
default name <literal>plperl</>) interpreter is a full Perl interpreter. However, certain
operations have been disabled in order to maintain the security of
the system. In general, the operations that are restricted are
those that interact with the environment. This includes filehandle
those that interact with the environment. This includes file handle
operations, <literal>require</literal>, and <literal>use</literal>
(for external modules). It should be noted that this security is
not absolute. Indeed, several Denial-of-Service attacks are still
......@@ -32,8 +32,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.9 2001/06/22 21:37:14 momji
</para>
<para>
When PL/Perl is installed as 'untrusted' interpreter (with name 'plperlu'),
everything is permitted, and any perl code can be loaded (by superuser only).
When PL/Perl is installed as <quote>untrusted</> interpreter (with name <literal>plperlu</literal>),
everything is permitted, and any Perl code can be loaded (by superuser only).
</para>
<sect1 id="plperl-install">
......@@ -170,13 +170,13 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
The creation of the function will succeed, but executing it will not.
Note that if same function was created by superuser using language
'plperlu', execution would succeed.
<literal>plperlu</>, execution would succeed.
</para>
<para>
Access to database itself from your perl function can be done via
an experimental module DBD::PgSPI, available at <ulink url="http://www.formenos.org/PgSPI/">this site</ulink>. This module makes available a DBI-compliant
database-handle named $pg_dbh, and you can use that to make queries with
normal DBI syntax.
Access to database itself from your Perl function can be done via
an experimental module <ulink url="http://www.formenos.org/PgSPI/"><literal>DBD::PgSPI</literal></ulink>. This module makes available a <acronym>DBI</>-compliant
database-handle named <varname>$pg_dbh</varname>, and you can use that to make queries with
normal <acronym>DBI</> syntax.
</para>
</sect1>
......
doc/src/sgml/plpython.sgml
View file @ a457d335
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.1 2001/05/12 17:49:32 petere Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.2 2001/09/10 21:58:47 petere Exp $ -->
<chapter id="plpython">
<title>PL/Python - Python Procedural Language</title>
......@@ -49,9 +49,9 @@ def __plpython_procedure_myfunc_23456():
<para>
PostgreSQL function variables are available in the global
<varname>args</varname> list. In the <function>myfunc</function>
example, args[0] contains whatever was passed in as the text
argument. For <literal>myfunc2(text, int4)</literal>, args[0]
would contain the text variable and args[1] the int4 variable.
example, <varname>args[0]</> contains whatever was passed in as the text
argument. For <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
would contain the <type>text</type> variable and <varname>args[1]</varname> the <type>integer</type> variable.
</para>
<para>
......@@ -59,12 +59,12 @@ def __plpython_procedure_myfunc_23456():
function calls. This variable is private static data. The global
dictionary GD is public data, available to all python functions
within a backend. Use with care. When the function is used in a
trigger, the triggers tuples are in TD["new"] and/or TD["old"]
trigger, the triggers tuples are in <literal>TD["new"]</literal> and/or <literal>TD["old"]</literal>
depending on the trigger event. Return 'None' or "OK" from the
python function to indicate the tuple is unmodified, "SKIP" to
abort the event, or "MODIFIED" to indicate you've modified the
tuple. If the trigger was called with arguments they are available
in TD["args"][0] to TD["args"][(n -1)]
in <literal>TD["args"][0] to TD["args"][(n -1)]</literal>.
</para>
<para>
......@@ -98,7 +98,7 @@ def __plpython_procedure_myfunc_23456():
</para>
<para>
Additionally, the plpy module provides two functions called
Additionally, the <literal>plpy</literal> module provides two functions called
<function>execute</function> and <function>prepare</function>.
Calling <function>plpy.execute</function> with a query string, and
an optional limit argument, causes that query to be run, and the
......
doc/src/sgml/plsql.sgml
View file @ a457d335
This diff is collapsed.
doc/src/sgml/pltcl.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.12 2001/08/02 15:45:55 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.13 2001/09/10 21:58:47 petere Exp $
-->
<chapter id="pltcl">
<title>PL/Tcl - TCL Procedural Language</title>
<title>PL/Tcl - Tcl Procedural Language</title>
<indexterm zone="pltcl">
<primary>PL/Tcl</primary>
......@@ -37,7 +37,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.12 2001/08/02 15:45:55 momji
The good restriction is that everything is executed in a safe
Tcl interpreter. In addition to the limited command set of safe Tcl, only
a few commands are available to access the database via SPI and to raise
messages via elog(). There is no way to access internals of the
messages via <function>elog()</>. There is no way to access internals of the
database backend or to gain OS-level access under the permissions of the
<productname>Postgres</productname> user ID, as a C function can do.
Thus, any unprivileged database user may be
......@@ -157,7 +157,7 @@ CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
</para>
<para>
To help protect PL/Tcl procedures from unwanted side effects,
an array is made available to each procedure via the upvar
an array is made available to each procedure via the <function>upvar</>
command. The global name of this variable is the procedure's internal
name and the local name is GD. It is recommended that GD be used
for private status data of a procedure. Use regular Tcl global variables
......@@ -210,7 +210,7 @@ CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
<listitem>
<para>
A Tcl list of the tables field names prefixed with an empty list element.
So looking up an element name in the list with the lsearch Tcl command
So looking up an element name in the list with the <function>lsearch</> Tcl command
returns the same positive number starting from 1 as the fields are numbered
in the pg_attribute system catalog.
</para>
......@@ -344,7 +344,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
<indexterm>
<primary>elog</primary>
</indexterm>
<term>elog <replaceable>level</replaceable> <replaceable>msg</replaceable></term>
<term><function>elog</> <replaceable>level</replaceable> <replaceable>msg</replaceable></term>
<listitem>
<para>
Fire a log message. Possible levels are NOTICE, ERROR,
......@@ -355,7 +355,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
</varlistentry>
<varlistentry>
<term>quote <replaceable>string</replaceable></term>
<term><function>quote</> <replaceable>string</replaceable></term>
<listitem>
<para>
Duplicates all occurrences of single quote and backslash characters.
......@@ -398,7 +398,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
<indexterm>
<primary>spi_lastoid</primary>
</indexterm>
<term>spi_lastoid</term>
<term><function>spi_lastoid</></term>
<listitem>
<para>
Returns the OID of the last query if it was an INSERT.
......@@ -407,7 +407,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
</varlistentry>
<varlistentry>
<term>spi_exec ?-count <replaceable>n</replaceable>? ?-array <replaceable>name</replaceable>? <replaceable>query</replaceable> ?<replaceable>loop-body</replaceable>?</term>
<term><function>spi_exec</function> <literal>?-count <replaceable>n</replaceable>? ?-array <replaceable>name</replaceable>? <replaceable>query</replaceable> ?<replaceable>loop-body</replaceable>?</literal></term>
<listitem>
<para>
Call parser/planner/optimizer/executor for query.
......@@ -446,45 +446,45 @@ spi_exec -array C "SELECT * FROM pg_class" {
</varlistentry>
<varlistentry>
<term>spi_prepare <replaceable>query</replaceable> <replaceable>typelist</replaceable></term>
<term><function>spi_prepare</function> <replaceable>query</replaceable> <replaceable>typelist</replaceable></term>
<listitem>
<para>
Prepares AND SAVES a query plan for later execution. It is a bit different
from the C level SPI_prepare in that the plan is automatically copied to the
toplevel memory context. Thus, there is currently no way of preparing a
top-level memory context. Thus, there is currently no way of preparing a
plan without saving it.
</para>
<para>
If the query references arguments, the type names must be given as a Tcl
list. The return value from spi_prepare is a query ID to be used in
subsequent calls to spi_execp. See spi_execp for a sample.
list. The return value from <function>spi_prepare</function> is a query ID to be used in
subsequent calls to <function>spi_execp</function>. See <function>spi_execp</function> for a sample.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>spi_exec ?-count <replaceable>n</replaceable>? ?-array<replaceable>name</replaceable>? ?-nulls<replaceable>string</replaceable>? <replaceable>queryid</replaceable> ?<replaceable>value-list</replaceable>? ?<replaceable>loop-body</replaceable>?</term>
<term><function>spi_exec</> <literal>?-count <replaceable>n</replaceable>? ?-array<replaceable>name</replaceable>? ?-nulls<replaceable>string</replaceable>? <replaceable>queryid</replaceable> ?<replaceable>value-list</replaceable>? ?<replaceable>loop-body</replaceable>?</literal></term>
<listitem>
<para>
Execute a prepared plan from spi_prepare with variable substitution.
The optional -count value tells spi_execp the maximum number of rows
Execute a prepared plan from <function>spi_prepare</> with variable substitution.
The optional <literal>-count</literal> value tells <function>spi_execp</> the maximum number of rows
to be processed by the query.
</para>
<para>
The optional value for -nulls is a string of spaces and 'n' characters
telling spi_execp which of the values are NULL's. If given, it must
The optional value for <literal>-nulls</> is a string of spaces and 'n' characters
telling <function>spi_execp</function> which of the values are NULL's. If given, it must
have exactly the length of the number of values.
</para>
<para>
The queryid is the ID returned by the spi_prepare call.
The <parameter>queryid</> is the ID returned by the <function>spi_prepare</function> call.
</para>
<para>
If there was a typelist given to spi_prepare, a Tcl list of values of
If there was a <parameter>typelist</> given to <function>spi_prepare</function>, a Tcl list of values of
exactly the same length must be given to spi_execp after the query. If
the type list on spi_prepare was empty, this argument must be omitted.
</para>
<para>
If the query is a SELECT statement, the same as described for spi_exec
If the query is a SELECT statement, the same as described for <function>spi_exec</>
happens for the loop-body and the variables for the fields selected.
</para>
<para>
......@@ -506,7 +506,7 @@ CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
Note that each backslash that Tcl should see must be doubled in
the query creating the function, since the main parser processes
backslashes too on CREATE FUNCTION.
Inside the query string given to spi_prepare should
Inside the query string given to <function>spi_prepare</> should
really be dollar signs to mark the parameter positions and to not let
$1 be substituted by the value given in the first function call.
</para>
......@@ -515,18 +515,20 @@ CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
<varlistentry>
<term>
Modules and the unknown command
Modules and the <function>unknown</> command
</term>
<listitem>
<para>
PL/Tcl has a special support for things often used. It recognizes two
magic tables, pltcl_modules and pltcl_modfuncs.
If these exist, the module 'unknown' is loaded into the interpreter
right after creation. Whenever an unknown Tcl procedure is called,
the unknown proc is asked to check if the procedure is defined in one
of the modules. If this is true, the module is loaded on demand.
To enable this behavior, the PL/Tcl call handler must be compiled
with -DPLTCL_UNKNOWN_SUPPORT set.
PL/Tcl has a special support for things often used. It
recognizes two magic tables, <literal>pltcl_modules</> and
<literal>pltcl_modfuncs</>. If these exist, the module
'unknown' is loaded into the interpreter right after
creation. Whenever an unknown Tcl procedure is called, the
unknown proc is asked to check if the procedure is defined in
one of the modules. If this is true, the module is loaded on
demand. To enable this behavior, the
<productname>PostgreSQL</> must be configured with the option
<option>--enable-pltcl-unknown</option>.
</para>
<para>
There are support scripts to maintain these tables in the modules
......
doc/src/sgml/rules.sgml
View file @ a457d335
This diff is collapsed.
doc/src/sgml/xaggr.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.12 2001/05/12 22:51:36 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.13 2001/09/10 21:58:47 petere Exp $
-->
<chapter id="xaggr">
......@@ -17,7 +17,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.12 2001/05/12 22:51:36 peter
That is, an aggregate can be
defined in terms of state that is modified whenever an
input item is processed. To define a new aggregate
function, one selects a datatype for the state value,
function, one selects a data type for the state value,
an initial value for the state, and a state transition
function. The state transition function is just an
ordinary function that could also be used outside the
......@@ -28,8 +28,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.12 2001/05/12 22:51:36 peter
</para>
<para>
Thus, in addition to the input and result datatypes seen by a user
of the aggregate, there is an internal state-value datatype that
Thus, in addition to the input and result data types seen by a user
of the aggregate, there is an internal state-value data type that
may be different from both the input and result types.
</para>
......@@ -40,8 +40,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.12 2001/05/12 22:51:36 peter
example of this kind of aggregate. "Sum" starts at
zero and always adds the current row's value to
its running total. For example, if we want to make a Sum
aggregate to work on a datatype for complex numbers,
we only need the addition function for that datatype.
aggregate to work on a data type for complex numbers,
we only need the addition function for that data type.
The aggregate definition is:
<programlisting>
......@@ -71,8 +71,8 @@ SELECT complex_sum(a) FROM test_complex;
state condition) if there are no non-null input values.
Perhaps we want to return NULL in that case instead --- SQL92
expects "Sum" to behave that way. We can do this simply by
omitting the "initcond" phrase, so that the initial state
condition is NULL. Ordinarily this would mean that the sfunc
omitting the <literal>initcond</literal> phrase, so that the initial state
condition is NULL. Ordinarily this would mean that the <literal>sfunc</literal>
would need to check for a NULL state-condition input, but for
"Sum" and some other simple aggregates like "Max" and "Min",
it's sufficient to insert the first non-null input value into
......
doc/src/sgml/xfunc.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.34 2001/09/06 10:28:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.35 2001/09/10 21:58:47 petere Exp $
-->
<chapter id="xfunc">
......@@ -1427,7 +1427,7 @@ LANGUAGE 'c';
in the <literal>prosrc</literal> attribute of the
<classname>pg_proc</classname> table entry. This may be the source
text in the procedural language itself (like for PL/Tcl), a
pathname to a file, or anything else that tells the call handler
path name to a file, or anything else that tells the call handler
what to do in detail.
</para>
......
doc/src/sgml/xindex.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.17 2001/08/31 04:17:13 ishii Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.18 2001/09/10 21:58:47 petere Exp $
Postgres documentation
-->
......@@ -70,7 +70,7 @@ Postgres documentation
</row>
<row>
<entry>amcanmulticol</entry>
<entry>does AM support multi-column indexes?</entry>
<entry>does AM support multicolumn indexes?</entry>
</row>
<row>
<entry>amindexnulls</entry>
......@@ -288,7 +288,7 @@ SELECT oid, *
<para>
The above example assumes that you want to make this new opclass the
default B-tree opclass for the <filename>complex</filename> datatype.
default B-tree opclass for the <filename>complex</filename> data type.
If you don't, just set <filename>opcdefault</filename> to false instead.
<filename>opckeytype</filename> is not described here; it should always
be zero for B-tree opclasses.
......@@ -354,24 +354,24 @@ CREATE FUNCTION complex_abs_eq(complex, complex)
are being defined. We can only have one operator named, say, = and
taking type <filename>complex</filename> for both operands. In this case
we don't have any other operator = for <filename>complex</filename>,
but if we were building a practical datatype we'd probably want = to
but if we were building a practical data type we'd probably want = to
be the ordinary equality operation for complex numbers. In that case,
we'd need to use some other operator name for complex_abs_eq.
</para>
<para>
Second, although Postgres can cope with operators having
the same name as long as they have different input datatypes, C can only
the same name as long as they have different input data types, C can only
cope with one global routine having a given name, period. So we shouldn't
name the C function something simple like <filename>abs_eq</filename>.
Usually it's a good practice to include the datatype name in the C
function name, so as not to conflict with functions for other datatypes.
Usually it's a good practice to include the data type name in the C
function name, so as not to conflict with functions for other data types.
</para>
<para>
Third, we could have made the Postgres name of the function
<filename>abs_eq</filename>, relying on Postgres to distinguish it
by input datatypes from any other Postgres function of the same name.
by input data types from any other Postgres function of the same name.
To keep the example simple, we make the function have the same names
at the C level and Postgres level.
</para>
......
doc/src/sgml/xoper.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xoper.sgml,v 1.12 2001/05/07 00:43:14 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xoper.sgml,v 1.13 2001/09/10 21:58:47 petere Exp $
-->
<Chapter Id="xoper">
......@@ -113,7 +113,7 @@ SELECT (a + b) AS c FROM test_complex;
commutator of the operator being defined. We say that operator A is the
commutator of operator B if (x A y) equals (y B x) for all possible input
values x,y. Notice that B is also the commutator of A. For example,
operators '<' and '>' for a particular datatype are usually each others'
operators '<' and '>' for a particular data type are usually each others'
commutators, and operator '+' is usually commutative with itself.
But operator '-' is usually not commutative with anything.
</para>
......@@ -176,7 +176,7 @@ SELECT (a + b) AS c FROM test_complex;
is the negator of operator B if both return boolean results and
(x A y) equals NOT (x B y) for all possible inputs x,y.
Notice that B is also the negator of A.
For example, '<' and '>=' are a negator pair for most datatypes.
For example, '<' and '>=' are a negator pair for most data types.
An operator can never be validly be its own negator.
</para>
......@@ -260,11 +260,11 @@ SELECT (a + b) AS c FROM test_complex;
</para>
<para>
You can use scalarltsel and scalargtsel for comparisons on datatypes that
You can use scalarltsel and scalargtsel for comparisons on data types that
have some sensible means of being converted into numeric scalars for
range comparisons. If possible, add the datatype to those understood
by the routine convert_to_scalar() in src/backend/utils/adt/selfuncs.c.
(Eventually, this routine should be replaced by per-datatype functions
range comparisons. If possible, add the data type to those understood
by the routine convert_to_scalar() in <filename>src/backend/utils/adt/selfuncs.c</filename>.
(Eventually, this routine should be replaced by per-data-type functions
identified through a column of the pg_type table; but that hasn't happened
yet.) If you do not do this, things will still work, but the optimizer's
estimates won't be as good as they could be.
......@@ -272,7 +272,7 @@ SELECT (a + b) AS c FROM test_complex;
<para>
There are additional selectivity functions designed for geometric
operators in src/backend/utils/adt/geo_selfuncs.c: areasel, positionsel,
operators in <filename>src/backend/utils/adt/geo_selfuncs.c</filename>: areasel, positionsel,
and contsel. At this writing these are just stubs, but you may want
to use them (or even better, improve them) anyway.
</para>
......@@ -351,12 +351,12 @@ SELECT (a + b) AS c FROM test_complex;
<para>
There are also machine-dependent ways in which a hash join might fail
to do the right thing. For example, if your datatype
to do the right thing. For example, if your data type
is a structure in which there may be uninteresting pad bits, it's unsafe
to mark the equality operator HASHES. (Unless, perhaps, you write
your other operators to ensure that the unused bits are always zero.)
Another example is that the FLOAT datatypes are unsafe for hash
joins. On machines that meet the IEEE floating point standard, minus
Another example is that the FLOAT data types are unsafe for hash
joins. On machines that meet the <acronym>IEEE</> floating point standard, minus
zero and plus zero are different values (different bit patterns) but
they are defined to compare equal. So, if float equality were marked
HASHES, a minus zero and a plus zero would probably not be matched up
......@@ -365,7 +365,7 @@ SELECT (a + b) AS c FROM test_complex;
<para>
The bottom line is that you should probably only use HASHES for
equality operators that are (or could be) implemented by memcmp().
equality operators that are (or could be) implemented by <function>memcmp()</function>.
</para>
</sect2>
......@@ -393,16 +393,16 @@ SELECT (a + b) AS c FROM test_complex;
it is possible to mergejoin two
distinct data types so long as they are logically compatible. For
example, the int2-versus-int4 equality operator is mergejoinable.
We only need sorting operators that will bring both datatypes into a
We only need sorting operators that will bring both data types into a
logically compatible sequence.
</para>
<para>
When specifying merge sort operators, the current operator and both
referenced operators must return boolean; the SORT1 operator must have
both input datatypes equal to the current operator's left argument type,
both input data types equal to the current operator's left argument type,
and the SORT2 operator must have
both input datatypes equal to the current operator's right argument type.
both input data types equal to the current operator's right argument type.
(As with COMMUTATOR and NEGATOR, this means that the operator name is
sufficient to specify the operator, and the system is able to make dummy
operator entries if you happen to define the equality operator before
......@@ -434,7 +434,7 @@ SELECT (a + b) AS c FROM test_complex;
<listitem>
<para>
There must be '<' and '>' ordering operators having the same left and
right input datatypes as the mergejoinable operator itself. These
right input data types as the mergejoinable operator itself. These
operators <emphasis>must</emphasis> be named '<' and '>'; you do
not have any choice in the matter, since there is no provision for
specifying them explicitly. Note that if the left and right data types
......
doc/src/sgml/xplang.sgml
View file @ a457d335
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.14 2001/08/13 21:34:51 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.15 2001/09/10 21:58:47 petere Exp $
-->
<chapter id="xplang">
......@@ -44,7 +44,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.14 2001/08/13 21:34:51 pete
<para>
For the languages supplied with the standard distribution, the
shell script <filename>createlang</filename> may be used instead
of carrying out the details by hand. For example, to install PL/pgSQL
of carrying out the details by hand. For example, to install <application>PL/pgSQL</application>
into the template1 database, use
<programlisting>
createlang plpgsql template1
......@@ -102,8 +102,8 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
executed inside the database backend, the <acronym>TRUSTED</acronym>
flag should only be given for
languages that do not allow access to database backends
internals or the filesystem. The languages PL/pgSQL,
PL/Tcl, and PL/Perl are known to be trusted; the language PL/TclU
internals or the file system. The languages <application>PL/pgSQL</application>,
<application>PL/Tcl</application>, and <application>PL/Perl</application> are known to be trusted; the language <application>PL/TclU</application>
should <emphasis>not</emphasis> be marked trusted.
</para>
</step>
......@@ -111,7 +111,7 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
<para>
In a default <productname>Postgres</productname> installation, the
handler for the PL/pgSQL language is built and installed into the
handler for the <application>PL/pgSQL</application> language is built and installed into the
<quote>library</quote> directory. If Tcl/Tk support is configured
in, the handlers for PL/Tcl and PL/TclU are also built and installed in
the same location. Likewise, the PL/Perl handler is built and installed
......@@ -125,7 +125,7 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
<step performance="required">
<para>
The following command tells the database where to find the
shared object for the PL/pgSQL language's call handler function.
shared object for the <application>PL/pgSQL</application> language's call handler function.
<programlisting>
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
......@@ -143,7 +143,7 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql
</programlisting>
then defines that the previously declared call handler function
should be invoked for functions and trigger procedures where the
language attribute is 'plpgsql'.
language attribute is <literal>plpgsql</literal>.
</para>
</step>
</procedure>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment