sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-17 01:18:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Ws, prepare for new doc style

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@228914 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2007-02-03 22:17:50 +00:00
parent 27d593d950
commit 9cbb34ac2a
18 changed files with 1256 additions and 1272 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
reference/sesam/functions/sesam-affected-rows.xml
View file

@ -1,40 +1,38 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-affected-rows">
<refnamediv>
<refname>sesam_affected_rows</refname>
<refpurpose>
Get number of rows affected by an immediate query
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_affected_rows</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function>.
</para>
<para>
Returns the number of rows affected by a query associated with
<parameter>result_id</parameter>.
</para>
<para>
The <function>sesam_affected_rows</function> function can only
return useful values when used in combination with "immediate"
SQL statements (updating operations like
<literal>INSERT</literal>, <literal>UPDATE</literal> and
<literal>DELETE</literal>) because SESAM does not deliver any
"affected rows" information for "select type" queries. The
number returned is the number of affected rows.
</para>
<para>
<example>
<title><function>sesam_affected_rows</function> example</title>
<programlisting role="php">
<refentry id="function.sesam-affected-rows">
<refnamediv>
<refname>sesam_affected_rows</refname>
<refpurpose>Get number of rows affected by an immediate query</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_affected_rows</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function>.
</para>
<para>
Returns the number of rows affected by a query associated with
<parameter>result_id</parameter>.
</para>
<para>
The <function>sesam_affected_rows</function> function can only
return useful values when used in combination with "immediate"
SQL statements (updating operations like
<literal>INSERT</literal>, <literal>UPDATE</literal> and
<literal>DELETE</literal>) because SESAM does not deliver any
"affected rows" information for "select type" queries. The
number returned is the number of affected rows.
</para>
<para>
<example>
<title><function>sesam_affected_rows</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$result = sesam_execimm("DELETE FROM PHONE WHERE LASTNAME = '" . strtoupper($name) . "'");
@ -45,15 +43,15 @@ echo sesam_affected_rows($result).
" entries with last name " . $name . " deleted.\n";
?>
]]>
</programlisting>
</example>
</para>
<para>
See also <function>sesam_query</function> and
<function>sesam_execimm</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
See also <function>sesam_query</function> and
<function>sesam_execimm</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

80
reference/sesam/functions/sesam-commit.xml
View file

