README for DBD::Sqlflex -- an Sqlflex interface for Perl 5 using DBI. Portions Copyright (c) 1994-96 Alligator Descartes Portions Copyright (c) 1996-98 Jonathan Leffler Portions Copyright (c) 1998-99 Infoflex, Inc. You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file. -- The following is a standard warning for all DBI and DBD::* software -- WARNING: THIS IS ALPHA SOFTWARE. IT IS POSSIBLY UNRELIABLE! --------------------------------------------------------------------------- PREREQUISITES If you do not have Perl version 5.003 or later, then build, test and install it before doing anything else! And please ensure that you compile it with whatever options are necessary to get __STDC__ defined. If you do not have DBI version 0.90 or later installed, then build, test and install it. To build DBD::Sqlflex, the C compiler must accept function prototypes. This is not a problem on any machine to which Sqlflex is currently ported (though the HP-UX compiler does not accept prototypes unless told to do so). You must have a version of Sqlflex-ESQL/C available to you. You should read the Sqlflex.License file for information about what you need. If you do not have ESQL/C and are not prepared to buy it, then please don't try to use DBD::Sqlflex -- it won't work. *** BEWARE *** You need to have a fully working Sqlflex environment before you try to build and test DBD::Sqlflex. Please use the sample software available from Infoflex, or their command-line SQL program, xsql to build a test database. ------------------> NOTE NOTE NOTE <----------------- The database must reside on a LOCAL (NOT NFS) disk. If you need remote access to a database, please see the Infoflex documentation for setting up a remote database server. Please ensure that you have $DBTEMP and $DBPATH set up in your environment. What is good for xsql is good for DBD::Sqlflex -- if you can't run xsql against a database, you'll never get DBD::Sqlflex working. BUILDING DBD::Sqlflex With the Sqlflex software from Infoflex, you should find instructions on setting the SQLDIR environment variable to use their esqlpp and sqlcc commands. Follow these instructions prior to building DBD::Sqlflex. Makefile.PL will attempt to connect to a database, by default the STORES database, which you should create using xsql. You do not need any tables created within the database. You may alternatively override the test database, using the DBD_SQLFLEX_DATABASE variable. Note that this variable only has significance when running the DBD::Sqlflex tests. It is not used by DBD::Sqlflex or Sqlflex itself. When Perl, DBI and ESQL/C are all installed do, and with the $SQLDIR variable set to point to your Sqlflex installation: perl Makefile.PL The script will attempt to work out what it needs to build the module. Then do: make This should complete without errors, and ideally without warnings either. If you get warnings, I'm interested to know what they are and how they could be fixed generically. If it fails horribly, see below. Do NOT hand edit the generated Makefile unless you are completely sure you understand the implications (and are willing to make those changes manually every time the Makefile is regenerated)! Always try to make changes by editing Makefile.PL, which is extensively annotated. You should also read the section on ExtUtils::MakeMaker in the 2nd Edition of 'Programming Perl'. You should never need to make any changes to the generated Makefile, nor to Makefile.PL. If you do *please* let me know so that I can try to make it automatic in a later release. *------------------------ NOT YET! -------------------------------- | | The "make test" facility documented here is currently unavailable | with the DBD::Sqlflex release. It should be fully implemented soon. | Sorry for any inconvenience. | *---------------------------------------------------------------------- | Then run: | | make test | | Note that testing DBD::Sqlflex does create some tables and databases. | The database is normally called 'dbd_ix_db', and the table names start | with 'dbd_ix_'. Some of the tables are permanent; most are temporary. | The tests are designed to work whether the tables and database are | present when the tests start or not; that means they get dropped. Do | not run the tests if you have precious tables or databases that begin | 'dbd_ix_'! | | It is a good idea to run: | | make test TEST_VERBOSE=1 | | You should inspect the results as not every test compares the actual | data returned with the data that should be returned (though many of | them do check the data which is returned). | | Additionally, for a really thorough scrutiny of DBD::Sqlflex, you need | to test with at least 3 different databases: one created MODE ANSI, one | created with a transaction log but not MODE ANSI, and one created | without any transaction logs at all. | | DBD_SQLFLEX_DATABASE=mode_ansi make test | DBD_SQLFLEX_DATABASE=logged make test | DBD_SQLFLEX_DATABASE=unlogged make test | *---------------------------------------------------------------------- Once you are satisfied that DBD::Sqlflex is working correctly, you should install it: make install If you ever need to remove it, possibly as a preamble to installing a new version, you should use the old version's makefile and run: make uninstall You can then install using the new version's makefile. It is important to use the correct (old or new) makefiles because the installed files may be different, and if some file is made obsolete by the new version (is not used by the new version), its makefile will not uninstall the obsolete file; over time and multiple versions, this could, eventually, lead to 'coronary thrombosis' on your disk drive -- or disk full. KNOWN PROBLEMS: None at this time. IF YOU HAVE PROBLEMS BUILDING DBD::SQLFLEX Firstly, check the Frequently Asked Questions, Known Bugs and any other pertinent documents at: http://www.arcana.co.uk/technologia/DBI If this does *not* resolve your problem, please post the details of your problem to dbi-users@fugue.com and CC them to me at help@infoflex.com There are 4 types of failures which you might encounter: A. A configuration failure (perl Makefile.PL does not work) B. A build failure (the Makefile was generated but there were problems during the build proper so that no test worked at all) C. A general test failure (although the build appeared OK, every single test fails, or almost all of them fail). D. A selective test failure (the build appeared OK and most of the tests pass, but a few (say 1 to 5) of them fail). Please classify your problem and follow the relevant steps below. Please include: 1. A log of a complete build: # Before doing anything, please either re-extract the source from the # compressed tar file you retrieved from CPAN into an empty directory # or make sure that the build area is really clean: [ -f Makefile ] && make realclean rm -f esql esqlvrsn.h # Send this output for all failure types (A, B, C, D) perl Makefile.PL # Send this output for failure types B, C, D. make # Send this output for failure types C, D # If the output is more than about 30 lines, then just send the first # 30 lines or so of the output -- anything more is unlikely to give any # extra information. make test # Send this output for failure types C, D # Then, taking the first test which fails (typically basic00.t) send # the output from: test.one t/basic00.t # Send this output for failure type D # If the failing tests are failing in distinctly different ways # (different error messages, or one is a core dump, or ...) then send # the test output for each of the different outputs, but do not send # more than 5 sets of test results unless requested to do so. test.one t/dbase.t If you use a Bourne or Korn Shell (or any work-alikes), you can also use the following command to get a lot more debug information, but don't send this unless asked to do so: PERL_DBI_DEBUG=2 test.one t/basic00.t Use this to verify that the problems you are reporting as different for failure type D really are different, but still don't send the output unless asked to do so. 2. A complete, sorted dump of your environment: env | sort 3. If you are not currently subscribed to the mailing list please subscribe via http://www.fugue.com/dbi. If you do not have WWW access, then send email to dbi-request@fugue.com. There are 3 mailing lists: dbi-announce@fugue.com dbi-users@fugue.com dbi-dev@fugue.com You should probably subscribe to dbi-users and probably do not need to subscribe to dbi-dev. IF YOU HAVE PROBLEMS USING DBD::SQLFLEX If your problem is with your own code and the DBD::Sqlflex tests all pass, then the initial message should give the version information (see point 3 above, plus the version of the Sqlflex database engine you are using), a description of the problem, a minimal test script, and the results of running the test script on your machine (along with an explanation of why the result is wrong -- it may not be obvious to me -- and what the correct result should be). The minimal test script should preferably: (1) Use the stores database, with empty username and password fields. If the test needs a particular type of database (eg with transactions) to demonstrate the problem, alternative convenient names are 'logged', 'unlogged' and 'mode_ansi'. (2) Use temporary tables rather than permanent ones. (3) Load just enough data to show the problem. (4) Test every statement using DBI functions for success. (5) Clearly indicate when it fails. (6) Clearly indicate when it passes. (7) It had better not use DBI->install_driver() without an extremely good reason, and I can't immediately think of a reason which would be good enough. If your test is failing with a core dump, the stack trace for it is useful if it lists function names -- it is not useful if it does not. Regards, Infoflex @(#)$Id: README $ --------------------------------------------------------------------------- NOTE: This document is derived from the DBD::Oracle README. Many of the points made in that will apply to DBD::Sqlflex too. Original document: (c) Tim Bunce Amendments 1: (c) Alligator Descartes Amendments 2: (c) Jonathan Leffler Amendments 3: (c) Jonathan Leffler Amendments 4: (c) Infoflex