head	1.16;
access;
symbols;
locks; strict;
comment	@# @;


1.16
date	92.06.17.22.11.04;	author ptong;	state Exp;
branches;
next	1.15;

1.15
date	92.06.17.05.36.12;	author ong;	state Exp;
branches;
next	1.14;

1.14
date	92.06.17.04.00.56;	author ong;	state Exp;
branches;
next	1.13;

1.13
date	92.06.17.02.25.53;	author ong;	state Exp;
branches;
next	1.12;

1.12
date	91.12.02.01.46.32;	author kemnitz;	state Exp;
branches;
next	1.11;

1.11
date	91.12.02.01.43.54;	author kemnitz;	state Exp;
branches;
next	1.10;

1.10
date	91.12.02.01.33.37;	author kemnitz;	state Exp;
branches;
next	1.9;

1.9
date	91.08.16.18.00.38;	author sp;	state Exp;
branches;
next	1.8;

1.8
date	91.08.13.21.43.00;	author kemnitz;	state Exp;
branches;
next	1.7;

1.7
date	91.02.25.10.03.11;	author mike;	state Exp;
branches;
next	1.6;

1.6
date	90.08.02.15.47.57;	author choi;	state Exp;
branches;
next	1.5;

1.5
date	90.07.27.12.08.12;	author kemnitz;	state Exp;
branches;
next	1.4;

1.4
date	90.07.21.17.57.54;	author kemnitz;	state Exp;
branches;
next	1.3;

1.3
date	90.07.20.09.53.30;	author claire;	state Exp;
branches;
next	1.2;

1.2
date	90.07.19.19.01.17;	author claire;	state Exp;
branches;
next	1.1;

1.1
date	90.07.18.16.21.58;	author mao;	state Exp;
branches;
next	;


desc
@man page for the defineCfunction postquel command
@


1.16
log
@get rid of section start, it shouldn't be here.
@
text
@.\" XXX standard disclaimer belongs here....
.\" $Header: /home/postgres/mer/refs/postquel/RCS/defineCfunction,v 1.15 1992/06/17 05:36:12 ong Exp ong $
.SP "DEFINE FUNCTION <C>" COMMANDS 6/16/92
.XA 2 "Define Function <C>"
.uh "NAME"
.lp
define function <C> \*- define a new function written in C
.uh "SYNOPSIS"
.lp
.(l
\fBdefine function\fP function_name \fB(\fP
	  \fBlanguage =\fP "c"\fB,\fP
	  \fBreturntype =\fP type-r
	  [ \fB, iscachable\fP ]
	\fB)\fP
    \fBarg is (\fP type-1  { \fB,\fP type-n } \fB)\fP
    \fBas\fP "/full/path/filename.o"
.)l
.uh "DESCRIPTION"
.lp
With this command, a POSTGRES user can register a C function with 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 filename ("/full/path/filename.o")
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 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 function overpaid
	(language = "c", returntype = bool, iscachable)
	arg is (float8, int4)
	as "/usr/postgres/src/adt/overpaid.o"
.)l
The C file "overpaid.c" might look something like:
.(l
#include <utils/builtin.h>

bool overpaid(salary, age)
	float8 *salary;
	int4    age;
{
	if (*salary > 200000.00)
		return(TRUE);
	if ((age < 30) && (*salary > 100000.00))
		return(TRUE);
	return(FALSE)
}
.)l
The overpaid function can 
be used in a query, e.g:
.(l
retrieve (EMP.name) where overpaid(EMP.salary, EMP.age)
.)l
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 function overpaid_2
	(language = "c", returntype = bool, iscachable)
	arg is (EMP)
	as "/usr/postgres/src/adt/overpaid_2.o"
.)l
The following queries are now accepted:
.(l
retrieve (EMP.name) where overpaid_2(EMP) 
.)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.  The C file "overpaid_2.c" might look
something like:
.(l
#include <utils/builtin.h>

bool overpaid_2()
{
	float8 *salary;
	int4    age;

	salary = (float8 *)GetAttribute("salary");
	age    = (int4)    GetAttribute("age");
	if (*salary > 200000.00)
		return(TRUE);
	if ((age < 30) && (*salary > 100000.00))
		return(TRUE);
	return(FALSE)
}
.)l
.lp
Alternately, the following two commands make use of the first C function,
overpaid(), to do essentially the same thing.
.(l
addattr (overpaid_2 = bool) to EMP

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

.uh "CREATING C FUNCTIONS FOR POSTGRES"
.lp
The C equivalents of builtin POSTGRES types are accessible in a C file
if $POSTGRESHOME/src/lib/H/utils/builtin.h is included as a header file.
This can be achieved by having
.(l
#include <utils/builtin.h>
.)l
at the top of the C source file and by compiling all C files with the
following include options:
.(l
 -I$POSTGRESHOME/src/lib/H
 -I$POSTGRESHOME/src/port/$PORTNAME
 -I$POSTGRESHOME/O/lib/H
.)l
before any ".c" programs in the "cc" command line:
.(l
cc -I$POSTGRESHOME/src/lib/H \\
	-I$POSTGRESHOME/src/port/$PORTNAME \\
	-I$POSTGRESHOME/O/lib/H \\
	-c progname.c
.)l
The directory $POSTGRESHOME/O/lib/H contains "tags.h", generated in the
build process.  The directory $POSTGRESHOME/src/port/$PORTNAME contains
"machine.h".  Typical values for PORTNAME are sunos4 and ultrix4.
.lp
The convention for passing arguments to and from the user's C functions is
to use pass-by-value for data types that are 32 bits (4 bytes) or
smaller, and pass-by-reference for data types that require more than 32 bits.
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 $POSTGRESHOME/src/lib/H) that the equivalent
C type is defined.  However, if you include "utils/builtin.h", these
files will automatically be included.
.uh "Equivalent C Types for Builtin POSTGRES Types"
.lp
.TS
center;
c c c
l l l.
\fIBuiltin Type\fP	\fIC Type\fP	\fIDefined In\fP
_
abstime	AbsoluteTime	utils/nabstime.h
bool	bool	tmp/c.h
box	(BOX *)	utils/geo-decls.h
bytea	(bytea *)	tmp/postgres.h
char	char	N/A
char16	Char16 or (char16 *)	tmp/postgres.h
cid	CID	tmp/postgres.h
int2	int2	tmp/postgres.h
int28	(int28 *)	tmp/postgres.h
int4	int4	tmp/postgres.h
float4	float32 or (float4 *)	tmp/c.h or tmp/postgres.h
float8	float64 or (float8 *)	tmp/c.h or tmp/postgres.h
lseg	(LSEG *)	tmp/geo-decls.h
oid	oid	tmp/postgres.h
oid8	(oid8 *)	tmp/postgres.h
path	(PATH *)	utils/geo-decls.h
point	(POINT *)	utils/geo-decls.h
regproc	regproc or REGPROC	tmp/postgres.h
reltime	RELTIME	tmp/postgres.h
text	(text *)	tmp/postgres.h
tid	ItemPointer	storage/itemptr.h
tinterval	TimeInterval	tmp/nabstime.h
uint2	uint16	tmp/c.h
uint4	uint32	tmp/c.h
xid	(XID *)	tmp/postgres.h
.TE
.lp

.uh "SEE ALSO"
.lp
information(unix), load(commands), remove function(commands).
.uh "RESTRICTIONS"
.lp
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 function.
.uh "BUGS"
.lp
Untrusted operation is not yet implemented.
.lp
Precomputing and caching of function results are not yet implemented.
.lp
C functions cannot return composite types.
.lp
The notation X.f is not supported for an inheritable C function, f.
.lp
Currently, Inheritable C functions are restricted to having a single tuple
argument in the current version of POSTGRES, although they may have up to 8
non-tuple arguments.
.lp
There is a bug in the POSTGRES which prevents the "overpaid_rule" example
from working correctly.
.lp
The dynamic loader for DECstation Ultrix has exceedingly bad performance.
.lp
On Ultrix, all .o files that POSTGRES is expected to load dynamically must
be compiled under \f2cc\fP with the "-G 0" option turned on.
@


1.15
log
@Fixed up.
@
text
@d2 1
a2 1
.\" $Header: /home/postgres/mer/refs/postquel/RCS/defineCfunction,v 1.14 1992/06/17 04:00:56 ong Exp ong $
a3 1
.SS COMMANDS
@


1.14
log
@Fixed up.
@
text
@d2 3
a4 2
.\" $Header: /users/ong/ref/postquel/RCS/defineCfunction,v 1.13 1992/06/17 02:25:53 ong Exp ong $
.SP "DEFINE FUNCTION <C>" COMMANDS 6/14/90
a11 1
************* CHECK THE BOLDIFICATION *****************
d13 2
a14 2
	  \fBlanguage =\fP "c",
	  \fBreturntype =\fP builtin-type-r
