archived-doc-es/reference/sqlite/functions/sqlite-create-function.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 656d1610af1a960d87c8b7056e54d0d4c75fb123 Maintainer: jpberdejo Status: ready -->
<refentry xml:id="function.sqlite-create-function" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>sqlite_create_function</refname>
  <refname>SQLiteDatabase::createFunction</refname>
  <refpurpose>
   Registra una función "regular" definida por el usuario para ser usada en sentencias SQL
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>void</type><methodname>sqlite_create_function</methodname>
   <methodparam><type>resource</type><parameter>dbhandle</parameter></methodparam>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter><initializer>-1</initializer></methodparam>
  </methodsynopsis>
  <para>&style.oop; (método):</para>
  <methodsynopsis>
   <modifier>public</modifier> <type>void</type><methodname>SQLiteDatabase::createFunction</methodname>
   <methodparam><type>string</type><parameter>function_name</parameter></methodparam>
   <methodparam><type>callable</type><parameter>callback</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>num_args</parameter><initializer>-1</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>sqlite_create_function</function> permite registrar una función PHP con SQLite como un <acronym>UDF</acronym> (User Defined
   Function), para así poder ser llamada desde dentro de sus sentencias SQL.
  </para>
  <para>
   La UDF puede ser usada en cualquier sentencia SQL que pueda llamar a funciones, tales como sentencias SELECT y UPDATE, y también en triggers.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dbhandle</parameter></term>
     <listitem>
      <para>
       El recurso de base de datos devuelto desde <function>sqlite_open</function>.
       Este parámetro no es requerido cuando se usa el método "Orientado a objetos".
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>function_name</parameter></term>
     <listitem>
      <para>
 El nombre de la función que se va a usar en las sentencias SQL.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>callback</parameter></term>
     <listitem>
      <para>
       Función de retorno para manejar la función SQL definida.
      </para>
      <note>
       <simpara>
        Las funciones de retorno deben devolver un tipo que SQLite sea capaz de entender (por ejemplo <link linkend="language.types.intro">tipo escalar</link>).
       </simpara>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num_args</parameter></term>
     <listitem>
      <para>
 Sugerencia para el intérprete de SQLite si la función acepta un número predeterminado de argumentos.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  &sqlite.param-compat;
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.void;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>sqlite_create_function</function></title>
    <programlisting role="php">
<![CDATA[
<?php
function md5_and_reverse($string)
{
    return strrev(md5($string));
}

if ($dbhandle = sqlite_open('mysqlitedb', 0666, $sqliteerror)) {
    
    sqlite_create_function($dbhandle, 'md5rev', 'md5_and_reverse', 1);
    
    $sql  = 'SELECT md5rev(filename) FROM files';
    $rows = sqlite_array_query($dbhandle, $sql);
} else {
    echo 'Error opening sqlite db: ' . $sqliteerror;
    exit;
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>En este ejemplo tenemos una función que calcula el valor md5 de un string, y luego lo pone del revés. Cuando se ejecuta la sentencia SQL, devuelve el valor del nombre de fichero transformado por otra función. Los datos devueltos en <parameter>$rows</parameter> contienen el resultado de la consulta procesada.
  </para>
  <para>
   La belleza de esta técnica es que no se necesita procesar el resultado utilizando un loop &foreach; despues de que se hayan consultado los datos.
  </para>
  <para>
   PHP registra una función especial llamada <literal>php</literal>
cuando la base de datos se abre por primera vez. La función php puede ser usada para llamar cualquier función PHP sin tener que registrarla primero.
  </para>
  <para>
   <example>
    <title>Ejemplo de uso de la función PHP</title>
    <programlisting role="php">
<![CDATA[
<?php
$rows = sqlite_array_query($dbhandle, "SELECT php('md5', filename) from files");
?>
]]>
    </programlisting>
    <para>
     Este ejemplo llamará la función <function>md5</function> en cada columna 
     <literal>filename</literal> en la base de datos y devolverá el resultado en <parameter>$rows</parameter>
    </para>
   </example>
  </para>
  <note>
   <para>
    Por razones de funcionamiento, PHP no codifica/descodifica automaticamente datos binarios pasados para y desde los UDFs. Es necesario codificar/descodificar manualmente los parámetros y valores devueltos si se necesita procesar los datos binarios de esta manera.
    Echar un vistazo a <function>sqlite_udf_encode_binary</function>
    y <function>sqlite_udf_decode_binary</function> para más información.
   </para>
  </note>
  <tip>
   <para>
    No se recomienda usar UDFs para manejar el proceso de datos binarios, a menos que el alto rendimiento no sea un requisito indispensable para su aplicación.
   </para>
  </tip>
  <tip>
   <para>
   Puede utilizar <function>sqlite_create_function</function> y
    <function>sqlite_create_aggregate</function> para reemplazar las funciones SQL nativas de SQLite.
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>sqlite_create_aggregate</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
 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
 -->