Ingebouwde Firebird 3.0-functies (SDF, ook wel Server Defined Functions genoemd)

Hieronder ingebouwde functies (behalve DECODE) worden alleen gebruikt als er geen

UDF met dezelfde naam is gedeclareerd.

Deze keuze tussen UDF of systeemfunctie wordt bepaald bij het compileren van de

statement en wordt niet gewijzigd als de statement wordt opgeslagen (trigger / SP).

Auteurs:

Adriano dos Santos Fernandes <[email protected]>

Oleg Loa <[email protected]>

Alexey Karyakin <[email protected]>

Claudio Valderrama C. <cvalde at usa.net>

---

ABS

---

Functie:

Retourneert de absolute waarde van een getal.

Formaat:

ABS( <getal> )

Voorbeeld:

select abs(amount) from transactions;

----

ACOS

----

Functie:

Retourneert de boogcosinus van een getal.

Formaat:

ACOS( <getal> )

Opmerkingen:

Het argument voor ACOS moet in het bereik -1 tot 1 liggen en retourneert een waarde in

het bereik 0 tot PI.

Voorbeeld:

select acos(x) from y;

---–

ACOSH

---–

Functie:

Retourneert de hyperbolische boogcosinus van een getal (uitgedrukt in radialen).

Formaat:

ACOSH( <getal> )

Voorbeeld:

select acosh(x) from y;

---——-

ASCII_CHAR

---——-

Functie:

Retourneert het ASCII-teken met de opgegeven code.

Formaat:

ASCII\_CHAR( <getal> )

Opmerkingen:

Het argument voor ASCII\_CHAR moet in het bereik 0 tot 255 liggen en retourneert een waarde

met de tekenset NONE.

Voorbeeld:

select ascii\_char(x) from y;

---——

ASCII_VAL

---——

Functie:

Retourneert de ASCII-code van het eerste teken van de opgegeven string.

Formaat:

ASCII\_VAL( <string> )

Opmerkingen:

1) Retourneert 0 als de string leeg is.

2) Geeft een foutmelding als het eerste teken multibyte is.

Voorbeeld:

select ascii\_val(x) from y;

----

ASIN

----

Functie:

Retourneert de boogsinus van een getal.

Formaat:

ASIN( <getal> )

Opmerkingen:

Het argument voor ASIN moet in het bereik -1 tot 1 liggen en retourneert een waarde in

het bereik -PI / 2 tot PI / 2.

Voorbeeld:

select asin(x) from y;

---–

ASINH

---–

Functie:

Retourneert de hyperbolische boogsinus van een getal (uitgedrukt in radialen).

Formaat:

ASINH( <getal> )

Voorbeeld:

select asinh(x) from y;

----

ATAN

----

Functie:

Retourneert de boogtangens van een getal.

Formaat:

ATAN( <getal> )

Opmerkingen:

Retourneert een waarde in het bereik -PI / 2 tot PI / 2.

Voorbeeld:

select atan(x) from y;

---–

ATAN2

---–

Functie:

Retourneert de boogtangens van het eerste getal / het tweede getal.

Formaat:

ATAN( <getal>, <getal> )

Opmerkingen:

Retourneert een waarde in het bereik -PI tot PI.

Voorbeeld:

select atan2(x, y) from z;

---–

ATANH

---–

Functie:

Retourneert de hyperbolische boogtangens van een getal (uitgedrukt in radialen).

Formaat:

ATANH( <getal> )

Voorbeeld:

select atanh(x) from y;

---—-

BIN_AND

---—-

Functie:

Retourneert het resultaat van een binaire AND-bewerking uitgevoerd op alle argumenten.

Formaat:

BIN\_AND( <getal>, <getal> \[, <getal> ...\] )

Voorbeeld:

select bin\_and(flags, 1) from x;

---—-

BIN_NOT

---—-

Functie:

Retourneert het resultaat van een bitsgewijze NOT-bewerking uitgevoerd op zijn argument.

Formaat:

BIN\_NOT( <getal> )

Voorbeeld:

select bin\_not(flags) from x;

---—

BIN_OR

---—

Functie:

