<!--

$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.9 1999/07/22 15:09:07 thomas Exp $

$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.10 1999/09/28 04:34:39 momjian Exp $

Postgres documentation

-->

<synopsis>

CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )

RETURNS <replaceable class="parameter">rtype</replaceable>

AS <replaceable class="parameter">definition</replaceable>

AS <replaceable class="parameter">definition</replaceable>

LANGUAGE '<replaceable class="parameter">langname</replaceable>'

CREATE FUNCTION <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">ftype</replaceable> [, ...] ] )

RETURNS <replaceable class="parameter">rtype</replaceable>

AS <replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable>

LANGUAGE 'c'

</synopsis>

<refsect2 id="R2-SQL-CREATEFUNCTION-1">

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><replaceable class="parameter">obj_file</replaceable> , <replaceable class="parameter">link_symbol</replaceable></term>

<listitem>

<para>

This form of the <command>AS</command> 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 <replaceable

class="parameter">obj_file</replaceable> is the name of the file

containing the dynamically loadable object, and <replaceable

class="parameter">link_symbol</replaceable>, is the object's link

symbol which is the same as the name of the function in the C

language source code.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><replaceable class="parameter">langname</replaceable></term>

<listitem>

<para>

<productname>Postgres</productname> 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 <literal>internal</literal>

andC-language functions, however.

</para>

so long as they have distinct argument types. This facility must

beused with caution for <literal>internal</literal> and

C-language functions, however.

</para>

<para>

Two <literal>internal</literal>

</para>

<para>

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.

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 <command>AS</command> clause in the

<command>CREATE FUNCTION</command> syntax to ensure that

overloaded SQL functions names are resolved to the correct

dynamically linked objects.

</para>

<para>

A C function cannot return a set of values.

</para>

is correct. It is intended for use in a CHECK contraint.

</para>

<programlisting>

<userinput>

CREATE FUNCTION ean_checkdigit(bpchar, bpchar) RETURNS bool

AS '/usr1/proj/bray/sql/funcs.so' LANGUAGE 'c';

eancode char(6) CHECK (eancode ~ '[0-9]{6}'),

CONSTRAINT ean CHECK (ean_checkdigit(eanprefix, eancode))

);

</userinput>

</programlisting>

<para>

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 <productname>Postgres</productname> 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 <command>AS</command> clause in the SQL definition

</para>

<programlisting>

CREATE FUNCTION point(complex) RETURNS point

AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'

LANGUAGE 'c';

</programlisting>

<para>

The C decalaration of the function is:

</para>

<programlisting>

Point * complex_to_point (Complex *z)

{

Point *p;

p = (Point *) palloc(sizeof(Point));

p->x = z->x;

p->y = z->y;

return p;

}

</programlisting>

</refsect1>

<refsect1 id="R1-SQL-CREATEFUNCTION-4">

SQL/PSM <command>CREATE FUNCTION</command> has the following syntax:

<synopsis>

CREATE FUNCTION <replaceable class="parameter">name</replaceable>

( [ [ IN | OUT | INOUT ] <replaceable class="parameter">eter</replaceable>eable>eable> <replaceable

class="parameter">type</replaceable> [, ...] ] )

( [ [ IN | OUT | INOUT ] <replaceable class="parameter">type</replaceable> [, ...] ] )

RETURNS <replaceable class="parameter">rtype</replaceable>

LANGUAGE '<replaceable class="parameter">langname</replaceable>'

ESPECIFIC <replaceable class="parameter">routine</replaceable>

<title>Compiled (C) Language Functions</title>

<para>

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.

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

<productname>Postgres</productname> executable. The SQL syntax

for the <xref linkend="sql-createfunction-title"

endterm="sql-createfunction-title"> 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.

</para>

<para>

The string which specifies the object file (the string in the AS clause)

should be the <emphasis>full path</emphasis>

of the object code file for the function, bracketed by quotation

marks. (<productname>Postgres</productname> will not compile a

function automatically; it must

be compiled before it is used in a CREATE FUNCTION

command. See below for additional information.)

The string which specifies the object file (the string in the AS

clause) should be the <emphasis>full path</emphasis> 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 <command>nm</command> will print all of the link

symbols in a dynamically loadable object.

