DBD::Unify --  a Unify interface for Perl 5 using DBI.

This is the Database Driver for the Unify family of database products.

   Copyright (c) 1999-2003  H.Merijn Brand <h.m.brand@hccnet.nl>

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

See the ChangeLog file for a complete history

REQUIREMENTS

    It has been ported and tested on DataServer 6.3AB, 6.3BE, 8.1CC, 8.1CE,
    8.1DAB, 8.2AC, 8.2AD, and 8.2B, but this does not mean it might not work
    on U2000 databases or other DataServer releases.

    It uses DBI 1.35 and perl5.6.1, perl-5.8.0, or perl5.9.0, but might get
    it to work with DBI 0.93 or higher and perl 5.005 or higher. But then
    again, in that case you should consider an upgrade.

    If you plan to use DataServer 8.1 or higher database in Unicode encoding
    (UTF-8), use perl5.8.0 or up (or at least 5.7.3), which has full Unicode
    3.2 support.

    One user has reported success with perl 5.005_03 on SunOS 5.7 with
    gcc-2.7.2.2, DBI-1.30, DBD-Unify-0.24 with DataServer-7.2.

BUILDING, TESTING AND INSTALLING:

    This will only work if DBI is installed on a recent version of perl ;-)
    and you are working in a valid Unify environment. Makefile.PL will stop
    with a warning if you are not.

	   # perl Makefile.PL

    This step will ask you if you need networked databases. Probably you do
    not, which is the default answer. Choosing 'Yes' will include two more
    libraries that are broken in 8.1CC for HP-UX. Choosing 'No' will prefer
    U2000ul.a and S2000ul.a over U2000u.a and S2000u.a resulting in smaller
    binaries with local-only support.

    If you are using gcc, it might be needed to explicitly tell Unify to
    use it, because ucc defaults to cc (always):

	   # export UPPNAME=/usr/local/pa20_32/bin/gcc
	   # export UCCNAME=/usr/local/pa20_32/bin/gcc
	   # export ULDNAME=/usr/local/pa20_32/bin/gcc

    Another approach would be:

	   # ln -s /usr/local/pa20_32/bin/gcc cc
	   # export PATH=".:$PATH"

    Now you need to build the objects:

	   # make

    And if that succeeds, run the tests:

	   # make test

    Make test will use the current database and create a table "xx". If
    the test fails, table xx might still exist. If it already exists,
    it might get lost, so be aware!

    Make test will try to test all DBI features found in the DBI-1.19 docs
    even some that are not DBD dependent. Partly to show that it still works
    for DBD::Unify, and partly to find what features are still to be
    implemented. Features known to fail will issue an ok when ran with
    make test, but will show additional comments with a todo tag when run
    directly (e.g. 'perl t/11-dbi-dbh.t'). Note that the t/21-uni-regex test
    skips the test for 'SHLIKE' because this will cause core dumps. Advice:
    do *not* use SHLIKE, but use REGLIKE (which is quite easy to convert to
    from SHLIKE). All versions above A/SQL 8.2AC should have this problem
    solved. The test is enabled by default. If you have an older (crashing)
    version, disable this test by removing the hash in line

      #if ("This test is known to fail") { ok ("shlike will core", 1) } else

    If you happen to have a DataServer only product (no accell), make
    will probably complain about a missing ACCELL.a from Makefile.PL
    The workaround seems to be to remove the reference to ACCELL.a from
    Makefile.PL (reported by Ron Kuris)

	   # make install

    Will install the DBD::Unify extension into the default perl path's. If
    you plan to run different perl versions and/or different Unify versions
    alongside eachother, use the installu.pl script instead, which installs
    DBD::Unify in the Unify tree [ .../lib/perl ], and extend the environment
    variable $PERL5LIB with $UNIFY/perl

	  # make installu

    As with all modules: Patches are welcome.

RESTRICTIONS:

    This is a basic port for Unify. At the moment of writing, this DBD
    does not support all DBI elements, methods and attributes. I'll add
    these the moment I need them myself, or one of you will supply them
    as patches.

    DATE and TIME fields are not fully supported. The database interaction
    works, but there are some issues left to iron out in the user
    interface. We're woking on it. Suggestions welcome.

    TEXT and BINARY fields are not (yet) supported, though it is easy to
    change (code is supplied, but returns undef). Since we (me and my
    co-workers) do not use these types with our databases, it's up to you
    again to supply patches. Be sure to read what the DBI thinks about
    BLOB's before diving into this snake-pit.

    Other known restrictions:

    # Incomplete or out-of-date documentation, though I keep trying to
      keep in pace with what I change

    # Missing support for datatypes TEXT and BINARY in fetch and
      positional parameters (it's up to you to supply patches)

    # Some database attributes not (yet) implemented. (AutoCommit et all)

    # Statement attributes not (yet) fully implemented. Those needed for
      $sth->fetchrow_hashref () now work, but STORE_attrib () doesn't.
      Someone (probably me) will have to work through the list of
      documented database- and statement handle attributes.

      DBD::Unify tries to return the {TYPE} attribute in ANSI/ODBC DBI
      compliant coding, and has the original Unify field type available
      in the {uni_types} attribute. Fot AMOUNT and HUGE AMOUNT however,
      ANSI has no defined codes. These will be returned as SQL_FLOAT and
      SQL_DOUBLE, with the {SCALE} set to 2.

    And deficiencies/shortcommings that come with Unify:

    # Unify does not supply the "NULLABLE" indicator when describing
      fields

    # Unify does not return the desired length of non-character type
      fields, but the /maximum/ PRECISION for those fields

    # Unify only distributes static libraries, so the module might
      become rather big

    # At least until 8.2, Unify library pool does *NOT* allow more then
      one different database open at the same time from within the same
      process (even when the first database has correctly disconnected
      and closed) :-((

      This problem is known  with Unify and registered in their bug
      database as 'usb100963: disconnect'. Unify Sacramento has finally
      located the bug's source after yet again I reported this in
      bug report 22960. DBD-Unify 0.25 and up have a workaround for all
      versions up to and including 8.2AD. It's fixed in 8.2B.

TO DO:

    # Remove as many restrictions as possible ;-)

    # Add more tests

    # Implement all implementable handle attributes (->{CursorName} is
      probably the easiest to start with ;-)

    # Investigate and implement 3-arg versions of $sth->bind_param ()

    # Investigate and implement 2- and 3-arg version of $dbh->do ()

    # Investigate if looks_as_number () should be used in st_bind ().
      Comments are in where it should.

    # Investigate if LIKE and SHLIKE operators in positional parameters
      indeed do not work (I've seen that, but found no time yet to look
      into this more). Currently it cores on SHLIKE. See t/21-uni-regex.t

    # Try finding a way to open several different Unify databases at the
      same time for parallel (or at least sequential) processing.

    # Try finding ways to increase performance, squeezing every last
      nanosecond out of each handle ;-P

    # If you're into Unify internals, try finding out why describing
      positional parameters in where clauses (not in selected fields)
      causes a core dump on the field name. Look in dbdimp.ic in function
      dbd_prm_describe () for comment about OSF/1.

ACKNOWLEDGEMENTS

    Thanks to Tom Poage <poage@fireball.ucdmc.ucdavis.edu> for keeping
    the speed in the development and help in adding the missing features.

COPYRIGHT AND LICENSE

    Copyright (C) 1999-2003 H.Merijn Brand

    This library is free software; you can redistribute it and/or modify
    it under the same terms as Perl itself. 

As always, have the appropriate amount of fun!