Retourneert het resultaat van een binaire OR-bewerking uitgevoerd op alle argumenten.

Formaat:

BIN\_OR( <getal>, <getal> \[, <getal> ...\] )

Voorbeeld:

select bin\_or(flags1, flags2) from x;

---—-

BIN_SHL

---—-

Functie:

Retourneert het resultaat van een binaire shift-links-bewerking uitgevoerd op de argumenten (eerste << tweede).

Formaat:

BIN\_SHL( <getal>, <getal> )

Voorbeeld:

select bin\_shl(flags1, 1) from x;

---—-

BIN_SHR

---—-

Functie:

Retourneert het resultaat van een binaire shift-rechts-bewerking uitgevoerd op de argumenten (eerste >> tweede).

Formaat:

BIN\_SHR( <getal>, <getal> )

Voorbeeld:

select bin\_shr(flags1, 1) from x;

---—-

BIN_XOR

---—-

Functie:

Retourneert het resultaat van een binaire XOR-bewerking uitgevoerd op alle argumenten.

Formaat:

BIN\_XOR( <getal>, <getal> \[, <getal> ...\] )

Voorbeeld:

select bin\_xor(flags1, flags2) from x;

---———–

CEIL | CEILING

---———–

Functie:

Retourneert een waarde die het kleinste gehele getal vertegenwoordigt dat groter

is dan of gelijk is aan het invoerargument.

Formaat:

{ CEIL \| CEILING }( <getal> )

Voorbeeld:

1) select ceil(val) from x;

2) select ceil(2.1), ceil(-2.1) from rdb$database;  -- retourneert 3, -2

---———

CHAR_TO_UUID

---———

Functie:

Converteert de CHAR(32) ASCII-weergave van een UUID

(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) naar de CHAR(16) OCTETS

weergave (geoptimaliseerd voor opslag).

Formaat:

CHAR\_TO\_UUID( <string> )

Belangrijk (voor big-endian servers):

Er is ontdekt dat vóór Firebird 2.5.2 CHAR\_TO\_UUID en UUID\_TO\_CHAR

onjuist werken op big-endian servers. Op deze machines worden bytes/tekens verwisseld en op

verkeerde posities geplaatst tijdens het converteren. Deze bug is verholpen in 2.5.2 en 3.0, maar dat betekent dat deze

functies nu andere waarden retourneren (voor dezelfde invoerparameter) dan voorheen.

Voorbeeld:

select char\_to\_uuid('93519227-8D50-4E47-81AA-8F6678C096A1') from rdb$database;

Zie ook: GEN_UUID en UUID_TO_CHAR

---

COS

---

Functie:

Retourneert de cosinus van een hoek (uitgedrukt in radialen).

Formaat:

COS( <getal> )

Opmerkingen:

De hoek wordt opgegeven in radialen en retourneert een waarde in het bereik -1 tot 1.

Voorbeeld:

select cos(x) from y;

----

COSH

----

Functie:

Retourneert de hyperbolische cosinus van een hoek (uitgedrukt in radialen).

Formaat:

COSH( <getal> )

Voorbeeld:

select cosh(x) from y;

---

COT

---

Functie:

Retourneert 1 / tan(argument).

Formaat:

COT( <getal> )

Voorbeeld:

select cot(x) from y;

---—-

DATEADD

---—-

Functie:

Retourneert een datum/tijd/timestamp-waarde verhoogd (of verlaagd, indien negatief)

met de opgegeven hoeveelheid tijd.

Formaat:

DATEADD( <getal> <timestamp\_deel> TO <datum\_tijd> )

DATEADD( <timestamp\_deel>, <getal>, <datum\_tijd> )

timestamp\_deel ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Opmerkingen:

1) WEEKDAY en YEARDAY kunnen niet worden gebruikt. Dat heeft geen zin.

2) YEAR, MONTH en DAY kunnen niet worden gebruikt met tijdwaarden.

3) Alle timestamp\_deel-waarden kunnen worden gebruikt met timestamp-waarden.

4) Bij gebruik van uur, minuut, seconde en milliseconde voor DATEADD en datums, moet de toegevoegde of

    afgetrokken hoeveelheid ten minste één dag bedragen om effect te hebben (d.w.z. het toevoegen van 23 uur aan een datum

    verhoogt deze niet).

Voorbeeld:

select dateadd(-1 day to current\_date) as yesterday

    from rdb$database;

---—–

DATEDIFF

---—–

Functie:

Retourneert een exacte numerieke waarde die de hoeveelheid tijd van de eerste

datum/tijd/timestamp-waarde tot de tweede vertegenwoordigt.

Formaat:

DATEDIFF( <timestamp\_deel> FROM <datum\_tijd> TO <datum\_tijd> )

DATEDIFF( <timestamp\_deel>, <datum\_tijd>, <datum\_tijd> )

timestamp\_deel ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Opmerkingen:

1) Retourneert een positieve waarde als de tweede waarde groter is dan de eerste,

   negatief wanneer de eerste groter is of nul wanneer ze gelijk zijn.

2) Vergelijking van datum met tijdwaarden is ongeldig.

3) WEEKDAY en YEARDAY kunnen niet worden gebruikt. Dat heeft geen zin.

4) YEAR, MONTH en DAY kunnen niet worden gebruikt met tijdwaarden.

5) Alle timestamp\_deel-waarden kunnen worden gebruikt met timestamp-waarden.

Voorbeeld:

select datediff(week from cast('yesterday' as timestamp) - 7 to current\_timestamp)

    from rdb$database;

---—

DECODE

---—

Functie:

DECODE is een snelkoppeling naar de CASE ... WHEN ... ELSE-expressie.

Formaat:

DECODE( <expressie>, <zoekwaarde>, <resultaat> \[ , <zoekwaarde>, <resultaat> ... \] \[, <standaardwaarde> \]

Voorbeeld:

select decode(state, 0, 'deleted', 1, 'active', 'unknown') from things;

---

EXP

---

Functie:

Retourneert de exponentiële e tot het argument.

Formaat:

EXP( <getal> )

Voorbeeld:

select exp(x) from y;

---–

FLOOR

---–

Functie:

Retourneert een waarde die het grootste gehele getal vertegenwoordigt dat kleiner

is dan of gelijk is aan het invoerargument.

Formaat:

FLOOR( <getal> )

Voorbeeld:

1) select floor(val) from x;

2) select floor(2.1), floor(-2.1) from rdb$database;  -- retourneert 2, -3

---—–

GEN_UUID

---—–

Functie:

Retourneert een universeel uniek nummer in CHAR(16) OCTETS-type.

Formaat:

GEN\_UUID()

Belangrijk:

Vóór Firebird 2.5.2 retourneerde GEN\_UUID volledig willekeurige strings. Dit is niet conform

RFC-4122 (UUID-specificatie).

Dit is verholpen in Firebird 2.5.2 en 3.0. Nu retourneert GEN\_UUID een conforme UUID versie 4

string, waarbij sommige bits zijn gereserveerd en de andere willekeurig zijn. De stringnotatie van een conforme

UUID is XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, waarbij 4 vast is (versie) en Y is 8, 9, A of B.

Voorbeeld:

insert into records (id) value (gen\_uuid());

Zie ook: CHAR_TO_UUID en UUID_TO_CHAR

----

HASH

----

Functie:

Retourneert een HASH van een string.

Formaat:

HASH( <string> )

Voorbeeld:

select hash(x) from y;

----

LEFT

----

Functie:

Retourneert de substring van een opgegeven lengte die aan het begin van een string verschijnt.

Formaat:

LEFT( <string>, <getal> )

Voorbeeld:

select left(name, char\_length(name) - 10)

    from people

    where name like '% FERNANDES';

–

Functie:

Retourneert de natuurlijke logaritme van een getal.

Formaat:

LN( <getal> )

Voorbeeld:

select ln(x) from y;

---

LOG

---

Functie:

LOG(x, y) retourneert de logaritme met grondtal x van y.

Formaat:

LOG( <getal>, <getal> )

Voorbeeld:

select log(x, 10) from y;

---–

LOG10

---–

Functie:

Retourneert de logaritme met grondtal tien van een getal.

