view release on metacpan or  search on metacpan

Sqlflex.pm  view on Meta::CPAN

The message may or may not extend over several lines, and is generally
formatted so that it will display neatly within 80 columns.
The last character of the message is a newline.

If $dbh->{PrintError} is false, then DBI does not report any errors
when it detects them; it is up to the user to note that errors have
occurred and to report them.

If you connect using the DBI->connect() method, or if you have
forgotten the driver, you can discover it again using:

    $drh = $dbh->{Driver};

This allows you to access the driver methods and attributes described
previously.

=over 4

BUG: The name of the database should be tracked more carefully via the
DATABASE, CLOSE DATABASE, CREATE DATABASE, ROLLFORWARD DATABASE and
START DATABASE statements.
Note that you cannot prepare CONNECT statements, so they do not have
to be tracked.

=back

=head2 METADATA

There are two methods which can be called using the DBI func() to get
at some basic Sqlflex metadata relatively conveniently.

	@list = $dbh->func('_tables');
	@list = $dbh->func('user', '_tables');
	@list = $dbh->func('base', '_tables');
	@list = $dbh->func('user', 'base', '_tables');
	@list = $dbh->func('system', '_tables');
	@list = $dbh->func('view', '_tables');
	@list = $dbh->func('synonym', '_tables');

The lists of tables are all qualified as 'owner'.tablename, and may be
used in SQL statements without fear that the table is not present in
the database (unless someone deletes it behind your back).
The leading arguments qualify the list of names returned.
Private synonyms are only reported for the current user.

	@list = $dbh->func('_columns');
	@list = $dbh->func(@tables, '_columns');

The lists are each references to an array of values corresponding to
the owner name, table name, the column number, the column name, the
basic data type (ix_ColType value - see below) and data length
(ix_ColLength - see below).
If no tables are listed, then all columns in the database are listed.
This can be quite slow because handling synonyms properly requires a
UNION operation.
Further, although the '_tables' method report the names of remote
synonyms, the '_columns' method does not expand them (mainly because
it is very hard t do it properly).
See the examples in t/metadata.t for how these can be used.
Exercise for the reader: extend '_columns' so that it reports on the
columns in remote synonyms, including relocated remote synonyms where
the original referenced site now forwards the name to a third site!

=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.
You need to do an explicit 'undef $dbh' to destroy the handle.
Any statements prepared using this handle are finished (see below) and
cannot be used again.
All space associated with the statements is released.

If you are using an Sqlflex driver for which $drh->{ProductVersion}
>= 600, then you can have multiple concurrent connections.
This means that multiple calls to $drh->connect will give you
independent connections to one or more databases.

If you are using an Sqlflex driver for which $drh->{ProductVersion} <
600, then you cannot have multiple concurrent connections.
If you make multiple calls to $drh->connect, you will achieve the same
effect as executing several database statements in a row.
This will generally switch databases successfully, but may invalidate
any statements previously prepared.
It may fail if the current database is not local, or if there is an
active transaction, etc.

=head2 SIMPLE STATEMENTS

Given a database connection, you can execute a variety of simple
statements using a variety of different calls:

    $dbh->commit;
    $dbh->rollback;

These two operations commit or rollback the current transaction.
If the database is unlogged, they do nothing.
If AutoCommit is set to 1, then they do nothing useful.
If AutoCommit is set to 0, then a new transaction is started
(implicitly for a database which is MODE ANSI, explicitly for a
database which is not MODE ANSI).

You can execute most preparable parameterless statements using:

    $dbh->do($stmt);

The statement should not be either SELECT (other than SELECT...INTO
TEMP) or EXECUTE PROCEDURE where the procedure returns data.

You can execute an arbitrary statement with parameters using:

    $dbh->do($stmt, undef, @parameters);
    $dbh->do($stmt, undef, $param1, $param2);

The 'undef' represents an undefined reference to a hash of attributes
(\%attr) which is documented in the DBI specification.
The 0.56 edition of this documentation omitted this argument, which
caused confusion.