php-doc-en/functions/ibase.xml
Hartmut Holzgraefe aa046d8616 more skeletons for missing functions
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@65608 c90b9560-bf6c-de11-be94-00142212c4b1
2001-12-18 19:08:15 +00:00

917 lines
26 KiB
XML

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.41 $ -->
<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>
<![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>
<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">
<![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>
<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. 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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ibase_errmsg</function></funcdef>
<void/>
</funcprototype>
</funcsynopsis>
<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>
<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">
<![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>
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">
<![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>
<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-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">
<![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>
<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-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">
<![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>
<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">
<![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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_blob_add</function></funcdef>
<paramdef>int <parameter>blob_id</parameter></paramdef>
<paramdef>string <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_blob_cancel</function></funcdef>
<paramdef>int <parameter>blob_id</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_blob_close</function></funcdef>
<paramdef>int <parameter>blob_id</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_blob_create</function></funcdef>
<paramdef>int <parameter><optional>link_identifier</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_blob_echo</function></funcdef>
<paramdef>string <parameter>blob_id_str</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ibase_blob_get</function></funcdef>
<paramdef>int <parameter>blob_id</parameter></paramdef>
<paramdef>int <parameter>len</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ibase_blob_import</function></funcdef>
<paramdef>int
<parameter><optional>link_identifier</optional></parameter>
</paramdef>
<paramdef>int <parameter>file_id</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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>
<funcsynopsis>
<funcprototype>
<funcdef>object <function>ibase_blob_info</function></funcdef>
<paramdef>string <parameter>blob_id_str</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
<refentry id='function.ibase-blob-open'>
<refnamediv>
<refname>ibase_blob_open</refname>
<refpurpose>
Open blob for retriving data parts
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ibase_blob_open</function></funcdef>
<paramdef>string <parameter>blob_id</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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
-->