Mark A. Hershberger

NAME

IO::BLOB::Pg - Emulate IO::File interface for PostgreSQL Large Objects

SYNOPSIS

 use IO::BLOB::Pg;
 use DBI;

 $dbh = DBI->connect("dbi:Pg:dbname=template1", "", "",
                     {RaiseError=>1,
                      AutoCommit=>0}) # <- Absolutely necessary!
 $io = IO::BLOB::Pg->new($dbi); # Create a new blob
 tie *IO, 'IO::BLOB::Pg';

 # write data
 print $io "string\n";
 $io->print(@data);
 syswrite($io, $buf, 100);

 select $io;
 printf "Some text %s\n", $str;

 # seek
 $pos = $io->getpos;
 $io->setpos(0);        # rewind
 $io->seek(-30, -1);

 # read data
 <$io>;
 $io->getline;
 read($io, $buf, 100);

 # get the blob's oid
 $oid = $io->oid;

 # close up
 $io->close;

 # open a previously created blob
 $io = IO::BLOB::Pg->new($dbi, $oid);

**** WARNING ****

To use this module, you *must* feed your DBI connection `AutoCommit => 0'. See the PostgreSQL documentation for more details.

DESCRIPTION

The IO::BLOB::Pg module provide the IO::File interface for Large Objects (aka BLOBs) in a PostgreSQL database. An IO::BLOB::Pg object can be attached to a Large Object ID, and will make it possible to use the normal file operations for reading or writing data, as well as seeking to various locations of the object.

This provides a tremendous amount of convenience since you can treat the object just like a regular file and operate on it as you would normally in Perl instead of doing all sorts of funky stuff like:

  $dbh->func($lobjfd, $buff, $len, "lo_read");

you get:

  <$lobjfd>

I based this code on Gisle Aas' IO::String.

The IO::BLOB::Pg module provides an interface compatible with IO::File as distributed with IO-1.20, but the following methods are not available; new_from_fd, fdopen, format_write, format_page_number, format_lines_per_page, format_lines_left, format_name, format_top_name.

The following methods are specific for the IO::BLOB::Pg class:

$io = IO::BLOB::Pg->new( $dbh[, $objid] )

The constructor returns a newly created IO::BLOB::Pg object. You must supply it with a database handle. It takes an optional argument which is oid of the large objectto read from or write into. If no $objid argument is given, then a new large object is created.

The IO::BLOB::Pg object returned will be tied to itself. This means that you can use most perl IO builtins on it too; readline, <>, getc, print, printf, syswrite, sysread, close.

$io->open( $dbh[, $objid] )

Attach an existing IO::BLOB::Pg object to some other $objid, or create a new large object if no $objid is given. The position is reset back to 0.

$io->oid

This method will return the oid of the large object. This is useful for when you create a large object and what to put a reference to it in another table.

$io->pad( [$char] )

The pad() method makes it possible to specify the padding to use if the object is extended by either the truncate() method. It is a single character and defaults to "\0".

$io->pos( [$newpos] )

Yet another interface for reading and setting the current read/write position within the object (the normal getpos/setpos/tell/seek methods are also available). The pos() method will always return the old position, and if you pass it an argument it will set the new position.

$io->length

Convenience method that gives you the size of the Blob.

One more difference compared to IO::Handle, is that the write() and syswrite() methods allow the length argument to be left out.

BUGS

The perl TIEHANDLE interface is still not complete. There are quite a few file operations that will not yet invoke any method on the tied object. See perltie for details.

SEE ALSO

IO::File, IO::String

COPYRIGHT

Copyright 2000 Mark A. Hershberger, <mah@everybody.org>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.