NAME

IBPerl.pm - module and extension for the InterBase client.


DESCRIPTION

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.


USAGE

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.


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.


IBPerl::Connection

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.


IBPerl::Transaction

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.


IBPerl::Statement

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.

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.


INSTALLATION


BUILDING AND INSTALLING ON UNIX AND WIN32

  1. Install InterBase
  2. Install Perl
  3. Unpack IBPerl kit
  4. perl Makefile.PL
  5. make
  6. make install


INSTALLING THE BINARY DISTRIBUTION ON WIN32

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.


CHANGE HISTORY

Beta version 0.7 (March, 1999):
Beta version 0.62 (November, 1998):
Beta version 0.61 (October, 1998):
Beta version 0.6 (September, 1998):
Beta version 0.5 (June, 1998):
Beta version 0.4 (March, 1998):
Beta version 0.2 (July 26, 1996)


FEATURES TO ADD


LIMITATIONS

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.


TROUBLESHOOTING

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.


VERSION

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/.


AUTHOR

IBPerl is copyright 1996-1999 by Bill Karwin. bkarwin@interbase.com.


LICENSE

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: