diff --git a/functions/fbsql.xml b/functions/fbsql.xml
index 915a9e7f29..2bb4e687a2 100644
--- a/functions/fbsql.xml
+++ b/functions/fbsql.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.36 $ -->
+<!-- $Revision: 1.37 $ -->
  <reference id="ref.fbsql">
   <title>FrontBase Functions</title>
   <titleabbrev>FrontBase</titleabbrev>
@@ -496,22 +496,40 @@
      </funcprototype>
     </funcsynopsis>
     <para> 
-     Returns: The database password for the database represented by
-     the link identifier.
+     Returns: The database password associated with the link identifier.
     </para>
     <para> 
      <function>fbsql_database_password</function> sets and retrieves
-     the database password for the current database.  if the second
+     the database password used by the connection. if a database is
+     protected by a database password, the user must call this function
+     before calling <function>fbsql_select_db</function>. if the second
      optional parameter is given the function sets the database
-     password for the database on the server that's associated with
-     the specified link identifier.  If no link identifier is
+     password for the specified link identifier.  If no link identifier is
      specified, the last opened link is assumed.  If no link is open,
      the function will try to establish a link as if
      <function>fbsql_connect</function> was called, and use it.
     </para>
     <para> 
-     See also: <function>fbsql_connect</function> and
-     <function>fbsql_pconnect</function>.
+     This function does not change the database password in the database
+     nor can it be used to retrive the database password for a database.
+    </para>
+    <example>
+     <title><function>fbsql_create_clob</function> example</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+    $link = fbsql_pconnect ("localhost", "_SYSTEM", "secret")
+        or die ("Could not connect");
+    fbsql_database_password($link, "secret db password");
+    fbsql_select_db($database, $link);
+?>
+]]>
+     </programlisting>
+    </example>
+    <para> 
+     See also: <function>fbsql_connect</function>,
+     <function>fbsql_pconnect</function> and
+     <function>fbsql_select_db</function>.
     </para>
    </refsect1>
   </refentry>
@@ -2252,9 +2270,15 @@ $result = fbsql_query ("SELECT my_col FROM my_tbl")
      Every subsequent call to <function>fbsql_query</function> will be
      made on the active database.
     </para>
+    <para>
+     if the database is protected with a database password, the user must
+     call <function>fbsql_database_password</function> before selecting
+     the database. 
+    </para>
     <para> See also:
      <function>fbsql_connect</function>, 
-     <function>fbsql_pconnect</function>, and
+     <function>fbsql_pconnect</function>,
+     <function>fbsql_database_password</function> and
      <function>fbsql_query</function>.
     </para>
    </refsect1>