d17 1
a17 1
    \fBarg is (\fP builtin-type\-1  { \fB,\fP builtin-type\-n } \fB)\fP
d26 2
a27 2
.i builtin-type-1 ,
.i builtin-type-2 ,
d29 1
a29 1
.i builtin-type-n ,
d31 1
a31 1
.i builtin-type-r
d275 2
a276 2
There is a bug in the POSTGRES which prevents the "overpaid_rule" example from
working correctly.
@


1.13
log
@Fixed up for 4.0.
@
text
@d2 1
a2 1
.\" $Header: /users/ong/ref/postquel/RCS/defineCfunction,v 1.12 1991/12/02 01:46:32 kemnitz Exp ong $
d12 7
a18 7
\f2define function\fP function_name \f2(\fP
	  \f2language =\fP "c",
	  \f2returntype =\fP builtin-type-r
	  [ \f2, iscachable\fP ]
	\f2)\fP
    \f2arg is (\fP builtin-type\-1  { \f2,\fP builtin-type\-n } \f2)\fP
    \f2as\fP "/full/path/filename.o"
d185 1
a185 1
The C equivalents of built-in POSTGRES types are accessible in a C file
d194 3
a196 3
- -I$POSTGRESHOME/src/lib/H
- -I$POSTGRESHOME/****MORE_STUFF_HERE****
- -I$POSTGRESHOME/****EVEN_MORE_STUFF_HERE****
d201 2
a202 2
	-I$POSTGRESHOME/****MORE_STUFF_HERE**** \\
	-I$POSTGRESHOME/****EVEN_MORE_STUFF_HERE**** \\
d205 4
d217 1
a217 1
.uh "Equivalent C Types for Built-In POSTGRES Types"
d265 1
a265 1
Precomputing and caching of function results is not yet implemented.
d269 1
a269 1
The notation X.f is not supported for an inheritable function, f.
d271 3
a273 2
Inheritable C functions are restricted to have a single tuple argument
in the current version of POSTGRES, although they may have non-tuple arguments.
@


1.12
log
@got rid of tutorial reference.
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.11 91/12/02 01:43:54 kemnitz Exp Locker: kemnitz $
d5 1
a5 1
.uh NAME
d8 1
a8 1
.uh SYNOPSIS
d10 13
a22 23
.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.
d25 3
a27 4
When defining the function,
the input data types,
.i type-1 ,
.i type-2 ,
d29 1
a29 1
.i type-n ,
d31 1
a31 1
.i type-r
d33 1
a33 2
along with a
.i filename
d36 1
a36 1
before it is used in a define c function command.)
d96 19
a114 3
define c function overpaid
(file = "/usr/postgres/src/adt/overpaid.o", returntype = bool, iscachable) 
arg (float8, int4)
d119 1
a119 1
retrieve (EMP.name) where overpaid (EMP.salary, EMP.age) 
a120 1
.lp
d139 1
a139 2
Consider an inheritable function 
overpaid-2, defined as follows:
d141 4
a144 3
define c function overpaid_2
(file = "/usr/postgres/src/adt/overpaid_2.o", returntype = bool, iscachable)
arg (EMP)
d149 27
d177 5
a181 1
retrieve (EMP.name) where EMP.overpaid_2
d183 14
a196 1
retrieve (EMP.name) where EMP.overpaid_2()
d198 6
a203 13
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))
d205 43
d251 3
a253 4
information(unix),
load(commands),
remove function(commands).
.uh RESTRICTIONS
d256 2
a257 2
define c function.
.uh BUGS
d259 1
a259 2
Untrusted operation
is not implemented in Version 3.0.
d261 1
a261 2
Precomputing and caching of function results
is not implemented in Version 3.0.
d268 4
a271 1
in Version 3, although they may have non-tuple arguments.
d274 3
@


1.11
log
@new syntax.
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.10 91/12/02 01:33:37 kemnitz Exp Locker: kemnitz $
d152 2
a153 2
record must be extracted using a function call getattr(name) as
explained in the companion POSTGRES tutorial.
@


1.10
log
@changed around to handle new syntax
@
text
@d2 3
a4 3
.\" $Header: RCS/defineCfunction,v 1.9 91/08/16 18:00:38 sp Exp Locker: kemnitz $
.SP "DEFINE C FUNCTION" COMMANDS 6/14/90
.XA 2 "Define C Function"
d7 1
a7 1
define function (C) \*- define a new C function 
@


1.9
log
@PRecomputing does not work...
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.8 91/08/13 21:43:00 kemnitz Exp Locker: sp $
d7 1
a7 1
define c function \*- define a new C function 
d10 1
a10 1
.b "define c function"
d13 2
a14 1
file = "filename"
a170 1
Tutorial: Creating and Using a C function.
@


1.8
log
@updated some numbers from 2.1 to 3 - the dynamic loader works now.
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.7 91/02/25 10:03:11 mike Exp Locker: kemnitz $
d21 1
d178 4
a181 1
is not implemented in Version 3.
@


1.7
log
@objectified
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.6 90/08/02 15:47:57 choi Exp Locker: mike $
d167 1
d177 1
a177 1
is not implemented in Version 2.1.
d184 1
a184 1
in Version 2.1.
d186 1
a186 3
There are numerous bugs in the 2.1 dynamic loader.  If you have problems with
loading a C function, please consult the release notes.
Also, the dynamic loader for Ultrix has exceedingly bad performance.
@


1.6
log
@changed "define C function" to "define c function" 
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.5 90/07/27 12:08:12 kemnitz Exp Locker: choi $
a88 3
If a C function is to operate on the current tuple in addition to attribute
arguments, the first type in 
.lp
d118 6
a123 2
.b RELATION
, in which case
d127 5
a131 5
An inheritable function essentially specifies a new column for
the associated table, whose data type is the return
type of the function and whose column name is the
name of the function.  Column functions can be referenced
using either the column notation or the function
d139 1
a139 1
arg (RELATION)
d176 1
a176 1
is not implemented in Version 2.
d178 1
a178 2
C functions cannot return composite types, accept composite types other than
RELATION as an argument, or contain POSTQUEL queries.
d183 1
a183 1
in Version 2.
d185 1
a185 1
There are numerous bugs in the 2.0 dynamic loader.  If you have problems with
d187 1
@


1.5
log
@Added disclaimer about the dynamic loader.
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.4 90/07/21 17:57:54 kemnitz Exp Locker: kemnitz $
d7 1
a7 1
define C function \*- define a new C function 
d10 1
a10 1
.b "define C function"
d46 1
a46 1
before it is used in a define C function command.)
d109 1
a109 1
define C function overpaid
d136 1
a136 1
define C function overpaid_2
d171 1
a171 1
define C function.
@


1.4
log
@Changed syntax so it agrees with the code.
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.3 90/07/20 09:53:30 claire Exp Locker: kemnitz $
d184 3
@


1.3
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.2 90/07/19 19:01:17 claire Exp Locker: claire $
d13 9
a25 7
.b " returns
type\-r
.b ", file ="
filename
[
.b ", iscachable"
] 
d44 3
a46 1
which indicates the location of the object code in .o format for the function.
d89 3
d109 3
a111 3
define C function overpaid (float8, int4) returns boolean, 
file = "/usr/postgres/src/adt/overpaid.o",
iscachable
d120 3
a122 1
a function can also be of type tuple, in which case
d136 3
a138 3
define C function overpaid-2 (EMP) returns = boolean,
file = "/usr/postgres/src/adt/overpaid-2.o",
iscachable
d142 1
a142 1
retrieve (EMP.name) where overpaid-2(EMP) 
d144 1
a144 1
retrieve (EMP.name) where EMP.overpaid-2
d146 1
a146 1
retrieve (EMP.name) where EMP.overpaid-2()
d148 1
a148 1
In this case, in the body of the overpaid-2 function, the fields in the EMP
d156 1
a156 1
add to EMP (overpaid = boolean)
d160 1
a160 1
then do instead retrieve (overpaid =  overpaid-2(current.salary, current.age))
d167 5
d177 2
a178 2
C functions cannot return composite types, accept composite types other than tuple as an
argument, or contain POSTQUEL queries.
d182 2
a183 1
Inheritable C functions are restricted to have a single argument in Version 2.
@


1.2
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" $Header: RCS/defineCfunction,v 1.1 90/07/18 16:21:58 mao Exp Locker: claire $
d96 2
a97 1
.b "define operator"
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Header: definefunction,v 1.4 88/06/27 13:02:24 wensel Exp $
d27 1
a27 1
.b "C function"
d85 1
a85 1
.b C functions
d95 3
a97 3
POSTQUEL operators using the 
define operator (postquel)
command.  
@