prepare.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 4d0440105fcba962378f6ad614fa09265bbf6875 Maintainer: seros Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="mysqli-stmt.prepare" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>mysqli_stmt::prepare</refname>
  <refname>mysqli_stmt_prepare</refname>
  <refpurpose>Preparar una sentencia SQL para su ejecución</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <para>&style.oop;</para>
  <methodsynopsis role="oop">
   <type>mixed</type><methodname>mysqli_stmt::prepare</methodname>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
  </methodsynopsis>
  <para>&style.procedural;</para>
  <methodsynopsis>
   <type>bool</type><methodname>mysqli_stmt_prepare</methodname>
   <methodparam><type>mysqli_stmt</type><parameter>stmt</parameter></methodparam>
   <methodparam><type>string</type><parameter>query</parameter></methodparam>
  </methodsynopsis>
  <para>
   Prepara una consulta the SQL apuntada por la consulta de cadena terminada en null.
  </para>
  <para>
   Los marcadores de parámetros deben estar vinculados a las variables de la apliación usando
   <function>mysqli_stmt_bind_param</function> y/o 
   <function>mysqli_stmt_bind_result</function> antes de ejecutar la
   sentencia u obtener filas.
  </para>
  <note>
   <para>
    En el caso de que se pase una sentencia a
    <function>mysqli_stmt_prepare</function> que sea más grande que
    <literal>max_allowed_packet</literal> del servidor, los códigos de
    error devueltos serán diferentes, dependiendo de si se usa el Controlador
    Nativo de MysQL (<literal>mysqlnd</literal>) o la biblioteca Cliente de MySQL
    (<literal>libmysqlclient</literal>). El comportamiento es como sigue:
   </para>
   <itemizedlist>
    <listitem>
     <para>
      <literal>mysqlnd</literal> en Linux devuelve un código de error 1153.
      El mensaje de error significa <quote>obtenido un paquete mas grande que
      <literal>max_allowed_packet</literal> bytes</quote>.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>mysqlnd</literal> en Windows devuelve un código de error 2006.
      Este mensaje de error significa <quote>el servidor se ha ido</quote>.
     </para>
    </listitem>
    <listitem>
     <para>
      <literal>libmysqlclient</literal> en todas las plataformas devuelve un código de error
      2006. Este mensaje de error significa <quote>el servidor se ha
      ido</quote>.
     </para>
    </listitem>
   </itemizedlist>
  </note>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    &mysqli.stmt.description;
    <varlistentry>
     <term><parameter>query</parameter></term>
     <listitem>
      <para>
       La consulta, como una cadena. Debe consistir en una sentencia SQL única.
      </para>
      <para>
       Se puede incluir uno o más marcadores de parámetros en la senetencia SQL
       embebiendo el carácter de signo de interrogación (<literal>?</literal>) en la
       posición apropiada.
      </para>
      <note>
       <para>
        No se debería añadir un punto y coma terminal o <literal>\g</literal>
        a la sentencia.
       </para>
      </note>
      <note>
       <para>
        Los marcadores únicamente son legales en ciertos lugares de las sentencias SQL.
        Por ejemplo, están permitidos en la lista de VALUES() de una sentencia INSERT
        (para especificar los valores de las columnas de una fila), o en una comparación en
        una cláusula WHERE para especificar un valor de comparación.
       </para>
       <para>
        Sin embargo, no están permitidos en identificadores (como nombres de tablas o columnas),
        en la lista de selección que nombra a las columnas a ser devueltas por una sentencia SELECT),
        o para especificar ambos operandos de un operador binario como signo igual
        <literal>=</literal>. La última restricción es necesaria debido a que sería imposible
        determinar el tipo de parámetro. En general, los parámetros son legales únicamente en sentencias de
        Lenguaje de Manipulación de Datos (DML), y no en sentencias de Lenguaje de Definición de Datos
        (DDL).
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>&style.oop;</title>
   <programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("localhost", "my_usuario", "mi_contraseña", "world");

/* comprobar la conexión */
if (mysqli_connect_errno()) {
    printf("Falló la conexión: %s\n", mysqli_connect_error());
    exit();
}

$ciudad = "Amersfoort";

/* crear una sentencia preparada */
$sentencia =  $mysqli->stmt_init();
if ($sentencia->prepare("SELECT District FROM City WHERE Name=?")) {

    /* vincular los parámetros para los marcadores */
    $sentencia->bind_param("s", $ciudad);

    /* ejecutar la consulta */
    $sentencia->execute();

    /* vincular las variables de resultados */
    $sentencia->bind_result($distrito);

    /* obtener el valor */
    $sentencia->fetch();

    printf("%s está en el distrito de %s\n", $ciudad, $distrito);

    /* cerrar la sentencia */
    $sentencia->close();
}

/* cerrar la conexión */
$mysqli->close();
?>
]]>
   </programlisting>
  </example>
  <example>
   <title>&style.procedural;</title>
   <programlisting role="php">
<![CDATA[
<?php
$enlace = mysqli_connect("localhost", "my_usuario", "mi_contraseña", "world");

/* comprobar la conexión */
if (mysqli_connect_errno()) {
    printf("Falló la conexión: %s\n", mysqli_connect_error());
    exit();
}

$ciudad = "Amersfoort";

/* crear una sentencia preparada */
$sentencia = mysqli_stmt_init($enlace);
if (mysqli_stmt_prepare($sentencia, 'SELECT District FROM City WHERE Name=?')) {

    /* vincular los parámetros para los marcadores */
    mysqli_stmt_bind_param($sentencia, "s", $ciudad);

    /* ejecutar la consulta */
    mysqli_stmt_execute($sentencia);

    /* vincular las variables de resultados */
    mysqli_stmt_bind_result($sentencia, $distrito);

    /* obtener el valor */
    mysqli_stmt_fetch($sentencia);

    printf("%s está en el distrito de %s\n", $ciudad, $distrito);

    /* cerrar la sentencia */
    mysqli_stmt_close($sentencia);
}

/* cerrar la conexión */
mysqli_close($enlace);
?>
]]>
   </programlisting>
   &examples.outputs;
   <screen>
<![CDATA[
Amersfoort está en el distrito de Utrecht
]]>
   </screen>
  </example>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>mysqli_stmt_init</function></member>
    <member><function>mysqli_stmt_execute</function></member>
    <member><function>mysqli_stmt_fetch</function></member>
    <member><function>mysqli_stmt_bind_param</function></member>
    <member><function>mysqli_stmt_bind_result</function></member>
    <member><function>mysqli_stmt_get_result</function></member>
    <member><function>mysqli_stmt_close</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
-->