DBD::Sprite - Perl extension for DBI, providing database emmulation via flat files.

- NAME
- AUTHOR
- SYNOPSIS
- DESCRIPTION
- INSTALLATION
- GETTING STARTED:
- CREATING AND DROPPING TABLES
- INSERTING, FETCHING AND MODIFYING DATA
- JOINS
- ERROR HANDLING
- METADATA
- DRIVER PRIVATE METHODS
- RESTRICTIONS
- LATEST CHANGES
- TODO
- KNOWN BUGS
- SEE ALSO

# NAME

         DBD::Sprite - Perl extension for DBI, providing database emmulation via flat files.

# AUTHOR

        This module is Copyright (C) 2000, 2001, 2002, 2003, 2004 by

                    Jim Turner

            Email: turnerjw@wwol.com

        All rights reserved.

        You may distribute this module under the terms of either the GNU General
        Public License or the Artistic License, as specified in the Perl README
        file.

            DBD::Sprite is a derived work by Jim Turner from Sprite.pm, a module
            written and copyrighted (c) 1995-1998, by Shishir Gurdavaram
            (shishir@ora.com).

# SYNOPSIS

         use DBI;
         $dbh = DBI->connect("DBI:Sprite:spritedb",'user','password')
             or die "Cannot connect: " . $DBI::errstr;
         $sth = $dbh->prepare("CREATE TABLE a (id INTEGER, name CHAR(10))")
             or die "Cannot prepare: " . $dbh->errstr();
         $sth->execute() or die "Cannot execute: " . $sth->errstr();
         $sth->finish();
         $dbh->disconnect();

# DESCRIPTION

DBD::Sprite is a DBI extension module adding database emulation via flat-files or XML documents to Perl's database-independent database interface. Unlike other DBD::modules, DBD::Sprite does not require you to purchase or obtain a database. Every thing you need to prototype database-independent applications using Perl and DBI are included here. You will, however, probably wish to obtain a real database, such as "mysql", for your production and larger data needs. This is because emulating databases and SQL with flat text files gets very slow as the size of your "database" grows to a non-trivial size (a few thousand records or so per table).

DBD::Sprite is built upon an old Perl module called "Sprite", written by Shishir Gurdavaram. This code was used as a starting point. It was completly reworked and many new features were added, producing a module called "JSprite.pm" (Jim Turner's Sprite). This was then merged in to DBI::DBD to produce what you are installing now. (DBD::Sprite). JSprite.pm is included in this module as a separate file, and is required.

Many thanks go to Mr. Gurdavaram.

The main advantage of DBD::Sprite is the ability to develop and test prototype applications on personal machines (or other machines which do not have an Oracle licence or some other "mainstream" database) before releasing them on "production" machines which do have a "real" database. This can all be done with minimal or no changes to your Perl code.

Another advantage of DBD::Sprite is that you can use Perl's regular expressions in your SQL "WHERE-clauses" to search through your data (ie. "...where FIELD =~ /\S/..."). Maybe, someday, more "real" databases will include this feature too!

DBD::Sprite provides the ability to emulate basic database tables and SQL calls via flat-files. The primary use envisioned for this to permit website developers who can not afford to purchase an Oracle licence to prototype and develop Perl applications on their own equipment for later hosting at larger customer sites where Oracle is used. :-)

DBD::Sprite attempts to do things in as database-independent manner as possible, but where differences occurr, DBD::Sprite most closely emmulates Oracle, for example "sequences/autonumbering. DBD::Sprite uses tiny one-line text files called `"sequence files (.seq). and `"seq_file_name.NEXTVAL function to insert into autonumbered fields. The reason for this is that the Author works in an Oracle shop and wrote this module to allow himself to work on code on his PC, and machines which did not have Oracle on them, since obtaining Oracle licences was sometimes time-consuming.

DBD::Sprite is similar to DBD::CSV, but differs in the following ways:

- 1) It creates and works on true "databases" with user-ids and passwords.
- 2) The database author specifies the field delimiters, record delimiters, users, passwords, table file path, AND extension for each database.
- 3) Transactions (commits and rollbacks) are fully supported!
- 4) Autonumbering and user-defined functions are supported.
- 5) Sprite supports basic two-table JOINS!
- 6) You don't need any other modules or databases. (NO prerequisites except Perl 5 and the DBI module!
- 7) It is not necessary to call the "$dbh->quote()" method all the time in your sql.
- 8) NULL is handled as an empty string.
- 9) Users can "register" their own data-conversion functions for use in sql. See "fn_register" method below.
- 10) Oracle Sequences are supported!
- 11) Numeric, Char(#), and Varchar(#) datatypes are supported and completely sortable!
- 12) Separate files for large "BLOB" data now supported.
- 13) Your choice of Encryption is now supported.
- 14) Storage in XML-format now supported.

# INSTALLATION

        Installing this module (and the prerequisites from above) is quite
        simple. You just fetch the archive, extract it with

            gzip -cd DBD-Sprite-0.1000.tar.gz | tar xf -

        (this is for Unix users, Windows users would prefer WinZip or something
        similar) and then enter the following:

            cd DBD-Sprite-#.###
            perl Makefile.PL
            make
            make test

        If any tests fail, let me know. Otherwise go on with

            make install

        Note that you almost definitely need root or administrator permissions.
        If you don't have them, read the ExtUtils::MakeMaker man page for
        details on installing in your own directories. the ExtUtils::MakeMaker
        manpage.

            NOTE:  You will also need to copy "makesdb.pl" to /usr/local/bin or
            somewhere in your path.

## Windows installation

    		If installing in Windows, you must 1st install the DBI module,
    	create a DBD subdirectory in your Perl's path (run "perl -V" to find out
    	what this is), copy "Sprite.pm" to it, then copy the other files (
    	JSprite.pm, OraSpriteFns.pl, and to_date.pl to the same directory you
    	created the DBD subdirectory in.  Then copy the file makesdb.pl to the
    	directory perl itself is in.  These directories (in ActivePerl) are:
    	c:\perl\site\lib and c:\perl\bin respectively.  You do NOT need to use
    	"make" or "nmake" to build DBD::Sprite!

# GETTING STARTED:

            1) cd to where you wish to store your database.
            2) run makesdb.pl to create your database, ie.

                    Database name: mydb
                    Database user: me
                    User password: mypassword
                    Database path: .
                    Table file extension (default .stb):
                    Record delimiter (default \n):
                    Field delimiter (default ::):

                    This will create a new database text file (mydb.sdb) in the current
                    directory.  This ascii file contains the information you enterred
                    above.  To add additional user-spaces, simply rerun makesdb.pl with
                    "mydb" as your database name, and enter additional users (name,
                    password, path, extension, and delimiters).  For an example, after
                    running "make test", look at the file "test.sdb".

                    When connecting to a Sprite database, Sprite will look in the current
                    directory, then, if specified, the path in the SPRITE_HOME environment
                    variable.

                    The database name, user, and password are used in the "db->connect()"
                    method described below.  The "database path" is where your tables will
                    be created and reside.  Table files are ascii text files which will
                    have, by default, the extension ".stb" (Sprite table).  By default,
                    each record will be written to a single line (separated by \n --
                    Windows users should probably use "\r\n").  Each field datum will be
                    written without quotes separated by the "field delimiter (default:
                    double-colon).  The first line of the table file consists of the
                    a field name, an equal ("=") sign, an asterisk if it is a key field,
                    then the datatype and size.  This information is included for each
                    field and separated by the field separator.  For an example, after
                    running "make test", look at the file "testtable.stb".

            3) write your script to use DBI, ie:

                    #!/usr/bin/perl
                    use DBI;

                    $dbh = DBI->connect('DBI:Sprite:mydb','me','mypassword') ||
                                    die "Could not connect (".$DBI->err.':'.$DBI->errstr.")!";
                    ...
                    #CREATE A TABLE, INSERT SOME RECORDS, HAVE SOME FUN!

            4) get your application working.

            5) rehost your application on a "production" machine and change "Sprite"
            to a DBI driver for a "real" database!

# CREATING AND DROPPING TABLES

        You can create and drop tables with commands like the following:

            $dbh->do("CREATE TABLE $table (id INTEGER, name CHAR(64))");
            $dbh->do("DROP TABLE $table");

        A drop just removes the file without any warning.

        See the DBI(3) manpage for more details.

        Table names cannot be arbitrary, due to restrictions of the SQL syntax.
        I recommend that table names are valid SQL identifiers: The first
        character is alphabetic, followed by an arbitrary number of alphanumeric
        characters. If you want to use other files, the file names must start
        with '/', './' or '../' and they must not contain white space.

# INSERTING, FETCHING AND MODIFYING DATA

        The following examples insert some data in a table and fetch it back:
        First all data in the string:

            $dbh->do("INSERT INTO $table VALUES (1, 'foobar')");

        Note the use of the quote method for escaping the word 'foobar'. Any
        string must be escaped, even if it doesn't contain binary data.

        Next an example using parameters:

            $dbh->do("INSERT INTO $table VALUES (?, ?)", undef,
                     2, "It's a string!");

        To retrieve data, you can use the following:

            my($query) = "SELECT * FROM $table WHERE id > 1 ORDER BY id";
            my($sth) = $dbh->prepare($query);
            $sth->execute();
            while (my $row = $sth->fetchrow_hashref) {
                print("Found result row: id = ", $row->{'id'},
                      ", name = ", $row->{'name'});
            }
            $sth->finish();

        Again, column binding works: The same example again.

            my($query) = "SELECT * FROM $table WHERE id > 1 ORDER BY id";
            my($sth) = $dbh->prepare($query);
            $sth->execute();
            my($id, $name);
            $sth->bind_columns(undef, \$id, \$name);
            while ($sth->fetch) {
                print("Found result row: id = $id, name = $name\n");
            }
            $sth->finish();

        Of course you can even use input parameters. Here's the same example for
        the third time:

            my($query) = "SELECT * FROM $table WHERE id = ?";
            my($sth) = $dbh->prepare($query);
            $sth->bind_columns(undef, \$id, \$name);
            for (my($i) = 1;  $i <= 2;   $i++) {
                $sth->execute($id);
                if ($sth->fetch) {
                    print("Found result row: id = $id, name = $name\n");
                }
                $sth->finish();
            }

        See the DBI(3) manpage for details on these methods. See the
        SQL::Statement(3) manpage for details on the WHERE clause.

        Data rows are modified with the UPDATE statement:

            $dbh->do("UPDATE $table SET id = 3 WHERE id = 1");

        Likewise you use the DELETE statement for removing rows:

            $dbh->do("DELETE FROM $table WHERE id > 1");

fn_register

Method takes 2 arguments: Function name and optionally, a package name (default is ""main").

                    $dbh->fn_register ('myfn','mypackage');

    -or-

                    use JSprite;
                    JSprite::fn_register ('myfn',__PACKAGE__);

Then, you could say in sql:

            insert into mytable values (myfn(?))

    and bind some value to "?", which is passed to "myfn", and the return-value
    is inserted into the database.  You could also say (without binding):

            insert into mytable values (myfn('mystring'))

    -or (if the function takes a number)-

            select field1, field2 from mytable where field3 = myfn(123)

    I<Return Value>

            None

# JOINS

As of v. 0.50, basic two-table inner-joins are now supported. For example:

            select t1.field1, t2.field1, t1.field2 from table1 t1, table2 t2
            where t1.field1 = t2.field3 order by t2.field1 desc, t1.field1

This would return the three fields requested based on a set intersection of all records in table1 and table2 such that field1 of table1 matches field3 of table3. NOTE: This is the ONLY type of join currently supported! You can, however add additional selection criteria and or ordering arguments. You can also omit the where-clause and get a "set union" of the specified fields for all records of both tables.

# ERROR HANDLING

        In the above examples we have never cared about return codes. Of course,
        this cannot be recommended. Instead we should have written (for
        example):

            my($query) = "SELECT * FROM $table WHERE id = ?";
            my($sth) = $dbh->prepare($query)
                or die "prepare: " . $dbh->errstr();
            $sth->bind_columns(undef, \$id, \$name)
                or die "bind_columns: " . $dbh->errstr();
            for (my($i) = 1;  $i <= 2;   $i++) {
                $sth->execute($id)
                    or die "execute: " . $dbh->errstr();
                if ($sth->fetch) {
                    print("Found result row: id = $id, name = $name\n");
                }
            }
            $sth->finish($id)
                or die "finish: " . $dbh->errstr();

        Obviously this is tedious. Fortunately we have DBI's *RaiseError*
        attribute:

            $dbh->{'RaiseError'} = 1;
            $@ = '';
            eval {
                my($query) = "SELECT * FROM $table WHERE id = ?";
                my($sth) = $dbh->prepare($query);
                $sth->bind_columns(undef, \$id, \$name);
                for (my($i) = 1;  $i <= 2;   $i++) {
                    $sth->execute($id);
                    if ($sth->fetch) {
                        print("Found result row: id = $id, name = $name\n");
                    }
                }
                $sth->finish($id);
            };
            if ($@) { die "SQL database error: $@"; }

        This is not only shorter, it even works when using DBI methods within
        subroutines.

# METADATA

        The following attributes are handled by DBI itself and not by DBD::Sprite,
        thus they should all work as expected:  I have only used the last 3.

            Active
            ActiveKids
            CachedKids
            CompatMode             (Not used)
            InactiveDestroy
            Kids
            PrintError
            RaiseError
            Warn

        The following DBI attributes are handled by DBD::Sprite:

        AutoCommit
            Works

        ChopBlanks
            Should Work

        NUM_OF_FIELDS
            Valid after `$sth->execute'

        NUM_OF_PARAMS
            Valid after `$sth->prepare'

        NAME
            Valid after `$sth->execute'; undef for Non-Select statements.

        NULLABLE
            Not really working. Always returns a reference to an array of '1's, as
            DBD::Sprite always allows NULL (handled as an empty string).
            Valid after `$sth->execute'.

        PRECISION
                    Works

        SCALE
                    Works

        LongReadLen
                    Should work

        LongTruncOk
    		    		works, except setting to zero allows any length of data to be
    		    		read.

        These attributes and methods are not supported:

            bind_param_inout
            CursorName

        In addition to the DBI attributes, you can use the following dbh
        attributes.  These attributes are read-only after "connect".

        The following are Sprite-specific options which can be set when connecting.

        sprite_dbdir
                Path to tables for database.

        sprite_dbext
            File extension used on table files in the database.

        sprite_dbuser
            Current database user.

        sprite_field
            Field delimiter string in use for the database.
            Default specified in database configuration file (.sdb)

        sprite_read
            Field delimiter string in use for inputting the database.
            Default = sprite_field

        sprite_write
            Field delimiter string in use for outputting the database.
            Default = sprite_field

        sprite_xsl  (NEW)
            Allows specifying of a url to an xsl template to be written to xml
            documents (when using the "xml" option).  This makes it very easy to
            view your tables via M$ Internet Explorer browser!

            Example:  sprite_xsl => 'http://turnerville.wwol.com/jim/spritexml2html.xsl'

            Default is none.  Only applies if "sprite_field" is set to "xml"!

        sprite_dbfdelim - DEPRECIATED, now use "sprite_field"!
            Field delimiter string in use for the database.

        sprite_dbrdelim - DEPRECIATED, now use "sprite_record"!
            Record delimiter string in use for the database.

        sprite_CaseTableNames
            By default, table names are case-insensitive (as they are in Oracle),
            to make table names case-sensitive (as in MySql), so that one could
            have two separate tables such as "test" and "TEST", set this option
            to 1.

        sprite_CaseFieldNames  (NEW)
            By default, field names are case-insensitive (as they are in Oracle),
            to make field names case-sensitive (as in XML), so that one could
            have two separate fields such as "field1" and "Field1", set this option
            to 1.

        sprite_Crypt
            "0" by defalt.  Specifies that encryption is to be used when storing
            the data in the flat-file.  To use, download "Crypt::CBC", and one
            or more of "Crypt::DES", "Crypt::IDEA", or "Crypt::Blowfish".  You
            can specify using any of the following formats:

                sprite_Crypt => 'my key string'
                    Use Blowfish encryption.
                sprite_Crypt => 'DES;my key string'
                    Use DES encryption.
                sprite_Crypt => 'encrypt=CBC;IDEA;my key string'
                    Use IDEA encription, but read in table as unencrypted, then
                    write it out encrypted (great for encrypting previously
                    unencrypted tables).
                sprite_Crypt => 'decrypt=CBC;Blowfish;my key string'
                    use Blowfish encryption, but write out table unencrypted.
                    This allows one to fetch an encrypted table and write it back
                    out unencrypted.

        sprite_reclimit  (aka. sprite_sizelimit)
            Allows user to specify the maximum number of records to be returned
            by a single query.  Default is "0", which permits an unlimited number.

        sprite_StrictCharComp
            CHAR fields are always right-padded with spaces to fill out
            the field.  Old (pre 5.17) Sprite behaviour was to require the
            padding be included in literals used for testing equality in
            "where" clauses.    I discovered that Oracle and some other databases
            do not require this when testing DBIx-Recordset, so Sprite will
            automatically right-pad literals when testing for equality.
            To disable this and force the old behavior, set this option to 1.

        sprite_lock_file
            Specify alternate path/file to use for file-locking on os'es without
            a working "flock" (ie. M$ os'es).  Default is
            "/path/to/where/my/tables/are/Sprite.lck".  This is useful if the
            file-system your tables are on is read-only.

        sprite_lock_try
            Allows user-specification of the number of times to try to create
            lock-file on os'es without a working "flock" (ie. M$ os'es).  Default
            is 10.

        sprite_forcereplace
            Forces existing Sprite table file to be deleted and recreated in lieu
            of being overwritten.  This was necessary because the author uses a
            Samba filesystem which for some reason does not permit overwriting
            of files.

        SPRITE_HOME
            Environment variable specifying a path to search for Sprite
            databases (*.sdb) files.

# DRIVER PRIVATE METHODS

        DBI->data_sources()
            The `data_sources' method returns a list of "databases" (.sdb files)
            found in the current directory and, if specified, the path in
            the SPRITE_HOME environment variable.

        $dbh->tables()
            This method returns a list of table names specified in the current
            database.
            Example:

                my($dbh) = DBI->connect("DBI:Sprite:mydatabase",'me','mypswd');
                my(@list) = $dbh->func('tables');

        JSprite::fn_register ('myfn',__PACKAGE__);
            This method takes the name of a user-defined data-conversion function
            for use in SQL commands.  Your function can optionally take arguments,
            but should return a single number or string.  Unless your function
            is defined in package "main", you must also specify the package name
            or "__PACKAGE__" for the current package.  For an example, see the
            section "INSERTING, FETCHING AND MODIFYING DATA" above or (JSprite(3)).

# OTHER SUPPORTING UTILITIES

            makesdb.pl
                    This utility lets you build new Sprite databases and later add
                    additional user-spaces to them.  Simply cd to the directory where
                    you wish to create / modify a database, and run.  It prompts as
                    follows:

                    Database name: Enter a 1-word name for your database.
                    Database user: Enter a 1-word user-name.
                    User password: Enter a 1-word password for this user.
                    Database path: Enter a path (no trailing backslash) to store tables.
                    Table file extension (default .stb):
                    Record delimiter (default \n):
                    Field delimiter (default ::):

                    The last 6 prompts repeat until you do not enter another user-name
                    allowing you to set up multiple users in a single database.  Each
                    "user" can have it's own separate tables by specifying different
                    paths, file-extensions, password, and delimiters!  You can invoke
                    "makesdb.pl" on an existing database to add new users.  You can
                    edit it with vi to remove users, delete the 5 lines starting with
                    the path for that user.  The file is all text, except for the
                    password, which is encrypted for your protection!

# RESTRICTIONS

            Although DBD::Sprite supports the following datatypes:
                    NUMBER FLOAT DOUBLE INT INTEGER NUM CHAR VARCHAR VARCHAR2
                    DATE LONG BLOB MEMO and RAW, there are really only 4 basic datatypes
                    (NUMBER, CHAR, VARCHAR, and BLOB).  This is because Perl treates
                    everything as simple strings.  The first 6 are all treated as "numbers"
                    by Perl for sorting purposes and the rest as strings.  This is seen
                    when sorting, ie NUMERIC types sort as 1,5,10,40,200, whereas
                    STRING types sort these as 1,10,200,40,5.  CHAR fields are right-
                    padded with spaces when stored.  LONG-type fields are subject to
                    truncation by the "LongReadLen" attribute value.  BLOB-type
                    fields have their data stored on separate files created by Sprite.

            DBD::Sprite works with the tieDBI module, if "Sprite => 1" lines are added
            to the "%CAN_BIND" and "%CAN_BINDSELECT" hashes.  This should not be
            necessary, and I will investigate when I have time.

    	Data field names must NOT be the same as any of Perl's string operators
    	(eq lt le ge gt, etc) or boolean operators (and or not)!

