aidan Tue Dec 28 07:06:26 2004 EDT
Modified files:
/phpdoc/en/reference/mysql/functions mysql-query.xml
Log:
Removed the second useless example, and replaced it with a best-practice
query. Moved the information around so it was more continuous, not scattered
from top to bottom (the result of many edits to add tidbits I assume). Also -
applied the new docskel.
http://cvs.php.net/diff.php/phpdoc/en/reference/mysql/functions/mysql-query.xml?r1=1.10&r2=1.11&ty=u
Index: phpdoc/en/reference/mysql/functions/mysql-query.xml
diff -u phpdoc/en/reference/mysql/functions/mysql-query.xml:1.10
phpdoc/en/reference/mysql/functions/mysql-query.xml:1.11
--- phpdoc/en/reference/mysql/functions/mysql-query.xml:1.10 Fri Feb 20
12:36:42 2004
+++ phpdoc/en/reference/mysql/functions/mysql-query.xml Tue Dec 28 07:06:25 2004
@@ -1,49 +1,100 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/mysql.xml, last change in rev 1.62 -->
<refentry id="function.mysql-query">
<refnamediv>
<refname>mysql_query</refname>
<refpurpose>Send a MySQL query</refpurpose>
</refnamediv>
- <refsect1>
- <title>Description</title>
- <methodsynopsis>
- <type>resource</type><methodname>mysql_query</methodname>
-
<methodparam><type>string</type><parameter>query</parameter></methodparam>
- <methodparam
choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
- </methodsynopsis>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>resource</type><methodname>mysql_query</methodname>
+ <methodparam><type>string</type><parameter>query</parameter></methodparam>
+ <methodparam
choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
+ </methodsynopsis>
<para>
- <function>mysql_query</function> sends a query to the currently
+ <function>mysql_query</function> sends a query (to the currently
active database on the server that's associated with the
- specified link identifier. If
- <parameter>link_identifier</parameter> isn't specified, the last
- opened link is assumed. If no link is open, the function tries
- to establish a link as if <function>mysql_connect</function> was
- called with no arguments, and use it. The result of the query is buffered.
- </para>
- <note>
- <para>
- The query string should not end with a semicolon.
- </para>
- </note>
- <para>
- Only for SELECT,SHOW,EXPLAIN or DESCRIBE statements
- <function>mysql_query</function>
- returns a resource identifier or &false; if the query was
- not executed correctly. For other type of SQL statements,
+ specified <parameter>link_identifier</parameter>).
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>query</parameter></term>
+ <listitem>
+ <para>
+ A SQL query
+ </para>
+ <para>
+ The query string should not end with a semicolon.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>link_identifier</parameter></term>
+ <listitem>
+ <para>
+ A link identifier, as returned by <function>mysql_connect</function>.
+ </para>
+ <para>
+ If <parameter>link_identifier</parameter> isn't specified, the last
+ opened link is assumed. If no link is open, the function tries
+ to establish a link as if <function>mysql_connect</function> was
+ called with no arguments, and use it. The result of the query is
buffered.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ For SELECT, SHOW, DESCRIBE or EXPLAIN statements,
+ <function>mysql_query</function>
+ returns a <type>resource</type> on success, and &false; on
+ error.
+ </para>
+ <para>
+ For other type of SQL statements, UPDATE, DELETE, DROP, etc,
<function>mysql_query</function> returns &true; on success
- and &false; on error. A non-&false; return value
- means that the query was legal and could be executed by
- the server. It does not indicate anything about the number of
- rows affected or returned. It is perfectly possible for a query
- to succeed but affect no rows or return no rows.
+ and &false; on error.
</para>
<para>
- The following query is syntactically invalid, so
- <function>mysql_query</function> fails and returns &false;:
+ The returned result resource should be passed to
+ <function>mysql_fetch_array</function>, and other
+ functions for dealing with result tables, to access the returned data.
+ </para>
+ <para>
+ Use <function>mysql_num_rows</function> to find out how many rows
+ were returned for a SELECT statement or
+ <function>mysql_affected_rows</function> to find out how many
+ rows were affected by a DELETE, INSERT, REPLACE, or UPDATE
+ statement.
+ </para>
+ <para>
+ <function>mysql_query</function> will also fail and return &false;
+ if the user does not have permission to access the table(s) referenced by
+ the query.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
<example>
- <title><function>mysql_query</function> example</title>
+ <title>Invalid Query</title>
+ <para>
+ The following query is syntactically invalid, so
+ <function>mysql_query</function> fails and returns &false;.
+ </para>
<programlisting role="php">
<![CDATA[
<?php
@@ -51,65 +102,73 @@
if (!$result) {
die('Invalid query: ' . mysql_error());
}
+
?>
]]>
</programlisting>
</example>
</para>
<para>
- The following query is semantically invalid if
- <literal>my_col</literal> is not a column in the table
- <literal>my_tbl</literal>, so <function>mysql_query</function>
- fails and returns &false;:
<example>
- <title><function>mysql_query</function></title>
+ <title>Valid Query</title>
+ <para>
+ The following query is valid, so <function>mysql_query</function>
+ returns a <type>resource</type>.
+ </para>
<programlisting role="php">
<![CDATA[
<?php
-$result = mysql_query('SELECT my_col FROM my_tbl');
+// This could be supplied by a user, for example
+$firstname = 'fred';
+$lastname = 'fox';
+
+// Formulate Query
+// This is the best way to perform a SQL query
+// For more examples, see mysql_real_escape_string()
+$query = sprintf("SELECT firstname, lastname, address, age FROM friends WHERE
firstname='%s' AND lastname='%s'",
+ mysql_real_escape_string($firstname),
+ mysql_real_escape_string($lastname));
+
+// Perform Query
+$result = mysql_query($query);
+
+// Check result
+// This shows the actual query sent to MySQL, and the error. Useful for
debugging.
if (!$result) {
- die('Invalid query: ' . mysql_error());
+ $message = 'Invalid query: ' . mysql_error() . "\n";
+ $message .= 'Whole query: ' . $query;
+ die($message);
}
+
+// Use result
+// Attempting to print $result won't allow access to information in the
resource
+// One of the mysql result functions must be used
+// See also mysql_result(), mysql_fetch_array(), mysql_fetch_row(), etc.
+while ($row = mysql_fetch_assoc($result)) {
+ echo $row['firstname'];
+ echo $row['lastname'];
+ echo $row['address'];
+ echo $row['age'];
+}
+
+// Free the resources associated with the result set
+// This is done automatically at the end of the script
+mysql_free_result($result);
?>
]]>
</programlisting>
</example>
</para>
- <para>
- <function>mysql_query</function> will also fail and return &false;
- if you don't have permission to access the table(s) referenced by
- the query.
- </para>
- <para>
- Assuming the query succeeds, you can call
- <function>mysql_num_rows</function> to find out how many rows
- were returned for a SELECT statement or
- <function>mysql_affected_rows</function> to find out how many
- rows were affected by a DELETE, INSERT, REPLACE, or UPDATE
- statement.
- </para>
- <para>
- Only for SELECT,SHOW,DESCRIBE or EXPLAIN statements,
- <function>mysql_query</function>
- returns a new result identifier that you can pass to
- <function>mysql_fetch_array</function> and other
- functions dealing with result tables. When you are done with the
- result set, you can free the resources associated with it by
- calling <function>mysql_free_result</function>. Although, the
- memory will automatically be freed at the end of the script's
- execution.
- </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
<para>
See also
- <function>mysql_num_rows</function>,
- <function>mysql_affected_rows</function>,
<function>mysql_unbuffered_query</function>,
- <function>mysql_free_result</function>,
- <function>mysql_fetch_array</function>,
- <function>mysql_fetch_row</function>,
<function>mysql_fetch_assoc</function>,
- <function>mysql_result</function>,
- <function>mysql_select_db</function> and
+ <function>mysql_error</function>,
+ <function>mysql_result</function> and
<function>mysql_connect</function>.
</para>
</refsect1>
