From 66834c02bb17a940e5bd78ae4055288c2359ab6f Mon Sep 17 00:00:00 2001
From: Georg Richter <georg@php.net>
Date: Fri, 20 Feb 2004 14:45:50 +0000
Subject: [PATCH] added documentation for mysqli_get_metadata and mysqli_report
added samples
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@151924 c90b9560-bf6c-de11-be94-00142212c4b1
---
reference/mysqli/functions/mysqli-debug.xml | 15 ++--
reference/mysqli/functions/mysqli-errno.xml | 42 +++++++++-
reference/mysqli/functions/mysqli-error.xml | 48 +++++++----
.../mysqli/functions/mysqli-get-metadata.xml | 67 +++++++++++++--
reference/mysqli/functions/mysqli-report.xml | 82 ++++++++++++++++++-
5 files changed, 219 insertions(+), 35 deletions(-)
diff --git a/reference/mysqli/functions/mysqli-debug.xml b/reference/mysqli/functions/mysqli-debug.xml
index bd3be510fe..d3b5c7f891 100644
--- a/reference/mysqli/functions/mysqli-debug.xml
+++ b/reference/mysqli/functions/mysqli-debug.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
<refentry id="function.mysqli-debug">
<refnamediv>
<refname>mysqli_debug</refname>
@@ -27,6 +27,13 @@
<title>Return values</title>
<para><function>mysqli_debug</function> doesn't return any value.</para>
</refsect1>
+ <refsect1>
+ <title>See also</title>
+ <para>
+ <function>mysqli_dump_debug_info</function>,
+ <function>mysqli_report</function>
+ </para>
+ </refsect1>
<refsect1>
<title>Example</title>
<para>
@@ -45,12 +52,6 @@ mysqli_debug("d:t:0,/tmp/client.trace");
</example>
</para>
</refsect1>
- <refsect1>
- <title>See also</title>
- <para>
- <function>mysqli_dump_debug_info</function>
- </para>
- </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/mysqli/functions/mysqli-errno.xml b/reference/mysqli/functions/mysqli-errno.xml
index 9def3d4e02..e106bbc2b4 100644
--- a/reference/mysqli/functions/mysqli-errno.xml
+++ b/reference/mysqli/functions/mysqli-errno.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
<refentry id="function.mysqli-errno">
<refnamediv>
<refname>mysqli_errno</refname>
@@ -42,9 +42,47 @@
<refsect1>
<title>See also</title>
<para>
- <function>mysqli_error</function>, <function>mysqli_sqlstate</function>
+ <function>mysqli_connect_errno</function>,
+ <function>mysqli_connect_error</function>,
+ <function>mysqli_error</function>,
+ <function>mysqli_sqlstate</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");
+
+if (!$mysqli->query("SET a=1")) {
+ printf("Errorcode: %d\n", $mysqli->errno);
+}
+$mysqli->close();
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Procedural style</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$link = mysqli_connect("localhost", "my_user", "my_password", "test");
+
+if (!mysqli_query($link, "SET a=1")) {
+ printf("Errorcode: %d\n", mysqli_errno($link));
+}
+mysqli_close($link);
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/mysqli/functions/mysqli-error.xml b/reference/mysqli/functions/mysqli-error.xml
index 6112c3f841..fc0f2dc798 100644
--- a/reference/mysqli/functions/mysqli-error.xml
+++ b/reference/mysqli/functions/mysqli-error.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
<refentry id="function.mysqli-error">
<refnamediv>
<refname>mysqli_error</refname>
@@ -32,32 +32,50 @@
A string that describes the error. An empty string if no error occurred.
</para>
</refsect1>
+ <refsect1>
+ <title>See also</title>
+ <para>
+ <function>mysqli_connect_errno</function>,
+ <function>mysqli_connect_error</function>,
+ <function>mysqli_errno</function>,
+ <function>mysqli_sqlstate</function>
+ </para>
+ </refsect1>
<refsect1>
<title>Example</title>
<para>
<example>
- <title>Using the mysqli_error function</title>
+ <title>Object oriented style</title>
<programlisting role="php">
<![CDATA[
<?php
-
- /* Fail to open a connection */
- $host = "no_such_host";
- $link = mysqli_connect($host, "username", "password") or
- die("Couldn't connect : " . mysqli_error());
-
+$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
+
+if (!$mysqli->query("SET a=1")) {
+ printf("Errorcode: %d\n", $mysqli->error);
+}
+$mysqli->close();
+?>
+]]>
+ </programlisting>
+ </example>
+ <example>
+ <title>Procedural style</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$link = mysqli_connect("localhost", "my_user", "my_password", "test");
+
+if (!mysqli_query($link, "SET a=1")) {
+ printf("Errorcode: %s\n", mysqli_error($link));
+}
+mysqli_close($link);
?>
]]>
</programlisting>
</example>
</para>
- </refsect1>
- <refsect1>
- <title>See also</title>
- <para>
- <function>mysqli_errno</function>, <function>mysqli_sqlstate</function>.
- </para>
- </refsect1>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/reference/mysqli/functions/mysqli-get-metadata.xml b/reference/mysqli/functions/mysqli-get-metadata.xml
index 487d689446..7ff25e0630 100644
--- a/reference/mysqli/functions/mysqli-get-metadata.xml
+++ b/reference/mysqli/functions/mysqli-get-metadata.xml
@@ -1,19 +1,72 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<refentry id="function.mysqli-get-metadata">
<refnamediv>
<refname>mysqli_get_metadata</refname>
- <refpurpose>Retrieves a resultset from a prepared statement for metadata information.</refpurpose>
+ <refpurpose></refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
+ <para>Procedural style:</para>
+ <methodsynopsis>
+ <type>mixed</type><methodname>mysqli_get_metadata</methodname>
+ <methodparam><type>object</type><parameter>stmt</parameter></methodparam>
+ </methodsynopsis>
+ <para>Object oriented style (method):</para>
+ <classsynopsis>
+ <ooclass><classname>stmt</classname></ooclass>
<methodsynopsis>
- <type>string</type><methodname>mysqli_get_metadata</methodname>
- <methodparam><type>object</type><parameter>stmt</parameter></methodparam>
+ <type>mixed</type>
+ <methodname>get_metadata</methodname>
+ <methodparam><type>void</type><parameter></parameter></methodparam>
</methodsynopsis>
-
- &warn.undocumented.func;
-
+ </classsynopsis>
+ <para>
+ If a statement passed to <function>mysqli_prepare</function> is one that produces
+ a result set, <function>mysqli_get_metadata</function> returns the result object
+ that can be used to process the meta information such as total number of fields
+ and individual field information.
+ </para>
+ <note>
+ <para>This result set pointer can be passed as an argument to any of the
+ field-based functions that process result set metadata, such as:
+ <itemizedlist>
+ <listitem><para><function>mysqli_num_fields</function></para></listitem>
+ <listitem><para><function>mysqli_fetch_field</function></para></listitem>
+ <listitem><para><function>mysqli_fetch_field_direct</function></para></listitem>
+ <listitem><para><function>mysqli_fetch_fields</function></para></listitem>
+ <listitem><para><function>mysqli_field_count</function></para></listitem>
+ <listitem><para><function>mysqli_field_seek</function></para></listitem>
+ <listitem><para><function>mysqli_field_tell</function></para></listitem>
+ <listitem><para><function>mysqli_free_result</function></para></listitem>
+ </itemizedlist>
+ </para>
+ </note>
+ <para>
+ The result set structure should be freed when you are done with it,
+ which you can do by passing it to <function>mysqli_free_result</function>
+ </para>
+ <note>
+ <para>
+ The result set returned by <function>mysqli_get_metadata</function> contains only
+ metadata. It does not contain any row results. The rows are obtained by using the
+ statement handle with <function>mysqli_fetch</function>.
+ </para>
+ </note>
+ </refsect1>
+ <refsect1>
+ &reftitle.returnvalues;
+ <para>
+ <function>mysqli_get_metadata</function> returns a result object or &false; if
+ an error occured.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>See also:</title>
+ <para>
+ <function>mysqli_prepare</function>,
+ <function>mysqli_free_result</function>
+ </para>
</refsect1>
</refentry>
diff --git a/reference/mysqli/functions/mysqli-report.xml b/reference/mysqli/functions/mysqli-report.xml
index f4bd446331..c0604817c8 100644
--- a/reference/mysqli/functions/mysqli-report.xml
+++ b/reference/mysqli/functions/mysqli-report.xml
@@ -1,9 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<refentry id="function.mysqli-report">
<refnamediv>
<refname>mysqli_report</refname>
- <refpurpose>Sets report level.</refpurpose>
+ <refpurpose>enables or disables internal report functions</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -11,9 +11,84 @@
<type>bool</type><methodname>mysqli_report</methodname>
<methodparam><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
+ <para>
+ <function>mysqli_report</function> is a powerful function to improve your queries
+ and code during development and testing phase. Depending on the flags it reports
+ errors from mysqli function calls or queries which don't use an index (or use a bad
+ index).
+ </para>
+ <table>
+ <title>Supported flags</title>
+ <tgroup cols='2'>
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><literal>MYSQLI_REPORT_OFF</literal></entry>
+ <entry>Turns reporting off</entry>
+ </row>
+ <row>
+ <entry><literal>MYSQLI_REPORT_ERROR</literal></entry>
+ <entry>Report errors from mysqli function calls</entry>
+ </row>
+ <row>
+ <entry><literal>MYSQLI_REPORT_INDEX</literal></entry>
+ <entry>Report if no index or bad index was used in a query</entry>
+ </row>
+ <row>
+ <entry><literal>MYSQLI_REPORT_ALL</literal></entry>
+ <entry>Set all options (report all)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </refsect1>
+ <refsect1>
+ <title>Return values</title>
+ <para>&return.success;</para>
+ </refsect1>
+ <refsect1>
+ <title>See also</title>
+ <para>
+ <function>mysqli_debug</function>,
+ <function>mysqli_dump_debug_info</function>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Example</title>
+ <para>
+ <example>
+ <title>Object oriented style</title>
+ <programlisting role="php">
+<![CDATA[
- &warn.undocumented.func;
+<?php
+$mysqli = new mysqli("localhost", "my_user", "my_password", "test");
+
+mysqli_report(MYSQLI_REPORT_ALL);
+
+$mysqli->query("DROP TABLE IF EXISTS report");
+$mysqli->query("CREATE TABLE report (a int, b int, index(a))");
+
+$mysqli->query("INSERT INTO report VALUES (1,1), (2,2), (1,3), (2,4), (6,5)");
+
+/* this should report syntax error */
+$mysqli->query("UPDAE report SET a=a+1 WHERE b=3");
+
+/* this should report index warning */
+$mysqli->query("UPDATE report SET a=a+1 WHERE b=3");
+
+$mysqli->close();
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
</refsect1>
</refentry>
@@ -35,5 +110,4 @@ sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
-vi: ts=1 sw=1
-->