php-doc-en/functions/ibase.xml
Hartmut Holzgraefe 206330a084 <void/>ified
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@47614 c90b9560-bf6c-de11-be94-00142212c4b1
2001-05-16 18:33:21 +00:00

696 lines
21 KiB
XML

<reference id="ref.ibase">
<title>InterBase functions</title>
<titleabbrev>InterBase</titleabbrev>
<partintro>
<para>
InterBase is a popular database put out by Borland/Inprise. More
information about InterBase is available at <ulink
url="&url.ibase;">&url.ibase;</ulink>. Oh, by the way, InterBase
just joined the open source movement!
</para>
<note>
<para>
Full support for InterBase 6 was added in PHP 4.0.
</para>
<para>
This database uses a single quote (') character for escaping, a
behavior similar to the Sybase database, add to your
<filename>php.ini</filename> the following directive:
<informalexample>
<programlisting>
magic_quotes_sybase = On
</programlisting>
</informalexample>
</para>
</note>
</partintro>
<refentry id="function.ibase-connect">
<refnamediv>
<refname>ibase_connect</refname>
<refpurpose>
Open a connection to an InterBase database
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_connect</function></funcdef>
<paramdef>string <parameter>database</parameter></paramdef>
<paramdef>string
<parameter><optional>username</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>password</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>charset</optional></parameter>
</paramdef>
<paramdef>int
<parameter><optional>buffers</optional></parameter>
</paramdef>
<paramdef>int
<parameter><optional>dialect</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>role</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Establishes a connection to an InterBase server.
The <parameter>database</parameter> argument
has to be a valid path to database file on the server it resides on.
If the server is not local, it must be prefixed with either
'hostname:' (TCP/IP), '//hostname/' (NetBEUI) or 'hostname@' (IPX/SPX),
depending on the connection protocol used. <parameter>username</parameter>
and <parameter>password</parameter> can also
be specified with PHP configuration directives ibase.default_user and
ibase.default_password. <parameter>charset</parameter> is the default
character set for a database. <parameter>buffers</parameter> is the number
of database buffers to allocate for the server-side cache. If 0 or omitted,
server chooses its own default. <parameter>dialect</parameter> selects
the default SQL dialect for any statement executed within a connection,
and it defaults to the highest one supported by client libraries.
</para>
<para>
In case a second call is made to
<function>ibase_connect</function> with the same arguments, no new link
will be established, but instead, the link identifier of the already opened
link will be returned. The link to the server will be closed as soon as the
execution of the script ends, unless it's closed earlier by explicitly calling
<function>ibase_close</function>.
<example>
<title><function>Ibase_connect</function> example</title>
<programlisting role="php">
&lt;?php
$dbh = ibase_connect ($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query ($dbh, $stmt);
while ($row = ibase_fetch_object ($sth)) {
print $row->email . "\n";
}
ibase_close ($dbh);
?>
</programlisting>
</example>
</para>
<note>
<para>
<parameter>buffers</parameter> was added in PHP4-RC2.
</para>
</note>
<note>
<para>
<parameter>dialect</parameter> was added in PHP4-RC2. It is functional
only with InterBase 6 and versions higher than that.
</para>
</note>
<note>
<para>
<parameter>role</parameter> was added in PHP4-RC2. It is functional
only with InterBase 5 and versions higher than that.
</para>
</note>
<para>
See also: <function>ibase_pconnect</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-pconnect">
<refnamediv>
<refname>ibase_pconnect</refname>
<refpurpose>
Creates an persistent connection to an InterBase database
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_pconnect</function></funcdef>
<paramdef>string <parameter>database</parameter></paramdef>
<paramdef>string
<parameter><optional>username</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>password</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>charset</optional></parameter>
</paramdef>
<paramdef>int
<parameter><optional>buffers</optional></parameter>
</paramdef>
<paramdef>int
<parameter><optional>dialect</optional></parameter>
</paramdef>
<paramdef>string
<parameter><optional>role</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ibase_pconnect</function> acts very much like
<function>ibase_connect</function> with two major differences.
First, when connecting, the function will first try to find a
(persistent) link that's already opened with the same parameters.
If one is found, an identifier for it will be returned instead of
opening a new connection. Second, the connection to the InterBase
server will not be closed when the execution of the script ends.
Instead, the link will remain open for future use
(<function>ibase_close</function> will not close links established
by <function>ibase_pconnect</function>). This type of link is
therefore called 'persistent'.
</para>
<note>
<para>
<parameter>buffers</parameter> was added in PHP4-RC2.
</para>
</note>
<note>
<para>
<parameter>dialect</parameter> was added in PHP4-RC2. It is functional
only with InterBase 6 and versions higher than that.
</para>
</note>
<note>
<para>
<parameter>role</parameter> was added in PHP4-RC2. It is functional
only with InterBase 5 and versions higher than that.
</para>
</note>
<para>
See also <function>ibase_connect</function> for the meaning of
parameters passed to this function. They are exactly the same.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-close">
<refnamediv>
<refname>ibase_close</refname>
<refpurpose>
Close a connection to an InterBase database
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_close</function></funcdef>
<paramdef>int
<parameter><optional>connection_id</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Closes the link to an InterBase database that's associated with
a connection id returned from <function>ibase_connect</function>.
If the connection id is omitted, the last opened link is assumed.
Default transaction on link is committed, other transactions are
rolled back.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-query">
<refnamediv>
<refname>ibase_query</refname>
<refpurpose>Execute a query on an InterBase database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_query</function></funcdef>
<paramdef>int
<parameter><optional>link_identifier</optional></parameter>
</paramdef>
<paramdef>string
<parameter>query</parameter>
</paramdef>
<paramdef>int
<parameter><optional>bind_args</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<simpara>
Performs a query on an InterBase database, returning a result
identifier for use with <function>ibase_fetch_row</function>,
<function>ibase_fetch_object</function>,
<function>ibase_free_result</function> and
<function>ibase_free_query</function>.
</simpara>
<note>
<para>
Although this function supports variable binding to parameter
placeholders, there is not very much meaning using this capability
with it. For real life use and an example, see
<function>ibase_prepare</function> and
<function>ibase_execute</function>.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.ibase-fetch-row">
<refnamediv>
<refname>ibase_fetch_row</refname>
<refpurpose>Fetch a row from an InterBase database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>ibase_fetch_row</function></funcdef>
<paramdef>int
<parameter>result_identifier</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<simpara>
Returns the next row specified by the result identifier obtained
using the <function>ibase_query</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.ibase-fetch-object">
<refnamediv>
<refname>ibase_fetch_object</refname>
<refpurpose>Get an object from a InterBase database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>object <function>ibase_fetch_object</function></funcdef>
<paramdef>int
<parameter>result_id</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Fetches a row as a pseudo-object from a
<parameter>result_id</parameter> obtained either by
<function>ibase_query</function> or
<function>ibase_execute</function>.
<informalexample>
<programlisting role="php">
&lt;php
$dbh = ibase_connect ($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query ($dbh, $stmt);
while ($row = ibase_fetch_object ($sth)) {
print $row->email . "\n";
}
ibase_close ($dbh);
?>
</programlisting>
</informalexample>
</para>
<para>
See also <function>ibase_fetch_row</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-field-info">
<refnamediv>
<refname>ibase_field_info</refname>
<refpurpose>
Get information about a field
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>ibase_field_info</function></funcdef>
<paramdef>int <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns an array with information about a field after a select
query has been run. The array is in the form of name, alias,
relation, length, type.
<informalexample>
<programlisting role="php">
// helio@helio.com.br 08-Dec-2000 02:53
$rs=ibase_query("Select * from something");
$coln = ibase_num_fields($rs);
for ($i=0 ; $i &lt; $coln ; $i++) {
$col_info = ibase_field_info($rs, $i);
echo "name: ".$col_info['name']."\n";
echo "alias: ".$col_info['alias']."\n";
echo "relation: ".$col_info['relation']."\n";
echo "length: ".$col_info['length']."\n";
echo "type: ".$col_info['type']."\n";
}
</programlisting>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-free-result">
<refnamediv>
<refname>ibase_free_result</refname>
<refpurpose>Free a result set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_free_result</function></funcdef>
<paramdef>int
<parameter>result_identifier</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<simpara>
Free's a result set the has been created by
<function>ibase_query</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.ibase-prepare">
<refnamediv>
<refname>ibase_prepare</refname>
<refpurpose>
Prepare a query for later binding of parameter placeholders and
execution
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_prepare</function></funcdef>
<paramdef>int
<parameter><optional>link_identifier</optional></parameter>
</paramdef>
<paramdef>string <parameter>query</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<simpara>
Prepare a query for later binding of parameter placeholders and
execution (via <function>ibase_execute</function>).
</simpara>
</refsect1>
</refentry>
<refentry id="function.ibase-execute">
<refnamediv>
<refname>ibase_execute</refname>
<refpurpose>Execute a previously prepared query</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_execute</function></funcdef>
<paramdef>int
<parameter>query</parameter>
</paramdef>
<paramdef>int
<parameter><optional>bind_args</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Execute a query prepared by <function>ibase_prepare</function>.
This is a lot more effective than using <function>ibase_query</function>
if you are repeating a same kind of query several times with only
some parameters changing.
<informalexample>
<programlisting role="php">
&lt;?php
$updates = array(
1 => 'Eric',
5 => 'Filip',
7 => 'Larry'
);
$query = ibase_prepare("UPDATE FOO SET BAR = ? WHERE BAZ = ?");
while (list($baz, $bar) = each($updates)) {
ibase_execute($query, $bar, $baz);
}
?>
</programlisting>
</informalexample>
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-trans">
<refnamediv>
<refname>ibase_trans</refname>
<refpurpose>Begin a transaction</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_trans</function></funcdef>
<paramdef>int
<parameter><optional>trans_args</optional></parameter>
</paramdef>
<paramdef>int
<parameter><optional>link_identifier</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Begins a transaction.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-commit">
<refnamediv>
<refname>ibase_commit</refname>
<refpurpose>Commit a transaction</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_commit</function></funcdef>
<paramdef>int
<parameter><optional>link_identifier</optional></parameter>
</paramdef>
<paramdef>int <parameter>trans_number</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Commits transaction <parameter>trans_number</parameter> which was
created with <function>ibase_trans</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-rollback">
<refnamediv>
<refname>ibase_rollback</refname>
<refpurpose>Rolls back a transaction</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_rollback</function></funcdef>
<paramdef>int
<parameter><optional>link_identifier</optional></parameter>
</paramdef>
<paramdef>int <parameter>trans_number</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Rolls back transaction <parameter>trans_number</parameter> which was
created with <function>ibase_trans</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-free-query">
<refnamediv>
<refname>ibase_free_query</refname>
<refpurpose>
Free memory allocated by a prepared query
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_free_query</function></funcdef>
<paramdef>int
<parameter>query</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<simpara>
Free a query prepared by <function>ibase_prepare</function>.
</simpara>
</refsect1>
</refentry>
<refentry id="function.ibase-timefmt">
<refnamediv>
<refname>ibase_timefmt</refname>
<refpurpose>
Sets the format of timestamp, date and time type columns returned from queries
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_timefmt</function></funcdef>
<paramdef>string
<parameter>format</parameter>
</paramdef>
<paramdef>int
<parameter><optional>columntype</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Sets the format of timestamp, date or time type columns returned
from queries. Internally, the columns are formatted by c-function
strftime(), so refer to it's documentation regarding to the format
of the string. <parameter>columntype</parameter> is one of the
constants IBASE_TIMESTAMP, IBASE_DATE and IBASE_TIME. If omitted,
defaults to IBASE_TIMESTAMP for backwards compatibility.
<informalexample>
<programlisting role="php">
&lt;?php
// InterBase 6 TIME-type columns will be returned in
// the form '05 hours 37 minutes'.
ibase_timefmt("%H hours %M minutes", IBASE_TIME);
?>
</programlisting>
</informalexample>
</para>
<para>
You can also set defaults for these formats with PHP configuration
directives ibase.timestampformat, ibase.dateformat and ibase.timeformat.
</para>
<note>
<para>
<parameter>columntype</parameter> was added in PHP 4.0. It has any
meaning only with InterBase version 6 and higher.
</para>
</note>
<note>
<para>
A backwards incompatible change happened in PHP 4.0 when PHP
configuration directive ibase.timeformat was renamed to
ibase.timestampformat and directives ibase.dateformat and
ibase.timeformat were added, so that the names would match better
their functionality.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.ibase-num-fields">
<refnamediv>
<refname>ibase_num_fields</refname>
<refpurpose>
Get the number of fields in a result set
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_num_fields</function></funcdef>
<paramdef>int <parameter>result_id</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns an integer containing the number of fields in a result
set.
<informalexample>
<programlisting role="php">
&lt;?php
$dbh = ibase_connect ($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query ($dbh, $stmt);
if (ibase_num_fields($sth) > 0) {
while ($row = ibase_fetch_object ($sth)) {
print $row->email . "\n";
}
} else {
die ("No Results were found for your query");
}
ibase_close ($dbh);
?>
</programlisting>
</informalexample>
</para>
<para>
See also: <function>ibase_field_info</function>.
</para>
<note>
<para>
<function>Ibase_num_fields</function> is currently not functional
in PHP 4.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.ibase-errmsg">
<refnamediv>
<refname>ibase_errmsg</refname>
<refpurpose>
Returns error messages
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ibase_errmsg</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<simpara>
Returns a string containing an error message.
</simpara>
</refsect1>
</refentry>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->