cvs: phpdoc /en/reference/sesam/functions sesam-affected-rows.xml sesam-commit.xml sesam-connect.xml sesam-diagnostic.xml sesam-disconnect.xml
sesam-errormsg.xml sesam-execimm.xml sesam-fetch-array.xml sesam-fetch-result.xml sesam-fetch-row.xml sesam-field-array.xml sesam-field-name.xml
sesam-free-result.xml sesam-num-fields.xml sesam-query.xml sesam-rollback.xml sesam-seek-row.xml sesam-settransaction.xml

didou Sat Feb 3 22:18:05 2007 UTC Modified files: /phpdoc/en/reference/sesam/functions sesam-affected-rows.xml sesam-commit.xml sesam-connect.xml sesam-diagnostic.xml sesam-disconnect.xml sesam-errormsg.xml sesam-execimm.xml sesam-fetch-array.xml sesam-fetch-result.xml sesam-fetch-row.xml sesam-field-array.xml sesam-field-name.xml sesam-free-result.xml sesam-num-fields.xml sesam-query.xml sesam-rollback.xml sesam-seek-row.xml sesam-settransaction.xml Log: ref.sesam: swtich to new style

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-affected-rows.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-affected-rows.xml diff -u phpdoc/en/reference/sesam/functions/sesam-affected-rows.xml:1.7 phpdoc/en/reference/sesam/functions/sesam-affected-rows.xml:1.8 --- phpdoc/en/reference/sesam/functions/sesam-affected-rows.xml:1.7 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-affected-rows.xml Sat Feb 3 22:18:05 2007 @@ -1,34 +1,56 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.8 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <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>. + Gets the number of rows affected by an immediate query. </para> <para> - Returns the number of rows affected by a query associated with - <parameter>result_id</parameter>. + 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. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <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. + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the number of rows affected by a query associated with + <parameter>result_id</parameter>. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>sesam_affected_rows</function> example</title> @@ -46,11 +68,18 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>sesam_query</function> and - <function>sesam_execimm</function>. + <simplelist> + <member><function>sesam_query</function></member> + <member><function>sesam_execimm</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-commit.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-commit.xml diff -u phpdoc/en/reference/sesam/functions/sesam-commit.xml:1.3 phpdoc/en/reference/sesam/functions/sesam-commit.xml:1.4 --- phpdoc/en/reference/sesam/functions/sesam-commit.xml:1.3 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-commit.xml Sat Feb 3 22:18:05 2007 @@ -1,24 +1,19 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.4 $ --> <refentry id="function.sesam-commit"> <refnamediv> <refname>sesam_commit</refname> <refpurpose>Commit pending updates to the SESAM database</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <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. + Commits any pending updates to the database. </para> <para> Note that there is no "auto-commit" feature as in other @@ -27,10 +22,18 @@ <function>sesam_disconnect</function>) will be discarded by an implied <function>sesam_rollback</function> call. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> + &return.success; </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - See also: <function>sesam_rollback</function>. <example> <title>Committing an update to the SESAM database</title> <programlisting role="php"> @@ -48,6 +51,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>sesam_rollback</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-connect.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-connect.xml diff -u phpdoc/en/reference/sesam/functions/sesam-connect.xml:1.4 phpdoc/en/reference/sesam/functions/sesam-connect.xml:1.5 --- phpdoc/en/reference/sesam/functions/sesam-connect.xml:1.4 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-connect.xml Sat Feb 3 22:18:05 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.5 $ --> <refentry id="function.sesam-connect"> <refnamediv> <refname>sesam_connect</refname> <refpurpose>Open SESAM database connection</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>sesam_connect</methodname> <methodparam><type>string</type><parameter>catalog</parameter></methodparam> @@ -15,38 +15,65 @@ <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> + Establishes a connection to a 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> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The <parameter>"schema"</parameter> references the desired - database schema (see SESAM handbook). + <variablelist> + <varlistentry> + <term><parameter>catalog</parameter></term> + <listitem> + <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> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>schema</parameter></term> + <listitem> + <para> + The <parameter>schema</parameter> references the desired database + schema (see SESAM handbook). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>user</parameter></term> + <listitem> + <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> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <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. + &return.success; </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - See also <function>sesam_disconnect</function>. <example> <title>Connect to a SESAM database</title> <programlisting role="php"> @@ -61,6 +88,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>sesam_disconnect</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-diagnostic.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-diagnostic.xml diff -u phpdoc/en/reference/sesam/functions/sesam-diagnostic.xml:1.8 phpdoc/en/reference/sesam/functions/sesam-diagnostic.xml:1.9 --- phpdoc/en/reference/sesam/functions/sesam-diagnostic.xml:1.8 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-diagnostic.xml Sat Feb 3 22:18:05 2007 @@ -1,18 +1,25 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.9 $ --> <refentry id="function.sesam-diagnostic"> <refnamediv> <refname>sesam_diagnostic</refname> <refpurpose>Return status information for last SESAM call</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>sesam_diagnostic</methodname> <void/> </methodsynopsis> <para> + Returns status information for last SESAM call. + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> Returns an associative array of status and return codes for the last SQL query/statement/command. Elements of the array are: <table> @@ -66,6 +73,10 @@ </tgroup> </table> </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> In the following example, a syntax error (E SEW42AE ILLEGAL CHARACTER) is displayed by including the offending SQL statement @@ -145,11 +156,17 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also: <function>sesam_errormsg</function> for simple access - to the error string only + <simplelist> + <member><function>sesam_errormsg</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-disconnect.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-disconnect.xml diff -u phpdoc/en/reference/sesam/functions/sesam-disconnect.xml:1.5 phpdoc/en/reference/sesam/functions/sesam-disconnect.xml:1.6 --- phpdoc/en/reference/sesam/functions/sesam-disconnect.xml:1.5 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-disconnect.xml Sat Feb 3 22:18:05 2007 @@ -1,24 +1,20 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.6 $ --> <refentry id="function.sesam-disconnect"> <refnamediv> <refname>sesam_disconnect</refname> <refpurpose>Detach from SESAM connection</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <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). + 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 @@ -34,6 +30,17 @@ function called after <function>sesam_disconnect</function> will fail. </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + Always returns &true;. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Closing a SESAM connection</title> @@ -49,10 +56,17 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>sesam_connect</function>. + <simplelist> + <member><function>sesam_connect</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-errormsg.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-errormsg.xml diff -u phpdoc/en/reference/sesam/functions/sesam-errormsg.xml:1.5 phpdoc/en/reference/sesam/functions/sesam-errormsg.xml:1.6 --- phpdoc/en/reference/sesam/functions/sesam-errormsg.xml:1.5 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-errormsg.xml Sat Feb 3 22:18:05 2007 @@ -1,21 +1,32 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.6 $ --> <refentry id="function.sesam-errormsg"> <refnamediv> <refname>sesam_errormsg</refname> <refpurpose>Returns error message of last SESAM call</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>sesam_errormsg</methodname> <void/> </methodsynopsis> <para> - Returns the SESAM error message associated with the most recent - SESAM error. + Gets the SESAM error message associated with the most recent SESAM error. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the SESAM error message associated with the most recent SESAM + error. An empty string means no errors. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>sesam_errormsg</function> example</title> @@ -30,11 +41,17 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>sesam_diagnostic</function> for the full set - of SESAM SQL status information. + <simplelist> + <member><function>sesam_diagnostic</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-execimm.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-execimm.xml diff -u phpdoc/en/reference/sesam/functions/sesam-execimm.xml:1.5 phpdoc/en/reference/sesam/functions/sesam-execimm.xml:1.6 --- phpdoc/en/reference/sesam/functions/sesam-execimm.xml:1.5 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-execimm.xml Sat Feb 3 22:18:05 2007 @@ -1,46 +1,69 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.6 $ --> <refentry id="function.sesam-execimm"> <refnamediv> <refname>sesam_execimm</refname> <refpurpose>Execute an "immediate" SQL-statement</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <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. + Executes an "immediate" statement. </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 + 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 + 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> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <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. + <variablelist> + <varlistentry> + <term><parameter>query</parameter></term> + <listitem> + <para> + 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>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - <informalexample> + Returns a SESAM result identifier on success, or &false; on error. + </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> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>sesam_execimm</function> Example</title> <programlisting role="php"> <![CDATA[ <?php @@ -53,13 +76,20 @@ ?> ]]> </programlisting> - </informalexample> + </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>sesam_query</function> and - <function>sesam_affected_rows</function>. + <simplelist> + <member><function>sesam_query</function></member> + <member><function>sesam_affected_rows</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-fetch-array.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-fetch-array.xml diff -u phpdoc/en/reference/sesam/functions/sesam-fetch-array.xml:1.8 phpdoc/en/reference/sesam/functions/sesam-fetch-array.xml:1.9 --- phpdoc/en/reference/sesam/functions/sesam-fetch-array.xml:1.8 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-fetch-array.xml Sat Feb 3 22:18:05 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.9 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>sesam_fetch_array</methodname> <methodparam><type>string</type><parameter>result_id</parameter></methodparam> @@ -15,27 +15,12 @@ <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 @@ -81,12 +66,137 @@ <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 + scroll attributes) row in the result set, or &false; if there are no more rows. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>whence</parameter></term> + <listitem> + <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><constant>SESAM_SEEK_NEXT</constant></entry> + <entry> + read sequentially (after fetch, the internal default is set + to <constant>SESAM_SEEK_NEXT</constant>) + </entry> + </row> + <row> + <entry>1</entry> + <entry><constant>SESAM_SEEK_PRIOR</constant></entry> + <entry> + read sequentially backwards (after fetch, the internal + default is set to <constant>SESAM_SEEK_PRIOR</constant>) + </entry> + </row> + <row> + <entry>2</entry> + <entry><constant>SESAM_SEEK_FIRST</constant></entry> + <entry> + rewind to first row (after fetch, the default is set to + <constant>SESAM_SEEK_NEXT</constant>) + </entry> + </row> + <row> + <entry>3</entry> + <entry><constant>SESAM_SEEK_LAST</constant></entry> + <entry> + seek to last row (after fetch, the default is set to + <constant>SESAM_SEEK_PRIOR</constant>) + </entry> + </row> + <row> + <entry>4</entry> + <entry><constant>SESAM_SEEK_ABSOLUTE</constant></entry> + <entry> + seek to absolute row number given as + <parameter>offset</parameter> (Zero-based. After fetch, the + internal default is set to + <constant>SESAM_SEEK_ABSOLUTE</constant>, and the internal + offset value is auto-incremented) + </entry> + </row> + <row> + <entry>5</entry> + <entry><constant>SESAM_SEEK_RELATIVE</constant></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: <constant>SESAM_SEEK_NEXT</constant>, and settable by + <function>sesam_seek_row</function>) are used. If + <parameter>whence</parameter> is supplied, its value replaces the + global default. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + Only evaluated (and required) if <parameter>whence</parameter> is + either <constant>SESAM_SEEK_RELATIVE</constant> or + <constant>SESAM_SEEK_ABSOLUTE</constant>. This parameter is only + valid for "scrollable" cursors. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an array that corresponds to the fetched row, or &false; if there are no more rows. </para> - <example> - <title>SESAM fetch array</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title>SESAM fetch array</title> + <programlisting role="php"> <![CDATA[ <?php $result = sesam_query("SELECT * FROM phone\n" . @@ -108,13 +218,20 @@ sesam_free_result($result); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also: <function>sesam_fetch_row</function> which returns an - indexed array. + <simplelist> + <member><function>sesam_fetch_row</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-fetch-result.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-fetch-result.xml diff -u phpdoc/en/reference/sesam/functions/sesam-fetch-result.xml:1.5 phpdoc/en/reference/sesam/functions/sesam-fetch-result.xml:1.6 --- phpdoc/en/reference/sesam/functions/sesam-fetch-result.xml:1.5 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-fetch-result.xml Sat Feb 3 22:18:05 2007 @@ -1,19 +1,54 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.6 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <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> + Fetches a result, optionally limited to <parameter>max_rows</parameter>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>max_rows</parameter></term> + <listitem> + <para> + 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> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <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. @@ -76,20 +111,20 @@ </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> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <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>. + <simplelist> + <member><function>sesam_fetch_array</function></member> + <member><function>sesam_fetch_row</function></member> + <member><function>sesam_query</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-fetch-row.xml?r1=1.9&r2=1.10&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-fetch-row.xml diff -u phpdoc/en/reference/sesam/functions/sesam-fetch-row.xml:1.9 phpdoc/en/reference/sesam/functions/sesam-fetch-row.xml:1.10 --- phpdoc/en/reference/sesam/functions/sesam-fetch-row.xml:1.9 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-fetch-row.xml Sat Feb 3 22:18:05 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.9 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.10 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>sesam_fetch_row</methodname> <methodparam><type>string</type><parameter>result_id</parameter></methodparam> @@ -15,128 +15,152 @@ <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. + 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> + 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> + 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> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <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 + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>whence</parameter></term> + <listitem> + <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><constant>SESAM_SEEK_NEXT</constant></entry> + <entry> + read sequentially (after fetch, the internal default is set + to <constant>SESAM_SEEK_NEXT</constant>) + </entry> + </row> + <row> + <entry>1</entry> + <entry><constant>SESAM_SEEK_PRIOR</constant></entry> + <entry> + read sequentially backwards (after fetch, the internal + default is set to <constant>SESAM_SEEK_PRIOR</constant>) + </entry> + </row> + <row> + <entry>2</entry> + <entry><constant>SESAM_SEEK_FIRST</constant></entry> + <entry> + rewind to first row (after fetch, the default is set to + <constant>SESAM_SEEK_NEXT</constant>) + </entry> + </row> + <row> + <entry>3</entry> + <entry><constant>SESAM_SEEK_LAST</constant></entry> + <entry> + seek to last row (after fetch, the default is set to + <constant>SESAM_SEEK_PRIOR</constant>) + </entry> + </row> + <row> + <entry>4</entry> + <entry><constant>SESAM_SEEK_ABSOLUTE</constant></entry> + <entry> + seek to absolute row number given as + <parameter>offset</parameter> (Zero-based. After fetch, the + internal default is set to + <constant>SESAM_SEEK_ABSOLUTE</constant>, and the internal + offset value is auto-incremented) + </entry> + </row> + <row> + <entry>5</entry> + <entry><constant>SESAM_SEEK_RELATIVE</constant></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: <constant>SESAM_SEEK_NEXT</constant>, and settable by + <function>sesam_seek_row</function>) are used. If + <parameter>whence</parameter> is supplied, its value replaces the + global default. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + Only evaluated (and required) if <parameter>whence</parameter> is + either <constant>SESAM_SEEK_RELATIVE</constant> or + <constant>SESAM_SEEK_ABSOLUTE</constant>. This parameter is only + valid for "scrollable" cursors. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an array that corresponds to the fetched row, or &false; if there are no more rows. </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <example> <title>SESAM fetch rows</title> <programlisting role="php"> @@ -166,12 +190,18 @@ ]]> </programlisting> </example> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <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. + <simplelist> + <member><function>sesam_fetch_array</function></member> + <member><function>sesam_fetch_result</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-field-array.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-field-array.xml diff -u phpdoc/en/reference/sesam/functions/sesam-field-array.xml:1.7 phpdoc/en/reference/sesam/functions/sesam-field-array.xml:1.8 --- phpdoc/en/reference/sesam/functions/sesam-field-array.xml:1.7 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-field-array.xml Sat Feb 3 22:18:05 2007 @@ -1,27 +1,42 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.8 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <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>. + 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> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <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>. + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> <table> <title> @@ -183,11 +198,17 @@ </tgroup> </table> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>sesam_query</function> for an example - of the <function>sesam_field_array</function> use. + <simplelist> + <member><function>sesam_query</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-field-name.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-field-name.xml diff -u phpdoc/en/reference/sesam/functions/sesam-field-name.xml:1.3 phpdoc/en/reference/sesam/functions/sesam-field-name.xml:1.4 --- phpdoc/en/reference/sesam/functions/sesam-field-name.xml:1.3 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-field-name.xml Sat Feb 3 22:18:05 2007 @@ -1,37 +1,69 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.4 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <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. + Gets the field name. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>index</parameter></term> + <listitem> + <para> + The column index is zero-based, not one-based as in SESAM. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the name of a field 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> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <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". + <simplelist> + <member><function>sesam_field_array</function>. It provides an + easier interface to access the column names and types, and allows + for detection of "multiple fields".</member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-free-result.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-free-result.xml diff -u phpdoc/en/reference/sesam/functions/sesam-free-result.xml:1.3 phpdoc/en/reference/sesam/functions/sesam-free-result.xml:1.4 --- phpdoc/en/reference/sesam/functions/sesam-free-result.xml:1.3 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-free-result.xml Sat Feb 3 22:18:05 2007 @@ -1,21 +1,42 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.4 $ --> <refentry id="function.sesam-free-result"> <refnamediv> <refname>sesam_free_result</refname> <refpurpose>Releases resources for the query</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> - <type>int</type><methodname>sesam_free_result</methodname> + <type>bool</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. + Releases resources for the query. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-num-fields.xml?r1=1.3&r2=1.4&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-num-fields.xml diff -u phpdoc/en/reference/sesam/functions/sesam-num-fields.xml:1.3 phpdoc/en/reference/sesam/functions/sesam-num-fields.xml:1.4 --- phpdoc/en/reference/sesam/functions/sesam-num-fields.xml:1.3 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-num-fields.xml Sat Feb 3 22:18:05 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.4 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>sesam_num_fields</methodname> <methodparam><type>string</type><parameter>result_id</parameter></methodparam> @@ -15,22 +15,51 @@ <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. + result. </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> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <para> + A valid result id returned by <function>sesam_query</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <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. + 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> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>sesam_query</function></member> + <member><function>sesam_field_array</function> for a way to distinguish + between "multiple field" columns and regular columns.</member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-query.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-query.xml diff -u phpdoc/en/reference/sesam/functions/sesam-query.xml:1.7 phpdoc/en/reference/sesam/functions/sesam-query.xml:1.8 --- phpdoc/en/reference/sesam/functions/sesam-query.xml:1.7 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-query.xml Sat Feb 3 22:18:05 2007 @@ -1,39 +1,26 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.8 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <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. + result (zero columns, indicating end-of-result). </para> <para> When using "scrollable" cursors, the cursor can be freely @@ -49,9 +36,47 @@ for retrieval by the <function>sesam_affected_rows</function> function. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>query</parameter></term> + <listitem> + <para> + The query statement. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>scrollable</parameter></term> + <listitem> + <para> + 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> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a SESAM "result identifier" on success, or &false; on error. This + result id is used by the other functions. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <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 @@ -109,6 +134,17 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>sesam_fetch_row</function></member> + <member><function>sesam_fetch_result</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-rollback.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-rollback.xml diff -u phpdoc/en/reference/sesam/functions/sesam-rollback.xml:1.4 phpdoc/en/reference/sesam/functions/sesam-rollback.xml:1.5 --- phpdoc/en/reference/sesam/functions/sesam-rollback.xml:1.4 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-rollback.xml Sat Feb 3 22:18:05 2007 @@ -1,22 +1,18 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.5 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <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. @@ -27,8 +23,18 @@ <function>sesam_rollback</function> is executed, discarding any pending changes to the database. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - See also: <function>sesam_commit</function>. <example> <title>Discarding an update to the SESAM database</title> <programlisting role="php"> @@ -48,6 +54,16 @@ </example> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>sesam_commit</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-seek-row.xml?r1=1.4&r2=1.5&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-seek-row.xml diff -u phpdoc/en/reference/sesam/functions/sesam-seek-row.xml:1.4 phpdoc/en/reference/sesam/functions/sesam-seek-row.xml:1.5 --- phpdoc/en/reference/sesam/functions/sesam-seek-row.xml:1.4 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-seek-row.xml Sat Feb 3 22:18:05 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.5 $ --> <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> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>sesam_seek_row</methodname> <methodparam><type>string</type><parameter>result_id</parameter></methodparam> @@ -15,84 +15,116 @@ <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>). + Sets the scrollable cursor mode for subsequent fetches. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <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> + <variablelist> + <varlistentry> + <term><parameter>result_id</parameter></term> + <listitem> + <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> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>whence</parameter></term> + <listitem> + <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></title> + <tgroup cols="3"> + <thead> + <row> + <entry>Value</entry> + <entry>Constant</entry> + <entry>Meaning</entry> + </row> + </thead> + <tbody> + <row> + <entry>0</entry> + <entry><constant>SESAM_SEEK_NEXT</constant></entry> + <entry>read sequentially + </entry> + </row> + <row> + <entry>1</entry> + <entry><constant>SESAM_SEEK_PRIOR</constant></entry> + <entry>read sequentially backwards + </entry> + </row> + <row> + <entry>2</entry> + <entry><constant>SESAM_SEEK_FIRST</constant></entry> + <entry> + fetch first row (after fetch, the default is set to + <constant>SESAM_SEEK_NEXT</constant>) + </entry> + </row> + <row> + <entry>3</entry> + <entry><constant>SESAM_SEEK_LAST</constant></entry> + <entry> + fetch last row (after fetch, the default is set to + <constant>SESAM_SEEK_PRIOR</constant>) + </entry> + </row> + <row> + <entry>4</entry> + <entry><constant>SESAM_SEEK_ABSOLUTE</constant></entry> + <entry> + fetch absolute row number given as + <parameter>offset</parameter> (Zero-based. After fetch, the + default is set to <constant>SESAM_SEEK_ABSOLUTE</constant>, + and the offset value is auto-incremented) + </entry> + </row> + <row> + <entry>5</entry> + <entry><constant>SESAM_SEEK_RELATIVE</constant></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> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>offset</parameter></term> + <listitem> + <para> + An optional parameter which is only evaluated (and required) if + <parameter>whence</parameter> is either + <constant>SESAM_SEEK_RELATIVE</constant> or + <constant>SESAM_SEEK_ABSOLUTE</constant>. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <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>. + &return.success; </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/sesam/functions/sesam-settransaction.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/sesam/functions/sesam-settransaction.xml diff -u phpdoc/en/reference/sesam/functions/sesam-settransaction.xml:1.5 phpdoc/en/reference/sesam/functions/sesam-settransaction.xml:1.6 --- phpdoc/en/reference/sesam/functions/sesam-settransaction.xml:1.5 Sat Feb 3 22:17:50 2007 +++ phpdoc/en/reference/sesam/functions/sesam-settransaction.xml Sat Feb 3 22:18:05 2007 @@ -1,109 +1,133 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> -<!-- splitted from ./en/functions/sesam.xml, last change in rev 1.1 --> +<!-- $Revision: 1.6 $ --> <refentry id="function.sesam-settransaction"> <refnamediv> <refname>sesam_settransaction</refname> <refpurpose>Set SESAM transaction parameters</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <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> + Overrides the default values for the <literal>isolation level</literal> + and <literal>read-only</literal> 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. See the SESAM handbook for detailed explanation of + the semantics. </para> <para> - The values set by <function>sesam_settransaction</function> will - override the default setting specified in the <link + This function can only be called before starting a transaction, not after + the transaction has been started already. + </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> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>isolation_level</parameter></term> + <listitem> + <para> + <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> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>read_only</parameter></term> + <listitem> + <para> + <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> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns &true; if the values are valid, and the + <literal>settransaction</literal> operation was successful, &false; + otherwise. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Setting SESAM transaction parameters</title> @@ -118,6 +142,7 @@ </example> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file