plperl db access documentation enhancement

Hello,

We were asked by Enova Financial to improve the documentation of PL/Perl database access functions.
Alvaro and me worked on that and we produced the patch that is attached. It splits initial block of functions
into the groups with the description directly following each of the group, corrects couple of mistakes and
adds an example.

One of the existing mistakes was confusion in definitions of spi_exec_prepared and spi_query_prepared.
Another one is usage of INTEGER type to return the result of spi_prepare in the example for prepared queries.
When trying to execute that function I've got the following error:

postgres=# CREATE OR REPLACE FUNCTION init() RETURNS INTEGER AS $#
    $_SHARED{my_plan} = spi_prepare( 'SELECT (now() + $1)::date AS now', 'INTERVAL');
$$ LANGUAGE plperl;

CREATE FUNCTION

postgres=# select init();
ERROR:  invalid input syntax for integer: "0x1007d6f40"
CONTEXT:  PL/Perl function "init"

Since the return value is not used anyway, I've changed the return type of the function declaration in the example to
VOID.

I think this is a good reason to suggest backpatching these changes  down to 8.2.




--
Alexey Klyukin                    http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc