<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="pdo-sqlite.createfunction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

<refnamediv>

<refname>Pdo\Sqlite::createFunction</refname>

<refpurpose>

Registriert eine benutzerdefinierte Funktion zur Verwendung in SQL-Anweisungen

</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis role="Pdo\\Sqlite">

<modifier>public</modifier> <type>bool</type><methodname>Pdo\Sqlite::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>

<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>

</methodsynopsis>

<simpara>

This method allows PHP function to be registered with SQLite as a

user-defined function, so that it can be called within SQL queries.

The defined function can be used in any SQL query that allows function calls,

for example <literal>SELECT</literal>, <literal>UPDATE</literal>, or triggers.

</simpara>

<tip>

<simpara>

By using this method it is possible to override native SQL functions.

</simpara>

</tip>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<variablelist>

<varlistentry>

<term><parameter>function_name</parameter></term>

<listitem>

<simpara>

Der Name der Funktion, der in SQL-Anweisungen genutzt wird.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>callback</parameter></term>

<listitem>

<simpara>

Die Callback-Funktion, die die definierte SQL-Funktion verarbeitet.

</simpara>

<note>

<simpara>

Die Callback-Funktionen sollten einen Typ zurückgeben, der von SQLite

verstanden wird, &zb; den

<link linkend="language.types.intro">Skalar-Typ</link>.

</simpara>

</note>

<para>

Diese Funktion muss wie folgt definiert werden:

<methodsynopsis>

<type>mixed</type><methodname><replaceable>callback</replaceable></methodname>

<methodparam><type>mixed</type><parameter>value</parameter></methodparam>

<methodparam rep="repeat"><type>mixed</type><parameter>values</parameter></methodparam>

</methodsynopsis>

<variablelist>

<varlistentry>

<term><parameter>value</parameter></term>

<listitem>

<para>

Das erste Argument, das an die SQL-Funktion übergeben wird.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>values</parameter></term>

<listitem>

<para>

Weitere Argumente, die an die SQL-Funktion übergeben werden.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>num_args</parameter></term>

<listitem>

<simpara>

Die Anzahl von Argumenten, die die SQL-Funktion erwartet.

Ist dieser Parameter <literal>-1</literal>, dann kann die SQL-Funktion

eine beliebige Anzahl von Argumenten annehmen.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>flags</parameter></term>

<listitem>

<simpara>

Eine Bitmaske von Flags.

Zurzeit wird nur <constant>Pdo\Sqlite::DETERMINISTIC</constant>

unterstützt, das angibt, dass die Funktion für dieselben Eingaben

innerhalb einer einzelnen SQL-Anweisung immer dasselbe Ergebnis

zurückgibt.

</simpara>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<simpara>

&return.success;

</simpara>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<example xml:id="pdo-sqlite.createfunction.example.basic">

<title><methodname>Pdo\Sqlite::createFunction</methodname>-Beispiel</title>

<simpara>

In diesem Beispiel wird eine Funktion verwendet, die die SHA256-Prüfsumme

einer Zeichenkette berechnet und anschließend umgekehrt. Wenn die

SQL-Anweisung ausgeführt wird, gibt sie den Wert des von unserer Funktion

umgewandelten Dateinamens zurück.

Die in <varname>$zeilen</varname> zurückgegebenen Daten enthalten das

verarbeitete Ergebnis.

</simpara>

<simpara>

Das Schöne an dieser Technik ist, dass das Ergebnis der Abfrage nicht in

einer &foreach;-Schleife nachbearbeitet werden muss.

</simpara>

<programlisting role="php">

</programlisting>

</example>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<simplelist>

<member><methodname>Pdo\Sqlite::createAggregate</methodname></member>

<member><methodname>Pdo\Sqlite::createCollation</methodname></member>

<member><function>sqlite_create_function</function></member>

<member><function>sqlite_create_aggregate</function></member>

</simplelist>

</refsect1>

</refentry>