Firebird Documentation IndexFirebird 2.5 SprachreferenzStatements der Data Definition (DDL) → EXTERNAL FUNCTION
Firebird Home Firebird Home Zurück: PROCEDUREFirebird Documentation IndexNach oben: Statements der Data Definition (DDL)Weiter: FILTER

EXTERNAL FUNCTION

Inhaltsverzeichnis

DECLARE EXTERNAL FUNCTION
ALTER EXTERNAL FUNCTION
DROP EXTERNAL FUNCTION

ÜBERPRÜFUNGSSTATUS

Alle Abschnitte von diesem Punkt bis zum Ende des Kapitels warten auf eine technische und redaktionelle Überprüfung.

Externe Funktionen, die auch als „benutzerdefinierte Funktionen“ (UDFs) bezeichnet werden, sind Programme, die in einer externen Programmiersprache geschrieben und in dynamisch geladenen Bibliotheken gespeichert werden. Sobald sie in einer Datenbank deklariert sind, werden sie in dynamischen und prozeduralen Anweisungen verfügbar, als wären sie intern in der SQL-Sprache implementiert.

Externe Funktionen erweitern die Möglichkeiten zur Datenverarbeitung mit SQL erheblich. Um eine Funktion für eine Datenbank verfügbar zu machen, wird sie mit der Anweisung DECLARE EXTERNAL FUNCTON deklariert.

Die Bibliothek, die eine Funktion enthält, wird geladen, wenn eine darin enthaltene Funktion aufgerufen wird.

Anmerkung

Externe Funktionen können in mehr als einem Bibliotheks- oder „-Modul“ enthalten sein, wie es in der Syntax erwähnt wird.

DECLARE EXTERNAL FUNCTION

Benutzt für:  Deklarieren einer benutzerdefinierten Funktion (UDF) zur Datenbank

Verfügbar in: DSQL, ESQL

Syntax: 

DECLARE EXTERNAL FUNCTION funcname
[<arg_type_decl> [, <arg_type_decl> ...]]
RETURNS {
  sqltype [BY {DESCRIPTOR | VALUE}] |
  CSTRING(length) |
  PARAMETER param_num }
[FREE_IT]
ENTRY_POINT 'entry_point' MODULE_NAME 'library_name';

<arg_type_decl> ::=
  sqltype [{BY DESCRIPTOR} | NULL] |
  CSTRING(length) [NULL]
        

Tabelle 5.27. DECLARE EXTERNAL FUNCTION Statement-Parameter

