.\" XXX standard disclaimer belongs here....
.\" $Header: RCS/defineCfunction,v 1.12 91/12/02 01:46:32 kemnitz Exp $
.SP "DEFINE FUNCTION <C>" COMMANDS 6/14/90
.XA 2 "Define Function <C>"
.uh NAME
.lp
define function <C> \*- define a new function written in C
.uh SYNOPSIS
.lp
.b "define function"
function_name
.b "("
file = "filename",
language = "c",
.b ,
returntype = <typename>
[
.b ", iscachable"
]
.b ")"
.b arg 
.b is
.b "("
type\-1 {
.b ,
type\-n }
.b ")"
.uh DESCRIPTION
.lp
Via this command, the implementor of a 
C function
can register it to POSTGRES.
Subsequently, this user is treated as the owner of the function.
.lp
When defining the function,
the input data types,
.i type-1 ,
.i type-2 ,
\&...,
.i type-n ,
and the return data type,
.i type-r
must be specified,
along with a
.i filename
which indicates the FULL PATH to the object code in .o format for the function.
(POSTGRES will not compile a function automatically - it must be compiled
before it is used in a define c function command.)
This code will be dynamically
loaded when necessary for execution.
Repeated execution of a function will cause
negligible additional overhead,
as the function will remain in a main memory cache.
.lp
The presense of the
.i iscachable
flag indicates that the function can be precomputed.  Under a
variety of circumstances, POSTGRES 
.b caches
the result of a function for improved performance.  
Most functions can be evaluated earlier than requested;
however,
some functions (such as 
.q time-of-day )
cannot.
Thus, the
.i iscachable
flag is used to indicate which option is appropriate for the
function being defined.
If the flag is not specified, POSTGRES defaults to never
precomputing the function.
.lp
Functions can be either called in the POSTGRES address space
or a process will be forked for the function
and a remote procedure call executed.
The choice of 
.b trusted
or 
.b untrusted 
operation is controlled
by the
DBA
of the data base in question who can set the
.q trusted
flag in the appropriate system catalog.
.lp
When a function is executed,
POSTGRES automatically performs type-checking of the parameters
and signals an error if there is a type mismatch.
.lp
C functions
are currently available in two variations.  If
a function is defined whose arguments and return types are
all 
.b base
types, then this is a
.b normal
function.  
Normal functions can be used in the query language POSTQUEL
to perform computations and also can be associated with
POSTQUEL operators using 
.b define
.b operator
(commands).
.lp
For example, The following command defines a function, overpaid.
.(l
define c function overpaid
(file = "/usr/postgres/src/adt/overpaid.o", returntype = bool, iscachable) 
arg (float8, int4)
.)l
The overpaid function can 
be used in a query, e.g:
.(l
retrieve (EMP.name) where overpaid (EMP.salary, EMP.age) 
.)l
.lp
On the other hand, the first argument to
a function can also be of type
.b set
or
of type
.b classname,
representing one or more instances of a particular class.
In this case
an 
.b inheritable 
function is defined.
An inheritable function essentially specifies a new attribute for
the associated class, whose data type is the return
type of the function and whose attribute name is the
name of the function.  Inheritable functions can be referenced
using either the attribute notation or the function
notation in POSTQUEL as explained in the following example. 
.lp
Consider an inheritable function 
overpaid-2, defined as follows:
.(l
define c function overpaid_2
(file = "/usr/postgres/src/adt/overpaid_2.o", returntype = bool, iscachable)
arg (EMP)
.)l
The following queries are now accepted:
.(l
retrieve (EMP.name) where overpaid_2(EMP) 

retrieve (EMP.name) where EMP.overpaid_2

retrieve (EMP.name) where EMP.overpaid_2()
.)l
In this case, in the body of the overpaid_2 function, the fields in the EMP
record must be extracted using a function call GetAttribute(name) as
explained in the \*(PP manual.
.pp
Alternately,
the following two commands do 
essentially the same thing.
.(l
addattr (overpaid = bool) to EMP

define rule example
on retrieve to EMP.overpaid
then do instead retrieve (overpaid =  overpaid_2(current.salary, current.age))
.)l

.uh "SEE ALSO"
.lp
information(unix),
load(commands),
remove function(commands).
.uh RESTRICTIONS
The name of the C function must be a legal C function name, and the name of
the function in C code must be exactly the same as the name used in
define c function.
.uh BUGS
.lp
Untrusted operation
is not implemented in Version 3.0.
.lp
Precomputing and caching of function results
is not implemented in Version 3.0.
.lp
C functions cannot return composite types.
.lp
The notation X.f is not supported for an inheritable function, f.
.lp
Inheritable C functions are restricted to have a single tuple argument
in Version 3, although they may have non-tuple arguments.
.lp
The dynamic loader for DECstation Ultrix has exceedingly bad performance.
