cvs: phpdoc /es/functions sesam.xml /hk/functions sesam.xml /it/functions sesam.xml /kr/functions sesam.xml

From: Date: Tue, 24 Jul 2001 14:35:43 +0000
Subject: cvs: phpdoc /es/functions sesam.xml /hk/functions sesam.xml /it/functions sesam.xml /kr/functions sesam.xml
Groups: php.doc 
Request: Send a blank email to phpdoc+get-969336481@lists.php.net to get a copy of this message
martin Tue Jul 24 10:35:43 2001 EDT Modified files: /phpdoc/es/functions sesam.xml /phpdoc/hk/functions sesam.xml /phpdoc/it/functions sesam.xml /phpdoc/kr/functions sesam.xml Log: Untranslated; therefore resync with .en version

Index: phpdoc/es/functions/sesam.xml diff -u phpdoc/es/functions/sesam.xml:1.2 phpdoc/es/functions/sesam.xml:1.3 --- phpdoc/es/functions/sesam.xml:1.2 Sat Jul 7 18:20:17 2001 +++ phpdoc/es/functions/sesam.xml Tue Jul 24 10:35:40 2001 @@ -5,19 +5,30 @@ <partintro> <para> SESAM/SQL-Server is a mainframe database system, developed by - Fujitsu Siemens Computers, Germany. It runs on high-end - mainframe servers using the operating system BS2000/OSD. + Fujitsu Siemens Computers, Germany. It runs on high-end mainframe + servers using the operating system BS2000/OSD. </para> <para> - In numerous productive BS2000 installations, SESAM/SQL-Server - has proven ... + In numerous productive BS2000 installations, SESAM/SQL-Server has + proven ... <itemizedlist> - <listitem><simpara>the ease of use of Java-, Web- and client/server - connectivity,</simpara></listitem> - <listitem><simpara>the capability to work with an availability of more - than 99.99%,</simpara></listitem> - <listitem><simpara>the ability to manage tens and even hundreds of - thousands of users.</simpara></listitem> + <listitem> + <simpara> + the ease of use of Java-, Web- and client/server connectivity, + </simpara> + </listitem> + <listitem> + <simpara> + the capability to work with an availability of more than + 99.99%, + </simpara> + </listitem> + <listitem> + <simpara> + the ability to manage tens and even hundreds of thousands of + users. + </simpara> + </listitem> </itemizedlist> </para> <para> @@ -27,81 +38,94 @@ <note> <title>Configuration notes</title> <para> - There is no standalone support for the PHP SESAM interface, - it works only as an integrated Apache module. In the Apache PHP - module, this <link linkend="ini.sect.sesam">SESAM interface is + There is no standalone support for the PHP SESAM interface, it + works only as an integrated Apache module. In the Apache PHP + module, this <link linkend="ini.sect.sesam">SESAM interface is configured</link> using Apache directives. <table> <title>SESAM Configuration directives</title> <tgroup cols="2"> <thead> <row> - <entry>Directive</entry> - <entry>Meaning</entry> + <entry>Directive</entry> + <entry>Meaning</entry> </row> </thead> <tbody> <row> - <entry><literal>php3_sesam_oml</literal></entry> - <entry>Name of BS2000 PLAM library containing the - loadable SESAM driver modules. - Required for using SESAM functions. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_oml $.SYSLNK.SESAM-SQL.030</programlisting> - </informalexample> - </para> - </entry> - </row> - <row> - <entry><literal>php3_sesam_configfile</literal></entry> - <entry>Name of SESAM application configuration file. - Required for using SESAM functions. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_configfile $SESAM.SESAM.CONF.AW</programlisting></informalexample> - It will usually contain a configuration like (see SESAM - reference manual): - <informalexample> - <programlisting role="bs2000"> + <entry><literal>php3_sesam_oml</literal></entry> + <entry> + Name of BS2000 PLAM library containing the loadable SESAM + driver modules. Required for using SESAM functions. + <para> + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_oml $.SYSLNK.SESAM-SQL.030 + </programlisting> + </informalexample> + </para> + </entry> + </row> + <row> + <entry><literal>php3_sesam_configfile</literal></entry> + <entry>Name of SESAM application configuration file. + Required for using SESAM functions. + <para> + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_configfile $SESAM.SESAM.CONF.AW + </programlisting> + </informalexample> + It will usually contain a configuration like (see SESAM reference + manual): + <informalexample> + <programlisting role="bs2000"> CNF=B NAM=K -NOTYPE</programlisting> - </informalexample> - </para> - </entry> - </row> - <row> - <entry><literal>php3_sesam_messagecatalog</literal></entry> - <entry>Name of SESAM message catalog file. - In most cases, this directive is not neccessary. Only if the - SESAM message file is not installed in the system's BS2000 - message file table, it can be set with this directive. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030</programlisting> - </informalexample> - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> +NOTYPE + </programlisting> + </informalexample> </para> + </entry> + </row> + <row> + <entry><literal>php3_sesam_messagecatalog</literal></entry> + <entry> + Name of SESAM message catalog file. In most cases, this + directive is not neccessary. Only if the SESAM message file is + not installed in the system's BS2000 message file table, it can + be set with this directive. <para> - In addition to the configuration of the PHP/SESAM interface, - you have to configure the SESAM-Database server itself on your + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030 + </programlisting> + </informalexample> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + In addition to the configuration of the PHP/SESAM interface, you + have to configure the SESAM-Database server itself on your mainframe as usual. That means: <itemizedlist> - <listitem><simpara>starting the SESAM database handler (DBH), and</simpara></listitem> - <listitem><simpara>connecting the databases with the SESAM database - handler</simpara></listitem> + <listitem> + <simpara> + starting the SESAM database handler (DBH), and + </simpara> + </listitem> + <listitem> + <simpara> + connecting the databases with the SESAM database handler + </simpara> + </listitem> </itemizedlist> </para> <para> @@ -117,28 +141,28 @@ </para> <para> The communication between PHP (running in the POSIX subsystem) - and the database handler (running outside the POSIX subsystem) - is realized by a special driver module called SQLSCI and SESAM - connection modules using common memory. - Because of the common memory access, and because PHP is a - static part of the web server, database accesses are very fast, - as they do not require remote accesses via ODBC, JDBC or UTM. + and the database handler (running outside the POSIX subsystem) is + realized by a special driver module called SQLSCI and SESAM + connection modules using common memory. Because of the common + memory access, and because PHP is a static part of the web + server, database accesses are very fast, as they do not require + remote accesses via ODBC, JDBC or UTM. </para> <para> Only a small stub loader (SESMOD) is linked with PHP, and the SESAM connection modules are pulled in from SESAM's OML PLAM library. In the <link - linkend="ini.sect.sesam">configuration</link>, you must tell - PHP the name of this PLAM library, and the file link to use for - the SESAM configuration file (As of SESAM V3.0, SQLSCI is - available in the SESAM Tool Library, which is part of the - standard distribution). + linkend="ini.sect.sesam">configuration</link>, you must tell PHP + the name of this PLAM library, and the file link to use for the + SESAM configuration file (As of SESAM V3.0, SQLSCI is available + in the SESAM Tool Library, which is part of the standard + distribution). </para> <para> Because the SQL command quoting for single quotes uses duplicated single quotes (as opposed to a single quote preceded by a - backslash, used in some other databases), it is advisable to - set the PHP configuration directives <link + backslash, used in some other databases), it is advisable to set + the PHP configuration directives <link linkend="ini.magic-quotes-gpc"><literal>php3_magic_quotes_gpc</literal></link> and <link linkend="ini.magic-quotes-sybase"><literal>php3_magic_quotes_sybase</literal></link> @@ -149,88 +173,91 @@ <note> <title>Runtime considerations</title> <para> - Because of limitations of the BS2000 process model, the driver can - be loaded only after the Apache server has forked off its server child - processes. This will slightly slow down the initial SESAM request - of each child, but subsequent accesses will respond at full speed. + Because of limitations of the BS2000 process model, the driver + can be loaded only after the Apache server has forked off its + server child processes. This will slightly slow down the initial + SESAM request of each child, but subsequent accesses will respond + at full speed. </para> <para> When explicitly defining a Message Catalog for SESAM, that catalog will be loaded each time the driver is loaded (i.e., at - the initial SESAM request). The BS2000 operating system prints - a message after successful load of the message catalog, which - will be sent to Apache's error_log file. BS2000 currently does - not allow suppression of this message, it will slowly fill up - the log. + the initial SESAM request). The BS2000 operating system prints a + message after successful load of the message catalog, which will + be sent to Apache's error_log file. BS2000 currently does not + allow suppression of this message, it will slowly fill up the + log. </para> <para> - Make sure that the SESAM OML PLAM library and SESAM - configuration file are readable by the user id running the web server. - Otherwise, the server will be unable to load the driver, and - will not allow to call any SESAM functions. Also, access to - the database must be granted to the user id under which the - Apache server is running. Otherwise, connections to the - SESAM database handler will fail. + Make sure that the SESAM OML PLAM library and SESAM configuration + file are readable by the user id running the web server. + Otherwise, the server will be unable to load the driver, and will + not allow to call any SESAM functions. Also, access to the + database must be granted to the user id under which the Apache + server is running. Otherwise, connections to the SESAM database + handler will fail. </para> </note> <note> <title>Cursor Types</title> <para> The result cursors which are allocated for SQL "select type" - queries can be either "sequential" or "scrollable". Because - of the larger memory overhead needed by "scrollable" cursors, - the default is "sequential". + queries can be either "sequential" or "scrollable". Because of + the larger memory overhead needed by "scrollable" cursors, the + default is "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>. When fetching a row - using a "scrollable" cursor, the following post-processing is - done for the global default values for the scrolling type - and scrolling offset: + 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>. When fetching a + row using a "scrollable" cursor, the following post-processing is + done for the global default values for the scrolling type and + scrolling offset: <table> <title>Scrolled Cursor Post-Processing</title> <tgroup cols="2"> <thead> <row> - <entry>Scroll Type</entry> - <entry>Action</entry> + <entry>Scroll Type</entry> + <entry>Action</entry> </row> </thead> <tbody> <row> - <entry><literal>SESAM_SEEK_NEXT</literal></entry> - <entry>none</entry> + <entry><literal>SESAM_SEEK_NEXT</literal></entry> + <entry>none</entry> </row> <row> - <entry><literal>SESAM_SEEK_PRIOR</literal></entry> - <entry>none</entry> + <entry><literal>SESAM_SEEK_PRIOR</literal></entry> + <entry>none</entry> </row> <row> - <entry><literal>SESAM_SEEK_FIRST</literal></entry> - <entry>set scroll type to - <literal>SESAM_SEEK_NEXT</literal></entry> + <entry><literal>SESAM_SEEK_FIRST</literal></entry> + <entry> + set scroll type to <literal>SESAM_SEEK_NEXT</literal> + </entry> </row> <row> - <entry><literal>SESAM_SEEK_LAST</literal></entry> - <entry>set scroll type to - <literal>SESAM_SEEK_PRIOR</literal></entry> + <entry><literal>SESAM_SEEK_LAST</literal></entry> + <entry> + set scroll type to <literal>SESAM_SEEK_PRIOR</literal> + </entry> </row> <row> - <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry> - <entry>Auto-Increment internal offset value</entry> + <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry> + <entry>Auto-Increment internal offset value</entry> </row> <row> - <entry><literal>SESAM_SEEK_RELATIVE</literal></entry> - <entry>none. (maintain global default - <parameter>offset</parameter> value, which allows - for, e.g., fetching each 10th row backwards) - </entry> + <entry><literal>SESAM_SEEK_RELATIVE</literal></entry> + <entry>none. (maintain global default + <parameter> + offset</parameter> value, which allows for, e.g., fetching + each 10th row backwards) + </entry> </row> </tbody> </tgroup> @@ -244,29 +271,29 @@ <para> Because in the PHP world it is natural to start indexes at zero (rather than 1), some adaptions have been made to the SESAM - interface: whenever an indexed array is starting with index 1 - in the native SESAM interface, the PHP interface uses - index 0 as a starting point. E.g., when retrieving columns with + interface: whenever an indexed array is starting with index 1 in + the native SESAM interface, the PHP interface uses index 0 as a + starting point. E.g., when retrieving columns with <function>sesam_fetch_row</function>, the first column has the index 0, and the subsequent columns have indexes up to (but not - including) the column count ($array["count"]). - When porting SESAM applications from other high level languages - to PHP, be aware of this changed interface. Where appropriate, - the description of the respective php sesam functions include a - note that the index is zero based. + including) the column count ($array["count"]). When porting + SESAM applications from other high level languages to PHP, be + aware of this changed interface. Where appropriate, the + description of the respective php sesam functions include a note + that the index is zero based. </para> </note> <note> <title>Security concerns</title> <para> - When allowing access to the SESAM databases, the web server - user should only have as little privileges as possible. For most + When allowing access to the SESAM databases, the web server user + should only have as little privileges as possible. For most databases, only read access privilege should be granted. - Depending on your usage scenario, add more access rights as - you see fit. Never allow full control to any database for - any user from the 'net! Restrict access to php scripts - which must administer the database by using password control - and/or SSL security. + Depending on your usage scenario, add more access rights as you + see fit. Never allow full control to any database for any user + from the 'net! Restrict access to php scripts which must + administer the database by using password control and/or SSL + security. </para> </note> <note> @@ -279,21 +306,26 @@ <itemizedlist> <listitem> <simpara>Vendor specific data types</simpara> - <simpara>Some vendor specific data types may have to be - replaced by standard SQL data types - (e.g., <literal>TEXT</literal> could be replaced by - <literal>VARCHAR(max. size)</literal>). - </simpara> + <simpara> + Some vendor specific data types may have to be replaced by + standard SQL data types (e.g., <literal>TEXT</literal> could + be replaced by <literal>VARCHAR(max. size)</literal>). + </simpara> </listitem> <listitem> <simpara>Keywords as SQL identifiers</simpara> - <simpara>In SESAM (as in standard SQL), such identifiers must - be enclosed in double quotes (or renamed).</simpara> + <simpara> + In SESAM (as in standard SQL), such identifiers must be + enclosed in double quotes (or renamed). + </simpara> </listitem> <listitem> - <simpara>Display length in data types</simpara> - <simpara>SESAM data types have a precision, not a display - length. Instead of <literal>int(4)</literal> (intended use: + <simpara> + Display length in data types + </simpara> + <simpara> + SESAM data types have a precision, not a display + length. Instead of <literal>int(4)</literal> (intended use: integers up to '9999'), SESAM requires simply <literal>int</literal> for an implied size of 31 bits. Also, the only datetime data types available in SESAM are: @@ -302,50 +334,60 @@ </simpara> </listitem> <listitem> - <simpara>SQL types with vendor-specific - <literal>unsigned</literal>, <literal>zerofill</literal>, or - <literal>auto_increment</literal> attributes</simpara> - <simpara><literal>Unsigned</literal> and<literal> - zerofill</literal> are not supported. - <literal>Auto_increment</literal> is automatic (use <literal>"INSERT ... - VALUES(*, ...)"</literal> instead of <literal>"... VALUES(0, - ...)"</literal> to take advantage of SESAM-implied - auto-increment. </simpara> - </listitem> - <listitem> - <simpara><command>int ... DEFAULT '0000'</command></simpara> - <simpara>Numeric variables must not be initialized with - string constants. Use <command>DEFAULT 0</command> - instead. To initialize variables of the datetime - SQL data types, the initialization string must be - prefixed with the respective type keyword, as in: - <literal> CREATE TABLE exmpl ( - xtime timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT &null; - ); </literal> + <simpara> + SQL types with vendor-specific <literal>unsigned</literal>, + <literal>zerofill</literal>, or + <literal>auto_increment</literal> attributes + </simpara> + <simpara> + <literal>Unsigned</literal> and<literal> zerofill</literal> + are not supported. <literal>Auto_increment</literal> is + automatic (use <literal>"INSERT ... VALUES(*, ...)"</literal> + instead of <literal>"... VALUES(0, ...)"</literal> to take + advantage of SESAM-implied auto-increment. </simpara> </listitem> <listitem> - <simpara><command>$count = xxxx_num_rows();</command></simpara> - <simpara>Some databases promise to guess/estimate the - number of the rows in a query result, even though - the returned value is grossly incorrect. SESAM - does not know the number of rows in a query result - before actually fetching them. If you REALLY need - the count, try <command>SELECT COUNT(...) WHERE - ...</command>, it will tell you the number of hits. - A second query will (hopefully) return the results. + <simpara> + <command>int ... DEFAULT '0000'</command> + </simpara> + <simpara> + Numeric variables must not be initialized with string + constants. Use <command>DEFAULT 0</command> instead. To + initialize variables of the datetime SQL data types, the + initialization string must be prefixed with the respective + type keyword, as in: <literal> CREATE TABLE exmpl ( xtime + timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT + &null; ); </literal> </simpara> </listitem> <listitem> - <simpara><command>DROP TABLE thename;</command></simpara> - <simpara>In SESAM, in the <command>DROP TABLE</command> - command, the table name must be either followed by - the keyword <literal>RESTRICT</literal> or - <literal>CASCADE</literal>. When specifying - <literal>RESTRICT</literal>, an error is returned if - there are dependent objects (e.g., VIEWs), while with - <literal>CASCADE</literal>, dependent objects will be - deleted along with the specified table. + <simpara> + <command>$count = xxxx_num_rows();</command> + </simpara> + <simpara> + Some databases promise to guess/estimate the number of the + rows in a query result, even though the returned value is + grossly incorrect. SESAM does not know the number of rows in + a query result before actually fetching them. If you REALLY + need the count, try <command>SELECT COUNT(...) WHERE + ...</command>, it will tell you the number of hits. A second + query will (hopefully) return the results. + </simpara> + </listitem> + <listitem> + <simpara> + <command>DROP TABLE thename;</command> + </simpara> + <simpara> + In SESAM, in the <command>DROP TABLE</command> command, the + table name must be either followed by the keyword + <literal>RESTRICT</literal> or + <literal>CASCADE</literal>. When specifying + <literal>RESTRICT</literal>, an error is returned if there are + dependent objects (e.g., VIEWs), while with + <literal>CASCADE</literal>, dependent objects will be deleted + along with the specified table. </simpara> </listitem> </itemizedlist> @@ -356,8 +398,8 @@ Notes on the use of various SQL types </title> <para> - SESAM does not currently support the BLOB type. A future - version of SESAM will have support for BLOB. + SESAM does not currently support the BLOB type. A future version + of SESAM will have support for BLOB. </para> <para> At the PHP interface, the following type conversions are @@ -367,38 +409,37 @@ <tgroup cols="2"> <thead> <row> - <entry>SQL Type</entry> - <entry>PHP Type</entry> + <entry>SQL Type</entry> + <entry>PHP Type</entry> </row> </thead> <tbody> <row> - <entry>SMALLINT, INTEGER</entry> - <entry>"integer"</entry> + <entry>SMALLINT, INTEGER</entry> + <entry>"integer"</entry> </row> <row> - <entry>NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE</entry> - <entry>"double"</entry> + <entry>NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE</entry> + <entry>"double"</entry> </row> <row> - <entry>DATE, TIME, TIMESTAMP</entry> - <entry>"string"</entry> + <entry>DATE, TIME, TIMESTAMP</entry> + <entry>"string"</entry> </row> <row> - <entry>VARCHAR, CHARACTER</entry> - <entry>"string"</entry> + <entry>VARCHAR, CHARACTER</entry> + <entry>"string"</entry> </row> </tbody> </tgroup> </table> When retrieving a complete row, the result is returned as an - array. Empty fields are not filled in, so you will have to - check for the existence of the individual fields yourself - (use <function>isset</function> or - <function>empty</function> to test for empty fields). - That allows more user control over the appearance of empty - fields (than in the case of an empty string as the - representation of an empty field). + array. Empty fields are not filled in, so you will have to check + for the existence of the individual fields yourself (use + <function>isset</function> or <function>empty</function> to test + for empty fields). That allows more user control over the + appearance of empty fields (than in the case of an empty string + as the representation of an empty field). </para> </note> <note> @@ -410,10 +451,9 @@ <example> <title>Creating a "multiple field" column</title> <programlisting role="sesam"> -CREATE TABLE multi_field_test -( - pkey CHAR(20) PRIMARY KEY, - multi(3) CHAR(12) +CREATE TABLE multi_field_test ( + pkey CHAR(20) PRIMARY KEY, + multi(3) CHAR(12) ) </programlisting> </example> @@ -421,28 +461,28 @@ <example> <title>Filling a "multiple field" column</title> <programlisting role="sesam"> -INSERT INTO multi_field_test ( pkey, multi(2..3) ) - VALUES ( 'Second', &lt;'first_val','second_val'&gt;) +INSERT INTO multi_field_test (pkey, multi(2..3) ) + VALUES ('Second', &lt;'first_val', 'second_val'&gt;) </programlisting> </example> - Note that (like in this case) leading empty sub-fields are ignored, - and the filled-in values are collapsed, so that in the above - example the result will appear as multi(1..2) instead of + Note that (like in this case) leading empty sub-fields are + ignored, and the filled-in values are collapsed, so that in the + above example the result will appear as multi(1..2) instead of multi(2..3). </para> <para> - When retrieving a result row, "multiple columns" are accessed like - "inlined" additional columns. In the example above, "pkey" will have - the index 0, and the three "multi(1..3)" columns will be accessible - as indices 1 through 3. + When retrieving a result row, "multiple columns" are accessed + like "inlined" additional columns. In the example above, "pkey" + will have the index 0, and the three "multi(1..3)" columns will + be accessible as indices 1 through 3. </para> </note> <para> - For specific SESAM details, please refer to - <ulink url="&url.sesam.en;">the SESAM/SQL-Server - documentation (english)</ulink> or - <ulink url="&url.sesam.de;">the SESAM/SQL-Server documentation (german)</ulink>, - both available online, or use the respective manuals. + For specific SESAM details, please refer to <ulink + url="&url.sesam.en;">the SESAM/SQL-Server documentation + (english)</ulink> or <ulink url="&url.sesam.de;">the + SESAM/SQL-Server documentation (german)</ulink>, both available + online, or use the respective manuals. </para> </partintro> @@ -455,29 +495,29 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_connect</function></funcdef> + <funcdef>bool <function>sesam_connect</function></funcdef> <paramdef>string <parameter>catalog</parameter></paramdef> <paramdef>string <parameter>schema</parameter></paramdef> <paramdef>string <parameter>user</parameter></paramdef> </funcprototype> </funcsynopsis> <para> - Returns &true; if a connection to the SESAM database was made, or - &false; on error. + 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 - "persistant" in the sense that only the very first invocation will - actually load the driver from the configured SESAM OML PLAM + "persistant" 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> + 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 @@ -486,11 +526,11 @@ <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. + <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>. @@ -498,8 +538,8 @@ <title>Connect to a SESAM database</title> <programlisting role="php"> &lt;?php -if (! sesam_connect ("mycatalog", "myschema", "otto") - die("Unable to connect to SESAM"; +if (!sesam_connect ("mycatalog", "myschema", "otto") + die("Unable to connect to SESAM"; ?&gt; </programlisting> </example> @@ -516,7 +556,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_disconnect</function></funcdef> + <funcdef>bool <function>sesam_disconnect</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -524,9 +564,9 @@ Returns: always &true;. </para> <para> - <function>sesam_disconnect</function> closes the logical link to a - SESAM database (without actually disconnecting and unloading the - driver). + <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 @@ -548,8 +588,9 @@ <title>Closing a SESAM connection</title> <programlisting role="php"> if (sesam_connect ("mycatalog", "myschema", "otto")) { -... some queries and stuff ... -sesam_disconnect(); } + ... some queries and stuff ... + sesam_disconnect(); +} </programlisting> </example> </para> @@ -565,7 +606,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_settransaction</function></funcdef> + <funcdef>bool <function>sesam_settransaction</function></funcdef> <paramdef>int <parameter>isolation_level</parameter></paramdef> <paramdef>int <parameter>read_only</parameter></paramdef> </funcprototype> @@ -580,72 +621,77 @@ 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. + 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. + <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> + <title> + Valid values for <parameter>"Isolation_Level"</parameter> + parameter + </title> <tgroup cols="3"> <thead> <row> - <entry>Value</entry> - <entry>Constant</entry> - <entry>Meaning</entry> + <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> + <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> + <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> + <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> + <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> + <title> + Valid values for <parameter>"Read_Only"</parameter> parameter + </title> <tgroup cols="3"> <thead> <row> - <entry>Value</entry> - <entry>Constant</entry> - <entry>Meaning</entry> + <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> + <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> + <entry>1</entry> + <entry><literal>SESAM_TXREAD_READONLY</literal></entry> + <entry>Read-Only</entry> </row> </tbody> </tgroup> @@ -661,7 +707,7 @@ <title>Setting SESAM transaction parameters</title> <programlisting role="php"> &lt;?php -sesam_settransaction(SESAM_TXISOL_REPEATABLE_READ, +sesam_settransaction (SESAM_TXISOL_REPEATABLE_READ, SESAM_TXREAD_READONLY); ?&gt; </programlisting> @@ -673,13 +719,15 @@ <refentry id="function.sesam-commit"> <refnamediv> <refname>sesam_commit</refname> - <refpurpose>Commit pending updates to the SESAM database</refpurpose> + <refpurpose> + Commit pending updates to the SESAM database + </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_commit</function></funcdef> + <funcdef>bool <function>sesam_commit</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -692,9 +740,9 @@ 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 + 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> @@ -707,10 +755,10 @@ <programlisting role="php"> &lt;?php if (sesam_connect ("mycatalog", "myschema", "otto")) { - if (!sesam_execimm("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)")) - die("insert failed"); - if (!sesam_commit()) - die("commit failed"); + if (!sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)")) + die("insert failed"); + if (!sesam_commit()) + die("commit failed"); } ?&gt; </programlisting> @@ -718,17 +766,19 @@ </para> </refsect1> </refentry> - + <refentry id="function.sesam-rollback"> <refnamediv> <refname>sesam_rollback</refname> - <refpurpose>Discard any pending updates to the SESAM database</refpurpose> + <refpurpose> + Discard any pending updates to the SESAM database + </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_rollback</function></funcdef> + <funcdef>bool <function>sesam_rollback</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -737,8 +787,8 @@ &false; on errors </para> <para> - <function>sesam_rollback</function> discards any pending updates to - the database. Also affected are result cursors and result + <function>sesam_rollback</function> discards any pending updates + to the database. Also affected are result cursors and result descriptors. </para> <para> @@ -754,11 +804,11 @@ <programlisting role="php"> &lt;?php if (sesam_connect ("mycatalog", "myschema", "otto")) { - if (sesam_execimm("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)") - && sesam_execimm("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) - sesam_commit(); - else - sesam_rollback(); + if (sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)") + &amp;&amp; sesam_execimm ("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) + sesam_commit(); + else + sesam_rollback(); } ?&gt; </programlisting> @@ -766,7 +816,7 @@ </para> </refsect1> </refentry> - + <refentry id="function.sesam-execimm"> <refnamediv> <refname>sesam_execimm</refname> @@ -797,10 +847,9 @@ 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>. + 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 @@ -811,12 +860,12 @@ <para> <informalexample> <programlisting role="php"> -$stmt = "INSERT INTO mytable VALUES('one', 'two')"; +$stmt = "INSERT INTO mytable VALUES ('one', 'two')"; $result = sesam_execimm ($stmt); $err = sesam_diagnostic(); -print("sqlstate = ".$err["sqlstate"]."\n". - "Affected rows = ".$err["rowcount"]." == ". - sesam_affected_rows($result)."\n"); +print ("sqlstate = ".$err["sqlstate"]."\n". + "Affected rows = ".$err["rowcount"]." == ". + sesam_affected_rows($result)."\n"); </programlisting> </informalexample> See also: <function>sesam_query</function> and @@ -836,14 +885,14 @@ <funcprototype> <funcdef>string <function>sesam_query</function></funcdef> <paramdef>string <parameter>query</parameter></paramdef> - <paramdef>boolean + <paramdef>bool <parameter><optional>scrollable</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> Returns: A SESAM "result identifier" on success, or - &false; on error. + &false; on error. </para> <para> A "result_id" resource is used by other functions to retrieve the @@ -851,32 +900,31 @@ </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 + 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). 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>. + 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. + 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 @@ -887,47 +935,49 @@ </title> <programlisting role="php"> &lt;?php -if (!sesam_connect("phonedb", "demo", "otto")) - die("cannot connect"); -$result = sesam_query("select * from phone"); +if (!sesam_connect ("phonedb", "demo", "otto")) + die ("cannot connect"); +$result = sesam_query ("select * from phone"); if (!$result) { - $err = sesam_diagnostic(); - die($err["errmsg"]); + $err = sesam_diagnostic(); + die ($err["errmsg"]); } echo "&lt;TABLE BORDER&gt;\n"; // Add title header with column names above the result: -if ($cols = sesam_field_array($result)) { - echo " &lt;TR&gt;&lt;TH COLSPAN=".$cols["count"]."&gt;Result:&lt;/TH&gt;&lt;/TR&gt;\n"; - echo " &lt;TR&gt;\n"; - for ($col = 0; $col &lt; $cols["count"]; ++$col) { - $colattr = $cols[$col]; - /* Span the table head over SESAM's "Multiple Fields": */ - if ($colattr["count"] &gt; 1) { - echo " &lt;TH COLSPAN=".$colattr["count"]."&gt;".$colattr["name"]. - "(1..".$colattr["count"].")&lt;/TH&gt;\n"; - $col += $colattr["count"] - 1; +if ($cols = sesam_field_array ($result)) { + echo " &lt;TR&gt;&lt;TH COLSPAN=".$cols["count"]."&gt;Result:&lt;/TH&gt;&lt;/TR&gt;\n"; + echo " &lt;TR&gt;\n"; + for ($col = 0; $col &lt; $cols["count"]; ++$col) { + $colattr = $cols[$col]; + /* Span the table head over SESAM's "Multiple Fields": */ + if ($colattr["count"] &gt; 1) { + echo " &lt;TH COLSPAN=".$colattr["count"]."&gt;".$colattr["name"]. + "(1..".$colattr["count"].")&lt;/TH&gt;\n"; + $col += $colattr["count"] - 1; + } else + echo " &lt;TH&gt;" . $colattr["name"] . "&lt;/TH&gt;\n"; } - else - echo " &lt;TH&gt;" . $colattr["name"] . "&lt;/TH&gt;\n"; - } - echo " &lt;/TR&gt;\n"; + echo " &lt;/TR&gt;\n"; } do { - // Fetch the result in chunks of 100 rows max. - $ok = sesam_fetch_result($result,100); - for ($row=0; $row &lt; $ok["rows"]; ++$row) { - echo " &lt;TR&gt;\n"; - for ($col = 0; $col &lt; $ok["cols"]; ++$col) { - if (isset($ok[$col][$row])) - echo " &lt;TD&gt;" . $ok[$col][$row] . "&lt;/TD&gt;\n"; - else - echo " &lt;TD&gt;-empty-&lt;/TD&gt;\n"; + // Fetch the result in chunks of 100 rows max. + $ok = sesam_fetch_result ($result, 100); + for ($row=0; $row &lt; $ok["rows"]; ++$row) { + echo " &lt;TR&gt;\n"; + for ($col = 0; $col &lt; $ok["cols"]; ++$col) { + if (isset($ok[$col][$row])) + echo " &lt;TD&gt;" . $ok[$col][$row] . "&lt;/TD&gt;\n"; + } else { + echo " &lt;TD&gt;-empty-&lt;/TD&gt;\n"; + } + } + echo " &lt;/TR&gt;\n"; } - echo " &lt;/TR&gt;\n"; - } -} while ($ok["truncated"]); // while there may be more data -echo "&lt;/TABLE&gt;\n"; +} +while ($ok["truncated"]) { // while there may be more data + echo "&lt;/TABLE&gt;\n"; +} // free result id sesam_free_result($result); ?&gt; @@ -940,7 +990,9 @@ <refentry id="function.sesam-num-fields"> <refnamediv> <refname>sesam_num_fields</refname> - <refpurpose>Return the number of fields/columns in a result set</refpurpose> + <refpurpose> + Return the number of fields/columns in a result set + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -951,12 +1003,12 @@ </funcprototype> </funcsynopsis> <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. + 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 @@ -995,9 +1047,11 @@ 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> + <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 @@ -1009,7 +1063,9 @@ <refentry id="function.sesam-diagnostic"> <refnamediv> <refname>sesam_diagnostic</refname> - <refpurpose>Return status information for last SESAM call</refpurpose> + <refpurpose> + Return status information for last SESAM call + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1021,8 +1077,7 @@ </funcsynopsis> <para> Returns an associative array of status and return codes for the - last SQL query/statement/command. - Elements of the array are: + last SQL query/statement/command. Elements of the array are: <table> <title> Status information returned by <function>sesam_diagnostic</function> @@ -1030,39 +1085,45 @@ <tgroup cols="2"> <thead> <row> - <entry>Element</entry> - <entry>Contents</entry> + <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> + <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> @@ -1079,74 +1140,72 @@ // Function which prints a formatted error message, // displaying a pointer to the syntax error in the // SQL statement -function PrintReturncode($exec_str) -{ - $err = Sesam_Diagnostic(); - $colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount - if ($err["errlin"] == -1) - --$colspan; - if ($err["errcol"] == -1) - --$colspan; - if ($err["rowcount"] == 0) - --$colspan; - echo "&lt;TABLE BORDER&gt;\n"; - echo "&lt;TR&gt;&lt;TH COLSPAN=".$colspan."&gt;&lt;FONT COLOR=red&gt;ERROR:&lt;/FONT&gt; ". +function PrintReturncode ($exec_str) { + $err = Sesam_Diagnostic(); + $colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount + if ($err["errlin"] == -1) + --$colspan; + if ($err["errcol"] == -1) + --$colspan; + if ($err["rowcount"] == 0) + --$colspan; + echo "&lt;TABLE BORDER&gt;\n"; + echo "&lt;TR&gt;&lt;TH COLSPAN=".$colspan."&gt;&lt;FONT COLOR=red&gt;ERROR:&lt;/FONT&gt; ". htmlspecialchars($err["errmsg"])."&lt;/TH&gt;&lt;/TR&gt;\n"; - if ($err["errcol"] &gt;= 0) { - echo "&lt;TR&gt;&lt;TD COLSPAN=".$colspan."&gt;&lt;PRE&gt;\n"; - $errstmt = $exec_str."\n"; - for ($lin=0; $errstmt != ""; ++$lin) { - if ($lin != $err["errlin"]) { // $lin is less or greater than errlin - if (! ($i = strchr($errstmt, "\n"))) - $i = ""; - $line = substr($errstmt, 0, strlen($errstmt)-strlen($i)+1); - $errstmt = substr($i, 1); - if ($line != "\n") - print htmlspecialchars($line); - } - else { - if (! ($i = strchr($errstmt, "\n"))) - $i = ""; - $line = substr($errstmt, 0, strlen($errstmt)-strlen($i)+1); - $errstmt = substr($i, 1); - for ($col=0; $col &lt; $err["errcol"]; ++$col) - echo (substr($line, $col, 1) == "\t") ? "\t" : "."; - echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;\\&lt;/BLINK&gt;&lt;/FONT&gt;\n"; - print "&lt;FONT COLOR=\"#880000\"&gt;".htmlspecialchars($line)."&lt;/FONT&gt;"; - for ($col=0; $col &lt; $err["errcol"]; ++$col) - echo (substr($line, $col, 1) == "\t") ? "\t" : "."; - echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;/&lt;/BLINK&gt;&lt;/FONT&gt;\n"; - } - } - echo "&lt;/PRE&gt;&lt;/TD&gt;&lt;/TR&gt;\n"; - } - echo "&lt;TR&gt;\n"; - echo " &lt;TD&gt;sqlstate=" . $err["sqlstate"] . "&lt;/TD&gt;\n"; - if ($err["errlin"] != -1) - echo " &lt;TD&gt;errlin=" . $err["errlin"] . "&lt;/TD&gt;\n"; - if ($err["errcol"] != -1) - echo " &lt;TD&gt;errcol=" . $err["errcol"] . "&lt;/TD&gt;\n"; - if ($err["rowcount"] != 0) - echo " &lt;TD&gt;rowcount=" . $err["rowcount"] . "&lt;/TD&gt;\n"; - echo "&lt;/TR&gt;\n"; - echo "&lt;/TABLE&gt;\n"; + if ($err["errcol"] &gt;= 0) { + echo "&lt;TR&gt;&lt;TD COLSPAN=".$colspan."&gt;&lt;PRE&gt;\n"; + $errstmt = $exec_str."\n"; + for ($lin=0; $errstmt != ""; ++$lin) { + if ($lin != $err["errlin"]) { // $lin is less or greater than errlin + if (!($i = strchr ($errstmt, "\n"))) + $i = ""; + $line = substr ($errstmt, 0, strlen($errstmt)-strlen($i)+1); + $errstmt = substr($i, 1); + if ($line != "\n") + print htmlspecialchars ($line); + } else { + if (! ($i = strchr ($errstmt, "\n"))) + $i = ""; + $line = substr ($errstmt, 0, strlen ($errstmt)-strlen($i)+1); + $errstmt = substr($i, 1); + for ($col=0; $col &lt; $err["errcol"]; ++$col) + echo (substr($line, $col, 1) == "\t") ? "\t" : "."; + echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;\\&lt;/BLINK&gt;&lt;/FONT&gt;\n"; + print "&lt;FONT COLOR=\"#880000\"&gt;".htmlspecialchars($line)."&lt;/FONT&gt;"; + for ($col=0; $col &lt; $err["errcol"]; ++$col) + echo (substr ($line, $col, 1) == "\t") ? "\t" : "."; + echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;/&lt;/BLINK&gt;&lt;/FONT&gt;\n"; + } + } + echo "&lt;/PRE&gt;&lt;/TD&gt;&lt;/TR&gt;\n"; + } + echo "&lt;TR&gt;\n"; + echo " &lt;TD&gt;sqlstate=" . $err["sqlstate"] . "&lt;/TD&gt;\n"; + if ($err["errlin"] != -1) + echo " &lt;TD&gt;errlin=" . $err["errlin"] . "&lt;/TD&gt;\n"; + if ($err["errcol"] != -1) + echo " &lt;TD&gt;errcol=" . $err["errcol"] . "&lt;/TD&gt;\n"; + if ($err["rowcount"] != 0) + echo " &lt;TD&gt;rowcount=" . $err["rowcount"] . "&lt;/TD&gt;\n"; + echo "&lt;/TR&gt;\n"; + echo "&lt;/TABLE&gt;\n"; } -if (!sesam_connect("mycatalog", "phoneno", "otto")) - die("cannot connect"); +if (!sesam_connect ("mycatalog", "phoneno", "otto")) + die ("cannot connect"); $stmt = "SELECT * FROM phone\n". - " WHERE@ LASTNAME='KRAEMER'\n". - " ORDER BY FIRSTNAME"; -if (! ($result = sesam_query($stmt))) - PrintReturncode($stmt); + " WHERE@ LASTNAME='KRAEMER'\n". + " ORDER BY FIRSTNAME"; +if (!($result = sesam_query ($stmt))) + PrintReturncode ($stmt); ?&gt; </programlisting> </example> </para> <para> - See also: <function>sesam_errormsg</function> for simple access to the - error string only + See also: <function>sesam_errormsg</function> for simple access + to the error string only </para> </refsect1> </refentry> @@ -1180,48 +1239,54 @@ <tgroup cols="2"> <thead> <row> - <entry>Array Element</entry> - <entry>Contents</entry> + <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>boolean $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> + <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>boolean $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> + <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> @@ -1245,7 +1310,9 @@ <refentry id="function.sesam-affected-rows"> <refnamediv> <refname>sesam_affected_rows</refname> - <refpurpose>Get number of rows affected by an immediate query</refpurpose> + <refpurpose> + Get number of rows affected by an immediate query + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1263,29 +1330,29 @@ </para> <para> Returns the number of rows affected by a query associated with - <parameter>result_id</parameter>. + <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. + 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> See also: <function>sesam_query</function> and - <function>sesam_execimm</function> + <function>sesam_execimm</function> </para> - <informalexample> - <programlisting role="php"> -$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper($name)."'"); -if (! $result) { + <informalexample> + <programlisting role="php"> +$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper ($name)."'"); +if (!$result) { ... error ... } -print sesam_affected_rows($result). - " entries with last name ".$name." deleted.\n" +print sesam_affected_rows ($result). + " entries with last name ".$name." deleted.\n" </programlisting> </informalexample> </refsect1> @@ -1305,13 +1372,13 @@ </funcprototype> </funcsynopsis> <para> - Returns the SESAM error message associated with the most - recent SESAM error. + Returns the SESAM error message associated with the most recent + SESAM error. </para> <informalexample> <programlisting role="php"> -if (!sesam_execimm($stmt)) - printf("%s&lt;br&gt;\n", sesam_errormsg()); +if (!sesam_execimm ($stmt)) + printf ("%s&lt;br&gt;\n", sesam_errormsg()); </programlisting> </informalexample> <para> @@ -1342,8 +1409,9 @@ </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>. + (column name, type, precision, ...) about individual columns of + the result after the query associated with + <parameter>result_id</parameter>. </para> <para> <table> @@ -1353,164 +1421,160 @@ <tgroup cols="2"> <thead> <row> - <entry>Array Element</entry> - <entry>Contents</entry> + <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> + <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>"integer"</simpara> - </listitem> - <listitem> - <simpara>"double"</simpara> - </listitem> - <listitem> - <simpara>"string"</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> + <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>"integer"</simpara> + </listitem> + <listitem> + <simpara>"double"</simpara> + </listitem> + <listitem> + <simpara>"string"</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 the <function>sesam_query</function> function - for an example of the <function>sesam_field_array</function> use. + See the <function>sesam_query</function> function for an example + of the <function>sesam_field_array</function> use. </para> </refsect1> </refentry> @@ -1535,14 +1599,14 @@ </funcprototype> </funcsynopsis> <para> - Returns an array that corresponds to the fetched row, - or &false; if there are no more rows. + 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 + <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 + 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> @@ -1550,62 +1614,71 @@ <function>sesam_query</function> (select type queries only!). </para> <para> - <parameter><optional>whence</optional></parameter> is an - optional parameter for a fetch operation on "scrollable" - cursors, which can be set to the following predefined - constants: + <parameter><optional>whence</optional></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> + <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> + <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> @@ -1615,40 +1688,38 @@ <para> When using "scrollable" cursors, the cursor can be freely positioned on the result set. If the - <parameter><optional>whence</optional></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><optional>whence</optional></parameter> is - supplied, its value replaces the global default. - </para> - <para> - <parameter><optional>offset</optional></parameter> is an - optional parameter which is only evaluated (and required) - if <parameter><optional>whence</optional></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 - 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 + <parameter><optional>whence</optional></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><optional>whence</optional></parameter> is supplied, + its value replaces the global default. + </para> + <para> + <parameter><optional>offset</optional></parameter> is an optional + parameter which is only evaluated (and required) if + <parameter><optional>whence</optional></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 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. </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. + 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> @@ -1657,16 +1728,16 @@ $result = sesam_query (&quot;SELECT * FROM phone\n&quot;. &quot; WHERE LASTNAME='&quot;.strtoupper($name).&quot;'\n&quot;. &quot; ORDER BY FIRSTNAME&quot;, 1); -if (! $result) { +if (!$result) { ... error ... } // print the table in backward order print &quot;&lt;TABLE BORDER&gt;\n&quot;; $row = sesam_fetch_row ($result, SESAM_SEEK_LAST); -while (is_array($row)) { +while (is_array ($row)) { print &quot; &lt;TR&gt;\n&quot;; - for($col = 0; $col &lt; $row[&quot;count&quot;]; ++$col) { - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[$col]).&quot;&lt;/TD&gt;\n&quot;; + for ($col = 0; $col &lt; $row[&quot;count&quot;]; ++$col) { + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[$col]).&quot;&lt;/TD&gt;\n&quot;; } print &quot; &lt;/TR&gt;\n&quot;; // use implied SESAM_SEEK_PRIOR @@ -1678,8 +1749,8 @@ </programlisting> </example> <para> - See also: <function>sesam_fetch_array</function> which returns - an associative array, and <function>sesam_fetch_result</function> + 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> @@ -1705,15 +1776,14 @@ </funcprototype> </funcsynopsis> <para> - Returns an array that corresponds to the fetched row, - or &false; if there are no more rows. + 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. + <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 @@ -1722,25 +1792,23 @@ <para> For the valid values of the optional <parameter><optional>whence</optional></parameter>and - <parameter><optional>offset</optional></parameter> - parameters, see the <function>sesam_fetch_row</function> - function for details. + <parameter><optional>offset</optional></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. - + <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 + 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> @@ -1748,30 +1816,29 @@ </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: + 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"> -CREATE TABLE ... ( ... MULTI(3) INT )</programlisting> +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. + <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. + 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> @@ -1780,16 +1847,16 @@ $result = sesam_query (&quot;SELECT * FROM phone\n&quot;. &quot; WHERE LASTNAME='&quot;.strtoupper($name).&quot;'\n&quot;. &quot; ORDER BY FIRSTNAME&quot;, 1); -if (! $result) { +if (!$result) { ... error ... } // print the table: print &quot;&lt;TABLE BORDER&gt;\n&quot;; -while (($row = sesam_fetch_array ($result)) && count($row) &gt; 0) { +while (($row = sesam_fetch_array ($result)) &amp;&amp; count ($row) &gt; 0) { print &quot; &lt;TR&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;firstname&quot;]).&quot;&lt;/TD&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;lastname&quot;]).&quot;&lt;/TD&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;phoneno&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;firstname&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;lastname&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;phoneno&quot;]).&quot;&lt;/TD&gt;\n&quot;; print &quot; &lt;/TR&gt;\n&quot;; } print &quot;&lt;/TABLE&gt;\n&quot;; @@ -1798,8 +1865,8 @@ </programlisting> </example> <para> - See also: <function>sesam_fetch_row</function> which returns - an indexed array. + See also: <function>sesam_fetch_row</function> which returns an + indexed array. </para> </refsect1> </refentry> @@ -1815,7 +1882,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_seek_row</function></funcdef> + <funcdef>bool <function>sesam_seek_row</function></funcdef> <paramdef>string <parameter>result_id</parameter></paramdef> <paramdef>int <parameter>whence</parameter></paramdef> <paramdef>int @@ -1829,74 +1896,78 @@ 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: + <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> + <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>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> + <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><optional>offset</optional></parameter> is an - optional parameter which is only evaluated (and required) - if <parameter>whence</parameter> is - either <literal>SESAM_SEEK_RELATIVE</literal> or + <parameter><optional>offset</optional></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> @@ -1923,7 +1994,6 @@ </refsect1> </refentry> </reference> - <!-- Keep this comment at the end of the file Local variables: Index: phpdoc/hk/functions/sesam.xml diff -u phpdoc/hk/functions/sesam.xml:1.2 phpdoc/hk/functions/sesam.xml:1.3 --- phpdoc/hk/functions/sesam.xml:1.2 Sat Jul 7 18:22:27 2001 +++ phpdoc/hk/functions/sesam.xml Tue Jul 24 10:35:41 2001 @@ -5,19 +5,30 @@ <partintro> <para> SESAM/SQL-Server is a mainframe database system, developed by - Fujitsu Siemens Computers, Germany. It runs on high-end - mainframe servers using the operating system BS2000/OSD. + Fujitsu Siemens Computers, Germany. It runs on high-end mainframe + servers using the operating system BS2000/OSD. </para> <para> - In numerous productive BS2000 installations, SESAM/SQL-Server - has proven ... + In numerous productive BS2000 installations, SESAM/SQL-Server has + proven ... <itemizedlist> - <listitem><simpara>the ease of use of Java-, Web- and client/server - connectivity,</simpara></listitem> - <listitem><simpara>the capability to work with an availability of more - than 99.99%,</simpara></listitem> - <listitem><simpara>the ability to manage tens and even hundreds of - thousands of users.</simpara></listitem> + <listitem> + <simpara> + the ease of use of Java-, Web- and client/server connectivity, + </simpara> + </listitem> + <listitem> + <simpara> + the capability to work with an availability of more than + 99.99%, + </simpara> + </listitem> + <listitem> + <simpara> + the ability to manage tens and even hundreds of thousands of + users. + </simpara> + </listitem> </itemizedlist> </para> <para> @@ -27,81 +38,94 @@ <note> <title>Configuration notes</title> <para> - There is no standalone support for the PHP SESAM interface, - it works only as an integrated Apache module. In the Apache PHP - module, this <link linkend="ini.sect.sesam">SESAM interface is + There is no standalone support for the PHP SESAM interface, it + works only as an integrated Apache module. In the Apache PHP + module, this <link linkend="ini.sect.sesam">SESAM interface is configured</link> using Apache directives. <table> <title>SESAM Configuration directives</title> <tgroup cols="2"> <thead> <row> - <entry>Directive</entry> - <entry>Meaning</entry> + <entry>Directive</entry> + <entry>Meaning</entry> </row> </thead> <tbody> <row> - <entry><literal>php3_sesam_oml</literal></entry> - <entry>Name of BS2000 PLAM library containing the - loadable SESAM driver modules. - Required for using SESAM functions. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_oml $.SYSLNK.SESAM-SQL.030</programlisting> - </informalexample> - </para> - </entry> - </row> - <row> - <entry><literal>php3_sesam_configfile</literal></entry> - <entry>Name of SESAM application configuration file. - Required for using SESAM functions. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_configfile $SESAM.SESAM.CONF.AW</programlisting></informalexample> - It will usually contain a configuration like (see SESAM - reference manual): - <informalexample> - <programlisting role="bs2000"> + <entry><literal>php3_sesam_oml</literal></entry> + <entry> + Name of BS2000 PLAM library containing the loadable SESAM + driver modules. Required for using SESAM functions. + <para> + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_oml $.SYSLNK.SESAM-SQL.030 + </programlisting> + </informalexample> + </para> + </entry> + </row> + <row> + <entry><literal>php3_sesam_configfile</literal></entry> + <entry>Name of SESAM application configuration file. + Required for using SESAM functions. + <para> + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_configfile $SESAM.SESAM.CONF.AW + </programlisting> + </informalexample> + It will usually contain a configuration like (see SESAM reference + manual): + <informalexample> + <programlisting role="bs2000"> CNF=B NAM=K -NOTYPE</programlisting> - </informalexample> - </para> - </entry> - </row> - <row> - <entry><literal>php3_sesam_messagecatalog</literal></entry> - <entry>Name of SESAM message catalog file. - In most cases, this directive is not neccessary. Only if the - SESAM message file is not installed in the system's BS2000 - message file table, it can be set with this directive. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030</programlisting> - </informalexample> - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> +NOTYPE + </programlisting> + </informalexample> </para> + </entry> + </row> + <row> + <entry><literal>php3_sesam_messagecatalog</literal></entry> + <entry> + Name of SESAM message catalog file. In most cases, this + directive is not neccessary. Only if the SESAM message file is + not installed in the system's BS2000 message file table, it can + be set with this directive. <para> - In addition to the configuration of the PHP/SESAM interface, - you have to configure the SESAM-Database server itself on your + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030 + </programlisting> + </informalexample> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + In addition to the configuration of the PHP/SESAM interface, you + have to configure the SESAM-Database server itself on your mainframe as usual. That means: <itemizedlist> - <listitem><simpara>starting the SESAM database handler (DBH), and</simpara></listitem> - <listitem><simpara>connecting the databases with the SESAM database - handler</simpara></listitem> + <listitem> + <simpara> + starting the SESAM database handler (DBH), and + </simpara> + </listitem> + <listitem> + <simpara> + connecting the databases with the SESAM database handler + </simpara> + </listitem> </itemizedlist> </para> <para> @@ -117,28 +141,28 @@ </para> <para> The communication between PHP (running in the POSIX subsystem) - and the database handler (running outside the POSIX subsystem) - is realized by a special driver module called SQLSCI and SESAM - connection modules using common memory. - Because of the common memory access, and because PHP is a - static part of the web server, database accesses are very fast, - as they do not require remote accesses via ODBC, JDBC or UTM. + and the database handler (running outside the POSIX subsystem) is + realized by a special driver module called SQLSCI and SESAM + connection modules using common memory. Because of the common + memory access, and because PHP is a static part of the web + server, database accesses are very fast, as they do not require + remote accesses via ODBC, JDBC or UTM. </para> <para> Only a small stub loader (SESMOD) is linked with PHP, and the SESAM connection modules are pulled in from SESAM's OML PLAM library. In the <link - linkend="ini.sect.sesam">configuration</link>, you must tell - PHP the name of this PLAM library, and the file link to use for - the SESAM configuration file (As of SESAM V3.0, SQLSCI is - available in the SESAM Tool Library, which is part of the - standard distribution). + linkend="ini.sect.sesam">configuration</link>, you must tell PHP + the name of this PLAM library, and the file link to use for the + SESAM configuration file (As of SESAM V3.0, SQLSCI is available + in the SESAM Tool Library, which is part of the standard + distribution). </para> <para> Because the SQL command quoting for single quotes uses duplicated single quotes (as opposed to a single quote preceded by a - backslash, used in some other databases), it is advisable to - set the PHP configuration directives <link + backslash, used in some other databases), it is advisable to set + the PHP configuration directives <link linkend="ini.magic-quotes-gpc"><literal>php3_magic_quotes_gpc</literal></link> and <link linkend="ini.magic-quotes-sybase"><literal>php3_magic_quotes_sybase</literal></link> @@ -149,88 +173,91 @@ <note> <title>Runtime considerations</title> <para> - Because of limitations of the BS2000 process model, the driver can - be loaded only after the Apache server has forked off its server child - processes. This will slightly slow down the initial SESAM request - of each child, but subsequent accesses will respond at full speed. + Because of limitations of the BS2000 process model, the driver + can be loaded only after the Apache server has forked off its + server child processes. This will slightly slow down the initial + SESAM request of each child, but subsequent accesses will respond + at full speed. </para> <para> When explicitly defining a Message Catalog for SESAM, that catalog will be loaded each time the driver is loaded (i.e., at - the initial SESAM request). The BS2000 operating system prints - a message after successful load of the message catalog, which - will be sent to Apache's error_log file. BS2000 currently does - not allow suppression of this message, it will slowly fill up - the log. + the initial SESAM request). The BS2000 operating system prints a + message after successful load of the message catalog, which will + be sent to Apache's error_log file. BS2000 currently does not + allow suppression of this message, it will slowly fill up the + log. </para> <para> - Make sure that the SESAM OML PLAM library and SESAM - configuration file are readable by the user id running the web server. - Otherwise, the server will be unable to load the driver, and - will not allow to call any SESAM functions. Also, access to - the database must be granted to the user id under which the - Apache server is running. Otherwise, connections to the - SESAM database handler will fail. + Make sure that the SESAM OML PLAM library and SESAM configuration + file are readable by the user id running the web server. + Otherwise, the server will be unable to load the driver, and will + not allow to call any SESAM functions. Also, access to the + database must be granted to the user id under which the Apache + server is running. Otherwise, connections to the SESAM database + handler will fail. </para> </note> <note> <title>Cursor Types</title> <para> The result cursors which are allocated for SQL "select type" - queries can be either "sequential" or "scrollable". Because - of the larger memory overhead needed by "scrollable" cursors, - the default is "sequential". + queries can be either "sequential" or "scrollable". Because of + the larger memory overhead needed by "scrollable" cursors, the + default is "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>. When fetching a row - using a "scrollable" cursor, the following post-processing is - done for the global default values for the scrolling type - and scrolling offset: + 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>. When fetching a + row using a "scrollable" cursor, the following post-processing is + done for the global default values for the scrolling type and + scrolling offset: <table> <title>Scrolled Cursor Post-Processing</title> <tgroup cols="2"> <thead> <row> - <entry>Scroll Type</entry> - <entry>Action</entry> + <entry>Scroll Type</entry> + <entry>Action</entry> </row> </thead> <tbody> <row> - <entry><literal>SESAM_SEEK_NEXT</literal></entry> - <entry>none</entry> + <entry><literal>SESAM_SEEK_NEXT</literal></entry> + <entry>none</entry> </row> <row> - <entry><literal>SESAM_SEEK_PRIOR</literal></entry> - <entry>none</entry> + <entry><literal>SESAM_SEEK_PRIOR</literal></entry> + <entry>none</entry> </row> <row> - <entry><literal>SESAM_SEEK_FIRST</literal></entry> - <entry>set scroll type to - <literal>SESAM_SEEK_NEXT</literal></entry> + <entry><literal>SESAM_SEEK_FIRST</literal></entry> + <entry> + set scroll type to <literal>SESAM_SEEK_NEXT</literal> + </entry> </row> <row> - <entry><literal>SESAM_SEEK_LAST</literal></entry> - <entry>set scroll type to - <literal>SESAM_SEEK_PRIOR</literal></entry> + <entry><literal>SESAM_SEEK_LAST</literal></entry> + <entry> + set scroll type to <literal>SESAM_SEEK_PRIOR</literal> + </entry> </row> <row> - <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry> - <entry>Auto-Increment internal offset value</entry> + <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry> + <entry>Auto-Increment internal offset value</entry> </row> <row> - <entry><literal>SESAM_SEEK_RELATIVE</literal></entry> - <entry>none. (maintain global default - <parameter>offset</parameter> value, which allows - for, e.g., fetching each 10th row backwards) - </entry> + <entry><literal>SESAM_SEEK_RELATIVE</literal></entry> + <entry>none. (maintain global default + <parameter> + offset</parameter> value, which allows for, e.g., fetching + each 10th row backwards) + </entry> </row> </tbody> </tgroup> @@ -244,29 +271,29 @@ <para> Because in the PHP world it is natural to start indexes at zero (rather than 1), some adaptions have been made to the SESAM - interface: whenever an indexed array is starting with index 1 - in the native SESAM interface, the PHP interface uses - index 0 as a starting point. E.g., when retrieving columns with + interface: whenever an indexed array is starting with index 1 in + the native SESAM interface, the PHP interface uses index 0 as a + starting point. E.g., when retrieving columns with <function>sesam_fetch_row</function>, the first column has the index 0, and the subsequent columns have indexes up to (but not - including) the column count ($array["count"]). - When porting SESAM applications from other high level languages - to PHP, be aware of this changed interface. Where appropriate, - the description of the respective php sesam functions include a - note that the index is zero based. + including) the column count ($array["count"]). When porting + SESAM applications from other high level languages to PHP, be + aware of this changed interface. Where appropriate, the + description of the respective php sesam functions include a note + that the index is zero based. </para> </note> <note> <title>Security concerns</title> <para> - When allowing access to the SESAM databases, the web server - user should only have as little privileges as possible. For most + When allowing access to the SESAM databases, the web server user + should only have as little privileges as possible. For most databases, only read access privilege should be granted. - Depending on your usage scenario, add more access rights as - you see fit. Never allow full control to any database for - any user from the 'net! Restrict access to php scripts - which must administer the database by using password control - and/or SSL security. + Depending on your usage scenario, add more access rights as you + see fit. Never allow full control to any database for any user + from the 'net! Restrict access to php scripts which must + administer the database by using password control and/or SSL + security. </para> </note> <note> @@ -279,21 +306,26 @@ <itemizedlist> <listitem> <simpara>Vendor specific data types</simpara> - <simpara>Some vendor specific data types may have to be - replaced by standard SQL data types - (e.g., <literal>TEXT</literal> could be replaced by - <literal>VARCHAR(max. size)</literal>). - </simpara> + <simpara> + Some vendor specific data types may have to be replaced by + standard SQL data types (e.g., <literal>TEXT</literal> could + be replaced by <literal>VARCHAR(max. size)</literal>). + </simpara> </listitem> <listitem> <simpara>Keywords as SQL identifiers</simpara> - <simpara>In SESAM (as in standard SQL), such identifiers must - be enclosed in double quotes (or renamed).</simpara> + <simpara> + In SESAM (as in standard SQL), such identifiers must be + enclosed in double quotes (or renamed). + </simpara> </listitem> <listitem> - <simpara>Display length in data types</simpara> - <simpara>SESAM data types have a precision, not a display - length. Instead of <literal>int(4)</literal> (intended use: + <simpara> + Display length in data types + </simpara> + <simpara> + SESAM data types have a precision, not a display + length. Instead of <literal>int(4)</literal> (intended use: integers up to '9999'), SESAM requires simply <literal>int</literal> for an implied size of 31 bits. Also, the only datetime data types available in SESAM are: @@ -302,50 +334,60 @@ </simpara> </listitem> <listitem> - <simpara>SQL types with vendor-specific - <literal>unsigned</literal>, <literal>zerofill</literal>, or - <literal>auto_increment</literal> attributes</simpara> - <simpara><literal>Unsigned</literal> and<literal> - zerofill</literal> are not supported. - <literal>Auto_increment</literal> is automatic (use <literal>"INSERT ... - VALUES(*, ...)"</literal> instead of <literal>"... VALUES(0, - ...)"</literal> to take advantage of SESAM-implied - auto-increment. </simpara> - </listitem> - <listitem> - <simpara><command>int ... DEFAULT '0000'</command></simpara> - <simpara>Numeric variables must not be initialized with - string constants. Use <command>DEFAULT 0</command> - instead. To initialize variables of the datetime - SQL data types, the initialization string must be - prefixed with the respective type keyword, as in: - <literal> CREATE TABLE exmpl ( - xtime timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT &null; - ); </literal> + <simpara> + SQL types with vendor-specific <literal>unsigned</literal>, + <literal>zerofill</literal>, or + <literal>auto_increment</literal> attributes + </simpara> + <simpara> + <literal>Unsigned</literal> and<literal> zerofill</literal> + are not supported. <literal>Auto_increment</literal> is + automatic (use <literal>"INSERT ... VALUES(*, ...)"</literal> + instead of <literal>"... VALUES(0, ...)"</literal> to take + advantage of SESAM-implied auto-increment. </simpara> </listitem> <listitem> - <simpara><command>$count = xxxx_num_rows();</command></simpara> - <simpara>Some databases promise to guess/estimate the - number of the rows in a query result, even though - the returned value is grossly incorrect. SESAM - does not know the number of rows in a query result - before actually fetching them. If you REALLY need - the count, try <command>SELECT COUNT(...) WHERE - ...</command>, it will tell you the number of hits. - A second query will (hopefully) return the results. + <simpara> + <command>int ... DEFAULT '0000'</command> + </simpara> + <simpara> + Numeric variables must not be initialized with string + constants. Use <command>DEFAULT 0</command> instead. To + initialize variables of the datetime SQL data types, the + initialization string must be prefixed with the respective + type keyword, as in: <literal> CREATE TABLE exmpl ( xtime + timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT + &null; ); </literal> </simpara> </listitem> <listitem> - <simpara><command>DROP TABLE thename;</command></simpara> - <simpara>In SESAM, in the <command>DROP TABLE</command> - command, the table name must be either followed by - the keyword <literal>RESTRICT</literal> or - <literal>CASCADE</literal>. When specifying - <literal>RESTRICT</literal>, an error is returned if - there are dependent objects (e.g., VIEWs), while with - <literal>CASCADE</literal>, dependent objects will be - deleted along with the specified table. + <simpara> + <command>$count = xxxx_num_rows();</command> + </simpara> + <simpara> + Some databases promise to guess/estimate the number of the + rows in a query result, even though the returned value is + grossly incorrect. SESAM does not know the number of rows in + a query result before actually fetching them. If you REALLY + need the count, try <command>SELECT COUNT(...) WHERE + ...</command>, it will tell you the number of hits. A second + query will (hopefully) return the results. + </simpara> + </listitem> + <listitem> + <simpara> + <command>DROP TABLE thename;</command> + </simpara> + <simpara> + In SESAM, in the <command>DROP TABLE</command> command, the + table name must be either followed by the keyword + <literal>RESTRICT</literal> or + <literal>CASCADE</literal>. When specifying + <literal>RESTRICT</literal>, an error is returned if there are + dependent objects (e.g., VIEWs), while with + <literal>CASCADE</literal>, dependent objects will be deleted + along with the specified table. </simpara> </listitem> </itemizedlist> @@ -356,8 +398,8 @@ Notes on the use of various SQL types </title> <para> - SESAM does not currently support the BLOB type. A future - version of SESAM will have support for BLOB. + SESAM does not currently support the BLOB type. A future version + of SESAM will have support for BLOB. </para> <para> At the PHP interface, the following type conversions are @@ -367,38 +409,37 @@ <tgroup cols="2"> <thead> <row> - <entry>SQL Type</entry> - <entry>PHP Type</entry> + <entry>SQL Type</entry> + <entry>PHP Type</entry> </row> </thead> <tbody> <row> - <entry>SMALLINT, INTEGER</entry> - <entry>"integer"</entry> + <entry>SMALLINT, INTEGER</entry> + <entry>"integer"</entry> </row> <row> - <entry>NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE</entry> - <entry>"double"</entry> + <entry>NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE</entry> + <entry>"double"</entry> </row> <row> - <entry>DATE, TIME, TIMESTAMP</entry> - <entry>"string"</entry> + <entry>DATE, TIME, TIMESTAMP</entry> + <entry>"string"</entry> </row> <row> - <entry>VARCHAR, CHARACTER</entry> - <entry>"string"</entry> + <entry>VARCHAR, CHARACTER</entry> + <entry>"string"</entry> </row> </tbody> </tgroup> </table> When retrieving a complete row, the result is returned as an - array. Empty fields are not filled in, so you will have to - check for the existence of the individual fields yourself - (use <function>isset</function> or - <function>empty</function> to test for empty fields). - That allows more user control over the appearance of empty - fields (than in the case of an empty string as the - representation of an empty field). + array. Empty fields are not filled in, so you will have to check + for the existence of the individual fields yourself (use + <function>isset</function> or <function>empty</function> to test + for empty fields). That allows more user control over the + appearance of empty fields (than in the case of an empty string + as the representation of an empty field). </para> </note> <note> @@ -410,10 +451,9 @@ <example> <title>Creating a "multiple field" column</title> <programlisting role="sesam"> -CREATE TABLE multi_field_test -( - pkey CHAR(20) PRIMARY KEY, - multi(3) CHAR(12) +CREATE TABLE multi_field_test ( + pkey CHAR(20) PRIMARY KEY, + multi(3) CHAR(12) ) </programlisting> </example> @@ -421,28 +461,28 @@ <example> <title>Filling a "multiple field" column</title> <programlisting role="sesam"> -INSERT INTO multi_field_test ( pkey, multi(2..3) ) - VALUES ( 'Second', &lt;'first_val','second_val'&gt;) +INSERT INTO multi_field_test (pkey, multi(2..3) ) + VALUES ('Second', &lt;'first_val', 'second_val'&gt;) </programlisting> </example> - Note that (like in this case) leading empty sub-fields are ignored, - and the filled-in values are collapsed, so that in the above - example the result will appear as multi(1..2) instead of + Note that (like in this case) leading empty sub-fields are + ignored, and the filled-in values are collapsed, so that in the + above example the result will appear as multi(1..2) instead of multi(2..3). </para> <para> - When retrieving a result row, "multiple columns" are accessed like - "inlined" additional columns. In the example above, "pkey" will have - the index 0, and the three "multi(1..3)" columns will be accessible - as indices 1 through 3. + When retrieving a result row, "multiple columns" are accessed + like "inlined" additional columns. In the example above, "pkey" + will have the index 0, and the three "multi(1..3)" columns will + be accessible as indices 1 through 3. </para> </note> <para> - For specific SESAM details, please refer to - <ulink url="&url.sesam.en;">the SESAM/SQL-Server - documentation (english)</ulink> or - <ulink url="&url.sesam.de;">the SESAM/SQL-Server documentation (german)</ulink>, - both available online, or use the respective manuals. + For specific SESAM details, please refer to <ulink + url="&url.sesam.en;">the SESAM/SQL-Server documentation + (english)</ulink> or <ulink url="&url.sesam.de;">the + SESAM/SQL-Server documentation (german)</ulink>, both available + online, or use the respective manuals. </para> </partintro> @@ -455,29 +495,29 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_connect</function></funcdef> + <funcdef>bool <function>sesam_connect</function></funcdef> <paramdef>string <parameter>catalog</parameter></paramdef> <paramdef>string <parameter>schema</parameter></paramdef> <paramdef>string <parameter>user</parameter></paramdef> </funcprototype> </funcsynopsis> <para> - Returns &true; if a connection to the SESAM database was made, or - &false; on error. + 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 - "persistant" in the sense that only the very first invocation will - actually load the driver from the configured SESAM OML PLAM + "persistant" 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> + 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 @@ -486,11 +526,11 @@ <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. + <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>. @@ -498,8 +538,8 @@ <title>Connect to a SESAM database</title> <programlisting role="php"> &lt;?php -if (! sesam_connect ("mycatalog", "myschema", "otto") - die("Unable to connect to SESAM"; +if (!sesam_connect ("mycatalog", "myschema", "otto") + die("Unable to connect to SESAM"; ?&gt; </programlisting> </example> @@ -516,7 +556,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_disconnect</function></funcdef> + <funcdef>bool <function>sesam_disconnect</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -524,9 +564,9 @@ Returns: always &true;. </para> <para> - <function>sesam_disconnect</function> closes the logical link to a - SESAM database (without actually disconnecting and unloading the - driver). + <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 @@ -548,8 +588,9 @@ <title>Closing a SESAM connection</title> <programlisting role="php"> if (sesam_connect ("mycatalog", "myschema", "otto")) { -... some queries and stuff ... -sesam_disconnect(); } + ... some queries and stuff ... + sesam_disconnect(); +} </programlisting> </example> </para> @@ -565,7 +606,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_settransaction</function></funcdef> + <funcdef>bool <function>sesam_settransaction</function></funcdef> <paramdef>int <parameter>isolation_level</parameter></paramdef> <paramdef>int <parameter>read_only</parameter></paramdef> </funcprototype> @@ -580,72 +621,77 @@ 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. + 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. + <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> + <title> + Valid values for <parameter>"Isolation_Level"</parameter> + parameter + </title> <tgroup cols="3"> <thead> <row> - <entry>Value</entry> - <entry>Constant</entry> - <entry>Meaning</entry> + <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> + <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> + <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> + <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> + <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> + <title> + Valid values for <parameter>"Read_Only"</parameter> parameter + </title> <tgroup cols="3"> <thead> <row> - <entry>Value</entry> - <entry>Constant</entry> - <entry>Meaning</entry> + <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> + <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> + <entry>1</entry> + <entry><literal>SESAM_TXREAD_READONLY</literal></entry> + <entry>Read-Only</entry> </row> </tbody> </tgroup> @@ -661,7 +707,7 @@ <title>Setting SESAM transaction parameters</title> <programlisting role="php"> &lt;?php -sesam_settransaction(SESAM_TXISOL_REPEATABLE_READ, +sesam_settransaction (SESAM_TXISOL_REPEATABLE_READ, SESAM_TXREAD_READONLY); ?&gt; </programlisting> @@ -673,13 +719,15 @@ <refentry id="function.sesam-commit"> <refnamediv> <refname>sesam_commit</refname> - <refpurpose>Commit pending updates to the SESAM database</refpurpose> + <refpurpose> + Commit pending updates to the SESAM database + </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_commit</function></funcdef> + <funcdef>bool <function>sesam_commit</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -692,9 +740,9 @@ 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 + 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> @@ -707,10 +755,10 @@ <programlisting role="php"> &lt;?php if (sesam_connect ("mycatalog", "myschema", "otto")) { - if (!sesam_execimm("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)")) - die("insert failed"); - if (!sesam_commit()) - die("commit failed"); + if (!sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)")) + die("insert failed"); + if (!sesam_commit()) + die("commit failed"); } ?&gt; </programlisting> @@ -718,17 +766,19 @@ </para> </refsect1> </refentry> - + <refentry id="function.sesam-rollback"> <refnamediv> <refname>sesam_rollback</refname> - <refpurpose>Discard any pending updates to the SESAM database</refpurpose> + <refpurpose> + Discard any pending updates to the SESAM database + </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_rollback</function></funcdef> + <funcdef>bool <function>sesam_rollback</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -737,8 +787,8 @@ &false; on errors </para> <para> - <function>sesam_rollback</function> discards any pending updates to - the database. Also affected are result cursors and result + <function>sesam_rollback</function> discards any pending updates + to the database. Also affected are result cursors and result descriptors. </para> <para> @@ -754,11 +804,11 @@ <programlisting role="php"> &lt;?php if (sesam_connect ("mycatalog", "myschema", "otto")) { - if (sesam_execimm("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)") - && sesam_execimm("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) - sesam_commit(); - else - sesam_rollback(); + if (sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)") + &amp;&amp; sesam_execimm ("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) + sesam_commit(); + else + sesam_rollback(); } ?&gt; </programlisting> @@ -766,7 +816,7 @@ </para> </refsect1> </refentry> - + <refentry id="function.sesam-execimm"> <refnamediv> <refname>sesam_execimm</refname> @@ -797,10 +847,9 @@ 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>. + 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 @@ -811,12 +860,12 @@ <para> <informalexample> <programlisting role="php"> -$stmt = "INSERT INTO mytable VALUES('one', 'two')"; +$stmt = "INSERT INTO mytable VALUES ('one', 'two')"; $result = sesam_execimm ($stmt); $err = sesam_diagnostic(); -print("sqlstate = ".$err["sqlstate"]."\n". - "Affected rows = ".$err["rowcount"]." == ". - sesam_affected_rows($result)."\n"); +print ("sqlstate = ".$err["sqlstate"]."\n". + "Affected rows = ".$err["rowcount"]." == ". + sesam_affected_rows($result)."\n"); </programlisting> </informalexample> See also: <function>sesam_query</function> and @@ -836,14 +885,14 @@ <funcprototype> <funcdef>string <function>sesam_query</function></funcdef> <paramdef>string <parameter>query</parameter></paramdef> - <paramdef>boolean + <paramdef>bool <parameter><optional>scrollable</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> Returns: A SESAM "result identifier" on success, or - &false; on error. + &false; on error. </para> <para> A "result_id" resource is used by other functions to retrieve the @@ -851,32 +900,31 @@ </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 + 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). 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>. + 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. + 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 @@ -887,47 +935,49 @@ </title> <programlisting role="php"> &lt;?php -if (!sesam_connect("phonedb", "demo", "otto")) - die("cannot connect"); -$result = sesam_query("select * from phone"); +if (!sesam_connect ("phonedb", "demo", "otto")) + die ("cannot connect"); +$result = sesam_query ("select * from phone"); if (!$result) { - $err = sesam_diagnostic(); - die($err["errmsg"]); + $err = sesam_diagnostic(); + die ($err["errmsg"]); } echo "&lt;TABLE BORDER&gt;\n"; // Add title header with column names above the result: -if ($cols = sesam_field_array($result)) { - echo " &lt;TR&gt;&lt;TH COLSPAN=".$cols["count"]."&gt;Result:&lt;/TH&gt;&lt;/TR&gt;\n"; - echo " &lt;TR&gt;\n"; - for ($col = 0; $col &lt; $cols["count"]; ++$col) { - $colattr = $cols[$col]; - /* Span the table head over SESAM's "Multiple Fields": */ - if ($colattr["count"] &gt; 1) { - echo " &lt;TH COLSPAN=".$colattr["count"]."&gt;".$colattr["name"]. - "(1..".$colattr["count"].")&lt;/TH&gt;\n"; - $col += $colattr["count"] - 1; +if ($cols = sesam_field_array ($result)) { + echo " &lt;TR&gt;&lt;TH COLSPAN=".$cols["count"]."&gt;Result:&lt;/TH&gt;&lt;/TR&gt;\n"; + echo " &lt;TR&gt;\n"; + for ($col = 0; $col &lt; $cols["count"]; ++$col) { + $colattr = $cols[$col]; + /* Span the table head over SESAM's "Multiple Fields": */ + if ($colattr["count"] &gt; 1) { + echo " &lt;TH COLSPAN=".$colattr["count"]."&gt;".$colattr["name"]. + "(1..".$colattr["count"].")&lt;/TH&gt;\n"; + $col += $colattr["count"] - 1; + } else + echo " &lt;TH&gt;" . $colattr["name"] . "&lt;/TH&gt;\n"; } - else - echo " &lt;TH&gt;" . $colattr["name"] . "&lt;/TH&gt;\n"; - } - echo " &lt;/TR&gt;\n"; + echo " &lt;/TR&gt;\n"; } do { - // Fetch the result in chunks of 100 rows max. - $ok = sesam_fetch_result($result,100); - for ($row=0; $row &lt; $ok["rows"]; ++$row) { - echo " &lt;TR&gt;\n"; - for ($col = 0; $col &lt; $ok["cols"]; ++$col) { - if (isset($ok[$col][$row])) - echo " &lt;TD&gt;" . $ok[$col][$row] . "&lt;/TD&gt;\n"; - else - echo " &lt;TD&gt;-empty-&lt;/TD&gt;\n"; + // Fetch the result in chunks of 100 rows max. + $ok = sesam_fetch_result ($result, 100); + for ($row=0; $row &lt; $ok["rows"]; ++$row) { + echo " &lt;TR&gt;\n"; + for ($col = 0; $col &lt; $ok["cols"]; ++$col) { + if (isset($ok[$col][$row])) + echo " &lt;TD&gt;" . $ok[$col][$row] . "&lt;/TD&gt;\n"; + } else { + echo " &lt;TD&gt;-empty-&lt;/TD&gt;\n"; + } + } + echo " &lt;/TR&gt;\n"; } - echo " &lt;/TR&gt;\n"; - } -} while ($ok["truncated"]); // while there may be more data -echo "&lt;/TABLE&gt;\n"; +} +while ($ok["truncated"]) { // while there may be more data + echo "&lt;/TABLE&gt;\n"; +} // free result id sesam_free_result($result); ?&gt; @@ -940,7 +990,9 @@ <refentry id="function.sesam-num-fields"> <refnamediv> <refname>sesam_num_fields</refname> - <refpurpose>Return the number of fields/columns in a result set</refpurpose> + <refpurpose> + Return the number of fields/columns in a result set + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -951,12 +1003,12 @@ </funcprototype> </funcsynopsis> <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. + 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 @@ -995,9 +1047,11 @@ 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> + <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 @@ -1009,7 +1063,9 @@ <refentry id="function.sesam-diagnostic"> <refnamediv> <refname>sesam_diagnostic</refname> - <refpurpose>Return status information for last SESAM call</refpurpose> + <refpurpose> + Return status information for last SESAM call + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1021,8 +1077,7 @@ </funcsynopsis> <para> Returns an associative array of status and return codes for the - last SQL query/statement/command. - Elements of the array are: + last SQL query/statement/command. Elements of the array are: <table> <title> Status information returned by <function>sesam_diagnostic</function> @@ -1030,39 +1085,45 @@ <tgroup cols="2"> <thead> <row> - <entry>Element</entry> - <entry>Contents</entry> + <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> + <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> @@ -1079,74 +1140,72 @@ // Function which prints a formatted error message, // displaying a pointer to the syntax error in the // SQL statement -function PrintReturncode($exec_str) -{ - $err = Sesam_Diagnostic(); - $colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount - if ($err["errlin"] == -1) - --$colspan; - if ($err["errcol"] == -1) - --$colspan; - if ($err["rowcount"] == 0) - --$colspan; - echo "&lt;TABLE BORDER&gt;\n"; - echo "&lt;TR&gt;&lt;TH COLSPAN=".$colspan."&gt;&lt;FONT COLOR=red&gt;ERROR:&lt;/FONT&gt; ". +function PrintReturncode ($exec_str) { + $err = Sesam_Diagnostic(); + $colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount + if ($err["errlin"] == -1) + --$colspan; + if ($err["errcol"] == -1) + --$colspan; + if ($err["rowcount"] == 0) + --$colspan; + echo "&lt;TABLE BORDER&gt;\n"; + echo "&lt;TR&gt;&lt;TH COLSPAN=".$colspan."&gt;&lt;FONT COLOR=red&gt;ERROR:&lt;/FONT&gt; ". htmlspecialchars($err["errmsg"])."&lt;/TH&gt;&lt;/TR&gt;\n"; - if ($err["errcol"] &gt;= 0) { - echo "&lt;TR&gt;&lt;TD COLSPAN=".$colspan."&gt;&lt;PRE&gt;\n"; - $errstmt = $exec_str."\n"; - for ($lin=0; $errstmt != ""; ++$lin) { - if ($lin != $err["errlin"]) { // $lin is less or greater than errlin - if (! ($i = strchr($errstmt, "\n"))) - $i = ""; - $line = substr($errstmt, 0, strlen($errstmt)-strlen($i)+1); - $errstmt = substr($i, 1); - if ($line != "\n") - print htmlspecialchars($line); - } - else { - if (! ($i = strchr($errstmt, "\n"))) - $i = ""; - $line = substr($errstmt, 0, strlen($errstmt)-strlen($i)+1); - $errstmt = substr($i, 1); - for ($col=0; $col &lt; $err["errcol"]; ++$col) - echo (substr($line, $col, 1) == "\t") ? "\t" : "."; - echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;\\&lt;/BLINK&gt;&lt;/FONT&gt;\n"; - print "&lt;FONT COLOR=\"#880000\"&gt;".htmlspecialchars($line)."&lt;/FONT&gt;"; - for ($col=0; $col &lt; $err["errcol"]; ++$col) - echo (substr($line, $col, 1) == "\t") ? "\t" : "."; - echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;/&lt;/BLINK&gt;&lt;/FONT&gt;\n"; - } - } - echo "&lt;/PRE&gt;&lt;/TD&gt;&lt;/TR&gt;\n"; - } - echo "&lt;TR&gt;\n"; - echo " &lt;TD&gt;sqlstate=" . $err["sqlstate"] . "&lt;/TD&gt;\n"; - if ($err["errlin"] != -1) - echo " &lt;TD&gt;errlin=" . $err["errlin"] . "&lt;/TD&gt;\n"; - if ($err["errcol"] != -1) - echo " &lt;TD&gt;errcol=" . $err["errcol"] . "&lt;/TD&gt;\n"; - if ($err["rowcount"] != 0) - echo " &lt;TD&gt;rowcount=" . $err["rowcount"] . "&lt;/TD&gt;\n"; - echo "&lt;/TR&gt;\n"; - echo "&lt;/TABLE&gt;\n"; + if ($err["errcol"] &gt;= 0) { + echo "&lt;TR&gt;&lt;TD COLSPAN=".$colspan."&gt;&lt;PRE&gt;\n"; + $errstmt = $exec_str."\n"; + for ($lin=0; $errstmt != ""; ++$lin) { + if ($lin != $err["errlin"]) { // $lin is less or greater than errlin + if (!($i = strchr ($errstmt, "\n"))) + $i = ""; + $line = substr ($errstmt, 0, strlen($errstmt)-strlen($i)+1); + $errstmt = substr($i, 1); + if ($line != "\n") + print htmlspecialchars ($line); + } else { + if (! ($i = strchr ($errstmt, "\n"))) + $i = ""; + $line = substr ($errstmt, 0, strlen ($errstmt)-strlen($i)+1); + $errstmt = substr($i, 1); + for ($col=0; $col &lt; $err["errcol"]; ++$col) + echo (substr($line, $col, 1) == "\t") ? "\t" : "."; + echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;\\&lt;/BLINK&gt;&lt;/FONT&gt;\n"; + print "&lt;FONT COLOR=\"#880000\"&gt;".htmlspecialchars($line)."&lt;/FONT&gt;"; + for ($col=0; $col &lt; $err["errcol"]; ++$col) + echo (substr ($line, $col, 1) == "\t") ? "\t" : "."; + echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;/&lt;/BLINK&gt;&lt;/FONT&gt;\n"; + } + } + echo "&lt;/PRE&gt;&lt;/TD&gt;&lt;/TR&gt;\n"; + } + echo "&lt;TR&gt;\n"; + echo " &lt;TD&gt;sqlstate=" . $err["sqlstate"] . "&lt;/TD&gt;\n"; + if ($err["errlin"] != -1) + echo " &lt;TD&gt;errlin=" . $err["errlin"] . "&lt;/TD&gt;\n"; + if ($err["errcol"] != -1) + echo " &lt;TD&gt;errcol=" . $err["errcol"] . "&lt;/TD&gt;\n"; + if ($err["rowcount"] != 0) + echo " &lt;TD&gt;rowcount=" . $err["rowcount"] . "&lt;/TD&gt;\n"; + echo "&lt;/TR&gt;\n"; + echo "&lt;/TABLE&gt;\n"; } -if (!sesam_connect("mycatalog", "phoneno", "otto")) - die("cannot connect"); +if (!sesam_connect ("mycatalog", "phoneno", "otto")) + die ("cannot connect"); $stmt = "SELECT * FROM phone\n". - " WHERE@ LASTNAME='KRAEMER'\n". - " ORDER BY FIRSTNAME"; -if (! ($result = sesam_query($stmt))) - PrintReturncode($stmt); + " WHERE@ LASTNAME='KRAEMER'\n". + " ORDER BY FIRSTNAME"; +if (!($result = sesam_query ($stmt))) + PrintReturncode ($stmt); ?&gt; </programlisting> </example> </para> <para> - See also: <function>sesam_errormsg</function> for simple access to the - error string only + See also: <function>sesam_errormsg</function> for simple access + to the error string only </para> </refsect1> </refentry> @@ -1180,48 +1239,54 @@ <tgroup cols="2"> <thead> <row> - <entry>Array Element</entry> - <entry>Contents</entry> + <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>boolean $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> + <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>boolean $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> + <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> @@ -1245,7 +1310,9 @@ <refentry id="function.sesam-affected-rows"> <refnamediv> <refname>sesam_affected_rows</refname> - <refpurpose>Get number of rows affected by an immediate query</refpurpose> + <refpurpose> + Get number of rows affected by an immediate query + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1263,29 +1330,29 @@ </para> <para> Returns the number of rows affected by a query associated with - <parameter>result_id</parameter>. + <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. + 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> See also: <function>sesam_query</function> and - <function>sesam_execimm</function> + <function>sesam_execimm</function> </para> - <informalexample> - <programlisting role="php"> -$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper($name)."'"); -if (! $result) { + <informalexample> + <programlisting role="php"> +$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper ($name)."'"); +if (!$result) { ... error ... } -print sesam_affected_rows($result). - " entries with last name ".$name." deleted.\n" +print sesam_affected_rows ($result). + " entries with last name ".$name." deleted.\n" </programlisting> </informalexample> </refsect1> @@ -1305,13 +1372,13 @@ </funcprototype> </funcsynopsis> <para> - Returns the SESAM error message associated with the most - recent SESAM error. + Returns the SESAM error message associated with the most recent + SESAM error. </para> <informalexample> <programlisting role="php"> -if (!sesam_execimm($stmt)) - printf("%s&lt;br&gt;\n", sesam_errormsg()); +if (!sesam_execimm ($stmt)) + printf ("%s&lt;br&gt;\n", sesam_errormsg()); </programlisting> </informalexample> <para> @@ -1342,8 +1409,9 @@ </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>. + (column name, type, precision, ...) about individual columns of + the result after the query associated with + <parameter>result_id</parameter>. </para> <para> <table> @@ -1353,164 +1421,160 @@ <tgroup cols="2"> <thead> <row> - <entry>Array Element</entry> - <entry>Contents</entry> + <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> + <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>"integer"</simpara> - </listitem> - <listitem> - <simpara>"double"</simpara> - </listitem> - <listitem> - <simpara>"string"</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> + <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>"integer"</simpara> + </listitem> + <listitem> + <simpara>"double"</simpara> + </listitem> + <listitem> + <simpara>"string"</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 the <function>sesam_query</function> function - for an example of the <function>sesam_field_array</function> use. + See the <function>sesam_query</function> function for an example + of the <function>sesam_field_array</function> use. </para> </refsect1> </refentry> @@ -1535,14 +1599,14 @@ </funcprototype> </funcsynopsis> <para> - Returns an array that corresponds to the fetched row, - or &false; if there are no more rows. + 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 + <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 + 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> @@ -1550,62 +1614,71 @@ <function>sesam_query</function> (select type queries only!). </para> <para> - <parameter><optional>whence</optional></parameter> is an - optional parameter for a fetch operation on "scrollable" - cursors, which can be set to the following predefined - constants: + <parameter><optional>whence</optional></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> + <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> + <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> @@ -1615,40 +1688,38 @@ <para> When using "scrollable" cursors, the cursor can be freely positioned on the result set. If the - <parameter><optional>whence</optional></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><optional>whence</optional></parameter> is - supplied, its value replaces the global default. - </para> - <para> - <parameter><optional>offset</optional></parameter> is an - optional parameter which is only evaluated (and required) - if <parameter><optional>whence</optional></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 - 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 + <parameter><optional>whence</optional></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><optional>whence</optional></parameter> is supplied, + its value replaces the global default. + </para> + <para> + <parameter><optional>offset</optional></parameter> is an optional + parameter which is only evaluated (and required) if + <parameter><optional>whence</optional></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 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. </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. + 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> @@ -1657,16 +1728,16 @@ $result = sesam_query (&quot;SELECT * FROM phone\n&quot;. &quot; WHERE LASTNAME='&quot;.strtoupper($name).&quot;'\n&quot;. &quot; ORDER BY FIRSTNAME&quot;, 1); -if (! $result) { +if (!$result) { ... error ... } // print the table in backward order print &quot;&lt;TABLE BORDER&gt;\n&quot;; $row = sesam_fetch_row ($result, SESAM_SEEK_LAST); -while (is_array($row)) { +while (is_array ($row)) { print &quot; &lt;TR&gt;\n&quot;; - for($col = 0; $col &lt; $row[&quot;count&quot;]; ++$col) { - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[$col]).&quot;&lt;/TD&gt;\n&quot;; + for ($col = 0; $col &lt; $row[&quot;count&quot;]; ++$col) { + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[$col]).&quot;&lt;/TD&gt;\n&quot;; } print &quot; &lt;/TR&gt;\n&quot;; // use implied SESAM_SEEK_PRIOR @@ -1678,8 +1749,8 @@ </programlisting> </example> <para> - See also: <function>sesam_fetch_array</function> which returns - an associative array, and <function>sesam_fetch_result</function> + 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> @@ -1705,15 +1776,14 @@ </funcprototype> </funcsynopsis> <para> - Returns an array that corresponds to the fetched row, - or &false; if there are no more rows. + 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. + <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 @@ -1722,25 +1792,23 @@ <para> For the valid values of the optional <parameter><optional>whence</optional></parameter>and - <parameter><optional>offset</optional></parameter> - parameters, see the <function>sesam_fetch_row</function> - function for details. + <parameter><optional>offset</optional></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. - + <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 + 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> @@ -1748,30 +1816,29 @@ </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: + 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"> -CREATE TABLE ... ( ... MULTI(3) INT )</programlisting> +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. + <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. + 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> @@ -1780,16 +1847,16 @@ $result = sesam_query (&quot;SELECT * FROM phone\n&quot;. &quot; WHERE LASTNAME='&quot;.strtoupper($name).&quot;'\n&quot;. &quot; ORDER BY FIRSTNAME&quot;, 1); -if (! $result) { +if (!$result) { ... error ... } // print the table: print &quot;&lt;TABLE BORDER&gt;\n&quot;; -while (($row = sesam_fetch_array ($result)) && count($row) &gt; 0) { +while (($row = sesam_fetch_array ($result)) &amp;&amp; count ($row) &gt; 0) { print &quot; &lt;TR&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;firstname&quot;]).&quot;&lt;/TD&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;lastname&quot;]).&quot;&lt;/TD&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;phoneno&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;firstname&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;lastname&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;phoneno&quot;]).&quot;&lt;/TD&gt;\n&quot;; print &quot; &lt;/TR&gt;\n&quot;; } print &quot;&lt;/TABLE&gt;\n&quot;; @@ -1798,8 +1865,8 @@ </programlisting> </example> <para> - See also: <function>sesam_fetch_row</function> which returns - an indexed array. + See also: <function>sesam_fetch_row</function> which returns an + indexed array. </para> </refsect1> </refentry> @@ -1815,7 +1882,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_seek_row</function></funcdef> + <funcdef>bool <function>sesam_seek_row</function></funcdef> <paramdef>string <parameter>result_id</parameter></paramdef> <paramdef>int <parameter>whence</parameter></paramdef> <paramdef>int @@ -1829,74 +1896,78 @@ 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: + <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> + <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>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> + <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><optional>offset</optional></parameter> is an - optional parameter which is only evaluated (and required) - if <parameter>whence</parameter> is - either <literal>SESAM_SEEK_RELATIVE</literal> or + <parameter><optional>offset</optional></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> @@ -1923,7 +1994,6 @@ </refsect1> </refentry> </reference> - <!-- Keep this comment at the end of the file Local variables: Index: phpdoc/it/functions/sesam.xml diff -u phpdoc/it/functions/sesam.xml:1.2 phpdoc/it/functions/sesam.xml:1.3 --- phpdoc/it/functions/sesam.xml:1.2 Sat Jul 7 18:25:12 2001 +++ phpdoc/it/functions/sesam.xml Tue Jul 24 10:35:41 2001 @@ -5,19 +5,30 @@ <partintro> <para> SESAM/SQL-Server is a mainframe database system, developed by - Fujitsu Siemens Computers, Germany. It runs on high-end - mainframe servers using the operating system BS2000/OSD. + Fujitsu Siemens Computers, Germany. It runs on high-end mainframe + servers using the operating system BS2000/OSD. </para> <para> - In numerous productive BS2000 installations, SESAM/SQL-Server - has proven ... + In numerous productive BS2000 installations, SESAM/SQL-Server has + proven ... <itemizedlist> - <listitem><simpara>the ease of use of Java-, Web- and client/server - connectivity,</simpara></listitem> - <listitem><simpara>the capability to work with an availability of more - than 99.99%,</simpara></listitem> - <listitem><simpara>the ability to manage tens and even hundreds of - thousands of users.</simpara></listitem> + <listitem> + <simpara> + the ease of use of Java-, Web- and client/server connectivity, + </simpara> + </listitem> + <listitem> + <simpara> + the capability to work with an availability of more than + 99.99%, + </simpara> + </listitem> + <listitem> + <simpara> + the ability to manage tens and even hundreds of thousands of + users. + </simpara> + </listitem> </itemizedlist> </para> <para> @@ -27,81 +38,94 @@ <note> <title>Configuration notes</title> <para> - There is no standalone support for the PHP SESAM interface, - it works only as an integrated Apache module. In the Apache PHP - module, this <link linkend="ini.sect.sesam">SESAM interface is + There is no standalone support for the PHP SESAM interface, it + works only as an integrated Apache module. In the Apache PHP + module, this <link linkend="ini.sect.sesam">SESAM interface is configured</link> using Apache directives. <table> <title>SESAM Configuration directives</title> <tgroup cols="2"> <thead> <row> - <entry>Directive</entry> - <entry>Meaning</entry> + <entry>Directive</entry> + <entry>Meaning</entry> </row> </thead> <tbody> <row> - <entry><literal>php3_sesam_oml</literal></entry> - <entry>Name of BS2000 PLAM library containing the - loadable SESAM driver modules. - Required for using SESAM functions. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_oml $.SYSLNK.SESAM-SQL.030</programlisting> - </informalexample> - </para> - </entry> - </row> - <row> - <entry><literal>php3_sesam_configfile</literal></entry> - <entry>Name of SESAM application configuration file. - Required for using SESAM functions. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_configfile $SESAM.SESAM.CONF.AW</programlisting></informalexample> - It will usually contain a configuration like (see SESAM - reference manual): - <informalexample> - <programlisting role="bs2000"> + <entry><literal>php3_sesam_oml</literal></entry> + <entry> + Name of BS2000 PLAM library containing the loadable SESAM + driver modules. Required for using SESAM functions. + <para> + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_oml $.SYSLNK.SESAM-SQL.030 + </programlisting> + </informalexample> + </para> + </entry> + </row> + <row> + <entry><literal>php3_sesam_configfile</literal></entry> + <entry>Name of SESAM application configuration file. + Required for using SESAM functions. + <para> + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_configfile $SESAM.SESAM.CONF.AW + </programlisting> + </informalexample> + It will usually contain a configuration like (see SESAM reference + manual): + <informalexample> + <programlisting role="bs2000"> CNF=B NAM=K -NOTYPE</programlisting> - </informalexample> - </para> - </entry> - </row> - <row> - <entry><literal>php3_sesam_messagecatalog</literal></entry> - <entry>Name of SESAM message catalog file. - In most cases, this directive is not neccessary. Only if the - SESAM message file is not installed in the system's BS2000 - message file table, it can be set with this directive. - <para> - Example: - <informalexample> - <programlisting role="apache"> -php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030</programlisting> - </informalexample> - </para> - </entry> - </row> - </tbody> - </tgroup> - </table> +NOTYPE + </programlisting> + </informalexample> </para> + </entry> + </row> + <row> + <entry><literal>php3_sesam_messagecatalog</literal></entry> + <entry> + Name of SESAM message catalog file. In most cases, this + directive is not neccessary. Only if the SESAM message file is + not installed in the system's BS2000 message file table, it can + be set with this directive. <para> - In addition to the configuration of the PHP/SESAM interface, - you have to configure the SESAM-Database server itself on your + Example: + <informalexample> + <programlisting role="apache"> +php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030 + </programlisting> + </informalexample> + </para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para> + In addition to the configuration of the PHP/SESAM interface, you + have to configure the SESAM-Database server itself on your mainframe as usual. That means: <itemizedlist> - <listitem><simpara>starting the SESAM database handler (DBH), and</simpara></listitem> - <listitem><simpara>connecting the databases with the SESAM database - handler</simpara></listitem> + <listitem> + <simpara> + starting the SESAM database handler (DBH), and + </simpara> + </listitem> + <listitem> + <simpara> + connecting the databases with the SESAM database handler + </simpara> + </listitem> </itemizedlist> </para> <para> @@ -117,28 +141,28 @@ </para> <para> The communication between PHP (running in the POSIX subsystem) - and the database handler (running outside the POSIX subsystem) - is realized by a special driver module called SQLSCI and SESAM - connection modules using common memory. - Because of the common memory access, and because PHP is a - static part of the web server, database accesses are very fast, - as they do not require remote accesses via ODBC, JDBC or UTM. + and the database handler (running outside the POSIX subsystem) is + realized by a special driver module called SQLSCI and SESAM + connection modules using common memory. Because of the common + memory access, and because PHP is a static part of the web + server, database accesses are very fast, as they do not require + remote accesses via ODBC, JDBC or UTM. </para> <para> Only a small stub loader (SESMOD) is linked with PHP, and the SESAM connection modules are pulled in from SESAM's OML PLAM library. In the <link - linkend="ini.sect.sesam">configuration</link>, you must tell - PHP the name of this PLAM library, and the file link to use for - the SESAM configuration file (As of SESAM V3.0, SQLSCI is - available in the SESAM Tool Library, which is part of the - standard distribution). + linkend="ini.sect.sesam">configuration</link>, you must tell PHP + the name of this PLAM library, and the file link to use for the + SESAM configuration file (As of SESAM V3.0, SQLSCI is available + in the SESAM Tool Library, which is part of the standard + distribution). </para> <para> Because the SQL command quoting for single quotes uses duplicated single quotes (as opposed to a single quote preceded by a - backslash, used in some other databases), it is advisable to - set the PHP configuration directives <link + backslash, used in some other databases), it is advisable to set + the PHP configuration directives <link linkend="ini.magic-quotes-gpc"><literal>php3_magic_quotes_gpc</literal></link> and <link linkend="ini.magic-quotes-sybase"><literal>php3_magic_quotes_sybase</literal></link> @@ -149,88 +173,91 @@ <note> <title>Runtime considerations</title> <para> - Because of limitations of the BS2000 process model, the driver can - be loaded only after the Apache server has forked off its server child - processes. This will slightly slow down the initial SESAM request - of each child, but subsequent accesses will respond at full speed. + Because of limitations of the BS2000 process model, the driver + can be loaded only after the Apache server has forked off its + server child processes. This will slightly slow down the initial + SESAM request of each child, but subsequent accesses will respond + at full speed. </para> <para> When explicitly defining a Message Catalog for SESAM, that catalog will be loaded each time the driver is loaded (i.e., at - the initial SESAM request). The BS2000 operating system prints - a message after successful load of the message catalog, which - will be sent to Apache's error_log file. BS2000 currently does - not allow suppression of this message, it will slowly fill up - the log. + the initial SESAM request). The BS2000 operating system prints a + message after successful load of the message catalog, which will + be sent to Apache's error_log file. BS2000 currently does not + allow suppression of this message, it will slowly fill up the + log. </para> <para> - Make sure that the SESAM OML PLAM library and SESAM - configuration file are readable by the user id running the web server. - Otherwise, the server will be unable to load the driver, and - will not allow to call any SESAM functions. Also, access to - the database must be granted to the user id under which the - Apache server is running. Otherwise, connections to the - SESAM database handler will fail. + Make sure that the SESAM OML PLAM library and SESAM configuration + file are readable by the user id running the web server. + Otherwise, the server will be unable to load the driver, and will + not allow to call any SESAM functions. Also, access to the + database must be granted to the user id under which the Apache + server is running. Otherwise, connections to the SESAM database + handler will fail. </para> </note> <note> <title>Cursor Types</title> <para> The result cursors which are allocated for SQL "select type" - queries can be either "sequential" or "scrollable". Because - of the larger memory overhead needed by "scrollable" cursors, - the default is "sequential". + queries can be either "sequential" or "scrollable". Because of + the larger memory overhead needed by "scrollable" cursors, the + default is "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>. When fetching a row - using a "scrollable" cursor, the following post-processing is - done for the global default values for the scrolling type - and scrolling offset: + 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>. When fetching a + row using a "scrollable" cursor, the following post-processing is + done for the global default values for the scrolling type and + scrolling offset: <table> <title>Scrolled Cursor Post-Processing</title> <tgroup cols="2"> <thead> <row> - <entry>Scroll Type</entry> - <entry>Action</entry> + <entry>Scroll Type</entry> + <entry>Action</entry> </row> </thead> <tbody> <row> - <entry><literal>SESAM_SEEK_NEXT</literal></entry> - <entry>none</entry> + <entry><literal>SESAM_SEEK_NEXT</literal></entry> + <entry>none</entry> </row> <row> - <entry><literal>SESAM_SEEK_PRIOR</literal></entry> - <entry>none</entry> + <entry><literal>SESAM_SEEK_PRIOR</literal></entry> + <entry>none</entry> </row> <row> - <entry><literal>SESAM_SEEK_FIRST</literal></entry> - <entry>set scroll type to - <literal>SESAM_SEEK_NEXT</literal></entry> + <entry><literal>SESAM_SEEK_FIRST</literal></entry> + <entry> + set scroll type to <literal>SESAM_SEEK_NEXT</literal> + </entry> </row> <row> - <entry><literal>SESAM_SEEK_LAST</literal></entry> - <entry>set scroll type to - <literal>SESAM_SEEK_PRIOR</literal></entry> + <entry><literal>SESAM_SEEK_LAST</literal></entry> + <entry> + set scroll type to <literal>SESAM_SEEK_PRIOR</literal> + </entry> </row> <row> - <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry> - <entry>Auto-Increment internal offset value</entry> + <entry><literal>SESAM_SEEK_ABSOLUTE</literal></entry> + <entry>Auto-Increment internal offset value</entry> </row> <row> - <entry><literal>SESAM_SEEK_RELATIVE</literal></entry> - <entry>none. (maintain global default - <parameter>offset</parameter> value, which allows - for, e.g., fetching each 10th row backwards) - </entry> + <entry><literal>SESAM_SEEK_RELATIVE</literal></entry> + <entry>none. (maintain global default + <parameter> + offset</parameter> value, which allows for, e.g., fetching + each 10th row backwards) + </entry> </row> </tbody> </tgroup> @@ -244,29 +271,29 @@ <para> Because in the PHP world it is natural to start indexes at zero (rather than 1), some adaptions have been made to the SESAM - interface: whenever an indexed array is starting with index 1 - in the native SESAM interface, the PHP interface uses - index 0 as a starting point. E.g., when retrieving columns with + interface: whenever an indexed array is starting with index 1 in + the native SESAM interface, the PHP interface uses index 0 as a + starting point. E.g., when retrieving columns with <function>sesam_fetch_row</function>, the first column has the index 0, and the subsequent columns have indexes up to (but not - including) the column count ($array["count"]). - When porting SESAM applications from other high level languages - to PHP, be aware of this changed interface. Where appropriate, - the description of the respective php sesam functions include a - note that the index is zero based. + including) the column count ($array["count"]). When porting + SESAM applications from other high level languages to PHP, be + aware of this changed interface. Where appropriate, the + description of the respective php sesam functions include a note + that the index is zero based. </para> </note> <note> <title>Security concerns</title> <para> - When allowing access to the SESAM databases, the web server - user should only have as little privileges as possible. For most + When allowing access to the SESAM databases, the web server user + should only have as little privileges as possible. For most databases, only read access privilege should be granted. - Depending on your usage scenario, add more access rights as - you see fit. Never allow full control to any database for - any user from the 'net! Restrict access to php scripts - which must administer the database by using password control - and/or SSL security. + Depending on your usage scenario, add more access rights as you + see fit. Never allow full control to any database for any user + from the 'net! Restrict access to php scripts which must + administer the database by using password control and/or SSL + security. </para> </note> <note> @@ -279,21 +306,26 @@ <itemizedlist> <listitem> <simpara>Vendor specific data types</simpara> - <simpara>Some vendor specific data types may have to be - replaced by standard SQL data types - (e.g., <literal>TEXT</literal> could be replaced by - <literal>VARCHAR(max. size)</literal>). - </simpara> + <simpara> + Some vendor specific data types may have to be replaced by + standard SQL data types (e.g., <literal>TEXT</literal> could + be replaced by <literal>VARCHAR(max. size)</literal>). + </simpara> </listitem> <listitem> <simpara>Keywords as SQL identifiers</simpara> - <simpara>In SESAM (as in standard SQL), such identifiers must - be enclosed in double quotes (or renamed).</simpara> + <simpara> + In SESAM (as in standard SQL), such identifiers must be + enclosed in double quotes (or renamed). + </simpara> </listitem> <listitem> - <simpara>Display length in data types</simpara> - <simpara>SESAM data types have a precision, not a display - length. Instead of <literal>int(4)</literal> (intended use: + <simpara> + Display length in data types + </simpara> + <simpara> + SESAM data types have a precision, not a display + length. Instead of <literal>int(4)</literal> (intended use: integers up to '9999'), SESAM requires simply <literal>int</literal> for an implied size of 31 bits. Also, the only datetime data types available in SESAM are: @@ -302,50 +334,60 @@ </simpara> </listitem> <listitem> - <simpara>SQL types with vendor-specific - <literal>unsigned</literal>, <literal>zerofill</literal>, or - <literal>auto_increment</literal> attributes</simpara> - <simpara><literal>Unsigned</literal> and<literal> - zerofill</literal> are not supported. - <literal>Auto_increment</literal> is automatic (use <literal>"INSERT ... - VALUES(*, ...)"</literal> instead of <literal>"... VALUES(0, - ...)"</literal> to take advantage of SESAM-implied - auto-increment. </simpara> - </listitem> - <listitem> - <simpara><command>int ... DEFAULT '0000'</command></simpara> - <simpara>Numeric variables must not be initialized with - string constants. Use <command>DEFAULT 0</command> - instead. To initialize variables of the datetime - SQL data types, the initialization string must be - prefixed with the respective type keyword, as in: - <literal> CREATE TABLE exmpl ( - xtime timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT &null; - ); </literal> + <simpara> + SQL types with vendor-specific <literal>unsigned</literal>, + <literal>zerofill</literal>, or + <literal>auto_increment</literal> attributes + </simpara> + <simpara> + <literal>Unsigned</literal> and<literal> zerofill</literal> + are not supported. <literal>Auto_increment</literal> is + automatic (use <literal>"INSERT ... VALUES(*, ...)"</literal> + instead of <literal>"... VALUES(0, ...)"</literal> to take + advantage of SESAM-implied auto-increment. </simpara> </listitem> <listitem> - <simpara><command>$count = xxxx_num_rows();</command></simpara> - <simpara>Some databases promise to guess/estimate the - number of the rows in a query result, even though - the returned value is grossly incorrect. SESAM - does not know the number of rows in a query result - before actually fetching them. If you REALLY need - the count, try <command>SELECT COUNT(...) WHERE - ...</command>, it will tell you the number of hits. - A second query will (hopefully) return the results. + <simpara> + <command>int ... DEFAULT '0000'</command> + </simpara> + <simpara> + Numeric variables must not be initialized with string + constants. Use <command>DEFAULT 0</command> instead. To + initialize variables of the datetime SQL data types, the + initialization string must be prefixed with the respective + type keyword, as in: <literal> CREATE TABLE exmpl ( xtime + timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT + &null; ); </literal> </simpara> </listitem> <listitem> - <simpara><command>DROP TABLE thename;</command></simpara> - <simpara>In SESAM, in the <command>DROP TABLE</command> - command, the table name must be either followed by - the keyword <literal>RESTRICT</literal> or - <literal>CASCADE</literal>. When specifying - <literal>RESTRICT</literal>, an error is returned if - there are dependent objects (e.g., VIEWs), while with - <literal>CASCADE</literal>, dependent objects will be - deleted along with the specified table. + <simpara> + <command>$count = xxxx_num_rows();</command> + </simpara> + <simpara> + Some databases promise to guess/estimate the number of the + rows in a query result, even though the returned value is + grossly incorrect. SESAM does not know the number of rows in + a query result before actually fetching them. If you REALLY + need the count, try <command>SELECT COUNT(...) WHERE + ...</command>, it will tell you the number of hits. A second + query will (hopefully) return the results. + </simpara> + </listitem> + <listitem> + <simpara> + <command>DROP TABLE thename;</command> + </simpara> + <simpara> + In SESAM, in the <command>DROP TABLE</command> command, the + table name must be either followed by the keyword + <literal>RESTRICT</literal> or + <literal>CASCADE</literal>. When specifying + <literal>RESTRICT</literal>, an error is returned if there are + dependent objects (e.g., VIEWs), while with + <literal>CASCADE</literal>, dependent objects will be deleted + along with the specified table. </simpara> </listitem> </itemizedlist> @@ -356,8 +398,8 @@ Notes on the use of various SQL types </title> <para> - SESAM does not currently support the BLOB type. A future - version of SESAM will have support for BLOB. + SESAM does not currently support the BLOB type. A future version + of SESAM will have support for BLOB. </para> <para> At the PHP interface, the following type conversions are @@ -367,38 +409,37 @@ <tgroup cols="2"> <thead> <row> - <entry>SQL Type</entry> - <entry>PHP Type</entry> + <entry>SQL Type</entry> + <entry>PHP Type</entry> </row> </thead> <tbody> <row> - <entry>SMALLINT, INTEGER</entry> - <entry>"integer"</entry> + <entry>SMALLINT, INTEGER</entry> + <entry>"integer"</entry> </row> <row> - <entry>NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE</entry> - <entry>"double"</entry> + <entry>NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE</entry> + <entry>"double"</entry> </row> <row> - <entry>DATE, TIME, TIMESTAMP</entry> - <entry>"string"</entry> + <entry>DATE, TIME, TIMESTAMP</entry> + <entry>"string"</entry> </row> <row> - <entry>VARCHAR, CHARACTER</entry> - <entry>"string"</entry> + <entry>VARCHAR, CHARACTER</entry> + <entry>"string"</entry> </row> </tbody> </tgroup> </table> When retrieving a complete row, the result is returned as an - array. Empty fields are not filled in, so you will have to - check for the existence of the individual fields yourself - (use <function>isset</function> or - <function>empty</function> to test for empty fields). - That allows more user control over the appearance of empty - fields (than in the case of an empty string as the - representation of an empty field). + array. Empty fields are not filled in, so you will have to check + for the existence of the individual fields yourself (use + <function>isset</function> or <function>empty</function> to test + for empty fields). That allows more user control over the + appearance of empty fields (than in the case of an empty string + as the representation of an empty field). </para> </note> <note> @@ -410,10 +451,9 @@ <example> <title>Creating a "multiple field" column</title> <programlisting role="sesam"> -CREATE TABLE multi_field_test -( - pkey CHAR(20) PRIMARY KEY, - multi(3) CHAR(12) +CREATE TABLE multi_field_test ( + pkey CHAR(20) PRIMARY KEY, + multi(3) CHAR(12) ) </programlisting> </example> @@ -421,28 +461,28 @@ <example> <title>Filling a "multiple field" column</title> <programlisting role="sesam"> -INSERT INTO multi_field_test ( pkey, multi(2..3) ) - VALUES ( 'Second', &lt;'first_val','second_val'&gt;) +INSERT INTO multi_field_test (pkey, multi(2..3) ) + VALUES ('Second', &lt;'first_val', 'second_val'&gt;) </programlisting> </example> - Note that (like in this case) leading empty sub-fields are ignored, - and the filled-in values are collapsed, so that in the above - example the result will appear as multi(1..2) instead of + Note that (like in this case) leading empty sub-fields are + ignored, and the filled-in values are collapsed, so that in the + above example the result will appear as multi(1..2) instead of multi(2..3). </para> <para> - When retrieving a result row, "multiple columns" are accessed like - "inlined" additional columns. In the example above, "pkey" will have - the index 0, and the three "multi(1..3)" columns will be accessible - as indices 1 through 3. + When retrieving a result row, "multiple columns" are accessed + like "inlined" additional columns. In the example above, "pkey" + will have the index 0, and the three "multi(1..3)" columns will + be accessible as indices 1 through 3. </para> </note> <para> - For specific SESAM details, please refer to - <ulink url="&url.sesam.en;">the SESAM/SQL-Server - documentation (english)</ulink> or - <ulink url="&url.sesam.de;">the SESAM/SQL-Server documentation (german)</ulink>, - both available online, or use the respective manuals. + For specific SESAM details, please refer to <ulink + url="&url.sesam.en;">the SESAM/SQL-Server documentation + (english)</ulink> or <ulink url="&url.sesam.de;">the + SESAM/SQL-Server documentation (german)</ulink>, both available + online, or use the respective manuals. </para> </partintro> @@ -455,29 +495,29 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_connect</function></funcdef> + <funcdef>bool <function>sesam_connect</function></funcdef> <paramdef>string <parameter>catalog</parameter></paramdef> <paramdef>string <parameter>schema</parameter></paramdef> <paramdef>string <parameter>user</parameter></paramdef> </funcprototype> </funcsynopsis> <para> - Returns &true; if a connection to the SESAM database was made, or - &false; on error. + 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 - "persistant" in the sense that only the very first invocation will - actually load the driver from the configured SESAM OML PLAM + "persistant" 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> + 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 @@ -486,11 +526,11 @@ <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. + <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>. @@ -498,8 +538,8 @@ <title>Connect to a SESAM database</title> <programlisting role="php"> &lt;?php -if (! sesam_connect ("mycatalog", "myschema", "otto") - die("Unable to connect to SESAM"; +if (!sesam_connect ("mycatalog", "myschema", "otto") + die("Unable to connect to SESAM"; ?&gt; </programlisting> </example> @@ -516,7 +556,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_disconnect</function></funcdef> + <funcdef>bool <function>sesam_disconnect</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -524,9 +564,9 @@ Returns: always &true;. </para> <para> - <function>sesam_disconnect</function> closes the logical link to a - SESAM database (without actually disconnecting and unloading the - driver). + <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 @@ -548,8 +588,9 @@ <title>Closing a SESAM connection</title> <programlisting role="php"> if (sesam_connect ("mycatalog", "myschema", "otto")) { -... some queries and stuff ... -sesam_disconnect(); } + ... some queries and stuff ... + sesam_disconnect(); +} </programlisting> </example> </para> @@ -565,7 +606,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_settransaction</function></funcdef> + <funcdef>bool <function>sesam_settransaction</function></funcdef> <paramdef>int <parameter>isolation_level</parameter></paramdef> <paramdef>int <parameter>read_only</parameter></paramdef> </funcprototype> @@ -580,72 +621,77 @@ 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. + 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. + <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> + <title> + Valid values for <parameter>"Isolation_Level"</parameter> + parameter + </title> <tgroup cols="3"> <thead> <row> - <entry>Value</entry> - <entry>Constant</entry> - <entry>Meaning</entry> + <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> + <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> + <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> + <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> + <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> + <title> + Valid values for <parameter>"Read_Only"</parameter> parameter + </title> <tgroup cols="3"> <thead> <row> - <entry>Value</entry> - <entry>Constant</entry> - <entry>Meaning</entry> + <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> + <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> + <entry>1</entry> + <entry><literal>SESAM_TXREAD_READONLY</literal></entry> + <entry>Read-Only</entry> </row> </tbody> </tgroup> @@ -661,7 +707,7 @@ <title>Setting SESAM transaction parameters</title> <programlisting role="php"> &lt;?php -sesam_settransaction(SESAM_TXISOL_REPEATABLE_READ, +sesam_settransaction (SESAM_TXISOL_REPEATABLE_READ, SESAM_TXREAD_READONLY); ?&gt; </programlisting> @@ -673,13 +719,15 @@ <refentry id="function.sesam-commit"> <refnamediv> <refname>sesam_commit</refname> - <refpurpose>Commit pending updates to the SESAM database</refpurpose> + <refpurpose> + Commit pending updates to the SESAM database + </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_commit</function></funcdef> + <funcdef>bool <function>sesam_commit</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -692,9 +740,9 @@ 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 + 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> @@ -707,10 +755,10 @@ <programlisting role="php"> &lt;?php if (sesam_connect ("mycatalog", "myschema", "otto")) { - if (!sesam_execimm("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)")) - die("insert failed"); - if (!sesam_commit()) - die("commit failed"); + if (!sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)")) + die("insert failed"); + if (!sesam_commit()) + die("commit failed"); } ?&gt; </programlisting> @@ -718,17 +766,19 @@ </para> </refsect1> </refentry> - + <refentry id="function.sesam-rollback"> <refnamediv> <refname>sesam_rollback</refname> - <refpurpose>Discard any pending updates to the SESAM database</refpurpose> + <refpurpose> + Discard any pending updates to the SESAM database + </refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_rollback</function></funcdef> + <funcdef>bool <function>sesam_rollback</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -737,8 +787,8 @@ &false; on errors </para> <para> - <function>sesam_rollback</function> discards any pending updates to - the database. Also affected are result cursors and result + <function>sesam_rollback</function> discards any pending updates + to the database. Also affected are result cursors and result descriptors. </para> <para> @@ -754,11 +804,11 @@ <programlisting role="php"> &lt;?php if (sesam_connect ("mycatalog", "myschema", "otto")) { - if (sesam_execimm("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)") - && sesam_execimm("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) - sesam_commit(); - else - sesam_rollback(); + if (sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)") + &amp;&amp; sesam_execimm ("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) + sesam_commit(); + else + sesam_rollback(); } ?&gt; </programlisting> @@ -766,7 +816,7 @@ </para> </refsect1> </refentry> - + <refentry id="function.sesam-execimm"> <refnamediv> <refname>sesam_execimm</refname> @@ -797,10 +847,9 @@ 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>. + 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 @@ -811,12 +860,12 @@ <para> <informalexample> <programlisting role="php"> -$stmt = "INSERT INTO mytable VALUES('one', 'two')"; +$stmt = "INSERT INTO mytable VALUES ('one', 'two')"; $result = sesam_execimm ($stmt); $err = sesam_diagnostic(); -print("sqlstate = ".$err["sqlstate"]."\n". - "Affected rows = ".$err["rowcount"]." == ". - sesam_affected_rows($result)."\n"); +print ("sqlstate = ".$err["sqlstate"]."\n". + "Affected rows = ".$err["rowcount"]." == ". + sesam_affected_rows($result)."\n"); </programlisting> </informalexample> See also: <function>sesam_query</function> and @@ -836,14 +885,14 @@ <funcprototype> <funcdef>string <function>sesam_query</function></funcdef> <paramdef>string <parameter>query</parameter></paramdef> - <paramdef>boolean + <paramdef>bool <parameter><optional>scrollable</optional></parameter> </paramdef> </funcprototype> </funcsynopsis> <para> Returns: A SESAM "result identifier" on success, or - &false; on error. + &false; on error. </para> <para> A "result_id" resource is used by other functions to retrieve the @@ -851,32 +900,31 @@ </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 + 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). 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>. + 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. + 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 @@ -887,47 +935,49 @@ </title> <programlisting role="php"> &lt;?php -if (!sesam_connect("phonedb", "demo", "otto")) - die("cannot connect"); -$result = sesam_query("select * from phone"); +if (!sesam_connect ("phonedb", "demo", "otto")) + die ("cannot connect"); +$result = sesam_query ("select * from phone"); if (!$result) { - $err = sesam_diagnostic(); - die($err["errmsg"]); + $err = sesam_diagnostic(); + die ($err["errmsg"]); } echo "&lt;TABLE BORDER&gt;\n"; // Add title header with column names above the result: -if ($cols = sesam_field_array($result)) { - echo " &lt;TR&gt;&lt;TH COLSPAN=".$cols["count"]."&gt;Result:&lt;/TH&gt;&lt;/TR&gt;\n"; - echo " &lt;TR&gt;\n"; - for ($col = 0; $col &lt; $cols["count"]; ++$col) { - $colattr = $cols[$col]; - /* Span the table head over SESAM's "Multiple Fields": */ - if ($colattr["count"] &gt; 1) { - echo " &lt;TH COLSPAN=".$colattr["count"]."&gt;".$colattr["name"]. - "(1..".$colattr["count"].")&lt;/TH&gt;\n"; - $col += $colattr["count"] - 1; +if ($cols = sesam_field_array ($result)) { + echo " &lt;TR&gt;&lt;TH COLSPAN=".$cols["count"]."&gt;Result:&lt;/TH&gt;&lt;/TR&gt;\n"; + echo " &lt;TR&gt;\n"; + for ($col = 0; $col &lt; $cols["count"]; ++$col) { + $colattr = $cols[$col]; + /* Span the table head over SESAM's "Multiple Fields": */ + if ($colattr["count"] &gt; 1) { + echo " &lt;TH COLSPAN=".$colattr["count"]."&gt;".$colattr["name"]. + "(1..".$colattr["count"].")&lt;/TH&gt;\n"; + $col += $colattr["count"] - 1; + } else + echo " &lt;TH&gt;" . $colattr["name"] . "&lt;/TH&gt;\n"; } - else - echo " &lt;TH&gt;" . $colattr["name"] . "&lt;/TH&gt;\n"; - } - echo " &lt;/TR&gt;\n"; + echo " &lt;/TR&gt;\n"; } do { - // Fetch the result in chunks of 100 rows max. - $ok = sesam_fetch_result($result,100); - for ($row=0; $row &lt; $ok["rows"]; ++$row) { - echo " &lt;TR&gt;\n"; - for ($col = 0; $col &lt; $ok["cols"]; ++$col) { - if (isset($ok[$col][$row])) - echo " &lt;TD&gt;" . $ok[$col][$row] . "&lt;/TD&gt;\n"; - else - echo " &lt;TD&gt;-empty-&lt;/TD&gt;\n"; + // Fetch the result in chunks of 100 rows max. + $ok = sesam_fetch_result ($result, 100); + for ($row=0; $row &lt; $ok["rows"]; ++$row) { + echo " &lt;TR&gt;\n"; + for ($col = 0; $col &lt; $ok["cols"]; ++$col) { + if (isset($ok[$col][$row])) + echo " &lt;TD&gt;" . $ok[$col][$row] . "&lt;/TD&gt;\n"; + } else { + echo " &lt;TD&gt;-empty-&lt;/TD&gt;\n"; + } + } + echo " &lt;/TR&gt;\n"; } - echo " &lt;/TR&gt;\n"; - } -} while ($ok["truncated"]); // while there may be more data -echo "&lt;/TABLE&gt;\n"; +} +while ($ok["truncated"]) { // while there may be more data + echo "&lt;/TABLE&gt;\n"; +} // free result id sesam_free_result($result); ?&gt; @@ -940,7 +990,9 @@ <refentry id="function.sesam-num-fields"> <refnamediv> <refname>sesam_num_fields</refname> - <refpurpose>Return the number of fields/columns in a result set</refpurpose> + <refpurpose> + Return the number of fields/columns in a result set + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -951,12 +1003,12 @@ </funcprototype> </funcsynopsis> <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. + 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 @@ -995,9 +1047,11 @@ 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> + <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 @@ -1009,7 +1063,9 @@ <refentry id="function.sesam-diagnostic"> <refnamediv> <refname>sesam_diagnostic</refname> - <refpurpose>Return status information for last SESAM call</refpurpose> + <refpurpose> + Return status information for last SESAM call + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1021,8 +1077,7 @@ </funcsynopsis> <para> Returns an associative array of status and return codes for the - last SQL query/statement/command. - Elements of the array are: + last SQL query/statement/command. Elements of the array are: <table> <title> Status information returned by <function>sesam_diagnostic</function> @@ -1030,39 +1085,45 @@ <tgroup cols="2"> <thead> <row> - <entry>Element</entry> - <entry>Contents</entry> + <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> + <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> @@ -1079,74 +1140,72 @@ // Function which prints a formatted error message, // displaying a pointer to the syntax error in the // SQL statement -function PrintReturncode($exec_str) -{ - $err = Sesam_Diagnostic(); - $colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount - if ($err["errlin"] == -1) - --$colspan; - if ($err["errcol"] == -1) - --$colspan; - if ($err["rowcount"] == 0) - --$colspan; - echo "&lt;TABLE BORDER&gt;\n"; - echo "&lt;TR&gt;&lt;TH COLSPAN=".$colspan."&gt;&lt;FONT COLOR=red&gt;ERROR:&lt;/FONT&gt; ". +function PrintReturncode ($exec_str) { + $err = Sesam_Diagnostic(); + $colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount + if ($err["errlin"] == -1) + --$colspan; + if ($err["errcol"] == -1) + --$colspan; + if ($err["rowcount"] == 0) + --$colspan; + echo "&lt;TABLE BORDER&gt;\n"; + echo "&lt;TR&gt;&lt;TH COLSPAN=".$colspan."&gt;&lt;FONT COLOR=red&gt;ERROR:&lt;/FONT&gt; ". htmlspecialchars($err["errmsg"])."&lt;/TH&gt;&lt;/TR&gt;\n"; - if ($err["errcol"] &gt;= 0) { - echo "&lt;TR&gt;&lt;TD COLSPAN=".$colspan."&gt;&lt;PRE&gt;\n"; - $errstmt = $exec_str."\n"; - for ($lin=0; $errstmt != ""; ++$lin) { - if ($lin != $err["errlin"]) { // $lin is less or greater than errlin - if (! ($i = strchr($errstmt, "\n"))) - $i = ""; - $line = substr($errstmt, 0, strlen($errstmt)-strlen($i)+1); - $errstmt = substr($i, 1); - if ($line != "\n") - print htmlspecialchars($line); - } - else { - if (! ($i = strchr($errstmt, "\n"))) - $i = ""; - $line = substr($errstmt, 0, strlen($errstmt)-strlen($i)+1); - $errstmt = substr($i, 1); - for ($col=0; $col &lt; $err["errcol"]; ++$col) - echo (substr($line, $col, 1) == "\t") ? "\t" : "."; - echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;\\&lt;/BLINK&gt;&lt;/FONT&gt;\n"; - print "&lt;FONT COLOR=\"#880000\"&gt;".htmlspecialchars($line)."&lt;/FONT&gt;"; - for ($col=0; $col &lt; $err["errcol"]; ++$col) - echo (substr($line, $col, 1) == "\t") ? "\t" : "."; - echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;/&lt;/BLINK&gt;&lt;/FONT&gt;\n"; - } - } - echo "&lt;/PRE&gt;&lt;/TD&gt;&lt;/TR&gt;\n"; - } - echo "&lt;TR&gt;\n"; - echo " &lt;TD&gt;sqlstate=" . $err["sqlstate"] . "&lt;/TD&gt;\n"; - if ($err["errlin"] != -1) - echo " &lt;TD&gt;errlin=" . $err["errlin"] . "&lt;/TD&gt;\n"; - if ($err["errcol"] != -1) - echo " &lt;TD&gt;errcol=" . $err["errcol"] . "&lt;/TD&gt;\n"; - if ($err["rowcount"] != 0) - echo " &lt;TD&gt;rowcount=" . $err["rowcount"] . "&lt;/TD&gt;\n"; - echo "&lt;/TR&gt;\n"; - echo "&lt;/TABLE&gt;\n"; + if ($err["errcol"] &gt;= 0) { + echo "&lt;TR&gt;&lt;TD COLSPAN=".$colspan."&gt;&lt;PRE&gt;\n"; + $errstmt = $exec_str."\n"; + for ($lin=0; $errstmt != ""; ++$lin) { + if ($lin != $err["errlin"]) { // $lin is less or greater than errlin + if (!($i = strchr ($errstmt, "\n"))) + $i = ""; + $line = substr ($errstmt, 0, strlen($errstmt)-strlen($i)+1); + $errstmt = substr($i, 1); + if ($line != "\n") + print htmlspecialchars ($line); + } else { + if (! ($i = strchr ($errstmt, "\n"))) + $i = ""; + $line = substr ($errstmt, 0, strlen ($errstmt)-strlen($i)+1); + $errstmt = substr($i, 1); + for ($col=0; $col &lt; $err["errcol"]; ++$col) + echo (substr($line, $col, 1) == "\t") ? "\t" : "."; + echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;\\&lt;/BLINK&gt;&lt;/FONT&gt;\n"; + print "&lt;FONT COLOR=\"#880000\"&gt;".htmlspecialchars($line)."&lt;/FONT&gt;"; + for ($col=0; $col &lt; $err["errcol"]; ++$col) + echo (substr ($line, $col, 1) == "\t") ? "\t" : "."; + echo "&lt;FONT COLOR=RED&gt;&lt;BLINK&gt;/&lt;/BLINK&gt;&lt;/FONT&gt;\n"; + } + } + echo "&lt;/PRE&gt;&lt;/TD&gt;&lt;/TR&gt;\n"; + } + echo "&lt;TR&gt;\n"; + echo " &lt;TD&gt;sqlstate=" . $err["sqlstate"] . "&lt;/TD&gt;\n"; + if ($err["errlin"] != -1) + echo " &lt;TD&gt;errlin=" . $err["errlin"] . "&lt;/TD&gt;\n"; + if ($err["errcol"] != -1) + echo " &lt;TD&gt;errcol=" . $err["errcol"] . "&lt;/TD&gt;\n"; + if ($err["rowcount"] != 0) + echo " &lt;TD&gt;rowcount=" . $err["rowcount"] . "&lt;/TD&gt;\n"; + echo "&lt;/TR&gt;\n"; + echo "&lt;/TABLE&gt;\n"; } -if (!sesam_connect("mycatalog", "phoneno", "otto")) - die("cannot connect"); +if (!sesam_connect ("mycatalog", "phoneno", "otto")) + die ("cannot connect"); $stmt = "SELECT * FROM phone\n". - " WHERE@ LASTNAME='KRAEMER'\n". - " ORDER BY FIRSTNAME"; -if (! ($result = sesam_query($stmt))) - PrintReturncode($stmt); + " WHERE@ LASTNAME='KRAEMER'\n". + " ORDER BY FIRSTNAME"; +if (!($result = sesam_query ($stmt))) + PrintReturncode ($stmt); ?&gt; </programlisting> </example> </para> <para> - See also: <function>sesam_errormsg</function> for simple access to the - error string only + See also: <function>sesam_errormsg</function> for simple access + to the error string only </para> </refsect1> </refentry> @@ -1180,48 +1239,54 @@ <tgroup cols="2"> <thead> <row> - <entry>Array Element</entry> - <entry>Contents</entry> + <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>boolean $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> + <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>boolean $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> + <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> @@ -1245,7 +1310,9 @@ <refentry id="function.sesam-affected-rows"> <refnamediv> <refname>sesam_affected_rows</refname> - <refpurpose>Get number of rows affected by an immediate query</refpurpose> + <refpurpose> + Get number of rows affected by an immediate query + </refpurpose> </refnamediv> <refsect1> <title>Description</title> @@ -1263,29 +1330,29 @@ </para> <para> Returns the number of rows affected by a query associated with - <parameter>result_id</parameter>. + <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. + 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> See also: <function>sesam_query</function> and - <function>sesam_execimm</function> + <function>sesam_execimm</function> </para> - <informalexample> - <programlisting role="php"> -$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper($name)."'"); -if (! $result) { + <informalexample> + <programlisting role="php"> +$result = sesam_execimm ("DELETE FROM PHONE WHERE LASTNAME = '".strtoupper ($name)."'"); +if (!$result) { ... error ... } -print sesam_affected_rows($result). - " entries with last name ".$name." deleted.\n" +print sesam_affected_rows ($result). + " entries with last name ".$name." deleted.\n" </programlisting> </informalexample> </refsect1> @@ -1305,13 +1372,13 @@ </funcprototype> </funcsynopsis> <para> - Returns the SESAM error message associated with the most - recent SESAM error. + Returns the SESAM error message associated with the most recent + SESAM error. </para> <informalexample> <programlisting role="php"> -if (!sesam_execimm($stmt)) - printf("%s&lt;br&gt;\n", sesam_errormsg()); +if (!sesam_execimm ($stmt)) + printf ("%s&lt;br&gt;\n", sesam_errormsg()); </programlisting> </informalexample> <para> @@ -1342,8 +1409,9 @@ </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>. + (column name, type, precision, ...) about individual columns of + the result after the query associated with + <parameter>result_id</parameter>. </para> <para> <table> @@ -1353,164 +1421,160 @@ <tgroup cols="2"> <thead> <row> - <entry>Array Element</entry> - <entry>Contents</entry> + <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> + <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>"integer"</simpara> - </listitem> - <listitem> - <simpara>"double"</simpara> - </listitem> - <listitem> - <simpara>"string"</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> + <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>"integer"</simpara> + </listitem> + <listitem> + <simpara>"double"</simpara> + </listitem> + <listitem> + <simpara>"string"</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 the <function>sesam_query</function> function - for an example of the <function>sesam_field_array</function> use. + See the <function>sesam_query</function> function for an example + of the <function>sesam_field_array</function> use. </para> </refsect1> </refentry> @@ -1535,14 +1599,14 @@ </funcprototype> </funcsynopsis> <para> - Returns an array that corresponds to the fetched row, - or &false; if there are no more rows. + 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 + <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 + 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> @@ -1550,62 +1614,71 @@ <function>sesam_query</function> (select type queries only!). </para> <para> - <parameter><optional>whence</optional></parameter> is an - optional parameter for a fetch operation on "scrollable" - cursors, which can be set to the following predefined - constants: + <parameter><optional>whence</optional></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> + <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> + <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> @@ -1615,40 +1688,38 @@ <para> When using "scrollable" cursors, the cursor can be freely positioned on the result set. If the - <parameter><optional>whence</optional></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><optional>whence</optional></parameter> is - supplied, its value replaces the global default. - </para> - <para> - <parameter><optional>offset</optional></parameter> is an - optional parameter which is only evaluated (and required) - if <parameter><optional>whence</optional></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 - 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 + <parameter><optional>whence</optional></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><optional>whence</optional></parameter> is supplied, + its value replaces the global default. + </para> + <para> + <parameter><optional>offset</optional></parameter> is an optional + parameter which is only evaluated (and required) if + <parameter><optional>whence</optional></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 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. </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. + 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> @@ -1657,16 +1728,16 @@ $result = sesam_query (&quot;SELECT * FROM phone\n&quot;. &quot; WHERE LASTNAME='&quot;.strtoupper($name).&quot;'\n&quot;. &quot; ORDER BY FIRSTNAME&quot;, 1); -if (! $result) { +if (!$result) { ... error ... } // print the table in backward order print &quot;&lt;TABLE BORDER&gt;\n&quot;; $row = sesam_fetch_row ($result, SESAM_SEEK_LAST); -while (is_array($row)) { +while (is_array ($row)) { print &quot; &lt;TR&gt;\n&quot;; - for($col = 0; $col &lt; $row[&quot;count&quot;]; ++$col) { - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[$col]).&quot;&lt;/TD&gt;\n&quot;; + for ($col = 0; $col &lt; $row[&quot;count&quot;]; ++$col) { + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[$col]).&quot;&lt;/TD&gt;\n&quot;; } print &quot; &lt;/TR&gt;\n&quot;; // use implied SESAM_SEEK_PRIOR @@ -1678,8 +1749,8 @@ </programlisting> </example> <para> - See also: <function>sesam_fetch_array</function> which returns - an associative array, and <function>sesam_fetch_result</function> + 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> @@ -1705,15 +1776,14 @@ </funcprototype> </funcsynopsis> <para> - Returns an array that corresponds to the fetched row, - or &false; if there are no more rows. + 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. + <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 @@ -1722,25 +1792,23 @@ <para> For the valid values of the optional <parameter><optional>whence</optional></parameter>and - <parameter><optional>offset</optional></parameter> - parameters, see the <function>sesam_fetch_row</function> - function for details. + <parameter><optional>offset</optional></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. - + <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 + 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> @@ -1748,30 +1816,29 @@ </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: + 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"> -CREATE TABLE ... ( ... MULTI(3) INT )</programlisting> +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. + <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. + 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> @@ -1780,16 +1847,16 @@ $result = sesam_query (&quot;SELECT * FROM phone\n&quot;. &quot; WHERE LASTNAME='&quot;.strtoupper($name).&quot;'\n&quot;. &quot; ORDER BY FIRSTNAME&quot;, 1); -if (! $result) { +if (!$result) { ... error ... } // print the table: print &quot;&lt;TABLE BORDER&gt;\n&quot;; -while (($row = sesam_fetch_array ($result)) && count($row) &gt; 0) { +while (($row = sesam_fetch_array ($result)) &amp;&amp; count ($row) &gt; 0) { print &quot; &lt;TR&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;firstname&quot;]).&quot;&lt;/TD&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;lastname&quot;]).&quot;&lt;/TD&gt;\n&quot;; - print &quot; &lt;TD&gt;&quot;.htmlspecialchars($row[&quot;phoneno&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;firstname&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;lastname&quot;]).&quot;&lt;/TD&gt;\n&quot;; + print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;phoneno&quot;]).&quot;&lt;/TD&gt;\n&quot;; print &quot; &lt;/TR&gt;\n&quot;; } print &quot;&lt;/TABLE&gt;\n&quot;; @@ -1798,8 +1865,8 @@ </programlisting> </example> <para> - See also: <function>sesam_fetch_row</function> which returns - an indexed array. + See also: <function>sesam_fetch_row</function> which returns an + indexed array. </para> </refsect1> </refentry> @@ -1815,7 +1882,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_seek_row</function></funcdef> + <funcdef>bool <function>sesam_seek_row</function></funcdef> <paramdef>string <parameter>result_id</parameter></paramdef> <paramdef>int <parameter>whence</parameter></paramdef> <paramdef>int @@ -1829,74 +1896,78 @@ 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: + <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> + <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>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> + <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><optional>offset</optional></parameter> is an - optional parameter which is only evaluated (and required) - if <parameter>whence</parameter> is - either <literal>SESAM_SEEK_RELATIVE</literal> or + <parameter><optional>offset</optional></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> @@ -1923,7 +1994,6 @@ </refsect1> </refentry> </reference> - <!-- Keep this comment at the end of the file Local variables: Index: phpdoc/kr/functions/sesam.xml diff -u phpdoc/kr/functions/sesam.xml:1.3 phpdoc/kr/functions/sesam.xml:1.4 --- phpdoc/kr/functions/sesam.xml:1.3 Sat Jul 7 18:26:18 2001 +++ phpdoc/kr/functions/sesam.xml Tue Jul 24 10:35:41 2001 @@ -495,7 +495,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_connect</function></funcdef> + <funcdef>bool <function>sesam_connect</function></funcdef> <paramdef>string <parameter>catalog</parameter></paramdef> <paramdef>string <parameter>schema</parameter></paramdef> <paramdef>string <parameter>user</parameter></paramdef> @@ -556,7 +556,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_disconnect</function></funcdef> + <funcdef>bool <function>sesam_disconnect</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -606,7 +606,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_settransaction</function></funcdef> + <funcdef>bool <function>sesam_settransaction</function></funcdef> <paramdef>int <parameter>isolation_level</parameter></paramdef> <paramdef>int <parameter>read_only</parameter></paramdef> </funcprototype> @@ -727,7 +727,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_commit</function></funcdef> + <funcdef>bool <function>sesam_commit</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -778,7 +778,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_rollback</function></funcdef> + <funcdef>bool <function>sesam_rollback</function></funcdef> <void/> </funcprototype> </funcsynopsis> @@ -805,7 +805,7 @@ &lt;?php if (sesam_connect ("mycatalog", "myschema", "otto")) { if (sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', &lt;0, 8, 15&gt;)") - && sesam_execimm ("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) + &amp;&amp; sesam_execimm ("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) sesam_commit(); else sesam_rollback(); @@ -885,7 +885,7 @@ <funcprototype> <funcdef>string <function>sesam_query</function></funcdef> <paramdef>string <parameter>query</parameter></paramdef> - <paramdef>boolean + <paramdef>bool <parameter><optional>scrollable</optional></parameter> </paramdef> </funcprototype> @@ -1852,7 +1852,7 @@ } // print the table: print &quot;&lt;TABLE BORDER&gt;\n&quot;; -while (($row = sesam_fetch_array ($result)) && count ($row) &gt; 0) { +while (($row = sesam_fetch_array ($result)) &amp;&amp; count ($row) &gt; 0) { print &quot; &lt;TR&gt;\n&quot;; print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;firstname&quot;]).&quot;&lt;/TD&gt;\n&quot;; print &quot; &lt;TD&gt;&quot;.htmlspecialchars ($row[&quot;lastname&quot;]).&quot;&lt;/TD&gt;\n&quot;; @@ -1882,7 +1882,7 @@ <title>Description</title> <funcsynopsis> <funcprototype> - <funcdef>boolean <function>sesam_seek_row</function></funcdef> + <funcdef>bool <function>sesam_seek_row</function></funcdef> <paramdef>string <parameter>result_id</parameter></paramdef> <paramdef>int <parameter>whence</parameter></paramdef> <paramdef>int
« previous php.doc (#969336481) next »