From c864e2b53159558dbe1c675c5391119e7ca0d7a5 Mon Sep 17 00:00:00 2001
From: Georg Richter <georg@php.net>
Date: Sat, 21 Feb 2004 08:44:40 +0000
Subject: [PATCH] fixed return value in mysqli_fetch_field_direct added samples

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@151980 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mysqli/functions/mysqli-execute.xml | 136 ++++++++++-----
 .../mysqli/functions/mysqli-fetch-array.xml   | 157 ++++++++++--------
 .../mysqli/functions/mysqli-fetch-assoc.xml   | 110 ++++++------
 .../functions/mysqli-fetch-field-direct.xml   |  71 +++++++-
 4 files changed, 303 insertions(+), 171 deletions(-)

diff --git a/reference/mysqli/functions/mysqli-execute.xml b/reference/mysqli/functions/mysqli-execute.xml
index fcffbd59fd..746c8d3f93 100644
--- a/reference/mysqli/functions/mysqli-execute.xml
+++ b/reference/mysqli/functions/mysqli-execute.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
   <refentry id="function.mysqli-execute">
    <refnamediv>
     <refname>mysqli_execute</refname>
@@ -44,49 +44,6 @@
     <title>Return values</title>
     <para>&return.success;</para>
    </refsect1>
-   <refsect1>
-    <title>Example</title>
-    <para>
-     <example>
-      <title>Using the mysqli_execute function</title>
-      <programlisting role="php">
-<![CDATA[
-<?php
-    
-    /* Open a connection */
-    $link = mysqli_connect("localhost", "user", "pass");
-    mysqli_select_db("mydb");
-    
-    /* Turn on autocommit */
-    mysqli_autocommit($link, true);
-    
-    /* Prepare an insert statement */
-    $query = "INSERT INTO mytable VALUES(?, ?)";
-    $stmt = mysqli_prepare($link, $query);
-    
-    $value_one = "hello";
-    $value_two = "world";
-    
-    mysqli_bind_param($link, $value_one, $value_two);
-    
-    /* Execute the statement */
-    mysqli_execute($stmt);
-    
-    /* Return the affected rows for the statement */
-    $affected_rows = mysqli_stmt_affected_rows($stmt);
-    
-    /* Close the statement */
-    
-    mysqli_stmt_close($stmt);
-    
-    echo "The total affected rows was $affected_rows";
-    
-?>
-]]>
-      </programlisting>
-     </example>
-    </para>
-   </refsect1>
    <refsect1>
     <title>See also</title>
     <para>
@@ -94,6 +51,97 @@
      <function>mysqli_bind_param</function>.
     </para>
    </refsect1>
+   <refsect1>
+    <title>Example</title>
+    <para>
+     <example>
+      <title>Object oriented style</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
+   
+$mysqli->query("DROP TABLE IF EXISTS friends"); 
+$mysqli->query("CREATE TABLE friends (id int, name varchar(20))"); 
+    
+/* Prepare an insert statement */
+$query = "INSERT INTO friends VALUES(?, ?)";
+$stmt = $mysqli->prepare($query);
+
+$stmt->bind_param("is", $val1, $val2);
+
+$val1 = 1;
+$val2 = 'Miller';
+    
+/* Execute the statement */
+$stmt->execute();
+
+$val1 = 2;
+$val2 = 'Wagner';
+    
+/* Execute the statement */
+$stmt->execute();
+    
+$stmt->close();
+
+/* Return the affected rows for the statement */
+if ($result = $mysqli->query("SELECT id,name FROM friends")) {
+    while ($row = $result->fetch_row()) {
+        printf("ID: %s  Name: %s\n", $row[0], $row[1]);
+    }
+    $result->close();
+}
+    
+$mysqli->close(); 
+?>
+]]>
+      </programlisting>
+     </example>
+     <example>
+      <title>Procedural style</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$link = mysqli_connect("localhost", "my_user", "my_password", "test");
+   
+mysqli_query($link, "DROP TABLE IF EXISTS friends"); 
+mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))"); 
+
+/* Prepare an insert statement */
+$query = "INSERT INTO friends VALUES(?, ?)";
+$stmt = mysqli_prepare($link, $query);
+
+mysqli_bind_param($stmt, "is", $val1, $val2);
+
+$val1 = 1;
+$val2 = 'Miller';
+
+/* Execute the statement */
+mysqli_execute($stmt);
+
+$val1 = 2;
+$val2 = 'Wagner';
+    
+/* Execute the statement */
+mysqli_execute($stmt);
+    
+mysqli_stmt_close($stmt);
+
+/* Return the affected rows for the statement */
+if ($result = mysqli_query($link, "SELECT id,name FROM friends")) {
+    while ($row = mysqli_fetch_row($result)) {
+        printf("ID: %s  Name: %s\n", $row[0], $row[1]);
+    }
+    mysqli_free_result($result);
+}
+    
+mysqli_close($link); 
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
+   </refsect1>
   </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/mysqli/functions/mysqli-fetch-array.xml b/reference/mysqli/functions/mysqli-fetch-array.xml
