IBPerl.pm - module and extension for the InterBase client.
Provides an object-oriented interface to Dynamic SQL programming of
InterBase, an enterprise relational database server that runs on a wide
range of operating systems.
use IBPerl;
See section below for description and some examples on the methods and
members of IBPerl classes. See scripts provided with the IBPerl
distribution for coding examples.
The host on which you run Perl scripts that use IBPerl must have InterBase
installed, to get access to the shared libraries (DLLs) for the InterBase
software.
IBPerl was designed and developed with Perl 5.004. It is recommended to use
this version or higher of Perl to run IBPerl.
There are no methods within the IBPerl class itself. It is merely a parent
class for the three classes below.
- $IBPerl::VERSION
-
String scalar containing the version of the IBPerl module.
- new IBPerl::Connection( { Server, Path, User, Password, Role, Protocol, Cache, Charset } )
-
Return a Connection object for a specified InterBase database. The
parameter is a hash list with the following keys, which you can supply in
any order:
Server is the hostname of the database server. This need not be fully-qualified
with domain, as long as the client can resolve the simple hostname. Using
an IP address in place of the hostname is not supported by InterBase.
Path is the absolute pathname of the location of the database on the server. On
NT and NetWare this path may include the drive or volume name, followed by
a colon. E.g. 'D:/DATA/CORP/SALES.GDB'.
Path is mandatory.
User and Password are authentication information for the connection to the database. This
user and password must exist in the security database on the database
server. These are mandatory, but they default to the ISC_USER and
ISC_PASSWORD environment variables, if set.
Role is an optional parameter to specify a SQL role name (supported only in
InterBase version 5.0 and later).
Protocol is optional and defaults to 'TCP/IP'. You can also specify 'NetBEUI'
(InterBase for NT only) or 'IPX/SPX' (InterBase NLM for NetWare only).
Cache is the number of database pages to allocate for the server-side cache. This
parameter is optional.
Charset is default character set for a database. Charset is the quoted name of a
character set. If omitted, character set defaults to NONE. This parameter
is optional.
If new could not construct a Connection object, $db->{Handle} is set to -1 and
IBPerl returns an error message in $db->{Error}.
- create IBPerl::Connection( { Server, Path, User, Password, Protocol, Cache, Page_Size, Charset } )
-
Like new, create returns a Connection object for an InterBase database. The difference is
that create creates a brand new database with the name specified.
The one difference between new and create is the Page_Size
parameter. This can be one of 1024, 2048, 4096 or 8192. Other values round
down to one of those values.
Page_size determines the size, in bytes, of pages in the database that you create
with this method.
If create could not create a database, or could not construct a Connection object, it
returns an error message in $db->{Error}.
WARNING: create silently destroys a database if one already exists, then creates a new one
in its place.
- $db->disconnect
-
Virtual method to release a connection to a database. This is done by
default in the destructor for the Connection class object. Returns 0 on
success, -1 on failure.
- $db->{Error}
-
Errors that occur during connection, creation or disconnection are recorded
in this class member.
- new IBPerl::Transaction( { Database } )
-
Return a Transaction object, started against the specified database
Connection object. The parameter is a hash list. Only Database
is recognized in this version of IBPerl; this should be a reference to an
IBPerl::Connection object.
new sets $trans->{Handle} to -1 and returns an error message in
$trans->{Error} if it could not construct a Transaction object.
This Transaction is hardcoded to the default InterBase options: read/write,
wait, snapshot. A future version of IBPerl will implement methods that
surface all the InterBase transaction options.
- $trans->commit
-
Virtual method to commit the work done in the context of a Transaction
object. Changes made during a Transaction are not visible to other users
until the Transaction has been committed. This is done by default in the
destructor method for the Transaction class object.
Returns 0 on success, -1 on failure.
- $trans->rollback
-
Virtual method to abort the work done in the context of a Transaction
object.
Returns 0 on success, -1 on failure.
- $trans->{Error}
-
Errors that occur during starting, committing or rolling back of a
transaction are recorded in this class member.
- new IBPerl::Statement( { Transaction, Stmt, Separator, DateFormat } )
-
Static method to create an instance of a Statement object. Returns a
Statement object reference, started in the context of the
Transaction. The arguments are a hash list.
The Stmt property is the SQL statement that the user submits.
The optional property Separator that is used when the results of a query are joined together into a string.
The optional DateFormat property is the format string for
strftime() to format dates; if you don't specify a format, IBPerl uses the default
date format for the locale (``%c'' to strftime()).
The special
value of 'tm' for DateFormat results in IBPerl returning each date value as a reference to a list, of
the same structure as the list returned by localtime.
This method sets $stmt->{Handle} to -1 and returns an error in
$stmt->{Error} if it could not initialize a Statement object.
- $stmt->execute(@list)
-
Virtual method to run the SQL statement, if it was not a
SELECT
.
Use the optional list argument to provide parameter values for a prepared, parameterized query.
There are no named parameters; you must supply the values in the order the
parameters occur in the original SQL statement.
Example:
$stmt = new IBPerl::Statement(Stmt=>'INSERT INTO MYTABLE VALUES ( ? )');
$stmt->execute( (47) );
See examples/test_param_insert.pl for a more complete example.
The user must commit changes with the commit method or abort with the rollback method.
The execute method returns 0 on success, -1 on failure.
- $stmt->open(@list)
-
Virtual method to run the SQL statement, if it was a
SELECT
or an EXECUTE PROCEDURE
. You should retrieve data with fetch.
Use the optional list argument to provide parameter values for a prepared,
parameterized query.
Example:
$stmt = new IBPerl::Statement(Stmt=>'SELECT * FROM MYTABLE WHERE QTY = ? ');
$stmt->open( (47) );
Returns 0 on success, -1 on failure.
- $stmt->fetch(ref)
-
Virtual method to retrieve one successive row of data from the current
SELECT
statement. Returns 0 for a successful fetch, 100 when the all rows have
been fetchhed, and -1 if there is an error. The ref parameter is a Perl reference to a scalar, list, or hash of the row of
data.
-
If ref references a scalar, the result is a Perl join of the columns, using
$stmt-
>{Sep}
as the delimiter between data.
Example:
$stmt = new IBPerl::Statement(Stmt=>'SELECT * FROM MYTABLE');
$stmt->fetch(\$record);
print "$record\n";
-
If ref references a list, the result starts at 0 and is in the order specified in
the select-list of the query.
Example:
$stmt = new IBPerl::Statement(Stmt=>'SELECT * FROM MYTABLE');
$stmt->fetch(\@record);
print "$record[0]\n";
-
If ref references a hashed list, it is keyed by the names of the columns in the
select-list of the query.
Example:
$stmt = new IBPerl::Statement(Stmt=>'SELECT * FROM MYTABLE');
$stmt->fetch(\%record);
print "$record{QTY}\n";
See examples/test_select.pl for a more complete example.
The fetch method returns 0 on success, -1 on failure, and 100 when the result set is
exhausted.
- $stmt->update(%hash)
-
Virtual method to perform an update of the record most recently fetched by
a cursor. The hash array argument is a set of key-value pairs, where the
hash keys are names of columns in the record, and the hash values are the
new values that you are assigning to the corresponding column.
Example:
$stmt = new IBPerl::Statement(Stmt=>'SELECT * FROM MYTABLE FOR UPDATE');
$stmt->fetch;
$stmt->update( QTY => 95 );
See examples/test_pos_upd.pl for a more complete example.
NOTE: currently only single-table queries can be updated in this manner.
- $stmt->delete
-
Virtual method to delete the record most recently fetched by a cursor.
Example:
$stmt = new IBPerl::Statement(Stmt=>'SELECT * FROM MYTABLE FOR UPDATE');
$stmt->fetch();
$stmt->delete();
See examples/test_pos_del.pl for a more complete example.
NOTE: currently only single-table queries can be updated in this manner.
- $stmt->close
-
Virtual method to close and free the statement. This is done by default in
the destructor for the Statement class object.
Returns 0 on success, -1 on failure.
- $stmt->{Stmt}
-
Class member containing the current SQL statement.
- $stmt->{Stmt_type}
-
Class member that contains the type of the statement. Currently, only
SELECT
, INSERT
, UPDATE
, DELETE
and EXEC_PROCEDURE
with no return parameters are supported.
- @$stmt->{Values}
-
Class member that provides access to the array created during a fetch.
- @$stmt->{Columns}
-
Class member that provides access to the array of column names created
during a fetch.
- @$stmt->{Nulls}
-
Class member that provides access to the array of the null/non-null state
of columns, created during a fetch.
- @$stmt->{Lengths}
-
Class member that provides access to the array of the data length of
columns, created during a fetch.
- $stmt->{Error}
-
Errors that occur during creation or execution of a statement are recorded
in this class member.
- Install InterBase
- Install Perl
- Unpack IBPerl kit
- perl Makefile.PL
- make
- make install
I have included a precompiled binary distribution of IBPerl for Win32. This
is to accomodate Win32 Perl users who might not have a C compiler. To
install the binary distribution, use the Install script.
Simply run perl Install while your current working directory is in the IBPerl distribution. This
script automatically finds the binary IBPerl files and copies them into the
location where your main Perl distribution is located.
- Beta version 0.7 (March, 1999):
-
-
Add special DateFormat value of 'tm', to return date as list a la
localtime()
-
Implement simple Install script to install binary distribution
-
Improved Makefile.PL rules for building on Win32
-
Updated pod file with more examples
-
Fixed bug in import of text Blobs
-
Fixed several internal bugs in checking for valid handles
-
Fixed bug in determining data length of VARCHAR input data
- Beta version 0.62 (November, 1998):
-
-
Fixed bug in
IB_free_DB()
that crashed perl on Linux
- Beta version 0.61 (October, 1998):
-
-
Fixed bug in
IB_destroy_ST()
that crashed perl on VARCHARs
- Beta version 0.6 (September, 1998):
-
-
Add parameterized queries
-
Add Blob insert/update
-
Add positioned update and delete methods
-
Add connection property for SQL role
-
Add connection property for character set
-
Add DateFormat property for statements
-
Fix bug in Page_size property of create
-
Fix bugs related to memory allocation
-
Fix bug in NUMERIC precision
- Beta version 0.5 (June, 1998):
-
-
Add support for Data Definition statements; NOTE that they are not autocommited like they are in isql
-
More error reporting improvements and bug fixes
-
Bug fixes to support concurrent statements
-
Add linking rule for Win32 to Makefile.PL
-
Add linking rule for Linux to Makefile.PL
- Beta version 0.4 (March, 1998):
-
-
Support for local database connections.
-
Fetch Blob data.
-
Multiple concurrent statements with cursors.
-
Multiple concurrent transactions.
-
Multiple concurrent database connections.
-
Proper error message handling when connection fails.
-
More robust and sophisticated error handling.
-
Fetch computed columns into a hash array.
- Beta version 0.2 (July 26, 1996)
-
-
Initial release, as a demo of InterBase API programming for the Borland
Developer's Conference in Anaheim, CA.
-
Support stored procedures that return values (this work is under
construction, but is ifdef'd out for now)
-
Testing for compatibility with mod_perl and embperl.
-
Fetch and store InterBase arrays.
-
Implement a tied hash to fetch/store queries.
-
Support for full set of InterBase transaction options.
-
Create multi-file databases.
-
Database administration operations: backup, sweep, validate, manipulating
users/passwords.
-
Wrapper module to provide compatibility with Tim Bunce's DBD package.
-
Table_info()
and tables()
methods
-
Types()
method
-
Auto-start-transaction within
prepare()
method (though I
generally eschew autocommit statements)
-
Wrapper module to provide compatibility with Buzz Moschetti's interperl
package.
IBPerl requires that the Perl interpreter and the InterBase client product
be installed on the host where you run scripts. IBPerl supports only
platforms supported by the InterBase client product.
I tested IBPerl on Microsoft Windows NT 4.0 using Borland C++ 5.02 to
compile the XS, and Gurusamy Sarathy's binary distribution of Perl 5.004
for Win32. Compatibility with ActiveState Perl is not guaranteed.
I have no plans to compile IBPerl on the Win16 platform, or to ever use the
Win16 platform for any purpose if I can avoid it.
IBPerl provides an interface only to InterBase databases, not to any other
brand of database.
IBPerl is known not to work when accessing servers running InterBase 3.2,
and it is likely to have problems accessing servers running InterBase 3.3.
When running with the free InterBase 4.0 on Linux, there is a known
incompatibility between the InterBase software and the GNU glibc used in
more current Linux distributions. If you compile IBPerl with -lgds (the pipe library) instead of -lgdslib (the shared library) this problem
seems to go away. InterBase 5.1.1 does not have this confict with GNU
glibc.
You might receive error warnings like ``Bad free()
ignored...'' These are harmless, but annoying. Prevent the error by
recompiling your perl executable without Perl's malloc library; use your
system malloc. If this is not possible to recompile perl, suppress the
warnings by setting the environment variable PERL_BADFREE to 0 before running your IBPerl scripts.
On Win32, you can use Gurusamy Sarathy's binary distribution of perl for
Win32. I know this to work correctly with IBPerl. If you use the
ActiveState Perl distribution, you must upgrade to version 507. Version 507
claims to work correctly with Perl extensions.
The current release of IBPerl as of the time of this writing is Beta
release version 0.7, January, 1999. You can find updates on InterBase's web
site, http://www.interbase.com/.
IBPerl is copyright 1996-1999 by Bill Karwin. bkarwin@interbase.com.
IBPerl is free, as-is software. You can download and use IBPerl according
to the Artistic License (see the Perl documentation) or the GNU Public
License.
Additionally: you have license to use, copy, and redistribute IBPerl as
part of a commercial or non-commercial Application provided that:
-
You agree that authorship and publication of the IBPerl module does not
imply a commitment or guarantee to support the software on the part of Bill
Karwin, InterBase Software Corp., INPRISE Corp. or any of the employees of
those entities.
-
You demand or accept no compensation for your Application other than that
compensation which you demand or accept for the Application as it exists
without the IBPerl module.
-
You agree to indemnify, hold harmless, and defend Bill Karwin, InterBase
Software Corp., and INPRISE Corp. from and against any claims or lawsuits,
including attorney's fees, that arise or result from the use or
distribution of your Application.
-
You grant third parties the rights to redistribute the IBPerl module, which
they acquire from your Application, only pursuant to terms no less
restrictive as those contained in this Agreement.