sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 08:58:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

- Clean up sqlite docs

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@132653 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Derick Rethans 2003-06-20 18:49:38 +00:00
parent 62c8d5727c
commit 27f047c673
23 changed files with 801 additions and 825 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
reference/sqlite/functions/sqlite-array-query.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-array-query">
<refnamediv>
<refname>sqlite_array_query</refname>
@ -23,9 +23,9 @@
using such a script.
</para>
<example>
<title><function>sqlite_array_query</function> implemented
yourself</title>
<programlisting role="php"><![CDATA[<?php
<title><function>sqlite_array_query</function> implemented yourself</title>
<programlisting role="php">
<![CDATA[<?php
$q = sqlite_query($database, "SELECT * from foo LIMIT 100");
$rows = array();
while ($r = sqlite_fetch_array($q)) {
@ -34,7 +34,7 @@ while ($r = sqlite_fetch_array($q)) {
?>]]>
</programlisting>
</example>
<note>
<tip>
<para>
<function>sqlite_array_query</function> is best suited to queries
returning 45 rows or less. If you have more data than that, it is
@ -42,7 +42,7 @@ while ($r = sqlite_fetch_array($q)) {
<function>sqlite_unbuffered_query</function> instead for more optimal
performance.
</para>
</note>
</tip>
</refsect1>
</refentry>

5
reference/sqlite/functions/sqlite-changes.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-changes">
<refnamediv>
<refname>sqlite_changes</refname>
@ -17,9 +17,6 @@
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

99
reference/sqlite/functions/sqlite-create-function.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-create-function">
<refnamediv>
@ -37,53 +37,55 @@
SELECT and UPDATE statements and also in triggers.
</para>
<example>
<title><function>sqlite_create_function</function> example</title>
<programlisting role="php">
<para>
<example>
<title><function>sqlite_create_function</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
function md5_and_reverse($string)
{
return strrev(md5($string));
}
sqlite_create_function($db, 'md5rev', 'md5_and_reverse', 1);
function md5_and_reverse($string) {
return strrev(md5($string));
}
$rows = sqlite_array_query($db, 'SELECT md5rev(filename) from files');
sqlite_create_function($db, 'md5rev', 'md5_and_reverse', 1);
$rows = sqlite_array_query($db, 'SELECT md5rev(filename) from files');
?>]]>
</programlisting>
<para>
In this example, we have a function that calculates the md5 sum of a
string, and then reverses it. When the SQL statement executes, it
returns the value of the filename transformed by our function. The data
returned in <parameter>$rows</parameter> contains the processed result.
</para>
<para>
The beauty of this technique is that you do not need to process the
result using a foreach() loop after you have queried for the data.
</para>
</example>
<note>
<para>
PHP registers a special function named <literal>php</literal> when the
database is first opened. The php function can be used to call any PHP
function without having to register it first.
</para>
</note>
<example>
<title>Example of using the PHP function</title>
<programlisting role="php">
<![CDATA[
</programlisting>
</example>
</para>
<para>
In this example, we have a function that calculates the md5 sum of a
string, and then reverses it. When the SQL statement executes, it
returns the value of the filename transformed by our function. The data
returned in <parameter>$rows</parameter> contains the processed result.
</para>
<para>
The beauty of this technique is that you do not need to process the
result using a foreach() loop after you have queried for the data.
</para>
<para>
PHP registers a special function named <literal>php</literal> when the
database is first opened. The php function can be used to call any PHP
function without having to register it first.
</para>
<para>
<example>
<title>Example of using the PHP function</title>
<programlisting role="php">
<![CDATA[
<?php
$rows = sqlite_array_query($db, "SELECT php('md5', filename) from files");
$rows = sqlite_array_query($db, "SELECT php('md5', filename) from files");
?>]]>
</programlisting>
<para>
This example will call the <function>md5</function> on each
<literal>filename</literal> column in the database and return the result
into <parameter>$rows</parameter>
</para>
</example>
</programlisting>
<para>
This example will call the <function>md5</function> on each
<literal>filename</literal> column in the database and return the result
into <parameter>$rows</parameter>
</para>
</example>
</para>
<note>
<para>
For performance reasons, PHP will not automatically encode/decode binary
@ -91,13 +93,14 @@
the parameters and return values if you need to process binary data in
this way.
</para>
<para>
<emphasis>It is not recommended to use UDF's to handle processesing of
binary data, unless high performance is not a key requirement of your
application.
</emphasis>
</para>
</note>
<tip>
<para>
It is not recommended to use UDF's to handle processesing of
binary data, unless high performance is not a key requirement of your
application.
</para>
</tip>
<para>
See also <function>sqlite_register_aggregate</function>.
</para>

60
reference/sqlite/functions/sqlite-current.xml
View file

@ -1,40 +1,40 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-current">
<refnamediv>
<refname>sqlite_current</refname>
<refpurpose>Fetches the current row from a result set as an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sqlite_current</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>result_type</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>decode_binary</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_current</function> is identical to
<function>sqlite_fetch_array</function> except that it does not advance
to the next row prior to returning the data; it returns the data from the
current position only.
</para>
<para>
If the current position is beyond the final row, this function returns
&false;
</para>
<note>
<para>
This function will not work on unbuffered result handles.
</para>
</note>
<para>
See also <function>sqlite_seek</function>,
<function>sqlite_next</function>.
</para>
</refsect1>
</refentry>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sqlite_current</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>result_type</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>decode_binary</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_current</function> is identical to
<function>sqlite_fetch_array</function> except that it does not advance
to the next row prior to returning the data; it returns the data from the
current position only.
</para>
<para>
If the current position is beyond the final row, this function returns
&false;
</para>
<note>
<para>
This function will not work on unbuffered result handles.
</para>
</note>
<para>
See also <function>sqlite_seek</function>,
<function>sqlite_next</function>.
</para>
</refsect1>
</refentry>

44
reference/sqlite/functions/sqlite-error-string.xml
View file

@ -1,27 +1,27 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-error-string">
<refnamediv>
<refname>sqlite_error_string</refname>
<refpurpose>Returns the textual description of an error code</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_error_string</methodname>
<methodparam><type>int</type><parameter>error_code</parameter></methodparam>
</methodsynopsis>
<para>
Returns a human readable description of the
<parameter>error_code</parameter> returned from
<function>sqlite_last_error</function>.
</para>
<para>
See also <function>sqlite_last_error</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sqlite-error-string">
<refnamediv>
<refname>sqlite_error_string</refname>
<refpurpose>Returns the textual description of an error code</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_error_string</methodname>
<methodparam><type>int</type><parameter>error_code</parameter></methodparam>
</methodsynopsis>
<para>
Returns a human readable description of the
<parameter>error_code</parameter> returned from
<function>sqlite_last_error</function>.
</para>
<para>
See also <function>sqlite_last_error</function>.
</para>
</refsect1>
</refentry>

84
reference/sqlite/functions/sqlite-escape-string.xml
View file

@ -1,46 +1,46 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-escape-string">
<refnamediv>
<refname>sqlite_escape_string</refname>
<refpurpose>Escapes a string for use as a query parameter</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_escape_string</methodname>
<methodparam><type>string</type><parameter>item</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_escape_string</function> will correctly quote the string
specified by <parameter>item</parameter>
for use in an SQLite SQL statement. This includes doubling up
single-quote characters (<literal>'</literal>) and checking for
binary-unsafe characters in the query string.
</para>
<para>
If the <parameter>item</parameter> contains a <literal>NUL</literal>
character, or if it begins with a character whose ordinal value is
<literal>0x01</literal>, PHP will apply a binary encoding scheme so that
you can safely store and retrieve binary data.
</para>
<para>
Although the encoding makes it safe to insert the data, it will render
simple text comparisions and LIKE clauses in your queries unusable for
the columns that contain the binary data. In practice, this shouldn't be
a problem, as your schema should be such that you don't use such things
on binary columns (in fact, it might be better to store binary data using
other means, such as in files).
</para>
<warning>
<simpara>
<function>addslashes</function> should <emphasis>NOT</emphasis> be used
to quote your strings for SQLite queries; it will lead to strange results when
retrieving your data.
</simpara>
</warning>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-escape-string">
<refnamediv>
<refname>sqlite_escape_string</refname>
<refpurpose>Escapes a string for use as a query parameter</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_escape_string</methodname>
<methodparam><type>string</type><parameter>item</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_escape_string</function> will correctly quote the string
specified by <parameter>item</parameter>
for use in an SQLite SQL statement. This includes doubling up
single-quote characters (<literal>'</literal>) and checking for
binary-unsafe characters in the query string.
</para>
<para>
If the <parameter>item</parameter> contains a <literal>NUL</literal>
character, or if it begins with a character whose ordinal value is
<literal>0x01</literal>, PHP will apply a binary encoding scheme so that
you can safely store and retrieve binary data.
</para>
<para>
Although the encoding makes it safe to insert the data, it will render
simple text comparisions and <literal>LIKE</literal> clauses in your
queries unusable for the columns that contain the binary data. In
practice, this shouldn't be a problem, as your schema should be such that
you don't use such things on binary columns (in fact, it might be better to
store binary data using other means, such as in files).
</para>
<warning>
<simpara>
<function>addslashes</function> should <emphasis>NOT</emphasis> be used to
quote your strings for SQLite queries; it will lead to strange results
when retrieving your data.
</simpara>
</warning>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

94
reference/sqlite/functions/sqlite-fetch-array.xml
View file

@ -1,51 +1,51 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<refentry id="function.sqlite-fetch-array">
<refnamediv>
<refname>sqlite_fetch_array</refname>
<refpurpose>Fetches the next row from a result set as an array.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sqlite_fetch_array</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>result_type</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>decode_binary</parameter></methodparam>
</methodsynopsis>
<para>
Fetches the next row from the given <parameter>result</parameter> handle.
If there are no more rows, returns &false;, otherwise returns an
associative array representing the row data.
</para>
<para>
<parameter>result_type</parameter> can be used to specifiy how you want
the results to be returned. The default value is
<literal>SQLITE_BOTH</literal> which returns columns indexed by their
ordinal column number and by column name.
<literal>SQLITE_ASSOC</literal> causes the array to be indexed only by
column names, and <literal>SQLITE_NUM</literal> to be indexed only by
ordinal column numbers.
</para>
<para>
The column names returned by <literal>SQLITE_ASSOC</literal> and
<literal>SQLITE_BOTH</literal> will be case-folded according to the value
of the <link linkend="ini.sqlite.assoc-case">sqlite.assoc_case</link>
configuration option.
</para>
<para>
When <parameter>decode_binary</parameter> is set to &true; (the default),
PHP will decode the binary encoding it applied to the data if it
was encoded using the <function>sqlite_escape_string</function>. You
will usually always leave this value at its default, unless you are
interoperating with databases created by other sqlite capable
applications.
</para>
<para>
See also <function>sqlite_array_query</function> and
<function>sqlite_fetch_string</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sqlite-fetch-array">
<refnamediv>
<refname>sqlite_fetch_array</refname>
<refpurpose>Fetches the next row from a result set as an array.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sqlite_fetch_array</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>result_type</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>decode_binary</parameter></methodparam>
</methodsynopsis>
<para>
Fetches the next row from the given <parameter>result</parameter> handle.
If there are no more rows, returns &false;, otherwise returns an
associative array representing the row data.
</para>
<para>
<parameter>result_type</parameter> can be used to specifiy how you want
the results to be returned. The default value is
<literal>SQLITE_BOTH</literal> which returns columns indexed by their
ordinal column number and by column name.
<literal>SQLITE_ASSOC</literal> causes the array to be indexed only by
column names, and <literal>SQLITE_NUM</literal> to be indexed only by
ordinal column numbers.
</para>
<para>
The column names returned by <literal>SQLITE_ASSOC</literal> and
<literal>SQLITE_BOTH</literal> will be case-folded according to the value
of the <link linkend="ini.sqlite.assoc-case">sqlite.assoc_case</link>
configuration option.
</para>
<para>
When <parameter>decode_binary</parameter> is set to &true; (the default),
PHP will decode the binary encoding it applied to the data if it
was encoded using the <function>sqlite_escape_string</function>. You
will usually always leave this value at its default, unless you are
interoperating with databases created by other sqlite capable
applications.
</para>
<para>
See also <function>sqlite_array_query</function> and
<function>sqlite_fetch_string</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

45
reference/sqlite/functions/sqlite-field-name.xml
View file

@ -1,29 +1,24 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-field-name">
<refnamediv>
<refname>sqlite_field_name</refname>
<refpurpose>Returns the name of a particular field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_field_name</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam><type>int</type><parameter>field_index</parameter></methodparam>
</methodsynopsis>
<para>
Given the ordinal column number, <literal>field_index</literal>, returns
the name of that field in the result handle
<parameter>result</parameter>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-field-name">
<refnamediv>
<refname>sqlite_field_name</refname>
<refpurpose>Returns the name of a particular field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_field_name</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam><type>int</type><parameter>field_index</parameter></methodparam>
</methodsynopsis>
<para>
Given the ordinal column number, <literal>field_index</literal>, returns
the name of that field in the result handle
<parameter>result</parameter>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

41
reference/sqlite/functions/sqlite-has-more.xml
View file

@ -1,26 +1,23 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-has-more">
<refnamediv>
<refname>sqlite_has_more</refname>
<refpurpose>Returns whether or not more rows are available</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_has_more</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_has_more</function> returns &true; if there are more
rows available from the <parameter>result</parameter> handle, or &false;
otherwise.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-has-more">
<refnamediv>
<refname>sqlite_has_more</refname>
<refpurpose>Returns whether or not more rows are available</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_has_more</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_has_more</function> returns &true; if there are more
rows available from the <parameter>result</parameter> handle, or &false;
otherwise.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

42
reference/sqlite/functions/sqlite-last-error.xml
View file

@ -1,26 +1,26 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-last-error">
<refnamediv>
<refname>sqlite_last_error</refname>
<refpurpose>Returns the error code of the last error for a database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_last_error</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
Returns the error code from the last operation performed on
<parameter>db</parameter>, the database handle.
</para>
<para>
See also <function>sqlite_error_string</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sqlite-last-error">
<refnamediv>
<refname>sqlite_last_error</refname>
<refpurpose>Returns the error code of the last error for a database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_last_error</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
Returns the error code from the last operation performed on
<parameter>db</parameter>, the database handle.
</para>
<para>
See also <function>sqlite_error_string</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

53
reference/sqlite/functions/sqlite-last-insert-rowid.xml
View file

@ -1,33 +1,30 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-last-insert-rowid">
<refnamediv>
<refname>sqlite_last_insert_rowid</refname>
<refpurpose>Returns the rowid of the most recently inserted row</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_last_insert_rowid</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
Returns the rowid of the row that was most recently inserted into the
database <parameter>db</parameter>, if it was created as an
auto-increment field.
</para>
<note>
<para>
You can create auto-increment fields in SQLite by declaring them as
<literal>INTEGER PRIMARY KEY</literal> in your table schema.
</para>
</note>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-last-insert-rowid">
<refnamediv>
<refname>sqlite_last_insert_rowid</refname>
<refpurpose>Returns the rowid of the most recently inserted row</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_last_insert_rowid</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
Returns the rowid of the row that was most recently inserted into the
database <parameter>db</parameter>, if it was created as an
auto-increment field.
</para>
<tip>
<para>
You can create auto-increment fields in SQLite by declaring them as
<literal>INTEGER PRIMARY KEY</literal> in your table schema.
</para>
</tip>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

89
reference/sqlite/functions/sqlite-libencoding.xml
View file

@ -1,51 +1,48 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-libencoding">
<refnamediv>
<refname>sqlite_libencoding</refname>
<refpurpose>Returns the encoding of the linked SQLite library
</refpurpose></refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_libencoding</methodname>
</methodsynopsis>
<para>
The SQLite library may be compiled in either ISO-8859-1 or UTF-8
compatible modes. This function allows you to determine which encoding
scheme is used by your version of the library.
</para>
<note>
<para>
The default PHP distribution builds libsqlite in ISO-8859-1 encoding
mode. However, this is a misnomer; rather than handling ISO-8859-1, it
operates according to your current locale settings for string
comparisons and sort ordering. So, rather than ISO-8859-1, you should
think of it as being '8-bit' instead.
</para>
<para>
When compiled with UTF-8 support, sqlite handles encoding and decoding
of UTF-8 multi-byte character sequences, but does not yet do a complete
job when working with the data (no normalization is performed for
example), and some comparison operations may still not be carried out
correctly.
</para>
<para>
It is not recommended that you use PHP in a web-server configuration
with a version of the SQLite library compiled with UTF-8 support, since
libsqlite will abort() the process if it detects a problem with the
UTF-8 encoding.
</para>
</note>
<para>
See also <function>sqlite_libversion</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-libencoding">
<refnamediv>
<refname>sqlite_libencoding</refname>
<refpurpose>Returns the encoding of the linked SQLite library</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_libencoding</methodname>
</methodsynopsis>
<para>
The SQLite library may be compiled in either ISO-8859-1 or UTF-8
compatible modes. This function allows you to determine which encoding
scheme is used by your version of the library.
</para>
<warning>
<para>
The default PHP distribution builds libsqlite in ISO-8859-1 encoding
mode. However, this is a misnomer; rather than handling ISO-8859-1, it
operates according to your current locale settings for string
comparisons and sort ordering. So, rather than ISO-8859-1, you should
think of it as being '8-bit' instead.
</para>
</warning>
<para>
When compiled with UTF-8 support, sqlite handles encoding and decoding
of UTF-8 multi-byte character sequences, but does not yet do a complete
job when working with the data (no normalization is performed for
example), and some comparison operations may still not be carried out
correctly.
</para>
<para>
It is not recommended that you use PHP in a web-server configuration
with a version of the SQLite library compiled with UTF-8 support, since
libsqlite will abort the process if it detects a problem with the
UTF-8 encoding.
</para>
<para>
See also <function>sqlite_libversion</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

41
reference/sqlite/functions/sqlite-libversion.xml
View file

@ -1,27 +1,24 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-libversion">
<refnamediv>
<refname>sqlite_libversion</refname>
<refpurpose>Returns the version of the linked SQLite library</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_libencoding</methodname>
</methodsynopsis>
<para>
Returns the version of the linked SQLite library as a string.
</para>
<para>
See also <function>sqlite_libencoding</function>.
</para>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-libversion">
<refnamediv>
<refname>sqlite_libversion</refname>
<refpurpose>Returns the version of the linked SQLite library</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sqlite_libversion</methodname>
</methodsynopsis>
<para>
Returns the version of the linked SQLite library as a string.
</para>
<para>
See also <function>sqlite_libencoding</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

51
reference/sqlite/functions/sqlite-next.xml
View file

@ -1,37 +1,34 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-next">
<refnamediv>
<refname>sqlite_next</refname>
<refpurpose>Seek to next row number</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_next</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_next</function> advances the result handle
<parameter>result</parameter> to the next row.
Returns &false; if there are no more rows, &true; otherwise.
</para>
<note>
<para>
This function cannot be used with unbuffered result handles.
</para>
</note>
<para>
See also <function>sqlite_seek</function>,
<function>sqlite_current</function> and
<function>sqlite_rewind</function>.
</para>
</refsect1>
</refentry>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_next</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_next</function> advances the result handle
<parameter>result</parameter> to the next row.
Returns &false; if there are no more rows, &true; otherwise.
</para>
<note>
<para>
This function cannot be used with unbuffered result handles.
</para>
</note>
<para>
See also <function>sqlite_seek</function>,
<function>sqlite_current</function> and
<function>sqlite_rewind</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

34
reference/sqlite/functions/sqlite-num-fields.xml
View file

@ -1,22 +1,22 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-num-fields">
<refnamediv>
<refname>sqlite_num_fields</refname>
<refpurpose>Returns the number of fields in a result set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_num_fields</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
Returns the number of fields in the <parameter>result</parameter> set.
</para>
</refsect1>
</refentry>
<refentry id="function.sqlite-num-fields">
<refnamediv>
<refname>sqlite_num_fields</refname>
<refpurpose>Returns the number of fields in a result set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_num_fields</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
Returns the number of fields in the <parameter>result</parameter> set.
</para>
</refsect1>
</refentry>

48
reference/sqlite/functions/sqlite-num-rows.xml
View file

@ -1,30 +1,26 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-num-rows">
<refnamediv>
<refname>sqlite_num_rows</refname>
<refpurpose>Returns the number of rows in a result set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_num_rows</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
Returns the number of rows in the <parameter>result</parameter> set.
</para>
<note>
<para>
This function cannot be used with unbuffered result sets.
</para>
</note>
</refsect1>
</refentry>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-num-rows">
<refnamediv>
<refname>sqlite_num_rows</refname>
<refpurpose>Returns the number of rows in a result set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sqlite_num_rows</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
Returns the number of rows in the <parameter>result</parameter> set.
</para>
<note>
<para>
This function cannot be used with unbuffered result sets.
</para>
</note>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

182
reference/sqlite/functions/sqlite-open.xml
View file

@ -1,101 +1,103 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<refentry id="function.sqlite-open">
<refnamediv>
<refname>sqlite_open</refname>
<refpurpose>Opens a SQLite database. Will create the database if it does not exist</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_open</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>&amp;errmessage</parameter></methodparam>
</methodsynopsis>
<para>
Returns a resource on success, &false; on error.
</para>
<para>
The <parameter>filename</parameter> parameter is the name of the
database. It can be a relative or absolute path to the file that sqlite
will use to store your data. If the file does not exist, sqlite will
attempt to create it. You <emphasis>MUST</emphasis> have write
permissions to the file if you want to insert data or modify the database
schema.
</para>
<para>
The <parameter>mode</parameter> parameter specifies the mode of the file and is
intended to be used to open the database in read-only mode.
Presently, this parameter is ignored by the sqlite library. The default
value for mode is the octal value <literal>0666</literal> and this is the
recommended value to use if you need access to the
<parameter>errmessage</parameter> parameter.
</para>
<para>
<parameter>errmessage</parameter> is passed by reference and is set to
hold a descriptive error message explaining why the database could not be
opened if there was an error.
</para>
<example>
<title><function>sqlite_open</function> example</title>
<programlisting role="php">
<refpurpose>Opens a SQLite database. Will create the database if it does not exist</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_open</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>&amp;errmessage</parameter></methodparam>
</methodsynopsis>
<para>
Returns a resource on success, &false; on error.
</para>
<para>
The <parameter>filename</parameter> parameter is the name of the
database. It can be a relative or absolute path to the file that sqlite
will use to store your data. If the file does not exist, sqlite will
attempt to create it. You <emphasis>MUST</emphasis> have write
permissions to the file if you want to insert data or modify the database
schema.
</para>
<para>
The <parameter>mode</parameter> parameter specifies the mode of the file and is
intended to be used to open the database in read-only mode.
Presently, this parameter is ignored by the sqlite library. The default
value for mode is the octal value <literal>0666</literal> and this is the
recommended value to use if you need access to the
<parameter>errmessage</parameter> parameter.
</para>
<para>
<parameter>errmessage</parameter> is passed by reference and is set to
hold a descriptive error message explaining why the database could not be
opened if there was an error.
</para>
<para>
<example>
<title><function>sqlite_open</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
if ($db=sqlite_open('mysqlitedb', 0666, $sqliteerror)) {
sqlite_query('CREATE TABLE foo (bar varchar(10))');
sqlite_query("INSERT INTO foo VALUES ('fnord')");
$result=sqlite_query('select bar from foo');
var_dump(sqlite_fetch_array($result));
} else {
die($sqliteerror);
}
if ($db = sqlite_open('mysqlitedb', 0666, $sqliteerror)) {
sqlite_query('CREATE TABLE foo (bar varchar(10))');
sqlite_query("INSERT INTO foo VALUES ('fnord')");
$result = sqlite_query('select bar from foo');
var_dump(sqlite_fetch_array($result));
} else {
die ($sqliteerror);
}
?>]]>
</programlisting>
</example>
<note>
<simpara>
On Unix platforms, SQLite is sensitive to scripts that use the fork() system call. If you
do have such a script, it is recommended that you close the handle prior
to forking and then re-open it in the child and/or parent.
For more information on this issue, see <ulink
url="http://www.sqlite.org/c_interface.html">The C language interface
to the SQLite library</ulink> in the section entitled
<literal>Multi-Threading And SQLite</literal>.
</simpara>
</note>
<note>
<simpara>
Starting with SQLite library version 2.8.2, you can specify
<literal>:memory:</literal> as the <parameter>filename</parameter> to
create a database that lives only in the memory of the computer.
This is useful mostly for temporary processing, as the in-memory
database will be destroyed when the process ends. It can also be
useful when coupled with the <literal>ATTACH DATABASE</literal> SQL
statement to load other databases and move and query data betweem them.
</simpara>
</note>
<note>
<simpara>
It is not recommended to work with SQLite databases mounted on NFS
partitions. Since NFS is notoriously bad when it comes to locking you
may find that you cannot even open the database at all, and if it
succeeds, the locking behaviour may be undefined.
</simpara>
</note>
<note>
<simpara>
SQLite is safe_mode and open_basedir aware.
</simpara>
</note>
</programlisting>
</example>
</para>
<tip>
<simpara>
On Unix platforms, SQLite is sensitive to scripts that use the fork() system call. If you
do have such a script, it is recommended that you close the handle prior
to forking and then re-open it in the child and/or parent.
For more information on this issue, see <ulink
url="http://www.sqlite.org/c_interface.html">The C language interface
to the SQLite library</ulink> in the section entitled
<literal>Multi-Threading And SQLite</literal>.
</simpara>
</tip>
<tip>
<simpara>
It is not recommended to work with SQLite databases mounted on NFS
partitions. Since NFS is notoriously bad when it comes to locking you
may find that you cannot even open the database at all, and if it
succeeds, the locking behaviour may be undefined.
</simpara>
</tip>
<note>
<simpara>
Starting with SQLite library version 2.8.2, you can specify
<literal>:memory:</literal> as the <parameter>filename</parameter> to
create a database that lives only in the memory of the computer.
This is useful mostly for temporary processing, as the in-memory
database will be destroyed when the process ends. It can also be
useful when coupled with the <literal>ATTACH DATABASE</literal> SQL
statement to load other databases and move and query data betweem them.
</simpara>
</note>
<note>
<simpara>
SQLite is &safemode; and open_basedir aware.
</simpara>
</note>
<para>
See also <function>sqlite_popen</function>,
<function>sqlite_close</function> and
<function>sqlite_query</function>.
</para>
</refsect1>
</refentry>
<para>
See also <function>sqlite_popen</function>,
<function>sqlite_close</function> and
<function>sqlite_query</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

100
reference/sqlite/functions/sqlite-popen.xml
View file

@ -1,58 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-popen">
<refnamediv>
<refname>sqlite_popen</refname>
<refpurpose>Opens a persistent handle to an SQLite database. Will create the database if it does not exist</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_popen</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>&amp;errmessage</parameter></methodparam>
</methodsynopsis>
<note>
<simpara>
This function behaves identically to <function>sqlite_open</function>
except that is uses the persistent resource mechanism of PHP.
For information about the meaning of the parameters, read the
<function>sqlite_open</function> manual page.
</simpara>
</note>
<para>
<function>sqlite_popen</function> will first check to see if a persistent
handle has already been opened for the given
<parameter>filename</parameter>. If it finds one, it returns that handle
to your script, otherwise it opens a fresh handle to the database.
</para>
<para>
The benefit of this approach is that you don't incurr the performance
cost of re-reading the database and index schema on each page hit served
by persistent web server SAPI's (any SAPI except for regular CGI or CLI).
</para>
<note>
<simpara>
If you use persistent handles and have the database updated by a
background process (perhaps via a crontab), and that process re-creates
the database by overwriting it (either by unlinking and rebuilding, or
moving the updated version to replace the current version),
you may experience undefined behaviour when a persistent handle on the
old version of the database is recycled.
</simpara>
<simpara>
To avoid this situation, have your background processes open the same
database file and perform their updates in a transaction.
</simpara>
</note>
<para>
See also <function>sqlite_popen</function>,
<function>sqlite_close</function> and
<function>sqlite_query</function>.
</para>
</refsect1>
</refentry>
<refpurpose>Opens a persistent handle to an SQLite database. Will create the database if it does not exist</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_popen</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>mode</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>&amp;errmessage</parameter></methodparam>
</methodsynopsis>
<simpara>
This function behaves identically to <function>sqlite_open</function>
except that is uses the persistent resource mechanism of PHP.
For information about the meaning of the parameters, read the
<function>sqlite_open</function> manual page.
</simpara>
<para>
<function>sqlite_popen</function> will first check to see if a persistent
handle has already been opened for the given
<parameter>filename</parameter>. If it finds one, it returns that handle
to your script, otherwise it opens a fresh handle to the database.
</para>
<para>
The benefit of this approach is that you don't incurr the performance
cost of re-reading the database and index schema on each page hit served
by persistent web server SAPI's (any SAPI except for regular CGI or CLI).
</para>
<note>
<simpara>
If you use persistent handles and have the database updated by a
background process (perhaps via a crontab), and that process re-creates
the database by overwriting it (either by unlinking and rebuilding, or
moving the updated version to replace the current version),
you may experience undefined behaviour when a persistent handle on the
old version of the database is recycled.
</simpara>
<simpara>
To avoid this situation, have your background processes open the same
database file and perform their updates in a transaction.
</simpara>
</note>
<para>
See also <function>sqlite_popen</function>,
<function>sqlite_close</function> and
<function>sqlite_query</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

140
reference/sqlite/functions/sqlite-query.xml
View file

@ -1,76 +1,76 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-query">
<refnamediv>
<refname>sqlite_query</refname>
<refpurpose>Executes a query against a given database and returns a result handle</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_query</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>resource</type><methodname>sqlite_query</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
Executes an SQL statement given by the <parameter>query</parameter> against
a given database (specified by the <parameter>db</parameter> parameter).
</para>
<para>
For queries that return rows, this function will return a result handle
which can then be used with functions such as
<function>sqlite_fetch_array</function> and
<function>sqlite_seek</function>.
</para>
<para>
For other kinds of queries, this function will return a boolean result;
&true; for success or &false; for failure.
</para>
<para>
Regardless of the query type, this function will return &false; if the
query failed.
</para>
<para>
<function>sqlite_query</function> returns a buffered, seekable result
handle. This is useful for reasonably small queries where you need to
be able to randomly access the rows. Buffered result handles will
allocate memory to hold the entire result and will not return until it
has been fetched. If you only need sequential access to the data, it is
recommended that you use the much higher performance
<function>sqlite_unbuffered_query</function> instead.
</para>
<note>
<simpara>
Two alternative syntaxes are supported for compatibility with other
database extensions (such as MySQL).
The preferred form is the first one, where the
<parameter>db</parameter> parameter is the first parameter to the
function.
</simpara>
</note>
<note>
<simpara>
SQLite <emphasis>will</emphasis> execute multiple queries separated by
semicolons, so you can use it to execute a batch of SQL that you have
loaded from a file or have embedded in a script.
</simpara>
<simpara>
When executing multiple queries, the return value of this function
will be &false; if the was an error, but undefined otherwise (it might
be &true; for success or it might return a result handle).
</simpara>
</note>
<para>
See also <function>sqlite_array_query</function>.
</para>
</refsect1>
</refentry>
<refnamediv>
<refname>sqlite_query</refname>
<refpurpose>Executes a query against a given database and returns a result handle</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_query</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>resource</type><methodname>sqlite_query</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
Executes an SQL statement given by the <parameter>query</parameter> against
a given database (specified by the <parameter>db</parameter> parameter).
</para>
<para>
For queries that return rows, this function will return a result handle
which can then be used with functions such as
<function>sqlite_fetch_array</function> and
<function>sqlite_seek</function>.
</para>
<para>
For other kinds of queries, this function will return a boolean result;
&true; for success or &false; for failure.
</para>
<para>
Regardless of the query type, this function will return &false; if the
query failed.
</para>
<para>
<function>sqlite_query</function> returns a buffered, seekable result
handle. This is useful for reasonably small queries where you need to
be able to randomly access the rows. Buffered result handles will
allocate memory to hold the entire result and will not return until it
has been fetched. If you only need sequential access to the data, it is
recommended that you use the much higher performance
<function>sqlite_unbuffered_query</function> instead.
</para>
<note>
<simpara>
Two alternative syntaxes are supported for compatibility with other
database extensions (such as MySQL).
The preferred form is the first one, where the
<parameter>db</parameter> parameter is the first parameter to the
function.
</simpara>
</note>
<warning>
<simpara>
SQLite <emphasis>will</emphasis> execute multiple queries separated by
semicolons, so you can use it to execute a batch of SQL that you have
loaded from a file or have embedded in a script.
</simpara>
<simpara>
When executing multiple queries, the return value of this function
will be &false; if the was an error, but undefined otherwise (it might
be &true; for success or it might return a result handle).
</simpara>
</warning>
<para>
See also <function>sqlite_array_query</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

170
reference/sqlite/functions/sqlite-register-aggregate.xml
View file

@ -1,98 +1,98 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<refentry id="function.sqlite-register-aggregate">
<refnamediv>
<refname>sqlite_register_aggregate</refname>
<refpurpose>Register an aggregating UDF for use in SQL statements</refpurpose></refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><function>sqlite_register_aggregate</function>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>function_name</parameter></methodparam>
<methodparam><type>mixed</type><parameter>step_func</parameter></methodparam>
<methodparam><type>mixed</type><parameter>finalize_func</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>num_args</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_register_aggregate</function> is similar to
<function>sqlite_create_function</function> except that it registers
functions that can be used to calculate a result aggregated across all the
rows of a query.
</para>
<para>
The key difference between this function and
<function>sqlite_create_function</function> is that two functions are
required to manage the aggregate; <parameter>step_func</parameter> is
called for each row of the result set. Your PHP function should
accumulate the result and store it into the aggregation context.
Once all the rows have been processed,
<parameter>finalize_func</parameter> will be called and it should then
take the data from the aggregation context and return the result.
</para>
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-register-aggregate">
<refnamediv>
<refname>sqlite_register_aggregate</refname>
<refpurpose>Register an aggregating UDF for use in SQL statements</refpurpose></refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><function>sqlite_register_aggregate</function>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>function_name</parameter></methodparam>
<methodparam><type>mixed</type><parameter>step_func</parameter></methodparam>
<methodparam><type>mixed</type><parameter>finalize_func</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>num_args</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_register_aggregate</function> is similar to
<function>sqlite_create_function</function> except that it registers
functions that can be used to calculate a result aggregated across all the
rows of a query.
</para>
<para>
The key difference between this function and
<function>sqlite_create_function</function> is that two functions are
required to manage the aggregate; <parameter>step_func</parameter> is
called for each row of the result set. Your PHP function should
accumulate the result and store it into the aggregation context.
Once all the rows have been processed,
<parameter>finalize_func</parameter> will be called and it should then
take the data from the aggregation context and return the result.
</para>
<para>
<example>
<title>max_length aggregation function example</title>
<programlisting role="php">
<![CDATA[
<?php
$data = array(
'one',
'two',
'three',
'four'
'five'
'six',
'seven',
'eight',
'nine'
'ten'
);
$db = sqlite_open(':memory:');
sqlite_query($db, "CREATE TABLE strings(a)");
foreach ($data as $str) {
sqlite_query($db, "INSERT INTO strings VALUES('" .
sqlite_escape_string($str) . "')");
}
$data = array(
'one',
'two',
'three',
'four'
'five'
'six',
'seven',
'eight',
'nine'
'ten'
);
$db = sqlite_open(':memory:');
sqlite_query($db, "CREATE TABLE strings(a)");
foreach ($data as $str) {
sqlite_query($db, "INSERT INTO strings VALUES('" .
sqlite_escape_string($str) . "')");
}
function max_len_step(&$context, $string)
{
if (strlen($string) > $context) {
$context = strlen($string);
}
}
function max_len_step(&$context, $string) {
if (strlen($string) > $context) {
$context = strlen($string);
}
}
function max_len_finalize(&$context)
{
return $context;
}
function max_len_finalize(&$context) {
return $context;
}
sqlite_create_aggregate($db, 'max_len', 'max_len_step', 'max_len_finalize');
sqlite_create_aggregate($db, 'max_len', 'max_len_step', 'max_len_finalize');
var_dump(sqlite_array_query($db, 'SELECT max_len(a) from strings'));
var_dump(sqlite_array_query($db, 'SELECT max_len(a) from strings'));
?>]]>
</programlisting>
<para>
In this example, we are creating an aggregating function that will
calculate the length of the longest string in one of the columns of the
table. For each row, the <literal>max_len_step</literal> function is
called and passed a <parameter>context</parameter> parameter. The context
parameter is just like any other PHP variable and be set to hold an array
or even an object value. In this example, we are simply using it to hold
the maximum length we have seen so far; if the
<parameter>string</parameter> has a length longer than the current
maximum, we update the the context to hold this new maximum length.
</para>
<para>
After all of the rows have been processed, SQLite calls the
<literal>max_len_finalize</literal> function to determine the aggregate
result. Here, we could perform some kind of calculation based on the
data found in the <parameter>context</parameter>. In our simple example
though, we have been calculating the result as the query progressed, so we
simply need to return the context value.
</para>
</example>
<note>
</programlisting>
</example>
</para>
<para>
In this example, we are creating an aggregating function that will
calculate the length of the longest string in one of the columns of the
table. For each row, the <literal>max_len_step</literal> function is
called and passed a <parameter>context</parameter> parameter. The context
parameter is just like any other PHP variable and be set to hold an array
or even an object value. In this example, we are simply using it to hold
the maximum length we have seen so far; if the
<parameter>string</parameter> has a length longer than the current
maximum, we update the the context to hold this new maximum length.
</para>
<para>
After all of the rows have been processed, SQLite calls the
<literal>max_len_finalize</literal> function to determine the aggregate
result. Here, we could perform some kind of calculation based on the
data found in the <parameter>context</parameter>. In our simple example
though, we have been calculating the result as the query progressed, so we
simply need to return the context value.
</para>
<tip>
<para>
It is NOT recommended for you to store a copy of the values in the context
and then process them at the end, as you would cause SQLite to use a lot of
@ -100,7 +100,7 @@
if a million rows were stored in memory, each containing a string 32 bytes
in length.
</para>
</note>
</tip>
<para>
See also <function>sqlite_create_function</function>.
</para>

56
reference/sqlite/functions/sqlite-rewind.xml
View file

@ -1,33 +1,33 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-rewind">
<refnamediv>
<refname>sqlite_rewind</refname>
<refpurpose>Seek to the first row number</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_rewind</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_rewind</function> seeks back to the first row in the
result set. Returns &false; if there are no rows in the result set,
&true; otherwise.
</para>
<note>
<para>
This function cannot be used with unbuffered result sets.
</para>
</note>
<para>
See also <function>sqlite_next</function>,
<function>sqlite_current</function> and <function>sqlite_seek</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sqlite-rewind">
<refnamediv>
<refname>sqlite_rewind</refname>
<refpurpose>Seek to the first row number</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_rewind</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_rewind</function> seeks back to the first row in the
result set. Returns &false; if there are no rows in the result set,
&true; otherwise.
</para>
<note>
<para>
This function cannot be used with unbuffered result sets.
</para>
</note>
<para>
See also <function>sqlite_next</function>,
<function>sqlite_current</function> and <function>sqlite_seek</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

60
reference/sqlite/functions/sqlite-seek.xml
View file

@ -1,35 +1,35 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-seek">
<refnamediv>
<refname>sqlite_seek</refname>
<refpurpose>Seek to a particular row number</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_rewind</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam><type>int</type><parameter>rownum</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_seek</function> seeks to the row given by the parameter
<parameter>rownum</parameter>. The row number is one-based (1 is the
first row). Returns &false; if the row does not exist, &true; otherwise.
</para>
<note>
<para>
This function cannot be used with unbuffered result handles.
</para>
</note>
<para>
See also <function>sqlite_next</function>,
<function>sqlite_current</function> and
<function>sqlite_rewind</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sqlite-seek">
<refnamediv>
<refname>sqlite_seek</refname>
<refpurpose>Seek to a particular row number</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sqlite_rewind</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam><type>int</type><parameter>rownum</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_seek</function> seeks to the row given by the parameter
<parameter>rownum</parameter>. The row number is one-based (1 is the
first row). Returns &false; if the row does not exist, &true; otherwise.
</para>
<note>
<para>
This function cannot be used with unbuffered result handles.
</para>
</note>
<para>
See also <function>sqlite_next</function>,
<function>sqlite_current</function> and
<function>sqlite_rewind</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

76
reference/sqlite/functions/sqlite-unbuffered-query.xml
View file

@ -1,43 +1,43 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<refentry id="function.sqlite-unbuffered-query">
<refnamediv>
<refname>sqlite_unbuffered_query</refname>
<refpurpose>Execute a query that does not prefetch and buffer all data</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_unbuffered_query</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>resource</type><methodname>sqlite_unbuffered_query</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_unbuffered_query</function> is identical to
<function>sqlite_query</function> except that the result that is returned
is a sequential forward-only result set that can only be used to read
each row, one after the other.
</para>
<para>
This function is ideal for generating things such as HTML tables where
you only need to process one row at a time and don't need to randomly
access the row data.
</para>
<note>
<para>
Functions such as <function>sqlite_seek</function> and
<function>sqlite_rewind</function> do not work on result handles
returned from this function.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.sqlite-unbuffered-query">
<refnamediv>
<refname>sqlite_unbuffered_query</refname>
<refpurpose>Execute a query that does not prefetch and buffer all data</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>resource</type><methodname>sqlite_unbuffered_query</methodname>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<methodsynopsis>
<type>resource</type><methodname>sqlite_unbuffered_query</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>resource</type><parameter>db</parameter></methodparam>
</methodsynopsis>
<para>
<function>sqlite_unbuffered_query</function> is identical to
<function>sqlite_query</function> except that the result that is returned
is a sequential forward-only result set that can only be used to read
each row, one after the other.
</para>
<para>
This function is ideal for generating things such as HTML tables where
you only need to process one row at a time and don't need to randomly
access the row data.
</para>
<note>
<para>
Functions such as <function>sqlite_seek</function> and
<function>sqlite_rewind</function> do not work on result handles
returned from this function.
</para>
</note>
</refsect1>
</refentry>