|
1 | | -<!-- $PostgreSQL: pgsql/doc/src/sgml/plhandler.sgml,v 1.7 2006/09/16 00:30:14 momjian Exp $ --> |
| 1 | +<!-- $PostgreSQL: pgsql/doc/src/sgml/plhandler.sgml,v 1.8 2009/10/08 04:41:07 tgl Exp $ --> |
2 | 2 |
|
3 | 3 | <chapter id="plhandler"> |
4 | 4 | <title>Writing A Procedural Language Handler</title> |
|
13 | 13 | the current <quote>version 1</quote> interface for compiled |
14 | 14 | languages (this includes functions in user-defined procedural languages, |
15 | 15 | functions written in SQL, and functions using the version 0 compiled |
16 | | - language interface), go through a <firstterm>call handler</firstterm> |
| 16 | + language interface) go through a <firstterm>call handler</firstterm> |
17 | 17 | function for the specific language. It is the responsibility of |
18 | 18 | the call handler to execute the function in a meaningful way, such |
19 | 19 | as by interpreting the supplied source text. This chapter outlines |
|
51 | 51 |
|
52 | 52 | <para> |
53 | 53 | It's up to the call handler to fetch the entry of the function from the |
54 | | - system table |
55 | | - <classname>pg_proc</classname> and to analyze the argument |
| 54 | + <classname>pg_proc</classname> system catalog and to analyze the argument |
56 | 55 | and return types of the called function. The <literal>AS</> clause from the |
57 | 56 | <command>CREATE FUNCTION</command> command for the function will be found |
58 | 57 | in the <literal>prosrc</literal> column of the |
@@ -152,10 +151,71 @@ CREATE LANGUAGE plsample |
152 | 151 | </programlisting> |
153 | 152 | </para> |
154 | 153 |
|
| 154 | + <para> |
| 155 | + Although providing a call handler is sufficient to create a minimal |
| 156 | + procedural language, there are two other functions that can optionally |
| 157 | + be provided to make the language more convenient to use. These |
| 158 | + are a <firstterm>validator</firstterm> and an |
| 159 | + <firstterm>inline handler</firstterm>. A validator can be provided |
| 160 | + to allow language-specific checking to be done during |
| 161 | + <xref linkend="sql-createfunction" endterm="sql-createfunction-title">. |
| 162 | + An inline handler can be provided to allow the language to support |
| 163 | + anonymous code blocks executed via the <xref linkend="sql-do" |
| 164 | + endterm="sql-do-title"> command. |
| 165 | + </para> |
| 166 | + |
| 167 | + <para> |
| 168 | + If a validator is provided by a procedural language, it |
| 169 | + must be declared as a function taking a single parameter of type |
| 170 | + <type>oid</>. The validator's result is ignored, so it is customarily |
| 171 | + declared to return <type>void</>. The validator will be called at |
| 172 | + the end of a <command>CREATE FUNCTION</> command that has created |
| 173 | + or updated a function written in the procedural language. |
| 174 | + The passed-in OID is the OID of the function's <classname>pg_proc</> |
| 175 | + row. The validator must fetch this row in the usual way, and do |
| 176 | + whatever checking is appropriate. Typical checks include verifying |
| 177 | + that the function's argument and result types are supported by the |
| 178 | + language, and that the function's body is syntactically correct |
| 179 | + in the language. If the validator finds the function to be okay, |
| 180 | + it should just return. If it finds an error, it should report that |
| 181 | + via the normal <function>ereport()</> error reporting mechanism. |
| 182 | + Throwing an error will force a transaction rollback and thus prevent |
| 183 | + the incorrect function definition from being committed. |
| 184 | + </para> |
| 185 | + |
| 186 | + <para> |
| 187 | + Validator functions should typically honor the <xref |
| 188 | + linkend="guc-check-function-bodies"> parameter: if it is turned off then |
| 189 | + any expensive or context-sensitive checking should be skipped. |
| 190 | + In particular, this parameter is turned off by <application>pg_dump</> |
| 191 | + so that it can load procedural language functions without worrying |
| 192 | + about possible dependencies of the function bodies on other database |
| 193 | + objects. (Because of this requirement, the call handler should avoid |
| 194 | + assuming that the validator has fully checked the function. The point |
| 195 | + of having a validator is not to let the call handler omit checks, but |
| 196 | + to notify the user immediately if there are obvious errors in a |
| 197 | + <command>CREATE FUNCTION</> command.) |
| 198 | + </para> |
| 199 | + |
| 200 | + <para> |
| 201 | + If an inline handler is provided by a procedural language, it |
| 202 | + must be declared as a function taking a single parameter of type |
| 203 | + <type>internal</>. The inline handler's result is ignored, so it is |
| 204 | + customarily declared to return <type>void</>. The inline handler |
| 205 | + will be called when a <command>DO</> statement is executed specifying |
| 206 | + the procedural language. The parameter actually passed is a pointer |
| 207 | + to an <structname>InlineCodeBlock</> struct, which contains information |
| 208 | + about the <command>DO</> statement's parameters, in particular the |
| 209 | + text of the anonymous code block to be executed. The inline handler |
| 210 | + should execute this code and return. |
| 211 | + </para> |
| 212 | + |
155 | 213 | <para> |
156 | 214 | The procedural languages included in the standard distribution |
157 | | - are good references when trying to write your owncall handler. |
| 215 | + are good references when trying to write your ownlanguage handler. |
158 | 216 | Look into the <filename>src/pl</> subdirectory of the source tree. |
| 217 | + The <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title"> |
| 218 | + reference page also has some useful details. |
159 | 219 | </para> |
160 | 220 |
|
161 | 221 | </chapter> |