Thread: Proposal for new PL/Perl README

to replace the one currently in $PGSRC/src/pl/plperl

it encompasses the information in that document while adding more structure
and more specific details about what is needed.  it also addresses
a couple of issues that came up when i had personally installed it.

since there is no email address for a maintainer on that, i post it here
for review, comment, and (hopefully) integration with the source tree.

regards
--e--



----------------------------------------------------------------------
README for PL/Perl                                          2000.09.19

PREREQUISITES
======================================================================
+ Perl must be built as a shared library.
+ when compiling Postgres, use the --with-perl option.

BUILDING
======================================================================
+ commands:
  cd $POSTGRES_SRC/src/pl/plperl/;
  perl Makefile.PL [POLLUTE=1];
  make;

     If you get error messages like:
     `errgv' undeclared
     `na' undeclared
     Then use the POLLUTE=1 flag.

INSTALLING
======================================================================
+ copy the shared object file to a reasonable location:
  cp blib/arch/auto/plperl/plperl.so $PG_HOME/lib

      Be sure to copy the .so file and not the .o file.
      If you get an error like:
          ELF file's phentsize not the expected size.
      you've copied the wrong file.

CONFIGURING
======================================================================
+ as postgres super user:
  createlang plperl [database]

NOTES ON USAGE
======================================================================
+ Use q[], qq[], and qw[] instead of single quotes in
  function definitions.
+ When using escape sequences, you must backslash your
  backslashes, e.g.
    $alphanum =~ s/\W//g;  # Wrong!  Will replace capital W's
    $alphanum =~ s/\\W//g; # Right!  Will replace non-word chars
+ Arguments to the function are available in @_
+ If argument is declared as a tuple, then tuple is represented as a
  hash reference.

EXAMPLES
======================================================================
CREATE FUNCTION addints(int4, int4) RETURNS int4 AS '
return $_[0] + $_[1]
' LANGUAGE 'plperl';

SELECT addints(3,4);

-- of course, you can pass tuples;
CREATE TABLE twoints ( a integer, b integer);
CREATE FUNCTION addtwoints(twoints) RETURNS integer AS '
$tup = shift;
return $tup->{"a"} + $tup->{"b"};
' LANGUAGE 'plperl';

SELECT addtwoints(twoints) from twoints;

-- here is one that will fail. Creating the function
-- will work, but using it will fail.
CREATE FUNCTION badfunc() RETURNS int4 AS '
open(TEMP, ">/tmp/badfile");
print TEMP "Gotcha!\n";
return 1;
' LANGUAGE 'plperl';

SELECT badfunc();

"Edward Q. Bridges" <ed.bridges@buzznik.com> writes:
> since there is no email address for a maintainer on that, i post it here
> for review, comment, and (hopefully) integration with the source tree.

Mark Hollomon <mhh@mindspring.com> is the originator of plperl.  Please
get together with him on documentation and code updates.  We're glad to
accept updates but it's only fair to let Mark comment first...

            regards, tom lane

Tom Lane wrote:

> "Edward Q. Bridges" <ed.bridges@buzznik.com> writes:
> > since there is no email address for a maintainer on that, i post it here
> > for review, comment, and (hopefully) integration with the source tree.
>
> Mark Hollomon <mhh@mindspring.com> is the originator of plperl.  Please
> get together with him on documentation and code updates.  We're glad to
> accept updates but it's only fair to let Mark comment first...
>
>                         regards, tom lane

I also proposed to removed the POLLUTE option by applying the following patch

to the plperl.c file. It compile well on Perl 5.005_03 and Perl 5.6.0.

328c328
<       if (SvTRUE(GvSV(PL_errgv)))
---
>       if (SvTRUE(GvSV(errgv)))
334c334
<               elog(ERROR, "creation of function failed : %s",
SvPV(GvSV(PL_errgv), PL_na));
---
>               elog(ERROR, "creation of function failed : %s",
SvPV(GvSV(errgv), na));
444c444
<       if (SvTRUE(GvSV(PL_errgv)))
---
>       if (SvTRUE(GvSV(errgv)))
450c450
<               elog(ERROR, "plperl : error from function : %s",
SvPV(GvSV(PL_errgv), PL_na));
---
>               elog(ERROR, "plperl : error from function : %s",
SvPV(GvSV(errgv), na));


Regard,

Gilles

Gilles DAROLD <gilles@darold.net> writes:
> I also proposed to removed the POLLUTE option by applying the
> following patch to the plperl.c file. It compile well on Perl 5.005_03
> and Perl 5.6.0.

... and will fail entirely on older Perls, before 5.004-something where
they changed the API.  The POLLUTE hack is at least backwards-compatible.

What we really need to do is revise plperl and interfaces/perl5 to use
Devel::PPPort, which masks the API change; but no one's got round to it.

            regards, tom lane

Tom Lane wrote:

> Gilles DAROLD <gilles@darold.net> writes:
> > I also proposed to removed the POLLUTE option by applying the
> > following patch to the plperl.c file. It compile well on Perl 5.005_03
> > and Perl 5.6.0.
>
> ... and will fail entirely on older Perls, before 5.004-something where
> they changed the API.  The POLLUTE hack is at least backwards-compatible.
>
> What we really need to do is revise plperl and interfaces/perl5 to use
> Devel::PPPort, which masks the API change; but no one's got round to it.
>
>                         regards, tom lane

I think this is a waste of time, Perl older versions are not as well as
newer (up to
5.004 which have some leak of memory) and upgrading Perl will assume the
backwards
compatibility as I know, at least it's one of its goal...

Regards,

Gilles

Edward Q. Bridges writes:

> to replace the one currently in $PGSRC/src/pl/plperl

We probably should add something like this to the main documentation body.


--
Peter Eisentraut      peter_e@gmx.net       http://yi.org/peter-e/