# LATEST CHANGES

Revision history for Perl extension DBD::Sprite.

- 0.01 Fri Feb 25 13:00:55, 2000
  - original version; created by h2xs 1.18
- 0.02 Fri Mar 03, 2000
  - Fixed single-quote handling on bound parameters.
- 0.07 Fri Apr 14, 2000
  - Refixed test-14 failure (CHAR datatype). Also create and alter table commands should now work properly (save your table 1st! ;)
- 0.08 Wed May 03, 2000
  - Fix Windows glob problem for Perl2EXE
  - Added missing file "OraSpriteFns.pl" to build
- 0.09 Fri Jun 09, 2000
  - Fix bug in DELETE which occassionally caused infinite loop.
- 0.10 Wed Aug 16, 2000
  - Fix bug involving "like" and field values containing regex- special characters, ie. ".".
- 0.11 Thu Aug 31, 2000
  - Fix regex bug in Sprite.pm and add error-checking for SQL
  - commands wo/space after table-name, ie "update table-name\n...".
- 0.12 Tue Sep 05, 2000
  - Show the size fields are truncated to in "-519" error message.
- 0.13 Tue Oct 10, 2000
  - Fix CaseTableNames attribute to "sprite_CaseTableNames.
  - Minor docs fix.
- 0.14 Thu Oct 12, 2000
  - Added Oracle TO_DATE and CONCAT functions. Fixed bug now allowing more than 1 argument for functions, and minor bug which stripped wild-card chars from function results in "LIKE" expressions.
