<!--

$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.43 2005/08/12 21:42:53 momjian Exp $

$PostgreSQL: pgsql/doc/src/sgml/plperl.sgml,v 2.44 2005/08/24 18:56:07 tgl Exp $

-->

<chapter id="plperl">

<para>

To create a function in the PL/Perl language, use the standard

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

syntax. A PL/Perl function must always return a scalar value. You

can return more complex structures (arrays, records, and sets)

in the appropriate context by returning a reference.

Never return a list. Here follows an example of a PL/Perl

function.

syntax:

<programlisting>

CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS $$

# PL/Perl function body

$$ LANGUAGE plperl;

</programlisting>

The body of the function is ordinary Perl code.

The body of the function is ordinary Perl code. A PL/Perl function must

always return a scalar value. You can return more complex structures

(arrays, records, and sets) by returning a reference, as discussed below.

Never return a list.

</para>

<para>

As with ordinary Perl code, you should use the strict pragma,

which you can do in one of two ways:

<itemizedlist>

<listitem>

<para>

Globally, by adding <quote>plperl</quote> to the list of <xref

linkend="guc-custom-variable-classes"> and setting

<literal>plperl.use_strict</literal> to true in

<filename>postgresql.conf</filename>

</para>

</listitem>

<listitem>

<para>

One function at a time, by using PL/PerlU (you must be database

superuser to do this) and including

<programlisting>

use strict;

</programlisting>

in the function body.

</para>

</listitem>

</itemizedlist>

</para>

<para>

The syntax of the <command>CREATE FUNCTION</command> command requires

<para>

PL/Perl functions can also return sets of either scalar or

composite types.In general, you'll want to return rows one at a

time both to speed up startup time and to keep from queueing up

composite types.Usually you'll want to return rows one at a

time, both to speed up startup time and to keep from queueing up

the entire result set in memory. You can do this with

<function>return_next</function> as illustrated below. Note that

after the last <function>return_next</function>, you must put

either <literal>return;</literal> or (better) <literal>return

undef;</literal>

either <literal>return</literal> or (better) <literal>return

undef</literal>.

<programlisting>

CREATE OR REPLACE FUNCTION perl_set_int(int)

contains either scalars, references to arrays, or references to

hashes for simple types, array types, and composite types,

respectively. Here are some simple examples of returning the entire

result set asa reference:

result set asan array reference:

<programlisting>

CREATE OR REPLACE FUNCTION perl_set_int(int) RETURNS SETOF INTEGER AS $$

it is a hazard if you declare a <application>PL/Perl</> function

as returning a domain type.

</para>

<para>

If you wish to use the <literal>strict</> pragma with your code,

the easiest way to do so is to <command>SET</>

<literal>plperl.use_strict</literal> to true. This parameter affects

subsequent compilations of <application>PL/Perl</> functions, but not

functions already compiled in the current session. To set the

parameter before <application>PL/Perl</> has been loaded, it is

necessary to have added <quote><literal>plperl</></> to the <xref

linkend="guc-custom-variable-classes"> list in

<filename>postgresql.conf</filename>.

</para>

<para>

Another way to use the <literal>strict</> pragma is to just put

<programlisting>

use strict;

</programlisting>

in the function body. But this only works for <application>PL/PerlU</>

functions, since <literal>use</> is not a trusted operation.

</para>

</sect1>

<sect1 id="plperl-database">

<!--

$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.347 2005/08/22 17:34:56 momjian Exp $

$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.348 2005/08/24 18:56:07 tgl Exp $

-->

<chapter Id="runtime">

when using custom variables:

<programlisting>

custom_variable_classes = 'plr,pljava'

custom_variable_classes = 'plr,plperl'

plr.path = '/usr/lib/R'

pljava.foo =1

plruby.bar = true # generates error, unknown class name

plperl.use_strict =true

plruby.use_strict = true # generates error: unknown class name

</programlisting>

</para>

</sect2>