.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Firebird 3pm"
.TH Firebird 3pm "2014-03-19" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBD::Firebird \- DBI driver for Firebird RDBMS server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use DBI;
\&
\&  $dbh = DBI\->connect("dbi:Firebird:db=$dbname", $user, $password);
\&
\&  # See the DBI module documentation for full details
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
DBD::Firebird is a Perl module which works with the \s-1DBI\s0 module to provide
access to Firebird databases.
.SH "MODULE DOCUMENTATION"
.IX Header "MODULE DOCUMENTATION"
This documentation describes driver specific behavior and restrictions. 
It is not supposed to be used as the only reference for the user. In any 
case consult the \s-1DBI\s0 documentation first !
.SH "THE DBI CLASS"
.IX Header "THE DBI CLASS"
.SS "\s-1DBI\s0 Class Methods"
.IX Subsection "DBI Class Methods"
.IP "\fBconnect\fR" 4
.IX Item "connect"
To connect to a database with a minimum of parameters, use the 
following syntax:
.Sp
.Vb 1
\&  $dbh = DBI\->connect("dbi:Firebird:dbname=$dbname", $user, $password);
.Ve
.Sp
If omitted, \f(CW$user\fR defaults to the \s-1ISC_USER\s0 environment variable
(or, failing that, the DBI-standard \s-1DBI_USER\s0 environment variable).
Similarly, \f(CW$password\fR defaults to \s-1ISC_PASSWORD \s0(or \s-1DBI_PASS\s0).  If
\&\f(CW$dbname\fR is blank, that is, \fI\*(L"dbi:Firebird:dbname=\*(R"\fR, the
environment variable \s-1ISC_DATABASE\s0 is substituted.
.Sp
The \s-1DSN\s0 may take several optional parameters, which may be split
over multiple lines.  Here is an example of connect statement which
uses all possible parameters:
.Sp
.Vb 9
\&   $dsn =<< "DSN";
\& dbi:Firebird:dbname=$dbname;
\& host=$host;
\& port=$port;
\& ib_dialect=$dialect;
\& ib_role=$role;
\& ib_charset=$charset;
\& ib_cache=$cache
\& DSN
\&
\& $dbh =  DBI\->connect($dsn, $username, $password);
.Ve
.Sp
The \f(CW$dsn\fR is prefixed by 'dbi:Firebird:', and consists of key-value
parameters separated by \fBsemicolons\fR. New line may be added after the
semicolon. The following is the list of valid parameters and their
respective meanings:
.Sp
.Vb 10
\&    parameter       meaning                                 optional?
\&    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    database        path to the database                    required
\&    dbname          path to the database
\&    db              path to the database
\&    hostname        hostname / IP address                   optional
\&    host            hostname / IP address
\&    port            port number                             optional
\&    ib_dialect      the SQL dialect to be used              optional
\&    ib_role         the role of the user                    optional
\&    ib_charset      character set to be used                optional
\&    ib_cache        number of database cache buffers        optional
\&    ib_dbkey_scope  change default duration of RDB$DB_KEY   optional
.Ve
.Sp
\&\fBdatabase\fR could be used interchangebly with \fBdbname\fR and \fBdb\fR. 
To connect to a remote host, use the \fBhost\fR parameter. 
Here is an example of \s-1DSN\s0 to connect to a remote Windows host:
.Sp
.Vb 1
\& $dsn = "dbi:Firebird:db=C:/temp/test.gdb;host=example.com;ib_dialect=3";
.Ve
.Sp
Database file alias can be used too in connection string. In the following 
example, \*(L"billing\*(R" is defined in aliases.conf:
.Sp
.Vb 1
\& $dsn = \*(Aqdbi:Firebird:hostname=192.168.88.5;db=billing;ib_dialect=3\*(Aq;
.Ve
.Sp
Firebird as of version 1.0 listens on port specified within the services
file. To connect to port other than the default 3050, add the port number at
the end of host name, separated by a slash. Example:
.Sp
.Vb 1
\& $dsn = \*(Aqdbi:Firebird:db=/data/test.gdb;host=localhost/3060\*(Aq;
.Ve
.Sp
Firebird 1.0 introduces \fB\s-1SQL\s0 dialect\fR to provide backward compatibility with
databases created by older versions of Firebird (pre 1.0). In short, \s-1SQL\s0 dialect
controls how Firebird interprets:
.Sp
.Vb 4
\& \- double quotes
\& \- the DATE datatype
\& \- decimal and numeric datatypes
\& \- new 1.0 reserved keywords
.Ve
.Sp
Valid values for \fBib_dialect\fR are 1 and 3 .The driver's default value is
3 (Currently it is possible to create databases in Dialect 1 and 3 only, however it is recommended that you use Dialect 3 exclusively, since Dialect 1 will eventually be deprecated. Dialect 2 cannot be used to create a database since it only serves to convert Dialect 1 to Dialect 3).
.Sp
http://www.firebirdsql.org/file/documentation/reference_manuals/user_manuals/html/isql\-dialects.html
.Sp
\&\fBib_role\fR specifies the role of the connecting user. \fB\s-1SQL\s0 role\fR is
implemented by Firebird to make database administration easier when dealing
with lots of users. A detailed reading can be found at:
.Sp
.Vb 1
\& http://www.ibphoenix.com/resources/documents/general/doc_59
.Ve
.Sp
If \fBib_cache\fR is not specified, the default database's cache size value will be 
used. The Firebird Operation Guide discusses in full length the importance of 
this parameter to gain the best performance.
.IP "\fBavailable_drivers\fR" 4
.IX Item "available_drivers"
.Vb 1
\&  @driver_names = DBI\->available_drivers;
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBdata_sources\fR" 4
.IX Item "data_sources"
This method is not yet implemented.
.IP "\fBtrace\fR" 4
.IX Item "trace"
.Vb 1
\&  DBI\->trace($trace_level, $trace_file)
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.SS "\s-1DBI\s0 Dynamic Attributes"
.IX Subsection "DBI Dynamic Attributes"
See Common Methods.
.SH "METHODS COMMON TO ALL DBI HANDLES"
.IX Header "METHODS COMMON TO ALL DBI HANDLES"
.IP "\fBerr\fR" 4
.IX Item "err"
.Vb 1
\&  $rv = $h\->err;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBerrstr\fR" 4
.IX Item "errstr"
.Vb 1
\&  $str = $h\->errstr;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBstate\fR" 4
.IX Item "state"
This method is not yet implemented.
.IP "\fBtrace\fR" 4
.IX Item "trace"
.Vb 1
\&  $h\->trace($trace_level, $trace_filename);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBtrace_msg\fR" 4
.IX Item "trace_msg"
.Vb 1
\&  $h\->trace_msg($message_text);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBfunc\fR" 4
.IX Item "func"
See \fBTransactions\fR section for information about invoking \f(CW\*(C`ib_set_tx_param()\*(C'\fR
from \fIfunc()\fR method.
.SH "ATTRIBUTES COMMON TO ALL DBI HANDLES"
.IX Header "ATTRIBUTES COMMON TO ALL DBI HANDLES"
.IP "\fBWarn\fR (boolean, inherited)" 4
.IX Item "Warn (boolean, inherited)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBActive\fR (boolean, read-only)" 4
.IX Item "Active (boolean, read-only)"
Supported by the driver as proposed by \s-1DBI. A\s0 database 
handle is active while it is connected and  statement 
handle is active until it is finished.
.IP "\fBKids\fR (integer, read-only)" 4
.IX Item "Kids (integer, read-only)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBActiveKids\fR (integer, read-only)" 4
.IX Item "ActiveKids (integer, read-only)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBCachedKids\fR (hash ref)" 4
.IX Item "CachedKids (hash ref)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBCompatMode\fR (boolean, inherited)" 4
.IX Item "CompatMode (boolean, inherited)"
Not used by this driver.
.IP "\fBInactiveDestroy\fR (boolean)" 4
.IX Item "InactiveDestroy (boolean)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBPrintError\fR (boolean, inherited)" 4
.IX Item "PrintError (boolean, inherited)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBRaiseError\fR (boolean, inherited)" 4
.IX Item "RaiseError (boolean, inherited)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBChopBlanks\fR (boolean, inherited)" 4
.IX Item "ChopBlanks (boolean, inherited)"
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBLongReadLen\fR (integer, inherited)" 4
.IX Item "LongReadLen (integer, inherited)"
Supported by the driver as proposed by \s-1DBI\s0.The default value is 80 bytes.
.IP "\fBLongTruncOk\fR (boolean, inherited)" 4
.IX Item "LongTruncOk (boolean, inherited)"
Supported by the driver as proposed by \s-1DBI.\s0
.IP "\fBTaint\fR (boolean, inherited)" 4
.IX Item "Taint (boolean, inherited)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.SH "DATABASE HANDLE OBJECTS"
.IX Header "DATABASE HANDLE OBJECTS"
.SS "Database Handle Methods"
.IX Subsection "Database Handle Methods"
.IP "\fBselectrow_array\fR" 4
.IX Item "selectrow_array"
.Vb 1
\&  @row_ary = $dbh\->selectrow_array($statement, \e%attr, @bind_values);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBselectall_arrayref\fR" 4
.IX Item "selectall_arrayref"
.Vb 1
\&  $ary_ref = $dbh\->selectall_arrayref($statement, \e%attr, @bind_values);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBselectcol_arrayref\fR" 4
.IX Item "selectcol_arrayref"
.Vb 1
\&  $ary_ref = $dbh\->selectcol_arrayref($statement, \e%attr, @bind_values);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBprepare\fR" 4
.IX Item "prepare"
.Vb 1
\&  $sth = $dbh\->prepare($statement, \e%attr);
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI.\s0
When AutoCommit is On, this method implicitly starts a new transaction,
which will be automatically committed after the following \fIexecute()\fR or the
last \fIfetch()\fR, depending on the statement type. For select statements,
commit automatically takes place after the last \fIfetch()\fR, or by explicitly 
calling \fIfinish()\fR method if there are any rows remaining. For non-select
statements, \fIexecute()\fR will implicitly commits the transaction.
.IP "\fBprepare_cached\fR" 4
.IX Item "prepare_cached"
.Vb 1
\&  $sth = $dbh\->prepare_cached($statement, \e%attr);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBdo\fR" 4
.IX Item "do"
.Vb 1
\&  $rv  = $dbh\->do($statement, \e%attr, @bind_values);
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI.\s0
This should be used for non-select statements, where the driver doesn't take
the conservative prepare \- execute steps, thereby speeding up the execution
time. But if this method is used with bind values, the speed advantage
diminishes as this method calls \fIprepare()\fR for binding the placeholders.
Instead of calling this method repeatedly with bind values, it would be
better to call \fIprepare()\fR once, and \fIexecute()\fR many times.
.Sp
See the notes for the execute method elsewhere in this document. Unlike the
execute method, currently this method doesn't return the number of affected
rows.
.IP "\fBcommit\fR" 4
.IX Item "commit"
.Vb 1
\&  $rc  = $dbh\->commit;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI.\s0 See also the 
notes about \fBTransactions\fR elsewhere in this document.
.IP "\fBrollback\fR" 4
.IX Item "rollback"
.Vb 1
\&  $rc  = $dbh\->rollback;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI.\s0 See also the 
notes about \fBTransactions\fR elsewhere in this document.
.IP "\fBdisconnect\fR" 4
.IX Item "disconnect"
.Vb 1
\&  $rc  = $dbh\->disconnect;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBping\fR" 4
.IX Item "ping"
.Vb 1
\&  $rc = $dbh\->ping;
.Ve
.Sp
This driver supports the ping-method, which can be used to check the 
validity of a database-handle. This is especially required by
\&\f(CW\*(C`Apache::DBI\*(C'\fR.
.IP "\fBprimary_key_info\fR" 4
.IX Item "primary_key_info"
.Vb 2
\&  $sth = $dbh\->primary_key_info(\*(Aq\*(Aq, \*(Aq\*(Aq, $table_name);
\&  @pks = $dbh\->primary_key(\*(Aq\*(Aq, \*(Aq\*(Aq, $table_name);
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0 Note that catalog and schema
are ignored.
.IP "\fBtable_info\fR" 4
.IX Item "table_info"
.Vb 1
\&  $sth = $dbh\->table_info;
.Ve
.Sp
All Firebird versions support the basic DBI-specified columns
(\s-1TABLE_NAME, TABLE_TYPE,\s0 etc.) as well as \f(CW\*(C`IB_TABLE_OWNER\*(C'\fR.  Peculiar
versions may return additional fields, prefixed by \f(CW\*(C`IB_\*(C'\fR.
.Sp
Table searching may not work as expected on older Interbase/Firebird engines
which do not natively offer a \s-1\fITRIM\s0()\fR function.  Some engines store \s-1TABLE_NAME\s0
in a blank-padded \s-1CHAR\s0 field, and a search for table name is performed via a
\&\s-1SQL \s0\f(CW\*(C`LIKE\*(C'\fR predicate, which is sensitive to blanks.  That is:
.Sp
.Vb 4
\&  $dbh\->table_info(\*(Aq\*(Aq, \*(Aq\*(Aq, \*(AqFOO\*(Aq);  # May not find table "FOO", depending on
\&                                    # FB version
\&  $dbh\->table_info(\*(Aq\*(Aq, \*(Aq\*(Aq, \*(AqFOO%\*(Aq); # Will always find "FOO", but also tables
\&                                    # "FOOD", "FOOT", etc.
.Ve
.Sp
Future versions of DBD::Firebird may attempt to work around this irritating
limitation, at the expense of efficiency.
.Sp
Note that Firebird implementations do not presently support the \s-1DBI\s0
concepts of 'catalog' and 'schema', so these parameters are effectively
ignored.
.IP "\fBtables\fR" 4
.IX Item "tables"
.Vb 1
\&  @names = $dbh\->tables;
.Ve
.Sp
Returns a list of tables, excluding any '\s-1SYSTEM TABLE\s0' types.
.IP "\fBtype_info_all\fR" 4
.IX Item "type_info_all"
.Vb 1
\&  $type_info_all = $dbh\->type_info_all;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.Sp
For further details concerning the Firebird specific data-types 
please read the Firebird Data Definition Guide
.Sp
http://www.firebirdsql.org/en/reference\-manuals/
.IP "\fBtype_info\fR" 4
.IX Item "type_info"
.Vb 1
\&  @type_info = $dbh\->type_info($data_type);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBquote\fR" 4
.IX Item "quote"
.Vb 1
\&  $sql = $dbh\->quote($value, $data_type);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.SS "Database Handle Attributes"
.IX Subsection "Database Handle Attributes"
.IP "\fBAutoCommit\fR  (boolean)" 4
.IX Item "AutoCommit (boolean)"
Supported by the driver as proposed by \s-1DBI.\s0 According to the 
classification of \s-1DBI,\s0 Firebird is a database, in which a 
transaction must be explicitly started. Without starting a 
transaction, every change to the database becomes immediately 
permanent. The default of AutoCommit is on, which corresponds 
to the \s-1DBI\s0's default. When setting AutoCommit to off, a transaction 
will be started and every commit or rollback 
will automatically start a new transaction. For details see the 
notes about \fBTransactions\fR elsewhere in this document.
.IP "\fBDriver\fR  (handle)" 4
.IX Item "Driver (handle)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBName\fR  (string, read-only)" 4
.IX Item "Name (string, read-only)"
Not yet implemented.
.IP "\fBRowCacheSize\fR  (integer)" 4
.IX Item "RowCacheSize (integer)"
Implemented by \s-1DBI,\s0 not used by the driver.
.IP "\fBib_softcommit\fR  (driver-specific, boolean)" 4
.IX Item "ib_softcommit (driver-specific, boolean)"
Set this attribute to \s-1TRUE\s0 to use Firebird's soft commit feature (default
to \s-1FALSE\s0). Soft commit retains the internal transaction handle when
committing a transaction, while the default commit behavior always closes
and invalidates the transaction handle.
.Sp
Since the transaction handle is still open, there is no need to start a new transaction 
upon every commit, so applications can gain performance improvement. Using soft commit is also 
desirable when dealing with nested statement handles under AutoCommit on.
.Sp
Switching the attribute's value from \s-1TRUE\s0 to \s-1FALSE\s0 will force hard commit thus 
closing the current transaction.
.IP "\fBib_enable_utf8\fR  (driver-specific, boolean)" 4
.IX Item "ib_enable_utf8 (driver-specific, boolean)"
Setting this attribute to \s-1TRUE\s0 will cause any Perl Unicode strings supplied as
statement parameters to be downgraded to octet sequences before passing them to
Firebird.
.Sp
Also, any character data retrieved from the database (\s-1CHAR, VARCHAR, BLOB\s0
sub_type \s-1TEXT\s0) will be upgraded to Perl Unicode strings.
.Sp
\&\fBCaveat\fR: Currently this is supported only if the \fBib_charset\fR \s-1DSN\s0 parameter
is \f(CW\*(C`UTF8\*(C'\fR. In the future, encoding and decoding to/from arbitrary character
set may be implemented.
.Sp
Example:
.Sp
.Vb 2
\&    $dbh = DBI\->connect( \*(Aqdbi:Firebird:db=database.fdb;ib_charset=UTF8\*(Aq,
\&        { ib_enable_utf8 => 1 } );
.Ve
.SH "STATEMENT HANDLE OBJECTS"
.IX Header "STATEMENT HANDLE OBJECTS"
.SS "Statement Handle Methods"
.IX Subsection "Statement Handle Methods"
.IP "\fBbind_param\fR" 4
.IX Item "bind_param"
Supported by the driver as proposed by \s-1DBI. \s0
The \s-1SQL\s0 data type passed as the third argument is ignored.
.IP "\fBbind_param_array\fR" 4
.IX Item "bind_param_array"
Supported by the driver as proposed by \s-1DBI.\s0
The attributes, supplied in the optional third parameter are ignored.
.IP "\fBbind_param_inout\fR" 4
.IX Item "bind_param_inout"
Not supported by this driver.
.IP "\fBexecute\fR" 4
.IX Item "execute"
.Vb 1
\&  $rv = $sth\->execute(@bind_values);
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBfetchrow_arrayref\fR" 4
.IX Item "fetchrow_arrayref"
.Vb 1
\&  $ary_ref = $sth\->fetchrow_arrayref;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBfetchrow_array\fR" 4
.IX Item "fetchrow_array"
.Vb 1
\&  @ary = $sth\->fetchrow_array;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBfetchrow_hashref\fR" 4
.IX Item "fetchrow_hashref"
.Vb 1
\&  $hash_ref = $sth\->fetchrow_hashref;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBfetchall_arrayref\fR" 4
.IX Item "fetchall_arrayref"
.Vb 1
\&  $tbl_ary_ref = $sth\->fetchall_arrayref;
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBfinish\fR" 4
.IX Item "finish"
.Vb 1
\&  $rc = $sth\->finish;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBrows\fR" 4
.IX Item "rows"
.Vb 1
\&  $rv = $sth\->rows;
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
It returns the number of \fBfetched\fR rows for select statements, otherwise
it returns \-1 (unknown number of affected rows).
.IP "\fBbind_col\fR" 4
.IX Item "bind_col"
.Vb 1
\&  $rc = $sth\->bind_col($column_number, \e$var_to_bind, \e%attr);
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBbind_columns\fR" 4
.IX Item "bind_columns"
.Vb 1
\&  $rc = $sth\->bind_columns(\e%attr, @list_of_refs_to_vars_to_bind);
.Ve
.Sp
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBdump_results\fR" 4
.IX Item "dump_results"
.Vb 1
\&  $rows = $sth\->dump_results($maxlen, $lsep, $fsep, $fh);
.Ve
.Sp
Implemented by \s-1DBI,\s0 no driver-specific impact.
.SS "Statement Handle Attributes"
.IX Subsection "Statement Handle Attributes"
.IP "\fB\s-1NUM_OF_FIELDS\s0\fR  (integer, read-only)" 4
.IX Item "NUM_OF_FIELDS (integer, read-only)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fB\s-1NUM_OF_PARAMS\s0\fR  (integer, read-only)" 4
.IX Item "NUM_OF_PARAMS (integer, read-only)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fB\s-1NAME\s0\fR  (array-ref, read-only)" 4
.IX Item "NAME (array-ref, read-only)"
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBNAME_lc\fR  (array-ref, read-only)" 4
.IX Item "NAME_lc (array-ref, read-only)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fBNAME_uc\fR  (array-ref, read-only)" 4
.IX Item "NAME_uc (array-ref, read-only)"
Implemented by \s-1DBI,\s0 no driver-specific impact.
.IP "\fB\s-1TYPE\s0\fR  (array-ref, read-only)" 4
.IX Item "TYPE (array-ref, read-only)"
Supported by the driver as proposed by \s-1DBI,\s0 with 
the restriction, that the types are Firebird
specific data-types which do not correspond to 
international standards.
.IP "\fB\s-1PRECISION\s0\fR  (array-ref, read-only)" 4
.IX Item "PRECISION (array-ref, read-only)"
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fB\s-1SCALE\s0\fR  (array-ref, read-only)" 4
.IX Item "SCALE (array-ref, read-only)"
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fB\s-1NULLABLE\s0\fR  (array-ref, read-only)" 4
.IX Item "NULLABLE (array-ref, read-only)"
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBCursorName\fR  (string, read-only)" 4
.IX Item "CursorName (string, read-only)"
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBStatement\fR  (string, read-only)" 4
.IX Item "Statement (string, read-only)"
Supported by the driver as proposed by \s-1DBI. \s0
.IP "\fBRowCache\fR  (integer, read-only)" 4
.IX Item "RowCache (integer, read-only)"
Not supported by the driver.
.IP "\fBParamValues\fR (hashref, read-only)" 4
.IX Item "ParamValues (hashref, read-only)"
Supported by the driver as proposed by \s-1DBI.\s0
.SH "TRANSACTION SUPPORT"
.IX Header "TRANSACTION SUPPORT"
The transaction behavior is controlled with the attribute AutoCommit. 
For a complete definition of AutoCommit please refer to the \s-1DBI\s0 documentation.
.PP
According to the \s-1DBI\s0 specification the default for AutoCommit is \s-1TRUE. \s0
In this mode, any change to the database becomes valid immediately. Any 
\&\fIcommit()\fR or \fIrollback()\fR will be rejected.
.PP
If AutoCommit is switched-off, immediately a transaction will be started.
A \fIrollback()\fR will rollback and close the active transaction, then implicitly 
start a new transaction. A disconnect will issue a rollback.
.PP
Firebird provides fine control over transaction behavior, where users can
specify the access mode, the isolation level, the lock resolution, and the 
table reservation (for a specified table). For this purpose,
\&\f(CW\*(C`ib_set_tx_param()\*(C'\fR database handle method is available.
.PP
Upon a successful \f(CW\*(C`connect()\*(C'\fR, these default parameter values will be used
for every \s-1SQL\s0 operation:
.PP
.Vb 3
\&    Access mode:        read_write
\&    Isolation level:    snapshot
\&    Lock resolution:    wait
.Ve
.PP
Any of the above value can be changed using \f(CW\*(C`ib_set_tx_param()\*(C'\fR.
.IP "\fBib_set_tx_param\fR" 4
.IX Item "ib_set_tx_param"
.Vb 6
\& $dbh\->func( 
\&    \-access_mode     => \*(Aqread_write\*(Aq,
\&    \-isolation_level => \*(Aqread_committed\*(Aq,
\&    \-lock_resolution => \*(Aqwait\*(Aq,
\&    \*(Aqib_set_tx_param\*(Aq
\& );
.Ve
.Sp
Valid value for \f(CW\*(C`\-access_mode\*(C'\fR is \f(CW\*(C`read_write\*(C'\fR, or \f(CW\*(C`read_only\*(C'\fR.
.Sp
Valid value for \f(CW\*(C`\-lock_resolution\*(C'\fR is \f(CW\*(C`wait\*(C'\fR, or \f(CW\*(C`no_wait\*(C'\fR. 
In Firebird 2.0, a timeout value for wait is introduced. This can be 
specified using hash ref as lock_resolution value:
.Sp
.Vb 4
\& $dbh\->func(
\&    \-lock_resolution => { wait => 5 }, # wait for 5 seconds
\&    \*(Aqib_set_tx_param\*(Aq
\& );
.Ve
.Sp
\&\f(CW\*(C`\-isolation_level\*(C'\fR may be: \f(CW\*(C`read_committed\*(C'\fR, \f(CW\*(C`snapshot\*(C'\fR,
\&\f(CW\*(C`snapshot_table_stability\*(C'\fR.
.Sp
If \f(CW\*(C`read_committed\*(C'\fR is to be used with \f(CW\*(C`record_version\*(C'\fR or
\&\f(CW\*(C`no_record_version\*(C'\fR, then they should be inside an anonymous array:
.Sp
.Vb 4
\& $dbh\->func( 
\&    \-isolation_level => [\*(Aqread_committed\*(Aq, \*(Aqrecord_version\*(Aq],
\&    \*(Aqib_set_tx_param\*(Aq
\& );
.Ve
.Sp
Table reservation is supported since \f(CW\*(C`DBD::Firebird 0.30\*(C'\fR. Names of the
tables to reserve as well as their reservation params/values are specified
inside a hashref, which is then passed as the value of \f(CW\*(C`\-reserving\*(C'\fR.
.Sp
The following example reserves \f(CW\*(C`foo_table\*(C'\fR with \f(CW\*(C`read\*(C'\fR lock and \f(CW\*(C`bar_table\*(C'\fR 
with \f(CW\*(C`read\*(C'\fR lock and \f(CW\*(C`protected\*(C'\fR access:
.Sp
.Vb 10
\& $dbh\->func(
\&    \-access_mode     => \*(Aqread_write\*(Aq,
\&    \-isolation_level => \*(Aqread_committed\*(Aq,
\&    \-lock_resolution => \*(Aqwait\*(Aq,
\&    \-reserving       =>
\&        {
\&            foo_table => {
\&                lock    => \*(Aqread\*(Aq,
\&            },
\&            bar_table => {
\&                lock    => \*(Aqread\*(Aq,
\&                access  => \*(Aqprotected\*(Aq,
\&            },
\&        },
\&    \*(Aqib_set_tx_param\*(Aq
\& );
.Ve
.Sp
Possible table reservation parameters are:
.RS 4
.ie n .IP """access"" (optional)" 4
.el .IP "\f(CWaccess\fR (optional)" 4
.IX Item "access (optional)"
Valid values are \f(CW\*(C`shared\*(C'\fR or \f(CW\*(C`protected\*(C'\fR.
.ie n .IP """lock"" (required)" 4
.el .IP "\f(CWlock\fR (required)" 4
.IX Item "lock (required)"
Valid values are \f(CW\*(C`read\*(C'\fR or \f(CW\*(C`write\*(C'\fR.
.RE
.RS 4
.Sp
Under \f(CW\*(C`AutoCommit\*(C'\fR mode, invoking this method doesn't only change the
transaction parameters (as with \f(CW\*(C`AutoCommit\*(C'\fR off), but also commits the
current transaction. The new transaction parameters will be used in
any newly started transaction.
.Sp
\&\f(CW\*(C`ib_set_tx_param()\*(C'\fR can also be invoked with no parameter in which it resets
transaction parameters to the default value.
.RE
.SH "DATE, TIME, and TIMESTAMP FORMATTING SUPPORT"
.IX Header "DATE, TIME, and TIMESTAMP FORMATTING SUPPORT"
\&\f(CW\*(C`DBD::Firebird\*(C'\fR supports various formats for query results of \s-1DATE, TIME,\s0
and \s-1TIMESTAMP\s0 types.
.PP
By default, it uses \*(L"%c\*(R" for \s-1TIMESTAMP, \s0\*(L"%x\*(R" for \s-1DATE,\s0 and \*(L"%X\*(R" for \s-1TIME,\s0
and pass them to \s-1ANSI C\s0's \fIstrftime()\fR function to format your query results.
These values are respectively stored in ib_timestampformat, ib_dateformat,
and ib_timeformat attributes, and may be changed in two ways:
.IP "\(bu" 4
At \f(CW$dbh\fR level
.Sp
This replaces the default values. Example:
.Sp
.Vb 3
\& $dbh\->{ib_timestampformat} = \*(Aq%m\-%d\-%Y %H:%M\*(Aq;
\& $dbh\->{ib_dateformat} = \*(Aq%m\-%d\-%Y\*(Aq;
\& $dbh\->{ib_timeformat} = \*(Aq%H:%M\*(Aq;
.Ve
.IP "\(bu" 4
At \f(CW$sth\fR level
.Sp
This overrides the default values only for the currently prepared statement. Example:
.Sp
.Vb 7
\& $attr = {
\&    ib_timestampformat => \*(Aq%m\-%d\-%Y %H:%M\*(Aq,
\&    ib_dateformat => \*(Aq%m\-%d\-%Y\*(Aq,
\&    ib_timeformat => \*(Aq%H:%M\*(Aq,
\& };
\& # then, pass it to prepare() method. 
\& $sth = $dbh\->prepare($sql, $attr);
.Ve
.PP
Since locale settings affect the result of \fIstrftime()\fR, if your application
is designed to be portable across different locales, you may consider using these
two special formats: '\s-1TM\s0' and '\s-1ISO\s0'. \f(CW\*(C`TM\*(C'\fR returns a 9\-element list, much like
Perl's \fIlocaltime()\fR. The \f(CW\*(C`ISO\*(C'\fR format applies \fIsprintf()\fR's pattern
\&\*(L"%04d\-%02d\-%02d \f(CW%02d:\fR%02d:%02d.%04d\*(R" for \s-1TIMESTAMP, \s0\*(L"%04d\-%02d\-%02d\*(R" for
\&\s-1DATE,\s0 and \*(L"%02d:%02d:%02d.%04d\*(R" for \s-1TIME. \s0
.PP
\&\f(CW\*(C`$dbh\->{ib_time_all}\*(C'\fR can be used to specify all of the three formats at
once. Example:
.PP
.Vb 1
\& $dbh\->{ib_time_all} = \*(AqTM\*(Aq;
.Ve
.SH "EVENT ALERT SUPPORT"
.IX Header "EVENT ALERT SUPPORT"
Event alerter is used to notify client applications whenever something is
happened on the database. For this to work, a trigger should be created,
which then calls \s-1POST_EVENT\s0 to post the event notification to the interested
client. A client could behave in two ways: wait for the event synchronously,
or register a callback which will be invoked asynchronously each time a
posted event received.
.ie n .IP """ib_init_event""" 4
.el .IP "\f(CWib_init_event\fR" 4
.IX Item "ib_init_event"
.Vb 1
\& $evh = $dbh\->func(@event_names, \*(Aqib_init_event\*(Aq);
.Ve
.Sp
Creates an event handle from a list of event names.
.ie n .IP """ib_wait_event""" 4
.el .IP "\f(CWib_wait_event\fR" 4
.IX Item "ib_wait_event"
.Vb 1
\& $dbh\->func($evh, \*(Aqib_wait_event\*(Aq);
.Ve
.Sp
Wait synchronously for particular events registered via event handle \f(CW$evh\fR.
Returns a hashref containing pair(s) of posted event's name and its corresponding count,
or undef on failure.
.ie n .IP """ib_register_callback""" 4
.el .IP "\f(CWib_register_callback\fR" 4
.IX Item "ib_register_callback"
.Vb 2
\& my $cb = sub { my $posted_events = $_[0]; ++$::COUNT < 6 };
\& $dbh\->func($evh, $cb, \*(Aqib_register_callback\*(Aq);
\&
\& sub inc_count { my $posted_events = shift; ++$::COUNT < 6 };
\& $dbh\->func($evh, \e&inc_count, \*(Aqib_register_callback\*(Aq);
\&
\& # or anonyomus subroutine
\& $dbh\->func(
\&   $evh, 
\&   sub { my ($pe) = @_; ++$::COUNT < 6 }, 
\&   \*(Aqib_register_callback\*(Aq
\& );
.Ve
.Sp
Associates an event handle with an asynchronous callback. A callback will be
passed a hashref as its argument, this hashref contains pair(s) of posted event's name
and its corresponding count.
.Sp
It is safe to call \f(CW\*(C`ib_register_callback\*(C'\fR multiple times for the same event handle. In this 
case, the previously registered callback will be automatically cancelled.
.Sp
If the callback returns \s-1FALSE,\s0 the registered callback will be no longer invoked, but internally
it is still there until the event handle goes out of scope (or undef-ed), or you call 
\&\f(CW\*(C`ib_cancel_callback\*(C'\fR to actually disassociate it from the event handle.
.ie n .IP """ib_cancel_callback""" 4
.el .IP "\f(CWib_cancel_callback\fR" 4
.IX Item "ib_cancel_callback"
.Vb 1
\& $dbh\->func($evh, \*(Aqib_cancel_callback\*(Aq);
.Ve
.Sp
Unregister a callback from an event handle. This function has a limitation,
however, that it can't be called from inside a callback. In many cases, you won't
need this function, since when an event handle goes out of scope, its associated callback(s)
will be automatically cancelled before it is cleaned up.
.SH "RETRIEVING FIREBIRD / INTERBASE SPECIFIC INFORMATION"
.IX Header "RETRIEVING FIREBIRD / INTERBASE SPECIFIC INFORMATION"
.ie n .IP """ib_tx_info""" 4
.el .IP "\f(CWib_tx_info\fR" 4
.IX Item "ib_tx_info"
.Vb 1
\& $hash_ref = $dbh\->func(\*(Aqib_tx_info\*(Aq);
.Ve
.Sp
Retrieve information about current active transaction.
.ie n .IP """ib_database_info""" 4
.el .IP "\f(CWib_database_info\fR" 4
.IX Item "ib_database_info"
.Vb 2
\& $hash_ref = $dbh\->func(@info, \*(Aqib_database_info\*(Aq);
\& $hash_ref = $dbh\->func([@info], \*(Aqib_database_info\*(Aq);
.Ve
.Sp
Retrieve database information from current connection.
.ie n .IP """ib_plan""" 4
.el .IP "\f(CWib_plan\fR" 4
.IX Item "ib_plan"
.Vb 1
\& $plan = $sth\->func(\*(Aqib_plan\*(Aq);
.Ve
.Sp
Retrieve query plan from a prepared \s-1SQL\s0 statement.
.Sp
.Vb 2
\& my $sth = $dbh\->prepare(\*(AqSELECT * FROM foo\*(Aq);
\& print $sth\->func(\*(Aqib_plan\*(Aq); # PLAN (FOO NATURAL)
.Ve
.ie n .IP """ib_drop_database""" 4
.el .IP "\f(CWib_drop_database\fR" 4
.IX Item "ib_drop_database"
.Vb 1
\& $result = $dbh\->func(\*(Aqib_drop_database\*(Aq);
.Ve
.Sp
Drops the database, associated with the connection. The database handle is no
longer valid after calling this function.
.Sp
Caution is advised as the drop is irrevocable.
.SH "UNSUPPORTED SQL STATEMENTS"
.IX Header "UNSUPPORTED SQL STATEMENTS"
Here is a list of \s-1SQL\s0 statements which can't be used. But this shouldn't be a 
problem, because their functionality are already provided by the \s-1DBI\s0 methods.
.IP "\(bu" 4
\&\s-1SET TRANSACTION\s0
.Sp
Use \f(CW\*(C`$dbh\-\*(C'\fRfunc(..., 'set_tx_param')> instead.
.IP "\(bu" 4
\&\s-1DESCRIBE\s0
.Sp
Provides information about columns that are retrieved by a \s-1DSQL\s0 statement,
or about placeholders in a statement. This functionality is supported by the
driver, and transparent for users. Column names are available via
\&\f(CW$sth\fR\->{\s-1NAME\s0} attributes.
.IP "\(bu" 4
\&\s-1EXECUTE IMMEDIATE\s0
.Sp
Calling \fIdo()\fR method without bind value(s) will do the same.
.IP "\(bu" 4
\&\s-1CLOSE, OPEN, DECLARE CURSOR\s0
.Sp
\&\f(CW$sth\fR\->{CursorName} is automagically available upon executing a \*(L"\s-1SELECT .. FOR
UPDATE\*(R"\s0 statement. A cursor is closed after the last \fIfetch()\fR, or by calling
\&\f(CW$sth\fR\->\fIfinish()\fR.
.IP "\(bu" 4
\&\s-1PREPARE, EXECUTE, FETCH\s0
.Sp
Similar functionalities are obtained by using \fIprepare()\fR, \fIexecute()\fR, and 
\&\fIfetch()\fR methods.
.SH "COMPATIBILITY WITH DBIx::* MODULES"
.IX Header "COMPATIBILITY WITH DBIx::* MODULES"
\&\f(CW\*(C`DBD::Firebird\*(C'\fR is known to work with \f(CW\*(C`DBIx::Recordset\*(C'\fR 0.21, and
\&\f(CW\*(C`Apache::DBI\*(C'\fR 0.87. Yuri Vasiliev <\fIyuri.vasiliev@targuscom.com\fR> reported 
successful usage with Apache::AuthDBI (part of \f(CW\*(C`Apache::DBI\*(C'\fR 0.87 
distribution).
.PP
The driver is untested with \f(CW\*(C`Apache::Session::DBI\*(C'\fR. Doesn't work with 
\&\f(CW\*(C`Tie::DBI\*(C'\fR. \f(CW\*(C`Tie::DBI\*(C'\fR calls \f(CW$dbh\fR\->prepare(\*(L"\s-1LISTFIELDS\s0 \f(CW$table_name\fR\*(R") on 
which Firebird fails to parse. I think that the call should be made within 
an eval block.
.SH "SERVICE METHODS"
.IX Header "SERVICE METHODS"
.SS "DBD::Firebird\->create_database( { params... } )"
.IX Subsection "DBD::Firebird->create_database( { params... } )"
A class method for creating empty databases.
.PP
The method croaks on error. Params may be:
.IP "db_path (string, required)" 4
.IX Item "db_path (string, required)"
Path to database, including host name if necessary.
.Sp
Examples:
.RS 4
.IP "server:/path/to/db.fdb" 4
.IX Item "server:/path/to/db.fdb"
.PD 0
.IP "/srv/db/base.fdb" 4
.IX Item "/srv/db/base.fdb"
.RE
.RS 4
.RE
.IP "user (string, optional)" 4
.IX Item "user (string, optional)"
.PD
User name to be used for the request.
.IP "password (string, optional)" 4
.IX Item "password (string, optional)"
Password to be used for the request.
.IP "page_size (integer, optional)" 4
.IX Item "page_size (integer, optional)"
Page size of the newly created database. Should be something supported by the
server. Firebird 2.5 supports the following page sizes: 1024, 2048, 4096, 8192
and 16384 and defaults to 4096.
.IP "character_set (string, optional)" 4
.IX Item "character_set (string, optional)"
The default character set of the database. Firebird 2.5 defaults to \f(CW\*(C`NONE\*(C'\fR.
.IP "dialect (integer, optional)" 4
.IX Item "dialect (integer, optional)"
The dialect of the database. Defaults to 3.
.PP
After creation, the new database can be used after connecting to it with the
usual \s-1DBI\-\s0>connect(...)
.SS "DBD::Firebird\->gfix( { params } )"
.IX Subsection "DBD::Firebird->gfix( { params } )"
A class method for simulating a subset of the functionality of the
Firebird's \fIgfix\fR\|(1) utility.
.PP
Params is a hash reference, with the following keys:
.IP "db_path (string, required)" 4
.IX Item "db_path (string, required)"
The path to the database to connect to. Should include host name if
necessary.
.IP "user (string, optional)" 4
.IX Item "user (string, optional)"
User name to connect as. Must be \s-1SYSDBA\s0 or database owner.
.IP "password (string, optional)" 4
.IX Item "password (string, optional)"
Password to be used for the connection.
.Sp
Note that user and password are not needed for embedded connections.
.IP "forced_writes (boolean, optional)" 4
.IX Item "forced_writes (boolean, optional)"
If given, sets the forced writes flag of the database, causing Firebird
to use synchronous writes when working with that database.
.IP "buffers (integer, optional)" 4
.IX Item "buffers (integer, optional)"
If given, sets the default number of buffers for the database. Can
be overridden on connect time. Note that buffers are measured in database
pages, not bytes.
.SH "FAQ"
.IX Header "FAQ"
.SS "Why do some operations performing positioned update and delete fail when AutoCommit is on?"
.IX Subsection "Why do some operations performing positioned update and delete fail when AutoCommit is on?"
For example, the following code snippet fails:
.PP
.Vb 7
\& $sth = $dbh\->prepare(
\& "SELECT * FROM ORDERS WHERE user_id < 5 FOR UPDATE OF comment");
\& $sth\->execute;
\& while (@res = $sth\->fetchrow_array) {
\&     $dbh\->do("UPDATE ORDERS SET comment = \*(AqWonderful\*(Aq WHERE 
\&     CURRENT OF $sth\->{CursorName}");
\& }
.Ve
.PP
When \fBAutoCommit is on\fR, a transaction is started within \fIprepare()\fR, and
committed automatically after the last \fIfetch()\fR, or within \fIfinish()\fR. Within
\&\fIdo()\fR, a transaction is started right before the statement is executed, and
gets committed right after the statement is executed. The transaction handle
is stored within the database handle. The driver is smart enough not to
override an active transaction handle with a new one. So, if you notice the
snippet above, after the first \fIfetchrow_array()\fR, the \fIdo()\fR is still using the
same transaction context, but as soon as it has finished executing the statement, it
\&\fBcommits\fR the transaction, whereas the next \fIfetchrow_array()\fR still needs
the transaction context!
.PP
So the secret to make this work is \fBto keep the transaction open\fR. This can be
done in two ways:
.IP "\(bu" 4
Using AutoCommit = 0
.Sp
If yours is default to AutoCommit on, you can put the snippet within a block:
.Sp
.Vb 5
\& {
\&     $dbh\->{AutoCommit} = 0;
\&     # same actions like above ....
\&     $dbh\->commit;
\& }
.Ve
.IP "\(bu" 4
Using \f(CW$dbh\fR\->{ib_softcommit} = 1
.Sp
This is a driver-specific attribute,You may want to look at
t/70\-nested\-sth.t to see it in action.
.SS "Why do nested statement handles break under AutoCommit mode?"
.IX Subsection "Why do nested statement handles break under AutoCommit mode?"
The same explanation as above applies. The workaround is also
much alike:
.PP
.Vb 5
\& {
\&     $dbh\->{AutoCommit} = 0;
\&     $sth1 = $dbh\->prepare("SELECT * FROM $table");
\&     $sth2 = $dbh\->prepare("SELECT * FROM $table WHERE id = ?");
\&     $sth1\->execute;
\&
\&     while ($row = $sth1\->fetchrow_arrayref) {
\&        $sth2\->execute($row\->[0]);
\&        $res = $sth2\->fetchall_arrayref;
\&     }
\&     $dbh\->commit;
\& }
.Ve
.PP
You may also use \f(CW$dbh\fR\->{ib_softcommit}  please check
t/70nested\-sth.t for an example on how to use it.
.SS "Why do placeholders fail to bind, generating unknown datatype error message?"
.IX Subsection "Why do placeholders fail to bind, generating unknown datatype error message?"
You can't bind a field name. The following example will fail:
.PP
.Vb 2
\& $sth = $dbh\->prepare("SELECT (?) FROM $table");
\& $sth\->execute(\*(Aquser_id\*(Aq);
.Ve
.PP
There are cases where placeholders can't be used in conjunction with \s-1COLLATE\s0
clause, such as this:
.PP
.Vb 1
\& SELECT * FROM $table WHERE UPPER(author) LIKE UPPER(? COLLATE FR_CA);
.Ve
.PP
This deals with the Firebird's \s-1SQL\s0 parser, not with \f(CW\*(C`DBD::Firebird\*(C'\fR. The
driver just passes \s-1SQL\s0 statements through the engine.
.SS "How to do automatic increment for a specific field?"
.IX Subsection "How to do automatic increment for a specific field?"
Create a sequence and a trigger to associate it with the field. The
following example creates a sequence named \s-1PROD_ID_SEQ,\s0 and a trigger for
table \s-1ORDERS\s0 which uses the generator to perform auto increment on field
\&\s-1PRODUCE_ID\s0 with increment size of 1.
.PP
.Vb 7
\& $dbh\->do("create sequence PROD_ID_SEQ");
\& $dbh\->do(
\& "CREATE TRIGGER INC_PROD_ID FOR ORDERS
\& BEFORE INSERT POSITION 0
\& AS BEGIN
\&   NEW.PRODUCE_ID = NEXT VALUE FOR PROD_ID_SEQ;
\& END");
.Ve
.PP
From Firebird 3.0 there is Identity support
.SS "How can I perform \s-1LIMIT\s0 clause as I usually do in MySQL?"
.IX Subsection "How can I perform LIMIT clause as I usually do in MySQL?"
\&\f(CW\*(C`LIMIT\*(C'\fR clause let users to fetch only a portion rather than the whole 
records as the result of a query. This is particularly efficient and useful 
for paging feature on web pages, where users can navigate back and forth 
between pages.
.PP
Using Firebird 2.5.x this can be implemented by using \f(CW\*(C`ROWS\*(C'\fR .
.PP
.Vb 1
\& http://www.firebirdsql.org/refdocs/langrefupd21\-select.html#langrefupd21\-select\-rows
.Ve
.PP
For example, to display a portion of table employee within your application:
.PP
.Vb 2
\& # fetch record 1 \- 5:
\& $res = $dbh\->selectall_arrayref("SELECT * FROM employee rows 1 to 5)");
\&
\& # fetch record 6 \- 10: 
\& $res = $dbh\->selectall_arrayref("SELECT * FROM employee rows 6 to 10)");
.Ve
.SS "How can I use the date/time formatting attributes?"
.IX Subsection "How can I use the date/time formatting attributes?"
Those attributes take the same format as the C function \fIstrftime()\fR's.
Examples:
.PP
.Vb 5
\& $attr = {
\&    ib_timestampformat => \*(Aq%m\-%d\-%Y %H:%M\*(Aq,
\&    ib_dateformat => \*(Aq%m\-%d\-%Y\*(Aq,
\&    ib_timeformat => \*(Aq%H:%M\*(Aq,
\& };
.Ve
.PP
Then, pass it to \fIprepare()\fR method.
.PP
.Vb 2
\& $sth = $dbh\->prepare($stmt, $attr);
\& # followed by execute() and fetch(), or:
\&
\& $res = $dbh\->selectall_arrayref($stmt, $attr);
.Ve
.SS "Can I set the date/time formatting attributes between prepare and fetch?"
.IX Subsection "Can I set the date/time formatting attributes between prepare and fetch?"
No. \f(CW\*(C`ib_dateformat\*(C'\fR, \f(CW\*(C`ib_timeformat\*(C'\fR, and \f(CW\*(C`ib_timestampformat\*(C'\fR can only
be set during \f(CW$sth\fR\->prepare. If this is a problem to you, let me know, and
probably I'll add this capability for the next release.
.SS "Can I change ib_dialect after \s-1DBI\-\s0>connect ?"
.IX Subsection "Can I change ib_dialect after DBI->connect ?"
No. If this is a problem to you, let me know, and probably I'll add this 
capability for the next release.
.SH "OBSOLETE FEATURES"
.IX Header "OBSOLETE FEATURES"
.IP "Private Method" 4
.IX Item "Private Method"
\&\f(CW\*(C`set_tx_param()\*(C'\fR is obsoleted by \f(CW\*(C`ib_set_tx_param()\*(C'\fR.
.SH "TESTED PLATFORMS"
.IX Header "TESTED PLATFORMS"
.SS "Clients"
.IX Subsection "Clients"
.IP "Linux" 4
.IX Item "Linux"
.PD 0
.IP "FreeBSD" 4
.IX Item "FreeBSD"
.IP "Solaris" 4
.IX Item "Solaris"
.IP "Win32" 4
.IX Item "Win32"
.PD
.SS "Servers"
.IX Subsection "Servers"
.IP "Firebird 2.5.x \s-1SS , SC\s0 and Classic for Linux (32 bits and 64)" 4
.IX Item "Firebird 2.5.x SS , SC and Classic for Linux (32 bits and 64)"
.PD 0
.IP "Firebird 2.5.x for Windows, FreeBSD, Solaris" 4
.IX Item "Firebird 2.5.x for Windows, FreeBSD, Solaris"
.PD
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
\&\s-1DBI\s0 by Tim Bunce <Tim.Bunce@pobox.com>
.IP "\(bu" 4
DBD::Firebird by Edwin Pratomo <edpratomo@cpan.org>, Daniel Ritz
<daniel.ritz@gmx.ch> and many others. See \*(L"\s-1COPYRIGHT & LICENSE\*(R"\s0.
.Sp
This module is originally based on the work of Bill Karwin's IBPerl.
.SH "BUGS/LIMITATIONS"
.IX Header "BUGS/LIMITATIONS"
Please report bugs and feature suggestions using 
http://rt.cpan.org/Public/Dist/Display.html?Name=DBD\-Firebird .
.PP
This module doesn't work with MSWin32 ActivePerl iThreads, and its emulated
fork. Tested with MSWin32 ActivePerl build 809 (Perl 5.8.3). The whole
process will block in unpredictable manner.
.PP
Under Linux, this module has been tested with several different iThreads
enabled Perl releases.
.PP
No problem occurred so far.. until you try to share a \s-1DBI\s0 handle ;\-)
.PP
But if you plan to use thread, you'd better use the latest stable version of
Perl
.PP
On FreeBSD you need a Perl compiled with thread support.
.PP
Limitations:
.IP "\(bu" 4
Arrays are not (yet) supported
.IP "\(bu" 4
Read/Write \s-1BLOB\s0 fields block by block not (yet) supported. The
maximum size of a \s-1BLOB\s0 read/write is hardcoded to about 1 \s-1MB.\s0
.IP "\(bu" 4
service manager \s-1API\s0 is not supported.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1\fIDBI\s0\fR\|(3).
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
.IP "Copyright (c) 2010\- 2012  Popa Adrian Marius <mapopa@gmail.com>" 4
.IX Item "Copyright (c) 2010- 2012 Popa Adrian Marius <mapopa@gmail.com>"
.PD 0
.IP "Copyright (c) 2011\- 2012  Stefan Suciu <stefbv70@gmail.com>" 4
.IX Item "Copyright (c) 2011- 2012 Stefan Suciu <stefbv70@gmail.com>"
.IP "Copyright (c) 2011  Damyan Ivanov <dmn@debian.org>" 4
.IX Item "Copyright (c) 2011 Damyan Ivanov <dmn@debian.org>"
.IP "Copyright (c) 2011  Alexandr Ciornii <alexchorny@gmail.com>" 4
.IX Item "Copyright (c) 2011 Alexandr Ciornii <alexchorny@gmail.com>"
.IP "Copyright (c) 2010, 2011  pilcrow <mjp@pilcrow.madison.wi.us>" 4
.IX Item "Copyright (c) 2010, 2011 pilcrow <mjp@pilcrow.madison.wi.us>"
.IP "Copyright (c) 1999\-2008  Edwin Pratomo" 4
.IX Item "Copyright (c) 1999-2008 Edwin Pratomo"
.IP "Portions Copyright (c) 2001\-2005  Daniel Ritz" 4
.IX Item "Portions Copyright (c) 2001-2005 Daniel Ritz"
.PD
.PP
The DBD::Firebird module is free software. 
You may distribute under the terms of either the \s-1GNU\s0 General Public
License or the Artistic License, as specified in the Perl \s-1README\s0 file.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
An attempt to enumerate all who have contributed patches (may misses some):
Michael Moehle, Igor Klingen, Sergey Skvortsov, Ilya Verlinsky, Pavel
Zheltouhov, Peter Wilkinson, Mark D. Anderson, Michael Samanov, Michael
Arnett, Flemming Frandsen, Mike Shoyher, Christiaan Lademann.