Formaat:

LOG10( <getal> )

Voorbeeld:

select log10(x) from y;

----

LPAD

----

Functie:

LPAD(string1, lengte, string2) voegt string2 toe aan het begin van

string1 totdat de lengte van de resulterende string gelijk wordt aan lengte.

Formaat:

LPAD( <string>, <getal> \[, <string> \] )

Opmerkingen:

1) Als de tweede string wordt weggelaten, is de standaardwaarde één spatie.

2) De tweede string wordt afgekapt wanneer de resulterende string

   groter wordt dan lengte.

3) De eerste string wordt afgekapt als de lengte groter is dan de lengte

   parameter.

Voorbeeld:

select lpad(x, 10) from y;

---—–

MAXVALUE

---—–

Functie:

Retourneert de maximale waarde van een lijst met waarden.

Formaat:

MAXVALUE( <waarde> \[, <waarde> ...\] )

Voorbeeld:

select maxvalue(v1, v2, 10) from x;

---—–

MINVALUE

---—–

Functie:

Retourneert de minimale waarde van een lijst met waarden.

Formaat:

MINVALUE( <waarde> \[, <waarde> ...\] )

Voorbeeld:

select minvalue(v1, v2, 10) from x;

---

MOD

---

Functie:

MOD(X, Y) retourneert het restdeel van de deling van X door Y.

Formaat:

MOD( <getal>, <getal> )

Voorbeeld:

select mod(x, 10) from y;

---—-

OVERLAY

---—-

Functie:

OVERLAY( <string1> PLACING <string2> FROM <start> \[ FOR <lengte> \] ) retourneert

string1 waarbij de substring FROM start FOR lengte wordt vervangen door string2.

Formaat:

OVERLAY( <string> PLACING <string> FROM <getal> \[ FOR <getal> \] )

Opmerkingen:

1) Als <lengte> niet is opgegeven, wordt CHAR\_LENGTH( <string2> ) geïmpliceerd.

2) De OVERLAY-functie is gelijk aan:

       SUBSTRING(<string1> FROM 1 FOR <start> - 1) \|\|

       <string2> \|\|

       SUBSTRING(<string1> FROM <start> + <lengte>)

–

Functie:

Retourneert de PI-constante (3.1459...).

Formaat:

PI()

Voorbeeld:

val = PI();

---—–

POSITION

---—–

Functie:

Retourneert de positie van de eerste string binnen de tweede string, beginnend bij

een offset (of vanaf het begin wanneer weggelaten). Wanneer niet gevonden, retourneert 0.

Formaat:

POSITION( <string> IN <string> )

POSITION( <string>, <string> \[, <number> \] )

Voorbeeld:

select rdb$relation\_name

    from rdb$relations

    where position('RDB$' IN rdb$relation\_name) = 1;

---–

POWER

---–

Functie:

POWER(X, Y) retourneert X tot de macht Y.

Formaat:

POWER( <number>, <number> )

Voorbeeld:

select power(x, 10) from y;

----

RAND

----

Functie:

Retourneert een willekeurig getal tussen 0 en 1.

Formaat:

RAND()

Voorbeeld:

select \* from x order by rand();

---—-

REPLACE

---—-

Functie:

REPLACE(searched, find, replacement) vervangt alle voorkomens van "find"

in "searched" door "replacement".

Formaat:

REPLACE( <string>, <string>, <string> )

Voorbeeld:

select replace(x, ' ', ',') from y;

---—-

REVERSE

---—-

Functie:

Retourneert een string in omgekeerde volgorde.

Formaat:

REVERSE( <value> )

Opmerkingen:

REVERSE is een nuttige functie om strings van rechts naar links te indexeren.

Voorbeeld:

create index people\_email on people computed by (reverse(email));

select \* from people where reverse(email) starting with reverse('.br');

---–

RIGHT

---–

Functie:

RIGHT(string, length)

Retourneert de substring van een opgegeven lengte die aan het einde van een string verschijnt.

Formaat:

RIGHT( <string>, <number> )

Voorbeeld:

select right(rdb$relation\_name, char\_length(rdb$relation\_name) - 4)

    from rdb$relations

    where rdb$relation\_name like 'RDB$%';

