*** ./doc/src/sgml/ref/create_function.sgml.orig Thu Sep 16 11:53:11 1999
--- ./doc/src/sgml/ref/create_function.sgml Thu Sep 16 12:10:41 1999
***************
*** 25,32 ****
CREATE FUNCTION name ( [ ftype [, ...] ] )
RETURNS rtype
! AS definition
LANGUAGE 'langname'
--- 25,38 ----
CREATE FUNCTION name ( [ ftype [, ...] ] )
RETURNS rtype
! AS definition
LANGUAGE 'langname'
+
+
+ CREATE FUNCTION name ( [ ftype [, ...] ] )
+ RETURNS rtype
+ AS obj_file , link_symbol
+ LANGUAGE 'c'
***************
*** 84,89 ****
--- 90,111 ----
+ obj_file , link_symbol
+
+
+ This form of the AS clause is used for
+ dynamically-linked, C language functions when the function name in
+ the C language source code is not the same as the name of the SQL
+ function. The string obj_file is the name of the file
+ containing the dynamically loadable object, and link_symbol, is the object's link
+ symbol which is the same as the name of the function in the C
+ language source code.
+
+
+
+
langname
***************
*** 165,174 ****
Postgres allows function "overloading";
that is, the same name can be used for several different functions
! so long as they have distinct argument types. This facility must be
! used with caution for internal
! and C-language functions, however.
!
Two internal
--- 187,196 ----
Postgres allows function "overloading";
that is, the same name can be used for several different functions
! so long as they have distinct argument types. This facility must
! be used with caution for internal and
! C-language functions, however.
!
Two internal
***************
*** 181,198 ****
! For dynamically-loaded C functions, the SQL name of the function must
! be the same as the C function name, because the AS clause is used to
! give the path name of the object file containing the C code. In this
! situation it is best not to try to overload SQL function names. It
! might work to load a C function that has the same C name as an internal
! function or another dynamically-loaded function --- or it might not.
! On some platforms the dynamic loader may botch the load in interesting
! ways if there is a conflict of C function names. So, even if it works
! for you today, you might regret overloading names later when you try
! to run the code somewhere else.
A C function cannot return a set of values.
--- 203,217 ----
! When overloading SQL functions with C-language functions, give
! each C-language instance of the function a distinct name, and use
! the alternative form of the AS clause in the
! CREATE FUNCTION syntax to ensure that
! overloaded SQL functions names are resolved to the correct
! dynamically linked objects.
+
A C function cannot return a set of values.
***************
*** 227,233 ****
is correct. It is intended for use in a CHECK contraint.
-
CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool
AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';
--- 246,251 ----
***************
*** 238,245 ****
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);
-
--- 256,296 ----
eancode char(6) CHECK (eancode ~ '[0-9]{6}'),
CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))
);
+
+
+
+ This example creates a function that does type conversion between the
+ user defined type complex, and the internal type point. The
+ function is implemented by a dynamically loaded object that was
+ compiled from C source. For Postgres to
+ find a type conversion function automatically, the sql function has
+ to have the same name as the return type, and overloading is
+ unavoidable. The function name is overloaded by using the second
+ form of the AS clause in the SQL definition
+
+
+ CREATE FUNCTION point(complex) RETURNS point
+ AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
+ LANGUAGE 'c';
+
+
+ The C decalaration of the function is:
+
+
+ Point * complex_to_point (Complex *z)
+ {
+ Point *p;
+
+ p = (Point *) palloc(sizeof(Point));
+ p->x = z->x;
+ p->y = z->y;
+
+ return p;
+ }
+
+
+
***************
*** 283,290 ****
SQL/PSM CREATE FUNCTION has the following syntax:
CREATE FUNCTION name
! ( [ [ IN | OUT | INOUT ] etereable>eable> type [, ...] ] )
RETURNS rtype
LANGUAGE 'langname'
ESPECIFIC routine
--- 334,340 ----
SQL/PSM CREATE FUNCTION has the following syntax:
CREATE FUNCTION name
! ( [ [ IN | OUT | INOUT ] type [, ...] ] )
RETURNS rtype
LANGUAGE 'langname'
ESPECIFIC routine
*** ./doc/src/sgml/xfunc.sgml.orig Thu Sep 16 11:52:31 1999
--- ./doc/src/sgml/xfunc.sgml Thu Sep 16 12:23:12 1999
***************
*** 357,381 ****
Compiled (C) Language Functions
! 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.
! The string which specifies the object file (the string in the AS clause)
! should be the full path
! of the object code file for the function, bracketed by quotation
! marks. (Postgres will not compile a
! function automatically; it must
! be compiled before it is used in a CREATE FUNCTION
! command. See below for additional information.)
--- 357,399 ----
Compiled (C) Language Functions
! Functions written in C can be compiled into dynamically loadable
! objects, and used to implement user-defined SQL functions. The
! first time the user defined function is called inside the backend,
! the dynamic loader loads the function's object code into memory,
! and links the function with the running
! Postgres executable. The SQL syntax
! for the command links the SQL function
! to the C source function in one of two ways. If the SQL function
! has the same name as the C source function the first form of the
! statement is used. The string argument in the AS clause is the
! full pathname of the file that contains the dynamically loadable
! compiled object. If the name of C function is different from the
! name of the SQL function, then the second form is used. In this
! form the AS clause takes two string arguments, the first is the
! full pathname of the dynamically loadable object file, and the
! second is the link symbol that the dynamic loader should search
! for. This link symbol is just the function name in the C source
! code.
!
! After it is used for the first time, a dynamically loaded, user
! function is retained in memory, and future calls to the function
! only incur the small overhead of a symbol table lookup.
! The string which specifies the object file (the string in the AS
! clause) should be the full path of the object
! code file for the function, bracketed by quotation marks. If a
! link symbol is used in the AS clause, the link symbol should also be
! bracketed by single quotation marks, and should be exactly the
! same as the name of function in the C source code. On UNIX systems
! the command nm will print all of the link
! symbols in a dynamically loadable object.
! (Postgres will not compile a function
! automatically; it must be compiled before it is used in a CREATE
! FUNCTION command. See below for additional information.)
***************
*** 960,969 ****
Name Space Conflicts
! As of Postgres v6.5,
! CREATE FUNCTION can decouple a C language
! function name from the name of the entry point. This is now the
! preferred technique to accomplish function overloading.
--- 978,990 ----
Name Space Conflicts
! As of Postgres v6.6, the alternative
! form of the AS clause for the SQL CREATE
! FUNCTION command described in
! decouples the SQL function name from the function name in the C
! source code. This is now the preferred technique to accomplish
! function overloading.
*** ./src/bin/psql/psqlHelp.h.orig Thu Sep 16 11:53:50 1999
--- ./src/bin/psql/psqlHelp.h Thu Sep 16 12:23:12 1999
***************
*** 88,95 ****
"create a user-defined function",
"\
\tCREATE FUNCTION function_name ([type1, ...typeN]) RETURNS return_type\n\
! \tAS 'object_filename'|'sql-queries'|'builtin_function_name'\n\
! \tLANGUAGE 'c'|'sql'|'internal';"},
{"create index",
"construct an index",
"\
--- 88,101 ----
"create a user-defined function",
"\
\tCREATE FUNCTION function_name ([type1, ...typeN]) RETURNS return_type\n\
! \tAS 'sql-queries'|'builtin_function_name'|'object_filename'\n\
! \tLANGUAGE 'sql'|'internal'|'c';\n\
! \n\
! OR\n\
! \n\
! \tCREATE FUNCTION function_name ([type1, ...typeN]) RETURNS return_type\n\
! \tAS 'object_filename', 'link_symbol'\n\
! \tLANGUAGE 'c';"},
{"create index",
"construct an index",
"\