- 0.15 Thu Nov 02, 2000
  - Fix bug that caused question marks in bound parameter values to be treated as additional parameters.
- 0.16 Thu Dec 21, 2000
  - Fixed bug which would not allow lower-case versions of the "AND" and "OR" operators. Also made field-names used as right-values return the appropriate value they represent rather than just a literal string of the field name, ie. "update table set FIELD1 = FIELD2" should now work properly instead of setting FIELD1 to "FIELD2" in every record of "table".
- 0.17 Fri Mar 09, 2001
  - Fixed bug where types not returned for cursor after update, Fixed bug where table names not returned if space appeared after "table_name"?
  - Fixed bug in "makesdb.pl" -
  - was encrypting wrong argument.
- 0.18 Wed Mar 13, 2001
  - Changed comparisens of literal data with "CHAR" fields to first pad the literal with appropriate spaces so that eqality tests would pass (to work like Oracle and the way DBIx-Recordset expects). Also added new option "sprite_StrictCharComp" to force the old behavior.
  - Fixed bug that occasionally inserted a "0" instead of "" in numeric fields when inserting NULL. To get the proper "old" behavior, specify a default of zero for each numeric field, ie. "NUMFIELD=NUMBER=0" in the top line of your Sprite table files.
  - Added some code to check syntax of "where" clauses. (for DBIx- Recordset.
  - Fixed a couple of other small bugs that DBIx-Recordset tests found.
- 0.19 Wed Mar 21, 2001
  - Fixed problem seeing all Windows file-names due to case-insensitivity in Windows.
- 0.20 Fri Aug 15, 2001
  - Fixed bug involving autocommit on statements containing "select" in data. Caught by Simon Elliott, Thanks! Also fixed several other minor glitches.
  - Fixed bug forbidding sequence files in mixed-case directories unless CaseTableNames was set (CaseTableNames only applies to the file-name). Also added code to display "$@" and "$?" in the error details message on -511 errors (could not [over]write file).
- 0.21 Wed Sep 12, 2001
  - Fixed AutoCommit to actually work. Caught by Jojo Kamote Escubil, Thanks, Jojo! Also fixed another bug affecting quoted value strings containing question marks (Caught by me!)
- 0.22 Mon Sep 17, 2001
  - Removed regex optimization (s///o) which caused record and field separators to not work right when one opened a database, closed that database, then opened a second database with different record and or field separators. Caught by Larry Yudelson, Thanks!
- 0.23 Thu Oct 23, 2001
  - Added new regex feature to allow one to capture regex matches and update field values, ie: update MYTABLE set FIELD1 = '$1' where FIELD2 =~ '(\d+)' This will set FIELD1 to the 1st number found in FIELD2 in the same record. Up to 2 matches for each "where" expression containing "=~" or "!~" may be captured. $1 .. $n correspond to each set of unescaped parenthesis from left to right in the "where" clause.
  - Added TO_CHAR function for converting Perl "time" values to printable formats. Has most date and numeric functions in the two-argument form of the Oracle "TO_CHAR" function, which it is designed to emulate.
  - Added some optimization for mass-updates.
  - Added many other new Oracle functions (TO_NUMBER, USER, ABS, COS, EXP, FLOOR, MOD, POWER, ROUND, SIGN, SIN, TRUNC, CHR, INITCAP, LTRIM, REPLACE, RTRIM, TRANSLATE, ASCII, LENGTH, SYSDATE. All should now work when selected from "DUAL".
  - Selecting from "DUAL" should now work as expected.
- 0.26 Mon Oct 29, 2001
  - Fixed bug introduced in 0.24 where tests failed not finding "makesdb.pl".
  - Fixed test failure on Windows platforms (I think).
  - Added still more Oraclish functions (CEIL, EXP, INSTR, INSTRB, LAST_DAY, LPAD, NVL, RPAD, LAST_DAY, and SQRT. Fixed FLOOR. It should be noted that these functions do almost no error-checking.
  - Added date-handling capability to TRUNC.
  - Added "AUTONUMBER" datatype to allow autonumbering without sequences. This emulates the way M$-Access(ODBC) does things.
- 0.27 Fri Nov 15, 2001
- Eliminated "reserved" status of special characters \x02 .. \x06 and \n by now using single "reserved" string pattern: "\x02\^#jSpR1tE\x02", where "#" can be any digit 0..9. The purpose of this is to allow for temporarily protecting some strings while performing string searches and substitutions, ie. protecting commas within quoted literal values while splitting the encompassing string on commas as separators. \n has previously been "flattened" out into spaces in order to treat multiline queries as a single line. This is still done, but numerous regices were modified with the "s" option. Please report anything that might be broken by this new release!
- 0.30 Thu Jan 10
  - Fixed bug where specifying a negative number in a "where" clause as an unbound constant, returned all records and set the field in all records to that number (ouch!)
  - Fixed bug there double-backslashes in data inserted into a table were converted to a single backslash.
  - Added better "BLOB" support. BLOB/LONG/MEMO fields no longer have default length specified as 5000 and data should no longer be truncated.
  - ADDED ENCRYPTION OPTION! If the "Crypt::CBC", and "Crypt::IDEA", "Crypt::Blowfish" or "Crypt::DES" are available, you can connect specifying "sprite_Crypt => 'IDEA;any_key_string'" (use "DES" in lieu of "IDEA", if so inclined). To read in existing unencrypted tables and write them out encrypted, use "sprite_Crypt => 'encrypt=IDEA;your_key_string'". To read in encrypted databases and write them back unencrypted, use: "sprite_Crypt => 'decrypt=IDEA;your_key_string'". Note: Any method of encryption that Crypt::CBC supports may be used instead of IDEA or DES, if you have the module installed.
- 0.31 Thu Feb 22
  - Fixed bug which prevented one from using single-letter field names. (caught by me).
  - Fixed bug which caused SELECTs to sometimes fail with psuedo-columns and functions, ie. sequence.NEXTVAL (caught by me).
  - Fixed bug that caused extra "-528:Could not read/write BLOB file" errors to be displayed after other errors (caught by me).
  - Added code so "darwin" (new Mac-OS) would use unix "/" separator, was using WinDOwS separators ("\\") for directories (caught by Thabo).
  - Changed internal "lock_file" and "lock_try" to "sprite_lock_file" and "sprite_lock_try" respectively to allow user to override defaults. This was requested to permit Sprite databases to exist on read-only filesystems. This is only applicable to os'es originating from a huge corporation based in Redmond, VA. that don't support flock. See the README file for more notes about file locking!
  - Added code to check "Create" command to make sure tables/sequences actually get created or else report error (caught by Dave Thorn).
  - Added RAW datatype (psuedonym for VARCHAR), since in Perl, any valid ASCII character can be inserted into a string. NOTE: Oracle requires packing and unpacking to hex!
- 0.33 Fri May 10
  - Added code so "bsdos" (BSD/OS) would use unix "/" separator, was being treated as "dos" and using WinDOwS separators ("\\") for directories (caught by Sweth Chandramouli), Thanks!
  - Added ability to specify path and or extension to database names in the connect function (The default of ".sdb" and path ($ENV{SPRITE_HOME}/, "./", then $ENV{HOME}/ still apply). If database name contains a dot ("."), then the ".sdb" extension is not added. If the database name begins with a "/", then it is assumed to be an absolute path, otherwise, the dafault search-paths (described above) are applied.
- 0.34 Wed May 22
  - Added beta (incomplete) XML support! By specifying 'XML' as your record seperator, your tables will be stored in XML format instead of Sprite's usual delimited text format. Special XML characters (<, >, &, and --) are escaped to proper XML format, ie. <, etc. Use of this option requires the installation of the Perl module "XML::Simple". The reason this is beta is because I'm a newbe to XML and have not yet been able to get all binary data to work correctly, namely high-ascii characters. If you see what I am missing, please feel free to tell me and or send patches!
  - Fixed bug where single-quotes appearing in fields in UPDATE statements caused -517 errors.
  - Added ability to separately specify the field separator string for input vs output. Original Sprite supported this, but I always set them to be the same. By default they still are. This became useful to me when testing XML because I could specify the output field separator as 'XML' and the input one as whatever my existing table was, read it in and write it right back out as XML! The new options are: sprite_read, sprite_write, and sprite_field. The latter sets both to the same thing. sprite_record sets the record separator.
- 0.35 Thu May 30
  - Made global variable "CBC" an object variable fixing bug which caused problems when one used both an encrypted database and an unencrypted one in the same program (caught by me).
  - Added base-64 encoding to the new XML stuff and fixed up the encoding so that binary data should now work properly both in and out. Encoded fields now have a 'xml:encoding="base64"' attribute. Note: the "MIME::Base64" module is now a prerequisite if using XML.
  - Restored the "sprite_sizelimit" attribute (alias for the "sprite_reclimit" attribute) for backward compatability sake (I once used this in another program and DBD::LDAP uses "ldap_sizelimit" - I can't remember why).
- 0.36 Thu Jun 6
  - Removed -402 warning if SELECT finds no records so Sprite will work like other DBI databases. To test if SELECT returned records or not, test the return value of $sth->execute(). It will be the number of records returned or "0E0" if none, or undef if error!
  - Initialize "LongReadLen" attribute because regular DBI returns a default value of 80, but DBI::PurePerl returns undef (caused Perl warning in test).
  - Dropping table now returns "0E0" on success instead of 1 (as DBD::Oracle does).
- 0.37 Tue Jun 11
  - Fixed bug which prevented Sprite from loading tables with zero or one records.
  - Added new option: "sprite_xsl" to allow one to specify an xsl template url to be written into the xml document containing each table. Default is none. Only applies when using the "xml" option!
- 0.38 Never released.
  - Added "rows" attribute to "select" tag in XML-formatted tables.
- 0.39 Mon Jun 24
  - Added "rows" attribute to "select" tag in XML-formatted tables.
  - Added option "sprite_CaseFieldNames". Default is zero. If set, causes field names to be case-sensitive, allowing same table to have multiple fields with same name and different cases, ie. "field1", and "FIELD1". Traditional behavior was to convert all field names to upper-case as does Oracle(tm). This is similar to the "sprite_CaseTableNames" option for table names.
- 0.40 Tue Jul 9
  - Fixed restriction which prevented one from sorting on fields not in the selected result-set.
  - Added multiple ascending/descending selection to the sort "order by" clause. Previously, one could only specify ascending/descending once after the last field and all sorts would be in that direction. Now, one can use things like: "order by field1 desc, field2 asc, field3 desc" Please note that previous queries like "order by field1, field2 desc" WERE broken since both would sort in descending order! Now it works like Oracle where field1 will sort ascending and within that, field2 sorts descending.
- 0.41 Fri Aug 16
  - Fixed bug resulting from a missing "require" stmt that returned error when unencoding base64-encoded values in XML tables.
- 0.42 Thu Sep 5
  - Added support for DBIx::GeneratedKey. This ment adding code to save the current value of the last sequence or "AUTONUMBER" field incremented. The former are incremented by a call to "sequencename".NEXTVAL in a query, the latter are incremented by inserting NULL into a "AUTONUMBER" field in an "INSERT" query.
- 0.43 Thu Oct 24
  - Fixed problem with error-handling with DBI when DBI->connect() fails. Sprite now calls "warn" if "PrintError" is in effect and returns error code and string separated by a colon in "$_", if DBI->connect() fails. This is due to DBI::set_err() failing when no DBI handle yet created.
  - Fixed "create table" to now actually create an XML table when in an XML database (previously new tables were always created in text format by very old code that predated the XML option. It now calls "write_file()" via "commit()" as it should and as "alter table" does. Thanks to Roland Bauer for catching this embarrassing omission. I guess I had never actually created a "new" XML table, I had just used "sprite_write" and sql.pl to change my existing text tables to the new XML format.
  - Added code to "drop()" (drop table) function to make sure no dangling data is left in memory from the dropped table.
- 0.44 Tue Feb 11
  - Fixed 2 bugs related to the "sprite_CaseFieldNames" option. First, the option did not work with the "xml" option. Second, the option precedence was wrong -- Options specified in the connect() method should override any in the database (.sdb) file. This was not happening.
- 0.45 Fri Jun 27
  - Fixed Makefile.PL bug in Perl 5.8+ where make would fail with something like "Can't use string ("*.xsi") as a HASH ref...". Thanks to everyone who reported this.
- 0.46 Mon Sep 29
  - Fixed problem with Windows path separators (changed \\ to / for ActivePerl.
  - Added Oracle "Truncate" function.
- 0.47 Fri Nov 28 2003
  - Fixed "_set_fbav"-reported error when sorting field containing a "null" element.
- 0.50 Fri Mar 5
  - *JOINS ARE FINALY HERE!* One can now do very basic two-table inner equi-joins using Sprite. This is based on the pre-Oracle-9 syntax, which supports table name aliasing. The table-name or alias must be specified qualifying each fieldname (tablename.fieldname). See the docs for an example. Test & enjoy! ;)
  - Fixed small bug that prevented passing bind-arguments containing an escaped single-quote to a "like" expression in a where-clause.
- 0.51 Thu Apr 22
  - Added new DBI function "last_insert_id" to return the value of the last sequence number used. Refer to the DBI docs for arguments and how to use this function. The general format is: $number = $dB->func(undef, undef, 'tablename', 'fieldname', 'last_insert_id')
  - Added new option "sprite_nocase" to support case-insensitive where-clauses like LDAP. NOTE - only currently for "LIKE/NOT LIKE". If set to a true value, then case is ignored for expressions like: "where FIELD like 'abc%'". Default is false.
  - Fixed bug which prevented the argument to a "like" expression from working if it contained an escaped single-quote.
- 0.52 -not released.
- 0.53 Wed Sep 29
  - Fixed a bug affecting joins where selects without fields, ie. select from table.. failed.
  - Fixed another bug affecting joins when queries failed unless both CaseTableNames and CaseFieldNames were set if field names were lower-case.
- 0.54 Wed Nov 10
  - Fixed bug involving misinterpretation of the DBI::set_err() function which caused a null warning to sometimes be issued by perfectly successfull "Prepare" statements. Changed the 2nd argument to DBI::set_err() from zero to undef when clearing error status. Caught by Steven Bray and me.
  - Changed all (misspelled) references to the Oracle-ish function "CURVAL" to "CURRVAL". Caught by Steven Bray.
  - Fixed variable declaration buglet which "masked earlier declaration". Caught by Steven Bray. Thanks, Steven.
- 0.55 Fri Apr 29 2005
  - Fixed bug that caused single-quotes enclosed in variables bound to placeholders to fail and or seg-fault.
  - Fixed bug that caused single-quotes in in-line where-cluse values (those not bound using placeholders) to be converted to a pair of double-quotes, causing condition test to fail.
- 0.56 Sat May 14 2005
  - Fixed bug that prevented sorting from working and returning all records when doing a SELECT DISTINCT with ORDER BY on a single column.
- 0.57 Tue Jun 14 2006
  - Fixed bug involving reversal of the increment and start values of sequences in the "Create Sequence" command. Should work now, even though the variable names appear reverse in "NEXTVAL" code.
  - Added code to support DBI's "primary_key_info" query.
- 0.58 Thu Jul 20 2006
  - Fixed bug that prevented empty-strings (two quotes in succession) as arguments to functions (caught by me).
  - Fixed bug that had sequence values and increments reversed.
  - Added "primary_key_info()" DBI function.
- 0.59 Sat Oct 21 2006
  - Fixed bug that prevented last_insert_id() from working with AUTONUMBER fields.
  - Added MySQL-like "select fn()" capability. Previously, one had to use the Oracle-ish "select fn() from DUAL".
  - Fixed CaseTableNames bug.
  - Fixex problem that caused warning message when doing a $dB->disconnect() when using AutoCommit.
  - Added several numeric datatype names and mapped them to the existing numeric types.
  - Added 2 MySQL-ish functions: CURDATE, NOW (and now).

# TODO

Extensions of DBD::Sprite

        *       Additional Oracle-ish functions built-in as requested.

        *       Delete dangling blob-files when dropping a table.

# KNOWN BUGS

        *       The module is using flock() internally. However, this function is
                not available on platforms. Using flock() is disabled on MacOS
                and Windows 95: There's no locking at all (perhaps not so
                important on these operating systems, as they are for single
                users anyways).

        *       Unique-key violations on updates probably will not be caught
                if the argument is a function-call or a field-name.

        *       Sorting for joins:  In order to obtain correct sorting, all
                fields specifying desired sort order must be grouped together by
                table, ie. "order by t1.field1, t1.field2, t2.field1, t2.field2",
                which should work fine.  This is due to the fact that the records
                are merged together after data for each table is sorted
                independently.  This should not be an issue for 95+% of all sorts,
                If it is, patches are welcome and my very own "sort_elements()"
                module is available to you!  An example of a sort known NOT to
                work exactly right would be:
                "order by t1.field1, t2.field1, t1.field2".

# SEE ALSO

            JSprite(3), DBI(3), perl(1)