index d8ea31f2a6..a3c3a30566 100644
--- a/reference/mysqli/functions/mysqli-fetch-array.xml
+++ b/reference/mysqli/functions/mysqli-fetch-array.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
   <refentry id="function.mysqli-fetch-array">
    <refnamediv>
     <refname>mysqli_fetch_array</refname>
@@ -24,7 +24,7 @@
       </methodsynopsis>
      </classsynopsis>
     <para>
-     Returns an array that corresponds to the fetched row or &false; if there are no more rows for the
+     Returns an array that corresponds to the fetched row or &null; if there are no more rows for the
      database connection represented by the <parameter>link</parameter> parameter. 
     </para>
     <para>
@@ -55,72 +55,7 @@
    <refsect1>
     <title>Return values</title>
     <para>
-     Returns an array that corresponds to the fetched row or &false; if there are no more rows in resultset.
-    </para>
-   </refsect1>
-   <refsect1>
-    <title>Example</title>
-    <para>
-     <example>
-      <title>mysqli_fetch_array with MYSQLI_NUM</title>
-      <programlisting role="php">
-<![CDATA[
-<?php
-    mysqli_connect("localhost", "mysql_user", "mysql_password") or
-        die("Could not connect: " . mysqli_error());
-    mysqli_select_db("mydb");
-
-    $result = mysqli_query("SELECT id, name FROM mytable");
-
-    while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
-        printf ("ID: %s  Name: %s", $row[0], $row[1]);  
-    }
-
-    mysqli_free_result($result);
-?>
-]]>
-      </programlisting>
-     </example>
-     <example>
-      <title>mysqli_fetch_array with MYSQLI_ASSOC</title>
-      <programlisting role="php">
-<![CDATA[
-<?php
-    mysqli_connect("localhost", "mysql_user", "mysql_password") or
-        die("Could not connect: " . mysqli_error());
-    mysqli_select_db("mydb");
-
-    $result = mysqli_query("SELECT id, name FROM mytable");
-
-    while ($row = mysqli_fetch_array($result, MYSQLI_ASSOC)) {
-        printf ("ID: %s  Name: %s", $row["id"], $row["name"]);
-    }
-
-    mysqli_free_result($result);
-?>
-]]>
-      </programlisting>
-     </example>
-     <example>
-      <title>mysqli_fetch_array with MYSQLI_BOTH</title>
-      <programlisting role="php">
-<![CDATA[
-<?php
-    mysqli_connect("localhost", "mysql_user", "mysql_password") or
-        die("Could not connect: " . mysqli_error());
-    mysqli_select_db("mydb");
-
-    $result = mysqli_query("SELECT id, name FROM mytable");
-
-    while ($row = mysqli_fetch_array($result, MYSQLI_BOTH)) {
-        printf ("ID: %s  Name: %s", $row[0], $row["name"]);
-    }
-
-    mysqli_free_result($result);
-?>
-]]>
-      </programlisting>
-     </example>
+     Returns an array that corresponds to the fetched row or &null; if there are no more rows in resultset.
     </para>
    </refsect1>
    <refsect1>
@@ -131,6 +66,92 @@
      <function>mysqli_fetch_object</function>.
     </para>
    </refsect1>
