Update plhandler.sgml to describe validators and inline handlers for

procedural languages.

diff --git a/doc/src/sgml/plhandler.sgml b/doc/src/sgml/plhandler.sgml
index 6173d5a678159c59bfaf3de1ba04aca9762b03d1..0d8ec93b8636366016086fc69fa735ab99168ccb 100644 (file)
--- a/doc/src/sgml/plhandler.sgml
+++ b/doc/src/sgml/plhandler.sgml
@@ -1,4 +1,4 @@
-
+
 
  
    Writing A Procedural Language Handler
@@ -13,7 +13,7 @@
     the current version 1 interface for compiled
     languages (this includes functions in user-defined procedural languages,
     functions written in SQL, and functions using the version 0 compiled
-    language interface), go through a call handler
+    language interface) go through a call handler
     function for the specific language.  It is the responsibility of
     the call handler to execute the function in a meaningful way, such
     as by interpreting the supplied source text.  This chapter outlines
@@ -51,8 +51,7 @@
 
    
     It's up to the call handler to fetch the entry of the function from the
-    system table
-    pg_proc and to analyze the argument
+    pg_proc system catalog and to analyze the argument
     and return types of the called function. The AS clause from the
     CREATE FUNCTION command for the function will be found
     in the prosrc column of the
@@ -152,10 +151,71 @@ CREATE LANGUAGE plsample
 
    
 
+   
+    Although providing a call handler is sufficient to create a minimal
+    procedural language, there are two other functions that can optionally
+    be provided to make the language more convenient to use.  These
+    are a validator and an
+    inline handler.  A validator can be provided
+    to allow language-specific checking to be done during
+    .
+    An inline handler can be provided to allow the language to support
+    anonymous code blocks executed via the 
+    endterm="sql-do-title"> command.
+   
+
+   
+    If a validator is provided by a procedural language, it
+    must be declared as a function taking a single parameter of type
+    oid.  The validator's result is ignored, so it is customarily
+    declared to return void.  The validator will be called at
+    the end of a CREATE FUNCTION command that has created
+    or updated a function written in the procedural language.
+    The passed-in OID is the OID of the function's pg_proc
+    row.  The validator must fetch this row in the usual way, and do
+    whatever checking is appropriate.  Typical checks include verifying
+    that the function's argument and result types are supported by the
+    language, and that the function's body is syntactically correct
+    in the language.  If the validator finds the function to be okay,
+    it should just return.  If it finds an error, it should report that
+    via the normal ereport() error reporting mechanism.
+    Throwing an error will force a transaction rollback and thus prevent
+    the incorrect function definition from being committed.
+   
+
+   
+    Validator functions should typically honor the 
+    linkend="guc-check-function-bodies"> parameter: if it is turned off then
+    any expensive or context-sensitive checking should be skipped.
+    In particular, this parameter is turned off by pg_dump
+    so that it can load procedural language functions without worrying
+    about possible dependencies of the function bodies on other database
+    objects.  (Because of this requirement, the call handler should avoid
+    assuming that the validator has fully checked the function.  The point
+    of having a validator is not to let the call handler omit checks, but
+    to notify the user immediately if there are obvious errors in a
+    CREATE FUNCTION command.)
+   
+
+   
+    If an inline handler is provided by a procedural language, it
+    must be declared as a function taking a single parameter of type
+    internal.  The inline handler's result is ignored, so it is
+    customarily declared to return void.  The inline handler
+    will be called when a DO statement is executed specifying
+    the procedural language.  The parameter actually passed is a pointer
+    to an InlineCodeBlock struct, which contains information
+    about the DO statement's parameters, in particular the
+    text of the anonymous code block to be executed.  The inline handler
+    should execute this code and return.
+   
+
    
     The procedural languages included in the standard distribution
-    are good references when trying to write your own call handler.
+    are good references when trying to write your own language handler.
     Look into the src/pl subdirectory of the source tree.
+    The 
+    reference page also has some useful details.
    
 
  


diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml

index 4c0463ddec1f251eafb1f9a70fe8798de94c5d00..f87308edb3645afe8159b90709f21785211b9d64 100644 (file)

--- a/doc/src/sgml/ref/create_language.sgml
+++ b/doc/src/sgml/ref/create_language.sgml
@@ -1,5 +1,5 @@
 
 
@@ -41,7 +41,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name
   
    CREATE LANGUAGE effectively associates the
    language name with a call handler that is responsible for executing
-   functions written in the language.  Refer to xplang">
+   functions written in the language.  Refer to plhandler">
    for more information about language call handlers.
   
 

diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml
index 4c0463ddec1f251eafb1f9a70fe8798de94c5d00..f87308edb3645afe8159b90709f21785211b9d64 100644 (file)
--- a/doc/src/sgml/ref/create_language.sgml
+++ b/doc/src/sgml/ref/create_language.sgml
@@ -1,5 +1,5 @@
 
 
@@ -41,7 +41,7 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE name
   
    CREATE LANGUAGE effectively associates the
    language name with a call handler that is responsible for executing
-   functions written in the language.  Refer to xplang">
+   functions written in the language.  Refer to plhandler">
    for more information about language call handlers.