cvs: phpdoc /en/functions fbsql.xml

fmk Wed Oct 17 14:35:36 2001 EDT Modified files: /phpdoc/en/functions fbsql.xml Log: Documentation for fbsql_read_blob() fbsql_read_clob() fbsql_set_lob_mode()

Index: phpdoc/en/functions/fbsql.xml diff -u phpdoc/en/functions/fbsql.xml:1.27 phpdoc/en/functions/fbsql.xml:1.28 --- phpdoc/en/functions/fbsql.xml:1.27 Wed Oct 10 18:23:17 2001 +++ phpdoc/en/functions/fbsql.xml Wed Oct 17 14:35:35 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.27 $ --> +<!-- $Revision: 1.28 $ --> <reference id="ref.fbsql"> <title>FrontBase functions</title> <titleabbrev>FrontBase</titleabbrev> @@ -201,7 +201,7 @@ </programlisting> </example> <para> - See also: <function>fbsql_connect</function>, and + See also: <function>fbsql_connect</function> and <function>fbsql_pconnect</function>. </para> </refsect1> @@ -305,7 +305,7 @@ </example> <para> See also - <function>fbsql_pconnect</function>, and + <function>fbsql_pconnect</function> and <function>fbsql_close</function>. </para> </refsect1> @@ -388,7 +388,7 @@ or die ("Could not connect"); $filename = "blobfile.bin"; $fp = fopen($filename, "rb"); - $blobdata = fread($fp, file_size($filename)); + $blobdata = fread($fp, filesize($filename)); fclose($fp); $blobHandle = fbsql_create_blob($blobdata, $link); @@ -398,8 +398,11 @@ ?&gt; </programlisting> </example> - <para> - See also: <function>fbsql_create_clob</function>. + <para>See also: + <function>fbsql_create_clob</function>, + <function>fbsql_read_blob</function>, + <function>fbsql_read_clob</function>, + <function>fbsql_set_lob_mode</function> </para> </refsect1> </refentry> @@ -438,7 +441,7 @@ or die ("Could not connect"); $filename = "clob_file.txt"; $fp = fopen($filename, "rb"); - $clobdata = fread($fp, file_size($filename)); + $clobdata = fread($fp, filesize($filename)); fclose($fp); $clobHandle = fbsql_create_clob($clobdata, $link); @@ -448,8 +451,11 @@ ?&gt; </programlisting> </example> - <para> - See also: <function>fbsql_create_blob</function>. + <para>See also: + <function>fbsql_create_blob</function>, + <function>fbsql_read_blob</function>, + <function>fbsql_read_clob</function>, + <function>fbsql_set_lob_mode</function> </para> </refsect1> </refentry> @@ -1056,7 +1062,7 @@ <function>fbsql_fetch_lengths</function> stores the lengths of each result column in the last row returned by <function>fbsql_fetch_row</function>, - <function>fbsql_fetch_array</function>, and + <function>fbsql_fetch_array</function> and <function>fbsql_fetch_object</function> in an array, starting at offset 0. </para> @@ -1159,7 +1165,7 @@ See also: <function>fbsql_fetch_array</function>, <function>fbsql_fetch_object</function>, <function>fbsql_data_seek</function>, - <function>fbsql_fetch_lengths</function>, and + <function>fbsql_fetch_lengths</function> and <function>fbsql_result</function>. </para> </refsect1> @@ -1529,7 +1535,7 @@ the table name. A result pointer is returned which can be used with <function>fbsql_field_flags</function>, <function>fbsql_field_len</function>, - <function>fbsql_field_name</function>, and + <function>fbsql_field_name</function> and <function>fbsql_field_type</function>. </para> <para> @@ -1862,12 +1868,134 @@ <function>fbsql_db_query</function>, <function>fbsql_free_result</function>, <function>fbsql_result</function>, - <function>fbsql_select_db</function>, and + <function>fbsql_select_db</function> and <function>fbsql_connect</function>. </para> </refsect1> </refentry> + <refentry id="function.fbsql-read-blob"> + <refnamediv> + <refname>fbsql_read_blob</refname> + <refpurpose>Read a BLOB from the database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>fbsql_read_blob</function></funcdef> + <paramdef>string <parameter>blob_handle</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: A string containing the BLOB specified by blob_handle. + </para> + <para> + <function>fbsql_read_blob</function> reads BLOB data from the database. + If a select statement contains BLOB and/or BLOB columns FrontBase + will return the data directly when data is fetched. This default + behavior can be changed with <function>fbsql_set_lob_mode</function> so + the fetch functions will return handles to BLOB and CLOB data. + If a handle is fetched a user must call <function>fbsql_read_blob</function> + to get the actual BLOB data from the database. + </para> + <example> + <title><function>fbsql_read_blob</function> example</title> + <programlisting role="php"> +&lt;?php + $link = fbsql_pconnect ("localhost", "_SYSTEM", "secret") + or die ("Could not connect"); + $sql = "SELECT BLOB_COLUMN FROM BLOB_TABLE;"; + $rs = fbsql_query($sql, $link); + $row_data = fbsql_fetch_row($rs); + // $row_data[0] will now contain the blob data for teh first row + fbsql_free_result($rs); + + $rs = fbsql_query($sql, $link); + fbsql_set_lob_mode($rs, FBSQL_LOB_HANDLE); + $row_data = fbsql_fetch_row($rs); + // $row_data[0] will now contain a handle to the BLOB data in the first row + $blob_data = fbsql_read_blob($row_data[0]); + fbsql_free_result($rs); + +?&gt; + </programlisting> + </example> + <para>See also: + <function>fbsql_create_blob</function>, + <function>fbsql_read_blob</function>, + <function>fbsql_read_clob</function>, + <function>fbsql_set_lob_mode</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.fbsql-read-clob"> + <refnamediv> + <refname>fbsql_read_clob</refname> + <refpurpose>Read a CLOB from the database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>fbsql_read_clob</function></funcdef> + <paramdef>string <parameter>clob_handle</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: A string containing the CLOB specified by clob_handle. + </para> + <para> + <function>fbsql_read_clob</function> reads CLOB data from the database. + If a select statement contains BLOB and/or CLOB columns FrontBase + will return the data directly when data is fetched. This default + behavior can be changed with <function>fbsql_set_lob_mode</function> so + the fetch functions will return handles to BLOB and CLOB data. + If a handle is fetched a user must call <function>fbsql_read_clob</function> + to get the actual CLOB data from the database. + </para> + <example> + <title><function>fbsql_read_clob</function> example</title> + <programlisting role="php"> +&lt;?php + $link = fbsql_pconnect ("localhost", "_SYSTEM", "secret") + or die ("Could not connect"); + $sql = "SELECT CLOB_COLUMN FROM CLOB_TABLE;"; + $rs = fbsql_query($sql, $link); + $row_data = fbsql_fetch_row($rs); + // $row_data[0] will now contain the clob data for teh first row + fbsql_free_result($rs); + + $rs = fbsql_query($sql, $link); + fbsql_set_lob_mode($rs, FBSQL_LOB_HANDLE); + $row_data = fbsql_fetch_row($rs); + // $row_data[0] will now contain a handle to the CLOB data in the first row + $clob_data = fbsql_read_clob($row_data[0]); + fbsql_free_result($rs); + +?&gt; + </programlisting> + </example> + <para>See also: + <function>fbsql_create_blob</function>, + <function>fbsql_read_blob</function>, + <function>fbsql_read_clob</function>, + <function>fbsql_set_lob_mode</function> + </para> + </refsect1> + </refentry> + <refentry id="function.fbsql-result"> <refnamediv> <refname>fbsql_result</refname> @@ -1911,7 +2039,7 @@ <para> Recommended high-performance alternatives: <function>fbsql_fetch_row</function>, - <function>fbsql_fetch_array</function>, and + <function>fbsql_fetch_array</function> and <function>fbsql_fetch_object</function>. </para> </refsect1> @@ -1949,6 +2077,62 @@ </refsect1> </refentry> + <refentry id="function.fbsql-set-lob-mode"> + <refnamediv> + <refname>fbsql_set_lob_mode</refname> + <refpurpose>Set the LOB retreive mode for a FrontBase result set</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>fbsql_set_lob_mode</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>string <parameter>database_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on error. + </para> + <para> + <function>fbsql_set_lob_mode</function> sets the mode for + retreiving LOB data from the database. When BLOB and CLOB data + is stored in FrontBase it can be stored direct or indirect. + Direct stored LOB data will allways be fetched no matter the setting + of the lob mode. If the LOB data is less than 24 bytes it will allways + be stored directly. + <itemizedlist> + <listitem> + <simpara> + FBSQL_LOB_DIRECT - LOB data is retreived directly. When data is + fetched from the database with <function>fbsql_fetch_row</function>, + and other fetch functions, all CLOB and BLOB columns will be returned + as ordinary coluimns. + This is the default value on a new FrontBase resutl. + </simpara> + </listitem> + <listitem> + <simpara> + FBSQL_LOB_HANDLE - LOB data is retreived as handles to the data. + When data is fetched from the database with <function>fbsql_fetch_row + </function>, and other fetch functions, LOB data will be returned as + a handle to the data if the data is stored indirect or the data if it + is stored direct. + If a handle is returned it will be a 27 byte string formated as + "@'000000000000000000000000'". + </simpara> + </listitem> + </itemizedlist> + </para> + <para> See also: + <function>fbsql_create_blob</function>, + <function>fbsql_create_clob</function>, + <function>fbsql_read_blob</function> and + <function>fbsql_read_clob</function> + </para> + </refsect1> + </refentry> + <refentry id="function.fbsql-select-db"> <refnamediv> <refname>fbsql_select_db</refname> @@ -1992,7 +2176,7 @@ </para> <para> See also: <function>fbsql_connect</function>, - <function>fbsql_pconnect</function>, and + <function>fbsql_pconnect</function> and <function>fbsql_query</function>. </para> </refsect1>