database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-07 11:02:12 +03:00
Code

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

Browse Source
This commit is contained in:
Peter Eisentraut 2001-09-10 21:58:47 +00:00
parent 51ba1c5a8c
commit a457d33516
21 changed files with 845 additions and 806 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
doc/src/sgml/ecpg.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.21 2001/09/06 00:23:42 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.22 2001/09/10 21:58:46 petere Exp $
--> -->
<chapter id="ecpg"> <chapter id="ecpg">
@ -195,7 +195,7 @@ struct sqlca
</para> </para>
<para> <para>
If an error occured in the last <acronym>SQL</acronym> statement. If an error occurred in the last <acronym>SQL</acronym> statement.
<parameter>sqlca.sqlcode</parameter> will be non-zero. If <parameter>sqlca.sqlcode</parameter> will be non-zero. If
<parameter>sqlca.sqlcode</parameter> is less that 0, this is a <parameter>sqlca.sqlcode</parameter> is less that 0, this is a
serious error, like the database definition does not match the serious error, like the database definition does not match the
@ -214,7 +214,7 @@ struct sqlca
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>-12, Out of memory in line %d.</term> <term><computeroutput>-12, Out of memory in line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
Should not normally occur. This indicates your virtual memory is Should not normally occur. This indicates your virtual memory is
@ -224,7 +224,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-200, Unsupported type %s on line %d.</term> <term><computeroutput>-200, Unsupported type %s on line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
Should not normally occur. This indicates the preprocessor has Should not normally occur. This indicates the preprocessor has
@ -236,7 +236,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-201, Too many arguments line %d.</term> <term><computeroutput>-201, Too many arguments line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This means that <productname>Postgres</productname> has This means that <productname>Postgres</productname> has
@ -248,7 +248,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-202, Too few arguments line %d.</term> <term><computeroutput>-202, Too few arguments line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This means that <productname>Postgres</productname> has This means that <productname>Postgres</productname> has
@ -260,7 +260,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-203, Too many matches line %d.</term> <term><computeroutput>-203, Too many matches line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This means the query has returned several rows but the This means the query has returned several rows but the
@ -271,7 +271,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-204, Not correctly formatted int type: %s line %d.</term> <term><computeroutput>-204, Not correctly formatted int type: %s line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This means the host variable is of type <type>int</type> and This means the host variable is of type <type>int</type> and
@ -284,7 +284,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-205, Not correctly formatted unsigned type: %s line %d.</term> <term><computeroutput>-205, Not correctly formatted unsigned type: %s line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This means the host variable is of type <type>unsigned This means the host variable is of type <type>unsigned
@ -298,7 +298,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-206, Not correctly formatted floating point type: %s line %d.</term> <term><computeroutput>-206, Not correctly formatted floating point type: %s line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This means the host variable is of type <type>float</type> and This means the host variable is of type <type>float</type> and
@ -311,7 +311,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-207, Unable to convert %s to bool on line %d.</term> <term><computeroutput>-207, Unable to convert %s to bool on line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This means the host variable is of type <type>bool</type> and This means the host variable is of type <type>bool</type> and
@ -322,17 +322,17 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-208, Empty query line %d.</term> <term><computeroutput>-208, Empty query line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
<productname>Postgres</productname> returned PGRES_EMPTY_QUERY, probably <productname>Postgres</productname> returned <symbol>PGRES_EMPTY_QUERY</symbol>, probably
because the query indeed was empty. because the query indeed was empty.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-220, No such connection %s in line %d.</term> <term><computeroutput>-220, No such connection %s in line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
The program tried to access a connection that does not exist. The program tried to access a connection that does not exist.
@ -341,7 +341,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-221, Not connected in line %d.</term> <term><computeroutput>-221, Not connected in line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
The program tried to access a connection that does exist but is The program tried to access a connection that does exist but is
@ -351,7 +351,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-230, Invalid statement name %s in line %d.</term> <term><computeroutput>-230, Invalid statement name %s in line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
The statement you are trying to use has not been prepared. The statement you are trying to use has not been prepared.
@ -360,7 +360,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-400, Postgres error: %s line %d.</term> <term><computeroutput>-400, Postgres error: %s line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
Some <productname>Postgres</productname> error. Some <productname>Postgres</productname> error.
@ -371,7 +371,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-401, Error in transaction processing line %d. </term> <term><computeroutput>-401, Error in transaction processing line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
<productname>Postgres</productname> signaled that we cannot start, <productname>Postgres</productname> signaled that we cannot start,
@ -381,7 +381,7 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>-402, connect: could not open database %s.</term> <term><computeroutput>-402, connect: could not open database %s.</computeroutput></term>
<listitem> <listitem>
<para> <para>
The connect to the database did not work. The connect to the database did not work.
@ -390,10 +390,10 @@ struct sqlca
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>100, Data not found line %d.</term> <term><computeroutput>100, Data not found line %d.</computeroutput></term>
<listitem> <listitem>
<para> <para>
This is a "normal" error that tells you that what you are quering cannot This is a "normal" error that tells you that what you are querying cannot
be found or you are at the end of the cursor. be found or you are at the end of the cursor.
</para> </para>
</listitem> </listitem>
@ -419,7 +419,7 @@ struct sqlca
<term>Oracle's single tasking</term> <term>Oracle's single tasking</term>
<listitem> <listitem>
<para> <para>
Oracle version 7.0 on AIX 3 uses OS-supported locks in shared Oracle version 7.0 on <systemitem class="osname">AIX</> 3 uses OS-supported locks in shared
memory that allow an application designer to link an application memory that allow an application designer to link an application
in a "single tasking" way. Instead of starting one client in a "single tasking" way. Instead of starting one client
process per application process, both the database part and the process per application process, both the database part and the
@ -526,21 +526,21 @@ struct sqlca
The following statements are not implemented thus far: The following statements are not implemented thus far:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> exec sql allocate</term> <term><literal>exec sql allocate</></term>
<listitem> <listitem>
<para> <para>
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> exec sql deallocate</term> <term><literal>exec sql deallocate</></term>
<listitem> <listitem>
<para> <para>
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> SQLSTATE</term> <term><literal>SQLSTATE</></term>
<listitem> <listitem>
<para> <para>
</para> </para>
@ -565,10 +565,10 @@ exec sql insert select from statement
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>sqlwarn[6]</term> <term><literal>sqlwarn[6]</literal></term>
<listitem> <listitem>
<para> <para>
sqlwarn[6] should be <literal>W</> if the <command>PRECISION</> <literal>sqlwarn[6]</literal> should be <literal>W</> if the <command>PRECISION</>
or <command>SCALE</> value specified in a <command>SET or <command>SCALE</> value specified in a <command>SET
DESCRIPTOR</> statement was ignored. DESCRIPTOR</> statement was ignored.
</para> </para>
@ -582,7 +582,7 @@ exec sql insert select from statement
<title>The Preprocessor</title> <title>The Preprocessor</title>
<para> <para>
The first four lines written by ecpg to the output are fixed lines. The first four lines written by <command>ecpg</command> to the output are fixed lines.
Two are comments and two are include lines necessary to interface Two are comments and two are include lines necessary to interface
to the library. to the library.
</para> </para>
@ -629,7 +629,7 @@ exec sql end declare section;
</para> </para>
<para> <para>
The special types VARCHAR and VARCHAR2 are converted into a named struct The special types <type>VARCHAR</type> and <type>VARCHAR2</type> are converted into a named struct
for every variable. A declaration like: for every variable. A declaration like:
<programlisting> <programlisting>
VARCHAR var[180]; VARCHAR var[180];
@ -745,7 +745,7 @@ exec sql connect to <replaceable>connection target</replaceable>;
</para> </para>
<para> <para>
Finally, the userid and password may be a constant text, a Finally, the <replaceable>userid</replaceable> and <replaceable>password</replaceable> may be a constant text, a
character variable, or a character string. character variable, or a character string.
</para> </para>
</listitem> </listitem>
@ -853,7 +853,7 @@ exec sql rollback;
<simplelist> <simplelist>
<member>The type as a special symbol.</member> <member>The type as a special symbol.</member>
<member>A pointer to the value or a pointer to the pointer.</member> <member>A pointer to the value or a pointer to the pointer.</member>
<member>The size of the variable if it is a char or varchar.</member> <member>The size of the variable if it is a <type>char</type> or <type>varchar</type>.</member>
<member>The number of elements in the array (for array fetches).</member> <member>The number of elements in the array (for array fetches).</member>
<member>The offset to the next element in the array (for array fetches).</member> <member>The offset to the next element in the array (for array fetches).</member>
<member>The type of the indicator variable as a special symbol.</member> <member>The type of the indicator variable as a special symbol.</member>
@ -876,7 +876,7 @@ exec sql rollback;
<para> <para>
Here is a complete example describing the output of the preprocessor of a Here is a complete example describing the output of the preprocessor of a
file foo.pgc: file <filename>foo.pgc</filename>:
<programlisting> <programlisting>
exec sql begin declare section; exec sql begin declare section;
int index; int index;
@ -919,7 +919,7 @@ ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ",
The most important function in the library is The most important function in the library is
<function>ECPGdo</function>. It takes a variable number of <function>ECPGdo</function>. It takes a variable number of
arguments. Hopefully there are no computers that limit the arguments. Hopefully there are no computers that limit the
number of variables that can be accepted by a varargs() function. This number of variables that can be accepted by a <function>varargs()</function> function. This
can easily add up to 50 or so arguments. can easily add up to 50 or so arguments.
</para> </para>
@ -960,7 +960,7 @@ ECPGdo(__LINE__, NULL, "select res from mytable where index = ? ",
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>ECPGt_EOIT</term> <term><literal>ECPGt_EOIT</literal></term>
<listitem> <listitem>
<para> <para>
An enum telling that there are no more input variables. An enum telling that there are no more input variables.

4
doc/src/sgml/extend.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <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> <note>
<para> <para>
We use the words <firstterm>procedure</firstterm> We use the words <firstterm>procedure</firstterm>
and <firstterm>function</firstterm> more or less interchangably. and <firstterm>function</firstterm> more or less interchangeably.
</para> </para>
</note> </note>

4
doc/src/sgml/indexcost.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <chapter id="indexcost">
@ -154,7 +154,7 @@ amcostestimate (Query *root,
<para> <para>
The index access costs should be computed in the units used by 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 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 the cost of processing one index tuple should usually be taken as
cpu_index_tuple_cost (which is a user-adjustable optimizer parameter). cpu_index_tuple_cost (which is a user-adjustable optimizer parameter).

64
doc/src/sgml/jdbc.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <chapter id="jdbc">
@ -514,7 +514,7 @@ mycon.setAutoCommit(false);
There are two methods of using Large Objects. The first is the There are two methods of using Large Objects. The first is the
standard <acronym>JDBC</acronym> way, and is documented here. The standard <acronym>JDBC</acronym> way, and is documented here. The
other, uses <productname>PostgreSQL</productname> extensions to 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 <acronym>API</acronym> to Java, providing even better access to
large objects than the standard. Internally, the driver uses the large objects than the standard. Internally, the driver uses the
extension to provide large object support. extension to provide large object support.
@ -674,7 +674,7 @@ import org.postgresql.fastpath.*;
... ...
Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI(); Fastpath fp = ((org.postgresql.Connection)myconn).getFastpathAPI();
</programlisting> </programlisting>
where myconn is an open Connection to <productname>PostgreSQL</productname>. where <varname>myconn</> is an open <classname>Connection</> to <productname>PostgreSQL</productname>.
</para> </para>
<formalpara> <formalpara>
@ -709,21 +709,21 @@ import org.postgresql.largeobject.*;
... ...
LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI(); LargeObjectManager lo = ((org.postgresql.Connection)myconn).getLargeObjectAPI();
</programlisting> </programlisting>
where myconn is an open Connection to where <varname>myconn</> is an open <classname>Connection</> to
<productname>PostgreSQL</productname>. <productname>PostgreSQL</productname>.
</para> </para>
<formalpara> <formalpara>
<title>Returns:</title> <title>Returns:</title>
<para> <para>
LargeObject object that implements the <acronym>API</acronym> <classname>LargeObject</classname> object that implements the <acronym>API</acronym>
</para> </para>
</formalpara> </formalpara>
<formalpara> <formalpara>
<title>Throws:</title> <title>Throws:</title>
<para> <para>
SQLException by LargeObject when initializing for first time <classname>SQLException</classname> by <classname>LargeObject</classname> when initializing for first time
</para> </para>
</formalpara> </formalpara>
</listitem> </listitem>
@ -735,9 +735,9 @@ public void addDataType(String type, String name)
</synopsis> </synopsis>
This allows client code to add a handler for one of This allows client code to add a handler for one of
PostgreSQL's more unique data types. Normally, a data type not PostgreSQL's more unique data types. Normally, a data type not
known by the driver is returned by ResultSet.getObject() as a known by the driver is returned by <literal>ResultSet.getObject()</literal> as a
PGobject instance. This method allows you to write a class <classname>PGobject</> instance. This method allows you to write a class
that extends PGobject, and tell the driver the type name, and 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 class name to use. The down side to this, is that you must
call this method each time a connection is made. call this method each time a connection is made.
</para> </para>
@ -749,7 +749,7 @@ public void addDataType(String type, String name)
((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name"); ((org.postgresql.Connection)myconn).addDataType("mytype","my.class.name");
... ...
</programlisting> </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 <productname>PostgreSQL</productname>. The handling class must
extend <classname>org.postgresql.util.PGobject</classname>. extend <classname>org.postgresql.util.PGobject</classname>.
</para> </para>
@ -772,7 +772,7 @@ java.lang.Object
<para> <para>
<classname>Fastpath</classname> is an <acronym>API</acronym> that <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 to execute a function on the database backend. Most client code
will not need to use this method, but it is provided because the will not need to use this method, but it is provided because the
Large Object <acronym>API</acronym> uses it. Large Object <acronym>API</acronym> uses it.
@ -825,11 +825,11 @@ public Object fastpath(int fnid,
<formalpara> <formalpara>
<title>Parameters:</title> <title>Parameters:</title>
<para> <para>
fnid - Function id <parameter>fnid</> - Function id
resulttype - True if the result is an integer, false <parameter>resulttype</> - True if the result is an integer, false
for for
other results other results
args - FastpathArguments to pass to fastpath <parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
</para> </para>
</formalpara> </formalpara>
@ -855,7 +855,7 @@ public Object fastpath(String name,
<note> <note>
<para> <para>
The mapping for the procedure name to function id needs to 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 the preferred method to call, as function id's can/may change
between versions of the backend. For an example of how this between versions of the backend. For an example of how this
works, refer to org.postgresql.LargeObject works, refer to org.postgresql.LargeObject
@ -865,11 +865,11 @@ public Object fastpath(String name,
<formalpara> <formalpara>
<title>Parameters:</title> <title>Parameters:</title>
<para> <para>
name - Function name <parameter>name</> - Function name
resulttype - True if the result is an integer, false <parameter>resulttype</> - True if the result is an integer, false
for for
other results other results
args - FastpathArguments to pass to fastpath <parameter>args</> - <classname>FastpathArguments</classname> to pass to fastpath
</para> </para>
</formalpara> </formalpara>
@ -899,8 +899,8 @@ public int getInteger(String name,
<formalpara> <formalpara>
<title>Parameters:</title> <title>Parameters:</title>
<para> <para>
name - Function name <parameter>name</parameter> - Function name
args - Function arguments <parameter>args</parameter> - Function arguments
</para> </para>
</formalpara> </formalpara>
@ -912,7 +912,7 @@ public int getInteger(String name,
<formalpara> <formalpara>
<title>Throws:</title> <title>Throws:</title>
<para> <para>
SQLException if a database-access error occurs or no result <classname>SQLException</classname> if a database-access error occurs or no result
</para> </para>
</formalpara> </formalpara>
</listitem> </listitem>
@ -930,8 +930,8 @@ public byte[] getData(String name,
<formalpara> <formalpara>
<title>Parameters:</title> <title>Parameters:</title>
<para> <para>
name - Function name <parameter>name</parameter> - Function name
args - Function arguments <parameter>args</parameter> - Function arguments
</para> </para>
</formalpara> </formalpara>
@ -943,7 +943,7 @@ public byte[] getData(String name,
<formalpara> <formalpara>
<title>Throws:</title> <title>Throws:</title>
<para> <para>
SQLException if a database-access error occurs or no result <classname>SQLException</classname> if a database-access error occurs or no result
</para> </para>
</formalpara> </formalpara>
</listitem> </listitem>
@ -984,7 +984,7 @@ public void addFunctions(ResultSet rs) throws SQLException
<para> <para>
PostgreSQL stores the function id's and their corresponding 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 instead of querying each function from that table when
required, a <classname>Hashtable</classname> is used. Also, only the function's required, a <classname>Hashtable</classname> is used. Also, only the function's
required are entered into this table, keeping connection required are entered into this table, keeping connection
@ -1002,7 +1002,7 @@ public void addFunctions(ResultSet rs) throws SQLException
<para> <para>
Do not think that manually converting them to the oid's will 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), development (there was some discussion about this for V7.0),
so this is implemented to prevent any unwarranted headaches so this is implemented to prevent any unwarranted headaches
in the future. in the future.
@ -1023,8 +1023,8 @@ public int getID(String name) throws SQLException
</synopsis> </synopsis>
<para> <para>
This returns the function id associated by its name If This returns the function id associated by its name If
addFunction() or addFunctions() have not been called for this <function>addFunction()</function> or <function>addFunctions()</function> have not been called for this
name, then an SQLException is thrown. name, then an <classname>SQLException</classname> is thrown.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -1112,21 +1112,21 @@ public FastpathArg(byte buf[],
<para> <para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term>buf</term> <term><parameter>buf</></term>
<listitem> <listitem>
<simpara>source array</simpara> <simpara>source array</simpara>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>off</term> <term><parameter>off</parameter></term>
<listitem> <listitem>
<simpara>offset within array</simpara> <simpara>offset within array</simpara>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>len</term> <term><parameter>len</parameter></term>
<listitem> <listitem>
<simpara>length of data to include</simpara> <simpara>length of data to include</simpara>
</listitem> </listitem>
@ -1880,7 +1880,7 @@ Methods
</para> </para>
<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 C interface's large object <acronym>API</acronym>. It consists of
two classes, <classname>LargeObjectManager</classname>, which deals with creating, two classes, <classname>LargeObjectManager</classname>, which deals with creating,
opening and deleting large objects, and <classname>LargeObject</classname> which deals opening and deleting large objects, and <classname>LargeObject</classname> which deals

52
doc/src/sgml/libpgeasy.sgml
View File

@ -1,9 +1,9 @@
<!-- <!--
$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"> <chapter id="pgeasy-chapter">
<title id="pgeasy">libpgeasy - Simplified C Library</title> <title id="pgeasy"><application>libpgeasy</application> - Simplified C Library</title>
<note> <note>
<title>Author</title> <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> <para>
It consists of set of simplified C functions that encapsulate the It consists of set of simplified C functions that encapsulate the
functionality of libpq. functionality of <application>libpq</application>.
The functions are: The functions are:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <synopsis>
PGresult *doquery(char *query); PGresult *doquery(char *query);
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
PGconn *connectdb(char *options); PGconn *connectdb(char *options);
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
void disconnectdb(); void disconnectdb();
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
int fetch(void *param,...); int fetch(void *param,...);
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
int fetchwithnulls(void *param,...); int fetchwithnulls(void *param,...);
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
void reset_fetch(); void reset_fetch();
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
void on_error_continue(); void on_error_continue();
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
void on_error_stop(); void on_error_stop();
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
PGresult *get_result(); PGresult *get_result();
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
void set_result(PGresult *newres); void set_result(PGresult *newres);
</para> </synopsis>
</listitem> </listitem>
<listitem> <listitem>
<para> <synopsis>
void unset_result(PGresult *oldres); void unset_result(PGresult *oldres);
</para> </synopsis>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -118,7 +118,7 @@ void unset_result(PGresult *oldres);
<function>fetchwithnulls</function> allows you to retrieve the NULL <function>fetchwithnulls</function> allows you to retrieve the NULL
status of the field by passing an <literal>int*</literal> status of the field by passing an <literal>int*</literal>
after each result pointer, which returns true or false if the field is null. 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>. by <function>doquery</function>.
<function>reset_fetch</function> starts the fetch back at the beginning. <function>reset_fetch</function> starts the fetch back at the beginning.
</para> </para>

119
doc/src/sgml/libpgtcl.sgml
View File

@ -1,5 +1,5 @@
<chapter id="pgtcl"> <chapter id="pgtcl">
<title>pgtcl - Tcl Binding Library</title> <title><application>pgtcl</application> - Tcl Binding Library</title>
<indexterm zone="pgtcl"> <indexterm zone="pgtcl">
<primary>libpgtcl</primary> <primary>libpgtcl</primary>
@ -10,10 +10,10 @@
</indexterm> </indexterm>
<Para> <Para>
<literal>pgtcl</literal> is a tcl package for front-end programs <literal>pgtcl</literal> is a Tcl package for front-end programs
to interface with <ProductName>Postgres</ProductName> to interface with <ProductName>Postgres</ProductName>
backends. It makes most of the functionality of <literal>libpq</literal> available to backends. It makes most of the functionality of <literal>libpq</literal> available to
tcl scripts. Tcl scripts.
</Para> </Para>
<Para> <Para>
@ -35,72 +35,72 @@ This package was originally written by Jolly Chen.
</THEAD> </THEAD>
<TBODY> <TBODY>
<ROW> <ROW>
<ENTRY>pg_connect</ENTRY> <ENTRY><function>pg_connect</function></ENTRY>
<ENTRY>opens a connection to the backend server</ENTRY> <ENTRY>opens a connection to the backend server</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_disconnect</ENTRY> <ENTRY><function>pg_disconnect</function></ENTRY>
<ENTRY>closes a connection</ENTRY> <ENTRY>closes a connection</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_conndefaults</ENTRY> <ENTRY><function>pg_conndefaults</function></ENTRY>
<ENTRY>get connection options and their defaults</ENTRY> <ENTRY>get connection options and their defaults</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_exec</ENTRY> <ENTRY><function>pg_exec</function></ENTRY>
<ENTRY>send a query to the backend</ENTRY> <ENTRY>send a query to the backend</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_result</ENTRY> <ENTRY><function>pg_result</function></ENTRY>
<ENTRY>manipulate the results of a query</ENTRY> <ENTRY>manipulate the results of a query</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_select</ENTRY> <ENTRY><function>pg_select</function></ENTRY>
<ENTRY>loop over the result of a SELECT statement</ENTRY> <ENTRY>loop over the result of a SELECT statement</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_listen</ENTRY> <ENTRY><function>pg_listen</function></ENTRY>
<ENTRY>establish a callback for NOTIFY messages</ENTRY> <ENTRY>establish a callback for NOTIFY messages</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_creat</ENTRY> <ENTRY><function>pg_lo_creat</function></ENTRY>
<ENTRY>create a large object</ENTRY> <ENTRY>create a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_open</ENTRY> <ENTRY><function>pg_lo_open</function></ENTRY>
<ENTRY>open a large object</ENTRY> <ENTRY>open a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_close</ENTRY> <ENTRY><function>pg_lo_close</function></ENTRY>
<ENTRY>close a large object</ENTRY> <ENTRY>close a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_read</ENTRY> <ENTRY><function>pg_lo_read</function></ENTRY>
<ENTRY>read a large object</ENTRY> <ENTRY>read a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_write</ENTRY> <ENTRY><function>pg_lo_write</function></ENTRY>
<ENTRY>write a large object</ENTRY> <ENTRY>write a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_lseek</ENTRY> <ENTRY><function>pg_lo_lseek</function></ENTRY>
<ENTRY>seek to a position in a large object</ENTRY> <ENTRY>seek to a position in a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_tell</ENTRY> <ENTRY><function>pg_lo_tell</function></ENTRY>
<ENTRY>return the current seek position of a large object</ENTRY> <ENTRY>return the current seek position of a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_unlink</ENTRY> <ENTRY><function>pg_lo_unlink</function></ENTRY>
<ENTRY>delete a large object</ENTRY> <ENTRY>delete a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_import</ENTRY> <ENTRY><function>pg_lo_import</function></ENTRY>
<ENTRY>import a Unix file into a large object</ENTRY> <ENTRY>import a Unix file into a large object</ENTRY>
</ROW> </ROW>
<ROW> <ROW>
<ENTRY>pg_lo_export</ENTRY> <ENTRY><function>pg_lo_export</function></ENTRY>
<ENTRY>export a large object into a Unix file</ENTRY> <ENTRY>export a large object into a Unix file</ENTRY>
</ROW> </ROW>
</TBODY> </TBODY>
@ -154,7 +154,7 @@ proc getDBs { {host "localhost"} {port "5432"} } {
</Sect1> </Sect1>
<Sect1 id="libpgtcl-ref"> <Sect1 id="libpgtcl-ref">
<Title>pgtcl Command Reference Information</Title> <Title><application>pgtcl</application> Command Reference Information</Title>
<REFENTRY ID="PGTCL-PGCONNECT"> <REFENTRY ID="PGTCL-PGCONNECT">
<REFMETA> <REFMETA>
@ -243,7 +243,7 @@ A list of valid options can be found in <filename>libpq</>'s
<OPTIONAL>-tty <REPLACEABLE CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL> <OPTIONAL>-tty <REPLACEABLE CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA>Specifies file or tty for optional debug output from backend. <PARA>Specifies file or <acronym>tty</acronym> for optional debug output from backend.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -273,7 +273,7 @@ A list of valid options can be found in <filename>libpq</>'s
<LISTITEM> <LISTITEM>
<PARA> <PARA>
If successful, a handle for a database connection is returned. If successful, a handle for a database connection is returned.
Handles start with the prefix "pgsql". Handles start with the prefix <literal>pgsql</literal>.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -304,8 +304,9 @@ for info about the available options in the newer syntax.
<REFSECT1 ID="R1-PGTCL-PGCONNECT-2"> <REFSECT1 ID="R1-PGTCL-PGCONNECT-2">
<TITLE>Usage <TITLE>Usage
</TITLE> </TITLE>
<PARA>XXX thomas 1997-12-24 <comment>
</PARA> XXX thomas 1997-12-24
</comment>
</REFSECT1> </REFSECT1>
</REFENTRY> </REFENTRY>
@ -433,11 +434,11 @@ The result is a list describing the possible connection options and their
current default values. current default values.
Each entry in the list is a sublist of the format: Each entry in the list is a sublist of the format:
</Para> </Para>
<para> <screen>
{optname label dispchar dispsize value} {optname label dispchar dispsize value}
</Para> </screen>
<Para> <Para>
where the optname is usable as an option in where the <replaceable>optname</> is usable as an option in
<FUNCTION>pg_connect -conninfo</FUNCTION>. <FUNCTION>pg_connect -conninfo</FUNCTION>.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
@ -462,7 +463,7 @@ current default value for each option.
<REFSECT1 ID="R1-PGTCL-PGCONNDEFAULTS-2"> <REFSECT1 ID="R1-PGTCL-PGCONNDEFAULTS-2">
<TITLE>Usage <TITLE>Usage
</TITLE> </TITLE>
<PARA>pg_conndefaults <PARA><literal>pg_conndefaults</>
</PARA> </PARA>
</REFSECT1> </REFSECT1>
</REFENTRY> </REFENTRY>
@ -532,7 +533,7 @@ pg_exec <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
A Tcl error will be returned if Pgtcl was unable to obtain a backend A Tcl error will be returned if <application>pgtcl</application> was unable to obtain a backend
response. Otherwise, a query result object is created and a handle for response. Otherwise, a query result object is created and a handle for
it is returned. This handle can be passed to <FUNCTION>pg_result</FUNCTION> it is returned. This handle can be passed to <FUNCTION>pg_result</FUNCTION>
to obtain the results of the query. to obtain the results of the query.
@ -620,7 +621,7 @@ Specifies one of several possible options.
<VARIABLELIST> <VARIABLELIST>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-status <option>-status</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -630,7 +631,7 @@ the status of the result.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-error <option>-error</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -640,7 +641,7 @@ the error message, if the status indicates error; otherwise an empty string.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-conn <option>-conn</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -650,7 +651,7 @@ the connection that produced the result.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-oid <option>-oid</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -661,7 +662,7 @@ inserted tuple; otherwise an empty string.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-numTuples <option>-numTuples</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -671,7 +672,7 @@ the number of tuples returned by the query.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-numAttrs <option>-numAttrs</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -681,7 +682,7 @@ the number of attributes in each tuple.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-list VarName <option>-list VarName</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -691,32 +692,32 @@ assign the results to a list of lists.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-assign arrayName <option>-assign arrayName</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
assign the results to an array, using subscripts of the form assign the results to an array, using subscripts of the form
(tupno,attributeName). <literal>(tupno,attributeName)</literal>.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-assignbyidx arrayName ?appendstr? <option>-assignbyidx arrayName ?appendstr?</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
assign the results to an array using the first attribute's value and assign the results to an array using the first attribute's value and
the remaining attributes' names as keys. If appendstr is given then the remaining attributes' names as keys. If <parameter>appendstr</> is given then
it is appended to each key. In short, all but the first field of each 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 tuple are stored into the array, using subscripts of the form
(firstFieldValue,fieldNameAppendStr). <literal>(firstFieldValue,fieldNameAppendStr)</literal>.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-getTuple tupleNumber <option>-getTuple tupleNumber</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -727,18 +728,18 @@ start at zero.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-tupleArray tupleNumber arrayName <option>-tupleArray tupleNumber arrayName</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
stores the fields of the tuple in array arrayName, indexed by field names. stores the fields of the tuple in array <parameter>arrayName</parameter>, indexed by field names.
Tuple numbers start at zero. Tuple numbers start at zero.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-attributes <option>-attributes</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -748,17 +749,17 @@ returns a list of the names of the tuple attributes.
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-lAttributes <option>-lAttributes</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
returns a list of sublists, {name ftype fsize} for each tuple attribute. returns a list of sublists, <literal>{name ftype fsize}</literal> for each tuple attribute.
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
<VARLISTENTRY> <VARLISTENTRY>
<TERM> <TERM>
-clear <option>-clear</option>
</TERM> </TERM>
<LISTITEM> <LISTITEM>
<PARA> <PARA>
@ -796,7 +797,7 @@ created by a prior <FUNCTION>pg_exec</FUNCTION>.
You can keep a query result around for as long as you need it, but when 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 you are done with it, be sure to free it by
executing <FUNCTION>pg_result -clear</FUNCTION>. Otherwise, you have executing <FUNCTION>pg_result -clear</FUNCTION>. Otherwise, you have
a memory leak, and Pgtcl will eventually start complaining that you've a memory leak, and <application>Pgtcl</> will eventually start complaining that you've
created too many query result objects. created too many query result objects.
</PARA> </PARA>
</REFSECT1> </REFSECT1>
@ -1021,9 +1022,9 @@ when a matching notification arrives.
</TITLE> </TITLE>
<PARA><FUNCTION>pg_listen</FUNCTION> creates, changes, or cancels a request <PARA><FUNCTION>pg_listen</FUNCTION> creates, changes, or cancels a request
to listen for asynchronous NOTIFY messages from the to listen for asynchronous NOTIFY messages from the
<ProductName>Postgres</ProductName> backend. With a callbackCommand <ProductName>Postgres</ProductName> backend. With a <parameter>callbackCommand</>
parameter, the request is established, or the command string of an already parameter, the request is established, or the command string of an already
existing request is replaced. With no callbackCommand parameter, a prior existing request is replaced. With no <parameter>callbackCommand</> parameter, a prior
request is canceled. request is canceled.
</PARA> </PARA>
@ -1041,8 +1042,8 @@ the idle loop to be entered.
</Para> </Para>
<para> <para>
You should not invoke the SQL statements LISTEN or UNLISTEN directly when You should not invoke the SQL statements <command>LISTEN</command> or <command>UNLISTEN</command> directly when
using <FUNCTION>pg_listen</FUNCTION>. Pgtcl takes care of issuing those using <FUNCTION>pg_listen</FUNCTION>. <application>Pgtcl</application> takes care of issuing those
statements for you. But if you want to send a NOTIFY message yourself, statements for you. But if you want to send a NOTIFY message yourself,
invoke the SQL NOTIFY statement using <FUNCTION>pg_exec</FUNCTION>. invoke the SQL NOTIFY statement using <FUNCTION>pg_exec</FUNCTION>.
</PARA> </PARA>
@ -1754,7 +1755,9 @@ pg_lo_unlink <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLAS
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Identifier for a large object. Identifier for a large object.
XXX Is this the same as objOid in other calls?? - thomas 1998-01-11 <comment>
XXX Is this the same as <parameter>objOid</parameter> in other calls?? - thomas 1998-01-11
</comment>
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -1850,7 +1853,9 @@ Unix file name.
</TITLE> </TITLE>
<PARA> <PARA>
None None
<comment>
XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11 XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11
</comment>
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>
@ -1919,7 +1924,9 @@ pg_lo_export <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLAS
<LISTITEM> <LISTITEM>
<PARA> <PARA>
Large object identifier. Large object identifier.
<comment>
XXX Is this the same as the objOid in other calls?? thomas - 1998-01-11 XXX Is this the same as the objOid in other calls?? thomas - 1998-01-11
</comment>
</PARA> </PARA>
</LISTITEM> </LISTITEM>
</VARLISTENTRY> </VARLISTENTRY>
@ -1944,7 +1951,9 @@ Unix file name.
</TITLE> </TITLE>
<PARA> <PARA>
None None
<comment>
XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11 XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11
</comment>
</PARA> </PARA>
</REFSECT2> </REFSECT2>
</REFSYNOPSISDIV> </REFSYNOPSISDIV>

84
doc/src/sgml/libpq++.sgml
View File

@ -1,9 +1,9 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:11 momjian Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.31 2001/09/10 21:58:46 petere Exp $
--> -->
<chapter id="libpqplusplus"> <chapter id="libpqplusplus">
<title>libpq++ - C++ Binding Library</title> <title><application>libpq++</application> - C++ Binding Library</title>
<para> <para>
<filename>libpq++</filename> is the C++ API to <filename>libpq++</filename> is the C++ API to
@ -74,7 +74,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<para> <para>
<filename>libpq++</filename> uses only environment variables or <filename>libpq++</filename> uses only environment variables or
<filename>libpq</>'s <function>PQconnectdb</> <filename>libpq</>'s <function>PQconnectdb</>
conninfo style strings. <parameter>conninfo</parameter> style strings.
</para> </para>
</note> </note>
@ -84,7 +84,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<envar>PGHOST</envar> sets the default server name. <envar>PGHOST</envar> sets the default server name.
If this begins with a slash, it specifies Unix-domain communication If this begins with a slash, it specifies Unix-domain communication
rather than TCP/IP communication; the value is the name of the rather than TCP/IP communication; the value is the name of the
directory in which the socket file is stored (default "/tmp"). directory in which the socket file is stored (default <filename>/tmp</filename>).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -133,7 +133,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<envar>PGTTY</envar> sets the file or tty on which debugging <envar>PGTTY</envar> sets the file or <acronym>tty</acronym> on which debugging
messages from the backend server are displayed. messages from the backend server are displayed.
</para> </para>
</listitem> </listitem>
@ -182,7 +182,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
</sect1> </sect1>
<sect1 id="libpqpp-classes"> <sect1 id="libpqpp-classes">
<title>libpq++ Classes</title> <title><application>libpq++</application> Classes</title>
<sect2> <sect2>
<title>Connection Class: <classname>PgConnection</classname></title> <title>Connection Class: <classname>PgConnection</classname></title>
@ -199,7 +199,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<para> <para>
The database class provides C++ objects that have a connection The database class provides C++ objects that have a connection
to a backend server. To create such an object one first needs to a backend server. To create such an object one first needs
the apropriate environment for the backend to access. the appropriate environment for the backend to access.
The following constructors deal with making a connection to a backend The following constructors deal with making a connection to a backend
server from a C++ program. server from a C++ program.
</para> </para>
@ -218,7 +218,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
PgConnection::PgConnection(const char *conninfo) PgConnection::PgConnection(const char *conninfo)
</synopsis> </synopsis>
Although typically called from one of the access classes, a connection to Although typically called from one of the access classes, a connection to
a backend server is possible by creating a PgConnection object. a backend server is possible by creating a <classname>PgConnection</> object.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -250,10 +250,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<synopsis> <synopsis>
PgDatabase(const char *conninfo) PgDatabase(const char *conninfo)
</synopsis> </synopsis>
After a PgDatabase has been created it should be checked to make sure After a <classname>PgDatabase</classname> has been created it should be checked to make sure
the connection to the database succeded before sending the connection to the database succeeded before sending
queries to the object. This can easily be done by queries to the object. This can easily be done by
retrieving the current status of the PgDatabase object with the retrieving the current status of the <classname>PgDatabase</classname> object with the
<function>Status</function> or <function>ConnectionBad</function> methods. <function>Status</function> or <function>ConnectionBad</function> methods.
</para> </para>
</listitem> </listitem>
@ -274,7 +274,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<synopsis> <synopsis>
PGnotify* PgConnection::Notifies() PGnotify* PgConnection::Notifies()
</synopsis> </synopsis>
See PQnotifies() for details. See <function>PQnotifies</function> for details.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -300,28 +300,28 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<simplelist> <simplelist>
<member> <member>
PGRES_EMPTY_QUERY <symbol>PGRES_EMPTY_QUERY</symbol>
</member> </member>
<member> <member>
PGRES_COMMAND_OK, if the query was a command <symbol>PGRES_COMMAND_OK</symbol>, if the query was a command
</member> </member>
<member> <member>
PGRES_TUPLES_OK, if the query successfully returned tuples <symbol>PGRES_TUPLES_OK</symbol>, if the query successfully returned tuples
</member> </member>
<member> <member>
PGRES_COPY_OUT <symbol>PGRES_COPY_OUT</symbol>
</member> </member>
<member> <member>
PGRES_COPY_IN <symbol>PGRES_COPY_IN</symbol>
</member> </member>
<member> <member>
PGRES_BAD_RESPONSE, if an unexpected response was received <symbol>PGRES_BAD_RESPONSE</symbol>, if an unexpected response was received
</member> </member>
<member> <member>
PGRES_NONFATAL_ERROR <symbol>PGRES_NONFATAL_ERROR</symbol>
</member> </member>
<member> <member>
PGRES_FATAL_ERROR <symbol>PGRES_FATAL_ERROR</symbol>
</member> </member>
</simplelist> </simplelist>
</para> </para>
@ -394,7 +394,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<listitem> <listitem>
<para> <para>
<function>FieldNum</function> <function>FieldNum</function>
PQfnumber Returns the field (attribute) index associated with <function>PQfnumber</function> Returns the field (attribute) index associated with
the given field name. the given field name.
<synopsis> <synopsis>
int PgDatabase::FieldNum(const char* field_name) const int PgDatabase::FieldNum(const char* field_name) const
@ -463,41 +463,41 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<listitem> <listitem>
<para> <para>
<function>GetValue</function> <function>GetValue</function>
Returns a single field (attribute) value of one tuple of a PGresult. Returns a single field (attribute) value of one tuple of a <structname>PGresult</structname>.
Tuple and field indices start at 0. Tuple and field indices start at 0.
<synopsis> <synopsis>
const char *PgDatabase::GetValue(int tup_num, int field_num) const const char *PgDatabase::GetValue(int tup_num, int field_num) const
</synopsis> </synopsis>
For most queries, the value returned by GetValue is a null-terminated For most queries, the value returned by <function>GetValue</function> is a null-terminated
ASCII string representation of the attribute value. But if BinaryTuples() string representation of the attribute value. But if <function>BinaryTuples</function>
is TRUE, the value returned by GetValue is the binary representation is TRUE, the value returned by <function>GetValue</function> is the binary representation
of the type in the internal format of the backend server (but not including of the type in the internal format of the backend server (but not including
the size word, if the field is variable-length). It is then the programmer's the size word, if the field is variable-length). It is then the programmer's
responsibility to cast and convert the data to the correct C type. The responsibility to cast and convert the data to the correct C type. The
pointer returned by GetValue points to storage that is part of the pointer returned by <function>GetValue</function> points to storage that is part of the
PGresult structure. One should not modify it, and one must explicitly <structname>PGresult</structname> structure. One should not modify it, and one must explicitly
copy the value into other storage if it is to be used past the lifetime copy the value into other storage if it is to be used past the lifetime
of the PGresult structure itself. BinaryTuples() is not yet implemented. of the <structname>PGresult</structname> structure itself. <function>BinaryTuples</function> is not yet implemented.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>GetValue</function> <function>GetValue</function>
Returns a single field (attribute) value of one tuple of a PGresult. Returns a single field (attribute) value of one tuple of a <structname>PGresult</structname>.
Tuple and field indices start at 0. Tuple and field indices start at 0.
<synopsis> <synopsis>
const char *PgDatabase::GetValue(int tup_num, const char *field_name) const const char *PgDatabase::GetValue(int tup_num, const char *field_name) const
</synopsis> </synopsis>
For most queries, the value returned by GetValue is a null-terminated For most queries, the value returned by <function>GetValue</function> is a null-terminated
ASCII string representation of the attribute value. But if BinaryTuples() string representation of the attribute value. But if <function>BinaryTuples</function>
is TRUE, the value returned by GetValue is the binary representation is TRUE, the value returned by <function>GetValue</function> is the binary representation
of the type in the internal format of the backend server (but not including of the type in the internal format of the backend server (but not including
the size word, if the field is variable-length). It is then the programmer's the size word, if the field is variable-length). It is then the programmer's
responsibility to cast and convert the data to the correct C type. The responsibility to cast and convert the data to the correct C type. The
pointer returned by GetValue points to storage that is part of the pointer returned by <function>GetValue</function> points to storage that is part of the
PGresult structure. One should not modify it, and one must explicitly <structname>PGresult</structname> structure. One should not modify it, and one must explicitly
copy the value into other storage if it is to be used past the lifetime copy the value into other storage if it is to be used past the lifetime
of the PGresult structure itself. BinaryTuples() is not yet implemented. of the <structname>PGresult</structname> structure itself. <function>BinaryTuples</function> is not yet implemented.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -509,9 +509,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
int PgDatabase::GetLength(int tup_num, int field_num) const int PgDatabase::GetLength(int tup_num, int field_num) const
</synopsis> </synopsis>
This is the actual data length for the particular data value, that This is the actual data length for the particular data value, that
is the size of the object pointed to by GetValue. Note that for is the size of the object pointed to by <function>GetValue</function>. Note that for
ASCII-represented values, this size has little to do with the binary ASCII-represented values, this size has little to do with the binary
size reported by PQfsize. size reported by <function>PQfsize</function>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -523,9 +523,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
int PgDatabase::GetLength(int tup_num, const char* field_name) const int PgDatabase::GetLength(int tup_num, const char* field_name) const
</synopsis> </synopsis>
This is the actual data length for the particular data value, that This is the actual data length for the particular data value, that
is the size of the object pointed to by GetValue. Note that for is the size of the object pointed to by <function>GetValue</function>. Note that for
ASCII-represented values, this size has little to do with the binary ASCII-represented values, this size has little to do with the binary
size reported by PQfsize. size reported by <function>PQfsize</function>.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -535,7 +535,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<synopsis> <synopsis>
bool GetIsNull(int tup_num, int field_num) const bool GetIsNull(int tup_num, int field_num) const
</synopsis> </synopsis>
Note that GetValue will return the empty string for null fields, not Note that <function>GetValue</function> will return the empty string for null fields, not
the NULL pointer. the NULL pointer.
</para> </para>
</listitem> </listitem>
@ -546,7 +546,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<synopsis> <synopsis>
bool GetIsNull(int tup_num, const char *field_name) const bool GetIsNull(int tup_num, const char *field_name) const
</synopsis> </synopsis>
Note that GetValue will return the empty string for null fields, not Note that <function>GetValue</function> will return the empty string for null fields, not
the NULL pointer. the NULL pointer.
</para> </para>
</listitem> </listitem>
@ -652,7 +652,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.30 2001/05/09 17:46:
<note> <note>
<para> <para>
In the past, the documentation has associated the names used for asyncronous In the past, the documentation has associated the names used for asynchronous
notification with relations or classes. However, there is in fact no notification with relations or classes. However, there is in fact no
direct linkage of the two concepts in the implementation, and the direct linkage of the two concepts in the implementation, and the
named semaphore in fact does not need to have a corresponding relation named semaphore in fact does not need to have a corresponding relation

410
doc/src/sgml/libpq.sgml
View File

@ -1,25 +1,25 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.70 2001/09/08 16:46:34 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.71 2001/09/10 21:58:46 petere Exp $
--> -->
<chapter id="libpq"> <chapter id="libpq">
<title>libpq - C Library</title> <title><application>libpq</application> - C Library</title>
<indexterm zone="libpq"> <indexterm zone="libpq">
<primary>libpq</primary> <primary>libpq</primary>
</indexterm> </indexterm>
<para> <para>
<filename>libpq</filename> is the <acronym>C</acronym> <application>libpq</application> is the <acronym>C</acronym>
application programmer's interface to application programmer's interface to
<productname>Postgres</productname>. <filename>libpq</filename> is a set <productname>PostgreSQL</productname>. <application>libpq</application> is a set
of library routines that allow client programs to pass queries to the of library routines that allow client programs to pass queries to the
<productname>Postgres</productname> backend server and to receive the <productname>PostgreSQL</productname> backend server and to receive the
results of these queries. <filename>libpq</filename> is also the results of these queries. <application>libpq</application> is also the
underlying engine for several other <productname>Postgres</productname> underlying engine for several other <productname>PostgreSQL</productname>
application interfaces, including <filename>libpq++</filename> (C++), application interfaces, including <application>libpq++</application> (C++),
<filename>libpgtcl</filename> (Tcl), <productname>Perl</productname>, and <filename>libpgtcl</filename> (Tcl), <productname>Perl</productname>, and
<filename>ecpg</filename>. So some aspects of libpq's behavior will be <filename>ecpg</filename>. So some aspects of <application>libpq</>'s behavior will be
important to you if you use one of those packages. important to you if you use one of those packages.
</para> </para>
@ -47,7 +47,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.70 2001/09/08 16:46:34 peter
<para> <para>
The following routines deal with making a connection to a The following routines deal with making a connection to a
<productname>Postgres</productname> backend server. The <productname>PostgreSQL</productname> backend server. The
application program can have several backend connections open at application program can have several backend connections open at
one time. (One reason to do that is to access more than one one time. (One reason to do that is to access more than one
database.) Each connection is represented by a database.) Each connection is represented by a
@ -69,10 +69,10 @@ PGconn *PQconnectdb(const char *conninfo)
</synopsis> </synopsis>
This routine opens a new database connection using the parameters taken This routine opens a new database connection using the parameters taken
from the string <literal>conninfo</literal>. Unlike PQsetdbLogin() below, from the string <literal>conninfo</literal>. Unlike <function>PQsetdbLogin</> below,
the parameter set can be extended without changing the function signature, the parameter set can be extended without changing the function signature,
so use either of this routine or the non-blocking analogues PQconnectStart so use either of this routine or the non-blocking analogues <function>PQconnectStart</>
/ PQconnectPoll is prefered for application programming. The passed string and <function>PQconnectPoll</function> is preferred for application programming. The passed string
can be empty to use all default parameters, or it can contain one or more can be empty to use all default parameters, or it can contain one or more
parameter settings separated by whitespace. parameter settings separated by whitespace.
</para> </para>
@ -106,25 +106,25 @@ PGconn *PQconnectdb(const char *conninfo)
<listitem> <listitem>
<para> <para>
IP address of host to connect to. This should be in standard IP address of host to connect to. This should be in standard
numbers-and-dots form, as used by the BSD functions inet_aton et al. If numbers-and-dots form, as used by the BSD functions <function>inet_aton</> et al. If
a non-zero-length string is specified, TCP/IP communication is used. a non-zero-length string is specified, TCP/IP communication is used.
</para> </para>
<para> <para>
Using hostaddr instead of host allows the application to avoid a host Using <literal>hostaddr</> instead of host allows the application to avoid a host
name look-up, which may be important in applications with time name look-up, which may be important in applications with time
constraints. However, Kerberos authentication requires the host constraints. However, Kerberos authentication requires the host
name. The following therefore applies. If host is specified without name. The following therefore applies. If host is specified without
hostaddr, a hostname look-up is forced. If hostaddr is specified without <literal>hostaddr</>, a host name lookup is forced. If <literal>hostaddr</> is specified without
host, the value for hostaddr gives the remote address; if Kerberos is host, the value for <literal>hostaddr</> gives the remote address; if Kerberos is
used, this causes a reverse name query. If both host and hostaddr are used, this causes a reverse name query. If both host and <literal>hostaddr</> are
specified, the value for hostaddr gives the remote address; the value specified, the value for <literal>hostaddr</> gives the remote address; the value
for host is ignored, unless Kerberos is used, in which case that value for host is ignored, unless Kerberos is used, in which case that value
is used for Kerberos authentication. Note that authentication is likely is used for Kerberos authentication. Note that authentication is likely
to fail if libpq is passed a host name that is not the name of the to fail if <application>libpq</application> is passed a host name that is not the name of the
machine at hostaddr. machine at <literal>hostaddr</>.
</para> </para>
<para> <para>
Without either a host name or host address, libpq will connect using a Without either a host name or host address, <application>libpq</application> will connect using a
local Unix domain socket. local Unix domain socket.
</para> </para>
</listitem> </listitem>
@ -180,7 +180,7 @@ PGconn *PQconnectdb(const char *conninfo)
<term><literal>tty</literal></term> <term><literal>tty</literal></term>
<listitem> <listitem>
<para> <para>
A file or tty for optional debug output from the backend. A file or <acronym>tty</acronym> for optional debug output from the backend.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -189,7 +189,7 @@ PGconn *PQconnectdb(const char *conninfo)
<term><literal>requiressl</literal></term> <term><literal>requiressl</literal></term>
<listitem> <listitem>
<para> <para>
Set to '1' to require SSL connection to the backend. Libpq Set to '1' to require SSL connection to the backend. <application>Libpq</>
will then refuse to connect if the server does not support will then refuse to connect if the server does not support
SSL. Set to '0' (default) to negotiate with server. SSL. Set to '0' (default) to negotiate with server.
</para> </para>
@ -235,8 +235,8 @@ PGconn *PQsetdb(char *pghost,
char *pgtty, char *pgtty,
char *dbName) char *dbName)
</synopsis> </synopsis>
This is a macro that calls <function>PQsetdbLogin()</function> with null pointers This is a macro that calls <function>PQsetdbLogin</function> with null pointers
for the login and pwd parameters. It is provided primarily for the <parameter>login</> and <parameter>pwd</> parameters. It is provided primarily
for backward compatibility with old programs. for backward compatibility with old programs.
</para> </para>
</listitem> </listitem>
@ -258,24 +258,24 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn)
</para> </para>
<para> <para>
The database connection is made using the parameters taken from the string The database connection is made using the parameters taken from the string
<literal>conninfo</literal>, passed to PQconnectStart. This string is in <literal>conninfo</literal>, passed to <function>PQconnectStart</function>. This string is in
the same format as described above for PQconnectdb. the same format as described above for <function>PQconnectdb</function>.
</para> </para>
<para> <para>
Neither PQconnectStart nor PQconnectPoll will block, as long as a number of Neither <function>PQconnectStart</function> nor <function>PQconnectPoll</function> will block, as long as a number of
restrictions are met: restrictions are met:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
The hostaddr and host parameters are used appropriately to ensure that The <literal>hostaddr</> and <literal>host</> parameters are used appropriately to ensure that
name and reverse name queries are not made. See the documentation of name and reverse name queries are not made. See the documentation of
these parameters under PQconnectdb above for details. these parameters under <function>PQconnectdb</function> above for details.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
If you call PQtrace, ensure that the stream object into which you trace If you call <function>PQtrace</function>, ensure that the stream object into which you trace
will not block. will not block.
</para> </para>
</listitem> </listitem>
@ -283,7 +283,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn)
<listitem> <listitem>
<para> <para>
You ensure for yourself that the socket is in the appropriate state You ensure for yourself that the socket is in the appropriate state
before calling PQconnectPoll, as described below. before calling <function>PQconnectPoll</function>, as described below.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -291,68 +291,91 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn)
<para> <para>
To begin, call <literal>conn=PQconnectStart("&lt;connection_info_string&gt;")</literal>. To begin, call <literal>conn=PQconnectStart("&lt;connection_info_string&gt;")</literal>.
If conn is NULL, then libpq has been unable to allocate a new PGconn If <varname>conn</varname> is NULL, then <application>libpq</> has been unable to allocate a new <structname>PGconn</>
structure. Otherwise, a valid PGconn pointer is returned (though not yet structure. Otherwise, a valid <structname>PGconn</> pointer is returned (though not yet
representing a valid connection to the database). On return from representing a valid connection to the database). On return from
PQconnectStart, call status=PQstatus(conn). If status equals <function>PQconnectStart</function>, call <literal>status=PQstatus(conn)</literal>. If status equals
CONNECTION_BAD, PQconnectStart has failed. <symbol>CONNECTION_BAD</symbol>, <function>PQconnectStart</function> has failed.
</para> </para>
<para> <para>
If PQconnectStart succeeds, the next stage is to poll libpq so that it may If <function>PQconnectStart</> succeeds, the next stage is to poll <application>libpq</> so that it may
proceed with the connection sequence. Loop thus: Consider a connection proceed with the connection sequence. Loop thus: Consider a connection
'inactive' by default. If PQconnectPoll last returned PGRES_POLLING_ACTIVE, <quote>inactive</quote> by default. If <function>PQconnectPoll</function> last returned <symbol>PGRES_POLLING_ACTIVE</>,
consider it 'active' instead. If PQconnectPoll(conn) last returned consider it <quote>active</quote> instead. If <function>PQconnectPoll(conn)</function> last returned
PGRES_POLLING_READING, perform a select for reading on PQsocket(conn). If <symbol>PGRES_POLLING_READING</symbol>, perform a select for reading on <function>PQsocket(conn)</function>. If
it last returned PGRES_POLLING_WRITING, perform a select for writing on it last returned <symbol>PGRES_POLLING_WRITING</symbol>, perform a select for writing on
PQsocket(conn). If you have yet to call PQconnectPoll, i.e. after the call <function>PQsocket(conn)</function>. If you have yet to call <function>PQconnectPoll</function>, i.e. after the call
to PQconnectStart, behave as if it last returned PGRES_POLLING_WRITING. If to <function>PQconnectStart</function>, behave as if it last returned <symbol>PGRES_POLLING_WRITING</symbol>. If
the select shows that the socket is ready, consider it 'active'. If it has the select shows that the socket is ready, consider it <quote>active</quote>. If it has
been decided that this connection is 'active', call PQconnectPoll(conn) been decided that this connection is <quote>active</quote>, call <function>PQconnectPoll(conn)</function>
again. If this call returns PGRES_POLLING_FAILED, the connection procedure again. If this call returns <symbol>PGRES_POLLING_FAILED</symbol>, the connection procedure
has failed. If this call returns PGRES_POLLING_OK, the connection has been has failed. If this call returns <symbol>PGRES_POLLING_OK</symbol>, the connection has been
successfully made. successfully made.
</para> </para>
<para> <para>
Note that the use of select() to ensure that the socket is ready is merely Note that the use of <function>select()</function> to ensure that the socket is ready is merely
a (likely) example; those with other facilities available, such as a a (likely) example; those with other facilities available, such as a
poll() call, may of course use that instead. <function>poll()</function> call, may of course use that instead.
</para> </para>
<para> <para>
At any time during connection, the status of the connection may be At any time during connection, the status of the connection may be
checked, by calling PQstatus. If this is CONNECTION_BAD, then the checked, by calling <function>PQstatus</>. If this is <symbol>CONNECTION_BAD</>, then the
connection procedure has failed; if this is CONNECTION_OK, then the connection procedure has failed; if this is <function>CONNECTION_OK</>, then the
connection is ready. Either of these states should be equally detectable connection is ready. Either of these states should be equally detectable
from the return value of PQconnectPoll, as above. Other states may be from the return value of <function>PQconnectPoll</>, as above. Other states may be
shown during (and only during) an asynchronous connection procedure. These shown during (and only during) an asynchronous connection procedure. These
indicate the current stage of the connection procedure, and may be useful indicate the current stage of the connection procedure, and may be useful
to provide feedback to the user for example. These statuses may include: to provide feedback to the user for example. These statuses may include:
<itemizedlist>
<variablelist>
<varlistentry>
<term><symbol>CONNECTION_STARTED</symbol></term>
<listitem> <listitem>
<para> <para>
CONNECTION_STARTED: Waiting for connection to be made. Waiting for connection to be made.
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term><symbol>CONNECTION_MADE</symbol></term>
<listitem> <listitem>
<para> <para>
CONNECTION_MADE: Connection OK; waiting to send. Connection OK; waiting to send.
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term><symbol>CONNECTION_AWAITING_RESPONSE</symbol></term>
<listitem> <listitem>
<para> <para>
CONNECTION_AWAITING_RESPONSE: Waiting for a response from the postmaster. Waiting for a response from the postmaster.
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term><symbol>CONNECTION_AUTH_OK</symbol></term>
<listitem> <listitem>
<para> <para>
CONNECTION_AUTH_OK: Received authentication; waiting for backend start-up. Received authentication; waiting for backend start-up.
</para> </para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term><symbol>CONNECTION_SETENV</symbol></term>
<listitem> <listitem>
<para> <para>
CONNECTION_SETENV: Negotiating environment. Negotiating environment.
</para> </para>
</listitem> </listitem>
</itemizedlist> </varlistentry>
</variablelist>
Note that, although these constants will remain (in order to maintain Note that, although these constants will remain (in order to maintain
compatibility) an application should never rely upon these appearing in a compatibility) an application should never rely upon these appearing in a
@ -376,16 +399,20 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn)
} }
</programlisting> </programlisting>
</para> </para>
<para> <para>
Note that if PQconnectStart returns a non-NULL pointer, you must call Note that if <function>PQconnectStart</function> returns a non-NULL pointer, you must call
PQfinish when you are finished with it, in order to dispose of <function>PQfinish</function> when you are finished with it, in order to dispose of
the structure and any associated memory blocks. This must be done even if a the structure and any associated memory blocks. This must be done even if a
call to PQconnectStart or PQconnectPoll failed. call to <function>PQconnectStart</function> or <function>PQconnectPoll</function> failed.
</para> </para>
<para> <para>
PQconnectPoll will currently block if libpq is compiled with USE_SSL <function>PQconnectPoll</function> will currently block if
<application>libpq</> is compiled with <symbol>USE_SSL</symbol>
defined. This restriction may be removed in the future. defined. This restriction may be removed in the future.
</para> </para>
<para> <para>
These functions leave the socket in a non-blocking state as if These functions leave the socket in a non-blocking state as if
<function>PQsetnonblocking</function> had been called. <function>PQsetnonblocking</function> had been called.
@ -414,22 +441,24 @@ struct PQconninfoOption
} }
</synopsis> </synopsis>
Returns a connection options array. This may Returns a connection options array. This may
be used to determine all possible PQconnectdb options and their be used to determine all possible <function>PQconnectdb</function> options and their
current default values. The return value points to an array of current default values. The return value points to an array of
PQconninfoOption structs, which ends with an entry having a NULL <structname>PQconninfoOption</structname> structs, which ends with an entry having a NULL
keyword pointer. Note that the default values ("val" fields) keyword pointer. Note that the default values (<structfield>val</structfield> fields)
will depend on environment variables and other context. will depend on environment variables and other context.
Callers must treat the connection options data as read-only. Callers must treat the connection options data as read-only.
</para> </para>
<para> <para>
After processing the options array, free it by passing it to After processing the options array, free it by passing it to
PQconninfoFree(). If this is not done, a small amount of memory <function>PQconninfoFree</function>. If this is not done, a small amount of memory
is leaked for each call to PQconndefaults(). is leaked for each call to <function>PQconndefaults</function>.
</para> </para>
<para> <para>
In Postgres versions before 7.0, PQconndefaults() returned a pointer In <productname>PostgreSQL</productname> versions before 7.0, <function>PQconndefaults</function> returned a pointer
to a static array, rather than a dynamically allocated array. That to a static array, rather than a dynamically allocated array. That
wasn't thread-safe, so the behavior has been changed. was not thread-safe, so the behavior has been changed.
</para> </para>
</listitem> </listitem>
@ -437,14 +466,14 @@ struct PQconninfoOption
<para> <para>
<function>PQfinish</function> <function>PQfinish</function>
Close the connection to the backend. Also frees Close the connection to the backend. Also frees
memory used by the PGconn object. memory used by the <structname>PGconn</structname> object.
<synopsis> <synopsis>
void PQfinish(PGconn *conn) void PQfinish(PGconn *conn)
</synopsis> </synopsis>
Note that even if the backend connection attempt fails (as Note that even if the backend connection attempt fails (as
indicated by PQstatus), the application should call PQfinish indicated by <function>PQstatus</function>), the application should call <function>PQfinish</function>
to free the memory used by the PGconn object. to free the memory used by the <structname>PGconn</structname> object.
The PGconn pointer should not be used after PQfinish has been called. The <structname>PGconn</> pointer should not be used after <function>PQfinish</function> has been called.
</para> </para>
</listitem> </listitem>
@ -477,14 +506,14 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn);
These functions will close the connection to the backend and attempt to These functions will close the connection to the backend and attempt to
reestablish a new connection to the same postmaster, using all the same reestablish a new connection to the same postmaster, using all the same
parameters previously used. This may be useful for error recovery if a parameters previously used. This may be useful for error recovery if a
working connection is lost. They differ from PQreset (above) in that they working connection is lost. They differ from <function>PQreset</function> (above) in that they
act in a non-blocking manner. These functions suffer from the same act in a non-blocking manner. These functions suffer from the same
restrictions as PQconnectStart and PQconnectPoll. restrictions as <function>PQconnectStart</> and <function>PQconnectPoll</>.
</para> </para>
<para> <para>
Call PQresetStart. If it returns 0, the reset has failed. If it returns 1, Call <function>PQresetStart</function>. If it returns 0, the reset has failed. If it returns 1,
poll the reset using PQresetPoll in exactly the same way as you would poll the reset using <function>PQresetPoll</function> in exactly the same way as you would
create the connection using PQconnectPoll. create the connection using <function>PQconnectPoll</function>.
</para> </para>
</listitem> </listitem>
@ -492,13 +521,13 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn);
</para> </para>
<para> <para>
libpq application programmers should be careful to <application>libpq</application> application programmers should be careful to
maintain the PGconn abstraction. Use the accessor functions below to get maintain the <structname>PGconn</structname> abstraction. Use the accessor functions below to get
at the contents of PGconn. Avoid directly referencing the fields of the at the contents of <structname>PGconn</structname>. Avoid directly referencing the fields of the
PGconn structure because they are subject to change in the future. <structname>PGconn</> structure because they are subject to change in the future.
(Beginning in <productname>Postgres</productname> release 6.4, the (Beginning in <productname>PostgreSQK</productname> release 6.4, the
definition of struct PGconn is not even provided in <filename>libpq-fe.h</filename>. definition of struct <structname>PGconn</structname> is not even provided in <filename>libpq-fe.h</filename>.
If you have old code that accesses PGconn fields directly, you can keep using it If you have old code that accesses <structname>PGconn</structname> fields directly, you can keep using it
by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
soon.) soon.)
<itemizedlist> <itemizedlist>
@ -509,8 +538,8 @@ soon.)
<synopsis> <synopsis>
char *PQdb(const PGconn *conn) char *PQdb(const PGconn *conn)
</synopsis> </synopsis>
PQdb and the next several functions return the values established <function>PQdb</> and the next several functions return the values established
at connection. These values are fixed for the life of the PGconn at connection. These values are fixed for the life of the <structname>PGconn</>
object. object.
</para> </para>
</listitem> </listitem>
@ -558,7 +587,7 @@ char *PQport(const PGconn *conn)
<listitem> <listitem>
<para> <para>
<function>PQtty</function> <function>PQtty</function>
Returns the debug tty of the connection. Returns the debug <acronym>tty</acronym> of the connection.
<synopsis> <synopsis>
char *PQtty(const PGconn *conn) char *PQtty(const PGconn *conn)
</synopsis> </synopsis>
@ -603,7 +632,7 @@ ConnStatusType PQstatus(const PGconn *conn)
</para> </para>
<para> <para>
See the entry for PQconnectStart and PQconnectPoll with regards See the entry for <function>PQconnectStart</> and <function>PQconnectPoll</> with regards
to other status codes to other status codes
that might be seen. that might be seen.
</para> </para>
@ -620,9 +649,9 @@ char *PQerrorMessage(const PGconn* conn);
</para> </para>
<para> <para>
Nearly all libpq functions will set Nearly all <application>libpq</> functions will set
<function>PQerrorMessage</function> if they fail. <function>PQerrorMessage</function> if they fail.
Note that by libpq convention, a non-empty Note that by <application>libpq</application> convention, a non-empty
<function>PQerrorMessage</function> will <function>PQerrorMessage</function> will
include a trailing newline. include a trailing newline.
</para> </para>
@ -655,13 +684,13 @@ int PQbackendPID(const PGconn *conn);
SSL *PQgetssl(const PGconn *conn); SSL *PQgetssl(const PGconn *conn);
</synopsis> </synopsis>
This structure can be used to verify encryption levels, check This structure can be used to verify encryption levels, check
server certificate and more. Refer to the OpenSSL documentation server certificate and more. Refer to the SSL documentation
for information about this structure. for information about this structure.
</para> </para>
<para> <para>
You must define <literal>USE_SSL</literal> in order to get the You must define <literal>USE_SSL</literal> in order to get the
prototype for this function. Doing this will also prototype for this function. Doing this will also
automatically include <filename>ssl.h</filename> from OpenSSL. automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
</para> </para>
</listitem> </listitem>
@ -684,19 +713,19 @@ SQL queries and commands.
<listitem> <listitem>
<para> <para>
<function>PQexec</function> <function>PQexec</function>
Submit a query to <productname>Postgres</productname> Submit a query to the server
and wait for the result. and wait for the result.
<synopsis> <synopsis>
PGresult *PQexec(PGconn *conn, PGresult *PQexec(PGconn *conn,
const char *query); const char *query);
</synopsis> </synopsis>
Returns a PGresult pointer or possibly a NULL pointer. Returns a <structname>PGresult</structname> pointer or possibly a NULL pointer.
A non-NULL pointer will generally be returned except in A non-NULL pointer will generally be returned except in
out-of-memory conditions or serious errors such as inability out-of-memory conditions or serious errors such as inability
to send the query to the backend. to send the query to the backend.
If a NULL is returned, it If a NULL is returned, it
should be treated like a PGRES_FATAL_ERROR result. Use should be treated like a <symbol>PGRES_FATAL_ERROR</symbol> result. Use
PQerrorMessage to get more information about the error. <function>PQerrorMessage</function> to get more information about the error.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -705,13 +734,13 @@ PGresult *PQexec(PGconn *conn,
The <function>PGresult</function> structure encapsulates the query result The <function>PGresult</function> structure encapsulates the query result
returned by the backend. returned by the backend.
<filename>libpq</filename> application programmers should be careful to <filename>libpq</filename> application programmers should be careful to
maintain the PGresult abstraction. Use the accessor functions below to get maintain the <structname>PGresult</structname> abstraction. Use the accessor functions below to get
at the contents of PGresult. Avoid directly referencing the fields of the at the contents of <structname>PGresult</structname>. Avoid directly referencing the fields of the
PGresult structure because they are subject to change in the future. <structname>PGresult</structname> structure because they are subject to change in the future.
(Beginning in <productname>Postgres</productname> release 6.4, the (Beginning in <productname>PostgreSQL</productname> 6.4, the
definition of struct PGresult is not even provided in libpq-fe.h. If you definition of struct <structname>PGresult</structname> is not even provided in <filename>libpq-fe.h</>. If you
have old code that accesses PGresult fields directly, you can keep using it have old code that accesses <structname>PGresult</structname> fields directly, you can keep using it
by including libpq-int.h too, but you are encouraged to fix the code by including <filename>libpq-int.h</filename> too, but you are encouraged to fix the code
soon.) soon.)
</para> </para>
@ -723,7 +752,8 @@ soon.)
<synopsis> <synopsis>
ExecStatusType PQresultStatus(const PGresult *res) ExecStatusType PQresultStatus(const PGresult *res)
</synopsis> </synopsis>
PQresultStatus can return one of the following values: <function>PQresultStatus</function> can return one of the following values:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>PGRES_EMPTY_QUERY</literal> -- The string sent to the backend was empty.</para> <para><literal>PGRES_EMPTY_QUERY</literal> -- The string sent to the backend was empty.</para>
@ -783,10 +813,10 @@ char *PQresultErrorMessage(const PGresult *res);
Immediately following a <function>PQexec</function> or <function>PQgetResult</function> Immediately following a <function>PQexec</function> or <function>PQgetResult</function>
call, <function>PQerrorMessage</function> (on the connection) will return the same call, <function>PQerrorMessage</function> (on the connection) will return the same
string as <function>PQresultErrorMessage</function> (on the result). However, a string as <function>PQresultErrorMessage</function> (on the result). However, a
PGresult will retain its error message <structname>PGresult</structname> will retain its error message
until destroyed, whereas the connection's error message will change when until destroyed, whereas the connection's error message will change when
subsequent operations are done. Use <function>PQresultErrorMessage</function> when you want to subsequent operations are done. Use <function>PQresultErrorMessage</function> when you want to
know the status associated with a particular PGresult; use <function>PQerrorMessage</function> know the status associated with a particular <structname>PGresult</structname>; use <function>PQerrorMessage</function>
when you want to know the status from the latest operation on the connection. when you want to know the status from the latest operation on the connection.
</para> </para>
</listitem> </listitem>
@ -794,13 +824,13 @@ when you want to know the status from the latest operation on the connection.
<listitem> <listitem>
<para> <para>
<function>PQclear</function> <function>PQclear</function>
Frees the storage associated with the PGresult. Frees the storage associated with the <structname>PGresult</structname>.
Every query result should be freed via PQclear when Every query result should be freed via <function>PQclear</function> when
it is no longer needed. it is no longer needed.
<synopsis> <synopsis>
void PQclear(PQresult *res); void PQclear(PQresult *res);
</synopsis> </synopsis>
You can keep a PGresult object around for as long as you You can keep a <structname>PGresult</structname> object around for as long as you
need it; it does not go away when you issue a new query, need it; it does not go away when you issue a new query,
nor even if you close the connection. To get rid of it, nor even if you close the connection. To get rid of it,
you must call <function>PQclear</function>. Failure to do this will you must call <function>PQclear</function>. Failure to do this will
@ -811,17 +841,17 @@ void PQclear(PQresult *res);
<listitem> <listitem>
<para> <para>
<function>PQmakeEmptyPGresult</function> <function>PQmakeEmptyPGresult</function>
Constructs an empty PGresult object with the given status. Constructs an empty <structname>PGresult</structname> object with the given status.
<synopsis> <synopsis>
PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status); PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
</synopsis> </synopsis>
This is libpq's internal routine to allocate and initialize an empty This is <application>libpq</>'s internal routine to allocate and initialize an empty
PGresult object. It is exported because some applications find it <structname>PGresult</structname> object. It is exported because some applications find it
useful to generate result objects (particularly objects with error useful to generate result objects (particularly objects with error
status) themselves. If conn is not NULL and status indicates an error, status) themselves. If <parameter>conn</parameter> is not NULL and status indicates an error,
the connection's current errorMessage is copied into the PGresult. the connection's current errorMessage is copied into the <structname>PGresult.</structname>
Note that PQclear should eventually be called on the object, just Note that <function>PQclear</function> should eventually be called on the object, just
as with a PGresult returned by libpq itself. as with a <structname>PGresult</structname> returned by <application>libpq</application> itself.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -960,7 +990,7 @@ int PQfmod(const PGresult *res,
int PQfsize(const PGresult *res, int PQfsize(const PGresult *res,
int field_index); int field_index);
</synopsis> </synopsis>
PQfsize returns the space allocated for this field in a database <function>PQfsize</> returns the space allocated for this field in a database
tuple, in other words the size of the server's binary representation tuple, in other words the size of the server's binary representation
of the data type. -1 is returned if the field is variable size. of the data type. -1 is returned if the field is variable size.
</para> </para>
@ -990,7 +1020,7 @@ extracts data from a <acronym>BINARY</acronym> cursor.
<para> <para>
<function>PQgetvalue</function> <function>PQgetvalue</function>
Returns a single field (attribute) value of one tuple Returns a single field (attribute) value of one tuple
of a PGresult. of a <structname>PGresult</structname>.
Tuple and field indices start at 0. Tuple and field indices start at 0.
<synopsis> <synopsis>
char* PQgetvalue(const PGresult *res, char* PQgetvalue(const PGresult *res,
@ -1007,10 +1037,10 @@ type in the internal format of the backend server
It is then the programmer's responsibility to cast and It is then the programmer's responsibility to cast and
convert the data to the correct C type. The pointer convert the data to the correct C type. The pointer
returned by <function>PQgetvalue</function> points to storage that is returned by <function>PQgetvalue</function> points to storage that is
part of the PGresult structure. One should not modify it, part of the <structname>PGresult</structname> structure. One should not modify it,
and one must explicitly and one must explicitly
copy the value into other storage if it is to copy the value into other storage if it is to
be used past the lifetime of the PGresult structure itself. be used past the lifetime of the <structname>PGresult</structname> structure itself.
</para> </para>
</listitem> </listitem>
@ -1025,7 +1055,7 @@ int PQgetisnull(const PGresult *res,
int field_num); int field_num);
</synopsis> </synopsis>
This function returns 1 if the field contains a NULL, 0 if This function returns 1 if the field contains a NULL, 0 if
it contains a non-null value. (Note that PQgetvalue it contains a non-null value. (Note that <function>PQgetvalue</function>
will return an empty string, not a null pointer, for a NULL will return an empty string, not a null pointer, for a NULL
field.) field.)
</para> </para>
@ -1042,8 +1072,8 @@ int PQgetlength(const PGresult *res,
int field_num); int field_num);
</synopsis> </synopsis>
This is the actual data length for the particular data value, that is the This is the actual data length for the particular data value, that is the
size of the object pointed to by PQgetvalue. Note that for ASCII-represented size of the object pointed to by <function>PQgetvalue</function>. Note that for character-represented
values, this size has little to do with the binary size reported by PQfsize. values, this size has little to do with the binary size reported by <function>PQfsize</function>.
</para> </para>
</listitem> </listitem>
@ -1086,7 +1116,7 @@ function is no longer actively supported.
<para> <para>
<function>PQcmdStatus</function> <function>PQcmdStatus</function>
Returns the command status string from the SQL command that Returns the command status string from the SQL command that
generated the PGresult. generated the <structname>PGresult</structname>.
<synopsis> <synopsis>
char * PQcmdStatus(const PGresult *res); char * PQcmdStatus(const PGresult *res);
</synopsis> </synopsis>
@ -1101,7 +1131,7 @@ char * PQcmdStatus(const PGresult *res);
char * PQcmdTuples(const PGresult *res); char * PQcmdTuples(const PGresult *res);
</synopsis> </synopsis>
If the <acronym>SQL</acronym> command that generated the If the <acronym>SQL</acronym> command that generated the
PGresult was INSERT, UPDATE or DELETE, this returns a <structname>PGresult</structname> was INSERT, UPDATE or DELETE, this returns a
string containing the number of rows affected. If the string containing the number of rows affected. If the
command was anything else, it returns the empty string. command was anything else, it returns the empty string.
</para> </para>
@ -1168,8 +1198,8 @@ done from a signal handler, but not otherwise.)
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PQexec</function> can return only one PGresult structure. If the submitted query <function>PQexec</function> can return only one <structname>PGresult</structname> structure. If the submitted query
string contains multiple <acronym>SQL</acronym> commands, all but the last PGresult are string contains multiple <acronym>SQL</acronym> commands, all but the last <structname>PGresult</structname> are
discarded by <function>PQexec</function>. discarded by <function>PQexec</function>.
</para> </para>
</listitem> </listitem>
@ -1202,8 +1232,8 @@ connection to the backend.
<synopsis> <synopsis>
int PQsetnonblocking(PGconn *conn, int arg) int PQsetnonblocking(PGconn *conn, int arg)
</synopsis> </synopsis>
Sets the state of the connection to nonblocking if arg is TRUE, Sets the state of the connection to nonblocking if <parameter>arg</parameter> is 1,
blocking if arg is FALSE. Returns 0 if OK, -1 if error. blocking if <parameter>arg</parameter> is 0. Returns 0 if OK, -1 if error.
</para> </para>
<para> <para>
In the nonblocking state, calls to In the nonblocking state, calls to
@ -1219,7 +1249,7 @@ int PQsetnonblocking(PGconn *conn, int arg)
completes. completes.
</para> </para>
<para> <para>
More of libpq is expected to be made safe for More of <application>libpq</application> is expected to be made safe for
<function>PQsetnonblocking</function> functionality in the near future. <function>PQsetnonblocking</function> functionality in the near future.
</para> </para>
</listitem> </listitem>
@ -1231,17 +1261,17 @@ int PQsetnonblocking(PGconn *conn, int arg)
<synopsis> <synopsis>
int PQisnonblocking(const PGconn *conn) int PQisnonblocking(const PGconn *conn)
</synopsis> </synopsis>
Returns TRUE if the connection is set to non-blocking mode, Returns 1 if the connection is set to non-blocking mode,
FALSE if blocking. 0 if blocking.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
<function>PQsendQuery</function> <function>PQsendQuery</function>
Submit a query to <productname>Postgres</productname> without Submit a query to <productname>PostgreSQL</productname> without
waiting for the result(s). TRUE is returned if the query was waiting for the result(s). 1 is returned if the query was
successfully dispatched, FALSE if not (in which case, use successfully dispatched, 0 if not (in which case, use
PQerrorMessage to get more information about the failure). PQerrorMessage to get more information about the failure).
<synopsis> <synopsis>
int PQsendQuery(PGconn *conn, int PQsendQuery(PGconn *conn,
@ -1400,7 +1430,7 @@ can also attempt to cancel a query that is still being processed by the backend.
<listitem> <listitem>
<para> <para>
<function>PQrequestCancel</function> <function>PQrequestCancel</function>
Request that <productname>Postgres</productname> abandon Request that <productname>PostgreSQL</productname> abandon
processing of the current query. processing of the current query.
<synopsis> <synopsis>
int PQrequestCancel(PGconn *conn); int PQrequestCancel(PGconn *conn);
@ -1430,7 +1460,7 @@ will abort the whole transaction.
So, it is also possible to use it in conjunction with plain So, it is also possible to use it in conjunction with plain
<function>PQexec</function>, if the decision to cancel can be made in a signal <function>PQexec</function>, if the decision to cancel can be made in a signal
handler. For example, <application>psql</application> invokes handler. For example, <application>psql</application> invokes
<function>PQrequestCancel</function> from a SIGINT signal handler, thus allowing <function>PQrequestCancel</function> from a <systemitem>SIGINT</> signal handler, thus allowing
interactive cancellation of queries that it issues through <function>PQexec</function>. interactive cancellation of queries that it issues through <function>PQexec</function>.
Note that <function>PQrequestCancel</function> will have no effect if the connection Note that <function>PQrequestCancel</function> will have no effect if the connection
is not currently open or the backend is not currently processing a query. is not currently open or the backend is not currently processing a query.
@ -1442,7 +1472,7 @@ is not currently open or the backend is not currently processing a query.
<title>Fast Path</title> <title>Fast Path</title>
<para> <para>
<productname>Postgres</productname> provides a fast path interface to send <productname>PostgreSQL</productname> provides a fast path interface to send
function calls to the backend. This is a trapdoor into system internals and function calls to the backend. This is a trapdoor into system internals and
can be a potential security hole. Most users will not need this feature. can be a potential security hole. Most users will not need this feature.
@ -1460,19 +1490,19 @@ PGresult* PQfn(PGconn* conn,
const PQArgBlock *args, const PQArgBlock *args,
int nargs); int nargs);
</synopsis> </synopsis>
The fnid argument is the object identifier of the function to be The <parameter>fnid</> argument is the object identifier of the function to be
executed. executed.
result_buf is the buffer in which <parameter>result_buf</parameter> is the buffer in which
to place the return value. The caller must have allocated to place the return value. The caller must have allocated
sufficient space to store the return value (there is no check!). sufficient space to store the return value (there is no check!).
The actual result length will be returned in the integer pointed The actual result length will be returned in the integer pointed
to by result_len. If a 4-byte integer result is expected, set to by <parameter>result_len</parameter>. If a 4-byte integer result is expected, set
result_is_int to 1; otherwise set it to 0. (Setting result_is_int to 1 <parameter>result_is_int</parameter> to 1; otherwise set it to 0. (Setting <parameter>result_is_int</parameter> to 1
tells libpq to byte-swap the value if necessary, so that it is tells <application>libpq</> to byte-swap the value if necessary, so that it is
delivered as a proper int value for the client machine. When delivered as a proper int value for the client machine. When
result_is_int is 0, the byte string sent by the backend is returned result_is_int is 0, the byte string sent by the backend is returned
unmodified.) unmodified.)
args and nargs specify the arguments to be passed to the function. <parameter>args</> and <parameter>nargs</> specify the arguments to be passed to the function.
<synopsis> <synopsis>
typedef struct { typedef struct {
int len; int len;
@ -1483,9 +1513,9 @@ typedef struct {
} u; } u;
} PQArgBlock; } PQArgBlock;
</synopsis> </synopsis>
<function>PQfn</function> always returns a valid PGresult*. The resultStatus <function>PQfn</function> always returns a valid <structname>PGresult*</structname>. The resultStatus
should be checked before the result is used. The should be checked before the result is used. The
caller is responsible for freeing the PGresult with caller is responsible for freeing the <structname>PGresult</structname> with
<function>PQclear</function> when it is no longer needed. <function>PQclear</function> when it is no longer needed.
</para> </para>
</listitem> </listitem>
@ -1498,11 +1528,11 @@ typedef struct {
<title>Asynchronous Notification</title> <title>Asynchronous Notification</title>
<para> <para>
<productname>Postgres</productname> supports asynchronous notification via the <productname>PostgreSQL</productname> supports asynchronous notification via the
LISTEN and NOTIFY commands. A backend registers its interest in a particular <command>LISTEN</command> and <command>NOTIFY</command> commands. A backend registers its interest in a particular
notification condition with the LISTEN command (and can stop listening notification condition with the <command>LISTEN</command> command (and can stop listening
with the UNLISTEN command). All backends listening on a with the <command>UNLISTEN</command> command). All backends listening on a
particular condition will be notified asynchronously when a NOTIFY of that particular condition will be notified asynchronously when a <command>NOTIFY</command> of that
condition name is executed by any backend. No additional information is condition name is executed by any backend. No additional information is
passed from the notifier to the listener. Thus, typically, any actual data passed from the notifier to the listener. Thus, typically, any actual data
that needs to be communicated is transferred through a database relation. that needs to be communicated is transferred through a database relation.
@ -1511,9 +1541,9 @@ not necessary for there to be any associated relation.
</para> </para>
<para> <para>
<filename>libpq</filename> applications submit LISTEN and UNLISTEN <filename>libpq</filename> applications submit <command>LISTEN</command> and <command>UNLISTEN</command>
commands as ordinary SQL queries. Subsequently, arrival of NOTIFY commands as ordinary SQL queries. Subsequently, arrival of <command>NOTIFY</command>
messages can be detected by calling PQnotifies(). messages can be detected by calling <function>PQnotifies</function>.
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -1533,14 +1563,14 @@ typedef struct pgNotify {
int be_pid; /* process id of backend */ int be_pid; /* process id of backend */
} PGnotify; } PGnotify;
</synopsis> </synopsis>
After processing a PGnotify object returned by <function>PQnotifies</function>, After processing a <structname>PGnotify</structname> object returned by <function>PQnotifies</function>,
be sure to free it with <function>free()</function> to avoid a memory leak. be sure to free it with <function>free()</function> to avoid a memory leak.
</para> </para>
<note> <note>
<para> <para>
In <productname>Postgres</productname> 6.4 and later, In <productname>PostgreSQL</productname> 6.4 and later,
the <literal>be_pid</literal> is the notifying backend's, the <literal>be_pid</literal> is that of the notifying backend,
whereas in earlier versions it was always your own backend's <acronym>PID</acronym>. whereas in earlier versions it was always the <acronym>PID</acronym> of your own backend.
</para> </para>
</note> </note>
</listitem> </listitem>
@ -1589,7 +1619,7 @@ if any notifications came in during the processing of the query.
</indexterm> </indexterm>
<para> <para>
The COPY command in <productname>Postgres</productname> has options to read from The COPY command in <productname>PostgreSQL</productname> has options to read from
or write to the network connection used by <filename>libpq</filename>. or write to the network connection used by <filename>libpq</filename>.
Therefore, functions are necessary to access this network Therefore, functions are necessary to access this network
connection directly so applications may take advantage of this capability. connection directly so applications may take advantage of this capability.
@ -1660,7 +1690,7 @@ application should call <function>PQconsumeInput</function> and
end-of-data signal is detected. Unlike <function>PQgetline</function>, this routine takes end-of-data signal is detected. Unlike <function>PQgetline</function>, this routine takes
responsibility for detecting end-of-data. responsibility for detecting end-of-data.
On each call, <function>PQgetlineAsync</function> will return data if a complete newline- On each call, <function>PQgetlineAsync</function> will return data if a complete newline-
terminated data line is available in libpq's input buffer, or if the terminated data line is available in <application>libpq</>'s input buffer, or if the
incoming data line is too long to fit in the buffer offered by the caller. incoming data line is too long to fit in the buffer offered by the caller.
Otherwise, no data is returned until the rest of the line arrives. Otherwise, no data is returned until the rest of the line arrives.
</para> </para>
@ -1675,7 +1705,7 @@ the caller is too small to hold a line sent by the backend, then a partial
data line will be returned. This can be detected by testing whether the data line will be returned. This can be detected by testing whether the
last returned byte is "<literal>\n</literal>" or not. last returned byte is "<literal>\n</literal>" or not.
The returned string is not null-terminated. (If you want to add a The returned string is not null-terminated. (If you want to add a
terminating null, be sure to pass a bufsize one smaller than the room terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller than the room
actually available.) actually available.)
</para> </para>
</listitem> </listitem>
@ -1788,7 +1818,7 @@ void PQtrace(PGconn *conn
<listitem> <listitem>
<para> <para>
<function>PQuntrace</function> <function>PQuntrace</function>
Disable tracing started by PQtrace Disable tracing started by <function>PQtrace</function>.
<synopsis> <synopsis>
void PQuntrace(PGconn *conn) void PQuntrace(PGconn *conn)
</synopsis> </synopsis>
@ -1842,7 +1872,7 @@ defaultNoticeProcessor(void * arg, const char * message)
</programlisting> </programlisting>
To use a special notice processor, call To use a special notice processor, call
<function>PQsetNoticeProcessor</function> just after <function>PQsetNoticeProcessor</function> just after
creation of a new PGconn object. creation of a new <structname>PGconn</> object.
</para> </para>
<para> <para>
@ -1853,9 +1883,9 @@ but the current pointer is returned.
<para> <para>
Once you have set a notice processor, you should expect that that function Once you have set a notice processor, you should expect that that function
could be called as long as either the PGconn object or PGresult objects could be called as long as either the <structname>PGconn</> object or <structname>PGresult</> objects
made from it exist. At creation of a PGresult, the PGconn's current made from it exist. At creation of a <structname>PGresult</>, the <structname>PGconn</>'s current
notice processor pointer is copied into the PGresult for possible use by notice processor pointer is copied into the <structname>PGresult</> for possible use by
routines like <function>PQgetvalue</function>. routines like <function>PQgetvalue</function>.
</para> </para>
@ -1884,7 +1914,7 @@ application programs.
<envar>PGHOST</envar> sets the default server name. <envar>PGHOST</envar> sets the default server name.
If this begins with a slash, it specifies Unix-domain communication If this begins with a slash, it specifies Unix-domain communication
rather than TCP/IP communication; the value is the name of the rather than TCP/IP communication; the value is the name of the
directory in which the socket file is stored (default "/tmp"). directory in which the socket file is stored (default <filename>/tmp</filename>).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -1894,7 +1924,7 @@ directory in which the socket file is stored (default "/tmp").
</indexterm> </indexterm>
<envar>PGPORT</envar> sets the default TCP port number or Unix-domain <envar>PGPORT</envar> sets the default TCP port number or Unix-domain
socket file extension for communicating with the socket file extension for communicating with the
<productname>Postgres</productname> backend. <productname>PostgreSQL</productname> backend.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -1903,7 +1933,7 @@ socket file extension for communicating with the
<primary><envar>PGDATABASE</envar></primary> <primary><envar>PGDATABASE</envar></primary>
</indexterm> </indexterm>
<envar>PGDATABASE</envar> sets the default <envar>PGDATABASE</envar> sets the default
<productname>Postgres</productname> database name. <productname>PostgreSQL</productname> database name.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -1927,8 +1957,8 @@ sets the password used if the backend demands password authentication.
<listitem> <listitem>
<para> <para>
<envar>PGREALM</envar> sets the Kerberos realm to use with <envar>PGREALM</envar> sets the Kerberos realm to use with
<productname>Postgres</productname>, if it is different from the local realm. <productname>PostgreSQL</productname>, if it is different from the local realm.
If <envar>PGREALM</envar> is set, <productname>Postgres</productname> If <envar>PGREALM</envar> is set, <productname>PostgreSQL</productname>
applications will attempt authentication with servers for this realm and use applications will attempt authentication with servers for this realm and use
separate ticket files to avoid conflicts with local separate ticket files to avoid conflicts with local
ticket files. This environment variable is only ticket files. This environment variable is only
@ -1938,7 +1968,7 @@ used if Kerberos authentication is selected by the backend.
<listitem> <listitem>
<para> <para>
<envar>PGOPTIONS</envar> sets additional runtime options for <envar>PGOPTIONS</envar> sets additional runtime options for
the <productname>Postgres</productname> backend. the <productname>PostgreSQL</productname> backend.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -1952,7 +1982,7 @@ messages from the backend server are displayed.
<para> <para>
The following environment variables can be used to specify user-level default The following environment variables can be used to specify user-level default
behavior for every Postgres session: behavior for every <productname>PostgreSQL</productname> session:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -1971,7 +2001,7 @@ sets the default time zone.
<para> <para>
<envar>PGCLIENTENCODING</envar> <envar>PGCLIENTENCODING</envar>
sets the default client encoding (if MULTIBYTE support was selected sets the default client encoding (if MULTIBYTE support was selected
when configuring Postgres). when configuring <productname>PostgreSQL</productname>).
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -1979,7 +2009,7 @@ when configuring Postgres).
<para> <para>
The following environment variables can be used to specify default internal The following environment variables can be used to specify default internal
behavior for every Postgres session: behavior for every <productname>PostgreSQL</productname> session:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -2008,22 +2038,22 @@ for information on correct values for these environment variables.
<para> <para>
<filename>libpq</filename> is thread-safe as of <filename>libpq</filename> is thread-safe as of
<productname>Postgres</productname> 7.0, so long as no two threads <productname>PostgreSQL</productname> 7.0, so long as no two threads
attempt to manipulate the same PGconn object at the same time. In particular, attempt to manipulate the same <structname>PGconn</> object at the same time. In particular,
you can't issue concurrent queries from different threads through the same you cannot issue concurrent queries from different threads through the same
connection object. (If you need to run concurrent queries, start up multiple connection object. (If you need to run concurrent queries, start up multiple
connections.) connections.)
</para> </para>
<para> <para>
PGresult objects are read-only after creation, and so can be passed around <structname>PGresult</> objects are read-only after creation, and so can be passed around
freely between threads. freely between threads.
</para> </para>
<para> <para>
The deprecated functions <function>PQoidStatus</function> and The deprecated functions <function>PQoidStatus</function> and
<function>fe_setauthsvc</function> are not thread-safe and should not be <function>fe_setauthsvc</function> are not thread-safe and should not be
used in multi-thread programs. <function>PQoidStatus</function> can be used in multithread programs. <function>PQoidStatus</function> can be
replaced by <function>PQoidValue</function>. There is no good reason to replaced by <function>PQoidValue</function>. There is no good reason to
call <function>fe_setauthsvc</function> at all. call <function>fe_setauthsvc</function> at all.
</para> </para>
@ -2032,10 +2062,10 @@ call <function>fe_setauthsvc</function> at all.
<sect1 id="libpq-build"> <sect1 id="libpq-build">
<title>Building Libpq Programs</title> <title>Building <application>Libpq</application> Programs</title>
<para> <para>
To build (i.e., compile and link) your libpq programs you need to To build (i.e., compile and link) your <application>libpq</application> programs you need to
do all of the following things: do all of the following things:
<itemizedlist> <itemizedlist>
@ -2101,10 +2131,10 @@ testlibpq.c:8:22: libpq-fe.h: No such file or directory
<listitem> <listitem>
<para> <para>
When linking the final program, specify the option When linking the final program, specify the option
<literal>-lpq</literal> so that the libpq library gets pulled <literal>-lpq</literal> so that the <application>libpq</application> library gets pulled
in, as well as the option in, as well as the option
<literal>-L<replaceable>directory</replaceable></literal> to <literal>-L<replaceable>directory</replaceable></literal> to
point it to the directory where libpq resides. (Again, the point it to the directory where the <application>libpq</application> library resides. (Again, the
compiler will search some directories by default.) For maximum compiler will search some directories by default.) For maximum
portability, put the <option>-L</option> option before the portability, put the <option>-L</option> option before the
<option>-lpq</option> option. For example: <option>-lpq</option> option. For example:
@ -2158,7 +2188,7 @@ testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
<title>Example Programs</title> <title>Example Programs</title>
<example id="libpq-example-1"> <example id="libpq-example-1">
<title>libpq Example Program 1</title> <title><application>libpq</application> Example Program 1</title>
<programlisting> <programlisting>
/* /*
@ -2291,7 +2321,7 @@ main()
</example> </example>
<example id="libpq-example-2"> <example id="libpq-example-2">
<title>libpq Example Program 2</title> <title><application>libpq</application> Example Program 2</title>
<programlisting> <programlisting>
/* /*
@ -2411,7 +2441,7 @@ main()
</example> </example>
<example id="libpq-example-3"> <example id="libpq-example-3">
<title>libpq Example Program 3</> <title><application>libpq</application> Example Program 3</>
<programlisting> <programlisting>
/* /*

34
doc/src/sgml/lobj.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <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 objects interchangeably to mean the same thing in this
section.) section.)
Since <productname>PostgreSQL 7.1</productname> all large objects are placed in 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> </para>
</sect1> </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 <function>lseek(2)</function>, etc. User
functions call these routines to retrieve only the data of functions call these routines to retrieve only the data of
interest from a large object. For example, if a large 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 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 lower third of a photograph, and determine the color of
the beard that appeared there, if any. The entire the beard that appeared there, if any. The entire
large object value need not be buffered, or even large object value need not be buffered, or even
@ -116,7 +116,7 @@ Oid lo_creat(PGconn *<replaceable class="parameter">conn</replaceable>, int <rep
in in
<filename>$<envar>PGROOT</envar>/src/backend/libpq/libpq-fs.h</filename> <filename>$<envar>PGROOT</envar>/src/backend/libpq/libpq-fs.h</filename>
The access type (read, write, or both) is controlled by 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 <acronym>INV_WRITE</acronym>. The low-order sixteen bits of mask are
the storage manager number on which the large object the storage manager number on which the large object
should reside. For sites other than Berkeley, these should reside. For sites other than Berkeley, these
@ -151,8 +151,8 @@ Oid lo_import(PGconn *<replaceable class="parameter">conn</replaceable>, const c
<synopsis> <synopsis>
int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <replaceable class="parameter">lobjId</replaceable>, const char *<replaceable class="parameter">filename</replaceable>) int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <replaceable class="parameter">lobjId</replaceable>, const char *<replaceable class="parameter">filename</replaceable>)
</synopsis> </synopsis>
The lobjId argument specifies the Oid of the large The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to export and the filename argument specifies object to export and the <parameter>filename</parameter> argument specifies
the <acronym>UNIX</acronym> path name of the file. the <acronym>UNIX</acronym> path name of the file.
</para> </para>
</sect2> </sect2>
@ -165,9 +165,9 @@ int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <re
<synopsis> <synopsis>
int lo_open(PGconn *conn, Oid lobjId, int mode) int lo_open(PGconn *conn, Oid lobjId, int mode)
</synopsis> </synopsis>
The lobjId argument specifies the Oid of the large The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to open. The mode bits control whether the object to open. The <parameter>mode</parameter> bits control whether the
object is opened for reading INV_READ), writing or object is opened for reading (<symbol>INV_READ</>), writing or
both. both.
A large object cannot be opened before it is created. A large object cannot be opened before it is created.
<function>lo_open</function> returns a large object descriptor <function>lo_open</function> returns a large object descriptor
@ -185,7 +185,7 @@ int lo_open(PGconn *conn, Oid lobjId, int mode)
<programlisting> <programlisting>
int lo_write(PGconn *conn, int fd, const char *buf, size_t len) int lo_write(PGconn *conn, int fd, const char *buf, size_t len)
</programlisting> </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>. argument must have been returned by a previous <function>lo_open</function>.
The number of bytes actually written is returned. In The number of bytes actually written is returned. In
the event of an error, the return value is negative. 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> <programlisting>
int lo_read(PGconn *conn, int fd, char *buf, size_t len) int lo_read(PGconn *conn, int fd, char *buf, size_t len)
</programlisting> </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>. argument must have been returned by a previous <function>lo_open</function>.
The number of bytes actually read is returned. In The number of bytes actually read is returned. In
the event of an error, the return value is negative. the event of an error, the return value is negative.
@ -245,7 +245,7 @@ int lo_close(PGconn *conn, int fd)
<synopsis> <synopsis>
Oid lo_unlink(PGconn *<replaceable class="parameter">conn</replaceable>, Oid lobjId) Oid lo_unlink(PGconn *<replaceable class="parameter">conn</replaceable>, Oid lobjId)
</synopsis> </synopsis>
The lobjId argument specifies the Oid of the large The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to remove. object to remove.
</para> </para>
</sect2> </sect2>
@ -278,20 +278,20 @@ SELECT lo_export(image.raster, '/tmp/motd') from image
</sect1> </sect1>
<sect1 id="lo-libpq"> <sect1 id="lo-libpq">
<title>Accessing Large Objects from LIBPQ</title> <title>Accessing Large Objects from <application>Libpq</application></title>
<para> <para>
Below is a sample program which shows how the large object Below is a sample program which shows how the large object
interface 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 commented out but are left in the source for the readers
benefit. This program can be found in benefit. This program can be found in
<filename> <filename>
../src/test/examples ../src/test/examples
</filename> </filename>
Frontend applications which use the large object interface Frontend applications which use the large object interface
in LIBPQ should include the header file in <application>libpq</application> should include the header file
libpq/libpq-fs.h and link with the libpq library. <filename>libpq/libpq-fs.h</filename> and link with the <application>libpq</application> library.
</para> </para>
</sect1> </sect1>

72
doc/src/sgml/odbc.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/odbc.sgml,v 1.22 2001/05/12 22:51:35 petere Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/odbc.sgml,v 1.23 2001/09/10 21:58:47 petere Exp $
--> -->
<chapter id="odbc"> <chapter id="odbc">
@ -53,10 +53,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/odbc.sgml,v 1.22 2001/05/12 22:51:35
<para> <para>
The backend access come from <acronym>ODBC</acronym> drivers, The backend access come from <acronym>ODBC</acronym> drivers,
or vendor specifc drivers that or vendor-specific drivers that
allow data access. <productname>psqlODBC</productname> is such a driver, allow data access. <productname>psqlODBC</productname> is such a driver,
along with others that are along with others that are
available, such as the OpenLink <acronym>ODBC</acronym> drivers. available, such as the <productname>OpenLink</productname> <acronym>ODBC</acronym> drivers.
</para> </para>
<para> <para>
@ -133,8 +133,8 @@ psql -d template1 -f <replaceable>LOCATION</>/odbc.sql
<title>Supported Platforms</title> <title>Supported Platforms</title>
<para> <para>
<productname>psqlODBC</productname> has been built and tested <productname>psqlODBC</productname> has been built and tested
on <productname>Linux</productname>. There have been reports of success on <systemitem class="osname">Linux</>. There have been reports of success
with FreeBSD and with Solaris. There are no known restrictions with <systemitem class="osname">FreeBSD</> and with <systemitem class="osname">Solaris</>. There are no known restrictions
on the basic code for other platforms which already support on the basic code for other platforms which already support
<productname>Postgres</productname>. <productname>Postgres</productname>.
</para> </para>
@ -248,9 +248,9 @@ InstallDir = /opt/applix/axdata/axshlib
<listitem> <listitem>
<para> <para>
In Visual C++, you can use the CRecordSet class, which wraps the In Visual C++, you can use the <classname>CRecordSet</classname> class, which wraps the
<acronym>ODBC</acronym> <acronym>API</acronym> <acronym>ODBC</acronym> <acronym>API</acronym>
set within an MFC 4.2 class. This is the easiest route if you are doing set within an <application>MFC</application> 4.2 class. This is the easiest route if you are doing
Windows C++ development under Windows NT. Windows C++ development under Windows NT.
</para> </para>
</listitem> </listitem>
@ -277,7 +277,7 @@ InstallDir = /opt/applix/axdata/axshlib
</para> </para>
<para> <para>
Visual Basic and the other RAD tools have Recordset objects Visual Basic and the other <acronym>RAD</acronym> tools have <classname>Recordset</classname> objects
that use <acronym>ODBC</acronym> that use <acronym>ODBC</acronym>
directly to access data. Using the data-aware controls, you can quickly directly to access data. Using the data-aware controls, you can quickly
link to the <acronym>ODBC</acronym> back end database link to the <acronym>ODBC</acronym> back end database
@ -291,7 +291,7 @@ InstallDir = /opt/applix/axdata/axshlib
<tip> <tip>
<para> <para>
You'll have to set up a DSN first. You'll have to set up a <acronym>DSN</acronym> first.
</para> </para>
</tip> </tip>
@ -299,7 +299,7 @@ InstallDir = /opt/applix/axdata/axshlib
</sect1> </sect1>
<sect1 id="odbc-applixware"> <sect1 id="odbc-applixware">
<title>ApplixWare</title> <title><application>ApplixWare</application></title>
<indexterm zone="odbc-applixware"> <indexterm zone="odbc-applixware">
<primary>ApplixWare</primary> <primary>ApplixWare</primary>
@ -326,7 +326,7 @@ InstallDir = /opt/applix/axdata/axshlib
</para> </para>
<procedure> <procedure>
<title>Enabling ApplixWare Database Access</title> <title>Enabling <application>ApplixWare</application> Database Access</title>
<para> <para>
These instructions are for the <literal>4.4.2</literal> release of These instructions are for the <literal>4.4.2</literal> release of
@ -341,7 +341,7 @@ InstallDir = /opt/applix/axdata/axshlib
<filename>elfodbc</filename> can <filename>elfodbc</filename> can
find <filename>libodbc.so</filename> find <filename>libodbc.so</filename>
(the <acronym>ODBC</acronym> driver manager) shared library. (the <acronym>ODBC</acronym> driver manager) shared library.
This library is included with the ApplixWare distribution, This library is included with the <application>ApplixWare</application> distribution,
but <filename>axnet.cnf</filename> needs to be modified to point to the but <filename>axnet.cnf</filename> needs to be modified to point to the
correct location. correct location.
</para> </para>
@ -371,7 +371,7 @@ InstallDir = /opt/applix/axdata/axshlib
libFor elfodbc <replaceable>applixroot</replaceable>/applix/axdata/axshlib/lib libFor elfodbc <replaceable>applixroot</replaceable>/applix/axdata/axshlib/lib
</programlisting> </programlisting>
which will tell elfodbc to look in this directory which will tell <literal>elfodbc</literal> to look in this directory
for the <acronym>ODBC</acronym> support library. for the <acronym>ODBC</acronym> support library.
Typically <productname>Applix</productname> is installed in Typically <productname>Applix</productname> is installed in
<filename>/opt</filename> so the full path would be <filename>/opt</filename> so the full path would be
@ -399,7 +399,7 @@ TextAsLongVarchar=0
</procedure> </procedure>
<procedure> <procedure>
<title>Testing ApplixWare ODBC Connections</title> <title>Testing <application>ApplixWare</application> ODBC Connections</title>
<step performance="required"> <step performance="required">
<para> <para>
@ -424,7 +424,7 @@ TextAsLongVarchar=0
Select <acronym>ODBC</acronym>, and click <command>Browse</command>. Select <acronym>ODBC</acronym>, and click <command>Browse</command>.
The database you configured in <filename>.odbc.ini</filename> The database you configured in <filename>.odbc.ini</filename>
should be shown. Make sure that the <option>Host: field</option> should be shown. Make sure that the <option>Host: field</option>
is empty (if it is not, axnet will try to contact axnet on another machine is empty (if it is not, <literal>axnet</> will try to contact <literal>axnet</> on another machine
to look for the database). to look for the database).
</para> </para>
</step> </step>
@ -443,7 +443,7 @@ TextAsLongVarchar=0
</substeps> </substeps>
<para> <para>
You should see "<literal>Starting elfodbc server</literal>" You should see <literal>Starting elfodbc server</literal>
in the lower left corner of the in the lower left corner of the
data window. If you get an error dialog box, see the debugging section data window. If you get an error dialog box, see the debugging section
below. below.
@ -476,7 +476,7 @@ TextAsLongVarchar=0
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
Cannot launch gateway on server <computeroutput>Cannot launch gateway on server</computeroutput>
</term> </term>
<listitem> <listitem>
<para> <para>
@ -487,9 +487,9 @@ TextAsLongVarchar=0
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term><computeroutput>
Error from ODBC Gateway: Error from ODBC Gateway:
IM003::[iODBC][Driver Manager]Specified driver could not be loaded IM003::[iODBC][Driver Manager]Specified driver could not be loaded</computeroutput>
</term> </term>
<listitem> <listitem>
<para> <para>
@ -501,7 +501,7 @@ TextAsLongVarchar=0
<varlistentry> <varlistentry>
<term> <term>
Server: Broken Pipe <computeroutput>Server: Broken Pipe</computeroutput>
</term> </term>
<listitem> <listitem>
@ -516,15 +516,15 @@ TextAsLongVarchar=0
<varlistentry> <varlistentry>
<term> <term>
setuid to 256: failed to launch gateway <computeroutput>setuid to 256: failed to launch gateway</computeroutput>
</term> </term>
<listitem> <listitem>
<para> <para>
The September release of ApplixWare v4.4.1 (the first release with official The September release of <application>ApplixWare</application> v4.4.1 (the first release with official
<acronym>ODBC</acronym> support under Linux) shows problems when user names <acronym>ODBC</acronym> support under Linux) shows problems when user names
exceed eight (8) characters in length. exceed eight (8) characters in length.
Problem description ontributed by Steve Campbell Problem description contributed by Steve Campbell
(<email>scampbell@lear.com</email>). (<email>scampbell@lear.com</email>).
</para> </para>
</listitem> </listitem>
@ -554,24 +554,24 @@ TextAsLongVarchar=0
</sect2> </sect2>
<sect2> <sect2>
<title>Debugging ApplixWare ODBC Connections</title> <title>Debugging <application>ApplixWare</application> ODBC Connections</title>
<para> <para>
One good tool for debugging connection problems uses the Unix system One good tool for debugging connection problems uses the Unix system
utility <application>strace</application>. utility <application>strace</application>.
</para> </para>
<procedure> <procedure>
<title>Debugging with strace</title> <title>Debugging with <command>strace</command></title>
<step performance="required"> <step performance="required">
<para> <para>
Start applixware. Start <application>ApplixWare</application>.
</para> </para>
</step> </step>
<step performance="required"> <step performance="required">
<para> <para>
Start an <application>strace</application> on Start an <application>strace</application> on
the axnet process. For example, if the <literal>axnet</literal> process. For example, if
<programlisting> <programlisting>
% ps -aucx | grep ax % ps -aucx | grep ax
@ -596,7 +596,7 @@ cary 27883 0.9 31.0 12692 4596 ? S 10:24 0:04 axmain
<step performance="required"> <step performance="required">
<para> <para>
Check the strace output. Check the <command>strace</command> output.
</para> </para>
<note> <note>
<title>Note from Cary</title> <title>Note from Cary</title>
@ -613,8 +613,8 @@ cary 27883 0.9 31.0 12692 4596 ? S 10:24 0:04 axmain
<para> <para>
For example, after getting For example, after getting
a "<literal>Cannot launch gateway on server</literal>", a <literal>Cannot launch gateway on server</literal>,
I ran strace on axnet and got I ran <command>strace</command> on <literal>axnet</literal> and got
<programlisting> <programlisting>
[pid 27947] open("/usr/lib/libodbc.so", O_RDONLY) = -1 ENOENT [pid 27947] open("/usr/lib/libodbc.so", O_RDONLY) = -1 ENOENT
@ -624,13 +624,13 @@ cary 27883 0.9 31.0 12692 4596 ? S 10:24 0:04 axmain
[pid 27947] write(2, "/usr2/applix/axdata/elfodbc: [pid 27947] write(2, "/usr2/applix/axdata/elfodbc:
can't load library 'libodbc.so'\n", 61) = -1 EIO (I/O error) can't load library 'libodbc.so'\n", 61) = -1 EIO (I/O error)
</programlisting> </programlisting>
So what is happening is that applix elfodbc is searching for libodbc.so, but it So what is happening is that <literal>applix elfodbc</literal> is searching for <filename>libodbc.so</filename>, but it
can't find it. That is why axnet.cnf needed to be changed. cannot find it. That is why <filename>axnet.cnf</filename> needed to be changed.
</para> </para>
</sect2> </sect2>
<sect2> <sect2>
<title>Running the ApplixWare Demo</title> <title>Running the <application>ApplixWare</application> Demo</title>
<para> <para>
In order to go through the In order to go through the
@ -645,7 +645,7 @@ can't load library 'libodbc.so'\n", 61) = -1 EIO (I/O error)
</para> </para>
<procedure> <procedure>
<title>Modifying the ApplixWare Demo</title> <title>Modifying the <application>ApplixWare</application> Demo</title>
<step performance="required"> <step performance="required">
<para> <para>
@ -683,7 +683,7 @@ can't load library 'libodbc.so'\n", 61) = -1 EIO (I/O error)
<step performance="required"> <step performance="required">
<para> <para>
Open the sqldemo.am file from the <application>Macro Editor</application>. Open the <filename>sqldemo.am</filename> file from the <application>Macro Editor</application>.
</para> </para>
</step> </step>
@ -734,7 +734,7 @@ can't load library 'libodbc.so'\n", 61) = -1 EIO (I/O error)
<para> <para>
You can add information about your You can add information about your
database login and password to the standard Applix start-up database login and password to the standard <application>Applix</application> start-up
macro file. This is an example macro file. This is an example
<filename>~/axhome/macros/login.am</filename> file: <filename>~/axhome/macros/login.am</filename> file:

18
doc/src/sgml/plperl.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <chapter id="plperl">
@ -21,7 +21,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.9 2001/06/22 21:37:14 momji
<para> <para>
The PL/Perl interpreter (when installed as trusted interpreter with 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 operations have been disabled in order to maintain the security of
the system. In general, the operations that are restricted are the system. In general, the operations that are restricted are
those that interact with the environment. This includes file handle those that interact with the environment. This includes file handle
@ -32,8 +32,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.9 2001/06/22 21:37:14 momji
</para> </para>
<para> <para>
When PL/Perl is installed as 'untrusted' interpreter (with name 'plperlu'), 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). everything is permitted, and any Perl code can be loaded (by superuser only).
</para> </para>
<sect1 id="plperl-install"> <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. The creation of the function will succeed, but executing it will not.
Note that if same function was created by superuser using language Note that if same function was created by superuser using language
'plperlu', execution would succeed. <literal>plperlu</>, execution would succeed.
</para> </para>
<para> <para>
Access to database itself from your perl function can be done via 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 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 $pg_dbh, and you can use that to make queries with database-handle named <varname>$pg_dbh</varname>, and you can use that to make queries with
normal DBI syntax. normal <acronym>DBI</> syntax.
</para> </para>
</sect1> </sect1>

14
doc/src/sgml/plpython.sgml
View File

@ -1,4 +1,4 @@
<!-- $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"> <chapter id="plpython">
<title>PL/Python - Python Procedural Language</title> <title>PL/Python - Python Procedural Language</title>
@ -49,9 +49,9 @@ def __plpython_procedure_myfunc_23456():
<para> <para>
PostgreSQL function variables are available in the global PostgreSQL function variables are available in the global
<varname>args</varname> list. In the <function>myfunc</function> <varname>args</varname> list. In the <function>myfunc</function>
example, args[0] contains whatever was passed in as the text example, <varname>args[0]</> contains whatever was passed in as the text
argument. For <literal>myfunc2(text, int4)</literal>, args[0] argument. For <literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
would contain the text variable and args[1] the int4 variable. would contain the <type>text</type> variable and <varname>args[1]</varname> the <type>integer</type> variable.
</para> </para>
<para> <para>
@ -59,12 +59,12 @@ def __plpython_procedure_myfunc_23456():
function calls. This variable is private static data. The global function calls. This variable is private static data. The global
dictionary GD is public data, available to all python functions dictionary GD is public data, available to all python functions
within a backend. Use with care. When the function is used in a 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 depending on the trigger event. Return 'None' or "OK" from the
python function to indicate the tuple is unmodified, "SKIP" to python function to indicate the tuple is unmodified, "SKIP" to
abort the event, or "MODIFIED" to indicate you've modified the abort the event, or "MODIFIED" to indicate you've modified the
tuple. If the trigger was called with arguments they are available 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>
<para> <para>
@ -98,7 +98,7 @@ def __plpython_procedure_myfunc_23456():
</para> </para>
<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>. <function>execute</function> and <function>prepare</function>.
Calling <function>plpy.execute</function> with a query string, and Calling <function>plpy.execute</function> with a query string, and
an optional limit argument, causes that query to be run, and the an optional limit argument, causes that query to be run, and the

162
doc/src/sgml/plsql.sgml
View File

@ -1,16 +1,16 @@
<!-- <!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.37 2001/09/10 06:35:34 ishii Exp $ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.38 2001/09/10 21:58:47 petere Exp $
--> -->
<chapter id="plpgsql"> <chapter id="plpgsql">
<title>PL/pgSQL - <acronym>SQL</acronym> Procedural Language</title> <title><application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language</title>
<indexterm zone="plpgsql"> <indexterm zone="plpgsql">
<primary>PL/pgSQL</primary> <primary>PL/pgSQL</primary>
</indexterm> </indexterm>
<para> <para>
PL/pgSQL is a loadable procedural language for the <application>PL/pgSQL</application> is a loadable procedural language for the
<productname>Postgres</productname> database system. <productname>Postgres</productname> database system.
</para> </para>
@ -24,7 +24,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.37 2001/09/10 06:35:34
<title>Overview</title> <title>Overview</title>
<para> <para>
The design goals of PL/pgSQL were to create a loadable procedural The design goals of <application>PL/pgSQL</> were to create a loadable procedural
language that language that
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -60,7 +60,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.37 2001/09/10 06:35:34
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
The PL/pgSQL call handler parses the function's source text and The <application>PL/pgSQL</> call handler parses the function's source text and
produces an internal binary instruction tree the first time the produces an internal binary instruction tree the first time the
function is called. The produced bytecode is identified function is called. The produced bytecode is identified
in the call handler by the object ID of the function. This ensures in the call handler by the object ID of the function. This ensures
@ -69,12 +69,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.37 2001/09/10 06:35:34
</para> </para>
<para> <para>
For all expressions and <acronym>SQL</acronym> statements used in For all expressions and <acronym>SQL</acronym> statements used in
the function, the PL/pgSQL bytecode interpreter creates a the function, the <application>PL/pgSQL</> bytecode interpreter creates a
prepared execution plan using the <acronym>SPI</acronym> manager's prepared execution plan using the <acronym>SPI</acronym> manager's
<function>SPI_prepare()</function> and <function>SPI_prepare()</function> and
<function>SPI_saveplan()</function> functions. This is done the <function>SPI_saveplan()</function> functions. This is done the
first time the individual first time the individual
statement is processed in the PL/pgSQL function. Thus, a function with statement is processed in the <application>PL/pgSQL</> function. Thus, a function with
conditional code that contains many statements for which execution conditional code that contains many statements for which execution
plans would be required, will only prepare and save those plans plans would be required, will only prepare and save those plans
that are really used during the lifetime of the database that are really used during the lifetime of the database
@ -102,18 +102,18 @@ END;
</para> </para>
<para> <para>
Because PL/pgSQL saves execution plans in this way, queries that appear Because <application>PL/pgSQL</application> saves execution plans in this way, queries that appear
directly in a PL/pgSQL function must refer to the same tables and fields directly in a <application>PL/pgSQL</application> function must refer to the same tables and fields
on every execution; that is, you cannot use a parameter as the name of on every execution; that is, you cannot use a parameter as the name of
a table or field in a query. To get around a table or field in a query. To get around
this restriction, you can construct dynamic queries using the PL/pgSQL this restriction, you can construct dynamic queries using the <application>PL/pgSQL</application>
EXECUTE statement --- at the price of constructing a new query plan EXECUTE statement --- at the price of constructing a new query plan
on every execution. on every execution.
</para> </para>
<para> <para>
Except for input/output conversion and calculation functions Except for input/output conversion and calculation functions
for user defined types, anything that can be defined in C language for user defined types, anything that can be defined in C language
functions can also be done with PL/pgSQL. It is possible to functions can also be done with <application>PL/pgSQL</application>. It is possible to
create complex conditional computation functions and later use create complex conditional computation functions and later use
them to define operators or use them in functional indexes. them to define operators or use them in functional indexes.
</para> </para>
@ -162,13 +162,13 @@ END;
</para> </para>
<para> <para>
With PL/pgSQL you can group a block of computation and a With <application>PL/pgSQL</application> you can group a block of computation and a
series of queries <emphasis>inside</emphasis> the series of queries <emphasis>inside</emphasis> the
database server, thus having the power of a procedural database server, thus having the power of a procedural
language and the ease of use of SQL, but saving lots of language and the ease of use of SQL, but saving lots of
time because you don't have the whole client/server time because you don't have the whole client/server
communication overhead. Your application will enjoy a communication overhead. Your application will enjoy a
considerable performance increase by using PL/pgSQL. considerable performance increase by using <application>PL/pgSQL</application>.
</para> </para>
</sect3> </sect3>
@ -176,9 +176,9 @@ END;
<title>SQL Support</title> <title>SQL Support</title>
<para> <para>
PL/pgSQL adds the power of a procedural language to the <application>PL/pgSQL</application> adds the power of a procedural language to the
flexibility and ease of <acronym>SQL</acronym>. With flexibility and ease of <acronym>SQL</acronym>. With
PL/pgSQL you can use all the datatypes, columns, operators <application>PL/pgSQL</application> you can use all the data types, columns, operators
and functions of SQL. and functions of SQL.
</para> </para>
</sect3> </sect3>
@ -187,7 +187,7 @@ END;
<title>Portability</title> <title>Portability</title>
<para> <para>
Because PL/pgSQL functions run inside PostgreSQL, these Because <application>PL/pgSQL</application> functions run inside PostgreSQL, these
functions will run on any platform where PostgreSQL functions will run on any platform where PostgreSQL
runs. Thus you can reuse code and have less development costs. runs. Thus you can reuse code and have less development costs.
</para> </para>
@ -195,13 +195,13 @@ END;
</sect2> </sect2>
<sect2 id="plpgsql-overview-developing-in-plpgsql"> <sect2 id="plpgsql-overview-developing-in-plpgsql">
<title>Developing in PL/pgSQL</title> <title>Developing in <application>PL/pgSQL</application></title>
<para> <para>
Developing in PL/pgSQL is pretty straight forward, especially Developing in <application>PL/pgSQL</application> is pretty straight forward, especially
if you have developed in other database procedural languages, if you have developed in other database procedural languages,
such as Oracle's PL/SQL. Two good ways of developing in such as Oracle's <application>PL/SQL</application>. Two good ways of developing in
PL/pgSQL are: <application>PL/pgSQL</application> are:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -212,18 +212,18 @@ END;
<listitem> <listitem>
<para> <para>
Using PostgreSQL's GUI Tool: pgaccess Using PostgreSQL's GUI Tool: <application>PgAccess</>
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<para> <para>
One good way to develop in PL/pgSQL is to simply use the text One good way to develop in <application>PL/pgSQL</> is to simply use the text
editor of your choice to create your functions, and in another editor of your choice to create your functions, and in another
console, use <command>psql</command> (PostgreSQL's interactive monitor) to load console, use <command>psql</command> (PostgreSQL's interactive monitor) to load
those functions. If you are doing it this way (and if you are those functions. If you are doing it this way (and if you are
a PL/pgSQL novice or in debugging stage), it is a good idea to a <application>PL/pgSQL</> novice or in debugging stage), it is a good idea to
always <command>DROP</command> your function before creating it. That way always <command>DROP</command> your function before creating it. That way
when you reload the file, it'll drop your functions and then when you reload the file, it'll drop your functions and then
re-create them. For example: re-create them. For example:
@ -240,15 +240,15 @@ end;
When you load the file for the first time, When you load the file for the first time,
<productname>PostgreSQL</> will raise a warning saying this <productname>PostgreSQL</> will raise a warning saying this
function doesn't exist and go on to create it. To load an SQL function doesn't exist and go on to create it. To load an SQL
file (filename.sql) into a database named "dbname", use the command: file (e.g., <filename>filename.sql</filename>) into a database named <literal>dbname</literal>, use the command:
<programlisting> <programlisting>
psql -f filename.sql dbname psql -f filename.sql dbname
</programlisting> </programlisting>
</para> </para>
<para> <para>
Another good way to develop in PL/pgSQL is using Another good way to develop in <application>PL/pgSQL</> is using
<productname>PostgreSQL</>'s GUI tool: pgaccess. It does some <productname>PostgreSQL</>'s GUI tool: <application>PgAccess</>. It does some
nice things for you, like escaping single-quotes, and making nice things for you, like escaping single-quotes, and making
it easy to recreate and debug functions. it easy to recreate and debug functions.
</para> </para>
@ -263,10 +263,10 @@ psql -f filename.sql dbname
<!-- **** PL/pgSQL structure **** --> <!-- **** PL/pgSQL structure **** -->
<sect2> <sect2>
<title>Structure of PL/pgSQL</title> <title>Structure of <application>PL/pgSQL</application></title>
<para> <para>
PL/pgSQL is a <emphasis>block structured</emphasis> language. All <application>PL/pgSQL</application> is a <emphasis>block structured</emphasis> language. All
keywords and identifiers can be used in mixed upper and keywords and identifiers can be used in mixed upper and
lower-case. A block is defined as: lower-case. A block is defined as:
@ -316,8 +316,8 @@ END;
<para> <para>
It is important not to confuse the use of BEGIN/END for It is important not to confuse the use of BEGIN/END for
grouping statements in PL/pgSQL with the database commands for grouping statements in <application>PL/pgSQL</> with the database commands for
transaction control. PL/pgSQL's BEGIN/END are only for grouping; transaction control. <application>PL/pgSQL</>'s BEGIN/END are only for grouping;
they do not start or end a transaction. Functions and trigger procedures they do not start or end a transaction. Functions and trigger procedures
are always executed within a transaction established by an outer query are always executed within a transaction established by an outer query
--- they cannot start or commit transactions, since --- they cannot start or commit transactions, since
@ -329,7 +329,7 @@ END;
<title>Comments</title> <title>Comments</title>
<para> <para>
There are two types of comments in PL/pgSQL. A double dash <literal>--</literal> There are two types of comments in <application>PL/pgSQL</>. A double dash <literal>--</literal>
starts a comment that extends to the end of the line. A <literal>/*</literal> starts a comment that extends to the end of the line. A <literal>/*</literal>
starts a block comment that extends to the next occurrence of <literal>*/</literal>. starts a block comment that extends to the next occurrence of <literal>*/</literal>.
Block comments cannot be nested, but double dash comments can be Block comments cannot be nested, but double dash comments can be
@ -350,7 +350,7 @@ END;
</para> </para>
<para> <para>
PL/pgSQL variables can have any SQL datatype, such as <application>PL/pgSQL</> variables can have any SQL data type, such as
<type>INTEGER</type>, <type>VARCHAR</type> and <type>INTEGER</type>, <type>VARCHAR</type> and
<type>CHAR</type>. All variables have as default value the <type>CHAR</type>. All variables have as default value the
<acronym>SQL</acronym> NULL value. <acronym>SQL</acronym> NULL value.
@ -454,7 +454,7 @@ END;
values. For example, let's say you have a column values. For example, let's say you have a column
named <type>user_id</type> in your named <type>user_id</type> in your
<type>users</type> table. To declare a variable with <type>users</type> table. To declare a variable with
the same datatype as users.user_id you write: the same data type as <structname>users</>.<structfield>user_id</> you write:
<programlisting> <programlisting>
user_id users.user_id%TYPE; user_id users.user_id%TYPE;
</programlisting> </programlisting>
@ -474,7 +474,7 @@ user_id users.user_id%TYPE;
<varlistentry> <varlistentry>
<term> <term>
<replaceable>table</replaceable>%ROWTYPE <literal><replaceable>table</replaceable>%ROWTYPE</literal>
</term> </term>
<listitem> <listitem>
<para> <para>
@ -560,12 +560,12 @@ RENAME this_var TO that_var;
<title>Expressions</title> <title>Expressions</title>
<para> <para>
All expressions used in PL/pgSQL statements are processed using All expressions used in <application>PL/pgSQL</application> statements are processed using
the backend's executor. Expressions that appear to contain the executor of the server. Expressions that appear to contain
constants may in fact require run-time evaluation constants may in fact require run-time evaluation
(e.g. <literal>'now'</literal> for the (e.g. <literal>'now'</literal> for the
<type>timestamp</type> type) so <type>timestamp</type> type) so
it is impossible for the PL/pgSQL parser it is impossible for the <application>PL/pgSQL</application> parser
to identify real constant values other than the NULL keyword. All to identify real constant values other than the NULL keyword. All
expressions are evaluated internally by executing a query expressions are evaluated internally by executing a query
<synopsis> <synopsis>
@ -574,7 +574,7 @@ SELECT <replaceable>expression</replaceable>
using the <acronym>SPI</acronym> manager. In the expression, occurrences of variable using the <acronym>SPI</acronym> manager. In the expression, occurrences of variable
identifiers are substituted by parameters and the actual values from identifiers are substituted by parameters and the actual values from
the variables are passed to the executor in the parameter array. All the variables are passed to the executor in the parameter array. All
expressions used in a PL/pgSQL function are only prepared and expressions used in a <application>PL/pgSQL</application> function are only prepared and
saved once. The only exception to this rule is an EXECUTE statement saved once. The only exception to this rule is an EXECUTE statement
if parsing of a query is needed each time it is encountered. if parsing of a query is needed each time it is encountered.
</para> </para>
@ -615,7 +615,7 @@ CREATE FUNCTION logfunc2 (text) RETURNS timestamp AS '
<productname>Postgres</productname> main parser knows when <productname>Postgres</productname> main parser knows when
preparing the plan for the INSERT, that the string preparing the plan for the INSERT, that the string
<literal>'now'</literal> should be interpreted as <literal>'now'</literal> should be interpreted as
<type>timestamp</type> because the target field of logtable <type>timestamp</type> because the target field of <classname>logtable</classname>
is of that type. Thus, it will make a constant from it at this is of that type. Thus, it will make a constant from it at this
time and this constant value is then used in all invocations of time and this constant value is then used in all invocations of
<function>logfunc1()</function> during the lifetime of the <function>logfunc1()</function> during the lifetime of the
@ -629,19 +629,19 @@ CREATE FUNCTION logfunc2 (text) RETURNS timestamp AS '
what type <literal>'now'</literal> should become and therefore what type <literal>'now'</literal> should become and therefore
it returns a data type of <type>text</type> containing the string it returns a data type of <type>text</type> containing the string
<literal>'now'</literal>. During the assignment <literal>'now'</literal>. During the assignment
to the local variable curtime, the PL/pgSQL interpreter casts this to the local variable <varname>curtime</varname>, the <application>PL/pgSQL</application> interpreter casts this
string to the timestamp type by calling the string to the <type>timestamp</type> type by calling the
<function>text_out()</function> and <function>timestamp_in()</function> <function>text_out()</function> and <function>timestamp_in()</function>
functions for the conversion. functions for the conversion.
</para> </para>
<para> <para>
This type checking done by the <productname>Postgres</productname> main This type checking done by the <productname>Postgres</productname> main
parser got implemented after PL/pgSQL was nearly done. parser got implemented after <application>PL/pgSQL</application> was nearly done.
It is a difference between 6.3 and 6.4 and affects all functions It is a difference between 6.3 and 6.4 and affects all functions
using the prepared plan feature of the <acronym>SPI</acronym> manager. using the prepared plan feature of the <acronym>SPI</acronym> manager.
Using a local Using a local
variable in the above manner is currently the only way in PL/pgSQL to get variable in the above manner is currently the only way in <application>PL/pgSQL</application> to get
those values interpreted correctly. those values interpreted correctly.
</para> </para>
@ -659,7 +659,7 @@ CREATE FUNCTION logfunc2 (text) RETURNS timestamp AS '
<title>Statements</title> <title>Statements</title>
<para> <para>
Anything not understood by the PL/pgSQL parser as specified below Anything not understood by the <application>PL/pgSQL</application> parser as specified below
will be put into a query and sent down to the database engine will be put into a query and sent down to the database engine
to execute. The resulting query should not return any data. to execute. The resulting query should not return any data.
</para> </para>
@ -675,8 +675,8 @@ CREATE FUNCTION logfunc2 (text) RETURNS timestamp AS '
If the expressions result data type doesn't match the variables If the expressions result data type doesn't match the variables
data type, or the variable has a size/precision that is known data type, or the variable has a size/precision that is known
(as for <type>char(20)</type>), the result value will be implicitly casted by (as for <type>char(20)</type>), the result value will be implicitly cast by
the PL/pgSQL bytecode interpreter using the result types output- and the <application>PL/pgSQL</application> bytecode interpreter using the result types output- and
the variables type input-functions. Note that this could potentially the variables type input-functions. Note that this could potentially
result in runtime errors generated by the types input functions. result in runtime errors generated by the types input functions.
</para> </para>
@ -694,7 +694,7 @@ tax := subtotal * 0.06;
All functions defined in a <productname>Postgres</productname> All functions defined in a <productname>Postgres</productname>
database return a value. Thus, the normal way to call a function database return a value. Thus, the normal way to call a function
is to execute a SELECT query or doing an assignment (resulting is to execute a SELECT query or doing an assignment (resulting
in a PL/pgSQL internal SELECT). in a <application>PL/pgSQL</application> internal SELECT).
</para> </para>
<para> <para>
@ -722,8 +722,8 @@ PERFORM create_mv(''cs_session_page_requests_mv'',''
<para> <para>
Often times you will want to generate dynamic queries inside Often times you will want to generate dynamic queries inside
your PL/pgSQL functions. Or you have functions that will your <application>PL/pgSQL</application> functions. Or you have functions that will
generate other functions. PL/pgSQL provides the EXECUTE generate other functions. <application>PL/pgSQL</application> provides the EXECUTE
statement for these occasions. statement for these occasions.
</para> </para>
@ -738,13 +738,13 @@ EXECUTE <replaceable class="command">query-string</replaceable>
<para> <para>
When working with dynamic queries you will have to face When working with dynamic queries you will have to face
escaping of single quotes in PL/pgSQL. Please refer to the escaping of single quotes in <application>PL/pgSQL</>. Please refer to the
table available at the "Porting from Oracle PL/SQL" chapter table available at the "Porting from Oracle PL/SQL" chapter
for a detailed explanation that will save you some effort. for a detailed explanation that will save you some effort.
</para> </para>
<para> <para>
Unlike all other queries in PL/pgSQL, a Unlike all other queries in <application>PL/pgSQL</>, a
<replaceable>query</replaceable> run by an EXECUTE statement is <replaceable>query</replaceable> run by an EXECUTE statement is
not prepared and saved just once during the life of the server. not prepared and saved just once during the life of the server.
Instead, the <replaceable>query</replaceable> is prepared each Instead, the <replaceable>query</replaceable> is prepared each
@ -873,7 +873,7 @@ RETURN <replaceable>expression</replaceable>
<title>Control Structures</title> <title>Control Structures</title>
<para> <para>
Control structures are probably the most useful (and Control structures are probably the most useful (and
important) part of PL/SQL. With PL/pgSQL's control structures, important) part of PL/SQL. With <application>PL/pgSQL</>'s control structures,
you can manipulate <productname>PostgreSQL</> data in a very you can manipulate <productname>PostgreSQL</> data in a very
flexible and powerful way. flexible and powerful way.
</para> </para>
@ -1022,8 +1022,8 @@ END IF;
<para> <para>
With the LOOP, WHILE, FOR and EXIT statements, you can With the LOOP, WHILE, FOR and EXIT statements, you can
control the flow of execution of your PL/pgSQL program control the flow of execution of your <application>PL/pgSQL</application> program
iteratively. iteractively.
</para> </para>
<variablelist> <variablelist>
@ -1208,7 +1208,7 @@ SELECT INTO <replaceable>target</replaceable> <replaceable>expressions</replace
record-/row-fields. Note that this is quite different from record-/row-fields. Note that this is quite different from
Postgres' normal interpretation of SELECT INTO, which is that the Postgres' normal interpretation of SELECT INTO, which is that the
INTO target is a newly created table. (If you want to create a INTO target is a newly created table. (If you want to create a
table from a SELECT result inside a PL/pgSQL function, use the table from a SELECT result inside a <application>PL/pgSQL</application> function, use the
equivalent syntax <command>CREATE TABLE AS SELECT</command>.) equivalent syntax <command>CREATE TABLE AS SELECT</command>.)
</para> </para>
@ -1344,7 +1344,7 @@ END LOOP;
<para> <para>
Use the RAISE statement to throw messages into the Use the RAISE statement to throw messages into the
<productname>Postgres</productname> elog mechanism. <productname>Postgres</productname> <function>elog</function> mechanism.
<synopsis> <synopsis>
RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">variable</replaceable> <optional>...</optional></optional>; RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">variable</replaceable> <optional>...</optional></optional>;
@ -1407,7 +1407,7 @@ RAISE EXCEPTION ''Inexistent ID --> %'',user_id;
</para> </para>
<para> <para>
Thus, the only thing PL/pgSQL currently does when it encounters Thus, the only thing <application>PL/pgSQL</application> currently does when it encounters
an abort during execution of a function or trigger an abort during execution of a function or trigger
procedure is to write some additional NOTICE level log messages procedure is to write some additional NOTICE level log messages
telling in which function and where (line number and type of telling in which function and where (line number and type of
@ -1423,7 +1423,7 @@ RAISE EXCEPTION ''Inexistent ID --> %'',user_id;
<title>Trigger Procedures</title> <title>Trigger Procedures</title>
<para> <para>
PL/pgSQL can be used to define trigger procedures. They are created <application>PL/pgSQL</application> can be used to define trigger procedures. They are created
with the usual <command>CREATE FUNCTION</command> command as a function with no with the usual <command>CREATE FUNCTION</command> command as a function with no
arguments and a return type of <type>OPAQUE</type>. arguments and a return type of <type>OPAQUE</type>.
</para> </para>
@ -1559,7 +1559,7 @@ RAISE EXCEPTION ''Inexistent ID --> %'',user_id;
</para> </para>
<example> <example>
<title>A PL/pgSQL Trigger Procedure Example</title> <title>A <application>PL/pgSQL</application> Trigger Procedure Example</title>
<para> <para>
This trigger ensures, that any time a row is inserted or updated This trigger ensures, that any time a row is inserted or updated
@ -1611,13 +1611,13 @@ CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
<para> <para>
Here are only a few functions to demonstrate how easy it is to Here are only a few functions to demonstrate how easy it is to
write PL/pgSQL write <application>PL/pgSQL</>
functions. For more complex examples the programmer functions. For more complex examples the programmer
might look at the regression test for PL/pgSQL. might look at the regression test for <application>PL/pgSQL</>.
</para> </para>
<para> <para>
One painful detail in writing functions in PL/pgSQL is the handling One painful detail in writing functions in <application>PL/pgSQL</application> is the handling
of single quotes. The function's source text on <command>CREATE FUNCTION</command> must of single quotes. The function's source text on <command>CREATE FUNCTION</command> must
be a literal string. Single quotes inside of literal strings must be be a literal string. Single quotes inside of literal strings must be
either doubled or quoted with a backslash. We are still looking for either doubled or quoted with a backslash. We are still looking for
@ -1633,10 +1633,10 @@ CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
</para> </para>
<example> <example>
<title>A Simple PL/pgSQL Function to Increment an Integer</title> <title>A Simple <application>PL/pgSQL</application> Function to Increment an Integer</title>
<para> <para>
The following two PL/pgSQL functions are identical to their The following two <application>PL/pgSQL</application> functions are identical to their
counterparts from the C language function discussion. This counterparts from the C language function discussion. This
function receives an <type>integer</type> and increments it by function receives an <type>integer</type> and increments it by
one, returning the incremented value. one, returning the incremented value.
@ -1652,7 +1652,7 @@ CREATE FUNCTION add_one (integer) RETURNS integer AS '
</example> </example>
<example> <example>
<title>A Simple PL/pgSQL Function to Concatenate Text</title> <title>A Simple <application>PL/pgSQL</application> Function to Concatenate Text</title>
<para> <para>
This function receives two <type>text</type> parameters and This function receives two <type>text</type> parameters and
@ -1669,16 +1669,16 @@ CREATE FUNCTION concat_text (text, text) RETURNS text AS '
</example> </example>
<example> <example>
<title>A PL/pgSQL Function on Composite Type</title> <title>A <application>PL/pgSQL</application> Function on Composite Type</title>
<para> <para>
In this example, we take EMP (a table) and an In this example, we take <literal>EMP</> (a table) and an
<type>integer</type> as arguments to our function, which returns <type>integer</type> as arguments to our function, which returns
a <type>boolean</type>. If the "salary" field of the EMP table is a <type>boolean</type>. If the <structfield>salary</> field of the <structname>EMP</> table is
<literal>NULL</literal>, we return "f". Otherwise we compare with <literal>NULL</literal>, we return <literal>f</>. Otherwise we compare with
that field with the <type>integer</type> passed to the function that field with the <type>integer</type> passed to the function
and return the <type>boolean</type> result of the comparison (t and return the <type>boolean</type> result of the comparison (t
or f). This is the PL/pgSQL equivalent to the example from the C or f). This is the <application>PL/pgSQL</application> equivalent to the example from the C
functions. functions.
</para> </para>
@ -1743,7 +1743,7 @@ CREATE FUNCTION c_overpaid (EMP, integer) RETURNS boolean AS '
<para> <para>
This section explains differences between Oracle's PL/SQL and This section explains differences between Oracle's PL/SQL and
PostgreSQL's PL/pgSQL languages in the hopes of helping developers PostgreSQL's <application>PL/pgSQL</application> languages in the hopes of helping developers
port applications from Oracle to PostgreSQL. Most of the code here port applications from Oracle to PostgreSQL. Most of the code here
is from the <ulink url="http://www.arsdigita.com">ArsDigita</ulink> is from the <ulink url="http://www.arsdigita.com">ArsDigita</ulink>
<ulink url="http://www.arsdigita.com/asj/clickstream">Clickstream <ulink url="http://www.arsdigita.com/asj/clickstream">Clickstream
@ -1753,10 +1753,10 @@ CREATE FUNCTION c_overpaid (EMP, integer) RETURNS boolean AS '
</para> </para>
<para> <para>
PL/pgSQL is similar to PL/SQL in many aspects. It is a block <application>PL/pgSQL</application> is similar to PL/SQL in many aspects. It is a block
structured, imperative language (all variables have to be structured, imperative language (all variables have to be
declared). PL/SQL has many more features than its PostgreSQL declared). PL/SQL has many more features than its PostgreSQL
counterpart, but PL/pgSQL allows for a great deal of functionality counterpart, but <application>PL/pgSQL</application> allows for a great deal of functionality
and it is being improved constantly. and it is being improved constantly.
</para> </para>
@ -1937,7 +1937,7 @@ SHOW ERRORS;
</para> </para>
<para> <para>
Let's go through this function and see the differences to PL/pgSQL: Let's go through this function and see the differences to <application>PL/pgSQL</>:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
@ -2100,7 +2100,7 @@ end;
<para> <para>
The following Oracle PL/SQL procedure is used to parse a URL and The following Oracle PL/SQL procedure is used to parse a URL and
return several elements (host, path and query). It is an return several elements (host, path and query). It is an
procedure because in PL/pgSQL functions only one value can be returned procedure because in <application>PL/pgSQL</application> functions only one value can be returned
(see <xref linkend="plpgsql-porting-procedures">). In (see <xref linkend="plpgsql-porting-procedures">). In
PostgreSQL, one way to work around this is to split the procedure PostgreSQL, one way to work around this is to split the procedure
in three different functions: one to return the host, another for in three different functions: one to return the host, another for
@ -2203,7 +2203,7 @@ end;
<para> <para>
Oracle procedures give a little more flexibility to the developer Oracle procedures give a little more flexibility to the developer
because nothing needs to be explicitly returned, but it can be because nothing needs to be explicitly returned, but it can be
through the use of INOUT or OUT parameters. through the use of <literal>INOUT</> or <literal>OUT</> parameters.
</para> </para>
<para> <para>
@ -2253,14 +2253,14 @@ show errors
<callout arearefs="co.plpgsql-porting-locktable"> <callout arearefs="co.plpgsql-porting-locktable">
<para> <para>
If you do a <literal>LOCK TABLE</literal> in PL/pgSQL, the lock If you do a <literal>LOCK TABLE</literal> in <application>PL/pgSQL</>, the lock
will not be released until the calling transaction is finished. will not be released until the calling transaction is finished.
</para> </para>
</callout> </callout>
<callout arearefs="co.plpgsql-porting-commit"> <callout arearefs="co.plpgsql-porting-commit">
<para> <para>
You also cannot have transactions in PL/pgSQL procedures. The You also cannot have transactions in <application>PL/pgSQL</application> procedures. The
entire function (and other functions called from therein) is entire function (and other functions called from therein) is
executed in a transaction and PostgreSQL rolls back the results if executed in a transaction and PostgreSQL rolls back the results if
something goes wrong. Therefore only one something goes wrong. Therefore only one
@ -2278,7 +2278,7 @@ show errors
</para> </para>
<para> <para>
So let's see one of the ways we could port this procedure to PL/pgSQL: So let's see one of the ways we could port this procedure to <application>PL/pgSQL</>:
<programlisting> <programlisting>
drop function cs_create_job(integer); drop function cs_create_job(integer);
@ -2316,7 +2316,7 @@ end;
<calloutlist> <calloutlist>
<callout arearefs="co.plpgsql-porting-raise"> <callout arearefs="co.plpgsql-porting-raise">
<para> <para>
Notice how you can raise notices (or errors) in PL/pgSQL. Notice how you can raise notices (or errors) in <application>PL/pgSQL</>.
</para> </para>
</callout> </callout>
</calloutlist> </calloutlist>
@ -2423,7 +2423,7 @@ END;
</sect3> </sect3>
<sect3 id="plpgsql-porting-optimization"> <sect3 id="plpgsql-porting-optimization">
<title>Optimizing PL/pgSQL Functions</title> <title>Optimizing <application>PL/pgSQL</application> Functions</title>
<para> <para>
PostgreSQL gives you two function creation modifiers to optimize PostgreSQL gives you two function creation modifiers to optimize

64
doc/src/sgml/pltcl.sgml
View File

@ -1,9 +1,9 @@
<!-- <!--
$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"> <chapter id="pltcl">
<title>PL/Tcl - TCL Procedural Language</title> <title>PL/Tcl - Tcl Procedural Language</title>
<indexterm zone="pltcl"> <indexterm zone="pltcl">
<primary>PL/Tcl</primary> <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 The good restriction is that everything is executed in a safe
Tcl interpreter. In addition to the limited command set of safe Tcl, only 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 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 database backend or to gain OS-level access under the permissions of the
<productname>Postgres</productname> user ID, as a C function can do. <productname>Postgres</productname> user ID, as a C function can do.
Thus, any unprivileged database user may be Thus, any unprivileged database user may be
@ -157,7 +157,7 @@ CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
</para> </para>
<para> <para>
To help protect PL/Tcl procedures from unwanted side effects, 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 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 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 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> <listitem>
<para> <para>
A Tcl list of the tables field names prefixed with an empty list element. 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 returns the same positive number starting from 1 as the fields are numbered
in the pg_attribute system catalog. in the pg_attribute system catalog.
</para> </para>
@ -344,7 +344,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
<indexterm> <indexterm>
<primary>elog</primary> <primary>elog</primary>
</indexterm> </indexterm>
<term>elog <replaceable>level</replaceable> <replaceable>msg</replaceable></term> <term><function>elog</> <replaceable>level</replaceable> <replaceable>msg</replaceable></term>
<listitem> <listitem>
<para> <para>
Fire a log message. Possible levels are NOTICE, ERROR, 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>
<varlistentry> <varlistentry>
<term>quote <replaceable>string</replaceable></term> <term><function>quote</> <replaceable>string</replaceable></term>
<listitem> <listitem>
<para> <para>
Duplicates all occurrences of single quote and backslash characters. 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> <indexterm>
<primary>spi_lastoid</primary> <primary>spi_lastoid</primary>
</indexterm> </indexterm>
<term>spi_lastoid</term> <term><function>spi_lastoid</></term>
<listitem> <listitem>
<para> <para>
Returns the OID of the last query if it was an INSERT. 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>
<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> <listitem>
<para> <para>
Call parser/planner/optimizer/executor for query. Call parser/planner/optimizer/executor for query.
@ -446,45 +446,45 @@ spi_exec -array C "SELECT * FROM pg_class" {
</varlistentry> </varlistentry>
<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> <listitem>
<para> <para>
Prepares AND SAVES a query plan for later execution. It is a bit different 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 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. plan without saving it.
</para> </para>
<para> <para>
If the query references arguments, the type names must be given as a Tcl 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 list. The return value from <function>spi_prepare</function> is a query ID to be used in
subsequent calls to spi_execp. See spi_execp for a sample. subsequent calls to <function>spi_execp</function>. See <function>spi_execp</function> for a sample.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<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> <listitem>
<para> <para>
Execute a prepared plan from spi_prepare with variable substitution. Execute a prepared plan from <function>spi_prepare</> with variable substitution.
The optional -count value tells spi_execp the maximum number of rows The optional <literal>-count</literal> value tells <function>spi_execp</> the maximum number of rows
to be processed by the query. to be processed by the query.
</para> </para>
<para> <para>
The optional value for -nulls is a string of spaces and 'n' characters The optional value for <literal>-nulls</> is a string of spaces and 'n' characters
telling spi_execp which of the values are NULL's. If given, it must 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. have exactly the length of the number of values.
</para> </para>
<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>
<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 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. the type list on spi_prepare was empty, this argument must be omitted.
</para> </para>
<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. happens for the loop-body and the variables for the fields selected.
</para> </para>
<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 Note that each backslash that Tcl should see must be doubled in
the query creating the function, since the main parser processes the query creating the function, since the main parser processes
backslashes too on CREATE FUNCTION. 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 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. $1 be substituted by the value given in the first function call.
</para> </para>
@ -515,18 +515,20 @@ CREATE FUNCTION t1_count(int4, int4) RETURNS int4 AS '
<varlistentry> <varlistentry>
<term> <term>
Modules and the unknown command Modules and the <function>unknown</> command
</term> </term>
<listitem> <listitem>
<para> <para>
PL/Tcl has a special support for things often used. It recognizes two PL/Tcl has a special support for things often used. It
magic tables, pltcl_modules and pltcl_modfuncs. recognizes two magic tables, <literal>pltcl_modules</> and
If these exist, the module 'unknown' is loaded into the interpreter <literal>pltcl_modfuncs</>. If these exist, the module
right after creation. Whenever an unknown Tcl procedure is called, 'unknown' is loaded into the interpreter right after
the unknown proc is asked to check if the procedure is defined in one creation. Whenever an unknown Tcl procedure is called, the
of the modules. If this is true, the module is loaded on demand. unknown proc is asked to check if the procedure is defined in
To enable this behavior, the PL/Tcl call handler must be compiled one of the modules. If this is true, the module is loaded on
with -DPLTCL_UNKNOWN_SUPPORT set. demand. To enable this behavior, the
<productname>PostgreSQL</> must be configured with the option
<option>--enable-pltcl-unknown</option>.
</para> </para>
<para> <para>
There are support scripts to maintain these tables in the modules There are support scripts to maintain these tables in the modules

52
doc/src/sgml/rules.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/rules.sgml,v 1.14 2001/07/09 23:50:32 tgl Exp $ --> <!-- $Header: /cvsroot/pgsql/doc/src/sgml/rules.sgml,v 1.15 2001/09/10 21:58:47 petere Exp $ -->
<Chapter Id="rules"> <Chapter Id="rules">
<Title>The <ProductName>Postgres</ProductName> Rule System</Title> <Title>The <ProductName>Postgres</ProductName> Rule System</Title>
@ -43,7 +43,7 @@
[<XRef LinkEnd="STON90b" EndTerm="STON90b">]. [<XRef LinkEnd="STON90b" EndTerm="STON90b">].
</para> </para>
<Sect1 id="querytree"> <Sect1 id="querytree">
<Title>What is a Querytree?</Title> <Title>What is a Query Tree?</Title>
<Para> <Para>
To understand how the rule system works it is necessary to know To understand how the rule system works it is necessary to know
@ -92,9 +92,7 @@
query trees in this document it is necessary to be able to identify query trees in this document it is necessary to be able to identify
the parts the statement is broken into when it is in the query tree the parts the statement is broken into when it is in the query tree
structure. The parts of a query tree are structure. The parts of a query tree are
</Para>
<Para>
<VariableList> <VariableList>
<VarListEntry> <VarListEntry>
<Term> <Term>
@ -214,7 +212,7 @@
<Para> <Para>
The query's qualification is an expression much like one of those The query's qualification is an expression much like one of those
contained in the target list entries. The result value of this contained in the target list entries. The result value of this
expression is a boolean that tells if the operation expression is a Boolean that tells if the operation
(INSERT, UPDATE, DELETE or SELECT) for the final result row should be (INSERT, UPDATE, DELETE or SELECT) for the final result row should be
executed or not. It is the WHERE clause of an executed or not. It is the WHERE clause of an
<Acronym>SQL</Acronym> statement. <Acronym>SQL</Acronym> statement.
@ -232,7 +230,7 @@
For a simple query like SELECT FROM a, b, c the join tree is just For a simple query like SELECT FROM a, b, c the join tree is just
a list of the FROM items, because we are allowed to join them in a list of the FROM items, because we are allowed to join them in
any order. But when JOIN expressions --- particularly outer joins any order. But when JOIN expressions --- particularly outer joins
--- are used, we have to join in the order shown by the JOINs. --- are used, we have to join in the order shown by the joins.
The join tree shows the structure of the JOIN expressions. The The join tree shows the structure of the JOIN expressions. The
restrictions associated with particular JOIN clauses (from ON or restrictions associated with particular JOIN clauses (from ON or
USING expressions) are stored as qualification expressions attached USING expressions) are stored as qualification expressions attached
@ -329,9 +327,9 @@
</Para> </Para>
<Para> <Para>
The database needed to play with the examples is named al_bundy. The database needed to play with the examples is named <literal>al_bundy</literal>.
You'll see soon why this is the database name. And it needs the You'll see soon why this is the database name. And it needs the
procedural language PL/pgSQL installed, because procedural language <application>PL/pgSQL</> installed, because
we need a little min() function returning the lower of 2 we need a little min() function returning the lower of 2
integer values. We create that as integer values. We create that as
@ -511,7 +509,7 @@
range table and checks if there are rules in <Filename>pg_rewrite</Filename> range table and checks if there are rules in <Filename>pg_rewrite</Filename>
for any relation. When processing the range table entry for for any relation. When processing the range table entry for
<Filename>shoelace</Filename> (the only one up to now) it finds the <Filename>shoelace</Filename> (the only one up to now) it finds the
rule '_RETshoelace' with the parsetree rule <literal>_RETshoelace</literal> with the parse tree
<ProgramListing> <ProgramListing>
<FirstTerm>SELECT s.sl_name, s.sl_avail, <FirstTerm>SELECT s.sl_name, s.sl_avail,
@ -791,7 +789,7 @@
into the table (after stripping ctid) and in the tuple header of the row into the table (after stripping ctid) and in the tuple header of the row
that ctid pointed to the cmax and xmax entries are set to the current that ctid pointed to the cmax and xmax entries are set to the current
command counter and current transaction ID. Thus the old row is hidden command counter and current transaction ID. Thus the old row is hidden
and after the transaction commited the vacuum cleaner can really move and after the transaction committed the vacuum cleaner can really move
it out. it out.
</Para> </Para>
@ -845,7 +843,7 @@
</Para> </Para>
<Para> <Para>
To change this we can define rules that modify the behaviour To change this we can define rules that modify the behavior
of non-SELECT queries. This is the topic of the next section. of non-SELECT queries. This is the topic of the next section.
</Para> </Para>
</Sect2> </Sect2>
@ -1316,8 +1314,8 @@
This way might irritate frontend applications because This way might irritate frontend applications because
absolutely nothing happened on the database and thus, the absolutely nothing happened on the database and thus, the
backend will not return anything for the query. Not backend will not return anything for the query. Not
even a PGRES_EMPTY_QUERY will be available in libpq. even a <symbol>PGRES_EMPTY_QUERY</symbol> will be available in <application>libpq</>.
In psql, nothing happens. This might change in the future. In <application>psql</application>, nothing happens. This might change in the future.
</Para> </Para>
</Note> </Note>
@ -1445,7 +1443,7 @@
It's a long way from the one INSERT ... SELECT to these It's a long way from the one INSERT ... SELECT to these
results. And its description will be the last in this results. And its description will be the last in this
document (but not the last example :-). First there was the parsers output document (but not the last example :-). First there was the parser's output
<ProgramListing> <ProgramListing>
INSERT INTO shoelace_ok SELECT INSERT INTO shoelace_ok SELECT
@ -1467,7 +1465,7 @@
and throws away the original INSERT on <Filename>shoelace_ok</Filename>. and throws away the original INSERT on <Filename>shoelace_ok</Filename>.
This rewritten query is passed to the rule system again and This rewritten query is passed to the rule system again and
the second applied rule 'shoelace_upd' produced the second applied rule <literal>shoelace_upd</literal> produced
<ProgramListing> <ProgramListing>
UPDATE shoelace_data SET UPDATE shoelace_data SET
@ -1487,7 +1485,7 @@
Again it's an INSTEAD rule and the previous parse tree is trashed. Again it's an INSTEAD rule and the previous parse tree is trashed.
Note that this query still uses the view <Filename>shoelace</Filename>. Note that this query still uses the view <Filename>shoelace</Filename>.
But the rule system isn't finished with this loop so it continues But the rule system isn't finished with this loop so it continues
and applies the rule '_RETshoelace' on it and we get and applies the rule <literal>_RETshoelace</literal> on it and we get
<ProgramListing> <ProgramListing>
UPDATE shoelace_data SET UPDATE shoelace_data SET
@ -1508,7 +1506,7 @@
Again an update rule has been applied and so the wheel Again an update rule has been applied and so the wheel
turns on and we are in rewrite round 3. This time rule turns on and we are in rewrite round 3. This time rule
'log_shoelace' gets applied what produces the extra <literal>log_shoelace</literal> gets applied what produces the extra
parse tree parse tree
<ProgramListing> <ProgramListing>
@ -1659,7 +1657,7 @@ Merge Join
WHERE sl_name = shoelace.sl_name); WHERE sl_name = shoelace.sl_name);
</ProgramListing> </ProgramListing>
Voila: Voilà:
<ProgramListing> <ProgramListing>
al_bundy=> SELECT * FROM shoelace; al_bundy=> SELECT * FROM shoelace;
@ -1718,7 +1716,7 @@ Merge Join
a relation (table or view) is automatically the owner of the a relation (table or view) is automatically the owner of the
rewrite rules that are defined for it. rewrite rules that are defined for it.
The <ProductName>Postgres</ProductName> rule system changes the The <ProductName>Postgres</ProductName> rule system changes the
behaviour of the default access control system. Relations that behavior of the default access control system. Relations that
are used due to rules get checked against the are used due to rules get checked against the
permissions of the rule owner, not the user invoking the rule. permissions of the rule owner, not the user invoking the rule.
This means, that a user does only need the required permissions This means, that a user does only need the required permissions
@ -1845,8 +1843,8 @@ Merge Join
</ProgramListing> </ProgramListing>
Both tables have many Both tables have many
thousands of rows and the index on hostname is unique. thousands of rows and the index on <structfield>hostname</> is unique.
The hostname column contains the full qualified domain The <structfield>hostname</> column contains the full qualified domain
name of the computer. The rule/trigger should constraint name of the computer. The rule/trigger should constraint
delete rows from software that reference the deleted host. delete rows from software that reference the deleted host.
Since the trigger is called for each individual row Since the trigger is called for each individual row
@ -1856,7 +1854,7 @@ Merge Join
DELETE FROM software WHERE hostname = $1; DELETE FROM software WHERE hostname = $1;
</ProgramListing> </ProgramListing>
in a prepared and saved plan and pass the hostname in in a prepared and saved plan and pass the <structfield>hostname</> in
the parameter. The rule would be written as the parameter. The rule would be written as
<ProgramListing> <ProgramListing>
@ -1890,7 +1888,7 @@ Merge Join
So there would be not that much difference in speed between So there would be not that much difference in speed between
the trigger and the rule implementation. With the next delete the trigger and the rule implementation. With the next delete
we want to get rid of all the 2000 computers where the hostname starts we want to get rid of all the 2000 computers where the <structfield>hostname</> starts
with 'old'. There are two possible queries to do that. One is with 'old'. There are two possible queries to do that. One is
<ProgramListing> <ProgramListing>
@ -1922,7 +1920,7 @@ Merge Join
</ProgramListing> </ProgramListing>
This shows, that the planner does not realize that the This shows, that the planner does not realize that the
qualification for the hostname on computer could also be qualification for the <structfield>hostname</> on computer could also be
used for an index scan on software when there are used for an index scan on software when there are
multiple qualification expressions combined with AND, what multiple qualification expressions combined with AND, what
he does in the regexp version of the query. The trigger will he does in the regexp version of the query. The trigger will
@ -1931,7 +1929,7 @@ Merge Join
over computer and 2000 index scans for the software. The over computer and 2000 index scans for the software. The
rule implementation will do it with two queries over indexes. rule implementation will do it with two queries over indexes.
And it depends on the overall size of the software table if And it depends on the overall size of the software table if
the rule will still be faster in the seqscan situation. 2000 the rule will still be faster in the sequential scan situation. 2000
query executions over the SPI manager take some time, even query executions over the SPI manager take some time, even
if all the index blocks to look them up will soon appear in if all the index blocks to look them up will soon appear in
the cache. the cache.
@ -1946,8 +1944,8 @@ Merge Join
Again this could result in many rows to be deleted from Again this could result in many rows to be deleted from
computer. So the trigger will again fire many queries into computer. So the trigger will again fire many queries into
the executor. But the rule plan will again be the Nestloop over the executor. But the rule plan will again be the nested loop over
two IndexScan's. Only using another index on computer: two index scans. Only using another index on computer:
<ProgramListing> <ProgramListing>
Nestloop Nestloop

6
doc/src/sgml/xaggr.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <chapter id="xaggr">
@ -71,8 +71,8 @@ SELECT complex_sum(a) FROM test_complex;
state condition) if there are no non-null input values. state condition) if there are no non-null input values.
Perhaps we want to return NULL in that case instead --- SQL92 Perhaps we want to return NULL in that case instead --- SQL92
expects "Sum" to behave that way. We can do this simply by expects "Sum" to behave that way. We can do this simply by
omitting the "initcond" phrase, so that the initial state omitting the <literal>initcond</literal> phrase, so that the initial state
condition is NULL. Ordinarily this would mean that the sfunc condition is NULL. Ordinarily this would mean that the <literal>sfunc</literal>
would need to check for a NULL state-condition input, but for would need to check for a NULL state-condition input, but for
"Sum" and some other simple aggregates like "Max" and "Min", "Sum" and some other simple aggregates like "Max" and "Min",
it's sufficient to insert the first non-null input value into it's sufficient to insert the first non-null input value into

2
doc/src/sgml/xfunc.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <chapter id="xfunc">

4
doc/src/sgml/xindex.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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 Postgres documentation
--> -->
@ -70,7 +70,7 @@ Postgres documentation
</row> </row>
<row> <row>
<entry>amcanmulticol</entry> <entry>amcanmulticol</entry>
<entry>does AM support multi-column indexes?</entry> <entry>does AM support multicolumn indexes?</entry>
</row> </row>
<row> <row>
<entry>amindexnulls</entry> <entry>amindexnulls</entry>

12
doc/src/sgml/xoper.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <Chapter Id="xoper">
@ -263,8 +263,8 @@ SELECT (a + b) AS c FROM test_complex;
You can use scalarltsel and scalargtsel for comparisons on data types that You can use scalarltsel and scalargtsel for comparisons on data types that
have some sensible means of being converted into numeric scalars for have some sensible means of being converted into numeric scalars for
range comparisons. If possible, add the data type to those understood range comparisons. If possible, add the data type to those understood
by the routine convert_to_scalar() in src/backend/utils/adt/selfuncs.c. by the routine convert_to_scalar() in <filename>src/backend/utils/adt/selfuncs.c</filename>.
(Eventually, this routine should be replaced by per-datatype functions (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 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 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. estimates won't be as good as they could be.
@ -272,7 +272,7 @@ SELECT (a + b) AS c FROM test_complex;
<para> <para>
There are additional selectivity functions designed for geometric 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 and contsel. At this writing these are just stubs, but you may want
to use them (or even better, improve them) anyway. to use them (or even better, improve them) anyway.
</para> </para>
@ -356,7 +356,7 @@ SELECT (a + b) AS c FROM test_complex;
to mark the equality operator HASHES. (Unless, perhaps, you write to mark the equality operator HASHES. (Unless, perhaps, you write
your other operators to ensure that the unused bits are always zero.) your other operators to ensure that the unused bits are always zero.)
Another example is that the FLOAT data types are unsafe for hash Another example is that the FLOAT data types are unsafe for hash
joins. On machines that meet the IEEE floating point standard, minus joins. On machines that meet the <acronym>IEEE</> floating point standard, minus
zero and plus zero are different values (different bit patterns) but zero and plus zero are different values (different bit patterns) but
they are defined to compare equal. So, if float equality were marked 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 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> <para>
The bottom line is that you should probably only use HASHES for 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> </para>
</sect2> </sect2>

14
doc/src/sgml/xplang.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$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"> <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> <para>
For the languages supplied with the standard distribution, the For the languages supplied with the standard distribution, the
shell script <filename>createlang</filename> may be used instead 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 into the template1 database, use
<programlisting> <programlisting>
createlang plpgsql template1 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> executed inside the database backend, the <acronym>TRUSTED</acronym>
flag should only be given for flag should only be given for
languages that do not allow access to database backends languages that do not allow access to database backends
internals or the filesystem. The languages PL/pgSQL, internals or the file system. The languages <application>PL/pgSQL</application>,
PL/Tcl, and PL/Perl are known to be trusted; the language PL/TclU <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. should <emphasis>not</emphasis> be marked trusted.
</para> </para>
</step> </step>
@ -111,7 +111,7 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
<para> <para>
In a default <productname>Postgres</productname> installation, the 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 <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 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 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"> <step performance="required">
<para> <para>
The following command tells the database where to find the 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> <programlisting>
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
@ -143,7 +143,7 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql
</programlisting> </programlisting>
then defines that the previously declared call handler function then defines that the previously declared call handler function
should be invoked for functions and trigger procedures where the should be invoked for functions and trigger procedures where the
language attribute is 'plpgsql'. language attribute is <literal>plpgsql</literal>.
</para> </para>
</step> </step>
</procedure> </procedure>