(<productname>Postgres</productname> will not compile a function

automatically; it must be compiled before it is used in a CREATE

FUNCTION command. See below for additional information.)

</para>

<sect2>

<title>Name Space Conflicts</title>

<para>

As of <productname>Postgres</productname> v6.5,

<command>CREATE FUNCTION</command> can decouple a C language

function name from the name of the entry point. This is now the

preferred technique to accomplish function overloading.

As of <productname>Postgres</productname> v6.6, the alternative

form of the AS clause for the SQL <command>CREATE

FUNCTION</command> command described in <xref

linkend="sql-createfunction-title" endterm="sql-createfunction-title">

decouples the SQL function name from the function name in the C

source code. This is now the preferred technique to accomplish

function overloading.

</para>

<sect3>

}

interpret_AS_clause(constchar*languageName,constchar*as,

interpret_AS_clause(constchar*languageName,constList*as,

char**prosrc_str_p,char**probin_str_p)

{

Assert(as!=NIL);

if (strcmp(languageName,"C")==0)

{

*prosrc_str_p="-";

*probin_str_p= (char*)as;

*probin_str_p=strVal(lfirst(as));

if (lnext(as)==NULL)

*prosrc_str_p="-";

*prosrc_str_p=strVal(lsecond(as));

}

{

*prosrc_str_p=(char*)as;

*prosrc_str_p=strVal(lfirst(as));

*probin_str_p="-";

if (lnext(as)!=NULL)

elog(ERROR,"CREATE FUNCTION: parse error in 'AS %s, %s'.",

strVal(lfirst(as)),strVal(lsecond(as)));

}

}

*

*

* IDENTIFICATION

* $Header: /cvsroot/pgsql/src/backend/parser/gram.y,v 2.99 1999/09/23 17:02:46 momjian Exp $

* $Header: /cvsroot/pgsql/src/backend/parser/gram.y,v 2.100 1999/09/28 04:34:44 momjian Exp $

*

* HISTORY

* AUTHORDATEMAJOR EVENT

%type <list>stmtblock, stmtmulti,

result, relation_name_list, OptTableElementList,

OptInherit, definition,

opt_with, func_args, func_args_list,

opt_with, func_args, func_args_list, func_as,

oper_argtypes, RuleActionList, RuleActionBlock, RuleActionMulti,

opt_column_list, columnList, opt_va_list, va_list,

sort_clause, sortby_list, index_params, index_list, name_list,

*****************************************************************************/

ProcedureStmt:CREATE FUNCTION func_name func_args

RETURNS func_return opt_with ASSconst LANGUAGE Sconst

RETURNS func_return opt_with ASfunc_as LANGUAGE Sconst

{

ProcedureStmt *n = makeNode(ProcedureStmt);

n->funcname = $3;

{$$ = lappend($1,makeString($3)); }

;

func_as: Sconst

{ $$ = lcons(makeString($1),NIL); }

| Sconst ',' Sconst

{ $$ = lappend(lcons(makeString($1),NIL), makeString($3)); }

;

func_return: set_opt TypeId

{

TypeName *n = makeNode(TypeName);

HeapTupleprocedureTuple;

Form_pg_procprocedureStruct;

char*proname,

*probinstring;

*probinstring,

*prosrcstring,

*linksymbol;

Datumprobinattr;

Datumprosrcattr;

func_ptruser_fn;

Relationrel;

boolisnull;

heap_close(rel,AccessShareLock);

user_fn=handle_load(probinstring,proname);

prosrcattr=heap_getattr(procedureTuple,

Anum_pg_proc_prosrc,

RelationGetDescr(rel),&isnull);

if (isnull)

{/* Use the proname for the link symbol */

linksymbol=proname;

}

elseif (!PointerIsValid(prosrcattr))

{/* pg_proc must be messed up! */

heap_close(rel);

elog(ERROR,"fmgr: Could not extract prosrc for %u from %s",

procedureId,ProcedureRelationName);

return (func_ptr)NULL;

}

{/* The text in prosrcattr is either "-" or

prosrcstring=textout((structvarlena*)prosrcattr);

if (strcmp(prosrcstring,"-")==0)

linksymbol=proname;

linksymbol=prosrcstring;

}

user_fn=handle_load(probinstring,linksymbol);

pfree(probinstring);