*** ./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", "\