Integrierte Firebird 3.0-Funktionen (SDF, auch bekannt als Server Defined Functions)
Eingebaute Funktionen unten (außer DECODE) werden nur verwendet, wenn keine
UDF mit demselben Namen deklariert ist.
Diese Wahl zwischen UDF oder Systemfunktion wird beim Kompilieren der
Anweisung getroffen und nicht geändert, wenn die Anweisung gespeichert wird (Trigger / SP).
Autoren:
Adriano dos Santos Fernandes <[email protected]>
Oleg Loa <[email protected]>
Alexey Karyakin <[email protected]>
Claudio Valderrama C. <cvalde at usa.net>
---
ABS
---
Funktion:
Gibt den absoluten Wert einer Zahl zurück.
Format:
ABS( <Zahl> )
Beispiel:
select abs(amount) from transactions;
----
ACOS
----
Funktion:
Gibt den Arkuskosinus einer Zahl zurück.
Format:
ACOS( <Zahl> )
Hinweise:
Das Argument für ACOS muss im Bereich -1 bis 1 liegen und gibt einen Wert im
Bereich 0 bis PI zurück.
Beispiel:
select acos(x) from y;
---–
ACOSH
---–
Funktion:
Gibt den hyperbolischen Arkuskosinus einer Zahl zurück (ausgedrückt in Bogenmaß).
Format:
ACOSH( <Zahl> )
Beispiel:
select acosh(x) from y;
---——-
ASCII_CHAR
---——-
Funktion:
Gibt das ASCII-Zeichen mit dem angegebenen Code zurück.
Format:
ASCII\_CHAR( <Zahl> )
Hinweise:
Das Argument für ASCII\_CHAR muss im Bereich 0 bis 255 liegen und gibt einen Wert
mit dem Zeichensatz NONE zurück.
Beispiel:
select ascii\_char(x) from y;
---——
ASCII_VAL
---——
Funktion:
Gibt den ASCII-Code des ersten Zeichens der angegebenen Zeichenkette zurück.
Format:
ASCII\_VAL( <Zeichenkette> )
Hinweise:
1) Gibt 0 zurück, wenn die Zeichenkette leer ist.
2) Wirft einen Fehler, wenn das erste Zeichen mehrbyte ist.
Beispiel:
select ascii\_val(x) from y;
----
ASIN
----
Funktion:
Gibt den Arkussinus einer Zahl zurück.
Format:
ASIN( <Zahl> )
Hinweise:
Das Argument für ASIN muss im Bereich -1 bis 1 liegen und gibt einen Wert im
Bereich -PI / 2 bis PI / 2 zurück.
Beispiel:
select asin(x) from y;
---–
ASINH
---–
Funktion:
Gibt den hyperbolischen Arkussinus einer Zahl zurück (ausgedrückt in Bogenmaß).
Format:
ASINH( <Zahl> )
Beispiel:
select asinh(x) from y;
----
ATAN
----
Funktion:
Gibt den Arkustangens einer Zahl zurück.
Format:
ATAN( <Zahl> )
Hinweise:
Gibt einen Wert im Bereich -PI / 2 bis PI / 2 zurück.
Beispiel:
select atan(x) from y;
---–
ATAN2
---–
Funktion:
Gibt den Arkustangens der ersten Zahl / der zweiten Zahl zurück.
Format:
ATAN( <Zahl>, <Zahl> )
Hinweise:
Gibt einen Wert im Bereich -PI bis PI zurück.
Beispiel:
select atan2(x, y) from z;
---–
ATANH
---–
Funktion:
Gibt den hyperbolischen Arkustangens einer Zahl zurück (ausgedrückt in Bogenmaß).
Format:
ATANH( <Zahl> )
Beispiel:
select atanh(x) from y;
---—-
BIN_AND
---—-
Funktion:
Gibt das Ergebnis einer binären UND-Verknüpfung zurück, die auf alle Argumente angewendet wird.
Format:
BIN\_AND( <Zahl>, <Zahl> \[, <Zahl> ...\] )
Beispiel:
select bin\_and(flags, 1) from x;
---—-
BIN_NOT
---—-
Funktion:
Gibt das Ergebnis einer bitweisen NICHT-Verknüpfung zurück, die auf ihr Argument angewendet wird.
Format:
BIN\_NOT( <Zahl> )
Beispiel:
select bin\_not(flags) from x;
---—
BIN_OR
---—
Funktion:
Gibt das Ergebnis einer binären ODER-Verknüpfung zurück, die auf alle Argumente angewendet wird.
Format:
BIN\_OR( <Zahl>, <Zahl> \[, <Zahl> ...\] )
Beispiel:
select bin\_or(flags1, flags2) from x;
---—-
BIN_SHL
---—-
Funktion:
Gibt das Ergebnis einer binären Linksverschiebung zurück, die auf die Argumente angewendet wird (erste << zweite).
Format:
BIN\_SHL( <Zahl>, <Zahl> )
Beispiel:
select bin\_shl(flags1, 1) from x;
---—-
BIN_SHR
---—-
Funktion:
Gibt das Ergebnis einer binären Rechtsverschiebung zurück, die auf die Argumente angewendet wird (erste >> zweite).
Format:
BIN\_SHR( <Zahl>, <Zahl> )
Beispiel:
select bin\_shr(flags1, 1) from x;
---—-
BIN_XOR
---—-
Funktion:
Gibt das Ergebnis einer binären XOR-Verknüpfung zurück, die auf alle Argumente angewendet wird.
Format:
BIN\_XOR( <Zahl>, <Zahl> \[, <Zahl> ...\] )
Beispiel:
select bin\_xor(flags1, flags2) from x;
---———–
CEIL | CEILING
---———–
Funktion:
Gibt einen Wert zurück, der die kleinste ganze Zahl darstellt, die größer
oder gleich dem Eingabeargument ist.
Format:
{ CEIL \| CEILING }( <Zahl> )
Beispiel:
1) select ceil(val) from x;
2) select ceil(2.1), ceil(-2.1) from rdb$database; -- gibt 3, -2 zurück
---———
CHAR_TO_UUID
---———
Funktion:
Konvertiert die CHAR(32) ASCII-Darstellung einer UUID
(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) in die CHAR(16) OCTETS
Darstellung (optimiert für die Speicherung).
Format:
CHAR\_TO\_UUID( <Zeichenkette> )
Wichtig (für Big-Endian-Server):
Es wurde festgestellt, dass vor Firebird 2.5.2 CHAR\_TO\_UUID und UUID\_TO\_CHAR auf
Big-Endian-Servern falsch funktionieren. Auf diesen Maschinen werden Bytes/Zeichen vertauscht und
bei der Konvertierung an falsche Positionen gesetzt. Dieser Fehler wurde in 2.5.2 und 3.0 behoben, aber das bedeutet, dass
diese Funktionen jetzt andere Werte (für denselben Eingabeparameter) als zuvor zurückgeben.
Beispiel:
select char\_to\_uuid('93519227-8D50-4E47-81AA-8F6678C096A1') from rdb$database;
Siehe auch: GEN_UUID und UUID_TO_CHAR
---
COS
---
Funktion:
Gibt den Kosinus eines Winkels zurück (ausgedrückt in Bogenmaß).
Format:
COS( <Zahl> )
Hinweise:
Der Winkel wird in Bogenmaß angegeben und gibt einen Wert im Bereich -1 bis 1 zurück.
Beispiel:
select cos(x) from y;
----
COSH
----
Funktion:
Gibt den hyperbolischen Kosinus eines Winkels zurück (ausgedrückt in Bogenmaß).
Format:
COSH( <Zahl> )
Beispiel:
select cosh(x) from y;
---
COT
---
Funktion:
Gibt 1 / tan(Argument) zurück.
Format:
COT( <Zahl> )
Beispiel:
select cot(x) from y;
---—-
DATEADD
---—-
Funktion:
Gibt einen Datums-/Zeit-/Zeitstempelwert zurück, der um die angegebene
Zeitspanne erhöht (oder bei negativem Wert verringert) wurde.
Format:
DATEADD( <Zahl> <Zeitstempel\_Teil> TO <Datum\_Zeit> )
DATEADD( <Zeitstempel\_Teil>, <Zahl>, <Datum\_Zeit> )
Zeitstempel\_Teil ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }
Hinweise:
1) WEEKDAY und YEARDAY können nicht verwendet werden. Das ergibt keinen Sinn.
2) YEAR, MONTH und DAY können nicht mit Zeitwerten verwendet werden.
3) Alle Zeitstempel\_Teil-Werte können mit Zeitstempelwerten verwendet werden.
4) Bei Verwendung von Stunde, Minute, Sekunde und Millisekunde für DATEADD und Datumsangaben sollte die hinzugefügte oder
subtrahierte Menge mindestens einen Tag betragen, um eine Wirkung zu erzielen (d. h. das Hinzufügen von 23 Stunden zu einem Datum
erhöht es nicht).
Beispiel:
select dateadd(-1 day to current\_date) as yesterday
from rdb$database;
---—–
DATEDIFF
---—–
Funktion:
Gibt einen exakten numerischen Wert zurück, der die Zeitspanne vom ersten
Datums-/Zeit-/Zeitstempelwert zum zweiten darstellt.
Format:
DATEDIFF( <Zeitstempel\_Teil> FROM <Datum\_Zeit> TO <Datum\_Zeit> )
DATEDIFF( <Zeitstempel\_Teil>, <Datum\_Zeit>, <Datum\_Zeit> )
Zeitstempel\_Teil ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }
Hinweise:
1) Gibt einen positiven Wert zurück, wenn der zweite Wert größer als der erste ist,
negativ, wenn der erste größer ist, oder null, wenn sie gleich sind.
2) Der Vergleich von Datum mit Zeitwerten ist ungültig.
3) WEEKDAY und YEARDAY können nicht verwendet werden. Das ergibt keinen Sinn.
4) YEAR, MONTH und DAY können nicht mit Zeitwerten verwendet werden.
5) Alle Zeitstempel\_Teil-Werte können mit Zeitstempelwerten verwendet werden.
Beispiel:
select datediff(week from cast('yesterday' as timestamp) - 7 to current\_timestamp)
from rdb$database;
---—
DECODE
---—
Funktion:
DECODE ist eine Abkürzung für den CASE ... WHEN ... ELSE-Ausdruck.
Format:
DECODE( <Ausdruck>, <Suche>, <Ergebnis> \[ , <Suche>, <Ergebnis> ... \] \[, <Standard> \]
Beispiel:
select decode(state, 0, 'deleted', 1, 'active', 'unknown') from things;
---
EXP
---
Funktion:
Gibt die Exponentialfunktion e hoch das Argument zurück.
Format:
EXP( <Zahl> )
Beispiel:
select exp(x) from y;
---–
FLOOR
---–
Funktion:
Gibt einen Wert zurück, der die größte ganze Zahl darstellt, die kleiner
oder gleich dem Eingabeargument ist.
Format:
FLOOR( <Zahl> )
Beispiel:
1) select floor(val) from x;
2) select floor(2.1), floor(-2.1) from rdb$database; -- gibt 2, -3 zurück
---—–
GEN_UUID
---—–
Funktion:
Gibt eine universelle eindeutige Nummer im Typ CHAR(16) OCTETS zurück.
Format:
GEN\_UUID()
Wichtig:
Vor Firebird 2.5.2 gab GEN\_UUID vollständig zufällige Zeichenketten zurück. Dies entspricht nicht
dem RFC-4122 (UUID-Spezifikation).
Dies wurde in Firebird 2.5.2 und 3.0 behoben. Jetzt gibt GEN\_UUID eine konforme UUID-Version-4-
Zeichenkette zurück, bei der einige Bits reserviert sind und die anderen zufällig sind. Das Zeichenkettenformat einer konformen
UUID ist XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, wobei 4 fest ist (Version) und Y 8, 9, A oder B ist.
Beispiel:
insert into records (id) value (gen\_uuid());
Siehe auch: CHAR_TO_UUID und UUID_TO_CHAR
----
HASH
----
Funktion:
Gibt einen HASH einer Zeichenkette zurück.
Format:
HASH( <Zeichenkette> )
Beispiel:
select hash(x) from y;
----
LEFT
----
Funktion:
Gibt die Teilzeichenkette einer angegebenen Länge zurück, die am Anfang einer Zeichenkette erscheint.
Format:
LEFT( <Zeichenkette>, <Zahl> )
Beispiel:
select left(name, char\_length(name) - 10)
from people
where name like '% FERNANDES';
–
LN
–
Funktion:
Gibt den natürlichen Logarithmus einer Zahl zurück.
Format:
LN( <Zahl> )
Beispiel:
select ln(x) from y;
---
LOG
---
Funktion:
LOG(x, y) gibt den Logarithmus von y zur Basis x zurück.
Format:
LOG( <Zahl>, <Zahl> )
Beispiel:
select log(x, 10) from y;
---–
LOG10
---–
Funktion:
Gibt den Logarithmus einer Zahl zur Basis zehn zurück.
Format:
LOG10( <Zahl> )
Beispiel:
select log10(x) from y;
----
LPAD
----
Funktion:
LPAD(Zeichenkette1, Länge, Zeichenkette2) fügt Zeichenkette2 am Anfang von
Zeichenkette1 hinzu, bis die Länge der Ergebniszeichenkette gleich der Länge wird.
Format:
LPAD( <Zeichenkette>, <Zahl> \[, <Zeichenkette> \] )
Hinweise:
1) Wenn die zweite Zeichenkette weggelassen wird, ist der Standardwert ein Leerzeichen.
2) Die zweite Zeichenkette wird abgeschnitten, wenn die Ergebniszeichenkette
größer als die Länge wird.
3) Die erste Zeichenkette wird abgeschnitten, wenn ihre Länge größer als der Längen-
Parameter ist.
Beispiel:
select lpad(x, 10) from y;
---—–
MAXVALUE
---—–
Funktion:
Gibt den Maximalwert einer Liste von Werten zurück.
Format:
MAXVALUE( <Wert> \[, <Wert> ...\] )
Beispiel:
select maxvalue(v1, v2, 10) from x;
---—–
MINVALUE
---—–
Funktion:
Gibt den Minimalwert einer Liste von Werten zurück.
Format:
MINVALUE( <Wert> \[, <Wert> ...\] )
Beispiel:
select minvalue(v1, v2, 10) from x;
---
MOD
---
Funktion:
MOD(X, Y) gibt den Restteil der Division von X durch Y zurück.
Format:
MOD( <Zahl>, <Zahl> )
Beispiel:
select mod(x, 10) from y;
---—-
OVERLAY
---—-
Funktion:
OVERLAY( <Zeichenkette1> PLACING <Zeichenkette2> FROM <Start> \[ FOR <Länge> \] ) gibt
Zeichenkette1 zurück, wobei die Teilzeichenkette VON Start FÜR Länge durch Zeichenkette2 ersetzt wird.
Format:
OVERLAY( <Zeichenkette> PLACING <Zeichenkette> FROM <Zahl> \[ FOR <Zahl> \] )
Hinweise:
1) Wenn <Länge> nicht angegeben ist, wird CHAR\_LENGTH( <Zeichenkette2> ) impliziert.
2) Die OVERLAY-Funktion ist äquivalent zu:
SUBSTRING(<Zeichenkette1> FROM 1 FOR <Start> - 1) \|\|
<Zeichenkette2> \|\|
SUBSTRING(<Zeichenkette1> FROM <Start> + <Länge>)
–
PI
–
Funktion:
Gibt die PI-Konstante (3.1459...) zurück.
Format:
PI()
Beispiel:
val = PI();
---—–
POSITION
---—–
Funktion:
Gibt die Position der ersten Zeichenkette innerhalb der zweiten Zeichenkette zurück, beginnend bei
ein Offset (oder ab dem Anfang, wenn nicht angegeben). Wenn nicht gefunden, wird 0 zurückgegeben.
Format:
POSITION( <string> IN <string> )
POSITION( <string>, <string> \[, <number> \] )
Beispiel:
select rdb$relation\_name
from rdb$relations
where position('RDB$' IN rdb$relation\_name) = 1;
---–
POWER
---–
Funktion:
POWER(X, Y) gibt X hoch Y zurück.
Format:
POWER( <number>, <number> )
Beispiel:
select power(x, 10) from y;
----
RAND
----
Funktion:
Gibt eine Zufallszahl zwischen 0 und 1 zurück.
Format:
RAND()
Beispiel:
select \* from x order by rand();
---—-
REPLACE
---—-
Funktion:
REPLACE(searched, find, replacement) ersetzt alle Vorkommen von "find"
in "searched" durch "replacement".
Format:
REPLACE( <string>, <string>, <string> )
Beispiel:
select replace(x, ' ', ',') from y;
---—-
REVERSE
---—-
Funktion:
Gibt eine Zeichenkette in umgekehrter Reihenfolge zurück.
Format:
REVERSE( <value> )
Hinweise:
REVERSE ist eine nützliche Funktion, um Zeichenketten von rechts nach links zu indizieren.
Beispiel:
create index people\_email on people computed by (reverse(email));
select \* from people where reverse(email) starting with reverse('.br');
---–
RIGHT
---–
Funktion:
RIGHT(string, length)
Gibt die Teilzeichenkette einer angegebenen Länge zurück, die am Ende einer Zeichenkette erscheint.
Format:
RIGHT( <string>, <number> )
Beispiel:
select right(rdb$relation\_name, char\_length(rdb$relation\_name) - 4)
from rdb$relations
where rdb$relation\_name like 'RDB$%';
---–
ROUND
---–
Funktion:
ROUND(number, scale)
Gibt eine Zahl zurück, die auf die angegebene Skala gerundet ist.
Format:
ROUND( <number> \[, <number> \] )
Hinweise:
Wenn die Skala (zweiter Parameter) negativ ist, wird der ganzzahlige Teil
des Wertes gerundet. Bsp.: ROUND(123.456, -1) gibt 120.000 zurück.
Beispiele:
select round(salary \* 1.1, 0) from people;
----
RPAD
----
Funktion:
RPAD(string1, length, string2) fügt string2 an das Ende von
string1 an, bis die Länge der Ergebniszeichenkette gleich length ist.
Format:
RPAD( <string>, <number> \[, <string> \] )
Hinweise:
1) Wenn die zweite Zeichenkette weggelassen wird, ist der Standardwert ein Leerzeichen.
2) Die zweite Zeichenkette wird abgeschnitten, wenn die Ergebniszeichenkette
größer als length wird.
3) Die erste Zeichenkette wird abgeschnitten, wenn ihre Länge größer als der length-
Parameter ist.
Beispiel:
select rpad(x, 10) from y;
----
SIGN
----
Funktion:
Gibt 1, 0 oder -1 zurück, je nachdem, ob der Eingabewert positiv, null oder
negativ ist.
Format:
SIGN( <number> )
Beispiel:
select sign(x) from y;
---
SIN
---
Funktion:
Gibt den Sinus eines Winkels (in Radiant ausgedrückt) zurück.
Format:
SIN( <number> )
Hinweise:
Das Argument für SIN muss in Radiant angegeben werden.
Beispiel:
select sin(x) from y;
----
SINH
----
Funktion:
Gibt den hyperbolischen Sinus eines Winkels (in Radiant ausgedrückt) zurück.
Format:
SINH( <number> )
Beispiel:
select sinh(x) from y;
----
SQRT
----
Funktion:
Gibt die Quadratwurzel einer Zahl zurück.
Format:
SQRT( <number> )
Beispiel:
select sqrt(x) from y;
---
TAN
---
Funktion:
Gibt den Tangens eines Winkels (in Radiant ausgedrückt) zurück.
Format:
TAN( <number> )
Hinweise:
Das Argument für TAN muss in Radiant angegeben werden.
Beispiel:
select tan(x) from y;
----
TANH
----
Funktion:
Gibt den hyperbolischen Tangens eines Winkels (in Radiant ausgedrückt) zurück.
Format:
TANH( <number> )
Beispiel:
select tanh(x) from y;
---–
TRUNC
---–
Funktion:
TRUNC(number, scale)
Gibt den ganzzahligen Teil (bis zur angegebenen Skala) einer Zahl zurück.
Format:
TRUNC( <number> \[, <number> \] )
Hinweise:
Wenn die Skala (zweiter Parameter) negativ ist, wird der ganzzahlige Teil
des Wertes abgeschnitten. Bsp.: TRUNC(123.456, -1) gibt 120.000 zurück.
Beispiel:
1) select trunc(x) from y;
2) select trunc(-2.8), trunc(2.8) from rdb$database; -- gibt -2, 2 zurück
3) select trunc(987.65, 1), trunc(987.65, -1) from rdb$database; -- gibt 987.60, 980.00 zurück
---———
UUID_TO_CHAR
---———
Funktion:
Konvertiert eine CHAR(16) OCTETS UUID (die von GEN\_UUID zurückgegeben wird) in die
CHAR(32) ASCII-Darstellung (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).
Format:
UUID\_TO\_CHAR( <string> )
Wichtig (für Big-Endian-Server):
Es wurde festgestellt, dass vor Firebird 2.5.2 CHAR\_TO\_UUID und UUID\_TO\_CHAR auf
Big-Endian-Servern falsch funktionieren. Auf diesen Maschinen werden Bytes/Zeichen vertauscht und
bei der Konvertierung an falsche Positionen gesetzt. Dieser Fehler wurde in 2.5.2 und 3.0 behoben, was bedeutet, dass
diese Funktionen nun andere Werte (für denselben Eingabeparameter) als zuvor zurückgeben.
Beispiel:
select uuid\_to\_char(gen\_uuid()) from rdb$database;
Siehe auch: GEN_UUID und CHAR_TO_UUID