php-doc-en/functions/ibase.xml
Hartmut Holzgraefe 7839d91186 added DO NOT EDIT noctice to old english functions files,
removing the others


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
2002-04-17 19:58:46 +00:00

830 lines
26 KiB
XML

<!-- D O N O T E D I T T H I S F I L E ! ! !
it is still here for historical reasons only
(as translators may need to check old revision diffs)
if you want to change things documented in this file
you should now edit the files found under en/reference
instead -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.47 $ -->
<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
&php.ini; the following directive:
<informalexample>
<programlisting>
<![CDATA[
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>
<methodsynopsis>
<type>int</type><methodname>ibase_connect</methodname>
<methodparam><type>string</type><parameter>database</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>username</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>password</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>buffers</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>dialect</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>role</parameter></methodparam>
</methodsynopsis>
<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">
<![CDATA[
<?php
$dbh = ibase_connect($host, $username, $password);
$stmt = 'SELECT * FROM tblname';
$sth = ibase_query($dbh, $stmt);
while ($row = ibase_fetch_object($sth)) {
echo $row->email, "\n";
}
ibase_free_result($sth);
ibase_close($dbh);
?>
]]>
</programlisting>
</example>
</para>
<note>
<para>
<parameter>buffers</parameter> was added in PHP 4.0RC2.
</para>
</note>
<note>
<para>
<parameter>dialect</parameter> was added in PHP 4.0RC2. It is functional
only with InterBase 6 and versions higher than that.
</para>
</note>
<note>
<para>
<parameter>role</parameter> was added in PHP 4.0RC2. 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>
<methodsynopsis>
<type>int</type><methodname>ibase_pconnect</methodname>
<methodparam><type>string</type><parameter>database</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>username</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>password</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>buffers</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>dialect</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>role</parameter></methodparam>
</methodsynopsis>
<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>
<methodsynopsis>
<type>int</type><methodname>ibase_close</methodname>
<methodparam choice="opt"><type>int</type><parameter>connection_id</parameter></methodparam>
</methodsynopsis>
<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>
<methodsynopsis>
<type>int</type><methodname>ibase_query</methodname>
<methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>bind_args</parameter></methodparam>
</methodsynopsis>
<simpara>
Performs a query on an InterBase database. If the query is not
successful, returns &false;. If it is successful and there are resulting
rows (such as with a SELECT query), returns a result identifier. If
the query was successful and there were no results, returns &true;.
Returns &false; if the query fails.
</simpara>
<para>
See also <function>ibase_errmsg</function>,
<function>ibase_fetch_row</function>,
<function>ibase_fetch_object</function>, and
<function>ibase_free_result</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ibase-errmsg">
<refnamediv>
<refname>ibase_errmsg</refname>
<refpurpose>
Returns error messages
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>ibase_errmsg</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns a string containing an error message.
</simpara>
</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>
<methodsynopsis>
<type>array</type><methodname>ibase_fetch_row</methodname>
<methodparam><type>int</type><parameter>result_identifier</parameter></methodparam>
</methodsynopsis>
<para>
Returns an array that corresponds to the fetched row, or &false;
if there are no more rows.
</para>
<para>
<function>ibase_fetch_row</function> fetches one row of data from
the result associated with the specified
<parameter>result_identifier</parameter>. The row is returned as
an array. Each result column is stored in an array offset,
starting at offset 0.
</para>
<para>
Subsequent call to <function>ibase_fetch_row</function> would
return the next row in the result set, or &false; if there are no
more rows.
</para>
</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>
<methodsynopsis>
<type>object</type><methodname>ibase_fetch_object</methodname>
<methodparam><type>int</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<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">
<![CDATA[
<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>
Subsequent call to <function>ibase_fetch_object</function> would
return the next row in the result set, or &false; if there are no
more rows.
</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>
<methodsynopsis>
<type>array</type><methodname>ibase_field_info</methodname>
<methodparam><type>int</type><parameter>result</parameter></methodparam>
<methodparam><type>int</type><parameter>field number</parameter></methodparam>
</methodsynopsis>
<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">
<![CDATA[
$rs=ibase_query("SELECT * FROM tablename");
$coln = ibase_num_fields($rs);
for ($i=0; $i < $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-query">
<refnamediv>
<refname>ibase_free_query</refname>
<refpurpose>
Free memory allocated by a prepared query
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ibase_free_query</methodname>
<methodparam><type>int</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<simpara>
Free a query prepared by <function>ibase_prepare</function>.
</simpara>
</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>
<methodsynopsis>
<type>int</type><methodname>ibase_free_result</methodname>
<methodparam><type>int</type><parameter>result_identifier</parameter></methodparam>
</methodsynopsis>
<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>
<methodsynopsis>
<type>int</type><methodname>ibase_prepare</methodname>
<methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<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>
<methodsynopsis>
<type>int</type><methodname>ibase_execute</methodname>
<methodparam><type>int</type><parameter>query</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>bind_args</parameter></methodparam>
</methodsynopsis>
<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">
<![CDATA[
<?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>
<methodsynopsis>
<type>int</type><methodname>ibase_trans</methodname>
<methodparam choice="opt"><type>int</type><parameter>trans_args</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<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>
<methodsynopsis>
<type>int</type><methodname>ibase_commit</methodname>
<methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
<methodparam><type>int</type><parameter>trans_number</parameter></methodparam>
</methodsynopsis>
<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>
<methodsynopsis>
<type>int</type><methodname>ibase_rollback</methodname>
<methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
<methodparam><type>int</type><parameter>trans_number</parameter></methodparam>
</methodsynopsis>
<para>
Rolls back transaction <parameter>trans_number</parameter> which was
created with <function>ibase_trans</function>.
</para>
</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>
<methodsynopsis>
<type>int</type><methodname>ibase_timefmt</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>columntype</parameter></methodparam>
</methodsynopsis>
<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">
<![CDATA[
<?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>
<methodsynopsis>
<type>int</type><methodname>ibase_num_fields</methodname>
<methodparam><type>int</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
Returns an integer containing the number of fields in a result
set.
<informalexample>
<programlisting role="php">
<![CDATA[
<?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>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-add'>
<refnamediv>
<refname>ibase_blob_add</refname>
<refpurpose>
Add data into created blob
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ibase_blob_add</methodname>
<methodparam><type>int</type><parameter>blob_id</parameter></methodparam>
<methodparam><type>string</type><parameter>data</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-cancel'>
<refnamediv>
<refname>ibase_blob_cancel</refname>
<refpurpose>
Cancel creating blob
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ibase_blob_cancel</methodname>
<methodparam><type>int</type><parameter>blob_id</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-close'>
<refnamediv>
<refname>ibase_blob_close</refname>
<refpurpose>
Close blob
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ibase_blob_close</methodname>
<methodparam><type>int</type><parameter>blob_id</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-create'>
<refnamediv>
<refname>ibase_blob_create</refname>
<refpurpose>
Create blob for adding data
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ibase_blob_create</methodname>
<methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-echo'>
<refnamediv>
<refname>ibase_blob_echo</refname>
<refpurpose>
Output blob contents to browser
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ibase_blob_echo</methodname>
<methodparam><type>string</type><parameter>blob_id_str</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-get'>
<refnamediv>
<refname>ibase_blob_get</refname>
<refpurpose>
Get len bytes data from open blob
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>ibase_blob_get</methodname>
<methodparam><type>int</type><parameter>blob_id</parameter></methodparam>
<methodparam><type>int</type><parameter>len</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-import'>
<refnamediv>
<refname>ibase_blob_import</refname>
<refpurpose>
Create blob, copy file in it, and close it
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>ibase_blob_import</methodname>
<methodparam choice="opt"><type>int</type><parameter>link_identifier</parameter></methodparam>
<methodparam><type>int</type><parameter>file_id</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-info'>
<refnamediv>
<refname>ibase_blob_info</refname>
<refpurpose>
Return blob length and other useful info
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>object</type><methodname>ibase_blob_info</methodname>
<methodparam><type>string</type><parameter>blob_id_str</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-open'>
<refnamediv>
<refname>ibase_blob_open</refname>
<refpurpose>
Open blob for retrieving data parts
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>ibase_blob_open</methodname>
<methodparam><type>string</type><parameter>blob_id</parameter></methodparam>
</methodsynopsis>
<para>
&warn.undocumented.func;
</para>
</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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->