Documentation cleanup
This commit is contained in:
Peter Eisentraut
parent
fa5c8a055a
commit
934c21344c
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.53 2003/10/17 18:57:00 tgl Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.54 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="ecpg">
|
||||
@ -284,7 +284,7 @@ EXEC SQL COMMIT;
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Single-row Select:
|
||||
Single-row select:
|
||||
<programlisting>
|
||||
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
|
||||
</programlisting>
|
||||
@ -359,7 +359,7 @@ EXEC SQL AT <replaceable>connection-name</replaceable> SELECT ...;
|
||||
The second option is to execute a statement to switch the current
|
||||
connection. That statement is:
|
||||
<programlisting>
|
||||
SET CONNECTION <replaceable>connection-name</replaceable>;
|
||||
EXEC SQL SET CONNECTION <replaceable>connection-name</replaceable>;
|
||||
</programlisting>
|
||||
This option is particularly convenient if many statements are to be
|
||||
executed on the same connection.
|
||||
@ -392,7 +392,7 @@ SET CONNECTION <replaceable>connection-name</replaceable>;
|
||||
write the name of a C variable into the SQL statement, prefixed by
|
||||
a colon. For example:
|
||||
<programlisting>
|
||||
INSERT INTO sometable VALUES (:v1, 'foo', :v2);
|
||||
EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);
|
||||
</programlisting>
|
||||
This statements refers to two C variables named
|
||||
<varname>v1</varname> and <varname>v2</varname> and also uses a
|
||||
@ -592,7 +592,7 @@ EXEC SQL BEGIN DECLARE SECTION;
|
||||
const char *stmt = "CREATE TABLE test1 (...);";
|
||||
EXEC SQL END DECLARE SECTION;
|
||||
|
||||
EXECUTE IMMEDIATE :stmt;
|
||||
EXEC SQL EXECUTE IMMEDIATE :stmt;
|
||||
</programlisting>
|
||||
You may not execute statements that retrieve data (e.g.,
|
||||
<command>SELECT</command>) this way.
|
||||
@ -611,9 +611,9 @@ EXEC SQL BEGIN DECLARE SECTION;
|
||||
const char *stmt = "INSERT INTO test1 VALUES(?, ?);";
|
||||
EXEC SQL END DECLARE SECTION;
|
||||
|
||||
PREPARE mystmt FROM :stmt;
|
||||
EXEC SQL PREPARE mystmt FROM :stmt;
|
||||
...
|
||||
EXECUTE mystmt USING 42, 'foobar';
|
||||
EXEC SQL EXECUTE mystmt USING 42, 'foobar';
|
||||
</programlisting>
|
||||
If the statement you are executing returns values, then add an
|
||||
<literal>INTO</literal> clause:
|
||||
@ -624,9 +624,9 @@ int v1, v2;
|
||||
VARCHAR v3;
|
||||
EXEC SQL END DECLARE SECTION;
|
||||
|
||||
PREPARE mystmt FROM :stmt;
|
||||
EXEC SQL PREPARE mystmt FROM :stmt;
|
||||
...
|
||||
EXECUTE mystmt INTO v1, v2, v3 USING 37;
|
||||
EXEC SQL EXECUTE mystmt INTO v1, v2, v3 USING 37;
|
||||
</programlisting>
|
||||
An <command>EXECUTE</command> command may have an
|
||||
<literal>INTO</literal> clause, a <literal>USING</literal> clause,
|
||||
@ -668,7 +668,7 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
|
||||
EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
|
||||
</programlisting>
|
||||
The identifier serves as the <quote>variable name</quote> of the
|
||||
descriptor area. The scope of the allocated descriptor is WHAT?.
|
||||
descriptor area. <comment>The scope of the allocated descriptor is WHAT?.</comment>
|
||||
When you don't need the descriptor anymore, you should deallocate
|
||||
it:
|
||||
<programlisting>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.25 2003/09/11 21:42:19 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.26 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="extend">
|
||||
@ -105,52 +105,74 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.25 2003/09/11 21:42:19 momj
|
||||
|
||||
<para>
|
||||
<productname>PostgreSQL</productname> data types are divided into base
|
||||
types, composite types, domain types, and pseudo-types.
|
||||
types, composite types, domains, and pseudo-types.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Base types are those, like <type>int4</type>, that are implemented
|
||||
below the level of the <acronym>SQL</> language (typically in a low-level
|
||||
language such as C). They generally correspond to
|
||||
what are often known as abstract data types.
|
||||
<productname>PostgreSQL</productname>
|
||||
can only operate on such types through functions provided
|
||||
by the user and only understands the behavior of such
|
||||
types to the extent that the user describes them. Base types are
|
||||
further subdivided into scalar and array types. For each scalar type,
|
||||
a corresponding array type is automatically created that can hold
|
||||
variable-size arrays of that scalar type.
|
||||
</para>
|
||||
<sect2>
|
||||
<title>Base Types</title>
|
||||
|
||||
<para>
|
||||
Composite types, or row types, are created whenever the user creates a
|
||||
table; it's also possible to define a <quote>stand-alone</> composite
|
||||
type with no associated table. A composite type is simply a list of
|
||||
base types with associated field names. A value of a composite type
|
||||
is a row or record of field values. The user can access the component
|
||||
fields from <acronym>SQL</> queries.
|
||||
</para>
|
||||
<para>
|
||||
Base types are those, like <type>int4</type>, that are
|
||||
implemented below the level of the <acronym>SQL</> language
|
||||
(typically in a low-level language such as C). They generally
|
||||
correspond to what are often known as abstract data types.
|
||||
<productname>PostgreSQL</productname> can only operate on such
|
||||
types through functions provided by the user and only understands
|
||||
the behavior of such types to the extent that the user describes
|
||||
them. Base types are further subdivided into scalar and array
|
||||
types. For each scalar type, a corresponding array type is
|
||||
automatically created that can hold variable-size arrays of that
|
||||
scalar type.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<para>
|
||||
A domain type is based on a particular base
|
||||
type and for many purposes is interchangeable with its base type.
|
||||
However, a domain may have constraints that restrict its valid values
|
||||
to a subset of what the underlying base type would allow. Domains can
|
||||
be created by simple <acronym>SQL</> commands.
|
||||
</para>
|
||||
<sect2>
|
||||
<title>Composite Types</title>
|
||||
|
||||
<para>
|
||||
Finally, there are a few <quote>pseudo-types</> for special purposes.
|
||||
Pseudo-types cannot appear as fields of tables or composite types, but
|
||||
they can be used to declare the argument and result types of functions.
|
||||
This provides a mechanism within the type system to identify special
|
||||
classes of functions. <xref
|
||||
linkend="datatype-pseudotypes-table"> lists the existing
|
||||
pseudo-types.
|
||||
</para>
|
||||
<para>
|
||||
Composite types, or row types, are created whenever the user
|
||||
creates a table; it's also possible to define a
|
||||
<quote>stand-alone</> composite type with no associated table. A
|
||||
composite type is simply a list of base types with associated
|
||||
field names. A value of a composite type is a row or record of
|
||||
field values. The user can access the component fields from
|
||||
<acronym>SQL</> queries.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Domains</title>
|
||||
|
||||
<para>
|
||||
A domain is based on a particular base type and for many purposes
|
||||
is interchangeable with its base type. However, a domain may
|
||||
have constraints that restrict its valid values to a subset of
|
||||
what the underlying base type would allow.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Domains can be created using the <acronym>SQL</> commands
|
||||
<command>CREATE DOMAIN</command>. Their creation and use is not
|
||||
discussed in this chapter.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>Pseudo-Types</title>
|
||||
|
||||
<para>
|
||||
There are a few <quote>pseudo-types</> for special purposes.
|
||||
Pseudo-types cannot appear as columns of tables or attributes of
|
||||
composite types, but they can be used to declare the argument and
|
||||
result types of functions. This provides a mechanism within the
|
||||
type system to identify special classes of functions. <xref
|
||||
linkend="datatype-pseudotypes-table"> lists the existing
|
||||
pseudo-types.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="extend-types-polymorphic">
|
||||
<title>Polymorphic Types and Functions</title>
|
||||
<title>Polymorphic Types</title>
|
||||
|
||||
<indexterm zone="extend-types-polymorphic">
|
||||
<primary>polymorphic type</primary>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/install-win32.sgml,v 1.15 2003/11/04 09:55:38 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/install-win32.sgml,v 1.16 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="install-win32">
|
||||
@ -109,7 +109,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/install-win32.sgml,v 1.15 2003/11/04 09:55:
|
||||
|
||||
<para>
|
||||
<application>psql</application> is compiled as a <quote>console
|
||||
application</>. As the Win32 console windows use a different
|
||||
application</>. As the Windows console windows use a different
|
||||
encoding than the rest of the system, you must take special care
|
||||
when using 8-bit characters at the <application>psql</application>
|
||||
prompt. When <application>psql</application> detects a problematic
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.141 2003/11/01 01:56:29 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.142 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="libpq">
|
||||
@ -355,7 +355,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
|
||||
whilst doing so.
|
||||
The point of this approach is that the waits for I/O to complete can occur
|
||||
in the application's main loop, rather than down inside
|
||||
<function>PQconnectdb()</>, and so the application can manage this
|
||||
<function>PQconnectdb</>, and so the application can manage this
|
||||
operation in parallel with other activities.
|
||||
</para>
|
||||
<para>
|
||||
@ -829,8 +829,8 @@ has been sent to the server and not yet completed.
|
||||
<caution>
|
||||
<para>
|
||||
<function>PQtransactionStatus</> will give incorrect results when using
|
||||
a <productname>PostgreSQL</> 7.3 server that has <literal>AUTOCOMMIT</>
|
||||
set to <literal>OFF</>. The server-side autocommit feature has been
|
||||
a <productname>PostgreSQL</> 7.3 server that has the parameter <literal>autocommit</>
|
||||
set to off. The server-side autocommit feature has been
|
||||
deprecated and does not exist in later server versions.
|
||||
</para>
|
||||
</caution>
|
||||
@ -1028,7 +1028,7 @@ PGresult *PQexec(PGconn *conn, const char *command);
|
||||
It is allowed to include multiple SQL commands (separated by semicolons) in
|
||||
the command string. Multiple queries sent in a single <function>PQexec</>
|
||||
call are processed in a single transaction, unless there are explicit
|
||||
BEGIN/COMMIT commands included in the query string to divide it into multiple
|
||||
<command>BEGIN</command>/<command>COMMIT</command> commands included in the query string to divide it into multiple
|
||||
transactions. Note however that the returned <structname>PGresult</structname>
|
||||
structure describes only the result of the last command executed from the
|
||||
string. Should one of the commands fail, processing of the string stops with
|
||||
@ -1737,7 +1737,7 @@ This function is deprecated (except for its use in connection with
|
||||
<command>COPY</>), because it is possible for a single
|
||||
<structname>PGresult</>
|
||||
to contain text data in some columns and binary data in others.
|
||||
<function>PQfformat()</> is preferred. <function>PQbinaryTuples</>
|
||||
<function>PQfformat</> is preferred. <function>PQbinaryTuples</>
|
||||
returns 1 only if all columns of the result are binary (format 1).
|
||||
</para>
|
||||
</listitem>
|
||||
@ -2068,7 +2068,7 @@ unsigned char *PQescapeBytea(const unsigned char *from,
|
||||
<function>PQescapeBytea</> returns an escaped version of the
|
||||
<parameter>from</parameter> parameter binary string in memory
|
||||
allocated with <function>malloc()</>. This memory must be freed
|
||||
using <function>PQfreemem()</> when the result is no longer needed.
|
||||
using <function>PQfreemem</> when the result is no longer needed.
|
||||
The return string has all special characters replaced so that they
|
||||
can be properly processed by the
|
||||
<productname>PostgreSQL</productname> string literal parser, and
|
||||
@ -2102,7 +2102,7 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
|
||||
It returns a pointer to a buffer allocated with
|
||||
<function>malloc()</function>, or null on error, and puts the size of
|
||||
the buffer in <parameter>to_length</parameter>. The result must be
|
||||
freed using <function>PQfreemem()</> when it is no longer needed.
|
||||
freed using <function>PQfreemem</> when it is no longer needed.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -2122,9 +2122,9 @@ void PQfreemem(void *ptr);
|
||||
<function>PQescapeBytea</function>,
|
||||
<function>PQunescapeBytea</function>,
|
||||
and <function>PQnotifies</function>.
|
||||
It is needed by Win32, which can not free memory across
|
||||
It is needed by Microsoft Windows, which cannot free memory across
|
||||
DLLs, unless multithreaded DLLs (<option>/MD</option> in VC6) are used.
|
||||
On other platforms it is the same as <function>free()</>.
|
||||
On other platforms, this function is the same as the standard library function <function>free()</>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
@ -2420,7 +2420,7 @@ while waiting for input from the database server. However, it is still
|
||||
possible that the application will block waiting to send output to the
|
||||
server. This is relatively uncommon but can happen if very long SQL commands
|
||||
or data values are sent. (It is much more probable if the application
|
||||
sends data via COPY IN, however.) To prevent this possibility and achieve
|
||||
sends data via <command>COPY IN</command>, however.) To prevent this possibility and achieve
|
||||
completely nonblocking database operation, the following additional
|
||||
functions may be used.
|
||||
|
||||
@ -2634,15 +2634,10 @@ After processing a <structname>PGnotify</structname> object returned by
|
||||
<structname>PGnotify</structname> pointer; the
|
||||
<structfield>relname</structfield> and <structfield>extra</structfield> fields
|
||||
do not represent separate allocations.
|
||||
(At present, the <structfield>extra</structfield> field is unused and will
|
||||
always point to an empty string.)
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
At present the <structfield>extra</structfield> field is unused and will
|
||||
always point to an empty string.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
In <productname>PostgreSQL</productname> 6.4 and later,
|
||||
@ -2657,28 +2652,28 @@ of asynchronous notification.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<function>PQnotifies()</function> does not actually read data from the server; it just
|
||||
<function>PQnotifies</function> does not actually read data from the server; it just
|
||||
returns messages previously absorbed by another <application>libpq</application>
|
||||
function. In prior releases of <application>libpq</application>, the only way
|
||||
to ensure timely receipt of <command>NOTIFY</> messages was to constantly submit commands,
|
||||
even empty ones, and then check <function>PQnotifies()</function> after each
|
||||
<function>PQexec()</function>. While this still works, it is
|
||||
even empty ones, and then check <function>PQnotifies</function> after each
|
||||
<function>PQexec</function>. While this still works, it is
|
||||
deprecated as a waste of processing power.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A better way to check for <command>NOTIFY</>
|
||||
messages when you have no useful commands to execute is to call
|
||||
<function>PQconsumeInput()</function>, then check
|
||||
<function>PQnotifies()</function>.
|
||||
<function>PQconsumeInput</function>, then check
|
||||
<function>PQnotifies</function>.
|
||||
You can use <function>select()</function> to wait for data to
|
||||
arrive from the server, thereby using no <acronym>CPU</acronym> power unless there is something
|
||||
to do. (See <function>PQsocket()</function> to obtain the file descriptor
|
||||
to do. (See <function>PQsocket</function> to obtain the file descriptor
|
||||
number to use with <function>select()</function>.)
|
||||
Note that this will work OK whether you submit commands with
|
||||
<function>PQsendQuery</function>/<function>PQgetResult</function> or simply
|
||||
use <function>PQexec</function>. You should, however, remember to
|
||||
check <function>PQnotifies()</function> after each
|
||||
check <function>PQnotifies</function> after each
|
||||
<function>PQgetResult</function> or <function>PQexec</function>, to see
|
||||
if any notifications came in during the processing of the command.
|
||||
</para>
|
||||
@ -2813,7 +2808,7 @@ int PQputCopyData(PGconn *conn,
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Transmits the COPY data in the specified <parameter>buffer</>, of length
|
||||
Transmits the <command>COPY</command> data in the specified <parameter>buffer</>, of length
|
||||
<parameter>nbytes</>, to the server. The result is 1 if the data was sent,
|
||||
zero if it was not sent because the attempt would block (this case is only
|
||||
possible if the connection is in nonblocking mode), or -1 if an error occurred.
|
||||
@ -2896,7 +2891,7 @@ int PQgetCopyData(PGconn *conn,
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Attempts to obtain another row of data from the server during a COPY.
|
||||
Attempts to obtain another row of data from the server during a <command>COPY</command>.
|
||||
Data is always returned one data row at a time; if only a partial row
|
||||
is available, it is not returned. Successful return of a data row
|
||||
involves allocating a chunk of memory to hold the data. The
|
||||
@ -2910,17 +2905,17 @@ buffer is returned. A non-<symbol>NULL</symbol> result buffer must be freed usi
|
||||
When a row is successfully returned, the return value is the number of
|
||||
data bytes in the row (this will always be greater than zero). The
|
||||
returned string is always null-terminated, though this is probably only
|
||||
useful for textual COPY. A result of zero indicates that the COPY is
|
||||
useful for textual <command>COPY</command>. A result of zero indicates that the <command>COPY</command> is
|
||||
still in progress, but no row is yet available (this is only possible
|
||||
when <parameter>async</> is true). A
|
||||
result of -1 indicates that the COPY is done.
|
||||
result of -1 indicates that the <command>COPY</command> is done.
|
||||
A result of -2 indicates that an error occurred (consult
|
||||
<function>PQerrorMessage</> for the reason).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When <parameter>async</> is true (not zero), <function>PQgetCopyData</>
|
||||
will not block waiting for input; it will return zero if the COPY is still
|
||||
will not block waiting for input; it will return zero if the <command>COPY</command> is still
|
||||
in progress but no complete row is available. (In this case wait for
|
||||
read-ready before trying again; it does not matter whether you call
|
||||
<function>PQconsumeInput</>.) When <parameter>async</> is
|
||||
@ -2992,7 +2987,7 @@ for a terminator line).
|
||||
<term><function>PQgetlineAsync</function><indexterm><primary>PQgetlineAsync</></></term>
|
||||
<listitem>
|
||||
<para>
|
||||
Reads a row of COPY data
|
||||
Reads a row of <command>COPY</command> data
|
||||
(transmitted by the server) into a buffer
|
||||
without blocking.
|
||||
<synopsis>
|
||||
@ -3031,7 +3026,7 @@ a whole row will be returned at one time. But if the buffer offered by
|
||||
the caller is too small to hold a row sent by the server, then a partial
|
||||
data row will be returned. With textual data this can be detected by testing
|
||||
whether the last returned byte is <literal>\n</literal> or not. (In a binary
|
||||
COPY, actual parsing of the COPY data format will be needed to make the
|
||||
<command>COPY</>, actual parsing of the <command>COPY</> data format will be needed to make the
|
||||
equivalent determination.)
|
||||
The returned string is not null-terminated. (If you want to add a
|
||||
terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller
|
||||
@ -3065,7 +3060,7 @@ call; it is okay to send a partial line or multiple lines per call.
|
||||
Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary
|
||||
for the application to explicitly send the two characters
|
||||
<literal>\.</literal> as a final line to indicate to the server that it had
|
||||
finished sending COPY data. While this still works, it is deprecated and the
|
||||
finished sending <command>COPY</> data. While this still works, it is deprecated and the
|
||||
special meaning of <literal>\.</literal> can be expected to be removed in a
|
||||
future release. It is sufficient to call <function>PQendcopy</function> after
|
||||
having sent the actual data.
|
||||
@ -3162,17 +3157,19 @@ Determines the verbosity of messages returned by
|
||||
<function>PQerrorMessage</> and <function>PQresultErrorMessage</>.
|
||||
<synopsis>
|
||||
typedef enum {
|
||||
PQERRORS_TERSE, PQERRORS_DEFAULT, PQERRORS_VERBOSE
|
||||
PQERRORS_TERSE,
|
||||
PQERRORS_DEFAULT,
|
||||
PQERRORS_VERBOSE
|
||||
} PGVerbosity;
|
||||
|
||||
PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
|
||||
</synopsis>
|
||||
<function>PQsetErrorVerbosity</> sets the verbosity mode, returning the
|
||||
connection's previous setting.
|
||||
In TERSE mode, returned messages include severity, primary text, and position
|
||||
only; this will normally fit on a single line. The DEFAULT mode produces
|
||||
In <firstterm>terse</> mode, returned messages include severity, primary text, and position
|
||||
only; this will normally fit on a single line. The default mode produces
|
||||
messages that include the above plus any detail, hint, or context fields
|
||||
(these may span multiple lines). The VERBOSE mode includes all available
|
||||
(these may span multiple lines). The <firstterm>VERBOSE</> mode includes all available
|
||||
fields. Changing the verbosity does not affect the messages available from
|
||||
already-existing <structname>PGresult</> objects, only subsequently-created
|
||||
ones.
|
||||
@ -3568,7 +3565,7 @@ If the permissions are less strict than this, the file will be ignored.
|
||||
</sect1>
|
||||
|
||||
<sect1 id="libpq-threading">
|
||||
<title>Threading Behavior</title>
|
||||
<title>Behavior in Threaded Programs</title>
|
||||
|
||||
<indexterm zone="libpq-threading">
|
||||
<primary>threads</primary>
|
||||
@ -3576,11 +3573,14 @@ If the permissions are less strict than this, the file will be ignored.
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
<application>libpq</application> is thread-safe if the library is
|
||||
compiled using <filename>configure</filename>'s
|
||||
<literal>--enable-thread-safety</> command-line option.
|
||||
(In addition, you might need to use other threading command-line
|
||||
options to compile your client code.)
|
||||
<application>libpq</application> is reentrant and thread-safe if the
|
||||
<filename>configure</filename> command-line option
|
||||
<literal>--enable-thread-safety</> has been used when the PostgreSQL
|
||||
distribution was built.
|
||||
In addition, you might need to use additional compiler command-line
|
||||
options when you compile your application code. Refer to your system's
|
||||
documentation for information about how to build thread-enabled
|
||||
applications.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.31 2003/11/01 01:56:29 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.32 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="largeObjects">
|
||||
@ -299,7 +299,7 @@ int lo_unlink(PGconn *conn, Oid lobjId);
|
||||
</sect1>
|
||||
|
||||
<sect1 id="lo-funcs">
|
||||
<title>Server-side Functions</title>
|
||||
<title>Server-Side Functions</title>
|
||||
|
||||
<para>
|
||||
There are two built-in server-side functions,
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.28 2003/11/01 01:56:29 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.29 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="plpgsql">
|
||||
@ -114,25 +114,25 @@ END;
|
||||
|
||||
<para>
|
||||
Because <application>PL/pgSQL</application> saves execution plans
|
||||
in this way, SQL commands that appear directly in a
|
||||
<application>PL/pgSQL</application> function must refer to the
|
||||
same tables and columns on every execution; that is, you cannot use
|
||||
a parameter as the name of a table or column in an SQL command. To get
|
||||
around this restriction, you can construct dynamic commands using
|
||||
the <application>PL/pgSQL</application> <command>EXECUTE</command>
|
||||
statement --- at the price of constructing a new execution plan on
|
||||
every execution.
|
||||
in this way, SQL commands that appear directly in a
|
||||
<application>PL/pgSQL</application> function must refer to the
|
||||
same tables and columns on every execution; that is, you cannot use
|
||||
a parameter as the name of a table or column in an SQL command. To get
|
||||
around this restriction, you can construct dynamic commands using
|
||||
the <application>PL/pgSQL</application> <command>EXECUTE</command>
|
||||
statement --- at the price of constructing a new execution plan on
|
||||
every execution.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
The <application>PL/pgSQL</application>
|
||||
<command>EXECUTE</command> statement is not related to the
|
||||
<command>EXECUTE</command> statement supported by the
|
||||
<productname>PostgreSQL</productname> server. The server's
|
||||
<command>EXECUTE</command> statement cannot be used within
|
||||
<application>PL/pgSQL</> functions (and is not needed).
|
||||
</para>
|
||||
<para>
|
||||
The <application>PL/pgSQL</application>
|
||||
<command>EXECUTE</command> statement is not related to the
|
||||
<command>EXECUTE</command> statement supported by the
|
||||
<productname>PostgreSQL</productname> server. The server's
|
||||
<command>EXECUTE</command> statement cannot be used within
|
||||
<application>PL/pgSQL</> functions (and is not needed).
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
@ -195,7 +195,7 @@ END;
|
||||
|
||||
<para>
|
||||
<application>PL/pgSQL</> functions may also be declared to accept
|
||||
and return the <quote>polymorphic</> types
|
||||
and return the polymorphic types
|
||||
<type>anyelement</type> and <type>anyarray</type>. The actual
|
||||
data types handled by a polymorphic function can vary from call to
|
||||
call, as discussed in <xref linkend="extend-types-polymorphic">.
|
||||
@ -230,7 +230,7 @@ END;
|
||||
the function definition. For example:
|
||||
<programlisting>
|
||||
CREATE OR REPLACE FUNCTION testfunc(integer) RETURNS integer AS '
|
||||
....
|
||||
....
|
||||
end;
|
||||
' LANGUAGE plpgsql;
|
||||
</programlisting>
|
||||
@ -255,7 +255,7 @@ end;
|
||||
</para>
|
||||
|
||||
<sect2 id="plpgsql-quote-tips">
|
||||
<title>Handling of Quote Marks</title>
|
||||
<title>Handling of Quotation Marks</title>
|
||||
|
||||
<para>
|
||||
Since the code of a <application>PL/pgSQL</> function is specified in
|
||||
@ -265,13 +265,13 @@ end;
|
||||
rather complicated code at times, especially if you are writing a
|
||||
function that generates other functions, as in the example in <xref
|
||||
linkend="plpgsql-statements-executing-dyn">. This chart may be useful
|
||||
as a summary of the needed numbers of quote marks in
|
||||
as a summary of the needed numbers of quotation marks in
|
||||
various situations.
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>1 quote mark</term>
|
||||
<term>1 quotation mark</term>
|
||||
<listitem>
|
||||
<para>
|
||||
To begin and end the function body, for example:
|
||||
@ -279,14 +279,14 @@ end;
|
||||
CREATE FUNCTION foo() RETURNS integer AS '...'
|
||||
LANGUAGE plpgsql;
|
||||
</programlisting>
|
||||
Anywhere within the function body, quote marks <emphasis>must</>
|
||||
Anywhere within the function body, quotation marks <emphasis>must</>
|
||||
appear in pairs.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>2 quote marks</term>
|
||||
<term>2 quotation marks</term>
|
||||
<listitem>
|
||||
<para>
|
||||
For string literals inside the function body, for example:
|
||||
@ -303,10 +303,10 @@ SELECT * FROM users WHERE f_name='foobar';
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>4 quote marks</term>
|
||||
<term>4 quotation marks</term>
|
||||
<listitem>
|
||||
<para>
|
||||
When you need a single quote in a string constant inside the function
|
||||
When you need a single quotation mark in a string constant inside the function
|
||||
body, for example:
|
||||
<programlisting>
|
||||
a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz''
|
||||
@ -318,10 +318,10 @@ a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz''
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>6 quote marks</term>
|
||||
<term>6 quotation marks</term>
|
||||
<listitem>
|
||||
<para>
|
||||
When a single quote in a string inside the function body is
|
||||
When a single quotation mark in a string inside the function body is
|
||||
adjacent to the end of that string constant, for example:
|
||||
<programlisting>
|
||||
a_output := a_output || '' AND name LIKE ''''foobar''''''
|
||||
@ -333,11 +333,11 @@ a_output := a_output || '' AND name LIKE ''''foobar''''''
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>10 quote marks</term>
|
||||
<term>10 quotation marks</term>
|
||||
<listitem>
|
||||
<para>
|
||||
When you want two single quotes in a string constant (which
|
||||
accounts for 8 quotes) and this is adjacent to the end of that
|
||||
When you want two single quotation marks in a string constant (which
|
||||
accounts for 8 quotation marks) and this is adjacent to the end of that
|
||||
string constant (2 more). You will probably only need that if
|
||||
you are writing a function that generates other functions. For
|
||||
example:
|
||||
@ -358,7 +358,7 @@ if v_... like ''...'' then return ''...''; end if;
|
||||
</variablelist>
|
||||
|
||||
<para>
|
||||
A different approach is to escape quote marks in the function body
|
||||
A different approach is to escape quotation marks in the function body
|
||||
with a backslash rather than by doubling them. With this method
|
||||
you'll find yourself writing things like <literal>\'\'</> instead
|
||||
of <literal>''''</>. Some find this easier to keep track of, some
|
||||
@ -568,7 +568,7 @@ END;
|
||||
linkend="extend-types-polymorphic">).
|
||||
This allows the function to access its actual return type
|
||||
as shown in <xref linkend="plpgsql-declaration-type">.
|
||||
<literal>$0</literal> is initialized to NULL and can be modified by
|
||||
<literal>$0</literal> is initialized to null and can be modified by
|
||||
the function, so it can be used to hold the return value if desired,
|
||||
though that is not required. <literal>$0</literal> can also be
|
||||
given an alias. For example, this function works on any data type
|
||||
@ -689,14 +689,12 @@ END;
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="plpgsql-declaration-records">
|
||||
<title>Record Types</title>
|
||||
<sect2 id="plpgsql-declaration-records">
|
||||
<title>Record Types</title>
|
||||
|
||||
<para>
|
||||
<synopsis>
|
||||
<replaceable>name</replaceable> RECORD;
|
||||
</synopsis>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Record variables are similar to row-type variables, but they have no
|
||||
@ -721,36 +719,38 @@ END;
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="plpgsql-declaration-renaming-vars">
|
||||
<title><literal>RENAME</></title>
|
||||
<sect2 id="plpgsql-declaration-renaming-vars">
|
||||
<title><literal>RENAME</></title>
|
||||
|
||||
<para>
|
||||
<synopsis>
|
||||
RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
|
||||
</synopsis>
|
||||
|
||||
Using the RENAME declaration you can change the name of a variable,
|
||||
record or row. This is primarily useful if NEW or OLD should be
|
||||
referenced by another name inside a trigger procedure. See also ALIAS.
|
||||
</para>
|
||||
<para>
|
||||
Using the <literal>RENAME</literal> declaration you can change the
|
||||
name of a variable, record or row. This is primarily useful if
|
||||
<literal>NEW</literal> or <literal>OLD</literal> should be
|
||||
referenced by another name inside a trigger procedure. See also
|
||||
<literal>ALIAS</literal>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Examples:
|
||||
<para>
|
||||
Examples:
|
||||
<programlisting>
|
||||
RENAME id TO user_id;
|
||||
RENAME this_var TO that_var;
|
||||
</programlisting>
|
||||
</para>
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
RENAME appears to be broken as of <productname>PostgreSQL</>
|
||||
7.3. Fixing this is of low priority, since ALIAS covers most of
|
||||
the practical uses of RENAME.
|
||||
</para>
|
||||
<para>
|
||||
<literal>RENAME</literal> appears to be broken as of
|
||||
<productname>PostgreSQL</> 7.3. Fixing this is of low priority,
|
||||
since <literal>ALIAS</literal> covers most of the practical uses
|
||||
of <literal>RENAME</literal>.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
</sect2>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="plpgsql-expressions">
|
||||
@ -1159,9 +1159,9 @@ END;
|
||||
<title>Obtaining the Result Status</title>
|
||||
|
||||
<para>
|
||||
There are several ways to determine the effect of a command. The
|
||||
first method is to use the <command>GET DIAGNOSTICS</command>
|
||||
command, which has the form:
|
||||
There are several ways to determine the effect of a command. The
|
||||
first method is to use the <command>GET DIAGNOSTICS</command>
|
||||
command, which has the form:
|
||||
|
||||
<synopsis>
|
||||
GET DIAGNOSTICS <replaceable>variable</replaceable> = <replaceable>item</replaceable> <optional> , ... </optional> ;
|
||||
@ -1192,49 +1192,49 @@ GET DIAGNOSTICS integer_var = ROW_COUNT;
|
||||
type <type>boolean</type>. <literal>FOUND</literal> starts out
|
||||
false within each <application>PL/pgSQL</application> function call.
|
||||
It is set by each of the following types of statements:
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>SELECT INTO</command> statement sets
|
||||
<literal>FOUND</literal> true if it returns a row, false if no
|
||||
row is returned.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>PERFORM</> statement sets <literal>FOUND</literal>
|
||||
true if it produces (and discards) a row, false if no row is
|
||||
produced.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<command>UPDATE</>, <command>INSERT</>, and <command>DELETE</>
|
||||
statements set <literal>FOUND</literal> true if at least one
|
||||
row is affected, false if no row is affected.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>FETCH</> statement sets <literal>FOUND</literal>
|
||||
true if it returns a row, false if no row is returned.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>FOR</> statement sets <literal>FOUND</literal> true
|
||||
if it iterates one or more times, else false. This applies to
|
||||
all three variants of the <command>FOR</> statement (integer
|
||||
<command>FOR</> loops, record-set <command>FOR</> loops, and
|
||||
dynamic record-set <command>FOR</>
|
||||
loops). <literal>FOUND</literal> is only set when the
|
||||
<command>FOR</> loop exits: inside the execution of the loop,
|
||||
<literal>FOUND</literal> is not modified by the
|
||||
<command>FOR</> statement, although it may be changed by the
|
||||
execution of other statements within the loop body.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>SELECT INTO</command> statement sets
|
||||
<literal>FOUND</literal> true if it returns a row, false if no
|
||||
row is returned.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>PERFORM</> statement sets <literal>FOUND</literal>
|
||||
true if it produces (and discards) a row, false if no row is
|
||||
produced.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<command>UPDATE</>, <command>INSERT</>, and <command>DELETE</>
|
||||
statements set <literal>FOUND</literal> true if at least one
|
||||
row is affected, false if no row is affected.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>FETCH</> statement sets <literal>FOUND</literal>
|
||||
true if it returns a row, false if no row is returned.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
A <command>FOR</> statement sets <literal>FOUND</literal> true
|
||||
if it iterates one or more times, else false. This applies to
|
||||
all three variants of the <command>FOR</> statement (integer
|
||||
<command>FOR</> loops, record-set <command>FOR</> loops, and
|
||||
dynamic record-set <command>FOR</>
|
||||
loops). <literal>FOUND</literal> is only set when the
|
||||
<command>FOR</> loop exits: inside the execution of the loop,
|
||||
<literal>FOUND</literal> is not modified by the
|
||||
<command>FOR</> statement, although it may be changed by the
|
||||
execution of other statements within the loop body.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<literal>FOUND</literal> is a local variable; any changes
|
||||
to it affect only the current <application>PL/pgSQL</application>
|
||||
function.
|
||||
@ -1583,7 +1583,7 @@ EXIT <optional> <replaceable>label</replaceable> </optional> <optional> WHEN <re
|
||||
|
||||
<para>
|
||||
If <literal>WHEN</> is present, loop exit occurs only if the specified condition
|
||||
is true, otherwise control passes to the statement after <literal>EXIT</>.
|
||||
is true, otherwise control passes to the statement after <literal>EXIT</>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1624,8 +1624,8 @@ END LOOP;
|
||||
<para>
|
||||
The <literal>WHILE</> statement repeats a
|
||||
sequence of statements so long as the condition expression
|
||||
evaluates to true. The condition is checked just before
|
||||
each entry to the loop body.
|
||||
evaluates to true. The condition is checked just before
|
||||
each entry to the loop body.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1654,12 +1654,12 @@ END LOOP;
|
||||
|
||||
<para>
|
||||
This form of <literal>FOR</> creates a loop that iterates over a range of integer
|
||||
values. The variable
|
||||
values. The variable
|
||||
<replaceable>name</replaceable> is automatically defined as type
|
||||
<type>integer</> and exists only inside the loop. The two expressions giving
|
||||
the lower and upper bound of the range are evaluated once when entering
|
||||
the loop. The iteration step is normally 1, but is -1 when <literal>REVERSE</> is
|
||||
specified.
|
||||
specified.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1678,7 +1678,7 @@ END LOOP;
|
||||
|
||||
<para>
|
||||
If the lower bound is greater than the upper bound (or less than,
|
||||
in the <literal>REVERSE</> case), the loop body is not
|
||||
in the <literal>REVERSE</> case), the loop body is not
|
||||
executed at all. No error is raised.
|
||||
</para>
|
||||
</sect3>
|
||||
@ -1841,13 +1841,13 @@ OPEN <replaceable>unbound-cursor</replaceable> FOR SELECT ...;
|
||||
|
||||
<para>
|
||||
The cursor variable is opened and given the specified query to
|
||||
execute. The cursor cannot be open already, and it must have been
|
||||
declared as an unbound cursor (that is, as a simple
|
||||
<type>refcursor</> variable). The <command>SELECT</command> query
|
||||
is treated in the same way as other <command>SELECT</command>
|
||||
statements in <application>PL/pgSQL</>: <application>PL/pgSQL</>
|
||||
variable names are substituted, and the query plan is cached for
|
||||
possible reuse.
|
||||
execute. The cursor cannot be open already, and it must have been
|
||||
declared as an unbound cursor (that is, as a simple
|
||||
<type>refcursor</> variable). The <command>SELECT</command> query
|
||||
is treated in the same way as other <command>SELECT</command>
|
||||
statements in <application>PL/pgSQL</>: <application>PL/pgSQL</>
|
||||
variable names are substituted, and the query plan is cached for
|
||||
possible reuse.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1865,14 +1865,14 @@ OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;
|
||||
OPEN <replaceable>unbound-cursor</replaceable> FOR EXECUTE <replaceable class="command">query-string</replaceable>;
|
||||
</synopsis>
|
||||
|
||||
<para>
|
||||
The cursor variable is opened and given the specified query to
|
||||
execute. The cursor cannot be open already, and it must have been
|
||||
declared as an unbound cursor (that is, as a simple
|
||||
<type>refcursor</> variable). The query is specified as a string
|
||||
expression in the same way as in the <command>EXECUTE</command>
|
||||
command. As usual, this gives flexibility so the query can vary
|
||||
from one run to the next.
|
||||
<para>
|
||||
The cursor variable is opened and given the specified query to
|
||||
execute. The cursor cannot be open already, and it must have been
|
||||
declared as an unbound cursor (that is, as a simple
|
||||
<type>refcursor</> variable). The query is specified as a string
|
||||
expression in the same way as in the <command>EXECUTE</command>
|
||||
command. As usual, this gives flexibility so the query can vary
|
||||
from one run to the next.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1890,14 +1890,14 @@ OPEN curs1 FOR EXECUTE ''SELECT * FROM '' || quote_ident($1);
|
||||
OPEN <replaceable>bound-cursor</replaceable> <optional> ( <replaceable>argument_values</replaceable> ) </optional>;
|
||||
</synopsis>
|
||||
|
||||
<para>
|
||||
This form of <command>OPEN</command> is used to open a cursor
|
||||
variable whose query was bound to it when it was declared. The
|
||||
cursor cannot be open already. A list of actual argument value
|
||||
expressions must appear if and only if the cursor was declared to
|
||||
take arguments. These values will be substituted in the query.
|
||||
The query plan for a bound cursor is always considered cacheable;
|
||||
there is no equivalent of <command>EXECUTE</command> in this case.
|
||||
<para>
|
||||
This form of <command>OPEN</command> is used to open a cursor
|
||||
variable whose query was bound to it when it was declared. The
|
||||
cursor cannot be open already. A list of actual argument value
|
||||
expressions must appear if and only if the cursor was declared to
|
||||
take arguments. These values will be substituted in the query.
|
||||
The query plan for a bound cursor is always considered cacheable;
|
||||
there is no equivalent of <command>EXECUTE</command> in this case.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1941,13 +1941,13 @@ OPEN curs3(42);
|
||||
FETCH <replaceable>cursor</replaceable> INTO <replaceable>target</replaceable>;
|
||||
</synopsis>
|
||||
|
||||
<para>
|
||||
<command>FETCH</command> retrieves the next row from the
|
||||
cursor into a target, which may be a row variable, a record
|
||||
variable, or a comma-separated list of simple variables, just like
|
||||
<command>SELECT INTO</command>. As with <command>SELECT
|
||||
INTO</command>, the special variable <literal>FOUND</literal> may
|
||||
be checked to see whether a row was obtained or not.
|
||||
<para>
|
||||
<command>FETCH</command> retrieves the next row from the
|
||||
cursor into a target, which may be a row variable, a record
|
||||
variable, or a comma-separated list of simple variables, just like
|
||||
<command>SELECT INTO</command>. As with <command>SELECT
|
||||
INTO</command>, the special variable <literal>FOUND</literal> may
|
||||
be checked to see whether a row was obtained or not.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1968,8 +1968,8 @@ CLOSE <replaceable>cursor</replaceable>;
|
||||
|
||||
<para>
|
||||
<command>CLOSE</command> closes the portal underlying an open
|
||||
cursor. This can be used to release resources earlier than end of
|
||||
transaction, or to free up the cursor variable to be opened again.
|
||||
cursor. This can be used to release resources earlier than end of
|
||||
transaction, or to free up the cursor variable to be opened again.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1986,40 +1986,40 @@ CLOSE curs1;
|
||||
<para>
|
||||
<application>PL/pgSQL</> functions can return cursors to the
|
||||
caller. This is useful to return multiple rows or columns,
|
||||
especially with very large result sets. To do this, the function
|
||||
opens the cursor and returns the cursor name to the caller (or simply
|
||||
opens the cursor using a portal name specified by or otherwise known
|
||||
to the caller). The caller can then fetch rows from the cursor. The
|
||||
cursor can be closed by the caller, or it will be closed automatically
|
||||
especially with very large result sets. To do this, the function
|
||||
opens the cursor and returns the cursor name to the caller (or simply
|
||||
opens the cursor using a portal name specified by or otherwise known
|
||||
to the caller). The caller can then fetch rows from the cursor. The
|
||||
cursor can be closed by the caller, or it will be closed automatically
|
||||
when the transaction closes.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The portal name used for a cursor can be specified by the
|
||||
programmer or automatically generated. To specify a portal name,
|
||||
simply assign a string to the <type>refcursor</> variable before
|
||||
opening it. The string value of the <type>refcursor</> variable
|
||||
will be used by <command>OPEN</> as the name of the underlying portal.
|
||||
However, if the <type>refcursor</> variable is NULL,
|
||||
<command>OPEN</> automatically generates a name that does not
|
||||
conflict with any existing portal, and assigns it to the
|
||||
<type>refcursor</> variable.
|
||||
programmer or automatically generated. To specify a portal name,
|
||||
simply assign a string to the <type>refcursor</> variable before
|
||||
opening it. The string value of the <type>refcursor</> variable
|
||||
will be used by <command>OPEN</> as the name of the underlying portal.
|
||||
However, if the <type>refcursor</> variable is null,
|
||||
<command>OPEN</> automatically generates a name that does not
|
||||
conflict with any existing portal, and assigns it to the
|
||||
<type>refcursor</> variable.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
A bound cursor variable is initialized to the string value
|
||||
representing its name, so that the portal name is the same as
|
||||
the cursor variable name, unless the programmer overrides it
|
||||
by assignment before opening the cursor. But an unbound cursor
|
||||
variable defaults to an initial value of NULL, so it will receive
|
||||
an automatically-generated unique name, unless overridden.
|
||||
A bound cursor variable is initialized to the string value
|
||||
representing its name, so that the portal name is the same as
|
||||
the cursor variable name, unless the programmer overrides it
|
||||
by assignment before opening the cursor. But an unbound cursor
|
||||
variable defaults to the null value initially , so it will receive
|
||||
an automatically-generated unique name, unless overridden.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
The following example shows one way a cursor name can be supplied by
|
||||
the caller:
|
||||
the caller:
|
||||
|
||||
<programlisting>
|
||||
CREATE TABLE test (col text);
|
||||
@ -2104,7 +2104,7 @@ RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="pa
|
||||
|
||||
<!--
|
||||
This example should work, but does not:
|
||||
RAISE NOTICE ''Id number '' || key || '' not found!'';
|
||||
RAISE NOTICE ''Id number '' || key || '' not found!'';
|
||||
Put it back when we allow non-string-literal formats.
|
||||
-->
|
||||
|
||||
@ -2158,14 +2158,14 @@ RAISE EXCEPTION ''Inexistent ID --> %'', user_id;
|
||||
</indexterm>
|
||||
|
||||
<para>
|
||||
<application>PL/pgSQL</application> can be used to define trigger
|
||||
procedures. A trigger procedure is created with the
|
||||
<command>CREATE FUNCTION</> command, declaring it as a function with
|
||||
no arguments and a return type of <type>trigger</type>. Note that
|
||||
the function must be declared with no arguments even if it expects
|
||||
to receive arguments specified in <command>CREATE TRIGGER</> ---
|
||||
trigger arguments are passed via <varname>TG_ARGV</>, as described
|
||||
below.
|
||||
<application>PL/pgSQL</application> can be used to define trigger
|
||||
procedures. A trigger procedure is created with the
|
||||
<command>CREATE FUNCTION</> command, declaring it as a function with
|
||||
no arguments and a return type of <type>trigger</type>. Note that
|
||||
the function must be declared with no arguments even if it expects
|
||||
to receive arguments specified in <command>CREATE TRIGGER</> ---
|
||||
trigger arguments are passed via <varname>TG_ARGV</>, as described
|
||||
below.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.20 2003/09/12 22:17:23 tgl Exp $ -->
|
||||
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.21 2003/11/12 22:47:47 petere Exp $ -->
|
||||
|
||||
<chapter id="plpython">
|
||||
<title>PL/Python - Python Procedural Language</title>
|
||||
@ -17,18 +17,6 @@
|
||||
<literal>createlang plpythonu <replaceable>dbname</></literal>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
As of <productname>PostgreSQL</productname> 7.4,
|
||||
PL/Python is only available as an <quote>untrusted</> language
|
||||
(meaning it does not offer any way of restricting what users
|
||||
can do in it). It has therefore been renamed to <literal>plpythonu</>.
|
||||
The trusted variant <literal>plpython</> may become available again in
|
||||
future, if a new secure execution mechanism is developed by the Python
|
||||
community.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<tip>
|
||||
<para>
|
||||
If a language is installed into <literal>template1</>, all subsequently
|
||||
@ -36,6 +24,15 @@
|
||||
</para>
|
||||
</tip>
|
||||
|
||||
<para>
|
||||
As of <productname>PostgreSQL</productname> 7.4, PL/Python is only
|
||||
available as an <quote>untrusted</> language (meaning it does not
|
||||
offer any way of restricting what users can do in it). It has
|
||||
therefore been renamed to <literal>plpythonu</>. The trusted
|
||||
variant <literal>plpython</> may become available again in future,
|
||||
if a new secure execution mechanism is developed in Python.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Users of source packages must specially enable the build of
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.26 2003/09/08 23:02:28 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.27 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter id="pltcl">
|
||||
@ -136,7 +136,7 @@ CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS '
|
||||
|
||||
<para>
|
||||
As shown above,
|
||||
to return a NULL value from a PL/Tcl function, execute
|
||||
to return a null value from a PL/Tcl function, execute
|
||||
<literal>return_null</literal>. This can be done whether the
|
||||
function is strict or not.
|
||||
</para>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.53 2003/10/26 04:34:05 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.54 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<refentry id="SQL-CREATEFUNCTION">
|
||||
@ -95,7 +95,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||
<para>
|
||||
The data type(s) of the function's arguments (optionally
|
||||
schema-qualified), if any. The argument types may be base, complex, or
|
||||
domain types, or copy the type of an existing column.
|
||||
domains, or copy the type of an existing column.
|
||||
</para>
|
||||
<para>
|
||||
The type of a column is referenced by writing
|
||||
@ -120,8 +120,8 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
|
||||
<listitem>
|
||||
<para>
|
||||
The return data type (optionally schema-qualified). The return type
|
||||
may be specified as a base, complex, or domain type,
|
||||
or may copy the type of an existing column. See the description
|
||||
may be a base type, complex type, or a domain,
|
||||
or may be specified to copy the type of an existing column. See the description
|
||||
under <literal>argtype</literal> above on how to reference the type
|
||||
of an existing column.
|
||||
</para>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.237 2003/11/10 22:27:00 momjian Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.238 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<appendix id="release">
|
||||
@ -878,12 +878,12 @@ zero-row record variable (Tom)</para></listitem>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>Allow PQcmdTuples() to return row counts for MOVE and FETCH (Neil)</para></listitem>
|
||||
<listitem><para>Add PQfreemem() for freeing memory on Win32, suggest for NOTIFY (Bruce)</para>
|
||||
<listitem><para>Add PQfreemem() for freeing memory on Windows, suggest for NOTIFY (Bruce)</para>
|
||||
<para>
|
||||
Win32 requires that memory allocated in a library be freed by a
|
||||
Windows requires that memory allocated in a library be freed by a
|
||||
function in the same library, hence free() doesn't work for freeing
|
||||
memory allocated by libpq. PQfreemem() is the proper way to free
|
||||
libpq memory, especially on Win32, and is recommended for other
|
||||
libpq memory, especially on Windows, and is recommended for other
|
||||
platforms as well.
|
||||
</para>
|
||||
</listitem>
|
||||
@ -961,8 +961,8 @@ zero-row record variable (Tom)</para></listitem>
|
||||
<listitem><para>Convert administration scripts to C (Peter)</para></listitem>
|
||||
<listitem><para>Bison >= 1.85 is now required to build the PostgreSQL grammar, if building from CVS</para></listitem>
|
||||
<listitem><para>Merge documentation into one book (Peter)</para></listitem>
|
||||
<listitem><para>Add Win32 compatibility functions (Bruce)</para></listitem>
|
||||
<listitem><para>Allow client interfaces to compile under MinGW/Win32 (Bruce)</para></listitem>
|
||||
<listitem><para>Add Windows compatibility functions (Bruce)</para></listitem>
|
||||
<listitem><para>Allow client interfaces to compile under MinGW (Bruce)</para></listitem>
|
||||
<listitem><para>New ereport() function for error reporting (Tom)</para></listitem>
|
||||
<listitem><para>Support Intel Linux compiler (Peter)</para></listitem>
|
||||
<listitem><para>Improve Linux startup scripts (Slawomir Sudnik, Darko Prenosil)</para></listitem>
|
||||
@ -1794,7 +1794,7 @@ of locale?</para></listitem>
|
||||
<listitem><para>Fix for sending large queries over non-blocking connections (Bernhard Herzog)</para></listitem>
|
||||
<listitem><para>Fix for libpq using timers on Win9X (David Ford)</para></listitem>
|
||||
<listitem><para>Allow libpq notify to handle servers with different-length identifiers (Tom)</para></listitem>
|
||||
<listitem><para>Add libpq PQescapeString() and PQescapeBytea() to Win32 (Bruce)</para></listitem>
|
||||
<listitem><para>Add libpq PQescapeString() and PQescapeBytea() to Windows (Bruce)</para></listitem>
|
||||
<listitem><para>Fix for SSL with non-blocking connections (Jack Bates)</para></listitem>
|
||||
<listitem><para>Add libpq connection timeout parameter (Denis A Ustimenko)</para></listitem>
|
||||
</itemizedlist>
|
||||
@ -1846,7 +1846,7 @@ of locale?</para></listitem>
|
||||
<listitem><para>Always enable multibyte in compile, remove --enable-multibyte option (Tatsuo)</para></listitem>
|
||||
<listitem><para>Always enable locale in compile, remove --enable-locale option (Peter)</para></listitem>
|
||||
<listitem><para>Fix for Win9x DLL creation (Magnus Naeslund)</para></listitem>
|
||||
<listitem><para>Fix for link() usage by WAL code on Win32, BeOS (Jason Tishler)</para></listitem>
|
||||
<listitem><para>Fix for link() usage by WAL code on Windows, BeOS (Jason Tishler)</para></listitem>
|
||||
<listitem><para>Add sys/types.h to c.h, remove from main files (Peter, Bruce)</para></listitem>
|
||||
<listitem><para>Fix AIX hang on SMP machines (Tomoyuki Niijima)</para></listitem>
|
||||
<listitem><para>AIX SMP hang fix (Tomoyuki Niijima)</para></listitem>
|
||||
@ -1871,7 +1871,7 @@ of locale?</para></listitem>
|
||||
<listitem><para>New Polish FAQ (Marcin Mazurek)</para></listitem>
|
||||
<listitem><para>Add Posix semaphore support (Tom)</para></listitem>
|
||||
<listitem><para>Document need for reindex (Bruce)</para></listitem>
|
||||
<listitem><para>Rename some internal identifiers to simplify Win32 compile (Jan, Katherine Ward)</para></listitem>
|
||||
<listitem><para>Rename some internal identifiers to simplify Windows compile (Jan, Katherine Ward)</para></listitem>
|
||||
<listitem><para>Add documentation on computing disk space (Bruce)</para></listitem>
|
||||
<listitem><para>Remove KSQO from GUC (Bruce)</para></listitem>
|
||||
<listitem><para>Fix memory leak in rtree (Kenneth Been)</para></listitem>
|
||||
@ -2588,8 +2588,8 @@ of locale?</para></listitem>
|
||||
<itemizedlist>
|
||||
<listitem><para>Configure, dynamic loader, and shared library fixes (Peter E)</para></listitem>
|
||||
<listitem><para>Fixes in QNX 4 port (Bernd Tegge)</para></listitem>
|
||||
<listitem><para>Fixes in Cygwin and Win32 ports (Jason Tishler, Gerhard Haring, Dmitry Yurtaev, Darko Prenosil, Mikhail Terekhov)</para></listitem>
|
||||
<listitem><para>Fix for Win32 socket communication failures (Magnus, Mikhail Terekhov)</para></listitem>
|
||||
<listitem><para>Fixes in Cygwin and Windows ports (Jason Tishler, Gerhard Haring, Dmitry Yurtaev, Darko Prenosil, Mikhail Terekhov)</para></listitem>
|
||||
<listitem><para>Fix for Windows socket communication failures (Magnus, Mikhail Terekhov)</para></listitem>
|
||||
<listitem><para>Hurd compile fix (Oliver Elphick)</para></listitem>
|
||||
<listitem><para>BeOS fixes (Cyril Velter)</para></listitem>
|
||||
<listitem><para>Remove configure --enable-unicode-conversion, now enabled by multibyte (Tatsuo)</para></listitem>
|
||||
@ -3675,7 +3675,7 @@ Clean up #include in /include directory (Bruce)
|
||||
Add scripts for checking includes (Bruce)
|
||||
Remove un-needed #include's from *.c files (Bruce)
|
||||
Change #include's to use <> and "" as appropriate (Bruce)
|
||||
Enable WIN32 compilation of libpq
|
||||
Enable Windows compilation of libpq
|
||||
Alpha spinlock fix from Uncle George <email>gatgul@voicenet.com</email>
|
||||
Overhaul of optimizer data structures (Tom)
|
||||
Fix to cygipc library (Yutaka Tanida)
|
||||
@ -3688,7 +3688,7 @@ New platform-specific regression handling (Tom)
|
||||
Rename oid8 -> oidvector and int28 -> int2vector (Bruce)
|
||||
Included all yacc and lex files into the distribution (Peter E.)
|
||||
Remove lextest, no longer needed (Peter E)
|
||||
Fix for libpq and psql on Win32 (Magnus)
|
||||
Fix for libpq and psql on Windows (Magnus)
|
||||
Internally change datetime and timespan into timestamp and interval (Thomas)
|
||||
Fix for plpgsql on BSD/OS
|
||||
Add SQL_ASCII test case to the regression test (Tatsuo)
|
||||
@ -3772,7 +3772,7 @@ Fixes for CASE in WHERE join clauses(Tom)
|
||||
Fix BTScan abort(Tom)
|
||||
Repair the check for redundant UNIQUE and PRIMARY KEY indexes(Thomas)
|
||||
Improve it so that it checks for multicolumn constraints(Thomas)
|
||||
Fix for Win32 making problem with MB enabled(Hiroki Kataoka)
|
||||
Fix for Windows making problem with MB enabled(Hiroki Kataoka)
|
||||
Allow BSD yacc and bison to compile pl code(Bruce)
|
||||
Fix SET NAMES working
|
||||
int8 fixes(Thomas)
|
||||
@ -4230,7 +4230,7 @@ Source Tree Changes
|
||||
-------------------
|
||||
Improve port matching(Tom)
|
||||
Portability fixes for SunOS
|
||||
Add NT/Win32 backend port and enable dynamic loading(Magnus and Daniel Horak)
|
||||
Add Windows NT backend port and enable dynamic loading(Magnus and Daniel Horak)
|
||||
New port to Cobalt Qube(Mips) running Linux(Tatsuo)
|
||||
Port to NetBSD/m68k(Mr. Mutsuki Nakajima)
|
||||
Port to NetBSD/sun3(Mr. Mutsuki Nakajima)
|
||||
@ -4338,7 +4338,7 @@ Timezone fixes(Tom)
|
||||
HP-UX fixes(Tom)
|
||||
Use implicit type coercion for matching DEFAULT values(Thomas)
|
||||
Add routines to help with single-byte (internal) character type(Thomas)
|
||||
Compilation of libpq for Win32 fixes(Magnus)
|
||||
Compilation of libpq for Windows fixes(Magnus)
|
||||
Upgrade to PyGreSQL 2.2(D'Arcy)
|
||||
</programlisting>
|
||||
</para>
|
||||
@ -4523,7 +4523,7 @@ New contrib/lo code for large object orphan removal(Peter)
|
||||
New psql command "SET CLIENT_ENCODING TO 'encoding'" for multibytes
|
||||
feature, see /doc/README.mb(Tatsuo)
|
||||
/contrib/noupdate code to revoke update permission on a column
|
||||
libpq can now be compiled on win32(Magnus)
|
||||
libpq can now be compiled on Windows(Magnus)
|
||||
Add PQsetdbLogin() in libpq
|
||||
New 8-byte integer type, checked by configure for OS support(Thomas)
|
||||
Better support for quoted table/column names(Thomas)
|
||||
@ -4586,7 +4586,7 @@ New setval() command to set sequence value(Massimo)
|
||||
Auto-remove unix socket file on start-up if no postmaster running(Massimo)
|
||||
Conditional trace package(Massimo)
|
||||
New UNLISTEN command(Massimo)
|
||||
psql and libpq now compile under win32 using win32.mak(Magnus)
|
||||
psql and libpq now compile under Windows using win32.mak(Magnus)
|
||||
Lo_read no longer stores trailing NULL(Bruce)
|
||||
Identifiers are now truncated to 31 characters internally(Bruce)
|
||||
Createuser options now availble on the command line
|
||||
@ -5551,7 +5551,7 @@ new OS-specific template files(Marc)
|
||||
no more need to edit Makefile.global(Marc)
|
||||
re-arrange include files(Marc)
|
||||
nextstep patches (Gregor Hoffleit)
|
||||
removed WIN32-specific code(Bruce)
|
||||
removed Windows-specific code(Bruce)
|
||||
removed postmaster -e option, now only postgres -e option (Bruce)
|
||||
merge duplicate library code in front/backends(Martin)
|
||||
now works with eBones, international Kerberos(Jun)
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/typeconv.sgml,v 1.37 2003/11/04 09:55:39 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/typeconv.sgml,v 1.38 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<chapter Id="typeconv">
|
||||
@ -289,7 +289,7 @@ candidate remains, use it; else continue to the next step.
|
||||
<step performance="required">
|
||||
<para>
|
||||
Run through all candidates and keep those with the most exact matches
|
||||
on input types. (Domain types are considered the same as their base type
|
||||
on input types. (Domains are considered the same as their base type
|
||||
for this purpose.) Keep all candidates if none have any exact matches.
|
||||
If only one candidate remains, use it; else continue to the next step.
|
||||
</para>
|
||||
@ -542,7 +542,7 @@ candidate remains, use it; else continue to the next step.
|
||||
<step performance="required">
|
||||
<para>
|
||||
Run through all candidates and keep those with the most exact matches
|
||||
on input types. (Domain types are considered the same as their base type
|
||||
on input types. (Domains are considered the same as their base type
|
||||
for this purpose.) Keep all candidates if none have any exact matches.
|
||||
If only one candidate remains, use it; else continue to the next step.
|
||||
</para>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.22 2003/08/31 17:32:20 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.23 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<sect1 id="xaggr">
|
||||
@ -140,16 +140,20 @@ CREATE AGGREGATE array_accum (
|
||||
|
||||
<programlisting>
|
||||
SELECT attrelid::regclass, array_accum(attname)
|
||||
FROM pg_attribute WHERE attnum > 0
|
||||
AND attrelid = 'pg_user'::regclass GROUP BY attrelid;
|
||||
FROM pg_attribute
|
||||
WHERE attnum > 0 AND attrelid = 'pg_user'::regclass
|
||||
GROUP BY attrelid;
|
||||
|
||||
attrelid | array_accum
|
||||
----------+-----------------------------------------------------------------------------
|
||||
pg_user | {usename,usesysid,usecreatedb,usesuper,usecatupd,passwd,valuntil,useconfig}
|
||||
(1 row)
|
||||
|
||||
SELECT attrelid::regclass, array_accum(atttypid)
|
||||
FROM pg_attribute WHERE attnum > 0
|
||||
AND attrelid = 'pg_user'::regclass GROUP BY attrelid;
|
||||
FROM pg_attribute
|
||||
WHERE attnum > 0 AND attrelid = 'pg_user'::regclass
|
||||
GROUP BY attrelid;
|
||||
|
||||
attrelid | array_accum
|
||||
----------+------------------------------
|
||||
pg_user | {19,23,16,16,16,25,702,1009}
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
<!--
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.77 2003/11/01 01:56:29 petere Exp $
|
||||
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.78 2003/11/12 22:47:47 petere Exp $
|
||||
-->
|
||||
|
||||
<sect1 id="xfunc">
|
||||
@ -392,9 +392,9 @@ SELECT name(emp) AS youngster
|
||||
result of the first function to it:
|
||||
|
||||
<screen>
|
||||
CREATE FUNCTION getname(emp) RETURNS text AS
|
||||
'SELECT $1.name;'
|
||||
LANGUAGE SQL;
|
||||
CREATE FUNCTION getname(emp) RETURNS text AS '
|
||||
SELECT $1.name;
|
||||
' LANGUAGE SQL;
|
||||
|
||||
SELECT getname(new_emp());
|
||||
getname
|
||||
@ -538,12 +538,12 @@ SELECT name, listchildren(name) FROM nodes;
|
||||
|
||||
<para>
|
||||
<acronym>SQL</acronym> functions may be declared to accept and
|
||||
return the <quote>polymorphic</> types
|
||||
<type>anyelement</type> and <type>anyarray</type>.
|
||||
See <xref linkend="extend-types-polymorphic"> for a more detailed explanation
|
||||
of polymorphic functions. Here is a polymorphic function
|
||||
<function>make_array</function> that builds up an array from two
|
||||
arbitrary data type elements:
|
||||
return the polymorphic types <type>anyelement</type> and
|
||||
<type>anyarray</type>. See <xref
|
||||
linkend="extend-types-polymorphic"> for a more detailed
|
||||
explanation of polymorphic functions. Here is a polymorphic
|
||||
function <function>make_array</function> that builds up an array
|
||||
from two arbitrary data type elements:
|
||||
<screen>
|
||||
CREATE FUNCTION make_array(anyelement, anyelement) RETURNS anyarray AS '
|
||||
SELECT ARRAY[$1, $2];
|
||||
@ -567,7 +567,7 @@ SELECT make_array(1, 2) AS intarray, make_array('a'::text, 'b') AS textarray;
|
||||
Without the typecast, you will get errors like this:
|
||||
<screen>
|
||||
<computeroutput>
|
||||
ERROR: could not determine ANYARRAY/ANYELEMENT type because input is UNKNOWN
|
||||
ERROR: could not determine "anyarray"/"anyelement" type because input has type "unknown"
|
||||
</computeroutput>
|
||||
</screen>
|
||||
</para>
|
||||
@ -576,7 +576,7 @@ ERROR: could not determine ANYARRAY/ANYELEMENT type because input is UNKNOWN
|
||||
It is permitted to have polymorphic arguments with a deterministic
|
||||
return type, but the converse is not. For example:
|
||||
<screen>
|
||||
CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS bool AS '
|
||||
CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS boolean AS '
|
||||
SELECT $1 > $2;
|
||||
' LANGUAGE SQL;
|
||||
|
||||
@ -589,8 +589,8 @@ SELECT is_greater(1, 2);
|
||||
CREATE FUNCTION invalid_func() RETURNS anyelement AS '
|
||||
SELECT 1;
|
||||
' LANGUAGE SQL;
|
||||
ERROR: cannot determine result datatype
|
||||
DETAIL: A function returning ANYARRAY or ANYELEMENT must have at least one argument of either type.
|
||||
ERROR: cannot determine result data type
|
||||
DETAIL: A function returning "anyarray" or "anyelement" must have at least one argument of either type.
|
||||
</screen>
|
||||
</para>
|
||||
</sect2>
|
||||
@ -758,15 +758,13 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
|
||||
that fails as well, the load will fail.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
The user ID the <productname>PostgreSQL</productname> server runs
|
||||
as must be able to traverse the path to the file you intend to
|
||||
load. Making the file or a higher-level directory not readable
|
||||
and/or not executable by the <systemitem>postgres</systemitem> user is a
|
||||
common mistake.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
The user ID the <productname>PostgreSQL</productname> server runs
|
||||
as must be able to traverse the path to the file you intend to
|
||||
load. Making the file or a higher-level directory not readable
|
||||
and/or not executable by the <systemitem>postgres</systemitem>
|
||||
user is a common mistake.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
In any case, the file name that is given in the
|
||||
@ -785,16 +783,14 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
After it is used for the first time, a dynamically loaded object
|
||||
file is retained in memory. Future calls in the same session to the
|
||||
function(s) in that file will only incur the small overhead of a symbol
|
||||
table lookup. If you need to force a reload of an object file, for
|
||||
example after recompiling it, use the <command>LOAD</> command or
|
||||
begin a fresh session.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
After it is used for the first time, a dynamically loaded object
|
||||
file is retained in memory. Future calls in the same session to
|
||||
the function(s) in that file will only incur the small overhead of
|
||||
a symbol table lookup. If you need to force a reload of an object
|
||||
file, for example after recompiling it, use the <command>LOAD</>
|
||||
command or begin a fresh session.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is recommended to locate shared libraries either relative to
|
||||
@ -805,17 +801,15 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
|
||||
command <literal>pg_config --pkglibdir</literal>.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Before <productname>PostgreSQL</productname> release 7.2, only exact
|
||||
absolute paths to object files could be specified in <command>CREATE
|
||||
FUNCTION</>. This approach is now deprecated since it makes the
|
||||
function definition unnecessarily unportable. It's best to specify
|
||||
just the shared library name with no path nor extension, and let
|
||||
the search mechanism provide that information instead.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Before <productname>PostgreSQL</productname> release 7.2, only
|
||||
exact absolute paths to object files could be specified in
|
||||
<command>CREATE FUNCTION</>. This approach is now deprecated
|
||||
since it makes the function definition unnecessarily unportable.
|
||||
It's best to specify just the shared library name with no path nor
|
||||
extension, and let the search mechanism provide that information
|
||||
instead.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="xfunc-c-basetype">
|
||||
@ -1685,8 +1679,7 @@ c_overpaid(PG_FUNCTION_ARGS)
|
||||
<function>c_overpaid</function> in SQL:
|
||||
|
||||
<programlisting>
|
||||
CREATE FUNCTION c_overpaid(emp, integer)
|
||||
RETURNS boolean
|
||||
CREATE FUNCTION c_overpaid(emp, integer) RETURNS boolean
|
||||
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'c_overpaid'
|
||||
LANGUAGE C;
|
||||
</programlisting>
|
||||
@ -2111,7 +2104,7 @@ CREATE OR REPLACE FUNCTION testpassbyval(integer, integer) RETURNS SETOF __testp
|
||||
|
||||
<para>
|
||||
C-language functions may be declared to accept and
|
||||
return the <quote>polymorphic</> types
|
||||
return the polymorphic types
|
||||
<type>anyelement</type> and <type>anyarray</type>.
|
||||
See <xref linkend="extend-types-polymorphic"> for a more detailed explanation
|
||||
of polymorphic functions. When function arguments or return types
|
||||
@ -2178,14 +2171,13 @@ make_array(PG_FUNCTION_ARGS)
|
||||
<function>make_array</function> in SQL:
|
||||
|
||||
<programlisting>
|
||||
CREATE FUNCTION make_array(anyelement)
|
||||
RETURNS anyarray
|
||||
CREATE FUNCTION make_array(anyelement) RETURNS anyarray
|
||||
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'make_array'
|
||||
LANGUAGE 'C' STRICT;
|
||||
LANGUAGE C STRICT;
|
||||
</programlisting>
|
||||
|
||||
Note the use of STRICT; this is essential since the code is not
|
||||
bothering to test for a NULL input.
|
||||
Note the use of <literal>STRICT</literal>; this is essential
|
||||
since the code is not bothering to test for a null input.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user