NAME

DBD::Illustra - DBI driver for Illustra Databases

DESCRIPTION

This document describes DBD::Illustra version 0.04.

You should also read the documentation for DBI as this document only contains information specific to DBD::Illustra.

USE OF DBD::Illustra

Loading DBD::Illustra

To use the DBD::Illustra software, you need to load the DBI software.

    use DBI;

Under normal circumstances, you should then connect to your database using the notation in the section "CONNECTING TO A DATABASE" which calls DBI->connect().

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.

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.

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.

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 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.

AUTHOR

Peter Haworth (pmh@edison.ioppublishing.com)

SEE ALSO

DBI