archived-doc-es/reference/mysql/functions/mysql-query.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: bd3486422338656009b890c04ff132f1c1a61176 Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xml:id="function.mysql-query" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysql_query</refname>
  <refpurpose>Enviar una consulta MySQL</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
  <warning>
   &mysql.alternative.note;
   <simplelist role="alternatives">
    <member><function>mysqli_query</function></member>
    <member><methodname>PDO::query</methodname></member>
   </simplelist>
  </warning>
 </refsynopsisdiv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>mixed</type><methodname>mysql_query</methodname>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
   <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter><initializer>NULL</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>mysql_query</function> envía una única consulta (no hay soporte para
   múltiples consultas) a la base de datos
   actualmente activa en el servidor asociado con el
   identificador de enlace especificado por <parameter>link_identifier</parameter>.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>query</parameter></term>
     <listitem>
      <para>
       Una consulta SQL
      </para>
      <para>
       El string de la consulta no debería terminar con un punto y coma.
       Los datos insertados en la consulta deberían estar <link
       linkend="function.mysql-real-escape-string">correctamente escapados</link>.
      </para>
     </listitem>
    </varlistentry>
    &mysql.linkid.description;
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Para SELECT, SHOW, DESCRIBE, EXPLAIN y otras sentencias que retornan un conjunto de resultados,
   <function>mysql_query</function> 
   devuelve un <type>resource</type> en caso de éxito, o &false; en caso de
   error.
  </para>
  <para>
   Para otros tipos de sentencias SQL, tales como INSERT, UPDATE, DELETE, DROP, etc,
   <function>mysql_query</function> devuelve &true; en caso de éxito
   o &false; en caso de error.
  </para>
  <para>
   El conjunto de resultados devuelto debería ser pasado a 
   <function>mysql_fetch_array</function>, y otras
   funciones para manejar las tablas del resultado, para acceder a los datos retornados.
  </para>
  <para>
   Use <function>mysql_num_rows</function> para averiguar cuántas filas
   fueron devueltas por la sentencia SELECT, o 
   <function>mysql_affected_rows</function> para averiguar cuántas
   filas fueron afectadas por las sentencias DELETE, INSERT, REPLACE,
   o UPDATE.
  </para>
  <para>
   <function>mysql_query</function> también fallará y retornará &false;
   si el usuario no está autorizado para acceder a la/s tabla/s a la/s que hace
   referencia la consulta.
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Consulta inválida</title>
    <para>
     La siguiente consulta no es sintácticamente válida, por lo que
     <function>mysql_query</function> fallará y retornará &false;.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
$resultado = mysql_query('SELECT * WHERE 1=1');
if (!$resultado) {
    die('Consulta no válida: ' . mysql_error());
}

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Consulta válida</title>
    <para>
     La siguiente consulta es válida, por lo que <function>mysql_query</function>
     retornará un <type>resource</type>.
    </para>
    <programlisting role="php">
<![CDATA[
<?php
// Lo siguiente podría ser proporcionado por un usuario, como por ejemplo
$nombre = 'fred';
$apellido  = 'fox';

// Formular la consulta
// Este es el mejor método para formular una consulta SQL
// Para más ejemplos, consulte mysql_real_escape_string()
$consulta = sprintf("SELECT nombre, apellido, direccion, edad FROM amigos 
    WHERE nombre='%s' AND apellido='%s'",
    mysql_real_escape_string($nombre),
    mysql_real_escape_string($apellido));

// Ejecutar la consulta
$resultado = mysql_query($consulta);

// Comprobar el resultado
// Lo siguiente muestra la consulta real enviada a MySQL, y el error ocurrido. Útil para depuración.
if (!$resultado) {
    $mensaje  = 'Consulta no válida: ' . mysql_error() . "\n";
    $mensaje .= 'Consulta completa: ' . $consulta;
    die($mensaje);
}

// Usar el resultado
// Si se intenta imprimir $resultado no será posible acceder a la información del recurso
// Se debe usar una de las funciones de resultados de mysql
// Consulte también mysql_result(), mysql_fetch_array(), mysql_fetch_row(), etc.
while ($fila = mysql_fetch_assoc($resultado)) {
    echo $fila['nombre'];
    echo $fila['apellido'];
    echo $fila['direccion'];
    echo $fila['edad'];
}

// Liberar los recursos asociados con el conjunto de resultados
// Esto se ejecutado automáticamente al finalizar el script.
mysql_free_result($resultado);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysql_connect</function></member>
    <member><function>mysql_error</function></member>
    <member><function>mysql_real_escape_string</function></member>
    <member><function>mysql_result</function></member>
    <member><function>mysql_fetch_assoc</function></member>
    <member><function>mysql_unbuffered_query</function></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->