+   <refsect1>
+    <title>Example</title>
+    <para>
+     <example>
+      <title>Object oriented style</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
+
+$mysqli->query("DROP TABLE IF EXISTS friends"); 
+$mysqli->query("CREATE TABLE friends (id int, name varchar(20))"); 
+ 
+$mysqli->query("INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
+
+$result = $mysqli->query( "SELECT id, name FROM friends");
+
+/* numeric array */
+while ($row = $result->fetch_array(MYSQLI_NUM)) {
+    printf ("ID: %s  Name: %s\n", $row[0], $row[1]);  
+}
+$result->close();
+
+$result = $mysqli->query("SELECT id, name FROM friends");
+
+/* associative array */
+while ($row = $result->fetch_array(MYSQLI_ASSOC)) {
+    printf ("ID: %s  Name: %s\n", $row["id"], $row["name"]);
+}
+$result->close();
+
+$result = $mysqli->query("SELECT id, name FROM friends");
+
+/* associative and numeric array */
+while ($row = $result->fetch_array(MYSQLI_BOTH)) {
+    printf ("ID: %s  Name: %s\n", $row[0], $row["name"]);
+}
+$result->close();
+
+$mysqli->close();
+?>
+]]>
+      </programlisting>
+     </example>
+     <example>
+      <title>Procedural style</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$link = mysqli_connect("localhost", "my_user", "my_password", "test");
+
+mysqli_query($link, "DROP TABLE IF EXISTS friends"); 
+mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))"); 
+ 
+mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
+
+$result = mysqli_query($link, "SELECT id, name FROM friends");
+
+/* numeric array */
+while ($row = mysqli_fetch_array($result, MYSQLI_NUM)) {
+    printf ("ID: %s  Name: %s\n", $row[0], $row[1]);  
+}
+mysqli_free_result($result);
+
+$result = mysqli_query($link, "SELECT id, name FROM friends");
+
+/* associative array */
+while ($row = mysqli_fetch_array($result, MYSQLI_ASSOC)) {
+    printf ("ID: %s  Name: %s\n", $row["id"], $row["name"]);
+}
+mysqli_free_result($result);
+$result = mysqli_query($link, "SELECT id, name FROM friends");
+
+/* associative and numeric array */
+while ($row = mysqli_fetch_array($result, MYSQLI_BOTH)) {
+    printf ("ID: %s  Name: %s\n", $row[0], $row["name"]);
+}
+mysqli_free_result($result);
+
+mysqli_close($link);
+?>
+]]>
+      </programlisting>
+     </example>
+    </para>
+   </refsect1>
   </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/mysqli/functions/mysqli-fetch-assoc.xml b/reference/mysqli/functions/mysqli-fetch-assoc.xml
index d0409e82a6..59b9ccb630 100644
--- a/reference/mysqli/functions/mysqli-fetch-assoc.xml
+++ b/reference/mysqli/functions/mysqli-fetch-assoc.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
   <refentry id="function.mysqli-fetch-assoc">
    <refnamediv>
     <refname>mysqli_fetch_assoc</refname>
@@ -23,7 +23,7 @@
       </methodsynopsis>
      </classsynopsis>
     <para>
-     Returns an associative array that corresponds to the fetched row or &false; if there are 
+     Returns an associative array that corresponds to the fetched row or &null; if there are 
      no more rows.
     </para>
     <para>
@@ -44,62 +44,9 @@
    <refsect1>
     <title>Return values</title>
     <para>
-     Returns an array that corresponds to the fetched row or &false; if there are no more rows in resultset.
+     Returns an array that corresponds to the fetched row or &null; if there are no more rows in resultset.
     </para>
    </refsect1>
-   <refsect1>
-    <title>Example</title>
-    <example>
-     <title>An expanded <function>mysqli_fetch_assoc</function> example</title>
-     <programlisting role="php">
-<![CDATA[
-<?php
-
-    $conn = mysqli_connect("localhost", "mysql_user", "mysql_password");
-    
-    if (!$conn) {
-        echo "Unable to connect to DB: " . mysqli_error();
-        exit;
-    }
-    
-    if (!mysqli_select_db("mydbname")) {
-        echo "Unable to select mydbname: " . mysqli_error();
-        exit;
-    }
-    
-    $sql = "SELECT id as userid, fullname, userstatus 
-            FROM   sometable
-            WHERE  userstatus = 1";
-
-    $result = mysqli_query($sql);
-
-    if (!$result) {
-        echo "Could not successfully run query ($sql) from DB: " . mysqli_error();
-        exit;
-    }
-    
-    if (mysqli_num_rows($result) == 0) {
-        echo "No rows found, nothing to print so am exiting";
-        exit;
-    }
-
-    // While a row of data exists, put that row in $row as an associative array
-    // Note: If you're expecting just one row, no need to use a loop
-    // Note: If you put extract($row); inside the following loop, you'll
-    //       then create $userid, $fullname, and $userstatus
-    while ($row = mysqli_fetch_assoc($result)) {
-        echo $row["userid"];
-        echo $row["fullname"];
-        echo $row["userstatus"];
-    }
-	    
-    mysqli_free_result($result);
-
-?>
-]]>
-     </programlisting>
-    </example>
-   </refsect1>
    <refsect1>
     <title>See also</title>
     <para>
@@ -108,6 +55,57 @@
      <function>mysqli_fetch_object</function>.
     </para>
    </refsect1>
