From 0f51802abb089b6eaebca504389e8d47468a4896 Mon Sep 17 00:00:00 2001
From: John Coggeshall <john@php.net>
Date: Thu, 15 May 2003 09:59:23 +0000
Subject: [PATCH] Documented 6 more functions of the MySQLi extension

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@127085 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mysqli/functions/mysqli-field-count.xml   | 10 ++++++---
 reference/mysqli/functions/mysqli-kill.xml    |  8 ++++---
 reference/mysqli/functions/mysqli-query.xml   | 16 +++++++++++---
 .../mysqli/functions/mysqli-real-query.xml    | 16 +++++++++++---
 .../mysqli/functions/mysqli-store-result.xml  | 16 +++++++++++---
 .../mysqli/functions/mysqli-thread-id.xml     | 15 ++++++++++---
 .../mysqli/functions/mysqli-use-result.xml    | 21 ++++++++++++++++---
 7 files changed, 81 insertions(+), 21 deletions(-)

diff --git a/reference/mysqli/functions/mysqli-field-count.xml b/reference/mysqli/functions/mysqli-field-count.xml
index 634383bc75..a3d9d4da8b 100644
--- a/reference/mysqli/functions/mysqli-field-count.xml
+++ b/reference/mysqli/functions/mysqli-field-count.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.mysqli-field-count">
    <refnamediv>
     <refname>mysqli_field_count</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>Returns the number of columns for the most recent query</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -12,7 +12,11 @@
       <methodparam><type>resource</type><parameter>link</parameter></methodparam>
      </methodsynopsis>
     <para>
-&warn.undocumented.func;
+    Returns the number of columns for the most recent query on the connection
+    represented by the <parameter>link</parameter> parameter. This function
+    can be useful when using the <function>mysqli_store_result</function>
+    to determine if the query should have produced a non-empty result set or
+    not without knowing the nature of the query.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/mysqli/functions/mysqli-kill.xml b/reference/mysqli/functions/mysqli-kill.xml
index 2a34d8743e..6ac8637481 100644
--- a/reference/mysqli/functions/mysqli-kill.xml
+++ b/reference/mysqli/functions/mysqli-kill.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.mysqli-kill">
    <refnamediv>
     <refname>mysqli_kill</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>Ask the server to kill a MySQL thread</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -13,7 +13,9 @@
       <methodparam><type>int</type><parameter>processid</parameter></methodparam>
      </methodsynopsis>
     <para>
-&warn.undocumented.func;
+    This function is used to ask the server to kill a MySQL thread specified
+    by the <parameter>processid</parameter> parameter. This value must be
+    retrieved by calling the <function>mysqli_thread_id</function> function.
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/mysqli/functions/mysqli-query.xml b/reference/mysqli/functions/mysqli-query.xml
index 5230f99104..a07984e34c 100644
--- a/reference/mysqli/functions/mysqli-query.xml
+++ b/reference/mysqli/functions/mysqli-query.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.mysqli-query">
    <refnamediv>
     <refname>mysqli_query</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>Performs a query on the database</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -14,7 +14,17 @@
       <methodparam choice='opt'><type>int</type><parameter>resultmode</parameter></methodparam>
      </methodsynopsis>
     <para>
-&warn.undocumented.func;
+    The <function>mysqli_query</function> function is used to simplify the
+    act of performing a query against the database represented by the
+    <parameter>link</parameter> parameter. Functionally, using this
+    function is identical to calling <function>mysqli_real_query</function>
+    followed either <function>mysqli_use_result</function> or 
+    <function>mysqli_store_result</function> where <parameter>query</parameter>
+    is the query string itself and <parameter>resultmode</parameter> is
+    either the constant MYSQLI_USE_RESULT or MYSQLI_STORE_RESULT depending
+    on the desired behavior. By default, if the 
+    <parameter>resultmode</parameter> is not provided MYSQLI_STORE_RESULT
+    is used.     
     </para>
    </refsect1>
   </refentry>
diff --git a/reference/mysqli/functions/mysqli-real-query.xml b/reference/mysqli/functions/mysqli-real-query.xml
index 32579c3a64..631d44c4aa 100644
--- a/reference/mysqli/functions/mysqli-real-query.xml
+++ b/reference/mysqli/functions/mysqli-real-query.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.mysqli-real-query">
    <refnamediv>
     <refname>mysqli_real_query</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>Execute an SQL query</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -13,8 +13,18 @@
       <methodparam><type>string</type><parameter>query</parameter></methodparam>
      </methodsynopsis>
     <para>
