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


1.15
date	92.06.17.21.30.51;	author mer;	state Exp;
branches;
next	1.14;

1.14
date	91.12.02.01.42.50;	author kemnitz;	state Exp;
branches;
next	1.13;

1.13
date	91.08.23.13.21.59;	author kemnitz;	state Exp;
branches;
next	1.12;

1.12
date	91.02.25.15.07.46;	author mike;	state Exp;
branches;
next	1.11;

1.11
date	90.08.10.14.14.55;	author cimarron;	state Exp;
branches;
next	1.10;

1.10
date	90.08.02.15.53.10;	author choi;	state Exp;
branches;
next	1.9;

1.9
date	90.07.27.14.47.01;	author goh;	state Exp;
branches;
next	1.8;

1.8
date	90.07.27.14.41.55;	author goh;	state Exp;
branches;
next	1.7;

1.7
date	90.07.27.14.33.29;	author goh;	state Exp;
branches;
next	1.6;

1.6
date	90.07.27.14.32.08;	author goh;	state Exp;
branches;
next	1.5;

1.5
date	90.07.27.14.29.16;	author goh;	state Exp;
branches;
next	1.4;

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

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

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

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


desc
@man page for the definePfunction postquel command
@


1.15
log
@bug fixes and rework, still waiting to Adam to give
the final word on what works and what doesn't
@
text
@.\" XXX standard disclaimer belongs here....
.\" $Header: /home/postgres/mer/refs/postquel/RCS/definePfunction,v 1.14 1991/12/02 01:42:50 kemnitz Exp mer $
.SP "DEFINE FUNCTION <POSTQUEL>" 6/16/92
.XA 2 "Define Function <POSTQUEL>"
.uh "NAME"
.lp
define function <POSTQUEL> \*- define a new POSTQUEL function 
.uh "SYNOPSIS"
.sp
\fB****************************************************\fP
\fB******* CHAPTER TO BE REVIEWED BY ADAM GLASS *******\fP
\fB****************************************************\fP
.sp
.lp
.(l
\fBdefine function\fP function_name \fB(\fP
	  \fBlanguage =\fP "postquel"\fB,\fP
	  \fBreturntype =\fP type-r
	\fB)\fP
    \fBarg is (\fP type-1  { \fB,\fP type-n } \fB)\fP
    \fBas\fP
	postquel-query | { list-of-postquel-queries }
.)l
.lp
.uh "DESCRIPTION"
.lp
The user can define a POSTQUEL function which consists
of a single postquel query or a brace-enclosed list
of postquel queries.   With this command, the user can implement a
\fBPOSTQUEL function\fP and register it to POSTGRES.
Subsequently, this user is treated as the owner of the function.
.lp
When defining a POSTQUEL function, the input data types,
.i type-1 ,
.i type-2 ,
\&...,
.i type-n 
must be specified, along with the queries that constitute the function.
The return type of a \*(PQ function is one of the composite types
indicated in the \fBintroduction(commands)\fP section of the manual.
If not specified, then \fIset\fP is the default return type.
.lp
POSTQUEL functions are automatically cachable as long as no POSTQUEL command
in the function in turn contains an uncachable function.
Lastly, functions coded in POSTQUEL are automatically trusted,
since a POSTQUEL function cannot escape from the POSTGRES run-time system.
.lp
POSTQUEL functions are currently available in the same two variations allowed
for C functions.  If a POSTQUEL function is defined whose arguments are all 
\fBbase\fP types, then this is a \fBnormal\fP function.
Normal functions can be used in the query language POSTQUEL to perform
computations.  The parameters to a normal function are specified in the body
of the function using the markers, $1, ..., $n, as noted
in the example function, TP1, defined as follows:
.(l
define function TP1
	(language = "postquel")
	arg is (int4, float8)
	as replace BANK (balance = balance - $2)
		where BANK.accountno = $1
.)l
A user could execute this function to debit account 17 by $100.00 as follows:
.(l
retrieve (x = TP1( 17,100.0))
.)l
.lp
On the other hand, the first argument to a POSTQUEL function can also be a
class name, in which case an \fBinheritable\fP
function is defined.  Inheritable functions can be referenced using either
the column notation or the function notation in POSTQUEL as explained in the
example below.  Moreover, the "cascaded dot" notation available to reference
composite columns is available for inheritable functions.
Lastly, an inheritable function takes a value for each instance in the class,
\fIclassname\fP, which is the first argument to the function.  Hence, in the
body of the function, any references to classname.attribute are automatically
references to the corresponding data element in the current instance of
classname.  Other parameters are denoted positionally as in normal functions.
.lp
To illustrate inheritable functions we use the GROUPS class as follows:
.(l
create GROUPS(name = char16, age = int4)
.)l
An example inheritable function would be: 
.(l
define function composition
	(language = "postquel")
	arg is (GROUPS)
	as retrieve (EMP.all)
		where EMP.age > GROUPS.age
.)l
Composition has a value for each instance of GROUPS which is the query:
.(l
retrieve (EMP.all)
	where EMP.age > current.age
.)l
Hence, the following command would define a new group "elders" whose members
were over 50.
.(l
append to groups (name = "elders", age = 50)
.)l
Both of the following commands obtain the names of all employees who are
"elders".
.(l
retrieve (GROUPS.composition.name)
	where GROUPS.name = "elders"

retrieve (composition(GROUPS).name)
	where GROUPS.name = "elders"
.)l
.lp
Alternately, the user can manually achieve the same definition of the
composition function by the following two commands:
.(l
addattr (composition = EMP) to GROUPS

define rule composition_rule is
  on retrieve to GROUPS.composition 
  do instead
	retrieve (EMP.all) where EMP.age > current.age
.)l
.uh "BUGS"
.lp
There is a bug in the POSTGRES which prevents the "composition_rule" example
from working correctly.
.lp
POSTQUEL functions currently 
can neither accept arguments nor return results of a base type. 
.lp
Inheritable functions are currently restricted to a 
single argument of type classname.
.lp
Inheritable POSTQUEL functions are not currently propagated thru the
inheritance hierarchy.
.lp
Inheritable functions cannot currently use functional notation
and must instead use the column notation.  For example, if a function
foo takes the class EMP as an argument
.(l
retrieve ( EMP.foo.all ) 
.)l
works, but
.(l
retrieve ( foo(EMP).all ) 
.)l
does not.
.lp
POSTQUEL functions cannot currently take a list of queries as the
function body.
.sp
\fB****************************************************\fP
\fB******* CHAPTER TO BE REVIEWED BY ADAM GLASS *******\fP
\fB****************************************************\fP
.sp
In Version \*(PV, POSTQUEL functions are not cachable, no matter what
their composition may be.
.lp
In Version \*(PV, POSTQUEL functions 
exhibit relational-cross-product rather than outer-join semantics.
This means, for instance, that given this schema :
.(l
create emp ( name = char16, salary = int4, dept = char16 )

define function hobbies
	(language = "postquel")
	arg is ( emp )
	as retrieve ( hobbies.all )
		where hobbies.empname = emp.name

append emp ( name = "goh", salary = 1000, dept = "toy" )
append emp ( name = "hong", salary = 1000, dept = "not-toy" )
append emp ( name = "cimarron", salary = 1500, dept = "toy" )
append emp ( name = "ron", salary = 29000, dept = "sys-admin" )

create hobbies ( activity = char16, empname = char16 )

append hobbies ( activity = "kayaking", empname = "goh" )
append hobbies ( activity = "basketball", empname = "hong" )
append hobbies ( activity = "basketball", empname = "ron" )
.)l
.sp
the query
.(l
retrieve ( emp.hobbies.activity , emp.name ) 
.)l
returns
.(l
	activity    	name
	--------------------------------------
	kayaking	goh
	basketball	hong
	basketball	ron
	--------------------------------------
.)l
rather than
.(l
	activity   	name
	--------------------------------------
	kayaking	goh
	basketball	hong
	basketball	ron
	NULL    	cimarron
	--------------------------------------
.)l
@


1.14
log
@fixed problem.
@
text
@d2 4
a5 5
.\" $Header: RCS/definePfunction,v 1.13 91/08/23 13:21:59 kemnitz Exp Locker: kemnitz $
.SP "DEFINE FUNCTION <POSTQUEL>" 6/14/90
.SS COMMANDS
.XA 2 "Define FUNCTION <POSTQUEL>"
.uh NAME
d8 16
a23 16
.uh SYNOPSIS
.lp
.b "define function"
function_name
.b "("
language = "postquel",
.b ,
returntype = <typename>
.b ")"
.b arg 
.b as
.br
postquel-query |
.b {
list-of-postquel-queries 
.b }
d25 1
a25 1
.uh DESCRIPTION
d29 2
a30 4
of postquel queries.
Via this command, the implementor of a
.b "POSTQUEL function"
can register it to POSTGRES.
d33 1
a33 2
When defining a POSTQUEL function,
the input data types,
d38 1
a38 3
must be specified,
along with the
queries that constitute the function.
d40 5
a44 10
indicated in the 
.b introduction 
(commands) section of the manual.  If not specified, then 
.i set 
is the 
default return type.
.lp
POSTQUEL functions are automatically cachable as long
as no POSTQUEL command in the function in turn contains an uncachable
function.
d46 1
a46 2
since a POSTQUEL function cannot escape from the POSTGRES 
run-time system.
d48 6
a53 13
POSTQUEL functions are currently available in the same
two variations allowed for C functions.  If
a POSTQUEL function is defined whose arguments 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.
The parameters to a normal function are
specified in the body of the function using
the markers, $1, ..., $n, as noted
d56 5
a60 3
define postquel function TP1(int4, float8) is
	replace BANK (balance = balance - $2)
	where BANK.accountno = $1
d62 1
a62 2
A user could execute this function to debit account 17 by $100.00
as follows:
d67 6
a72 12
On the other hand, the first argument to
a POSTQUEL function can also be a class name, in which case
an 
.b inheritable 
function is defined.
Inheritable functions can be referenced
using either the column notation or the function
notation in POSTQUEL as explained in the example below. 
Moreover, the 
"cascaded dot"
notation available to reference composite columns is 
available for inheritable functions.
d74 4
a77 6
.i classname,
which is the first argument to the function.  Hence, in the
body of the function, any references to classname.attribute  
are automatically references to the corresponding data
element in the current instance of classname.  Other parameters
are denoted positionally as in normal functions.
d79 1
a79 2
To illustrate inheritable functions we use the
GROUPS class as follows:
d85 5
a89 3
define postquel function composition (GROUPS), 
retrieve (EMP.all)
where EMP.age > GROUPS.age
d94 1
a94 1
where EMP.age > current.age
d96 2
a97 4
Hence, the following 
command would define a new group 
"elders" 
whose members were over 50.
d101 2
a102 2
Both of the following commands obtain the names of all
employees who are "elders". 
d105 1
a105 1
where GROUPS.name = "elders"
d108 1
a108 1
where GROUPS.name = "elders"
d111 2
a112 3
Alternately, the user can manually achieve the same
definition of the composition function 
by the following two commands:
d116 4
a119 3
define rule example
on retrieve to GROUPS.composition 
then do instead retrieve (EMP.all) where EMP.age > current.age
d121 4
a124 1
.uh BUGS 
d149 7
a155 3
.lp
In Version 3.0, POSTQUEL functions are not cachable, no matter what
their composition may be.  
d157 1
a157 1
In Version 3.0, POSTQUEL functions 
d163 5
a167 2
define postquel function hobbies ( emp ) returns hobbies is
retrieve ( hobbies.all ) where hobbies.empname = emp.name
@


1.13
log
@2.1 -> 3.0
@
text
@d2 2
a3 2
.\" $Header: RCS/definePfunction,v 1.12 91/02/25 15:07:46 mike Exp Locker: kemnitz $
.SP "DEFINE POSTQUEL FUNCTION" 6/14/90
d5 1
a5 1
.XA 2 "Define POSTQUEL FUNCTION"
d8 1
a8 1
define postquel function \*- define a new POSTQUEL function 
d11 1
a11 1
.b "define postquel function"
d14 1
a14 1
type\-1 {
d16 1
a16 1
type\-n }
d18 2
a19 3
.b returns
class-name
.b is
d25 1
a25 1

@


1.12
log
@objectified
@
text
@d2 1
a2 1
.\" $Header: RCS/definePfunction,v 1.11 90/08/10 14:14:55 cimarron Exp Locker: mike $
d175 1
a175 1
In Version 2.1, POSTQUEL functions are not cachable, no matter what
d178 1
a178 1
In Version 2.1, POSTQUEL functions 
@


1.11
log
@corrected picture in bugs section.
@
text
@d2 1
a2 1
.\" $Header: RCS/definePfunction,v 1.10 90/08/02 15:53:10 choi Exp Locker: cimarron $
d19 1
a19 1
relation-name
d50 1
a50 1
.i RELATION 
d87 1
a87 1
a POSTQUEL function can also be a tuple, in which case
d98 2
a99 2
Lastly, an inheritable function takes a value for each row in the relation,
.i relname,
d101 1
a101 1
body of the function, any references to relname.attribute  
d103 1
a103 1
element in the current row of relname.  Other parameters
d107 1
a107 1
GROUPS relation as follows:
d117 1
a117 1
Composition has a value for each row of GROUPS which is the query:
d143 1
a143 1
addattr (composition = RELATION) to GROUPS
d152 1
a152 2
cannot return a result of a base type, 
nor can they return results of a composite type other than tuples.
a153 3
POSTQUEL functions cannot currently take arguments of base types
nor can they take argumnents of composite types other than tuples.
.lp
d155 1
a155 1
single argument of type tuple.
d157 2
a158 4
POSTQUEL functions cannot currently be propagate thru the
inheritance hierarchy even if they are defined as functions
which take a relation as its first argument.  However, the return values
can still be accessed via the cascaded dot notation.
d160 1
a160 15
POSTQUEL functions do not currently take base types as an argument.
.lp
POSTQUEL functions currently only accept a single relation type as
an argument.  
This means that 
.(l
define postquel function foo ( EMP ) is ...
.)l
works, but 
.(l
define postquel function foo ( EMP, DEPT , ... ) is ...
.)l
does not.
.lp
``Inheritable'' functions cannot currently use functional notation
d162 1
a162 1
foo takes the relation EMP as an argument
d175 1
a175 1
In Version 2.0, POSTQUEL functions are not cachable, no matter what
d178 2
a179 2
In Version 2.0, POSTQUEL functions which return results of type
tuple exhibit relational-cross-product rather than outer-join semantics.
@


1.10
log
@changed "define POSTQUEL function" to "define postquel function"
@
text
@d2 1
a2 1
.\" $Header: RCS/definePfunction,v 1.9 90/07/27 14:47:01 goh Exp Locker: choi $
d218 1
d225 1
d227 3
a229 5
	|   activity	|     name	|
	|------------------|------------------|
	|   kayaking 	|     goh		|
	|   basketball	|     hong		|
	|   basketball	|     ron		|
d234 1
d236 4
a239 6
	|   activity	|     name	|
	|------------------|------------------|
	|   kayaking 	|     goh		|
	|   basketball	|     hong		|
	|   basketball	|     ron		|
	|   NULL	|     cimarron  	|
@


1.9
log
@sigh, I think ``tbl'' would be better for the query result,
but still, this looks more ``authentic'' in the sense that it
more closely reflects what the terminal monitor would
return.
@
text
@d2 1
a2 1
.\" $Header: RCS/definePfunction,v 1.4 90/07/26 18:23:46 kemnitz Exp Locker: goh $
d8 1
a8 1
define POSTQUEL function \*- define a new POSTQUEL function 
d11 1
a11 1
.b "define POSTQUEL function"
d76 1
a76 1
define POSTQUEL function TP1(int4, float8) is
d113 1
a113 1
define POSTQUEL function composition (GROUPS), 
d172 1
a172 1
define POSTQUEL function foo ( EMP ) is ...
d176 1
a176 1
define POSTQUEL function foo ( EMP, DEPT , ... ) is ...
@


1.8
log
@added bug-notice about x-product vs OJ semantics
@
text
@d224 1
a224 1
	---------------------------------
d226 5
a230 5
	|---------------|---------------|
	|   kayaking 	|     goh	|
	|   basketball	|     hong	|
	|   basketball	|     ron	|
	---------------------------------
d234 1
a234 1
	---------------------------------
d236 6
a241 6
	|---------------|---------------|
	|   kayaking 	|     goh	|
	|   basketball	|     hong	|
	|   basketball	|     ron	|
	|   NULL	|     cimarron  |
	---------------------------------
@


1.7
log
@added bug notice about not being cachable
@
text
@d195 48
a242 1
In Version 2, POSTQUEL functions are not cachable, no matter what
@


1.6
log
@minor adjustment to clarify a bug notice
@
text
@d195 1
@


1.5
log
@bug-notice updates and syntax update
@
text
@d161 4
a164 1
POSTQUEL functions cannot currently be inherited.
@


1.4
log
@Changed define syntax.
@
text
@d2 1
a2 1
.\" $Header: RCS/definePfunction,v 1.3 90/07/20 09:17:43 claire Exp Locker: kemnitz $
a13 4
file = "filename"
.b ")"
.b arg 
.b "("
d18 9
d29 3
d44 2
a45 3
along with a
.i filename
which indicates the location of the POSTQUEL code for the function.
d76 3
a78 2
define POSTQUEL function TP1(int4, float8),
file = /usr2/TP1
a79 5
The contents of the file /usr2/TP1 would be:
.(l
replace BANK (balance = balance - $2)
where BANK.accountno = $1
.)l
d91 1
a91 1
Iheritable functions can be referenced
a113 4
file = /usr2/composition
.)l
The contents of /usr2/composition would be:
.(l
d143 1
a143 1
add to GROUPS (composition = RELATION)
d153 1
a153 1
nor can they take arguments of composite types other than tuples.
d155 37
a191 1
Inheritable functions are currently restricted to a single argument of type tuple.
@


1.3
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" $Header: RCS/definePfunction,v 1.2 90/07/19 18:55:10 claire Exp Locker: claire $
d14 4
a21 4
.b "[ returns
type\-r]
.b ", file ="
filename
d43 1
a43 1
.i relation 
d144 1
a144 1
add to GROUPS (composition = relation)
@


1.2
log
@*** empty log message ***
@
text
@d2 3
a4 5
.\" $Header: RCS/definePfunction,v 1.1 90/07/18 16:21:59 mao Exp Locker: claire $
.SP "DEFINE POSTQUEL FUNCTION" COMMANDS 6/14/90
lst 3 words
.ce 1
/fb<rest>/fr
@


1.1
log
@Initial revision
@
text
@d2 1
a2 1
.\" $Header: definetype.composite,v 1.10 89/03/23 11:49:32 wensel Exp $
d4 3
d97 2
a98 1
Lastly, an inheritable function takes a value for each row in the relation, relname,
@
