1999-07-22 17:11:05 +02:00
|
|
|
<chapter id="xfunc">
|
|
|
|
<title id="xfunc-title">Extending <acronym>SQL</acronym>: Functions</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As it turns out, part of defining a new type is the
|
|
|
|
definition of functions that describe its behavior.
|
|
|
|
Consequently, while it is possible to define a new
|
|
|
|
function without defining a new type, the reverse is
|
|
|
|
not true. We therefore describe how to add new functions
|
|
|
|
to <productname>Postgres</productname> before describing
|
|
|
|
how to add new types.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<productname>Postgres</productname> <acronym>SQL</acronym>
|
|
|
|
provides three types of functions:
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
query language functions
|
|
|
|
(functions written in <acronym>SQL</acronym>)
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
procedural language
|
|
|
|
functions (functions written in, for example, PLTCL or PLSQL)
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
programming
|
|
|
|
language functions (functions written in a compiled
|
|
|
|
programming language such as <acronym>C</acronym>)
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
Every kind
|
|
|
|
of function can take a base type, a composite type or
|
|
|
|
some combination as arguments (parameters). In addition,
|
|
|
|
every kind of function can return a base type or
|
|
|
|
a composite type. It's easiest to define <acronym>SQL</acronym>
|
|
|
|
functions, so we'll start with those. Examples in this section
|
|
|
|
can also be found in <filename>funcs.sql</filename>
|
|
|
|
and <filename>funcs.c</filename>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
<title>Query Language (<acronym>SQL</acronym>) Functions</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
SQL functions execute an arbitrary list of SQL queries, returning
|
|
|
|
the results of the last query in the list. SQL functions in general
|
|
|
|
return sets. If their returntype is not specified as a
|
|
|
|
<literal>setof</literal>,
|
|
|
|
then an arbitrary element of the last query's result will be returned.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The body of a SQL function following AS
|
|
|
|
should be a list of queries separated by whitespace characters and
|
|
|
|
bracketed within quotation marks. Note that quotation marks used in
|
|
|
|
the queries must be escaped, by preceding them with two
|
|
|
|
backslashes.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Arguments to the SQL function may be referenced in the queries using
|
|
|
|
a $n syntax: $1 refers to the first argument, $2 to the second, and so
|
|
|
|
on. If an argument is complex, then a <firstterm>dot</firstterm>
|
|
|
|
notation (e.g. "$1.emp") may be
|
|
|
|
used to access attributes of the argument or
|
|
|
|
to invoke functions.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Examples</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To illustrate a simple SQL function, consider the following,
|
|
|
|
which might be used to debit a bank account:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
create function TP1 (int4, float8) returns int4
|
|
|
|
as 'update BANK set balance = BANK.balance - $2
|
|
|
|
where BANK.acctountno = $1
|
|
|
|
select(x = 1)'
|
|
|
|
language 'sql';
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
A user could execute this function to debit account 17 by $100.00 as
|
|
|
|
follows:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
select (x = TP1( 17,100.0));
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The following more interesting example takes a single argument of type
|
|
|
|
EMP, and retrieves multiple results:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
select function hobbies (EMP) returns set of HOBBIES
|
|
|
|
as 'select (HOBBIES.all) from HOBBIES
|
|
|
|
where $1.name = HOBBIES.person'
|
|
|
|
language 'sql';
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title><acronym>SQL</acronym> Functions on Base Types</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The simplest possible <acronym>SQL</acronym> function has no arguments and
|
|
|
|
simply returns a base type, such as <acronym>int4</acronym>:
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
CREATE FUNCTION one() RETURNS int4
|
|
|
|
AS 'SELECT 1 as RESULT' LANGUAGE 'sql';
|
|
|
|
|
|
|
|
SELECT one() AS answer;
|
|
|
|
|
|
|
|
+-------+
|
|
|
|
|answer |
|
|
|
|
+-------+
|
|
|
|
|1 |
|
|
|
|
+-------+
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
Notice that we defined a target list for the function
|
|
|
|
(with the name RESULT), but the target list of the
|
|
|
|
query that invoked the function overrode the function's
|
|
|
|
target list. Hence, the result is labelled answer
|
|
|
|
instead of one.
|
1999-07-22 17:11:05 +02:00
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
It's almost as easy to define <acronym>SQL</acronym> functions
|
1999-03-14 16:24:15 +01:00
|
|
|
that take base types as arguments. In the example below, notice
|
1998-03-01 09:16:16 +01:00
|
|
|
how we refer to the arguments within the function as $1
|
1999-07-22 17:11:05 +02:00
|
|
|
and $2:
|
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
CREATE FUNCTION add_em(int4, int4) RETURNS int4
|
|
|
|
AS 'SELECT $1 + $2;' LANGUAGE 'sql';
|
|
|
|
|
|
|
|
SELECT add_em(1, 2) AS answer;
|
|
|
|
|
|
|
|
+-------+
|
|
|
|
|answer |
|
|
|
|
+-------+
|
|
|
|
|3 |
|
|
|
|
+-------+
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<sect2>
|
|
|
|
<title><acronym>SQL</acronym> Functions on Composite Types</title>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
When specifying functions with arguments of composite
|
|
|
|
types (such as EMP), we must not only specify which
|
|
|
|
argument we want (as we did above with $1 and $2) but
|
|
|
|
also the attributes of that argument. For example,
|
|
|
|
take the function double_salary that computes what your
|
1999-07-22 17:11:05 +02:00
|
|
|
salary would be if it were doubled:
|
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
CREATE FUNCTION double_salary(EMP) RETURNS int4
|
|
|
|
AS 'SELECT $1.salary * 2 AS salary;' LANGUAGE 'sql';
|
|
|
|
|
|
|
|
SELECT name, double_salary(EMP) AS dream
|
|
|
|
FROM EMP
|
1999-03-14 16:24:15 +01:00
|
|
|
WHERE EMP.cubicle ~= '(2,1)'::point;
|
|
|
|
|
1998-03-01 09:16:16 +01:00
|
|
|
|
|
|
|
+-----+-------+
|
|
|
|
|name | dream |
|
|
|
|
+-----+-------+
|
|
|
|
|Sam | 2400 |
|
|
|
|
+-----+-------+
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
Notice the use of the syntax $1.salary.
|
|
|
|
Before launching into the subject of functions that
|
|
|
|
return composite types, we must first introduce the
|
|
|
|
function notation for projecting attributes. The simple way
|
|
|
|
to explain this is that we can usually use the
|
1999-07-22 17:11:05 +02:00
|
|
|
notation attribute(class) and class.attribute interchangably:
|
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
--
|
|
|
|
-- this is the same as:
|
|
|
|
-- SELECT EMP.name AS youngster FROM EMP WHERE EMP.age < 30
|
|
|
|
--
|
|
|
|
SELECT name(EMP) AS youngster
|
|
|
|
FROM EMP
|
|
|
|
WHERE age(EMP) < 30;
|
|
|
|
|
|
|
|
+----------+
|
|
|
|
|youngster |
|
|
|
|
+----------+
|
|
|
|
|Sam |
|
|
|
|
+----------+
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
As we shall see, however, this is not always the case.
|
|
|
|
This function notation is important when we want to use
|
|
|
|
a function that returns a single instance. We do this
|
|
|
|
by assembling the entire instance within the function,
|
|
|
|
attribute by attribute. This is an example of a function
|
|
|
|
that returns a single EMP instance:
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
CREATE FUNCTION new_emp() RETURNS EMP
|
|
|
|
AS 'SELECT \'None\'::text AS name,
|
|
|
|
1000 AS salary,
|
|
|
|
25 AS age,
|
1999-03-14 16:24:15 +01:00
|
|
|
\'(2,2)\'::point AS cubicle'
|
1998-03-01 09:16:16 +01:00
|
|
|
LANGUAGE 'sql';
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
In this case we have specified each of the attributes
|
|
|
|
with a constant value, but any computation or expression
|
|
|
|
could have been substituted for these constants.
|
|
|
|
Defining a function like this can be tricky. Some of
|
|
|
|
the more important caveats are as follows:
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The target list order must be exactly the same as
|
|
|
|
that in which the attributes appear in the CREATE
|
|
|
|
TABLE statement (or when you execute a .* query).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
You must typecast the expressions (using ::) very carefully
|
|
|
|
or you will see the following error:
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
<computeroutput>
|
|
|
|
WARN::function declared to return type EMP does not retrieve (EMP.*)
|
|
|
|
</computeroutput>
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When calling a function that returns an instance, we
|
1998-03-01 09:16:16 +01:00
|
|
|
cannot retrieve the entire instance. We must either
|
|
|
|
project an attribute out of the instance or pass the
|
|
|
|
entire instance into another function.
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
SELECT name(new_emp()) AS nobody;
|
|
|
|
|
|
|
|
+-------+
|
|
|
|
|nobody |
|
|
|
|
+-------+
|
|
|
|
|None |
|
|
|
|
+-------+
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The reason why, in general, we must use the function
|
1998-03-01 09:16:16 +01:00
|
|
|
syntax for projecting attributes of function return
|
|
|
|
values is that the parser just doesn't understand
|
|
|
|
the other (dot) syntax for projection when combined
|
|
|
|
with function calls.
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
SELECT new_emp().name AS nobody;
|
|
|
|
WARN:parser: syntax error at or near "."
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Any collection of commands in the <acronym>SQL</acronym> query
|
1999-03-14 16:24:15 +01:00
|
|
|
language can be packaged together and defined as a function.
|
1999-07-22 17:11:05 +02:00
|
|
|
The commands can include updates (i.e., <acronym>insert</acronym>,
|
|
|
|
<acronym>update</acronym> and <acronym>delete</acronym>) as well
|
|
|
|
as <acronym>select</acronym> queries. However, the final command
|
|
|
|
must be a <acronym>select</acronym> that returns whatever is
|
1998-03-01 09:16:16 +01:00
|
|
|
specified as the function's returntype.
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
CREATE FUNCTION clean_EMP () RETURNS int4
|
|
|
|
AS 'DELETE FROM EMP WHERE EMP.salary <= 0;
|
|
|
|
SELECT 1 AS ignore_this'
|
|
|
|
LANGUAGE 'sql';
|
|
|
|
|
|
|
|
SELECT clean_EMP();
|
|
|
|
|
|
|
|
+--+
|
|
|
|
|x |
|
|
|
|
+--+
|
|
|
|
|1 |
|
|
|
|
+--+
|
1999-03-14 16:24:15 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
<title>Procedural Language Functions</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Procedural languages aren't built into Postgres. They are offered
|
|
|
|
by loadable modules. Please refer to the documentation for the
|
|
|
|
PL in question for details about the syntax and how the AS
|
|
|
|
clause is interpreted by the PL handler.
|
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
|
|
|
There are two procedural languages available with the standard
|
|
|
|
<productname>Postgres</productname> distribution (PLTCL and PLSQL), and other
|
|
|
|
languages can be defined.
|
|
|
|
Refer to <xref linkend="xplang-title" endterm="xplang-title"> for
|
|
|
|
more information.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<sect1>
|
|
|
|
<title>Internal Functions</title>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
|
|
|
Internal functions are functions written in C which have been statically
|
|
|
|
linked into the <productname>Postgres</productname> backend
|
|
|
|
process. The AS
|
|
|
|
clause gives the C-language name of the function, which need not be the
|
|
|
|
same as the name being declared for SQL use.
|
|
|
|
(For reasons of backwards compatibility, an empty AS
|
|
|
|
string is accepted as meaning that the C-language function name is the
|
|
|
|
same as the SQL name.) Normally, all internal functions present in the
|
|
|
|
backend are declared as SQL functions during database initialization,
|
|
|
|
but a user could use <command>CREATE FUNCTION</command>
|
|
|
|
to create additional alias names for an internal function.
|
|
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
<title>Compiled (C) Language Functions</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Functions written in C can be defined to Postgres, which will dynamically
|
|
|
|
load them into its address space. The AS
|
|
|
|
clause gives the full path name of the object file that contains the
|
|
|
|
function. This file is loaded either using
|
|
|
|
load(l)
|
|
|
|
or automatically the first time the function is necessary for
|
|
|
|
execution. Repeated execution of a function will cause negligible
|
|
|
|
additional overhead, as the function will remain in a main memory
|
|
|
|
cache.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The string which specifies the object file (the string in the AS clause)
|
|
|
|
should be the <emphasis>full path</emphasis>
|
|
|
|
of the object code file for the function, bracketed by quotation
|
|
|
|
marks. (<productname>Postgres</productname> will not compile a
|
|
|
|
function automatically; it must
|
|
|
|
be compiled before it is used in a CREATE FUNCTION
|
|
|
|
command. See below for additional information.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>C Language Functions on Base Types</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The following table gives the C type required for parameters in the C
|
|
|
|
functions that will be loaded into Postgres. The "Defined In"
|
|
|
|
column gives the actual header file (in the
|
|
|
|
<filename>.../src/backend/</filename>
|
|
|
|
directory) that the equivalent C type is defined. However, if you
|
|
|
|
include <filename>utils/builtins.h</filename>,
|
|
|
|
these files will automatically be
|
|
|
|
included.
|
|
|
|
|
|
|
|
<table tocentry="1">
|
|
|
|
<title>Equivalent C Types
|
|
|
|
for Built-In <productname>Postgres</productname> Types</title>
|
|
|
|
<titleabbrev>Equivalent C Types</titleabbrev>
|
|
|
|
<tgroup cols="3">
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
Built-In Type
|
|
|
|
</entry>
|
|
|
|
<entry>
|
|
|
|
C Type
|
|
|
|
</entry>
|
|
|
|
<entry>
|
|
|
|
Defined In
|
|
|
|
</entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<row>
|
|
|
|
<entry>abstime</entry>
|
|
|
|
<entry>AbsoluteTime</entry>
|
|
|
|
<entry>utils/nabstime.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>bool</entry>
|
|
|
|
<entry>bool</entry>
|
|
|
|
<entry>include/c.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>box</entry>
|
|
|
|
<entry>(BOX *)</entry>
|
|
|
|
<entry>utils/geo-decls.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>bytea</entry>
|
|
|
|
<entry>(bytea *)</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>char</entry>
|
|
|
|
<entry>char</entry>
|
|
|
|
<entry>N/A</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>cid</entry>
|
|
|
|
<entry>CID</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>datetime</entry>
|
|
|
|
<entry>(DateTime *)</entry>
|
|
|
|
<entry>include/c.h or include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>int2</entry>
|
|
|
|
<entry>int2</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>int28</entry>
|
|
|
|
<entry>(int28 *)</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>int4</entry>
|
|
|
|
<entry>int4</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>float4</entry>
|
|
|
|
<entry>float32 or (float4 *)</entry>
|
|
|
|
<entry>include/c.h or include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>float8</entry>
|
|
|
|
<entry>float64 or (float8 *)</entry>
|
|
|
|
<entry>include/c.h or include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>lseg</entry>
|
|
|
|
<entry>(LSEG *)</entry>
|
|
|
|
<entry>include/geo-decls.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>name</entry>
|
|
|
|
<entry>(Name)</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>oid</entry>
|
|
|
|
<entry>oid</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>oid8</entry>
|
|
|
|
<entry>(oid8 *)</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>path</entry>
|
|
|
|
<entry>(PATH *)</entry>
|
|
|
|
<entry>utils/geo-decls.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>point</entry>
|
|
|
|
<entry>(POINT *)</entry>
|
|
|
|
<entry>utils/geo-decls.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>regproc</entry>
|
|
|
|
<entry>regproc or REGPROC</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>reltime</entry>
|
|
|
|
<entry>RelativeTime</entry>
|
|
|
|
<entry>utils/nabstime.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>text</entry>
|
|
|
|
<entry>(text *)</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>tid</entry>
|
|
|
|
<entry>ItemPointer</entry>
|
|
|
|
<entry>storage/itemptr.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>timespan</entry>
|
|
|
|
<entry>(TimeSpan *)</entry>
|
|
|
|
<entry>include/c.h or include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>tinterval</entry>
|
|
|
|
<entry>TimeInterval</entry>
|
|
|
|
<entry>utils/nabstime.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>uint2</entry>
|
|
|
|
<entry>uint16</entry>
|
|
|
|
<entry>include/c.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>uint4</entry>
|
|
|
|
<entry>uint32</entry>
|
|
|
|
<entry>include/c.h</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>xid</entry>
|
|
|
|
<entry>(XID *)</entry>
|
|
|
|
<entry>include/postgres.h</entry>
|
|
|
|
</row>
|
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</table>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Internally, <productname>Postgres</productname> regards a
|
1999-03-14 16:24:15 +01:00
|
|
|
base type as a "blob of memory." The user-defined
|
|
|
|
functions that you define over a type in turn define the
|
1999-07-22 17:11:05 +02:00
|
|
|
way that <productname>Postgres</productname> can operate
|
|
|
|
on it. That is, <productname>Postgres</productname> will
|
1999-03-14 16:24:15 +01:00
|
|
|
only store and retrieve the data from disk and use your
|
|
|
|
user-defined functions to input, process, and output the data.
|
1998-03-01 09:16:16 +01:00
|
|
|
Base types can have one of three internal formats:
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
pass by value, fixed-length
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
pass by reference, fixed-length
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
pass by reference, variable-length
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
By-value types can only be 1, 2 or 4 bytes in length
|
|
|
|
(even if your computer supports by-value types of other
|
1999-07-22 17:11:05 +02:00
|
|
|
sizes). <productname>Postgres</productname> itself
|
1999-03-14 16:24:15 +01:00
|
|
|
only passes integer types by value. You should be careful
|
|
|
|
to define your types such that they will be the same
|
|
|
|
size (in bytes) on all architectures. For example, the
|
1999-07-22 17:11:05 +02:00
|
|
|
<acronym>long</acronym> type is dangerous because it
|
1999-03-14 16:24:15 +01:00
|
|
|
is 4 bytes on some machines and 8 bytes on others, whereas
|
1999-07-22 17:11:05 +02:00
|
|
|
<acronym>int</acronym> type is 4 bytes on most
|
|
|
|
<acronym>UNIX</acronym> machines (though not on most
|
1999-03-14 16:24:15 +01:00
|
|
|
personal computers). A reasonable implementation of
|
1999-07-22 17:11:05 +02:00
|
|
|
the <acronym>int4</acronym> type on <acronym>UNIX</acronym>
|
1998-03-01 09:16:16 +01:00
|
|
|
machines might be:
|
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<programlisting>
|
|
|
|
/* 4-byte integer, passed by value */
|
|
|
|
typedef int int4;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
On the other hand, fixed-length types of any size may
|
|
|
|
be passed by-reference. For example, here is a sample
|
1999-07-22 17:11:05 +02:00
|
|
|
implementation of a <productname>Postgres</productname> type:
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<programlisting>
|
|
|
|
/* 16-byte structure, passed by reference */
|
|
|
|
typedef struct
|
|
|
|
{
|
|
|
|
double x, y;
|
|
|
|
} Point;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
Only pointers to such types can be used when passing
|
1999-07-22 17:11:05 +02:00
|
|
|
them in and out of <productname>Postgres</productname> functions.
|
1998-03-01 09:16:16 +01:00
|
|
|
Finally, all variable-length types must also be passed
|
|
|
|
by reference. All variable-length types must begin
|
|
|
|
with a length field of exactly 4 bytes, and all data to
|
|
|
|
be stored within that type must be located in the memory
|
|
|
|
immediately following that length field. The
|
|
|
|
length field is the total length of the structure
|
|
|
|
(i.e., it includes the size of the length field
|
|
|
|
itself). We can define the text type as follows:
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
typedef struct {
|
|
|
|
int4 length;
|
|
|
|
char data[1];
|
|
|
|
} text;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
Obviously, the data field is not long enough to hold
|
1999-07-22 17:11:05 +02:00
|
|
|
all possible strings; it's impossible to declare such
|
|
|
|
a structure in <acronym>C</acronym>. When manipulating
|
1999-03-14 16:24:15 +01:00
|
|
|
variable-length types, we must be careful to allocate
|
|
|
|
the correct amount of memory and initialize the length field.
|
|
|
|
For example, if we wanted to store 40 bytes in a text
|
1998-03-01 09:16:16 +01:00
|
|
|
structure, we might use a code fragment like this:
|
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<programlisting>
|
|
|
|
#include "postgres.h"
|
|
|
|
...
|
|
|
|
char buffer[40]; /* our source data */
|
|
|
|
...
|
|
|
|
text *destination = (text *) palloc(VARHDRSZ + 40);
|
|
|
|
destination->length = VARHDRSZ + 40;
|
|
|
|
memmove(destination->data, buffer, 40);
|
|
|
|
...
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
Now that we've gone over all of the possible structures
|
|
|
|
for base types, we can show some examples of real functions.
|
1999-07-22 17:11:05 +02:00
|
|
|
Suppose <filename>funcs.c</filename> look like:
|
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
#include <string.h>
|
1998-04-26 06:18:06 +02:00
|
|
|
#include "postgres.h"
|
1999-03-14 16:24:15 +01:00
|
|
|
|
|
|
|
/* By Value */
|
|
|
|
|
1998-03-01 09:16:16 +01:00
|
|
|
int
|
|
|
|
add_one(int arg)
|
|
|
|
{
|
|
|
|
return(arg + 1);
|
|
|
|
}
|
1999-03-14 16:24:15 +01:00
|
|
|
|
|
|
|
/* By Reference, Fixed Length */
|
|
|
|
|
|
|
|
Point *
|
|
|
|
makepoint(Point *pointx, Point *pointy )
|
1998-03-01 09:16:16 +01:00
|
|
|
{
|
1999-03-14 16:24:15 +01:00
|
|
|
Point *new_point = (Point *) palloc(sizeof(Point));
|
|
|
|
|
|
|
|
new_point->x = pointx->x;
|
|
|
|
new_point->y = pointy->y;
|
|
|
|
|
|
|
|
return new_point;
|
1998-03-01 09:16:16 +01:00
|
|
|
}
|
1999-03-14 16:24:15 +01:00
|
|
|
|
|
|
|
/* By Reference, Variable Length */
|
|
|
|
|
1998-03-01 09:16:16 +01:00
|
|
|
text *
|
|
|
|
copytext(text *t)
|
|
|
|
{
|
|
|
|
/*
|
|
|
|
* VARSIZE is the total size of the struct in bytes.
|
|
|
|
*/
|
|
|
|
text *new_t = (text *) palloc(VARSIZE(t));
|
|
|
|
memset(new_t, 0, VARSIZE(t));
|
|
|
|
VARSIZE(new_t) = VARSIZE(t);
|
|
|
|
/*
|
|
|
|
* VARDATA is a pointer to the data region of the struct.
|
|
|
|
*/
|
|
|
|
memcpy((void *) VARDATA(new_t), /* destination */
|
|
|
|
(void *) VARDATA(t), /* source */
|
|
|
|
VARSIZE(t)-VARHDRSZ); /* how many bytes */
|
|
|
|
return(new_t);
|
|
|
|
}
|
1999-03-14 16:24:15 +01:00
|
|
|
|
|
|
|
text *
|
|
|
|
concat_text(text *arg1, text *arg2)
|
|
|
|
{
|
|
|
|
int32 new_text_size = VARSIZE(arg1) + VARSIZE(arg2) - VARHDRSZ;
|
|
|
|
text *new_text = (text *) palloc(new_text_size);
|
|
|
|
|
|
|
|
memset((void *) new_text, 0, new_text_size);
|
|
|
|
VARSIZE(new_text) = new_text_size;
|
|
|
|
strncpy(VARDATA(new_text), VARDATA(arg1), VARSIZE(arg1)-VARHDRSZ);
|
|
|
|
strncat(VARDATA(new_text), VARDATA(arg2), VARSIZE(arg2)-VARHDRSZ);
|
|
|
|
return (new_text);
|
|
|
|
}
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
|
|
|
On <acronym>OSF/1</acronym> we would type:
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
CREATE FUNCTION add_one(int4) RETURNS int4
|
1999-07-22 17:11:05 +02:00
|
|
|
AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-03-14 16:24:15 +01:00
|
|
|
CREATE FUNCTION makepoint(point, point) RETURNS point
|
1999-07-22 17:11:05 +02:00
|
|
|
AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
|
1999-03-14 16:24:15 +01:00
|
|
|
|
1998-04-26 06:18:06 +02:00
|
|
|
CREATE FUNCTION concat_text(text, text) RETURNS text
|
1999-07-22 17:11:05 +02:00
|
|
|
AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
|
1999-03-14 16:24:15 +01:00
|
|
|
|
1998-03-01 09:16:16 +01:00
|
|
|
CREATE FUNCTION copytext(text) RETURNS text
|
1999-07-22 17:11:05 +02:00
|
|
|
AS '<replaceable>PGROOT</replaceable>/tutorial/funcs.so' LANGUAGE 'c';
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
On other systems, we might have to make the filename
|
|
|
|
end in .sl (to indicate that it's a shared library).
|
1999-07-22 17:11:05 +02:00
|
|
|
</para>
|
|
|
|
</sect2>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<sect2>
|
|
|
|
<title>C Language Functions on Composite Types</title>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
Composite types do not have a fixed layout like C
|
|
|
|
structures. Instances of a composite type may contain
|
|
|
|
null fields. In addition, composite types that are
|
|
|
|
part of an inheritance hierarchy may have different
|
|
|
|
fields than other members of the same inheritance hierarchy.
|
1999-07-22 17:11:05 +02:00
|
|
|
Therefore, <productname>Postgres</productname> provides
|
1999-03-14 16:24:15 +01:00
|
|
|
a procedural interface for accessing fields of composite types
|
1999-07-22 17:11:05 +02:00
|
|
|
from C. As <productname>Postgres</productname> processes
|
1999-03-14 16:24:15 +01:00
|
|
|
a set of instances, each instance will be passed into your
|
1999-07-22 17:11:05 +02:00
|
|
|
function as an opaque structure of type <acronym>TUPLE</acronym>.
|
1998-03-01 09:16:16 +01:00
|
|
|
Suppose we want to write a function to answer the query
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
* SELECT name, c_overpaid(EMP, 1500) AS overpaid
|
|
|
|
FROM EMP
|
|
|
|
WHERE name = 'Bill' or name = 'Sam';
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
|
1998-03-01 09:16:16 +01:00
|
|
|
In the query above, we can define c_overpaid as:
|
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<programlisting>
|
1998-04-26 06:18:06 +02:00
|
|
|
#include "postgres.h"
|
1999-03-14 16:24:15 +01:00
|
|
|
#include "executor/executor.h" /* for GetAttributeByName() */
|
|
|
|
|
1998-03-01 09:16:16 +01:00
|
|
|
bool
|
1999-03-14 16:24:15 +01:00
|
|
|
c_overpaid(TupleTableSlot *t, /* the current instance of EMP */
|
1998-03-01 09:16:16 +01:00
|
|
|
int4 limit)
|
|
|
|
{
|
|
|
|
bool isnull = false;
|
|
|
|
int4 salary;
|
|
|
|
salary = (int4) GetAttributeByName(t, "salary", &isnull);
|
|
|
|
if (isnull)
|
|
|
|
return (false);
|
|
|
|
return(salary > limit);
|
|
|
|
}
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
|
|
|
<acronym>GetAttributeByName</acronym> is the
|
|
|
|
<productname>Postgres</productname> system function that
|
1998-03-01 09:16:16 +01:00
|
|
|
returns attributes out of the current instance. It has
|
|
|
|
three arguments: the argument of type TUPLE passed into
|
|
|
|
the function, the name of the desired attribute, and a
|
|
|
|
return parameter that describes whether the attribute
|
1999-07-22 17:11:05 +02:00
|
|
|
is null. <acronym>GetAttributeByName</acronym> will
|
1999-03-14 16:24:15 +01:00
|
|
|
align data properly so you can cast its return value to
|
|
|
|
the desired type. For example, if you have an attribute
|
1999-07-22 17:11:05 +02:00
|
|
|
name which is of the type name, the <acronym>GetAttributeByName</acronym>
|
1999-03-14 16:24:15 +01:00
|
|
|
call would look like:
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
char *str;
|
|
|
|
...
|
|
|
|
str = (char *) GetAttributeByName(t, "name", &isnull)
|
1999-07-22 17:11:05 +02:00
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
|
|
|
The following query lets <productname>Postgres</productname>
|
1999-03-14 16:24:15 +01:00
|
|
|
know about the c_overpaid function:
|
1999-07-22 17:11:05 +02:00
|
|
|
|
|
|
|
<programlisting>
|
1998-03-01 09:16:16 +01:00
|
|
|
* CREATE FUNCTION c_overpaid(EMP, int4) RETURNS bool
|
1999-07-22 17:11:05 +02:00
|
|
|
AS '<replaceable>PGROOT</replaceable>/tutorial/obj/funcs.so' LANGUAGE 'c';
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
While there are ways to construct new instances or modify
|
|
|
|
existing instances from within a C function, these
|
|
|
|
are far too complex to discuss in this manual.
|
1999-07-22 17:11:05 +02:00
|
|
|
</para>
|
|
|
|
</sect2>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<sect2>
|
|
|
|
<title>Writing Code</title>
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<para>
|
1998-03-01 09:16:16 +01:00
|
|
|
We now turn to the more difficult task of writing
|
|
|
|
programming language functions. Be warned: this section
|
|
|
|
of the manual will not make you a programmer. You must
|
1999-07-22 17:11:05 +02:00
|
|
|
have a good understanding of <acronym>C</acronym>
|
1999-03-14 16:24:15 +01:00
|
|
|
(including the use of pointers and the malloc memory manager)
|
1999-07-22 17:11:05 +02:00
|
|
|
before trying to write <acronym>C</acronym> functions for
|
|
|
|
use with <productname>Postgres</productname>. While it may
|
1999-03-14 16:24:15 +01:00
|
|
|
be possible to load functions written in languages other
|
1999-07-22 17:11:05 +02:00
|
|
|
than <acronym>C</acronym> into <productname>Postgres</productname>,
|
1999-03-14 16:24:15 +01:00
|
|
|
this is often difficult (when it is possible at all)
|
1999-07-22 17:11:05 +02:00
|
|
|
because other languages, such as <acronym>FORTRAN</acronym>
|
|
|
|
and <acronym>Pascal</acronym> often do not follow the same
|
|
|
|
<firstterm>calling convention</firstterm>
|
|
|
|
as <acronym>C</acronym>. That is, other
|
1998-03-01 09:16:16 +01:00
|
|
|
languages do not pass argument and return values
|
|
|
|
between functions in the same way. For this reason, we
|
|
|
|
will assume that your programming language functions
|
1999-07-22 17:11:05 +02:00
|
|
|
are written in <acronym>C</acronym>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
C functions with base type arguments can be written in a
|
|
|
|
straightforward fashion. The C equivalents of built-in Postgres types
|
|
|
|
are accessible in a C file if
|
|
|
|
<filename><replaceable>PGROOT</replaceable>/src/backend/utils/builtins.h</filename>
|
|
|
|
is included as a header file. This can be achieved by having
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
#include <utils/builtins.h>
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
at the top of the C source file.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The basic rules for building <acronym>C</acronym> functions
|
1999-03-14 16:24:15 +01:00
|
|
|
are as follows:
|
1998-03-01 09:16:16 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Most of the header (include) files for
|
|
|
|
<productname>Postgres</productname>
|
|
|
|
should already be installed in
|
|
|
|
<filename><replaceable>PGROOT</replaceable>/include</filename> (see Figure 2).
|
|
|
|
You should always include
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
-I$PGROOT/include
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
on your cc command lines. Sometimes, you may
|
|
|
|
find that you require header files that are in
|
|
|
|
the server source itself (i.e., you need a file
|
|
|
|
we neglected to install in include). In those
|
|
|
|
cases you may need to add one or more of
|
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
-I$PGROOT/src/backend
|
|
|
|
-I$PGROOT/src/backend/include
|
|
|
|
-I$PGROOT/src/backend/port/<PORTNAME>
|
|
|
|
-I$PGROOT/src/backend/obj
|
|
|
|
</programlisting>
|
|
|
|
|
|
|
|
(where <PORTNAME> is the name of the port, e.g.,
|
|
|
|
alpha or sparc).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When allocating memory, use the
|
|
|
|
<productname>Postgres</productname>
|
|
|
|
routines palloc and pfree instead of the
|
|
|
|
corresponding <acronym>C</acronym> library routines
|
|
|
|
malloc and free.
|
|
|
|
The memory allocated by palloc will be freed
|
|
|
|
automatically at the end of each transaction,
|
|
|
|
preventing memory leaks.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Always zero the bytes of your structures using
|
|
|
|
memset or bzero. Several routines (such as the
|
|
|
|
hash access method, hash join and the sort algorithm)
|
|
|
|
compute functions of the raw bits contained in
|
|
|
|
your structure. Even if you initialize all fields
|
|
|
|
of your structure, there may be
|
|
|
|
several bytes of alignment padding (holes in the
|
|
|
|
structure) that may contain garbage values.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Most of the internal <productname>Postgres</productname>
|
|
|
|
types are declared in <filename>postgres.h</filename>,
|
|
|
|
so it's a good
|
|
|
|
idea to always include that file as well. Including
|
|
|
|
postgres.h will also include elog.h and palloc.h for you.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Compiling and loading your object code so that
|
|
|
|
it can be dynamically loaded into
|
|
|
|
<productname>Postgres</productname>
|
|
|
|
always requires special flags.
|
|
|
|
See <xref linkend="dfunc-title" endterm="dfunc-title">
|
|
|
|
for a detailed explanation of how to do it for
|
|
|
|
your particular operating system.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1>
|
|
|
|
<title>Function Overloading</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
More than one function may be defined with the same name, as long as
|
|
|
|
the arguments they take are different. In other words, function names
|
|
|
|
can be <firstterm>overloaded</firstterm>.
|
|
|
|
A function may also have the same name as an attribute. In the case
|
|
|
|
that there is an ambiguity between a function on a complex type and
|
|
|
|
an attribute of the complex type, the attribute will always be used.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Name Space Conflicts</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As of <productname>Postgres</productname> v6.5,
|
|
|
|
<command>CREATE FUNCTION</command> can decouple a C language
|
|
|
|
function name from the name of the entry point. This is now the
|
|
|
|
preferred technique to accomplish function overloading.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect3>
|
|
|
|
<title>Pre-v6.5</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For functions written in C, the SQL name declared in
|
|
|
|
<command>CREATE FUNCTION</command>
|
|
|
|
must be exactly the same as the actual name of the function in the
|
|
|
|
C code (hence it must be a legal C function name).
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There is a subtle implication of this restriction: while the
|
|
|
|
dynamic loading routines in most operating systems are more than
|
|
|
|
happy to allow you to load any number of shared libraries that
|
|
|
|
contain conflicting (identically-named) function names, they may
|
|
|
|
in fact botch the load in interesting ways. For example, if you
|
|
|
|
define a dynamically-loaded function that happens to have the
|
|
|
|
same name as a function built into Postgres, the DEC OSF/1 dynamic
|
|
|
|
loader causes Postgres to call the function within itself rather than
|
|
|
|
allowing Postgres to call your function. Hence, if you want your
|
|
|
|
function to be used on different architectures, we recommend that
|
|
|
|
you do not overload C function names.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There is a clever trick to get around the problem just described.
|
|
|
|
Since there is no problem overloading SQL functions, you can
|
|
|
|
define a set of C functions with different names and then define
|
|
|
|
a set of identically-named SQL function wrappers that take the
|
|
|
|
appropriate argument types and call the matching C function.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Another solution is not to use dynamic loading, but to link your
|
|
|
|
functions into the backend statically and declare them as INTERNAL
|
|
|
|
functions. Then, the functions must all have distinct C names but
|
|
|
|
they can be declared with the same SQL names (as long as their
|
|
|
|
argument types differ, of course). This way avoids the overhead of
|
|
|
|
an SQL wrapper function, at the cost of more effort to prepare a
|
|
|
|
custom backend executable.
|
|
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
1998-12-29 03:24:47 +01:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
|
|
|
mode: sgml
|
|
|
|
sgml-omittag:nil
|
|
|
|
sgml-shorttag:t
|
|
|
|
sgml-minimize-attributes:nil
|
|
|
|
sgml-always-quote-attributes:t
|
|
|
|
sgml-indent-step:1
|
|
|
|
sgml-indent-data:t
|
|
|
|
sgml-parent-document:nil
|
|
|
|
sgml-default-dtd-file:"./reference.ced"
|
|
|
|
sgml-exposed-tags:nil
|
|
|
|
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
|
|
|
|
sgml-local-ecat-files:nil
|
|
|
|
End:
|
|
|
|
-->
|