view release on metacpan or  search on metacpan

lib/DBD/Ovrimos.pm  view on Meta::CPAN

=head1 NAME

DBD::Ovrimos - DBI Driver for Ovrimos (formerly Altera SQL Server)

=head1 SYNOPSIS

     use DBI;
     my $dbh=DBI->connect(
          "dbi:Ovrimos:some.host.com:2500",
          "user",
          "passwd")
          or die "Cannot connect\n";
     # more DBI calls...

=head1 DESCRIPTION

DBI driver for Ovrimos (See L<DBI(3)> for details). This driver is essentially
a rename of DBD::Altera. Since DBI
is a moving target at the time of this writing, this driver should only be
assumed to work with DBI 0.93.
A standard notice in DBD drivers' man pages is that, since the DBI is not yet
stable, any DBD driver should be considered ALPHA software. So be it.
We will try to keep up with the changes, stay tuned at
<http://www.altera.gr/download.html> which is the primary download site for
this driver.

=head1 CURRENT VERSION

Release 0.12 Name change...
Previous release were:
Release 0.11 Essentially a bug-fix.
Release 0.10 (one hair short of 1.00). Main difference from previous version
0.09 is minor alterations to permit use for AGI (Another Gateway Interface).
In other words, how can one use the same module to write both DBI programs
and stored procedures for Ovrimos. Also, stored procedures
are now supported, using the pseudo-SQL "call xxx ..." statement. See
the documentation of Ovrimos for details.

=head1 DRIVER-SPECIFIC BEHAVIOR

=head2 DATA-SOURCE NAME

The dsn string passed to DBI->connect must be of the following form:

     dbi:Ovrimos:host:port

where host is a TCP/IP address in human-readable or dotted-decimal format, and
port is the TCP/IP port number to use (Ovrimos SQLPORT configuration
parameter).

=head2 CONNECTIONS, SESSIONS AND TRANSACTIONS

One can have multiple connections to an Ovrimos database, up to
the limit specified by one's User License. Keep in mind that what the License
calls 'sessions' amount to what are called separate statements in DBI.
Underlying the DBI is a protocol using the ODBC-equivalent 'connections' and
'statements'. Sessions are kept live until commit/rollback, and that can
result in denial of service if you reach the License limit. The database 
handle will reuse an inactive statement handle, so finish() often.

Commit/rollback finish()'es implicitly all open cursors (that's the answer
one asks ODBC with SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR).

Cached statements are not available. In the near future it is planned to
cache SQL statements internally at the SQL Server, so preparing the same
SQL statement as some time before will return a new $sth but without the
cost associated with preparing from scratch.

=head2 DATA TYPES

All ODBC 2.0 data types are supported. The format of time/date values is
as per the SQL/2 Standard, i.e.: S<'DATE YYYY-MM-DD'>, S<'TIME HH:MM:SS'> and
S<'TIMESTAMP YYYY-MM-DD HH:MM:SS'>.

Ovrimos supports some additional types that
are given below alongside their numerical value:

=over 4

=item UNSIGNED SMALLINT = 20

=item UNSIGNED INTEGER  = 21

=item UNSIGNED TINYINT  = 22

=item UNSIGNED BIGINT   = 23

=back

=head2 ERROR HANDLING

As it stands, the DBI does not support the notion of warnings.
Consequently, there are no diagnostics for successful calls.
There is no obstacle in adding this, but since perl code using
DBI will not check $h->errstr for successful operations, there is
not much incentive to actually do it. Diagnostics for failed calls
are inspected with the usual DBI calls. Do not pay any attention to
$h->err; it is dummy. Ovrimos returns Standard SQL
SQLSTATES and assorted messages, modelled principally after ODBC
use. Since many diagnostics can be accumulated by one call, the
diagnostics are merged, separated with newline. In that way, only
the first SQLSTATE in the queue is visible using $h->state. One
has to parse $h->errstr to find out the rest.

=head2 BLOBS