+   <refsect1>
+    <title>Example</title>
+    <example>
+     <title>Object oriented style</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
+
+$mysqli->query( "DROP TABLE IF EXISTS friends"); 
+$mysqli->query( "CREATE TABLE friends (id int, name varchar(20))"); 
+ 
+$mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
+
+$result = $mysqli->query( "SELECT id, name FROM friends");
+
+while ($row = $result->fetch_assoc()) {
+    printf ("ID: %s  Name: %s\n", $row["id"], $row["name"]);
+}
+$result->close();
+
+$mysqli->close();
+?>
+]]>
+     </programlisting>
+    </example>
+    <example>
+     <title>Procedural style</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$link = mysqli_connect("localhost", "my_user", "my_password", "test");
+
+mysqli_query($link, "DROP TABLE IF EXISTS friends"); 
+mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))"); 
+ 
+mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
+
+$result = mysqli_query($link, "SELECT id, name FROM friends");
+
+while ($row = mysqli_fetch_assoc($result)) {
+printf ("ID: %s  Name: %s\n", $row["id"], $row["name"]);
+    }
+mysqli_free_result($result);
+
+mysqli_close($link);
+?>
+]]>
+     </programlisting>
+    </example>
+   </refsect1>
   </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/mysqli/functions/mysqli-fetch-field-direct.xml b/reference/mysqli/functions/mysqli-fetch-field-direct.xml
index aeab5b146b..fc242a2c63 100644
--- a/reference/mysqli/functions/mysqli-fetch-field-direct.xml
+++ b/reference/mysqli/functions/mysqli-fetch-field-direct.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
   <refentry id="function.mysqli-fetch-field-direct">
    <refnamediv>
     <refname>mysqli_fetch_field_direct</refname>
@@ -26,7 +26,7 @@
       </methodsynopsis>
      </classsynopsis>
     <para>
-     <function>mysqli_fetch_field_direct</function> returns an associative array which contains 
+     <function>mysqli_fetch_field_direct</function> returns an object which contains 
      field definition informations from specified resultset. The value of fieldnr must be in the 
      range from <literal>0</literal> to <literal>number of fields - 1</literal>.
     </para>
@@ -34,7 +34,7 @@
    <refsect1>
     <title>Return values</title>
     <para>
-     Returns an associative array which contains field definition informations or &false; if no field information
+     Returns an object which contains field definition informations or &false; if no field information
      for specified <literal>fieldnr</literal> is available.
     </para>
    </refsect1>
@@ -46,6 +46,71 @@
      <function>mysqli_fetch_fields</function>
     </para>
    </refsect1>
+   <refsect1>
+    <title>Example</title>
+    <example>
+     <title>Object oriented style</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
+
+$mysqli->query( "DROP TABLE IF EXISTS friends"); 
+$mysqli->query( "CREATE TABLE friends (id int, name varchar(20))"); 
+ 
+$mysqli->query( "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
+
+$result = $mysqli->query( "SELECT id, name FROM friends");
+
+/* Get field information for column 'name' */
+$finfo = $result->fetch_field_direct(1);
+ 
+printf("Name:     %s\n", $finfo->name);
+printf("Table:    %s\n", $finfo->table);
+printf("Default:  %s\n", $finfo->def);
+printf("max. Len: %d\n", $finfo->max_length);
+printf("Flags:    %d\n", $finfo->flags);
+printf("Type:     %d\n", $finfo->type);
+    
+$result->close();
+
+$mysqli->close();
+?>
+]]>
+     </programlisting>
+    </example>
+    <example>
+     <title>Procedural style</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$link = mysqli_connect("localhost", "my_user", "my_password", "test");
+
+mysqli_query($link, "DROP TABLE IF EXISTS friends"); 
+mysqli_query($link, "CREATE TABLE friends (id int, name varchar(20))"); 
+ 
+mysqli_query($link, "INSERT INTO friends VALUES (1,'Hartmut'), (2, 'Ulf')");
+
+$result = mysqli_query($link, "SELECT id, name FROM friends");
+
+/* Get field information for column 'name' */
+$finfo = mysqli_fetch_field_direct($result, 1);
+ 
+printf("Name:     %s\n", $finfo->name);
+printf("Table:    %s\n", $finfo->table);
+printf("Default:  %s\n", $finfo->def);
+printf("max. Len: %d\n", $finfo->max_length);
+printf("Flags:    %d\n", $finfo->flags);
+printf("Type:     %d\n", $finfo->type);
+
+mysqli_free_result($result);
+
+mysqli_close($link);
+?>
+]]>
+     </programlisting>
+    </example>
+   </refsect1>
   </refentry>
 
 <!-- Keep this comment at the end of the file