• NAME
• DESCRIPTION
• USAGE
  • IBPerl
  • IBPerl::Connection
  • IBPerl::Transaction
  • IBPerl::Statement
• INSTALLATION
  • BUILDING AND INSTALLING ON UNIX AND WIN32
  • INSTALLING THE BINARY DISTRIBUTION ON WIN32
• CHANGE HISTORY
• FEATURES TO ADD
• LIMITATIONS
• TROUBLESHOOTING
• VERSION
• AUTHOR
• LICENSE

NAME

DESCRIPTION

USAGE

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

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

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

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

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):

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

FEATURES TO ADD

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

LIMITATIONS

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

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

AUTHOR

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.