mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-27 22:38:55 +00:00
ae6d0d058b
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@47413 c90b9560-bf6c-de11-be94-00142212c4b1
1789 lines
57 KiB
XML
1789 lines
57 KiB
XML
<reference id="ref.fbsql">
|
|
<title>FrontBase functions</title>
|
|
<titleabbrev>FrontBase</titleabbrev>
|
|
<partintro>
|
|
<simpara>
|
|
These functions allow you to access FrontBase database servers. In
|
|
order to have these functions available, you must compile php
|
|
with fbsql support by using the
|
|
<option role="configure">--with-fbsql</option> option. If you
|
|
use this option without specifying the path to fbsql, php will
|
|
search for the fbsql client libraries in the default installation
|
|
location for the platform. Users who installed FrontBase in
|
|
a non standard directory should always specify the path to fbsql:
|
|
<option role="configure">--with-fbsql=/path/to/fbsql</option>.
|
|
This will force php to use the client libraries installed by
|
|
FrontBase, avoiding any conflicts.
|
|
</simpara>
|
|
<simpara>
|
|
More information about FrontBase can be found at <ulink
|
|
url="&url.fbsql;">&url.fbsql;</ulink>.
|
|
</simpara>
|
|
<simpara>
|
|
Documentation for FrontBase can be found at <ulink
|
|
url="&url.fbsql.docs;">&url.fbsql.docs;</ulink>.
|
|
</simpara>
|
|
<simpara>
|
|
Frontbase support has been added to PHP 4.0.6.
|
|
</simpara>
|
|
</partintro>
|
|
|
|
<refentry id="function.fbsql-affected-rows">
|
|
<refnamediv>
|
|
<refname>fbsql_affected_rows</refname>
|
|
<refpurpose>Get number of affected rows in previous FrontBase
|
|
operation</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fbsql_affected_rows</function></funcdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_affected_rows</function> returns the number
|
|
of rows affected by the last INSERT, UPDATE or DELETE query
|
|
associated with <parameter>link_identifier</parameter>. If the
|
|
link identifier isn't specified, the last link opened by
|
|
<function>fbsql_connect</function> is assumed.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If you are using transactions, you need to call
|
|
<function>fbsql_affected_rows</function> after your INSERT,
|
|
UPDATE, or DELETE query, not after the commit.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
If the last query was a DELETE query with no WHERE clause, all
|
|
of the records will have been deleted from the table but this
|
|
function will return zero.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
When using UPDATE, FrontBase will not update columns where the new
|
|
value is the same as the old value. This creates the possiblity
|
|
that <function>fbsql_affected_rows</function> may not actually
|
|
equal the number of rows matched, only the number of rows that
|
|
were literally affected by the query.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
If the last query failed, this function will return -1.
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_num_rows</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-autocommit">
|
|
<refnamediv>
|
|
<refname>fbsql_autocommit</refname>
|
|
<refpurpose>Enable or disable autocommit.</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>fbsql_autocommit</function></funcdef>
|
|
<paramdef>resource
|
|
<parameter>link_identifier</parameter>
|
|
</paramdef>
|
|
<paramdef>bool
|
|
<parameter>
|
|
<optional>OnOff</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_autocommit</function> returns the current
|
|
autocommit status. if the optional OnOff parameter is
|
|
given the auto commit status will be changed.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-change-user">
|
|
<refnamediv>
|
|
<refname>fbsql_change_user</refname>
|
|
<refpurpose>
|
|
Change logged in user of the active connection
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_change_user</function></funcdef>
|
|
<paramdef>string <parameter>user</parameter></paramdef>
|
|
<paramdef>string <parameter>password</parameter></paramdef>
|
|
<paramdef>string
|
|
<parameter>
|
|
<optional>database</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_change_user</function> changes the logged in user
|
|
of the current active connection, or the connection given by the
|
|
optional parameter link_identifier. If a database is
|
|
specified, this will default or current database after the user
|
|
has been changed. If the new user and password authorization fails,
|
|
the current connected user stays active.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-close">
|
|
<refnamediv>
|
|
<refname>fbsql_close</refname>
|
|
<refpurpose>Close FrontBase connection</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>boolean <function>fbsql_close</function></funcdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: <literal>TRUE</literal> on success, <literal>FALSE</literal> on error.
|
|
</para>
|
|
<para> <function>fbsql_close</function> closes the connection to
|
|
the FrontBase server that's associated with the specified link
|
|
identifier. If <parameter>link_identifier</parameter> isn't
|
|
specified, the last opened link is used.
|
|
</para>
|
|
<para>
|
|
Using <function>fbsql_close</function> isn't usually necessary,
|
|
as non-persistent open links are automatically closed at the end
|
|
of the script's execution.
|
|
</para>
|
|
<example>
|
|
<title><function>fbsql_close</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$link = fbsql_connect ("localhost", "_SYSTEM", "secret")
|
|
or die ("Could not connect");
|
|
print ("Connected successfully");
|
|
fbsql_close ($link);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See also: <function>fbsql_connect</function>, and
|
|
<function>fbsql_pconnect</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-connect">
|
|
<refnamediv>
|
|
<refname>fbsql_connect</refname>
|
|
<refpurpose>Open a connection to a FrontBase Server</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_connect</function></funcdef>
|
|
<paramdef>string
|
|
<parameter>
|
|
<optional>hostname
|
|
</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
<paramdef>string
|
|
<parameter>
|
|
<optional>username</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
<paramdef>string
|
|
<parameter>
|
|
<optional>password</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a positive FrontBase link identifier on success, or an error
|
|
message on failure.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_connect</function> establishes a connection
|
|
to a FrontBase server. The following defaults are assumed for
|
|
missing optional parameters: <parameter>hostname</parameter> =
|
|
'NULL', <parameter>username</parameter> = '_SYSTEM' and
|
|
<parameter>password</parameter> = empty password.
|
|
</para>
|
|
<para>
|
|
If a second call is made to <function>fbsql_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.
|
|
</para>
|
|
<para>
|
|
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>fbsql_close</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>fbsql_connect</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
|
|
$link = fbsql_connect ("localhost", "_SYSTEM", "secret")
|
|
or die ("Could not connect");
|
|
print ("Connected successfully");
|
|
fbsql_close ($link);
|
|
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See also
|
|
<function>fbsql_pconnect</function>, and
|
|
<function>fbsql_close</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-create-db">
|
|
<refnamediv>
|
|
<refname>fbsql_create_db</refname>
|
|
<refpurpose>Create a FrontBase database</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>fbsql_create_db</function></funcdef>
|
|
<paramdef>string <parameter>database name</parameter></paramdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_create_db</function> attempts to create a new
|
|
database on the server associated with the specified link
|
|
identifier.
|
|
</para>
|
|
<example>
|
|
<title><function>fbsql_create_db</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$link = fbsql_pconnect ("localhost", "_SYSTEM", "secret")
|
|
or die ("Could not connect");
|
|
if (fbsql_create_db ("my_db")) {
|
|
print("Database created successfully\n");
|
|
} else {
|
|
printf("Error creating database: %s\n", fbsql_error ());
|
|
}
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See also: <function>fbsql_drop_db</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-data-seek">
|
|
<refnamediv>
|
|
<refname>fbsql_data_seek</refname>
|
|
<refpurpose>Move internal result pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>fbsql_data_seek</function></funcdef>
|
|
<paramdef>resource <parameter>result_identifier</parameter></paramdef>
|
|
<paramdef>int <parameter>row_number</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: <literal>TRUE</literal> on success, <literal>FALSE</literal> on failure.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_data_seek</function> moves the internal row
|
|
pointer of the FrontBase result associated with the specified result
|
|
identifier to point to the specified row number. The next call
|
|
to <function>fbsql_fetch_row</function> would return that row.
|
|
</para>
|
|
<para>
|
|
<parameter>Row_number</parameter> starts at 0.
|
|
</para>
|
|
|
|
<example>
|
|
<title><function>fbsql_data_seek</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$link = fbsql_pconnect ("localhost", "_SYSTEM", "secret")
|
|
or die ("Could not connect");
|
|
|
|
fbsql_select_db ("samp_db")
|
|
or die ("Could not select database");
|
|
|
|
$query = "SELECT last_name, first_name FROM friends;";
|
|
$result = fbsql_query ($query)
|
|
or die ("Query failed");
|
|
|
|
# fetch rows in reverse order
|
|
|
|
for ($i = fbsql_num_rows ($result) - 1; $i >=0; $i--) {
|
|
if (!fbsql_data_seek ($result, $i)) {
|
|
printf ("Cannot seek to row %d\n", $i);
|
|
continue;
|
|
}
|
|
|
|
if(!($row = fbsql_fetch_object ($result)))
|
|
continue;
|
|
|
|
printf("%s %s<BR>\n", $row->last_name, $row->first_name);
|
|
}
|
|
|
|
fbsql_free_result ($result);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-db-query">
|
|
<refnamediv>
|
|
<refname>fbsql_db_query</refname>
|
|
<refpurpose>Send a FrontBase query</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_db_query</function></funcdef>
|
|
<paramdef>string <parameter>database</parameter></paramdef>
|
|
<paramdef>string <parameter>query</parameter></paramdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: A positive FrontBase result identifier to the query result,
|
|
or <literal>FALSE</literal> on error.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_db_query</function> selects a database and
|
|
executes a query on it. If the optional link identifier isn't
|
|
specified, the function will try to find an open link to the
|
|
FrontBase server and if no such link is found it'll try to create one
|
|
as if <function>fbsql_connect</function> was called with no
|
|
arguments
|
|
</para>
|
|
<para>
|
|
See also <function>fbsql_connect</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-drop-db">
|
|
<refnamediv>
|
|
<refname>fbsql_drop_db</refname>
|
|
<refpurpose>Drop (delete) a FrontBase database</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>fbsql_drop_db</function></funcdef>
|
|
<paramdef>string <parameter>database_name</parameter></paramdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: <literal>TRUE</literal> on success, <literal>FALSE</literal> on failure.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_drop_db</function> attempts to drop (remove) an
|
|
entire database from the server associated with the specified
|
|
link identifier.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-errno">
|
|
<refnamediv>
|
|
<refname>fbsql_errno</refname>
|
|
<refpurpose>Returns the numerical value of the error message from previous
|
|
FrontBase operation</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fbsql_errno</function></funcdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the error number from the last fbsql function, or
|
|
<literal>0</literal> (zero) if no error occurred.
|
|
</para>
|
|
<para>
|
|
Errors coming back from the fbsql database backend dont
|
|
issue warnings. Instead, use <function>fbsql_errno</function> to
|
|
retrieve the error code. Note that this function only returns the
|
|
error code from the most recently executed fbsql function (not
|
|
including <function>fbsql_error</function> and
|
|
<function>fbsql_errno</function>), so if you want to use it,
|
|
make sure you check the value before calling another fbsql
|
|
function.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<?php
|
|
fbsql_connect("marliesle");
|
|
echo fbsql_errno().": ".fbsql_error()."<BR>";
|
|
fbsql_select_db("nonexistentdb");
|
|
echo fbsql_errno().": ".fbsql_error()."<BR>";
|
|
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
|
|
echo fbsql_errno().": ".fbsql_error()."<BR>";
|
|
?>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_error</function>,
|
|
<function>fbsql_warnings</function>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-error">
|
|
<refnamediv>
|
|
<refname>fbsql_error</refname>
|
|
<refpurpose>Returns the text of the error message from previous
|
|
FrontBase operation</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fbsql_error</function></funcdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the error text from the last fbsql function, or
|
|
<literal>''</literal> (the empty string) if no error occurred.
|
|
</para>
|
|
<para>
|
|
Errors coming back from the fbsql database backend dont
|
|
issue warnings. Instead, use <function>fbsql_error</function> to
|
|
retrieve the error text. Note that this function only returns the
|
|
error text from the most recently executed fbsql function (not
|
|
including <function>fbsql_error</function> and
|
|
<function>fbsql_errno</function>), so if you want to use it, make
|
|
sure you check the value before calling another fbsql function.
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<?php
|
|
fbsql_connect("marliesle");
|
|
echo fbsql_errno().": ".fbsql_error()."<BR>";
|
|
fbsql_select_db("nonexistentdb");
|
|
echo fbsql_errno().": ".fbsql_error()."<BR>";
|
|
$conn = fbsql_query("SELECT * FROM nonexistenttable;");
|
|
echo fbsql_errno().": ".fbsql_error()."<BR>";
|
|
?>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_errno</function>,
|
|
<function>fbsql_warnings</function>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-fetch-array">
|
|
<refnamediv>
|
|
<refname>fbsql_fetch_array</refname>
|
|
<refpurpose>
|
|
Fetch a result row as an associative array, a numeric array, or both.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>fbsql_fetch_array</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>result_type</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an array that corresponds to the fetched row, or <literal>FALSE</literal>
|
|
if there are no more rows.</para>
|
|
<para>
|
|
<function>fbsql_fetch_array</function> is an extended version of
|
|
<function>fbsql_fetch_row</function>. In addition to storing the
|
|
data in the numeric indices of the result array, it also stores
|
|
the data in associative indices, using the field names as keys.
|
|
</para>
|
|
<para>
|
|
If two or more columns of the result have the same field names,
|
|
the last column will take precedence. To access the other column(s)
|
|
of the same name, you must the numeric index of the column or
|
|
make an alias for the column.
|
|
<informalexample>
|
|
<programlisting>
|
|
select t1.f1 as foo t2.f1 as bar from t1, t2
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
An important thing to note is that using
|
|
<function>fbsql_fetch_array</function> is NOT significantly
|
|
slower than using <function>fbsql_fetch_row</function>, while it
|
|
provides a significant added value.
|
|
</para>
|
|
<para>
|
|
The optional second argument <parameter>result_type</parameter>
|
|
in <function>fbsql_fetch_array</function> is a constant and can
|
|
take the following values: FBSQL_ASSOC, FBSQL_NUM, and
|
|
FBSQL_BOTH.
|
|
</para>
|
|
<para>
|
|
For further details, see also
|
|
<function>fbsql_fetch_row</function> and <function>fbsql_fetch_assoc</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>fbsql_fetch_array</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
fbsql_connect ($host, $user, $password);
|
|
$result = fbsql_db_query ("database","select user_id, fullname from table");
|
|
while ($row = fbsql_fetch_array ($result)) {
|
|
echo "user_id: ".$row["user_id"]."<br>\n";
|
|
echo "user_id: ".$row[0]."<br>\n";
|
|
echo "fullname: ".$row["fullname"]."<br>\n";
|
|
echo "fullname: ".$row[1]."<br>\n";
|
|
}
|
|
fbsql_free_result ($result);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-fetch-assoc">
|
|
<refnamediv>
|
|
<refname>fbsql_fetch_assoc</refname>
|
|
<refpurpose>
|
|
Fetch a result row as an associative array
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>fbsql_fetch_assoc</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an associative array that corresponds to the fetched row,
|
|
or <literal>FALSE</literal> if there are no more rows.</para>
|
|
<para>
|
|
<function>fbsql_fetch_assoc</function> is equivalent to calling
|
|
<function>fbsql_fetch_array</function> with FBSQL_ASSOC for the
|
|
optional second parameter. It only returns an associative array.
|
|
This is the way <function>fbsql_fetch_array</function> originally
|
|
worked. If you need the numeric indices as well as the
|
|
associative, use <function>fbsql_fetch_array</function>.
|
|
</para>
|
|
<para>
|
|
If two or more columns of the result have the same field names,
|
|
the last column will take precedence. To access the other column(s)
|
|
of the same name, you must use <function>fbsql_fetch_array</function> and
|
|
have it return the numeric indices as well.
|
|
</para>
|
|
<para>
|
|
An important thing to note is that using
|
|
<function>fbsql_fetch_assoc</function> is NOT significantly
|
|
slower than using <function>fbsql_fetch_row</function>, while it
|
|
provides a significant added value.
|
|
</para>
|
|
<para>
|
|
For further details, see also
|
|
<function>fbsql_fetch_row</function> and <function>fbsql_fetch_array</function>.
|
|
</para>
|
|
<example>
|
|
<title><function>fbsql_fetch_assoc</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
fbsql_connect ($host, $user, $password);
|
|
$result = fbsql_db_query ("database","select * from table");
|
|
while ($row = fbsql_fetch_assoc ($result)) {
|
|
echo $row["user_id"];
|
|
echo $row["fullname"];
|
|
}
|
|
fbsql_free_result ($result);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-fetch-field">
|
|
<refnamediv>
|
|
<refname>fbsql_fetch_field</refname>
|
|
<refpurpose>
|
|
Get column information from a result and return as an object
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>object <function>fbsql_fetch_field</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>field_offset</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an object containing field information.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_fetch_field</function> can be used in order to
|
|
obtain information about fields in a certain query result. If
|
|
the field offset isn't specified, the next field that wasn't yet
|
|
retrieved by <function>fbsql_fetch_field</function> is retrieved.
|
|
</para>
|
|
<para>
|
|
The properties of the object are:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
name - column name
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
table - name of the table the column belongs to
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
max_length - maximum length of the column
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
not_null - 1 if the column cannot be null
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
type - the type of the column
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<example>
|
|
<title><function>fbsql_fetch_field</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
fbsql_connect ($host, $user, $password)
|
|
or die ("Could not connect");
|
|
$result = fbsql_db_query ("database", "select * from table")
|
|
or die ("Query failed");
|
|
# get column metadata
|
|
$i = 0;
|
|
while ($i < fbsql_num_fields ($result)) {
|
|
echo "Information for column $i:<BR>\n";
|
|
$meta = fbsql_fetch_field ($result);
|
|
if (!$meta) {
|
|
echo "No information available<BR>\n";
|
|
}
|
|
echo "<PRE>
|
|
max_length: $meta->max_length
|
|
name: $meta->name
|
|
not_null: $meta->not_null
|
|
table: $meta->table
|
|
type: $meta->type
|
|
</PRE>";
|
|
$i++;
|
|
}
|
|
fbsql_free_result ($result);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See also <function>fbsql_field_seek</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-fetch-lengths">
|
|
<refnamediv>
|
|
<refname>fbsql_fetch_lengths</refname>
|
|
<refpurpose>
|
|
Get the length of each output in a result
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>fbsql_fetch_lengths</function></funcdef>
|
|
<paramdef>resource
|
|
<parameter><optional>result</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: An array that corresponds to the lengths of each field
|
|
in the last row fetched by <function>fbsql_fetch_row</function>,
|
|
or <literal>FALSE</literal> on error.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_fetch_lengths</function> stores the lengths of
|
|
each result column in the last row returned by
|
|
<function>fbsql_fetch_row</function>,
|
|
<function>fbsql_fetch_array</function>, and
|
|
<function>fbsql_fetch_object</function> in an array, starting at
|
|
offset 0.
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_fetch_row</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-fetch-object">
|
|
<refnamediv>
|
|
<refname>fbsql_fetch_object</refname>
|
|
<refpurpose>Fetch a result row as an object</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>object <function>fbsql_fetch_object</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>result_type</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an object with properties that correspond to the fetched
|
|
row, or <literal>FALSE</literal> if there are no more rows.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_fetch_object</function> is similar to
|
|
<function>fbsql_fetch_array</function>, with one difference - an
|
|
object is returned, instead of an array. Indirectly, that means
|
|
that you can only access the data by the field names, and not by
|
|
their offsets (numbers are illegal property names).
|
|
</para>
|
|
<para>
|
|
The optional argument <parameter>result_type</parameter> is a
|
|
constant and can take the following values: FBSQL_ASSOC,
|
|
FBSQL_NUM, and FBSQL_BOTH.
|
|
</para>
|
|
<para>
|
|
Speed-wise, the function is identical to
|
|
<function>fbsql_fetch_array</function>, and almost as quick as
|
|
<function>fbsql_fetch_row</function> (the difference is
|
|
insignificant).
|
|
<example>
|
|
<title><function>fbsql_fetch_object</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
fbsql_connect ($host, $user, $password);
|
|
$result = fbsql_db_query ("database", "select * from table");
|
|
while ($row = fbsql_fetch_object ($result)) {
|
|
echo $row->user_id;
|
|
echo $row->fullname;
|
|
}
|
|
fbsql_free_result ($result);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_fetch_array</function> and
|
|
<function>fbsql_fetch_row</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-fetch-row">
|
|
<refnamediv>
|
|
<refname>fbsql_fetch_row</refname>
|
|
<refpurpose>Get a result row as an enumerated array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>fbsql_fetch_row</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: An array that corresponds to the fetched row, or <literal>FALSE</literal>
|
|
if there are no more rows.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_fetch_row</function> fetches one row of data from
|
|
the result associated with the specified result identifier. 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>fbsql_fetch_row</function> would
|
|
return the next row in the result set, or <literal>FALSE</literal> if there are no
|
|
more rows.
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_fetch_array</function>,
|
|
<function>fbsql_fetch_object</function>,
|
|
<function>fbsql_data_seek</function>,
|
|
<function>fbsql_fetch_lengths</function>, and
|
|
<function>fbsql_result</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-field-flags">
|
|
<refnamediv>
|
|
<refname>fbsql_field_flags</refname>
|
|
<refpurpose>
|
|
Get the flags associated with the specified field in a result
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fbsql_field_flags</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>field_offset</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_field_flags</function> returns the field flags of
|
|
the specified field. The flags are reported as a single word
|
|
per flag separated by a single space, so that you can split the
|
|
returned value using <function>explode</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-field-name">
|
|
<refnamediv>
|
|
<refname>fbsql_field_name</refname>
|
|
<refpurpose>
|
|
Get the name of the specified field in a result
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fbsql_field_name</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>field_index</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_field_name</function> returns the name of the
|
|
specified field index. <parameter>result</parameter> must be a
|
|
valid result identifier and <parameter>field_index</parameter> is
|
|
the numerical offset of the field.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
<parameter>field_index</parameter> starts at 0.
|
|
</para>
|
|
<para>
|
|
e.g. The index of the third field would actually be 2, the index
|
|
of the fourth field would be 3 and so on.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<example>
|
|
<title><function>fbsql_field_name</function> example</title>
|
|
<programlisting role="php">
|
|
// The users table consists of three fields:
|
|
// user_id
|
|
// username
|
|
// password.
|
|
|
|
$res = fbsql_db_query("users", "select * from users", $link);
|
|
|
|
echo fbsql_field_name($res, 0) . "\n";
|
|
echo fbsql_field_name($res, 2);
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The above example would produce the following output:
|
|
<informalexample>
|
|
<programlisting>
|
|
user_id
|
|
password
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-field-len">
|
|
<refnamediv>
|
|
<refname>fbsql_field_len</refname>
|
|
<refpurpose>
|
|
Returns the length of the specified field
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fbsql_field_len</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>field_offset</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_field_len</function> returns the length of the
|
|
specified field.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-field-seek">
|
|
<refnamediv>
|
|
<refname>fbsql_field_seek</refname>
|
|
<refpurpose>
|
|
Set result pointer to a specified field offset
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>fbsql_field_seek</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>field_offset</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Seeks to the specified field offset. If the next call to
|
|
<function>fbsql_fetch_field</function> doesn't include a field
|
|
offset, the field offset specified in
|
|
<function>fbsql_field_seek</function> will be returned.
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_fetch_field</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-field-table">
|
|
<refnamediv>
|
|
<refname>fbsql_field_table</refname>
|
|
<refpurpose>
|
|
Get name of the table the specified field is in
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fbsql_field_table</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>field_offset</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the name of the table that the specifed field is
|
|
in.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-field-type">
|
|
<refnamediv>
|
|
<refname>fbsql_field_type</refname>
|
|
<refpurpose>
|
|
Get the type of the specified field in a result
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fbsql_field_type</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>field_offset</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_field_type</function> is similar to the
|
|
<function>fbsql_field_name</function> function. The arguments are
|
|
identical, but the field type is returned instead. The field type
|
|
will be one of "int", "real", "string", "blob", and others as
|
|
detailed in the <ulink url="&url.fbsql.docs;">FrontBase
|
|
documentation</ulink>.
|
|
<example>
|
|
<title><function>fbsql_field_type</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
|
|
fbsql_connect ("localhost", "_SYSTEM", "");
|
|
fbsql_select_db ("wisconsin");
|
|
$result = fbsql_query ("SELECT * FROM onek;");
|
|
$fields = fbsql_num_fields ($result);
|
|
$rows = fbsql_num_rows ($result);
|
|
$i = 0;
|
|
$table = fbsql_field_table ($result, $i);
|
|
echo "Your '".$table."' table has ".$fields." fields and ".$rows." records <BR>";
|
|
echo "The table has the following fields <BR>";
|
|
while ($i < $fields) {
|
|
$type = fbsql_field_type ($result, $i);
|
|
$name = fbsql_field_name ($result, $i);
|
|
$len = fbsql_field_len ($result, $i);
|
|
$flags = fbsql_field_flags ($result, $i);
|
|
echo $type." ".$name." ".$len." ".$flags."<BR>";
|
|
$i++;
|
|
}
|
|
fbsql_close();
|
|
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-free-result">
|
|
<refnamediv>
|
|
<refname>fbsql_free_result</refname>
|
|
<refpurpose>Free result memory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>fbsql_free_result</function></funcdef>
|
|
<paramdef>int <parameter>result</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_free_result</function> will free all memory
|
|
associated with the result identifier <parameter>result</parameter>.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_free_result</function> only needs to be called if
|
|
you are concerned about how much memory is being used for queries
|
|
that return large result sets. All associated result memory is
|
|
automatically freed at the end of the script's execution.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-insert-id">
|
|
<refnamediv>
|
|
<refname>fbsql_insert_id</refname>
|
|
<refpurpose>
|
|
Get the id generated from the previous INSERT operation
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fbsql_insert_id</function></funcdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_insert_id</function> returns the ID generated for
|
|
an column defined as DEFAULT UNIQUE by the previous INSERT query using the
|
|
given <parameter>link_identifier</parameter>. If
|
|
<parameter>link_identifier</parameter> isn't specified, the last
|
|
opened link is assumed.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_insert_id</function> returns 0 if the previous
|
|
query does not generate an DEFAULT UNIQUE value. If you need to
|
|
save the value for later, be sure to call fbsql_insert_id()
|
|
immediately after the query that generates the value.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The value of the FrontBase SQL function
|
|
<literal>LAST_INSERT_ID()</literal> always contains the most
|
|
recently generated DEFAULT UNIQUE value, and is not reset
|
|
between queries.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-list-dbs">
|
|
<refnamediv>
|
|
<refname>fbsql_list_dbs</refname>
|
|
<refpurpose>
|
|
List databases available on a FrontBase server
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_list_dbs</function></funcdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_list_dbs</function> will return a result pointer
|
|
containing the databases available from the current fbsql
|
|
daemon. Use the <function>fbsql_tablename</function> function to
|
|
traverse this result pointer.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>fbsql_list_dbs</function> example</title>
|
|
<programlisting role="php">
|
|
$link = fbsql_connect('localhost', 'myname', 'secret');
|
|
$db_list = fbsql_list_dbs($link);
|
|
|
|
while ($row = fbsql_fetch_object($db_list)) {
|
|
echo $row->Database . "\n";
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The above example would produce the following output:
|
|
<informalexample>
|
|
<programlisting>
|
|
database1
|
|
database2
|
|
database3
|
|
...
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The above code would just as easily work with
|
|
<function>fbsql_fetch_row</function> or other similar functions.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-list-fields">
|
|
<refnamediv>
|
|
<refname>fbsql_list_fields</refname>
|
|
<refpurpose>List FrontBase result fields</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_list_fields</function></funcdef>
|
|
<paramdef>string <parameter>database_name</parameter></paramdef>
|
|
<paramdef>string <parameter>table_name</parameter></paramdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_list_fields</function> retrieves information
|
|
about the given tablename. Arguments are the database name and
|
|
the table name. A result pointer is returned which can be used
|
|
with <function>fbsql_field_flags</function>,
|
|
<function>fbsql_field_len</function>,
|
|
<function>fbsql_field_name</function>, and
|
|
<function>fbsql_field_type</function>.
|
|
</para>
|
|
<para>
|
|
A result identifier is a positive integer. The function returns
|
|
-1 if a error occurs. A string describing the error will be
|
|
placed in <literal>$phperrmsg</literal>, and unless the function
|
|
was called as <literal>@fbsql()</literal> then this error string
|
|
will also be printed out.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>fbsql_list_fields</function> example</title>
|
|
<programlisting role="php">
|
|
$link = fbsql_connect('localhost', 'myname', 'secret');
|
|
|
|
$fields = fbsql_list_fields("database1", "table1", $link);
|
|
$columns = fbsql_num_fields($fields);
|
|
|
|
for ($i = 0; $i < $columns; $i++) {
|
|
echo fbsql_field_name($fields, $i) . "\n";;
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The above example would produce the following output:
|
|
<informalexample>
|
|
<programlisting>
|
|
field1
|
|
field2
|
|
field3
|
|
...
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-list-tables">
|
|
<refnamediv>
|
|
<refname>fbsql_list_tables</refname>
|
|
<refpurpose>List tables in a FrontBase database</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_list_tables</function></funcdef>
|
|
<paramdef>string <parameter>database</parameter></paramdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_list_tables</function> takes a database name and
|
|
returns a result pointer much like the
|
|
<function>fbsql_db_query</function> function. The
|
|
<function>fbsql_tablename</function> function should be used to
|
|
extract the actual table names from the result pointer.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-next-result">
|
|
<refnamediv>
|
|
<refname>fbsql_next_result</refname>
|
|
<refpurpose>Move the internal result pointer to the next result</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool
|
|
<function>fbsql_next_result</function>
|
|
</funcdef>
|
|
<paramdef>int <parameter>result_id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
When sending more than one SQL statement to the server or executing a stored procedure
|
|
with multiple results will cause the server to return multiple result sets.
|
|
This function will test for additional results available form the server. if an
|
|
additional result set exists it will free the existing result set and prepare to
|
|
fetch the wors from the new result set.
|
|
The function will return <literal>TRUE</literal> if an additional result set was
|
|
available or <literal>FALSE</literal> othervise.
|
|
</para>
|
|
<example>
|
|
<title><function>fbsql_next_result</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$link = fbsql_connect ("localhost", "_SYSTEM", "secret");
|
|
fbsql_select_db("MyDB", $link);
|
|
$SQL = "Select * from table1; select * from table2;";
|
|
$rs = fbsql_query($SQL, $link);
|
|
do {
|
|
while ($row = fbsql_fetch_row($rs)) {
|
|
}
|
|
} while (fbsql_next_result($rs));
|
|
fbsql_free_result($rs);
|
|
fbsql_close ($link);
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-num-fields">
|
|
<refnamediv>
|
|
<refname>fbsql_num_fields</refname>
|
|
<refpurpose>Get number of fields in result</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fbsql_num_fields</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_num_fields</function> returns the number of
|
|
fields in a result set.
|
|
</para>
|
|
<para>
|
|
See also:
|
|
<function>fbsql_db_query</function>,
|
|
<function>fbsql_query</function>,
|
|
<function>fbsql_fetch_field</function>,
|
|
<function>fbsql_num_rows</function>.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-num-rows">
|
|
<refnamediv>
|
|
<refname>fbsql_num_rows</refname>
|
|
<refpurpose>Get number of rows in result</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fbsql_num_rows</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_num_rows</function> returns the number of rows in
|
|
a result set. This command is only valid for SELECT statements.
|
|
To retrieve the number of rows returned from a INSERT, UPDATE or
|
|
DELETE query, use <function>fbsql_affected_rows</function>.
|
|
<example>
|
|
<title><function>fbsql_num_rows</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
|
|
$link = fbsql_connect("localhost", "username", "password");
|
|
fbsql_select_db("database", $link);
|
|
|
|
$result = fbsql_query("SELECT * FROM table1;", $link);
|
|
$num_rows = fbsql_num_rows($result);
|
|
|
|
echo "$num_rows Rows\n";
|
|
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also:
|
|
<function>fbsql_affected_rows</function>,
|
|
<function>fbsql_connect</function>,
|
|
<function>fbsql_select_db</function> and
|
|
<function>fbsql_query</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-pconnect">
|
|
<refnamediv>
|
|
<refname>fbsql_pconnect</refname>
|
|
<refpurpose>
|
|
Open a persistent connection to a FrontBase Server
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_pconnect</function></funcdef>
|
|
<paramdef>string
|
|
<parameter><optional>hostname</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>string
|
|
<parameter><optional>username</optional></parameter>
|
|
</paramdef>
|
|
<paramdef>string
|
|
<parameter><optional>password</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: A positive FrontBase persistent link identifier on success,
|
|
or <literal>FALSE</literal> on error.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_pconnect</function> establishes a connection
|
|
to a FrontBase server. The following defaults are assumed for
|
|
missing optional parameters: <parameter>host</parameter> =
|
|
'localhost', <parameter>username</parameter> = "_SYSTEM"
|
|
and <parameter>password</parameter> = empty password.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_pconnect</function> acts very much like
|
|
<function>fbsql_connect</function> with two major differences.
|
|
</para>
|
|
<para>
|
|
To set Frontbase server port number, use <function>fbsql_select_db</function>.
|
|
</para>
|
|
<para>
|
|
First, when connecting, the function would first try to find a
|
|
(persistent) link that's already open with the same host,
|
|
username and password. If one is found, an identifier for it
|
|
will be returned instead of opening a new connection.
|
|
</para>
|
|
<para>
|
|
Second, the connection to the SQL server will not be closed when
|
|
the execution of the script ends. Instead, the link will remain
|
|
open for future use.
|
|
</para>
|
|
<para>
|
|
This type of links is therefore called 'persistent'.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-query">
|
|
<refnamediv>
|
|
<refname>fbsql_query</refname>
|
|
<refpurpose>Send a FrontBase query</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_query</function></funcdef>
|
|
<paramdef>string <parameter>query</parameter></paramdef>
|
|
<paramdef>resource
|
|
<parameter><optional>link_identifier</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_query</function> sends a query to the currently
|
|
active database on the server that's associated with the
|
|
specified link identifier. If
|
|
<parameter>link_identifier</parameter> isn't specified, the last
|
|
opened link is assumed. If no link is open, the function tries
|
|
to establish a link as if <function>fbsql_connect</function> was
|
|
called with no arguments, and use it.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The query string shall always end with a semicolon.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
<function>fbsql_query</function> returns <literal>TRUE</literal> (non-zero) or <literal>FALSE</literal>
|
|
to indicate whether or not the query succeeded. A return value
|
|
of <literal>TRUE</literal> means that the query was legal and could be executed by
|
|
the server. It does not indicate anything about the number of
|
|
rows affected or returned. It is perfectly possible for a query
|
|
to succeed but affect no rows or return no rows.
|
|
</para>
|
|
<para>
|
|
The following query is syntactically invalid, so
|
|
<function>fbsql_query</function> fails and returns <literal>FALSE</literal>:
|
|
<example>
|
|
<title><function>fbsql_query</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$result = fbsql_query ("SELECT * WHERE 1=1")
|
|
or die ("Invalid query");
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
The following query is semantically invalid if
|
|
<literal>my_col</literal> is not a column in the table
|
|
<literal>my_tbl</literal>, so <function>fbsql_query</function>
|
|
fails and returns <literal>FALSE</literal>:
|
|
<example>
|
|
<title><function>fbsql_query</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
$result = fbsql_query ("SELECT my_col FROM my_tbl")
|
|
or die ("Invalid query");
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<function>fbsql_query</function> will also fail and return <literal>FALSE</literal>
|
|
if you don't have permission to access the table(s) referenced by
|
|
the query.
|
|
</para>
|
|
<para>
|
|
Assuming the query succeeds, you can call
|
|
<function>fbsql_num_rows</function> to find out how many rows
|
|
were returned for a SELECT statment or
|
|
<function>fbsql_affected_rows</function> to find out how many
|
|
rows were affected by a DELETE, INSERT, REPLACE, or UPDATE
|
|
statement.
|
|
</para>
|
|
<para>
|
|
For SELECT statements, <function>fbsql_query</function> returns a
|
|
new result identifier that you can pass to
|
|
<function>fbsql_result</function>. When you are done with the
|
|
result set, you can free the resources associated with it by
|
|
calling <function>fbsql_free_result</function>. Although, the
|
|
memory will automatically be freed at the end of the script's
|
|
execution.
|
|
</para>
|
|
<para>
|
|
See also: <function>fbsql_affected_rows</function>,
|
|
<function>fbsql_db_query</function>,
|
|
<function>fbsql_free_result</function>,
|
|
<function>fbsql_result</function>,
|
|
<function>fbsql_select_db</function>, and
|
|
<function>fbsql_connect</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-result">
|
|
<refnamediv>
|
|
<refname>fbsql_result</refname>
|
|
<refpurpose>Get result data</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed <function>fbsql_result</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>row</parameter></paramdef>
|
|
<paramdef>mixed
|
|
<parameter>
|
|
<optional>field</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_result</function> returns the contents of one
|
|
cell from a FrontBase result set. The field argument can be the
|
|
field's offset, or the field's name, or the field's table dot
|
|
field's name (tabledname.fieldname). If the column name has been
|
|
aliased ('select foo as bar from...'), use the alias instead of
|
|
the column name.
|
|
</para>
|
|
<para>
|
|
When working on large result sets, you should consider using one
|
|
of the functions that fetch an entire row (specified below). As
|
|
these functions return the contents of multiple cells in one
|
|
function call, they're MUCH quicker than
|
|
<function>fbsql_result</function>. Also, note that specifying a
|
|
numeric offset for the field argument is much quicker than
|
|
specifying a fieldname or tablename.fieldname argument.
|
|
</para>
|
|
<para>
|
|
Calls to <function>fbsql_result</function> should not be mixed
|
|
with calls to other functions that deal with the result set.
|
|
</para>
|
|
<para>
|
|
Recommended high-performance alternatives:
|
|
<function>fbsql_fetch_row</function>,
|
|
<function>fbsql_fetch_array</function>, and
|
|
<function>fbsql_fetch_object</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-select-db">
|
|
<refnamediv>
|
|
<refname>fbsql_select_db</refname>
|
|
<refpurpose>Select a FrontBase database</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>resource <function>fbsql_select_db</function></funcdef>
|
|
<paramdef>string <parameter>database_name</parameter></paramdef>
|
|
<paramdef>resource
|
|
<parameter>
|
|
<optional>link_identifier</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns: <literal>TRUE</literal> on success, <literal>FALSE</literal> on error.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_select_db</function> sets the current active
|
|
database on the server that's associated with the specified link
|
|
identifier. If no link identifier is specified, the last opened
|
|
link is assumed. If no link is open, the function will try to
|
|
establish a link as if <function>fbsql_connect</function> was
|
|
called, and use it.
|
|
</para>
|
|
<para>
|
|
The client contacts FBExec to obtain the port number to use for
|
|
the connection to the database. if the database name is a number
|
|
the system will use that as a port number and it will not ask
|
|
FBExec for the port number.
|
|
The FrontBase server can be stared as
|
|
FRontBase -FBExec=No -port=<port number> <database name>.
|
|
</para>
|
|
<para>
|
|
Every subsequent call to <function>fbsql_query</function> will be
|
|
made on the active database.
|
|
</para>
|
|
<para> See also:
|
|
<function>fbsql_connect</function>,
|
|
<function>fbsql_pconnect</function>, and
|
|
<function>fbsql_query</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-tablename">
|
|
<refnamediv>
|
|
<refname>fbsql_tablename</refname>
|
|
<refpurpose>Get table name of field</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fbsql_tablename</function></funcdef>
|
|
<paramdef>resource <parameter>result</parameter></paramdef>
|
|
<paramdef>int <parameter>i</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>fbsql_tablename</function> takes a result pointer
|
|
returned by the <function>fbsql_list_tables</function> function
|
|
as well as an integer index and returns the name of a table. The
|
|
<function>fbsql_num_rows</function> function may be used to
|
|
determine the number of tables in the result pointer.
|
|
<example>
|
|
<title><function>fbsql_tablename</function> example</title>
|
|
<programlisting role="php">
|
|
<?php
|
|
fbsql_connect ("localhost", "_SYSTEM", "");
|
|
$result = fbsql_list_tables ("wisconsin");
|
|
$i = 0;
|
|
while ($i < fbsql_num_rows ($result)) {
|
|
$tb_names[$i] = fbsql_tablename ($result, $i);
|
|
echo $tb_names[$i] . "<BR>";
|
|
$i++;
|
|
}
|
|
?>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fbsql-warnings">
|
|
<refnamediv>
|
|
<refname>fbsql_warnings</refname>
|
|
<refpurpose>Enable or disable FrontBase warnings</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>fbsql_warnings</function></funcdef>
|
|
<paramdef>bool
|
|
<parameter>
|
|
<optional>OnOff</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns <literal>TRUE</literal> if warnings is turned on otherwise <literal>FALSE</literal>.
|
|
</para>
|
|
<para>
|
|
<function>fbsql_warnings</function> enables or disables FrontBase
|
|
warnings.
|
|
</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
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|