NAME
DBD::Fulcrum - Fulcrum SearchServer database driver for the DBI module
SYNOPSIS
use DBI;
use DBD::Fulcrum;
$ful_dbh = DBI->connect('dbi:Fulcrum:', $user, $passwd);
# use $ENV{FULSEARCH} for "instance", $user and $pass normally empty
# See the DBI module documentation for full detailsDESCRIPTION
DBD::Fulcrum is a Perl module which works with the DBI module to provide access to Fulcrum SearchServer data sources.
REQUIREMENTS SearchServer 2.x and beyond (lately tested only on 3.5) on IBM AIX 3.2.5, 4.1.5; Digital OSF/1 3.2c, Digital Unix 4.0x, Solaris 2.5.1, 2.6 Sparc, Solaris 2.4 (reported from user), Windows NT 4.0sp3, HP-UX 10.20, 11.00
You'll need the SearchServer C SDK to build this driver.ENVIRONMENT
As a Fulcrum SearchServer SDK application, this driver will use the environment to determine its operating specifications: FULSEARCH FULCREATE FULTEMP will generally be needed. For NT, use the DBI_DSN environment variable prevails. Please consult Fulcrum docs for more information or refer to test.pl for real-world use.
CAVEATS AND NOTES
General This driver implements basic functionality ONLY.
DBD::Fulcrum::ful_maxhitsinternalcolumns (driver-specific attribute) This attribute modifies allocation of result values buffers. It is driver-wide and is checked when an actual allocation is made. So, use it as soon as possible and try to use it throughout an application. Seting this attribute to a positive integer makes the driver allocate an additional 14 * fulcrum_MaximumHistInInternalColumns bytes for any char-based column. This is to allow for expansion of returned data length from internal columns when SHOW_MATCHES includes 'INTERNAL_COLUMNS' (i.e. SET SHOW_MATCHES 'TRUE' or SET SHOW_MATCHES 'INTERNAL_COLUMNS'). With these SHOW_MATCHES settings, SearchServer inserts match start/end markers in the column data. If this attribute is not set it defaults to 0; in which case the column will be truncated at its original length, so that part of the original data will not be returned. Truncation of data is not considered an error. To check if a truncation occurs you can use $h->state as per the example in test.pl.
$sth->{ful_last_row_id} (driver-specific read-only attribute) After an INSERT, UPDATE or DELETE statement, you can get the row id (FT_CID) of the last affected row via $sth->{ful_last_row_id}. If not after INSERT, UPDATE or DELETE the value of this attribute is unspecified. Code contributed by Loic Dachary (see acknoledgments section). Note that to use this attribute you must use prepare/execute instead of "do" since only prepare will return a $sth, and only execute will initialize the attribute.
Please be patient I have not a lot of time to dedicate to this driver nowadays. If you find a problem, and even better its solution, I will be very grateful if you let me know.
PLATFORM-SPECIFIC NOTES
Solaris Reports have been in of problems running DBD::Fulcrum under Solaris. The problem usually manifests as a cryptic "relocation error" in ld.so.1. You have this problem if a query succeeds using execsql but fails from a Perl program. The solution (hopefully) is to set LD_PRELOAD=$FULCRUM_HOME/lib/libftft.so in your environment. Thanks to Juha Makinen (FI) who found the solution and relayed it to me.
Digital Unix Due to the Fulcrum libraries being 32-bit, you'll have to build a static perl for DBD::Fulcrum to work on this platform. Since I'm not a MakeMaker geek, you'll need to follow this ugly hack: 1) perl Makefile.PL 2) hand-edit Makefile.aperl 3) change MAP_LINKCMD and change it to read $(CC) -taso plus whatever was there. 4) make -f Makefile.aperl (More or less). You'll get "unaligned access" console warnings due to 32-bitness of Fulcrum libraries. Suppress the warnings, there's no other way to deal with this.
Windows NT Starting with version 0.12 you should be able to build under Microsoft(tm) Windows(tm) NT(tm).
Environment variables have very little usefulness there, BUT you'll need FULCRUM_HOME set because Makefile.PL depends on it. Instead of using FULSEARCH, use the first parameter to connect in order to specify the ODBC data source (which roughly define a directory for SearchServer to use). test.pl uses the definition of the environment variable DBI_DSN, read on.
So in order to build and test:
*please note* I have successfully built and tested with SearchServer 3.5c under NT 4.0, Microsoft Visual C++ 5.0, perl 5.004_57 (of the development track) and DBI 0.92. I can't imagine what could happen in another situation. And, I most definitely lack the time to test. If you feel like it, try and let me know your configuration, I'll add it to this file.
First of all, have SearchServer installed and running. Test your SearchServer before trying to use DBI, please. Declare a new ODBC data source that you'll need to use for the after-build test. Let's name it "testdsn". Notice the FULCREATE, FULSEARCH and FULTEMP values? Instead of using the environment, you define them here. Copy to the directory you specified for FULCREATE and FULSEARCH (do yourself a favour and let them be the same), the exactly same files you see in build-dir.sh (THAT will not work, sorry) unless you don't see them in FULCRUM_HOME\fultext (that is, ignore the ftpdf.ini file if it's missing). You'll at mininum need fultext.ftc, and the *mess files. Use execsql, select the just declared data source "testdsn", and run the test.fte you find here. This will create the TEST table used by the tests (I'm losing count of tests here :-).
In your worthy Command Prompt, set the environment variable DBI_DSN: set DBI_DSN=testdsn
Rememeber to set FULCRUM_HOME to the base installation directory of the SearchServer C SDK.
Now you should be able to perl Makefile.PL, nmake and nmake install. At least it worked for me.
COLLATERALS
Fulcrum SearchServer: http://www.fulcrum.com
SEE ALSO
AUTHOR
DBD::Fulcrum by Davide Migliavacca.
ACKNOWLEDGEMENTS
All people working on DBI-related projects, and most specially Tim Bunce for creating DBI itself. Roberto Bianchettin <robertob@pisa.iol.it>, Juha Makinen, Peter Wyngaard for testing unstable releases and finding problems (and solutions!) Loic Dachary <loic@ceic.com> for adding support for retrienving FT_CID values after insert, update or delete. Ted Lemon, for continuing support to the dbi mailing lists.
COPYRIGHT
The DBD::Fulcrum module is Copyright (c) 1996,1997,1998 Davide Migliavacca and Inferentia, Milano ITALY
You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.