view release on metacpan or  search on metacpan

Illustra.pm  view on Meta::CPAN

You can find out which databases are available using the function:

    @dbnames=DBI->data_sources('Illustra');

Note that you may be able to connect to other databases not returned by this
method. Also some databases returned by this method may be unavailable due
to access rights or other reasons.

=head2 CONNECTING TO A DATABASE

    $dbh = DBI->connect("dbi:Illustra:$database",$user,$pass);
    $dbh = DBI->connect("dbi:Illustra:$database",$user,$pass,\%attr);

The $database part of the first argument specifies the name of the database
to connect to. Currently, only databases served by the default server may
be connected.

=head2 DISCONNECTING FROM A DATABASE

You can also disconnect from the database:

    $dbh->disconnect;

This will rollback any uncommitted work. Note that this does not destroy
the database handle. Any statements prepared using this handle are finished
and cannot be used again.

=head2 LARGE OBJECTS

Illustra supports values known as large objects, which may be larger than
a database page, and are stored as separate files outside the database.
DBD::Illustra provides support for reading large objects through the
non-DBI C<read_large_object> method.
Illustra will not allow large objects to be read while a
query is active, and also doesn't provide enough information for the driver
to determine which columns returned contain large objects. This means that
the user of DBD::Illustra must go through more work to read large objects.
When a large object column is selected from, instead of returning the contents
of the column, Illustra returns a "large object handle," which may be used to
retrieve the contents of the large object, once the query is finished:

    $sth=$dbh->prepare('some query returning large objects');
    $sth->execute;
    my($lohandle)=$sth->fetchrow_array;
    # Query MUST be finished for this to work
    $sth->finish;

    # Read large object
    $offset=0;
    $blob='';
    while(defined($frag=$dbh->func($lohandle,$offset,4096,'read_large_object'))){
      $len=length $flag or last;
      $blob.=$frag;
      $offset+=$len;
    }

Due to the limitations in the Illustra API, it is not
possible to support reading large objects from each row, as they are fetched.
This means that future versions of DBD::Illustra will never be able to
transparently return large objects with normal column data. However, you can
cast large object values to large_text, in which case they will be returned
as normal values.

=head1 AUTHOR

Peter Haworth (pmh@edison.ioppublishing.com)

=head1 SEE ALSO

L<DBI>

=cut