--- PApp-SQL/SQL.pm	2001/02/03 17:48:02	1.9
+++ PApp-SQL/SQL.pm	2001/02/05 14:05:08	1.10
@@ -5,28 +5,47 @@
 =head1 SYNOPSIS
 
  use PApp::SQL;
- # to be written
+
+ my $st = sql_exec $DBH, "select ... where a = ?", $a;
+
+ local $DBH = <database handle>;
+ my $st = sql_exec \my($bind_a, $bind_b), "select a,b ...";
+ my $st = sql_insertid
+             sql_exec "insert into ... values (?, ?)", $v1, $v2;
+ my $a = sql_fetch "select a from ...";
+ sql_fetch \my($a, $b), "select a,b ...";
+
+ sql_exists "name from table where name like 'a%'"
+    or die "a* required but not existent";
+
+ my $db = new PApp::SQL::Database "", "DBI:mysql:test", "user", "pass";
+ local $PApp::SQL::DBH = $db->checked_dbh; # does 'ping'
+
+ sql_exec $db->dbh, "select ...";
 
 =head1 DESCRIPTION
 
 This module provides you with easy-to-use functions to execute sql
 commands (using DBI). Despite being easy to use, they are also quite
-efficient and allow you to write faster programs in less lines of code.
-
-=over 4
+efficient and allow you to write faster programs in less lines of code. It
+should work with anything from perl-5.004_01 onwards, but I only support
+5.005+.
+
+If the descriptions here seem terse or if you always wanted to know
+what PApp is then have a look at the PApp module which uses this module
+extensively but also provides you with a lot more gimmicks to play around
+with to help you create cool applications ;)
 
 =cut
 
 package PApp::SQL;
 
-use DBI;
-
-#use PApp::Exception; # not yet used
+use DBI ();
 
 BEGIN {
-   use base Exporter;
+   use base qw(Exporter DynaLoader);
 
-   $VERSION = 0.11;
+   $VERSION = 0.12;
    @EXPORT = qw(
          sql_exec sql_fetch sql_fetchall sql_exists sql_insertid $sql_exec
    );
@@ -34,16 +53,46 @@
          connect_cached
    );
 
-   require XSLoader;
-   XSLoader::load PApp::SQL, $VERSION;
+   bootstrap PApp::SQL $VERSION;
 }
 
 our $sql_exec;  # last result of sql_exec's execute call
 our $DBH;       # the default database handle
-our $database;	# the current SQL::Database object, if applicable
+our $Database;	# the current SQL::Database object, if applicable
 
 our %dbcache;
 
+=head2 GLOBAL VARIABLES
+
+=over 4
+
+=item $sql_exec
+
+Since the C<sql_exec> family of functions return a statement handle there
+must eb another way to test the return value of the C<execute> call. This
+global variable contains the result of the most recent call to C<execute>
+done by this module.
+
+=item $PApp::SQL::DBH
+
+The default database handle used by this module if no C<$DBH> was
+specified as argument and no C<$DBH> is found in the current package. See
+C<sql_exec> for a discussion.
+
+=item $PApp::SQL::Database
+
+The current default C<PApp::SQL::Database>-object. Future versions might
+automatically fall back on this database and create database handles from
+it if neccessary. At the moment this is not used by this module but might
+be nice as a placeholder for the database object that corresponds to
+$PApp::SQL::DBH.
+
+=back
+
+=head2 FUNCTIONS
+
+=over 4
+
 =item $dbh = connect_cached $id, $dsn, $user, $pass, $flags, $connect
 
 (not exported by by default)
@@ -332,14 +381,6 @@
 
 1;
 
-=head1 BUGS
-
-As of this writing, sql_fetch and sql_fetchall are not very well tested
-(they were just re-written in C).
-
-sql_exists could be faster (it is written very ugly to not change the
-current package).
-
 =head1 SEE ALSO
 
 L<PApp>.