From c65fc65d3b7b94b3bd94f66263e739dd66f81743 Mon Sep 17 00:00:00 2001
From: Kristina Chodorow <kristina@php.net>
Date: Mon, 12 Jul 2010 15:53:42 +0000
Subject: [PATCH] error codes, remove opt

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@301206 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mongo/mongocollection/find.xml | 24 ++++++++++
 reference/mongo/mongocursorexception.xml | 59 ++++++++++++++++++------
 reference/mongo/mongogridfs/remove.xml   | 21 +++++++++
 3 files changed, 90 insertions(+), 14 deletions(-)

diff --git a/reference/mongo/mongocollection/find.xml b/reference/mongo/mongocollection/find.xml
index ae1d9260c1..5cd61a60d1 100644
--- a/reference/mongo/mongocollection/find.xml
+++ b/reference/mongo/mongocollection/find.xml
@@ -106,6 +106,30 @@ $articles = $collection->find(array(
 ]]>
    </programlisting>
   </example>
+
+  <example>
+   <title>Getting results as an array</title>
+   <para>
+    This returns a <classname>MongoCursor</classname>.  Often, when people are 
+    starting out, they are more comfortable using an array.  To turn a cursor
+    into an array, use the <function>iterator_to_array</function> function.  
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$cursor = $collection->find();
+$array = iterator_to_array($cursor);
+
+?>
+]]>
+   </programlisting>
+   <para>
+    Using <function>iterator_to_array</function> forces the driver to load all of
+    the results into memory, so do not do this for result sets that are larger
+    than memory!
+   </para>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
diff --git a/reference/mongo/mongocursorexception.xml b/reference/mongo/mongocursorexception.xml
index 1d2b973066..e46f1c84ca 100644
--- a/reference/mongo/mongocursorexception.xml
+++ b/reference/mongo/mongocursorexception.xml
@@ -17,28 +17,61 @@
 
    <para>
     If there is an error receiving a reply, there will be a more 
-    specific error message to help diagnose the problem:
+    specific error message to help diagnose the problem.  As it is a bit 
+    programmatically awkward to parse an exception message, there is also an
+    error code associated with each cause of the exception.
    </para>
 
    <itemizedlist>
     <listitem>
      <para>
-      <literal>could not establish db connection</literal>
+      <literal>threw away response, please try again</literal>
+     </para>
+     <para>
+      Code: 1
+     </para>
+     <para>
+      Unlikely to occur in a single-threaded application.  The database sent the
+      resoponse while another thread was waiting for a response, so the other
+      thread threw it out.  You should attempt the query again, possibly with 
+      less threads.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <emphasis>various</emphasis>
+     </para>
+     <para>
+      Code: 1
      </para>
      <para>
       A database reply could not be recieved because a connection 
       with the database could not be established.
      </para>
     </listitem>
+    <listitem>
+     <para>
+      <literal>various</literal>
+     </para>
+     <para>
+      Code: 2
+     </para>
+     <para>
+      Caused by the request timing out.  This will return the error message 
+      from the C socket library.
+     </para>
+    </listitem>
     <listitem>
      <para>
       <literal>no db response</literal>
      </para>
      <para>
-      This may not even be an error, for example, the database 
-      command "shutdown" returns no response.  However, if you 
-      were expecting a response, this means the database didn't 
-      give one.
+      Code: 4
+     </para>
+     <para>
+      This may not even be an error, for example, the database command 
+      "shutdown" returns no response.  However, if you were expecting a 
+      response, this means the database didn't give one.
      </para>
     </listitem>
     <listitem>
@@ -46,12 +79,10 @@
       <literal>bad response length: %d, max: %d, did the db assert?</literal>
      </para>
      <para>
-      This means that the database said that its response was 
-      greater than 4Mb or less than 0.  Generally, a number 
-      greater than 5Mb should be reported to the developers as a 
-      potential database bug (max response length is 4Mb).  A 
-      response of less than 0 often means a database assertion 
-      occured.
+      This means that the database said that its response was greater than 4Mb 
+      or less than 0.  Generally, a number greater than 5Mb should be reported 
+      to the developers as a potential database bug (max response length is 
+      4Mb).  A response of less than 0 often means a database assertion occured.
      </para>
     </listitem>
     <listitem>
@@ -59,8 +90,8 @@
       <literal>incomplete response</literal>
      </para>
      <para>
-      Occurs if the database response started out correctly, but broke off in
-      the middle.
+      Highly unusual.  Occurs if the database response started out correctly, 
+      but broke off in the middle.
      </para>
     </listitem>
     <listitem>
diff --git a/reference/mongo/mongogridfs/remove.xml b/reference/mongo/mongogridfs/remove.xml
index 843e739499..1cbbc25a57 100644
--- a/reference/mongo/mongogridfs/remove.xml
+++ b/reference/mongo/mongogridfs/remove.xml
@@ -12,6 +12,7 @@
   <methodsynopsis>
    <modifier>public</modifier> <type>boolean</type><methodname>MongoGridFS::remove</methodname>
    <methodparam choice="opt"><type>array</type><parameter>criteria</parameter><initializer>array()</initializer></methodparam>
+   <methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>array()</initializer></methodparam>
   </methodsynopsis>
  </refsect1>
 
@@ -29,6 +30,26 @@
       </para>
      </listitem>
     </varlistentry>   
+    <varlistentry>
+     <term>
+      <parameter>options</parameter>
+     </term>
+     <listitem>
+      <para>
+       Options for the remove.  Valid options are:
+      </para>
+      <itemizedlist>
+       <listitem>
+        <para>
+         <literal>"safe"</literal>
+        </para>
+        <para>
+         Check that the remove succeeded.
+        </para>
+       </listitem>
+      </itemizedlist>
+     </listitem>
+    </varlistentry>   
    </variablelist>
   </para>
  </refsect1>