@ -1,41 +1,39 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-commit">
<refnamediv>
<refname>sesam_commit</refname>
<refpurpose>
Commit pending updates to the SESAM database
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_commit</methodname>
<void/>
</methodsynopsis>
<para>
Returns: &true; on success,
&false; on errors
</para>
<para>
<function>sesam_commit</function> commits any pending updates to
the database.
</para>
<para>
Note that there is no "auto-commit" feature as in other
databases, as it could lead to accidental data loss. Uncommitted
data at the end of the current script (or when calling
<function>sesam_disconnect</function>) will be discarded by an
implied <function>sesam_rollback</function> call.
</para>
<para>
</para>
<para>
See also: <function>sesam_rollback</function>.
<example>
<title>Committing an update to the SESAM database</title>
<programlisting role="php">
<refentry id="function.sesam-commit">
<refnamediv>
<refname>sesam_commit</refname>
<refpurpose>Commit pending updates to the SESAM database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_commit</methodname>
<void/>
</methodsynopsis>
<para>
Returns: &true; on success,
&false; on errors
</para>
<para>
<function>sesam_commit</function> commits any pending updates to
the database.
</para>
<para>
Note that there is no "auto-commit" feature as in other
databases, as it could lead to accidental data loss. Uncommitted
data at the end of the current script (or when calling
<function>sesam_disconnect</function>) will be discarded by an
implied <function>sesam_rollback</function> call.
</para>
<para>
</para>
<para>
See also: <function>sesam_rollback</function>.
<example>
<title>Committing an update to the SESAM database</title>
<programlisting role="php">
<![CDATA[
<?php
if (sesam_connect ("mycatalog", "myschema", "otto")) {
@ -46,11 +44,11 @@ if (sesam_connect ("mycatalog", "myschema", "otto")) {
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

110
reference/sesam/functions/sesam-connect.xml
View file

@ -1,55 +1,55 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-connect">
<refnamediv>
<refname>sesam_connect</refname>
<refpurpose>Open SESAM database connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_connect</methodname>
<methodparam><type>string</type><parameter>catalog</parameter></methodparam>
<methodparam><type>string</type><parameter>schema</parameter></methodparam>
<methodparam><type>string</type><parameter>user</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if a connection to the SESAM
database was made, or &false; on error.
</para>
<para>
<function>sesam_connect</function> establishes a connection to an
SESAM database handler task. The connection is always
"persistent" in the sense that only the very first invocation
will actually load the driver from the configured SESAM OML PLAM
library. Subsequent calls will reuse the driver and will
immediately use the given catalog, schema, and user.
</para>
<para>
When creating a database, the <parameter>"catalog"</parameter>
name is specified in the SESAM configuration directive
<command>//ADD-SQL-DATABASE-CATALOG-LIST ENTRY-1 =
*CATALOG(CATALOG-NAME = catalogname,...)</command>
</para>
<para>
The <parameter>"schema"</parameter> references the desired
database schema (see SESAM handbook).
</para>
<para>
The <parameter>"user"</parameter> argument references one of the
users which are allowed to access this
<parameter>"catalog"</parameter> /
<parameter>"schema"</parameter> combination. Note that
<parameter>"user"</parameter> is completely independent from both
the system's user id's and from HTTP user/password protection. It
appears in the SESAM configuration only.
</para>
<para>
See also <function>sesam_disconnect</function>.
<example>
<title>Connect to a SESAM database</title>
<programlisting role="php">
<refentry id="function.sesam-connect">
<refnamediv>
<refname>sesam_connect</refname>
<refpurpose>Open SESAM database connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_connect</methodname>
<methodparam><type>string</type><parameter>catalog</parameter></methodparam>
<methodparam><type>string</type><parameter>schema</parameter></methodparam>
<methodparam><type>string</type><parameter>user</parameter></methodparam>
</methodsynopsis>
<para>
Returns &true; if a connection to the SESAM
database was made, or &false; on error.
</para>
<para>
<function>sesam_connect</function> establishes a connection to an
SESAM database handler task. The connection is always
"persistent" in the sense that only the very first invocation
will actually load the driver from the configured SESAM OML PLAM
library. Subsequent calls will reuse the driver and will
immediately use the given catalog, schema, and user.
</para>
<para>
When creating a database, the <parameter>"catalog"</parameter>
name is specified in the SESAM configuration directive
<command>//ADD-SQL-DATABASE-CATALOG-LIST ENTRY-1 =
*CATALOG(CATALOG-NAME = catalogname,...)</command>
</para>
<para>
The <parameter>"schema"</parameter> references the desired
database schema (see SESAM handbook).
</para>
<para>
The <parameter>"user"</parameter> argument references one of the
users which are allowed to access this
<parameter>"catalog"</parameter> /
<parameter>"schema"</parameter> combination. Note that
<parameter>"user"</parameter> is completely independent from both
the system's user id's and from HTTP user/password protection. It
appears in the SESAM configuration only.
</para>
<para>
See also <function>sesam_disconnect</function>.
<example>
<title>Connect to a SESAM database</title>
<programlisting role="php">
<![CDATA[
<?php
if (!sesam_connect ("mycatalog", "myschema", "otto")) {
@ -57,11 +57,11 @@ if (!sesam_connect ("mycatalog", "myschema", "otto")) {
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

168
reference/sesam/functions/sesam-diagnostic.xml
View file

@ -1,86 +1,84 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-diagnostic">
<refnamediv>
<refname>sesam_diagnostic</refname>
<refpurpose>
Return status information for last SESAM call
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_diagnostic</methodname>
<void/>
</methodsynopsis>
<para>
Returns an associative array of status and return codes for the
last SQL query/statement/command. Elements of the array are:
<table>
<title>
Status information returned by <function>sesam_diagnostic</function>
</title>
<tgroup cols="2">
<thead>
<row>
<entry>Element</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry>$array["sqlstate"]</entry>
<entry>
5 digit SQL return code (see the SESAM manual for the
description of the possible values of SQLSTATE)
</entry>
</row>
<row>
<entry>$array["rowcount"]</entry>
<entry>
number of affected rows in last update/insert/delete (set
after "immediate" statements only)
</entry>
</row>
<row>
<entry>$array["errmsg"]</entry>
<entry>
"human readable" error message string (set after errors
only)
</entry>
</row>
<row>
<entry>$array["errcol"]</entry>
<entry>
error column number of previous error (0-based; or -1 if
undefined. Set after errors only)
</entry>
</row>
<row>
<entry>$array["errlin"]</entry>
<entry>
error line number of previous error (0-based; or -1 if
undefined. Set after errors only)
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
In the following example, a syntax error (E SEW42AE ILLEGAL
CHARACTER) is displayed by including the offending SQL statement
and pointing to the error location:
<example>
<title>Displaying SESAM error messages with error position</title>
<programlisting role="php">
<refentry id="function.sesam-diagnostic">
<refnamediv>
<refname>sesam_diagnostic</refname>
<refpurpose>Return status information for last SESAM call</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_diagnostic</methodname>
<void/>
</methodsynopsis>
<para>
Returns an associative array of status and return codes for the
last SQL query/statement/command. Elements of the array are:
<table>
<title>
Status information returned by <function>sesam_diagnostic</function>
</title>
<tgroup cols="2">
<thead>
<row>
<entry>Element</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry>$array["sqlstate"]</entry>
<entry>
5 digit SQL return code (see the SESAM manual for the
description of the possible values of SQLSTATE)
</entry>
</row>
<row>
<entry>$array["rowcount"]</entry>
<entry>
number of affected rows in last update/insert/delete (set
after "immediate" statements only)
</entry>
</row>
<row>
<entry>$array["errmsg"]</entry>
<entry>
"human readable" error message string (set after errors
only)
</entry>
</row>
<row>
<entry>$array["errcol"]</entry>
<entry>
error column number of previous error (0-based; or -1 if
undefined. Set after errors only)
</entry>
</row>
<row>
<entry>$array["errlin"]</entry>
<entry>
error line number of previous error (0-based; or -1 if
undefined. Set after errors only)
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
In the following example, a syntax error (E SEW42AE ILLEGAL
CHARACTER) is displayed by including the offending SQL statement
and pointing to the error location:
<example>
<title>Displaying SESAM error messages with error position</title>
<programlisting role="php">
<![CDATA[
<?php
// Function which prints a formatted error message,
// displaying a pointer to the syntax error in the
// SQL statement
function PrintReturncode($exec_str)
function PrintReturncode($exec_str)
{
$err = Sesam_Diagnostic();
$colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount
@ -144,15 +142,15 @@ if (!($result = sesam_query ($stmt)))
PrintReturncode ($stmt);
?>
]]>
</programlisting>
</example>
</para>
<para>
See also: <function>sesam_errormsg</function> for simple access
to the error string only
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
See also: <function>sesam_errormsg</function> for simple access
to the error string only
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

94
reference/sesam/functions/sesam-disconnect.xml
View file

@ -1,59 +1,59 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-disconnect">
<refnamediv>
<refname>sesam_disconnect</refname>
<refpurpose>Detach from SESAM connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_disconnect</methodname>
<void/>
</methodsynopsis>
<para>
Returns: always &true;.
</para>
<para>
<function>sesam_disconnect</function> closes the logical link to
a SESAM database (without actually disconnecting and unloading
the driver).
</para>
<para>
Note that this isn't usually necessary, as the open connection is
automatically closed at the end of the script's execution.
Uncommitted data will be discarded, because an implicit
<function>sesam_rollback</function> is executed.
</para>
<para>
<function>sesam_disconnect</function> will not close the
persistent link, it will only invalidate the currently defined
<parameter>"catalog"</parameter>, <parameter>"schema"</parameter>
and <parameter>"user"</parameter> triple, so that any sesam
function called after <function>sesam_disconnect</function> will
fail.
</para>
<para>
<example>
<title>Closing a SESAM connection</title>
<programlisting role="php">
<refentry id="function.sesam-disconnect">
<refnamediv>
<refname>sesam_disconnect</refname>
<refpurpose>Detach from SESAM connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_disconnect</methodname>
<void/>
</methodsynopsis>
<para>
Returns: always &true;.
</para>
<para>
<function>sesam_disconnect</function> closes the logical link to
a SESAM database (without actually disconnecting and unloading
the driver).
</para>
<para>
Note that this isn't usually necessary, as the open connection is
automatically closed at the end of the script's execution.
Uncommitted data will be discarded, because an implicit
<function>sesam_rollback</function> is executed.
</para>
<para>
<function>sesam_disconnect</function> will not close the
persistent link, it will only invalidate the currently defined
<parameter>"catalog"</parameter>, <parameter>"schema"</parameter>
and <parameter>"user"</parameter> triple, so that any sesam
function called after <function>sesam_disconnect</function> will
fail.
</para>
<para>
<example>
<title>Closing a SESAM connection</title>
<programlisting role="php">
<![CDATA[
<?php
if (sesam_connect ("mycatalog", "myschema", "otto")) {
/* ... some queries and stuff ... */
sesam_disconnect();
sesam_disconnect();
}
?>
]]>
</programlisting>
</example>
</para>
<para>
See also <function>sesam_connect</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
See also <function>sesam_connect</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

58
reference/sesam/functions/sesam-errormsg.xml
View file

@ -1,25 +1,25 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-errormsg">
<refnamediv>
<refname>sesam_errormsg</refname>
<refpurpose>Returns error message of last SESAM call</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sesam_errormsg</methodname>
<void/>
</methodsynopsis>
<para>
Returns the SESAM error message associated with the most recent
SESAM error.
</para>
<para>
<example>
<title><function>sesam_errormsg</function> example</title>
<programlisting role="php">
<refentry id="function.sesam-errormsg">
<refnamediv>
<refname>sesam_errormsg</refname>
<refpurpose>Returns error message of last SESAM call</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sesam_errormsg</methodname>
<void/>
</methodsynopsis>
<para>
Returns the SESAM error message associated with the most recent
SESAM error.
</para>
<para>
<example>
<title><function>sesam_errormsg</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
if (!sesam_execimm($stmt)) {
@ -27,15 +27,15 @@ if (!sesam_execimm($stmt)) {
}
?>
]]>
</programlisting>
</example>
</para>
<para>
See also <function>sesam_diagnostic</function> for the full set
of SESAM SQL status information.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
<para>
See also <function>sesam_diagnostic</function> for the full set
of SESAM SQL status information.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

102
reference/sesam/functions/sesam-execimm.xml
View file

@ -1,47 +1,47 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-execimm">
<refnamediv>
<refname>sesam_execimm</refname>
<refpurpose>Execute an "immediate" SQL-statement</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sesam_execimm</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<para>
Returns: A SESAM "result identifier" on success, or
&false; on error.
</para>
<para>
<function>sesam_execimm</function> executes an "immediate"
statement (i.e., a statement like UPDATE, INSERT or DELETE which
returns no result, and has no INPUT or OUTPUT variables).
"select type" queries can not be used with
<function>sesam_execimm</function>. Sets the
<parameter>affected_rows</parameter> value for retrieval by the
<function>sesam_affected_rows</function> function.
</para>
<para>
Note that <function>sesam_query</function> can handle both
"immediate" and "select-type" queries. Use
<function>sesam_execimm</function> only if you know beforehand
what type of statement will be executed. An attempt to use
SELECT type queries with <function>sesam_execimm</function> will
return <literal>$err["sqlstate"] == "42SBW"</literal>.
</para>
<para>
The returned "result identifier" can not be used for retrieving
anything but the <function>sesam_affected_rows</function>; it is
only returned for symmetry with the
<function>sesam_query</function> function.
</para>
<para>
<informalexample>
<programlisting role="php">
<refentry id="function.sesam-execimm">
<refnamediv>
<refname>sesam_execimm</refname>
<refpurpose>Execute an "immediate" SQL-statement</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sesam_execimm</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<para>
Returns: A SESAM "result identifier" on success, or
&false; on error.
</para>
<para>
<function>sesam_execimm</function> executes an "immediate"
statement (i.e., a statement like UPDATE, INSERT or DELETE which
returns no result, and has no INPUT or OUTPUT variables).
"select type" queries can not be used with
<function>sesam_execimm</function>. Sets the
<parameter>affected_rows</parameter> value for retrieval by the
<function>sesam_affected_rows</function> function.
</para>
<para>
Note that <function>sesam_query</function> can handle both
"immediate" and "select-type" queries. Use
<function>sesam_execimm</function> only if you know beforehand
what type of statement will be executed. An attempt to use
SELECT type queries with <function>sesam_execimm</function> will
return <literal>$err["sqlstate"] == "42SBW"</literal>.
</para>
<para>
The returned "result identifier" can not be used for retrieving
anything but the <function>sesam_affected_rows</function>; it is
only returned for symmetry with the
<function>sesam_query</function> function.
</para>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$stmt = "INSERT INTO mytable VALUES ('one', 'two')";
@ -52,15 +52,15 @@ echo "sqlstate = " . $err["sqlstate"] . "\n".
sesam_affected_rows($result) . "\n";
?>
]]>
</programlisting>
</informalexample>
</para>
<para>
See also <function>sesam_query</function> and
<function>sesam_affected_rows</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</informalexample>
</para>
<para>
See also <function>sesam_query</function> and
<function>sesam_affected_rows</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

178
reference/sesam/functions/sesam-fetch-array.xml
View file

@ -1,92 +1,92 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-fetch-array">
<refnamediv>
<refname>sesam_fetch_array</refname>
<refpurpose>Fetch one row as an associative array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_fetch_array</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
Returns an array that corresponds to the fetched row, or
&false; if there are no more rows.
</para>
<para>
<function>sesam_fetch_array</function> is an alternative version
of <function>sesam_fetch_row</function>. Instead of storing the
data in the numeric indices of the result array, it stores the
data in associative indices, using the field names as keys.
</para>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function> (select type queries only!).
</para>
<para>
For the valid values of the optional
<parameter>whence</parameter>and
<parameter>offset</parameter> parameters,
see the <function>sesam_fetch_row</function> function for
details.
</para>
<para>
<function>sesam_fetch_array</function> fetches one row of data
from the result associated with the specified result identifier.
The row is returned as an associative array. Each result column
is stored with an associative index equal to its column
(aka. field) name. The column names are converted to lower case.
</para>
<para>
Columns without a field name (e.g., results of arithmetic
operations) and empty fields are not stored in the array. Also,
if two or more columns of the result have the same column names,
the later column will take precedence. In this situation, either
call <function>sesam_fetch_row</function> or make an alias for
the column.
<informalexample>
<programlisting role="sesam">
<refentry id="function.sesam-fetch-array">
<refnamediv>
<refname>sesam_fetch_array</refname>
<refpurpose>Fetch one row as an associative array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_fetch_array</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
Returns an array that corresponds to the fetched row, or
&false; if there are no more rows.
</para>
<para>
<function>sesam_fetch_array</function> is an alternative version
of <function>sesam_fetch_row</function>. Instead of storing the
data in the numeric indices of the result array, it stores the
data in associative indices, using the field names as keys.
</para>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function> (select type queries only!).
</para>
<para>
For the valid values of the optional
<parameter>whence</parameter>and
<parameter>offset</parameter> parameters,
see the <function>sesam_fetch_row</function> function for
details.
</para>
<para>
<function>sesam_fetch_array</function> fetches one row of data
from the result associated with the specified result identifier.
The row is returned as an associative array. Each result column
is stored with an associative index equal to its column
(aka. field) name. The column names are converted to lower case.
</para>
<para>
Columns without a field name (e.g., results of arithmetic
operations) and empty fields are not stored in the array. Also,
if two or more columns of the result have the same column names,
the later column will take precedence. In this situation, either
call <function>sesam_fetch_row</function> or make an alias for
the column.
<informalexample>
<programlisting role="sesam">
<![CDATA[
SELECT TBL1.COL AS FOO, TBL2.COL AS BAR FROM TBL1, TBL2
]]>
</programlisting>
</informalexample>
</para>
<para>
A special handling allows fetching "multiple field" columns
(which would otherwise all have the same column names). For each
column of a "multiple field", the index name is constructed by
appending the string "(n)" where n is the sub-index of the
multiple field column, ranging from 1 to its declared repetition
factor. The indices are NOT zero based, in order to match the
nomenclature used in the respective query syntax. For a column
declared as:
<informalexample>
<programlisting role="sesam">
</programlisting>
</informalexample>
</para>
<para>
A special handling allows fetching "multiple field" columns
(which would otherwise all have the same column names). For each
column of a "multiple field", the index name is constructed by
appending the string "(n)" where n is the sub-index of the
multiple field column, ranging from 1 to its declared repetition
factor. The indices are NOT zero based, in order to match the
nomenclature used in the respective query syntax. For a column
declared as:
<informalexample>
<programlisting role="sesam">
<![CDATA[
CREATE TABLE ... ( ... MULTI(3) INT )
]]>
</programlisting>
</informalexample>
the associative indices used for the individual "multiple field"
columns would be <literal>"multi(1)"</literal>,
<literal>"multi(2)"</literal>, and <literal>"multi(3)"</literal>
respectively.
</para>
<para>
Subsequent calls to <function>sesam_fetch_array</function> would
return the next (or prior, or n'th next/prior, depending on the
scroll attributes) row in the result set, or
&false; if there are no more rows.
</para>
<example>
<title>SESAM fetch array</title>
<programlisting role="php">
</programlisting>
</informalexample>
the associative indices used for the individual "multiple field"
columns would be <literal>"multi(1)"</literal>,
<literal>"multi(2)"</literal>, and <literal>"multi(3)"</literal>
respectively.
</para>
<para>
Subsequent calls to <function>sesam_fetch_array</function> would
return the next (or prior, or n'th next/prior, depending on the
scroll attributes) row in the result set, or
&false; if there are no more rows.
</para>
<example>
<title>SESAM fetch array</title>
<programlisting role="php">
<![CDATA[
<?php
$result = sesam_query("SELECT * FROM phone\n" .
@ -108,14 +108,14 @@ echo "</table>\n";
sesam_free_result($result);
?>
]]>
</programlisting>
</example>
<para>
See also: <function>sesam_fetch_row</function> which returns an
indexed array.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<para>
See also: <function>sesam_fetch_row</function> which returns an
indexed array.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

182
reference/sesam/functions/sesam-fetch-result.xml
View file

@ -1,96 +1,96 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-fetch-result">
<refnamediv>
<refname>sesam_fetch_result</refname>
<refpurpose>Return all or part of a query result</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>sesam_fetch_result</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>max_rows</parameter></methodparam>
</methodsynopsis>
<para>
Returns a mixed array with the query result entries, optionally
limited to a maximum of <parameter>max_rows</parameter> rows.
Note that both row and column indexes are zero-based.
<table>
<title>
Mixed result set returned by <function>sesam_fetch_result</function>
</title>
<tgroup cols="2">
<thead>
<row>
<entry>Array Element</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry>int $arr["count"]</entry>
<entry>
number of columns in result set (or zero if this was an
"immediate" query)
</entry>
</row>
<row>
<entry>int $arr["rows"]</entry>
<entry>
number of rows in result set (between zero and
<parameter>max_rows</parameter>)
</entry>
</row>
<row>
<entry>bool $arr["truncated"]</entry>
<entry>
&true; if the number of rows was at least
<parameter>max_rows</parameter>, &false;
otherwise. Note that even when this is
&true;, the next
<function>sesam_fetch_result</function> call may return zero
rows because there are no more result entries.
</entry>
</row>
<row>
<entry>mixed $arr[col][row]</entry>
<entry>
result data for all the fields at
row(<literal>row</literal>) and
column(<literal>col</literal>), (where the integer index
<literal>row</literal> is between 0 and
<literal>$arr["rows"]-1</literal>, and
<literal>col</literal> is between 0 and
<literal>$arr["count"]-1</literal>). Fields may be empty, so
you must check for the existence of a field by using the php
<function>isset</function> function. The type of the
returned fields depend on the respective SQL type declared
for its column (see <link linkend="ref.sesam">SESAM
overview</link> for the conversions applied). SESAM
"multiple fields" are "inlined" and treated like a sequence
of columns.
</entry>
</row>
</tbody>
</tgroup>
</table>
Note that the amount of memory used up by a large query may be
gigantic. Use the <parameter>max_rows</parameter> parameter to
limit the maximum number of rows returned, unless you are
absolutely sure that your result will not use up all available
memory.
</para>
<para>
See also: <function>sesam_fetch_row</function>, and
<function>sesam_field_array</function> to check for "multiple
fields". See the description of the
<function>sesam_query</function> function for a complete example
using <function>sesam_fetch_result</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.sesam-fetch-result">
<refnamediv>
<refname>sesam_fetch_result</refname>
<refpurpose>Return all or part of a query result</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>sesam_fetch_result</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>max_rows</parameter></methodparam>
</methodsynopsis>
<para>
Returns a mixed array with the query result entries, optionally
limited to a maximum of <parameter>max_rows</parameter> rows.
Note that both row and column indexes are zero-based.
<table>
<title>
Mixed result set returned by <function>sesam_fetch_result</function>
</title>
<tgroup cols="2">
<thead>
<row>
<entry>Array Element</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry>int $arr["count"]</entry>
<entry>
number of columns in result set (or zero if this was an
"immediate" query)
</entry>
</row>
<row>
<entry>int $arr["rows"]</entry>
<entry>
number of rows in result set (between zero and
<parameter>max_rows</parameter>)
</entry>
</row>
<row>
<entry>bool $arr["truncated"]</entry>
<entry>
&true; if the number of rows was at least
<parameter>max_rows</parameter>, &false;
otherwise. Note that even when this is
&true;, the next
<function>sesam_fetch_result</function> call may return zero
rows because there are no more result entries.
</entry>
</row>
<row>
<entry>mixed $arr[col][row]</entry>
<entry>
result data for all the fields at
row(<literal>row</literal>) and
column(<literal>col</literal>), (where the integer index
<literal>row</literal> is between 0 and
<literal>$arr["rows"]-1</literal>, and
<literal>col</literal> is between 0 and
<literal>$arr["count"]-1</literal>). Fields may be empty, so
you must check for the existence of a field by using the php
<function>isset</function> function. The type of the
returned fields depend on the respective SQL type declared
for its column (see <link linkend="ref.sesam">SESAM
overview</link> for the conversions applied). SESAM
"multiple fields" are "inlined" and treated like a sequence
of columns.
</entry>
</row>
</tbody>
</tgroup>
</table>
Note that the amount of memory used up by a large query may be
gigantic. Use the <parameter>max_rows</parameter> parameter to
limit the maximum number of rows returned, unless you are
absolutely sure that your result will not use up all available
memory.
</para>
<para>
See also: <function>sesam_fetch_row</function>, and
<function>sesam_field_array</function> to check for "multiple
fields". See the description of the
<function>sesam_query</function> function for a complete example
using <function>sesam_fetch_result</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

298
reference/sesam/functions/sesam-fetch-row.xml
View file

@ -1,145 +1,145 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.8 $ -->
<!-- $Revision: 1.9 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-fetch-row">
<refnamediv>
<refname>sesam_fetch_row</refname>
<refpurpose>Fetch one row as an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_fetch_row</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
Returns an array that corresponds to the fetched row, or
&false; if there are no more rows.
</para>
<para>
The number of columns in the result set is returned in an
associative array element $array["count"]. Because some of the
result columns may be empty, the <function>count</function>
function can not be used on the result row returned by
<function>sesam_fetch_row</function>.
</para>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function> (select type queries only!).
</para>
<para>
<parameter>whence</parameter> is an optional
parameter for a fetch operation on "scrollable" cursors, which
can be set to the following predefined constants:
<table>
<title>Valid values for <parameter>"whence"</parameter> parameter</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry><literal>SESAM_SEEK_NEXT</literal></entry>
<entry>
read sequentially (after fetch, the internal default is set
to <literal>SESAM_SEEK_NEXT</literal>)
</entry>
</row>
<row>
<entry>1</entry>
<entry><literal>SESAM_SEEK_PRIOR</literal></entry>
<entry>
read sequentially backwards (after fetch, the internal
default is set to <literal>SESAM_SEEK_PRIOR</literal>)
</entry>
</row>
<row>
<entry>2</entry>
<entry><literal>SESAM_SEEK_FIRST</literal></entry>
<entry>
rewind to first row (after fetch, the default is set to
<literal>SESAM_SEEK_NEXT</literal>)
</entry>
</row>
<row>
<entry>3</entry>
<entry><literal>SESAM_SEEK_LAST</literal></entry>
<entry>
seek to last row (after fetch, the default is set to
<literal>SESAM_SEEK_PRIOR</literal>)
</entry>
</row>
<row>
<entry>4</entry>
<entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry>
<entry>
seek to absolute row number given as
<parameter>offset</parameter> (Zero-based. After fetch, the
internal default is set to
<literal>SESAM_SEEK_ABSOLUTE</literal>, and the internal
offset value is auto-incremented)
</entry>
</row>
<row>
<entry>5</entry>
<entry><literal>SESAM_SEEK_RELATIVE</literal></entry>
<entry>
seek relative to current scroll position, where
<parameter>offset</parameter> can be a positive or negative
offset value.
</entry>
</row>
</tbody>
</tgroup>
</table>
This parameter is only valid for "scrollable" cursors.
</para>
<para>
When using "scrollable" cursors, the cursor can be freely
positioned on the result set. If the
<parameter>whence</parameter> parameter is
omitted, the global default values for the scrolling type
(initialized to: <literal>SESAM_SEEK_NEXT</literal>, and settable
by <function>sesam_seek_row</function>) are used. If
<parameter>whence</parameter> is supplied,
its value replaces the global default.
</para>
<para>
<parameter>offset</parameter> is an optional
parameter which is only evaluated (and required) if
<parameter>whence</parameter> is either
<literal>SESAM_SEEK_RELATIVE</literal> or
<literal>SESAM_SEEK_ABSOLUTE</literal>. This parameter is only
valid for "scrollable" cursors.
</para>
<para>
<function>sesam_fetch_row</function> fetches one row of data from
the result associated with the specified result identifier. The
row is returned as an array (indexed by values between
<literal>0</literal> and <literal>$array["count"]-1</literal>).
Fields may be empty, so you must check for the existence of a
field by using the <function>isset</function> function. The
type of the returned fields depend on the respective SQL type
declared for its column (see <link linkend="ref.sesam">SESAM
overview</link> for the conversions applied). SESAM "multiple
fields" are "inlined" and treated like a sequence of columns.
</para>
<para>
Subsequent calls to <function>sesam_fetch_row</function> would
return the next (or prior, or n'th next/prior, depending on the
scroll attributes) row in the result set, or
&false; if there are no more rows.
</para>
<example>
<title>SESAM fetch rows</title>
<programlisting role="php">
<refentry id="function.sesam-fetch-row">
<refnamediv>
<refname>sesam_fetch_row</refname>
<refpurpose>Fetch one row as an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_fetch_row</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
Returns an array that corresponds to the fetched row, or
&false; if there are no more rows.
</para>
<para>
The number of columns in the result set is returned in an
associative array element $array["count"]. Because some of the
result columns may be empty, the <function>count</function>
function can not be used on the result row returned by
<function>sesam_fetch_row</function>.
</para>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function> (select type queries only!).
</para>
<para>
<parameter>whence</parameter> is an optional
parameter for a fetch operation on "scrollable" cursors, which
can be set to the following predefined constants:
<table>
<title>Valid values for <parameter>"whence"</parameter> parameter</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry><literal>SESAM_SEEK_NEXT</literal></entry>
<entry>
read sequentially (after fetch, the internal default is set
to <literal>SESAM_SEEK_NEXT</literal>)
</entry>
</row>
<row>
<entry>1</entry>
<entry><literal>SESAM_SEEK_PRIOR</literal></entry>
<entry>
read sequentially backwards (after fetch, the internal
default is set to <literal>SESAM_SEEK_PRIOR</literal>)
</entry>
</row>
<row>
<entry>2</entry>
<entry><literal>SESAM_SEEK_FIRST</literal></entry>
<entry>
rewind to first row (after fetch, the default is set to
<literal>SESAM_SEEK_NEXT</literal>)
</entry>
</row>
<row>
<entry>3</entry>
<entry><literal>SESAM_SEEK_LAST</literal></entry>
<entry>
seek to last row (after fetch, the default is set to
<literal>SESAM_SEEK_PRIOR</literal>)
</entry>
</row>
<row>
<entry>4</entry>
<entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry>
<entry>
seek to absolute row number given as
<parameter>offset</parameter> (Zero-based. After fetch, the
internal default is set to
<literal>SESAM_SEEK_ABSOLUTE</literal>, and the internal
offset value is auto-incremented)
</entry>
</row>
<row>
<entry>5</entry>
<entry><literal>SESAM_SEEK_RELATIVE</literal></entry>
<entry>
seek relative to current scroll position, where
<parameter>offset</parameter> can be a positive or negative
offset value.
</entry>
</row>
</tbody>
</tgroup>
</table>
This parameter is only valid for "scrollable" cursors.
</para>
<para>
When using "scrollable" cursors, the cursor can be freely
positioned on the result set. If the
<parameter>whence</parameter> parameter is
omitted, the global default values for the scrolling type
(initialized to: <literal>SESAM_SEEK_NEXT</literal>, and settable
by <function>sesam_seek_row</function>) are used. If
<parameter>whence</parameter> is supplied,
its value replaces the global default.
</para>
<para>
<parameter>offset</parameter> is an optional
parameter which is only evaluated (and required) if
<parameter>whence</parameter> is either
<literal>SESAM_SEEK_RELATIVE</literal> or
<literal>SESAM_SEEK_ABSOLUTE</literal>. This parameter is only
valid for "scrollable" cursors.
</para>
<para>
<function>sesam_fetch_row</function> fetches one row of data from
the result associated with the specified result identifier. The
row is returned as an array (indexed by values between
<literal>0</literal> and <literal>$array["count"]-1</literal>).
Fields may be empty, so you must check for the existence of a
field by using the <function>isset</function> function. The
type of the returned fields depend on the respective SQL type
declared for its column (see <link linkend="ref.sesam">SESAM
overview</link> for the conversions applied). SESAM "multiple
fields" are "inlined" and treated like a sequence of columns.
</para>
<para>
Subsequent calls to <function>sesam_fetch_row</function> would
return the next (or prior, or n'th next/prior, depending on the
scroll attributes) row in the result set, or
&false; if there are no more rows.
</para>
<example>
<title>SESAM fetch rows</title>
<programlisting role="php">
<![CDATA[
<?php
$result = sesam_query("SELECT * FROM phone\n" .
@ -164,15 +164,15 @@ echo "</table>\n";
sesam_free_result($result);
?>
]]>
</programlisting>
</example>
<para>
See also: <function>sesam_fetch_array</function> which returns an
associative array, and <function>sesam_fetch_result</function>
which returns many rows per invocation.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<para>
See also: <function>sesam_fetch_array</function> which returns an
associative array, and <function>sesam_fetch_result</function>
which returns many rows per invocation.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

380
reference/sesam/functions/sesam-field-array.xml
View file

@ -1,196 +1,194 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-field-array">
<refnamediv>
<refname>sesam_field_array</refname>
<refpurpose>
Return meta information about individual columns in a result
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_field_array</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function>.
</para>
<para>
Returns a mixed associative/indexed array with meta information
(column name, type, precision, ...) about individual columns of
the result after the query associated with
<parameter>result_id</parameter>.
</para>
<para>
<table>
<title>
Mixed result set returned by <function>sesam_field_array</function>
</title>
<tgroup cols="2">
<thead>
<row>
<entry>Array Element</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry>int $arr["count"]</entry>
<entry>
Total number of columns in result set (or zero if this was
an "immediate" query). SESAM "multiple fields" are
"inlined" and treated like the respective number of columns.
</entry>
</row>
<row>
<entry>string $arr[col]["name"]</entry>
<entry>
column name for column(<literal>col</literal>), where
<literal>col</literal> is between 0 and
<literal>$arr["count"]-1</literal>. The returned value can
be the empty string (for dynamically computed
columns). SESAM "multiple fields" are "inlined" and treated
like the respective number of columns, each with the same
column name.
</entry>
</row>
<row>
<entry>string $arr[col]["count"]</entry>
<entry>
The "count" attribute describes the repetition factor when
the column has been declared as a "multiple field". Usually,
the "count" attribute is 1. The first column of a "multiple
field" column however contains the number of repetitions
(the second and following column of the "multiple field"
contain a "count" attribute of 1). This can be used to
detect "multiple fields" in the result set. See the example
shown in the <function>sesam_query</function> description
for a sample use of the "count" attribute.
</entry>
</row>
<row>
<entry>string $arr[col]["type"]</entry>
<entry>
PHP variable type of the data for
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
returned value can be one of
<itemizedlist>
<listitem>
<simpara><type>integer</type></simpara>
</listitem>
<listitem>
<simpara><type>float</type></simpara>
</listitem>
<listitem>
<simpara><type>string</type></simpara>
</listitem>
</itemizedlist>
depending on the SQL type of the result. SESAM "multiple
fields" are "inlined" and treated like the respective number
of columns, each with the same PHP type.
</entry>
</row>
<row>
<entry>string $arr[col]["sqltype"]</entry>
<entry>
SQL variable type of the column data for
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
returned value can be one of
<itemizedlist>
<listitem>
<simpara>"CHARACTER"</simpara>
</listitem>
<listitem>
<simpara>"VARCHAR"</simpara>
</listitem>
<listitem>
<simpara>"NUMERIC"</simpara>
</listitem>
<listitem>
<simpara>"DECIMAL"</simpara>
</listitem>
<listitem>
<simpara>"INTEGER"</simpara>
</listitem>
<listitem>
<simpara>"SMALLINT"</simpara>
</listitem>
<listitem>
<simpara>"FLOAT"</simpara>
</listitem>
<listitem>
<simpara>"REAL"</simpara>
</listitem>
<listitem>
<simpara>"DOUBLE"</simpara>
</listitem>
<listitem>
<simpara>"DATE"</simpara>
</listitem>
<listitem>
<simpara>"TIME"</simpara>
</listitem>
<listitem>
<simpara>"TIMESTAMP"</simpara>
</listitem>
</itemizedlist>
describing the SQL type of the result. SESAM "multiple
fields" are "inlined" and treated like the respective number
of columns, each with the same SQL type.
</entry>
</row>
<row>
<entry>string $arr[col]["length"]</entry>
<entry>
The SQL "length" attribute of the SQL variable in
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
"length" attribute is used with "CHARACTER" and "VARCHAR"
SQL types to specify the (maximum) length of the string
variable. SESAM "multiple fields" are "inlined" and treated
like the respective number of columns, each with the same
length attribute.
</entry>
</row>
<row>
<entry>string $arr[col]["precision"]</entry>
<entry>
The "precision" attribute of the SQL variable in
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
"precision" attribute is used with numeric and time data
types. SESAM "multiple fields" are "inlined" and treated
like the respective number of columns, each with the same
precision attribute.
</entry>
</row>
<row>
<entry>string $arr[col]["scale"]</entry>
<entry>
The "scale" attribute of the SQL variable in
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
"scale" attribute is used with numeric data types. SESAM
"multiple fields" are "inlined" and treated like the
respective number of columns, each with the same scale
attribute.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
See also <function>sesam_query</function> for an example
of the <function>sesam_field_array</function> use.
</para>
</refsect1>
</refentry>
<refentry id="function.sesam-field-array">
<refnamediv>
<refname>sesam_field_array</refname>
<refpurpose>Return meta information about individual columns in a result</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>sesam_field_array</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>result_id</parameter> is a valid result id returned by
<function>sesam_query</function>.
</para>
<para>
Returns a mixed associative/indexed array with meta information
(column name, type, precision, ...) about individual columns of
the result after the query associated with
<parameter>result_id</parameter>.
</para>
<para>
<table>
<title>
Mixed result set returned by <function>sesam_field_array</function>
</title>
<tgroup cols="2">
<thead>
<row>
<entry>Array Element</entry>
<entry>Contents</entry>
</row>
</thead>
<tbody>
<row>
<entry>int $arr["count"]</entry>
<entry>
Total number of columns in result set (or zero if this was
an "immediate" query). SESAM "multiple fields" are
"inlined" and treated like the respective number of columns.
</entry>
</row>
<row>
<entry>string $arr[col]["name"]</entry>
<entry>
column name for column(<literal>col</literal>), where
<literal>col</literal> is between 0 and
<literal>$arr["count"]-1</literal>. The returned value can
be the empty string (for dynamically computed
columns). SESAM "multiple fields" are "inlined" and treated
like the respective number of columns, each with the same
column name.
</entry>
</row>
<row>
<entry>string $arr[col]["count"]</entry>
<entry>
The "count" attribute describes the repetition factor when
the column has been declared as a "multiple field". Usually,
the "count" attribute is 1. The first column of a "multiple
field" column however contains the number of repetitions
(the second and following column of the "multiple field"
contain a "count" attribute of 1). This can be used to
detect "multiple fields" in the result set. See the example
shown in the <function>sesam_query</function> description
for a sample use of the "count" attribute.
</entry>
</row>
<row>
<entry>string $arr[col]["type"]</entry>
<entry>
PHP variable type of the data for
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
returned value can be one of
<itemizedlist>
<listitem>
<simpara><type>integer</type></simpara>
</listitem>
<listitem>
<simpara><type>float</type></simpara>
</listitem>
<listitem>
<simpara><type>string</type></simpara>
</listitem>
</itemizedlist>
depending on the SQL type of the result. SESAM "multiple
fields" are "inlined" and treated like the respective number
of columns, each with the same PHP type.
</entry>
</row>
<row>
<entry>string $arr[col]["sqltype"]</entry>
<entry>
SQL variable type of the column data for
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
returned value can be one of
<itemizedlist>
<listitem>
<simpara>"CHARACTER"</simpara>
</listitem>
<listitem>
<simpara>"VARCHAR"</simpara>
</listitem>
<listitem>
<simpara>"NUMERIC"</simpara>
</listitem>
<listitem>
<simpara>"DECIMAL"</simpara>
</listitem>
<listitem>
<simpara>"INTEGER"</simpara>
</listitem>
<listitem>
<simpara>"SMALLINT"</simpara>
</listitem>
<listitem>
<simpara>"FLOAT"</simpara>
</listitem>
<listitem>
<simpara>"REAL"</simpara>
</listitem>
<listitem>
<simpara>"DOUBLE"</simpara>
</listitem>
<listitem>
<simpara>"DATE"</simpara>
</listitem>
<listitem>
<simpara>"TIME"</simpara>
</listitem>
<listitem>
<simpara>"TIMESTAMP"</simpara>
</listitem>
</itemizedlist>
describing the SQL type of the result. SESAM "multiple
fields" are "inlined" and treated like the respective number
of columns, each with the same SQL type.
</entry>
</row>
<row>
<entry>string $arr[col]["length"]</entry>
<entry>
The SQL "length" attribute of the SQL variable in
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
"length" attribute is used with "CHARACTER" and "VARCHAR"
SQL types to specify the (maximum) length of the string
variable. SESAM "multiple fields" are "inlined" and treated
like the respective number of columns, each with the same
length attribute.
</entry>
</row>
<row>
<entry>string $arr[col]["precision"]</entry>
<entry>
The "precision" attribute of the SQL variable in
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
"precision" attribute is used with numeric and time data
types. SESAM "multiple fields" are "inlined" and treated
like the respective number of columns, each with the same
precision attribute.
</entry>
</row>
<row>
<entry>string $arr[col]["scale"]</entry>
<entry>
The "scale" attribute of the SQL variable in
column(<literal>col</literal>), where <literal>col</literal>
is between 0 and <literal>$arr["count"]-1</literal>. The
"scale" attribute is used with numeric data types. SESAM
"multiple fields" are "inlined" and treated like the
respective number of columns, each with the same scale
attribute.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
See also <function>sesam_query</function> for an example
of the <function>sesam_field_array</function> use.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

68
reference/sesam/functions/sesam-field-name.xml
View file

@ -1,40 +1,38 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-field-name">
<refnamediv>
<refname>sesam_field_name</refname>
<refpurpose>
Return one column name of the result set
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_field_name</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>index</parameter></methodparam>
</methodsynopsis>
<para>
Returns the name of a field (i.e., the column name) in the result
set, or &false; on error.
</para>
<para>
For "immediate" queries, or for dynamic columns, an empty string
is returned.
</para>
<note>
<para>
The column index is zero-based, not one-based as in SESAM.
</para>
</note>
<para>
See also: <function>sesam_field_array</function>. It provides an
easier interface to access the column names and types, and allows
for detection of "multiple fields".
</para>
</refsect1>
</refentry>
<refentry id="function.sesam-field-name">
<refnamediv>
<refname>sesam_field_name</refname>
<refpurpose>Return one column name of the result set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_field_name</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>index</parameter></methodparam>
</methodsynopsis>
<para>
Returns the name of a field (i.e., the column name) in the result
set, or &false; on error.
</para>
<para>
For "immediate" queries, or for dynamic columns, an empty string
is returned.
</para>
<note>
<para>
The column index is zero-based, not one-based as in SESAM.
</para>
</note>
<para>
See also: <function>sesam_field_array</function>. It provides an
easier interface to access the column names and types, and allows
for detection of "multiple fields".
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

38
reference/sesam/functions/sesam-free-result.xml
View file

@ -1,24 +1,24 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-free-result">
<refnamediv>
<refname>sesam_free_result</refname>
<refpurpose>Releases resources for the query</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_free_result</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
Releases resources for the query associated with
<parameter>result_id</parameter>. Returns
&false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.sesam-free-result">
<refnamediv>
<refname>sesam_free_result</refname>
<refpurpose>Releases resources for the query</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_free_result</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
Releases resources for the query associated with
<parameter>result_id</parameter>. Returns
&false; on error.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

66
reference/sesam/functions/sesam-num-fields.xml
View file

@ -1,39 +1,37 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-num-fields">
<refnamediv>
<refname>sesam_num_fields</refname>
<refpurpose>
Return the number of fields/columns in a result set
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_num_fields</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
After calling <function>sesam_query</function> with a "select
type" query, this function gives you the number of columns in the
result. Returns an integer describing the total number of
columns (aka. fields) in the current
<parameter>result_id</parameter> result set or
&false; on error.
</para>
<para>
For "immediate" statements, the value zero is returned. The SESAM
"multiple field" columns count as their respective dimension,
i.e., a three-column "multiple field" counts as three columns.
</para>
<para>
See also: <function>sesam_query</function> and
<function>sesam_field_array</function> for a way to distinguish
between "multiple field" columns and regular columns.
</para>
</refsect1>
</refentry>
<refentry id="function.sesam-num-fields">
<refnamediv>
<refname>sesam_num_fields</refname>
<refpurpose>Return the number of fields/columns in a result set</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>sesam_num_fields</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
</methodsynopsis>
<para>
After calling <function>sesam_query</function> with a "select
type" query, this function gives you the number of columns in the
result. Returns an integer describing the total number of
columns (aka. fields) in the current
<parameter>result_id</parameter> result set or
&false; on error.
</para>
<para>
For "immediate" statements, the value zero is returned. The SESAM
"multiple field" columns count as their respective dimension,
i.e., a three-column "multiple field" counts as three columns.
</para>
<para>
See also: <function>sesam_query</function> and
<function>sesam_field_array</function> for a way to distinguish
between "multiple field" columns and regular columns.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

124
reference/sesam/functions/sesam-query.xml
View file

@ -1,62 +1,62 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-query">
<refnamediv>
<refname>sesam_query</refname>
<refpurpose>Perform a SESAM SQL query and prepare the result</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sesam_query</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>scrollable</parameter></methodparam>
</methodsynopsis>
<para>
Returns: A SESAM "result identifier" on success, or
&false; on error.
</para>
<para>
A "result_id" resource is used by other functions to retrieve the
query results.
</para>
<para>
<function>sesam_query</function> sends a query to the currently
active database on the server. It can execute both "immediate"
SQL statements and "select type" queries. If an "immediate"
statement is executed, then no cursor is allocated, and any
subsequent <function>sesam_fetch_row</function> or
<function>sesam_fetch_result</function> call will return an empty
result (zero columns, indicating end-of-result). For "select
type" statements, a result descriptor and a (scrollable or
sequential, depending on the optional boolean
<parameter>scrollable</parameter> parameter) cursor will be
allocated. If <parameter>scrollable</parameter> is omitted, the
cursor will be sequential.
</para>
<para>
When using "scrollable" cursors, the cursor can be freely
positioned on the result set. For each "scrollable" query, there
are global default values for the scrolling type (initialized to:
<literal>SESAM_SEEK_NEXT</literal>) and the scrolling offset
which can either be set once by
<function>sesam_seek_row</function> or each time when fetching a
row using <function>sesam_fetch_row</function>.
</para>
<para>
For "immediate" statements, the number of affected rows is saved
for retrieval by the <function>sesam_affected_rows</function>
function.
</para>
<para>
See also: <function>sesam_fetch_row</function> and
<function>sesam_fetch_result</function>.
<example>
<title>
Show all rows of the "phone" table as a HTML table
</title>
<programlisting role="php">
<refentry id="function.sesam-query">
<refnamediv>
<refname>sesam_query</refname>
<refpurpose>Perform a SESAM SQL query and prepare the result</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>sesam_query</methodname>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>scrollable</parameter></methodparam>
</methodsynopsis>
<para>
Returns: A SESAM "result identifier" on success, or
&false; on error.
</para>
<para>
A "result_id" resource is used by other functions to retrieve the
query results.
</para>
<para>
<function>sesam_query</function> sends a query to the currently
active database on the server. It can execute both "immediate"
SQL statements and "select type" queries. If an "immediate"
statement is executed, then no cursor is allocated, and any
subsequent <function>sesam_fetch_row</function> or
<function>sesam_fetch_result</function> call will return an empty
result (zero columns, indicating end-of-result). For "select
type" statements, a result descriptor and a (scrollable or
sequential, depending on the optional boolean
<parameter>scrollable</parameter> parameter) cursor will be
allocated. If <parameter>scrollable</parameter> is omitted, the
cursor will be sequential.
</para>
<para>
When using "scrollable" cursors, the cursor can be freely
positioned on the result set. For each "scrollable" query, there
are global default values for the scrolling type (initialized to:
<literal>SESAM_SEEK_NEXT</literal>) and the scrolling offset
which can either be set once by
<function>sesam_seek_row</function> or each time when fetching a
row using <function>sesam_fetch_row</function>.
</para>
<para>
For "immediate" statements, the number of affected rows is saved
for retrieval by the <function>sesam_affected_rows</function>
function.
</para>
<para>
See also: <function>sesam_fetch_row</function> and
<function>sesam_fetch_result</function>.
<example>
<title>
Show all rows of the "phone" table as a HTML table
</title>
<programlisting role="php">
<![CDATA[
<?php
if (!sesam_connect("phonedb", "demo", "otto"))
@ -105,11 +105,11 @@ echo "</table>\n";
sesam_free_result($result);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

76
reference/sesam/functions/sesam-rollback.xml
View file

@ -1,39 +1,37 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-rollback">
<refnamediv>
<refname>sesam_rollback</refname>
<refpurpose>
Discard any pending updates to the SESAM database
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_rollback</methodname>
<void/>
</methodsynopsis>
<para>
Returns: &true; on success,
&false; on errors
</para>
<para>
<function>sesam_rollback</function> discards any pending updates
to the database. Also affected are result cursors and result
descriptors.
</para>
<para>
At the end of each script, and as part of the
<function>sesam_disconnect</function> function, an implied
<function>sesam_rollback</function> is executed, discarding any
pending changes to the database.
</para>
<para>
See also: <function>sesam_commit</function>.
<example>
<title>Discarding an update to the SESAM database</title>
<programlisting role="php">
<refentry id="function.sesam-rollback">
<refnamediv>
<refname>sesam_rollback</refname>
<refpurpose>Discard any pending updates to the SESAM database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_rollback</methodname>
<void/>
</methodsynopsis>
<para>
Returns: &true; on success,
&false; on errors
</para>
<para>
<function>sesam_rollback</function> discards any pending updates
to the database. Also affected are result cursors and result
descriptors.
</para>
<para>
At the end of each script, and as part of the
<function>sesam_disconnect</function> function, an implied
<function>sesam_rollback</function> is executed, discarding any
pending changes to the database.
</para>
<para>
See also: <function>sesam_commit</function>.
<example>
<title>Discarding an update to the SESAM database</title>
<programlisting role="php">
<![CDATA[
<?php
if (sesam_connect ("mycatalog", "myschema", "otto")) {
@ -46,11 +44,11 @@ if (sesam_connect ("mycatalog", "myschema", "otto")) {
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

194
reference/sesam/functions/sesam-seek-row.xml
View file

@ -1,103 +1,101 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-seek-row">
<refnamediv>
<refname>sesam_seek_row</refname>
<refpurpose>
Set scrollable cursor mode for subsequent fetches
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_seek_row</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>whence</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>result_id</parameter> is a valid result id (select
type queries only, and only if a "scrollable" cursor was
requested when calling <function>sesam_query</function>).
</para>
<para>
<parameter>whence</parameter> sets the global default value for
the scrolling type, it specifies the scroll type to use in
subsequent fetch operations on "scrollable" cursors, which can be
set to the following predefined constants:
<table>
<title>Valid values for <parameter>"whence"</parameter> parameter</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry><literal>SESAM_SEEK_NEXT</literal></entry>
<entry>read sequentially
</entry>
</row>
<row>
<entry>1</entry>
<entry><literal>SESAM_SEEK_PRIOR</literal></entry>
<entry>read sequentially backwards
</entry>
</row>
<row>
<entry>2</entry>
<entry><literal>SESAM_SEEK_FIRST</literal></entry>
<entry>
fetch first row (after fetch, the default is set to
<literal>SESAM_SEEK_NEXT</literal>)
</entry>
</row>
<row>
<entry>3</entry>
<entry><literal>SESAM_SEEK_LAST</literal></entry>
<entry>
fetch last row (after fetch, the default is set to
<literal>SESAM_SEEK_PRIOR</literal>)
</entry>
</row>
<row>
<entry>4</entry>
<entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry>
<entry>
fetch absolute row number given as
<parameter>offset</parameter> (Zero-based. After fetch, the
default is set to <literal>SESAM_SEEK_ABSOLUTE</literal>,
and the offset value is auto-incremented)
</entry>
</row>
<row>
<entry>5</entry>
<entry><literal>SESAM_SEEK_RELATIVE</literal></entry>
<entry>
fetch relative to current scroll position, where
<parameter>offset</parameter> can be a positive or negative
offset value (this also sets the default "offset" value for
subsequent fetches).
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<parameter>offset</parameter> is an optional
parameter which is only evaluated (and required) if
<parameter>whence</parameter> is either
<literal>SESAM_SEEK_RELATIVE</literal> or
<literal>SESAM_SEEK_ABSOLUTE</literal>.
</para>
</refsect1>
</refentry>
<refentry id="function.sesam-seek-row">
<refnamediv>
<refname>sesam_seek_row</refname>
<refpurpose>Set scrollable cursor mode for subsequent fetches</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_seek_row</methodname>
<methodparam><type>string</type><parameter>result_id</parameter></methodparam>
<methodparam><type>int</type><parameter>whence</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>offset</parameter></methodparam>
</methodsynopsis>
<para>
<parameter>result_id</parameter> is a valid result id (select
type queries only, and only if a "scrollable" cursor was
requested when calling <function>sesam_query</function>).
</para>
<para>
<parameter>whence</parameter> sets the global default value for
the scrolling type, it specifies the scroll type to use in
subsequent fetch operations on "scrollable" cursors, which can be
set to the following predefined constants:
<table>
<title>Valid values for <parameter>"whence"</parameter> parameter</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry><literal>SESAM_SEEK_NEXT</literal></entry>
<entry>read sequentially
</entry>
</row>
<row>
<entry>1</entry>
<entry><literal>SESAM_SEEK_PRIOR</literal></entry>
<entry>read sequentially backwards
</entry>
</row>
<row>
<entry>2</entry>
<entry><literal>SESAM_SEEK_FIRST</literal></entry>
<entry>
fetch first row (after fetch, the default is set to
<literal>SESAM_SEEK_NEXT</literal>)
</entry>
</row>
<row>
<entry>3</entry>
<entry><literal>SESAM_SEEK_LAST</literal></entry>
<entry>
fetch last row (after fetch, the default is set to
<literal>SESAM_SEEK_PRIOR</literal>)
</entry>
</row>
<row>
<entry>4</entry>
<entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry>
<entry>
fetch absolute row number given as
<parameter>offset</parameter> (Zero-based. After fetch, the
default is set to <literal>SESAM_SEEK_ABSOLUTE</literal>,
and the offset value is auto-incremented)
</entry>
</row>
<row>
<entry>5</entry>
<entry><literal>SESAM_SEEK_RELATIVE</literal></entry>
<entry>
fetch relative to current scroll position, where
<parameter>offset</parameter> can be a positive or negative
offset value (this also sets the default "offset" value for
subsequent fetches).
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<parameter>offset</parameter> is an optional
parameter which is only evaluated (and required) if
<parameter>whence</parameter> is either
<literal>SESAM_SEEK_RELATIVE</literal> or
<literal>SESAM_SEEK_ABSOLUTE</literal>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

226
reference/sesam/functions/sesam-settransaction.xml
View file

@ -1,124 +1,124 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 -->
<refentry id="function.sesam-settransaction">
<refnamediv>
<refname>sesam_settransaction</refname>
<refpurpose>Set SESAM transaction parameters</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_settransaction</methodname>
<methodparam><type>int</type><parameter>isolation_level</parameter></methodparam>
<methodparam><type>int</type><parameter>read_only</parameter></methodparam>
</methodsynopsis>
<para>
Returns: &true; if the values are valid, and the
<function>settransaction</function> operation was successful,
&false; otherwise.
</para>
<para>
<function>sesam_settransaction</function> overrides the default
values for the "isolation level" and "read-only" transaction
parameters (which are set in the SESAM configuration file), in
order to optimize subsequent queries and guarantee database
consistency. The overridden values are used for the next
transaction only.
</para>
<para>
<function>sesam_settransaction</function> can only be called
before starting a transaction, not after the transaction has been
started already.
</para>
<para>
To simplify the use in PHP scripts, the following constants have
been predefined in PHP (see SESAM handbook for detailed
explanation of the semantics):
<table>
<title>
Valid values for <parameter>"Isolation_Level"</parameter>
parameter
</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry><literal>SESAM_TXISOL_READ_UNCOMMITTED</literal></entry>
<entry>Read Uncommitted</entry>
</row>
<row>
<entry>2</entry>
<entry><literal>SESAM_TXISOL_READ_COMMITTED</literal></entry>
<entry>Read Committed</entry>
</row>
<row>
<entry>3</entry>
<entry><literal>SESAM_TXISOL_REPEATABLE_READ</literal></entry>
<entry>Repeatable Read</entry>
</row>
<row>
<entry>4</entry>
<entry><literal>SESAM_TXISOL_SERIALIZABLE</literal></entry>
<entry>Serializable</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>
Valid values for <parameter>"Read_Only"</parameter> parameter
</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry><literal>SESAM_TXREAD_READWRITE</literal></entry>
<entry>Read/Write</entry>
</row>
<row>
<entry>1</entry>
<entry><literal>SESAM_TXREAD_READONLY</literal></entry>
<entry>Read-Only</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The values set by <function>sesam_settransaction</function> will
override the default setting specified in the <link
linkend="ini.sesam-configfile">SESAM configuration file</link>.
</para>
<para>
<example>
<title>Setting SESAM transaction parameters</title>
<programlisting role="php">
<refentry id="function.sesam-settransaction">
<refnamediv>
<refname>sesam_settransaction</refname>
<refpurpose>Set SESAM transaction parameters</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>sesam_settransaction</methodname>
<methodparam><type>int</type><parameter>isolation_level</parameter></methodparam>
<methodparam><type>int</type><parameter>read_only</parameter></methodparam>
</methodsynopsis>
<para>
Returns: &true; if the values are valid, and the
<function>settransaction</function> operation was successful,
&false; otherwise.
</para>
<para>
<function>sesam_settransaction</function> overrides the default
values for the "isolation level" and "read-only" transaction
parameters (which are set in the SESAM configuration file), in
order to optimize subsequent queries and guarantee database
consistency. The overridden values are used for the next
transaction only.
</para>
<para>
<function>sesam_settransaction</function> can only be called
before starting a transaction, not after the transaction has been
started already.
</para>
<para>
To simplify the use in PHP scripts, the following constants have
been predefined in PHP (see SESAM handbook for detailed
explanation of the semantics):
<table>
<title>
Valid values for <parameter>"Isolation_Level"</parameter>
parameter
</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry><literal>SESAM_TXISOL_READ_UNCOMMITTED</literal></entry>
<entry>Read Uncommitted</entry>
</row>
<row>
<entry>2</entry>
<entry><literal>SESAM_TXISOL_READ_COMMITTED</literal></entry>
<entry>Read Committed</entry>
</row>
<row>
<entry>3</entry>
<entry><literal>SESAM_TXISOL_REPEATABLE_READ</literal></entry>
<entry>Repeatable Read</entry>
</row>
<row>
<entry>4</entry>
<entry><literal>SESAM_TXISOL_SERIALIZABLE</literal></entry>
<entry>Serializable</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>
Valid values for <parameter>"Read_Only"</parameter> parameter
</title>
<tgroup cols="3">
<thead>
<row>
<entry>Value</entry>
<entry>Constant</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry><literal>SESAM_TXREAD_READWRITE</literal></entry>
<entry>Read/Write</entry>
</row>
<row>
<entry>1</entry>
<entry><literal>SESAM_TXREAD_READONLY</literal></entry>
<entry>Read-Only</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
The values set by <function>sesam_settransaction</function> will
override the default setting specified in the <link
linkend="ini.sesam-configfile">SESAM configuration file</link>.
</para>
<para>
<example>
<title>Setting SESAM transaction parameters</title>
<programlisting role="php">
<![CDATA[
<?php
sesam_settransaction (SESAM_TXISOL_REPEATABLE_READ,
SESAM_TXREAD_READONLY);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables: