Chapter 52. Writing A Procedural Language
All calls to functions that are written in a language other than the current “version 1” interface for
compiled languages (this includes functions in user-deﬁned procedural languages, functions written
in SQL, and functions using the version 0 compiled language interface) go through a call handler
function for the speciﬁc language. It is the responsibility of the call handler toexecute the function in
ameaningful way, such as by interpreting the supplied source text. This chapter outlines how a new
procedural language’s call handler can be written.
The call handler for a procedural language is a “normal” function that must be written in a compiled
language such as C, using the version-1 interface, and registered with PostgreSQL as taking no ar-
guments and returning the type
.This special pseudotype identiﬁes the function
as a call handler and prevents it from being called directly in SQL commands. For more details on C
language calling conventions and dynamic loading, see Section35.9.
The call handler is called in the same way as any other function: It receives a pointer to a
containing argument values and information about the called
function, and it is expected to return a
result (and possibly set the
ﬁeld of the
structure, if it wishes to return an SQL null result). The difference
between a call handler and an ordinary callee function is that the
ﬁeld of the
structure will contain the OID of the actual function to be called, not of
the call handler itself. The call handler must use this ﬁeld to determine which function to execute.
Also, the passed argument list has been set up according to the declaration of the target function, not
of the call handler.
It’s up to the call handler to fetch the entry of the function from the
system catalog and
to analyze the argument and return types of the called function. The
clause from the
command for the function willbe found in the
column of the
is commonly source text in the procedural language, but in theory it could be something else, such as
apath name to a ﬁle, or anything else that tells the call handler what to do in detail.
Often, the same function is called many times per SQL statement. A call handler can avoid repeated
lookups of information about the called function by using the
ﬁeld. This will
,but can be set by the call handler to point at information about the called func-
tion. On subsequent calls, if
is already non-
then it can be used and the
information lookup stepskipped. The call handler must make sure that
to point at memory that will live at least until the end of the current query, since an
structure couldbekept that long. One waytodothis is to allocate the extra data inthe memorycontext
;such data will normally have the same lifespan as the
itself. But the handler could also choose to use a longer-lived memory context so that it can cache
function deﬁnition information across queries.
When a procedural-language function is invoked as a trigger, no arguments are passed in the usual
way, but the
ﬁeld points at a
as it is in a plain function call. A language handler should provide mechanisms for
procedural-language functions to get at the trigger information.
This is a template for a procedural-language handler written in C: