--- PApp-SQL/SQL.pm	2000/11/05 01:54:38	1.3
+++ PApp-SQL/SQL.pm	2001/01/07 02:53:53	1.6
@@ -26,7 +26,7 @@
 BEGIN {
    use base Exporter;
 
-   $VERSION = 0.1;
+   $VERSION = 0.11;
    @EXPORT = qw(
          sql_exec sql_fetch sql_fetchall sql_exists sql_insertid $sql_exec
    );
@@ -52,11 +52,18 @@
 flags from C<$flags>. These are just the same arguments as given to
 C<DBI->connect>.
 
-The database handle will be cached under the unique id C<$id>. If the same
-id is requested later, the cached handle will be checked (using ping), and
-the connection will be re-established if necessary (be sure to prefix your
-application or module name to the id to make it "more" unique. Things like
-__PACKAGE__ . __LINE__ work fine as well).
+The database handle will be cached under the unique id
+C<$id|$dsn|$user|$pass>. If the same id is requested later, the
+cached handle will be checked (using ping), and the connection will
+be re-established if necessary (be sure to prefix your application or
+module name to the id to make it "more" unique. Things like __PACKAGE__ .
+__LINE__ work fine as well).
+
+The reason C<$id> is necessary is that you might specify special connect
+arguments or special flags, or you might want to configure your $DBH
+differently than maybe other applications requesting the same database
+connection. If none of this is becessary for your application you can
+leave $id empty (i.e. "").
 
 If specified, C<$connect> is a callback (e.g. a coderef) that will be
 called each time a new connection is being established, with the new
@@ -75,13 +82,13 @@
    $id = "$id\0$dsn\0$user\0$pass";
    unless ($dbcache{$id} && $dbcache{$id}->ping) {
       #warn "connecting to ($dsn|$user|$pass|$flags)\n";#d#
-      # first, nuke our cache (sooory ;)
+      # first, nuke our statement cache (sooory ;)
       cachesize cachesize 0;
       # then connect anew
       $dbcache{$id} =
          eval { DBI->connect($dsn, $user, $pass, $flags) }
          || eval { DBI->connect($dsn, $user, $pass, $flags) }
-         || die "$DBI::errstr\n";
+         || die "unable to connect to database $dsn: $DBI::errstr\n";
       $connect->($dbcache{$id}) if $connect;
    }
    $dbcache{$id};