view release on metacpan or  search on metacpan

blib/lib/Mac/DtfSQL.pm  view on Meta::CPAN

=head1 MEMORY REQUIREMENTS

 A minimum of 10MB / 11MB of RAM assigned to the MacPerl 5.2.0r4 / 5.6.1 application.
 A minimum of 11MB / 12MB of RAM assigned to the MPW Shell for running the MacPerl 5.2.0r4 / 5.6.1 tool.

This module requires quite a bit of RAM, as noted above. These values were determined by running the DBI test suite 
that comes with this module. They should be regarded as the absolute minimum. The MacPerl 5.6.1 application and tool 
will need at least 1MB more RAM than the MacPerl 5.2.0r4 application and tool. However, as your database grows, be 
prepared to assign more memory to MacPerl. If the memory assigned is less than the minimum, the MacPerl application 
or tool may crash during connection. Otherwise, the MacPerl application and the tool usually report an "out of memory!" 
or a "Can't connect as user X" error. However, if you get such an out of memory error, it's better to quit the 
corresponding application (and assign more RAM to it). If you try to run another script, you can crash your computer.

=head1 HOW TO GET dtF/SQL 2.01

Please note that dtF/SQL 2.01 is freely available only for non-commercial use. See sLAB's License Agreement 
for details.

Downloading dtF/SQL version 2.01 requires registration. Visit sLAB's web site at http://www.slab.de/us/home/, 
go to the download section and register yourself (your name and email-address are sufficient). Within a few 
minutes, you will get a user name and password via email. Now, visit their web site again, go straight to the 
download section, choose 'Non-public Download', wait for the file list to come and choose

 dtF/SQL 2.01 for MacOS
 	dtFmac-201.sit	Size: 3395 kByte	Date: 09/14/2000 .
	
Then choose "License agreement for non-commercial users", read and agree to the upcoming License Agreement 
to actually download the file.

There are older versions of dtF/SQL available, and some don't require registration. However, this module
was written for version 2.01 and B<will not work with older versions of dtF/SQL>. With the 2.0 release of
the dtF/SQL database engine, its API has been revamped.

Within the downloaded package, you will find the shared library (PPC only) needed for this module, as well as 
the static PPC and 68K libraries, the documentation, a tool for administrating a dtF/SQL database (PPC only), 
the dtF/SQL database server (PPC only), sample source code (in C and C++) and other useful stuff. Please note 
that this module is useless without the dtF/SQL shared library, as you might guess.


=head1 dtF/SQL 2.01 (KNOWN) LIMITATIONS

The current implementation of the dtF/SQL database engine is limited to one connection at a time, as 
documented. But it also has some limitations (bugs?), beyond from what is documented or obvious (see 
the dtF/SQL SPECIFICATION section). The following restrictions were detected while working with 
dtF/SQL. 

* The dtF/SQL database engine could only be used in single-user mode (i.e. locally), because the dtF/SQL 
Database-Server, needed for a network connection, doesn't work as expected (at least on a single Mac, 
running Mac OS 8.6 and Open Transport v2.0.3, acting both as a client and server; I haven't tested it in 
a network).

* There is a limitation (bug?) concerning foreign keys consisting of multiple columns. Basically, a foreign 
key is a column or group of columns within a (dependant) table that references a primary key in some other 
(parent) table. Foreign keys provide a way to enforce the referential integrity of a database. The check for 
referential integrity works fine in dtF/SQL as long as the foreign key consists of a single column: A record 
will *not* be accepted if the foreign key doesn't exist (as primary key) in the parent table; you will 
get an error message. But for multi-column foreign keys dtF/SQL cannot check the referential integrity. A 
record will be accepted even if the foreign key doesn't exist (as primary key) in the parent table. Don't rely 
on this feature.

* The dtF/SQL cascaded delete feature (ON DELETE DELETE or ON DELETE CASCADE action-constraint/trigger), 
which helps to preserve the referential integrity of a database, doesn't work properly. Let's say, table 
A is the parent table with primary key [A.id]. Table B is the dependent table, i.e. contains a foreign key 
[B.id] which is the primary key of table A. The primary key of table B is a multi-column key [B.id, B.id2], 
i.e. the foreign key [B.id] of table B is part of its primary key. Table B was created with the cascaded 
delete action-constraint set for this foreign key [B.id]. If you now delete a record in table A, dtF/SQL will, 
as you expect, delete the corresponding records (where A.id = B.id) in table B too. *But*, if you try to 
insert one of the just deleted records into table B again (same multi-column primary key), you will get a 
referential integrity error, saying "UNIQUE value exists for column 'B.id' ", i.e. dtF/SQL hasn't realized, 
that the primary key is free for use again. This doesn't happen if you delete the corresponding records in 
table B by hand, i.e. with a DELETE statement. Because this cascaded delete behavior is not what you might 
expect, don't rely on this feature.

* dtF/SQL is also a bit weak on documentation. It contains some errors (e.g. wrong cross-references in 
the C/C++/Java Reference manual), but generally it's not that bad that one can't work with it. All in 
all, it doesn't go into deep detail and is very brief on some relevant topics (auto-commit behavior,  
for example). 

There may be other limitations that I haven't detected yet -- comments welcome. 


=head1 API CONSTANTS

There are various constants that are defined in the API.


=head2 MISCELLANEOUS

    DTF_FALSE
    DTF_TRUE
    NULL
    DTFHANDLE_NULL
    DTF_INVALID_COUNT

=head2 DIMENSION CONSTANTS

    DTF_MAX_NAME          #  max length for column and table names (incl. \0)
    DTF_MAX_USERPASS      #  max length of user name or password (incl. \0)

    #  min and max database file size, in KBytes
    DTF_MIN_MAXSIZE       #  ...KB == 2MB
    DTF_MAX_MAXSIZE       #  ...KB == 2GB

    DTF_MAX_FIELDLENGTH   # max non-blob fieldlength

=head2 ERROR CODE CONSTANTS

    DTF_ERR_OK                 DTF_ERR_BUFFER_FULL 
    DTF_ERR_BAD                DTF_ERR_EXISTS
    DTF_ERR_FATAL              DTF_ERR_DOES_NOT_EXIST
    DTF_ERR_OTHER              DTF_ERR_SERVER
    DTF_ERR_BAD_ID             DTF_ERR_CLIENT
    DTF_ERR_LOCK               DTF_ERR_SYNC
    DTF_ERR_NO_SEG             DTF_ERR_NET
    DTF_ERR_NO_PAGE            DTF_ERR_STOPPED
    DTF_ERR_NO_BUFFER          DTF_ERR_PASSWORD
    DTF_ERR_IO                 DTF_ERR_ACCESS
    DTF_ERR_FULL               DTF_ERR_DIV_BY_ZERO
    DTF_ERR_NO_FILE            DTF_ERR_CONVERSION
    DTF_ERR_RANGE              DTF_ERR_RESOURCE
    DTF_ERR_FILE               DTF_ERR_TM_FULL
    DTF_ERR_MEMORY             DTF_ERR_VERSION
    DTF_ERR_INTEGRITY          DTF_ERR_LOG_READY
    DTF_ERR_NO_SCAN            DTF_ERR_SEQUENCE
    DTF_ERR_NO_MORE_RECORDS    DTF_ERR_USER

=head2 RESULT TYPE OF CURSOR

    DTF_RT_SEQUENTIAL
    DTF_RT_RANDOM