-&warn.undocumented.func;
+    The <function>mysqli_real_query</function> function is used to execute
+    only a query against the database represnted by the <parameter>link</parameter>
+    whose result can then be retrieved or stored using the
+    <function>mysqli_store_result</function> or <function>mysqli_use_result</function>
+    functions.
     </para>
+    <note>
+     <para>
+     In order to determine if a given query should return a result set or not,
+     see <function>mysqli_field_count</function>.
+     </para>
+    </note>
    </refsect1>
   </refentry>
 
diff --git a/reference/mysqli/functions/mysqli-store-result.xml b/reference/mysqli/functions/mysqli-store-result.xml
index 73343a37dc..62f17849e4 100644
--- a/reference/mysqli/functions/mysqli-store-result.xml
+++ b/reference/mysqli/functions/mysqli-store-result.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.mysqli-store-result">
    <refnamediv>
     <refname>mysqli_store_result</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>Transfers a result set from the last query</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -12,8 +12,18 @@
       <methodparam><type>resource</type><parameter>link</parameter></methodparam>
      </methodsynopsis>
     <para>
-&warn.undocumented.func;
+    Transfers the result set from the last query on the database connection
+    represented by the <parameter>link</parameter> parameter to be used with
+    the <function>mysqli_data_seek</function> function.
     </para>
+    <note>
+     <para>
+     Although it is always good practice to free the memory used by the result of
+     a query using the <function>mysqli_free_result</function> function, when
+     transfering large result sets using the <function>mysqli_store_result</function>
+     this becomes particularly important.
+     </para>
+    </note>
    </refsect1>
   </refentry>
 
diff --git a/reference/mysqli/functions/mysqli-thread-id.xml b/reference/mysqli/functions/mysqli-thread-id.xml
index abeb34a3e5..a8efcd1394 100644
--- a/reference/mysqli/functions/mysqli-thread-id.xml
+++ b/reference/mysqli/functions/mysqli-thread-id.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.mysqli-thread-id">
    <refnamediv>
     <refname>mysqli_thread_id</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>Returns the thread ID for the current connection</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -12,8 +12,17 @@
       <methodparam><type>resource</type><parameter>link</parameter></methodparam>
      </methodsynopsis>
     <para>
-&warn.undocumented.func;
+    The <function>mysqli_thread_id</function> function returns the thread
+    ID for the current connection which can then be killed using the
+    <function>mysqli_kill</function> function.
     </para>
+    <note>
+     <para>
+     The thread ID is assigned on a connection-by-connection basis. Hence,
+     if the connection is broken and then re-established a new thread ID
+     will be assigned.
+     </para>
+    </note>
    </refsect1>
   </refentry>
 
diff --git a/reference/mysqli/functions/mysqli-use-result.xml b/reference/mysqli/functions/mysqli-use-result.xml
index 9f88102f95..92fdee8f19 100644
--- a/reference/mysqli/functions/mysqli-use-result.xml
+++ b/reference/mysqli/functions/mysqli-use-result.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
   <refentry id="function.mysqli-use-result">
    <refnamediv>
     <refname>mysqli_use_result</refname>
-    <refpurpose></refpurpose>
+    <refpurpose>Initiate a result set retrieval</refpurpose>
    </refnamediv>
    <refsect1>
     <title>Description</title>
@@ -12,8 +12,23 @@
       <methodparam><type>resource</type><parameter>link</parameter></methodparam>
      </methodsynopsis>
     <para>
-&warn.undocumented.func;
+    <function>mysqli_use_result</function> is used to initiate the retrieval
+    of a result set from the last query executed using the
+    <function>mysqli_real_query</function> function on the database connection
+    specified by the <parameter>link</parameter> parameter. Either this or the
+    <function>mysqli_store_result</function> must be called before the
+    results of a query can be retrieved, and one or the other must be called
+    to prevent the next query on that database connection from failing.
     </para>
+    <note>
+     <para>
+     The <function>mysqli_use_result</function> function does not transfer
+     the entire result set from the database and hence cannot be used functions
+     such as <function>mysqli_data_seek</function> to move to a particular
+     row within the set. To use this functionality, the result set must be
+     stored using <function>mysqli_store_result</function>
+     </para>
+    </note>
    </refsect1>
   </refentry>