php-doc-en/reference/mysql/functions/mysql-query.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- 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>
      <methodparam choice="opt"><type>int</type><parameter>result_mode</parameter></methodparam>
     </methodsynopsis>
    <para>
     <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.
    </para>
    <para>
     The optional <parameter>result_mode</parameter> parameter
     can be MYSQL_USE_RESULT and MYSQL_STORE_RESULT. It
     defaults to MYSQL_STORE_RESULT, so the result is buffered.
     See also <function>mysql_unbuffered_query</function> for the
     counterpart of this behaviour.
    </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,
     <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.
    </para>
    <para>
     The following query is syntactically invalid, so
     <function>mysql_query</function> fails and returns &false;:
     <example>
      <title><function>mysql_query</function></title>
      <programlisting role="php">
<![CDATA[
<php
$result = mysql_query("SELECT * WHERE 1=1")
    or 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>
      <programlisting role="php">
<![CDATA[
<?php
$result = mysql_query("SELECT my_col FROM my_tbl")
    or die("Invalid query: " . mysql_error());
?>
]]>
      </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 statment 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>
    <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_connect</function>.
    </para>
   </refsect1>
  </refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
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
-->