---–

ROUND

---–

Functie:

ROUND(number, scale)

Retourneert een getal afgerond op de opgegeven schaal.

Formaat:

ROUND( <number> \[, <number> \] )

Opmerkingen:

Als de schaal (tweede parameter) negatief is, wordt het gehele deel van

de waarde afgerond. Bijv.: ROUND(123.456, -1) retourneert 120.000.

Voorbeelden:

select round(salary \* 1.1, 0) from people;

----

RPAD

----

Functie:

RPAD(string1, length, string2) voegt string2 toe aan het einde van

string1 totdat de lengte van de resulterende string gelijk wordt aan length.

Formaat:

RPAD( <string>, <number> \[, <string> \] )

Opmerkingen:

1) Als de tweede string wordt weggelaten, is de standaardwaarde één spatie.

2) De tweede string wordt afgekapt wanneer de resulterende string

   groter wordt dan length.

3) De eerste string wordt afgekapt als de lengte groter is dan de length-parameter.

Voorbeeld:

select rpad(x, 10) from y;

----

SIGN

----

Functie:

Retourneert 1, 0 of -1, afhankelijk van of de invoerwaarde respectievelijk positief, nul of

negatief is.

Formaat:

SIGN( <number> )

Voorbeeld:

select sign(x) from y;

---

SIN

---

Functie:

Retourneert de sinus van een hoek (uitgedrukt in radialen).

Formaat:

SIN( <number> )

Opmerkingen:

Het argument voor SIN moet in radialen worden opgegeven.

Voorbeeld:

select sin(x) from y;

----

SINH

----

Functie:

Retourneert de hyperbolische sinus van een hoek (uitgedrukt in radialen).

Formaat:

SINH( <number> )

Voorbeeld:

select sinh(x) from y;

----

SQRT

----

Functie:

Retourneert de vierkantswortel van een getal.

Formaat:

SQRT( <number> )

Voorbeeld:

select sqrt(x) from y;

---

TAN

---

Functie:

Retourneert de tangens van een hoek (uitgedrukt in radialen).

Formaat:

TAN( <number> )

Opmerkingen:

Het argument voor TAN moet in radialen worden opgegeven.

Voorbeeld:

select tan(x) from y;

----

TANH

----

Functie:

Retourneert de hyperbolische tangens van een hoek (uitgedrukt in radialen).

Formaat:

TANH( <number> )

Voorbeeld:

select tanh(x) from y;

---–

TRUNC

---–

Functie:

TRUNC(number, scale)

Retourneert het integrale deel (tot de opgegeven schaal) van een getal.

Formaat:

TRUNC( <number> \[, <number> \] )

Opmerkingen:

Als de schaal (tweede parameter) negatief is, wordt het gehele deel van

de waarde afgekapt. Bijv.: TRUNC(123.456, -1) retourneert 120.000.

Voorbeeld:

1) select trunc(x) from y;

2) select trunc(-2.8), trunc(2.8) from rdb$database;  -- retourneert -2, 2

3) select trunc(987.65, 1), trunc(987.65, -1) from rdb$database;  -- retourneert 987.60, 980.00

---———

UUID_TO_CHAR

---———

Functie:

Converteert een CHAR(16) OCTETS UUID (die wordt geretourneerd door GEN\_UUID) naar de

CHAR(32) ASCII-representatie (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

Formaat:

UUID\_TO\_CHAR( <string> )

Belangrijk (voor big-endian servers):

Er is ontdekt dat vóór Firebird 2.5.2, CHAR\_TO\_UUID en UUID\_TO\_CHAR onjuist werken

op big-endian servers. Op deze machines worden bytes/tekens verwisseld en op

verkeerde posities geplaatst tijdens het converteren. Deze bug is opgelost in 2.5.2 en 3.0, maar dat betekent dat deze

functies nu andere waarden retourneren (voor dezelfde invoerparameter) dan voorheen.

Voorbeeld:

select uuid\_to\_char(gen\_uuid()) from rdb$database;

Zie ook: GEN_UUID en CHAR_TO_UUID