BLOBs are supported via the SQL2 types B<S<LONG VARCHAR>> and B<S<LONG
VARBINARY>>. These are not fetched with SQL queries and the LongReadLen and
LongTruncOk attributes are not honored. Instead, Ovrimos
presents a HTTP interface for retrieving BLOBS. Every BLOB has a Uniform
Resource Identifier that can be found using the built-in B<URI> function.
This makes for easy retrieval of BLOBs in CGI scripts, where the URI can
be embedded in HTML constructs like this:

     my ($name,$uri1,$uri2);
     $sth->bind_columns(undef,\($name,$uri1,$uri2));

     $sth->prepare('select name,uri(blob1),uri(blob2) from blobtest');
     $sth->execute;

     while($sth->fetch) {

lib/DBD/Ovrimos.pm  view on Meta::CPAN

          ($host,$port,$file)=($1,$2,$3);
     } elsif($uri =~ m[^http://(.*)/(.*)]) {
          ($host,$file)=($1,$2);
     } else {
          die "horribly";
     }
     my $so=IO::Socket::INET->new( Proto=>"tcp", PeerAddr=>$host,
          PeerPort=>$port) or die "in pain";
     print $so "GET /$file HTTP/1.0\r\n\r\n";
     $so->flush() or die "in agony";

One can then proceed to read from $so after skipping the reply header.
If the MIME type is required, it can be found in the 'Content-type:'
attribute of the reply header.

Maybe in a later release this functionality will be included in the driver.

=head2 DRIVER-SPECIFIC ATTRIBUTES

There are some additional attributes that the user can query a $sth for:

=over 4

=item TYPE (also ovrimos_column_type)

Reference to an array of column types as per ODBC, plus the Ovrimos extended types.
TYPE is in capitals because the values returned conform to approved standards
(ODBC, X/Open).

=item ovrimos_column_precision

Reference to an array of column precisions. Has meaning only for vector types
(*CHAR, *BINARY) and NUMERIC/DECIMAL

=item ovrimos_column_scale

Reference to an array of column scales. Has meaning only for NUMERIC/DECIMAL.

=item ovrimos_execution_plan

It is a high-level explanation of the execution plan for the statement. The
format is highly version-dependent and not to be dependent upon, but a human
reader should be able to understand the access path for every range variable
used, the order of range variables, the indices used, which temporary tables
have been created et.c.

=item ovrimos_native_query

The query submitted, but in the form retained by the SQL Server. The SQL
Server applies transformations to the SQL source and disambiguates certain
constructs. The modified source can also be found in the execution plan (see
above).

=back

=head2 LOW-LEVEL LIBRARY

The entire low-level library that implements the Ovrimos protocol
is included. The DBI driver is based on this library, but one could conceivably
use the library on its own. It is the only way, for the time being, to use
scrollable cursors and bookmarks, since the DBI does not support them (yet?).
See the package C<DBD::Ovrimos::lowlevel> in C<Ovrimos.pm>. No documentation is
provided in this version about the low-level library.

=head1 COMFORMANCE

There is a particularity concerning transactions: see
L</CONNECTIONS, SESSIONS AND TRANSACTIONS>.

Cached statements don't exist. Not even the function prepare_cached exists.
Do not use it! You won't find any relevant attribute either.

=head1 KNOWN BUGS

There are no known bugs in the DBD Driver.

=head1 ACKNOWLEDGEMENTS

I would like to thank all the people on the DBI-DEV mailing list that
helped clear some misunderstandings.

=head1 SEE ALSO

DBI(3)

=head1 AUTHOR

     Dimitrios Souflis                  dsouflis@altera.gr,

=head1 COPYRIGHT

     (c) Altera Ltd, Greece             http://www.altera.gr

Permission is granted to use this software library according to the
GNU Library General Public License (see <http://www.gnu.org>).

=cut

require 5.003;
use strict;
use IO::Socket;

package DBD::Ovrimos::lowlevel;

#Declarations for low-level functions and constants
#Essentially a Perl port of the C low-level library

sub _plain_mesg($$);

sub sqlConnect($$$$);
sub sqlConnectOutcome();
sub sqlDisconnect($);
sub sqlAllocStmt($);
sub sqlFreeStmt($);

sub sqlSetConnIntOption($$$);
sub sqlGetConnIntOption($$);
sub sqlSetStmtIntOption($$$);
sub sqlGetStmtIntOption($$);
sub sqlSetRowsetSize($$);
sub sqlGetRowsetSize($);