Parameter Beschreibung
funcname Funktionsname in der Datenbank. Es kann aus bis zu 31 Zeichen bestehen. Es sollte unter allen internen und externen Funktionsnamen in der Datenbank eindeutig sein und nicht mit dem Namen übereinstimmen, der aus der UDF-Bibliothek über ENTRY_POINT.
entry_point Der exportierte Name der Funktion
library_name Der Name des Moduls (MODULE_NAME, aus dem die Funktion exportiert wird. Dies ist der Name der Datei ohne die „.dll“ oder „.so“-Dateierweiterung.
sqltype SQL-Datentyp. Es kann kein Array oder Array-Element sein
length Die maximale Länge einer nullterminierten Zeichenfolge, angegeben in Bytes
param_num Die Nummer des Eingabeparameters, von 1 in der Liste der Eingabeparameter in der Deklaration nummeriert, beschreibt den Datentyp, der von der Funktion zurückgegeben wird


Die Anweisung DECLARE EXTERNAL FUNCTION stellt eine benutzerdefinierte Funktion in der Datenbank zur Verfügung. UDF-Deklarationen müssen in jeder Datenbank vorgenommen werden, die sie verwenden soll. Es gibt keine Notwendigkeit, UDFs zu deklarieren, die niemals verwendet werden.

Der Name der externen Funktion muss unter allen Funktionsnamen eindeutig sein. Es kann sich vom exportierten Namen der Funktion unterscheiden, wie im ENTRY_POINT-Argument angegeben.

DECLARE EXTERNAL FUNCTION-Eingabeparameter

Die Eingabeparameter der Funktion folgen dem Namen der Funktion und sind durch Kommas getrennt. Für jeden Parameter ist ein SQL-Datentyp angegeben. Arrays können nicht als Funktionsparameter verwendet werden. Neben den SQL-Typen steht der CSTRING-Typ für die Angabe einer nullterminierten Zeichenfolge mit einer maximalen Länge von LENGTH Bytes zur Verfügung.

Standardmäßig werden Eingabeparameter durch Referenz übergeben. Die BY DESCRIPTOR-Klausel kann stattdessen angegeben werden, wenn der Eingabeparameter durch den Deskriptor übergeben wird. Das Übergeben eines Parameters nach Deskriptor ermöglicht die Verarbeitung von NULLs.

Klauseln und Schlüsselwörter

RETURNS-Klausel:  (Erforderlich) gibt den von der Funktion zurückgegebenen Ausgabeparameter an. Eine Funktion ist skalar: Sie gibt nur einen Parameter zurück. Der Ausgabeparameter kann von einem beliebigen SQL-Typ (außer einem Array oder einem Array-Element) oder einer nullterminierten Zeichenfolge (CSTRING) sein. Der Ausgabeparameter kann durch Referenz (Standard), Deskriptor oder Wert übergeben werden. Wenn die Klausel BY DESCRIPTOR angegeben ist, wird der Ausgabeparameter von Deskriptor übergeben. Wenn die BY VALUE-Klausel angegeben ist, wird der Ausgabeparameter über den Wert übergeben.

PARAMETER-Schlüsselwort:  gibt an, dass die Funktion den Wert aus dem Parameter an Stelle param_num zurückgibt. Es ist notwendig, wenn Sie einen Wert des Datentyps BLOB zurückgeben müssen.

FREE_IT Schlüsselwort:  bedeutet, dass der Speicher, der zum Speichern des Rückgabewerts zugewiesen wurde, freigegeben wird, nachdem die Funktion ausgeführt wurde. Sie wird nur verwendet, wenn der Speicher in der UDF dynamisch zugewiesen wurde. In einer solchen UDF muss der Speicher mit Hilfe der Funktion ib_util_malloc aus dem ib_util -Modul zugewiesen werden, was die Kompatibilität mit den im Firebird-Code verwendeten Funktionen und Code der ausgelieferten UDF-Module, zum Zuweisen und Freigeben von Speicher.

ENTRY_POINT-Klausel:  gibt den Namen des Einstiegspunkts (den Namen der importierten Funktion) an, der aus dem Modul exportiert wird.

MODULE_NAME-Klausel:  Definiert den Namen des Moduls, in dem sich die exportierte Funktion befindet. Der Link zum Modul sollte nicht der vollständige Pfad und die Erweiterung der Datei sein, wenn dies vermieden werden kann. Wenn sich das Modul am Standardspeicherort (im Unterverzeichnis ../UDF des Firebird-Serverstammes) oder an einem in firebird.conf explizit konfigurierten Speicherort befindet, ist es einfacher, die Datenbank zwischen verschiedene Plattformen. Der Parameter UDFAccess in der Datei firebird.conf ermöglicht die Konfiguration von Zugriffsbeschränkungen für externe Funktionsmodule.

 Jeder Benutzer, der mit der Datenbank verbunden ist, kann eine externe Funktion (UDF) deklarieren.

Beispiele zuv Verwendung von DECLARE EXTERNAL FUNCTION: 

  1. Deklarieren der externen AddDate-Funktion im fbudf-Modul. Die Ein- und Ausgabeparameter werden als Referenz übergeben.
    DECLARE EXTERNAL FUNCTION addDay
    TIMESTAMP, INT
    RETURNS TIMESTAMP
    ENTRY_POINT 'addDay' MODULE_NAME 'fbudf';
              
  2. Deklaration der externen Invl-Funktion im fbudf-Modul. Die Ein- und Ausgabeparameter werden vom Deskriptor übergeben.
    DECLARE EXTERNAL FUNCTION invl
    INT BY DESCRIPTOR, INT BY DESCRIPTOR
    RETURNS INT BY DESCRIPTOR
    ENTRY_POINT 'idNvl' MODULE_NAME 'fbudf';
              
  3. Declaring the isLeapYear external function located in the fbudf module. The input parameter is passed by reference, while the output parameter is passed by value.
    DECLARE EXTERNAL FUNCTION isLeapYear
    TIMESTAMP
    RETURNS INT BY VALUE
    ENTRY_POINT 'isLeapYear' MODULE_NAME 'fbudf';
              
  4. Deklaration der externen Funktion i64Truncate im fbudf-Modul. Die Ein- und Ausgabeparameter werden vom Deskriptor übergeben. Der zweite Parameter der Funktion wird als Rückgabewert verwendet.
    DECLARE EXTERNAL FUNCTION i64Truncate
    NUMERIC(18) BY DESCRIPTOR, NUMERIC(18) BY DESCRIPTOR
    RETURNS PARAMETER 2
    ENTRY_POINT 'fbtruncate' MODULE_NAME 'fbudf';
              

Siehe auch:  ALTER EXTERNAL FUNCTION, DROP EXTERNAL FUNCTION

ALTER EXTERNAL FUNCTION

Benutzt für:  Ändern des Eintrittspunkts und / oder des Modulnamens für eine benutzerdefinierte Funktion (UDF)

Verfügbar in: DSQL

Syntax: 

ALTER EXTERNAL FUNCTION funcname
[ENTRY_POINT 'new_entry_point']
[MODULE_NAME 'new_library_name'];
        

Tabelle 5.28. ALTER EXTERNAL FUNCTION Statement-Parameter

Parameter Beschreibung
funcname Funktionsname in der Datenbank
new_entry_point Der neue exportierte Name der Funktion
new_library_name Der neue Name des Moduls (MODULE_NAME, aus dem die Funktion exportiert wird, ist der Name der Datei ohne die „.dll“- oder „.so“-Dateierweiterung.


Die Anweisung ALTER EXTERNAL FUNCTION ändert den Eintrittspunkt und / oder den Modulnamen für eine benutzerdefinierte Funktion (UDF). Vorhandene Abhängigkeiten bleiben erhalten, nachdem die Anweisung mit der Änderung [s] ausgeführt wurde.

Die ENTRY_POINT-Klausel:  dient zur Angabe des neuen Eintrittspunktes (der Name der Funktion, die aus dem Modul exportiert wird).

Die MODULE_NAME-Klausel:  Gibt den neuen Namen des Moduls an, in dem sich die exportierte Funktion befindet.

 Jeder an die Datenbank angeschlossene Benutzer kann den Eintrittspunkt und den Modulnamen ändern.

Beispiele für die Verwendung von ALTER EXTERNAL FUNCTION: 

  1. Ändern des Einstiegspunkts für eine externe Funktion
    ALTER EXTERNAL FUNCTION invl ENTRY_POINT 'intNvl';
                
  2. Ändern des Modulnamens für eine externe Funktion
    ALTER EXTERNAL FUNCTION invl MODULE_NAME 'fbudf2';
                

Siehe auch:  DECLARE EXTERNAL FUNCTION, DROP EXTERNAL FUNCTION

DROP EXTERNAL FUNCTION

Benutzt für:  Entfernen einer benutzerdefinierten Funktion (UDF) aus einer Datenbank

Verfügbar in: DSQL, ESQL

Syntax: 

DROP EXTERNAL FUNCTION funcname
        

Tabelle 5.29. DROP EXTERNAL FUNCTION Statement-Parameter

Parameter Beschreibung
funcname Funktionsname in der Datenbank


Die Anweisung DROP EXTERNAL FUNCTION löscht die Deklaration einer benutzerdefinierten Funktion aus der Datenbank. Wenn es Abhängigkeiten von der externen Funktion gibt, schlägt die Anweisung fehl und der entsprechende Fehler wird ausgelöst.

 Jeder mit der Datenbank verbundene Benutzer kann die Deklaration einer internen Funktion löschen.

Beispiel der Verwendung von DROP EXTERNAL FUNCTION:  Löschen der Deklaration der addDay-Funktion.

DROP EXTERNAL FUNCTION addDay;
          

Siehe auch:  DECLARE EXTERNAL FUNCTION

Zurück: PROCEDUREFirebird Documentation IndexNach oben: Statements der Data Definition (DDL)Weiter: FILTER
Firebird Documentation IndexFirebird 2.5 SprachreferenzStatements der Data Definition (DDL) → EXTERNAL FUNCTION