From 5beaca7d29fbe7e2ab54a169217fbd3221949946 Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Thu, 15 Jul 2004 21:28:57 +0000
Subject: [PATCH] Added an example, implemented user notes on how E_WARNING is
 emitted if !resource, and added see also.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@163409 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../mysql/functions/mysql-free-result.xml     | 38 ++++++++++++++++++-
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/reference/mysql/functions/mysql-free-result.xml b/reference/mysql/functions/mysql-free-result.xml
index c4077f1c5f..2d93758ab1 100644
--- a/reference/mysql/functions/mysql-free-result.xml
+++ b/reference/mysql/functions/mysql-free-result.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- splitted from ./en/functions/mysql.xml, last change in rev 1.102 -->
   <refentry id="function.mysql-free-result">
    <refnamediv>
@@ -21,15 +21,49 @@
      you are concerned about how much memory is being used for queries
      that return large result sets.  All associated result memory is
      automatically freed at the end of the script's execution.
-     <!-- TODO and as of PHP 4 before, see freeing resources -->
     </para>
     <para>
      &return.success;
     </para>
+    <para>
+     If a non-resource is used for the <parameter>result</parameter>, an
+     error of level E_WARNING will be emitted.  It's worth noting that
+     <function>mysql_query</function> only returns a <type>resource</type>
+     for SELECT, SHOW, EXPLAIN, and DESCRIBE queries.
+    </para>
+    <para>
+     <example>
+      <title>A <function>mysql_free_result</function> example</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$result = mysql_query("SELECT id,email FROM people WHERE id = '42'");
+if (!$result) {
+    echo 'Could not run query: ' . mysql_error();
+    exit;
+}
+/* Use the result, assuming we're done with it afterwords */
+$row = mysql_fetch_assoc($result);
+
+/* Now we free up the result and continue on with our script */
+mysql_free_result($result);
+
+echo $row['id'];
+echo $row['email'];
+
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
     <para>
      For downward compatibility <function>mysql_freeresult</function>
      can also be used. This is deprecated, however.
     </para>
+    <para>
+     See also <function>mysql_query</function> and 
+     <function>is_resource</function>.
+    </para>
    </refsect1>
   </refentry>