Guide Du Langage SQL De Firebird 5.0 | Fonctions Conditionnelles

`IIF()`

Disponible en

DSQL, PSQL

Syntaxe

IIF (<condition>, ResultT, ResultF)

Table 1. paramètres de fonction IIF
Paramètre	Description
condition	Une expression du type logique.
resultT	Valeur de retour si condition est vraie.
resultF	Valeur de retour si condition est fausse.

type de résultat de retour

dépend des types d’arguments d’entrée

La fonction IIF a trois arguments. Si le premier argument est vrai, le résultat est le deuxième paramètre, sinon le résultat est le troisième paramètre.

L’opérateur IIF peut également être comparé à l’opérateur triple “?:” dans les langages C-like.

Note	Essentiellement, la fonction `IIF` est un raccourci de l’opérateur `CASE`. CASE WHEN <condition> THEN resultT ELSE resultF END

Exemple `IIF`

Example 1. Utilisation de la fonction IIF

SELECT IIF(SEX = 'M', 'Sir', 'Madam') FROM CUSTOMERS

Voir aussi :

CASE.

`MAXVALUE()`

Disponible en

DSQL, PSQL

Syntaxe

MAXVALUE (<expr1> [, ... , <exprN> ])

Table 1. paramètres de fonction `MAXVALUE`
Paramètre	Description
expr1 … exprN	Expressions de tout type compatible.

Le type de résultat renvoyé :

est le même que le premier argument de expr1.

Renvoie la valeur maximale d’une liste de nombres, de chaînes de caractères ou de paramètres de type DATE / TIME / TIMESTAMP.

Note	Si un ou plusieurs paramètres d’entrée sont `NULL`, le résultat de la fonction `MAXVALUE` est également `NULL` contrairement à la fonction d’agrégation `MAX`.

Exemple `MAXVALUE`

Example 1. Utilisation de la fonction MAXVALUE

SELECT MAXVALUE(PRICE_1, PRICE_2) AS PRICE
FROM PRICELIST

Voir aussi :

[fblangref-scalarfuncs-minvalue].

`MINVALUE()`

Disponible en

DSQL, PSQL

Syntaxe

MINVALUE (<expr1> [, ... , <exprN> ])

Table 1. paramètres de fonction MINVALUE
Paramètre	Description
expr1 … exprN	Expressions de tout type compatible.

type de résultat de retour

est le même que le premier argument de expr1.

Renvoie la valeur minimale d’une liste de nombres, de chaînes de caractères ou de paramètres de type DATE / TIME / TIMESTAMP.

Note	Si un ou plusieurs paramètres d’entrée sont `NULL`, le résultat de la fonction `MINVALUE` est également `NULL` contrairement à la fonction d’agrégation `MIN`.

Exemple `MINVALUE`

Example 1. Utilisation de la fonction MINVALUE

SELECT MINVALUE(PRICE_1, PRICE_2) AS PRICE
FROM PRICELIST

Voir aussi :

[fblangref-scalarfuncs-maxvalue].

`NULLIF()`

Disponible en

DSQL, PSQL

Syntaxe

NULLIF (<exp1>, <exp2>)

Table 1. paramètres de fonction `NULLIF`
Paramètre	Description
expr1, expr2	Expressions de tout type compatible.

type de résultat de retour

dépend des types d’arguments d’entrée

La fonction retourne la valeur du premier argument s’il n’est pas égal au second. Si les arguments sont égaux, NULL est retourné.

Exemple `NULLIF`

Example 1. Utilisation de la fonction NULLIF

SELECT AVG(NULLIF(weight, -1)) FROM cargo;

Cette requête renvoie la valeur moyenne du champ weight sur la table, sauf pour les lignes où il n’est pas spécifié (égal à -1). S’il n’y avait pas cette fonction, le simple opérateur avg(weight) renverrait une valeur incorrecte.

Voir aussi :

[fblangref-scalarfuncs-coalesce], CASE.

Autres fonctions

Cette section contient des caractéristiques difficiles à catégoriser.

`MAKE_DBKEY()`

Disponible en

DSQL, PSQL

Syntaxe

MAKE_DBKEY (<relation>, recnum [, dpnum [, ppnum]]})

<relation> ::= rel_name | rel_id

Table 1. paramètres de fonction `MAKE_DBKEY`
Paramètre	Description
rel_name	Nom de la table.
rel_id	ID de la table. Peut être trouvé dans `RDB$RELATIONS.RDB$RELATION_ID'.
recnum	Numéro d’enregistrement, soit absolu (si dpnum et ppnum sont absents), soit relatif (si dpnum est présent).
dpnum	Numéro de page des données DP, soit absolu (si ppnum est absent), soit relatif (si ppnum est présent).
ppnum	Numéro de page des pointeurs vers les données PP.

La fonction MAKE_DBKEY crée une valeur DBKEY en utilisant le nom ou l’identifiant de la table, le numéro d’enregistrement et, en option, un numéro de page de données logique et un numéro de page de pointeur.

Note

Remarques

Si le premier argument (table) est une expression ou un littéral, il est traité comme un nom de table et Firebird recherche l’identifiant de la table correspondante. La recherche est sensible à la casse.

Dans le cas d’un littéral de type chaîne, l’identifiant de la table est évalué lors de la préparation.Dans le cas d’une expression, l’ID de la table est évalué au moment de l’exécution.

Si la table est introuvable, une erreur isc_relnotdef se produit.
Si le premier argument (table) est une expression numérique ou un littéral, il est traité comme un identifiant de table et utilisé "tel quel", sans vérifier si la table existe.

Si la valeur de l’argument est négative ou dépasse l’identifiant de table maximum autorisé (actuellement 65535), NULL est retourné.
Le deuxième argument (recnum) est le numéro d’enregistrement absolu par rapport à (si les arguments suivants — dpnum et ppnum — sont manquants) ou le numéro d’enregistrement relatif au premier enregistrement spécifié dans les arguments suivants.
Le troisième argument (dpnum) est le numéro de page de données logique (DP) dans la table (si l’argument suivant — ppnum — est absent) ou le numéro de page de données relatif à la première page de données adressée par le ppnum donné.
Le quatrième argument (ppnum) — est le numéro de page de l’index logique (PP) dans la table.
Tous les nombres commencent par zéro. La valeur maximale autorisée pour dpnum et ppnum est 2³² (4294967296).

Si dpnum est spécifié, la valeur de recnum peut être négative.

Si dpnum est manquant et que recnum est négatif, NULL est retourné.

Si ppnum est spécifié, dpnum peut être négatif.

Si ppnum est manquant et que dpnum est négatif, NULL est retourné.
Si l’un des arguments spécifiés est NULL, le résultat est également NULL.
Le premier argument (table) est décrit comme INTEGER, mais peut être remplacé par l’application comme VARCHAR ou CHAR.

recnum, dpnum et ppnum sont décrits comme BIGINT (entier signé de 64 bits).

Exemple:

La requête sélectionne un enregistrement en utilisant le nom de la table (nom de la table en majuscules).
```
select * from rdb$relations where rdb$db_key = make_dbkey('RDB$RELATIONS', 0)
```
La requête sélectionne un enregistrement en utilisant l’identifiant de la table
```
select * from rdb$relations where rdb$db_key = make_dbkey(6, 0)
```
La requête sélectionne tous les enregistrements qui sont physiquement sur la première page des données dans la table
```
select * from rdb$relations
where rdb$db_key >= make_dbkey(6, 0, 0)
  and rdb$db_key <  make_dbkey(6, 0, 1)
```
La requête sélectionne tous les enregistrements qui sont physiquement sur la première page de données de la page d’index 6 dans la table
```
select * from SOMETABLE
where rdb$db_key >= make_dbkey('SOMETABLE', 0, 0, 5)
  and rdb$db_key <  make_dbkey('SOMETABLE', 0, 1, 5)
```
Voir aussi: [fblangref-appx-supp-rdb-dbkey].

`RDB$ERROR()`

Disponible en

PSQL

Syntaxe

RDB$ERROR (<context>)

<context> ::= GDSCODE | SQLCODE | SQLSTATE | EXCEPTION | MESSAGE

type de résultat de retour

Cela dépend du contexte

Renvoie la valeur du contexte de l’exception active. Le type de retour dépend du contexte.

Note	La fonction `RDB$ERROR` renvoie toujours `NULL` en dehors du bloc de gestion des erreurs. `WHEN … DO`.

Contextes disponibles comme argument de la fonction RDB$ERROR :

EXCEPTION: La fonction renvoie un nom d’exception si une exception définie par l’utilisateur est active, ou NULL si une des exceptions du système est active.Pour le contexte EXCEPTION, le type de valeur de retour : VARCHAR(63) JEU DE CARACTÈRES UTF8.
MESSAGE: la fonction retourne le texte interprété d’une exception active.Pour le contexte MESSAGE, le type de valeur de retour : VARCHAR(1024) JEU DE CARACTÈRES UTF8.
GDSCODE: la fonction retourne la valeur de la variable contextuelle GDSCODE.
SQLCODE: la fonction retourne la valeur de la variable contextuelle SQLCODE.
SQLSTATE: la fonction retourne la valeur de la variable de contexte SQLSTATE.

Example 1. Utilisation de la fonction RDB$ERROR pour sauvegarder le texte de l’erreur dans le journal de bord

...
BEGIN
...
WHEN ANY DO
  EXECUTE PROCEDURE P_LOG_EXCEPTION(RDB$ERROR(MESSAGE));
END
...

Voir aussi :

WHEN … DO,EXCEPTION,GDSCODE,SQLCODE,SQLSTATE.

`RDB$GET_TRANSACTION_CN()`

Disponible en

DSQL, PSQL

Syntaxe

RDB$GET_TRANSACTION_CN (transaction_id)

Table 1. paramètres de fonction RDB$GET_TRANSACTION_CN
Paramètre	Description
transaction_id	Numéro de transaction (identifiant)

Le type de résultat renvoyé :

BIGINT

Renvoie le numéro d’engagement pour une transaction donnée.

Note

Les mécanismes internes de Firebird utilisent un entier non signé de 8 octets pour le Commit Number et un entier non signé de 6 octets pour le numéro de transaction. Par conséquent, même si le langage SQL n’a pas d’entiers non signés, et que RDB$GET_TRANSACTION_CN renvoie un BIGINT signé, vous ne pouvez pas voir un numéro de confirmation négatif, sauf pour quelques valeurs spéciales utilisées pour les transactions non confirmées.

Si la fonction RDB$GET_TRANSACTION_CN renvoie une valeur supérieure à 1, il s’agit du (Commit Number) réel de la transaction, c’est-à-dire que la transaction a été validée après le démarrage de la base de données.

Dans d’autres cas, la fonction peut renvoyer l’un des résultats suivants indiquant l’état de validation de la transaction :

`-2`	transactions mortes (annulées) ;
`-1`	Transactions suspendues (en état de limbo 2PC transactions) ;
`0`	transactions actives ;
`1`	pour les transactions validées avant le démarrage de la base de données ou avec un numéro inférieur à OIT (Oldest Interesting Transaction) ;
`NULL`	: Si le numéro de transaction est `NULL` ou supérieur à Transaction suivante.

Example 1. Utilisation de RDB$GET_TRANSACTION_CN

select rdb$get_transaction_cn(current_transaction) from rdb$database;

select rdb$get_transaction_cn(123) from rdb$database;

Fonction: Retourne le numéro de commit de la transaction donnée. Le type de résultat est BIGINT.

Note

Remarques :

le moteur utilise en interne des entiers non signés de 8 octets pour les numéros de commit, et des entiers non signés de 6 octets pour les numéros de transaction. Ainsi, malgré que le langage SQL n'ait pas d'entiers non signés et que RDB$GET_TRANSACTION_CN retourne BIGINT signés, il est impossible de voir des nombres de commit négatifs à l'exception des quelques valeurs spéciales utilisées pour les transactions non commises.

En résumé, les nombres retournés par RDB$GET_TRANSACTION_CN peuvent avoir les valeurs suivantes :

-2 - la transaction est morte (annulée)
-1 - la transaction est dans les limbes
 0 - la transaction est active,
 1 - la transaction a été effectuée avant le démarrage de la base de données ou moins que la base de données.
	 Transaction intéressante la plus ancienne
>1 - transaction effectuée après le démarrage de la base de données
NULL - le numéro de transaction donné est NULL ou supérieur à celui de la base de données Next Transaction (Transaction suivante)

Voir aussi README.read_consistency.md

Format : RDB$GET_TRANSACTION_CN( <numéro de transaction> )

Exemples :

	select rdb$get_transaction_cn(current_transaction) from rdb$database ;
	select rdb$get_transaction_cn(123) from rdb$database ;

Note	Pour plus d’informations sur le Commit Number, reportez-vous aux Firebird 4.0 Release Notes.

`RDB$ROLE_IN_USE()`

Disponible en

DSQL, PSQL

Syntaxe

RDB$ROLE_IN_USE (role_name)

Table 1. paramètres de fonction `RDB$ROLE_IN_USE`
Paramètre	Description
role_name	Le nom du rôle dont l’utilisation est contrôlée.

type de résultat de retour

BOOLEAN

La fonction RDB$ROLE_IN_USE retourne si le rôle est utilisé par l’utilisateur actuel.

Note	Cette fonction vous permet de vérifier l’utilisation de n’importe quel rôle : ceux spécifiés explicitement (lors de la connexion ou modifiés à l’aide de l’instruction SET ROLE) et ceux attribués implicitement (rôles attribués à un utilisateur à l’aide de la clause DEFAULT).

Example 1. Utilisation de la fonction RDB$ROLE_IN_USE

-- Vérifier si l'attribut explicitement attribué ou
-- rôle de MANAGER obtenu implicitement
IF (RDB$ROLE_IN_USE('MANAGER')) THEN
BEGIN
  ...
END

Example 2. Liste des rôles utilisés par la connexion actuelle

SELECT * FROM RDB$ROLES WHERE RDB$ROLE_IN_USE(RDB$ROLE_NAME)

Voir aussi :

GRANT ROLE, SET ROLE, CURRENT_ROLE.

`RDB$SYSTEM_PRIVILEGE()`

Disponible en

DSQL, PSQL

Syntaxe

RDB$SYSTEM_PRIVILEGE (<privilege>)

Table 1. paramètres de fonction `RDB$SYSTEM_PRIVILEGE`
Paramètre	Description
privilege	Privilège système vérifiable

type de résultat de retour

BOOLEAN

La fonction RDB$SYSTEM_PRIVILEGE utilise le privilège système de la connexion actuelle. Pour obtenir une liste des privilèges système, consultez la rubrique CREATE ROLE.

Example 1. Utilisation de la fonction RDB$SYSTEM_PRIVILEGE

SELECT RDB$SYSTEM_PRIVILEGE(USER_MANAGEMENT) FROM RDB$DATABASE;

Voir aussi :

CREATE ROLE.

Fonctions mathématiques

`ABS()`

Disponible en

DSQL, PSQL

Syntaxe

ABS (number)

Table 1. paramètres de fonction `ABS`
Paramètre	Description
number	Expression de type numérique

Expression de type numérique

est le même que l’argument d’entrée.

La fonction ABS renvoie la valeur absolue (modulo) de l’argument.

`COS()`

Disponible en

DSQL, PSQL

Syntaxe

COS (angle)

Table 1. paramètres de fonction `COS`
Paramètre	Description
angle	Angle exprimé en radians.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction COS renvoie le cosinus d’un angle. L’argument doit être donné en radians.

Tout résultat NOT NULL se situe dans l’intervalle [-1, 1].

Voir aussi :

[fblangref-scalarfuncs-acos].

`COSH()`

Disponible en

DSQL, PSQL

Syntaxe

COSH (number)

Table 1. paramètres de fonction `COSH`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction COSH renvoie le cosinus hyperbolique de l’argument.

Tout résultat NOT NULL se situe dans l’intervalle [1, +∞].

Voir aussi :

[fblangref-scalarfuncs-acosh].

`COT()`

Disponible en

DSQL, PSQL

Syntaxe

COT (angle)

Table 1. paramètres de fonction `COT`
Paramètre	Description
angle	Angle exprimé en radians.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction COT renvoie la cotangente de l’angle. L’argument doit être donné en radians.

Voir aussi :

[fblangref-scalarfuncs-tan].

`EXP()`

Disponible en

DSQL, PSQL

Syntaxe

EXP (number)

Table 1. paramètres de fonction `EXP`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction EXP retourne la valeur de l’exposant naturel, e^nombre.

Voir aussi :

[fblangref-scalarfuncs-ln].

`FLOOR()`

Disponible en

DSQL, PSQL

Syntaxe

FLOOR (number)

Table 1. paramètres de fonction `FLOOR`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

BIGINT, INT128, DECFLOAT ou DOUBLE PRECISION selon le type d’argument.

La fonction FLOOR renvoie un entier inférieur ou égal à l’argument.

Voir aussi :

[fblangref-scalarfuncs-ceil], [fblangref-scalarfuncs-trunc].

`LN()`

Disponible en

DSQL, PSQL

Syntaxe

LN (number)

Table 1. paramètres de fonction `LN`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction LN renvoie le logarithme naturel de l’argument.

Note	Si un argument négatif ou nul est passé, la fonction renvoie une erreur.

Voir aussi :

[fblangref-scalarfuncs-exp].

`LOG()`

Disponible en

DSQL, PSQL

Syntaxe

LOG (x, y)

Table 1. paramètres de fonction `LOG`
Paramètre	Description
x	Base. Expression de type numérique.
y	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction LOG renvoie le logarithme de y (deuxième argument) sur la base de x (premier argument).

Particularités d’utilisation :

Si l’un des arguments est inférieur ou égal à 0, une erreur se produit ;
Si les deux arguments valent 1, le résultat de la fonction est NaN (Not-a-Number — pas un nombre) ;
Si x = 1 et y < 1, le résultat de la fonction est -INF (-∞) ;
Si x = 1 et y > 1, le résultat de la fonction est `INF` (∞).

`LOG10()`

Disponible en

DSQL, PSQL

Syntaxe

LOG10 (number)

Table 1. paramètres de fonction `LOG10`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction `LOG10' renvoie le logarithme décimal de l’argument.

Note	Si l’argument d’entrée est négatif ou égal à 0, une erreur se produit.

`MOD()`

Disponible en

DSQL, PSQL

Syntaxe

MOD (a, b)

Table 1. paramètres de fonction `MOD`
Paramètre	Description
a	Expression est de type numérique.
b	Expression est de type numérique.

Le type de résultat renvoyé :

INTEGER, BIGINT ou INT128 selon les types d’arguments.

La fonction MOD renvoie le reste d’une division d’un nombre entier.

Note	Les nombres réels sont arrondis avant d’effectuer la division. Par exemple, le résultat de “`mod(7,5, 2,5)`” serait 2 ("`mod(8, 3)`), et non 0.

`PI()`

Disponible en

DSQL, PSQL

Syntaxe

PI ()

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction PI renvoie le nombre π.

`ACOS()`

Disponible en

DSQL, PSQL

Syntaxe

ACOS (number)

Table 1. paramètres de fonction ACOS
Paramètre	Description
number	Une expression de type numérique dans la plage [-1 ; 1].

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction ACOS retourne l’arc cosinus (en radians) de l’argument.

Si l’argument de la fonction est en dehors de l’intervalle [-1, 1], la fonction renverra une valeur indéfinie NaN.

Voir aussi :

[fblangref-scalarfuncs-cos].

`POWER()`

Disponible en

DSQL, PSQL

Syntaxe

POWER (x, y)

Table 1. paramètres de fonction `POWER`
Paramètre	Description
x	Expression est de type numérique.
y	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction POWER renvoie le résultat de l’élévation de x à la puissance de y, c’est-à-dire (x^y).

Note	Si x est inférieur à zéro, une erreur se produit.

`RAND()`

Disponible en

DSQL, PSQL

Syntaxe

RAND ()

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction RAND renvoie un nombre pseudo-aléatoire entre 0 et 1.

`ROUND()`

Disponible en

DSQL, PSQL

Syntaxe

ROUND (number [, scale])

Table 1. paramètres de fonction `ROUND`
Paramètre	Description
number	Expression est de type numérique.
scale	L’échelle est un nombre entier définissant le nombre de décimales auquel l’arrondi doit être effectué, soit 2 pour l’arrondi au multiple le plus proche de 0,01 1 pour arrondir au multiple le plus proche de 0.1 0 pour l’arrondi au nombre entier le plus proche -1 au multiple de 10 le plus proche -2 au multiple de 100 le plus proche La valeur par défaut est 0.

Type de résultat de retour

entier mis à l’échelle (INTEGER, BIGINT ou INT128) ou DECFLOAT ou DOUBLE PRECISION selon le type de number.

La fonction ROUND arrondit le nombre au nombre entier le plus proche. Si la partie fractionnaire est égale à 0,5, elle est arrondie au nombre entier supérieur le plus proche pour les nombres positifs et au nombre entier inférieur le plus proche pour les nombres négatifs. Avec le paramètre optionnel scale, le nombre peut être arrondi à l’une des puissances de 10 (dizaines, centaines, dixièmes, centièmes, etc.) au lieu d’un simple nombre entier.

Note	Si le paramètre scale est utilisé, le résultat a la même échelle que le premier paramètre number.

Exemple `ROUND`

Example 1. Utilisation de la fonction ROUND

ROUND(123.654, 1) -- Résultat : 123.700 (pas 123.7)
ROUND(8341.7, -3) -- Résultat : 8000.0 (pas 8000)
ROUND(45.1212, 0) -- Résultat : 45.0000 (pas 45)
ROUND(45.1212) -- Résultat : 45

Voir aussi :

[fblangref-scalarfuncs-trunc].

`SIGN()`

Disponible en

DSQL, PSQL

Syntaxe

SIGN (number)

Table 1. paramètres de fonction `SIGN`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

SMALLINT

La fonction SIGN renvoie le signe du paramètre d’entrée.

-1 — le nombre est inférieur à zéro
0 — le nombre est zéro
1 — le nombre est plus grand que zéro

`SIN()`

Disponible en

DSQL, PSQL

Syntaxe

SIN (angle)

Table 1. paramètres de fonction `SIN`
Paramètre	Description
angle	Angle exprimé en radians.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction SIN renvoie le sinus d’un angle. L’argument doit être donné en radians.

Tout résultat NOT NULL se situe dans l’intervalle [-1, 1].

Voir aussi :

[fblangref-scalarfuncs-asin].

`SINH()`

Disponible en

DSQL, PSQL

Syntaxe

SINH (number)

Table 1. paramètres de fonction `SINH`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction SINH renvoie le sinus hyperbolique de l’argument.

Voir aussi :

[fblangref-scalarfuncs-asinh].

`SQRT()`

Disponible en

DSQL, PSQL

Syntaxe

SQRT (number)

Table 1. paramètres de fonction `SQRT`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction SQRT renvoie la racine carrée de l’argument.

`TAN()`

Disponible en

DSQL, PSQL

Syntaxe

TAN (angle)

Table 1. paramètres de fonction `TAN`
Paramètre	Description
angle	Angle exprimé en radians.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction TAN renvoie la tangente de l’angle. L’argument doit être donné en radians.

Voir aussi :

[fblangref-scalarfuncs-atan], [fblangref-scalarfuncs-atan2].

`TANH()`

Disponible en

DSQL, PSQL

Syntaxe

TANH (number)

Table 1. paramètres de fonction `TANH`
Paramètre	Description
number	Expression est de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction TANH renvoie la tangente hyperbolique de l’argument.

Tout résultat NOT NULL se situe dans l’intervalle [-1, 1].

Voir aussi :

[fblangref-scalarfuncs-atanh].

`TRUNC()`

Disponible en

DSQL, PSQL

Syntaxe

TRUNC (number [, scale])

Table 1. paramètres de fonction `TRUNC`
Paramètre	Description
number	Expression est de type numérique.
scale	L’échelle est un nombre entier définissant le nombre de décimales auquel la troncature doit être effectuée, c’est à dire 2 pour la troncature au multiple le plus proche de 0,01 1 pour la troncature au multiple le plus proche de 0,1 0 pour la troncature au nombre entier le plus proche -1 au multiple de 10 le plus proche -2 au multiple de 100 le plus proche La valeur par défaut est 0.

type de résultat de retour

entier mis à l’échelle (INTEGER, BIGINT ou INT128) ou DECFLOAT ou DOUBLE PRECISION selon le type de number.

La fonction TRUNC tronque le nombre à l’entier le plus proche. Avec le paramètre optionnel scale, le nombre peut être tronqué à l’une des puissances de 10 (dizaines, centaines, dixièmes, centièmes, etc.) au lieu d’un simple nombre entier.

Note	Si le paramètre scale est utilisé, le résultat a la même échelle que le premier paramètre number.

Important

La fonction incrémente toujours les nombres négatifs car elle rogne la partie fractionnaire.

Example 1. Utilisation de la fonction TRUNC

TRUNC(789.2225, 2) -- Résultat : 789.2200 (pas 789.22)
TRUNC(345.4, -2) -- Résultat : 300.0 (pas 300)
TRUNC(-163.41, 0) -- Résultat : -163.00 (pas -163)
TRUNC(-163.41) -- Résultat : -163

Voir aussi :

[fblangref-scalarfuncs-round], [fblangref-scalarfuncs-ceil], [fblangref-scalarfuncs-floor].

`ACOSH()`

Disponible en

DSQL, PSQL

Syntaxe

ACOSH (number)

Table 1. paramètres de fonction `ACOSH`
Paramètre	Description
number	Une expression de type numérique dans la plage [1 ; +∞].

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction ACOSH retourne l’arc cosinus hyperbolique (en radians) de l’argument.

Voir aussi :

[fblangref-scalarfuncs-cosh].

`ASIN()`

Disponible en

DSQL, PSQL

Syntaxe

ASIN (number)

Table 1. paramètres de fonction `ASIN`
Paramètre	Description
number	Une expression de type numérique dans l’intervalle [-1 ; 1].

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction ASIN renvoie l’arcsine (en radians) de l’argument.

Si l’argument de la fonction est en dehors de l’intervalle [-1, 1], la fonction renverra une valeur indéfinie NaN.

Voir aussi :

[fblangref-scalarfuncs-sin].

`ASINH()`

Disponible en

DSQL, PSQL

Syntaxe

ASIN (number)

Table 1. paramètres de fonction `ASINH`
Paramètre	Description
number	Une expression de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction ASINH renvoie l’arcsinus hyperbolique (en radians) de l’argument.

Voir aussi :

[fblangref-scalarfuncs-sinh].

`ATAN()`

Disponible en

DSQL, PSQL

Syntaxe

ATAN (number)

Table 1. paramètres de fonction `ATAN`
Paramètre	Description
number	Une expression de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction ATAN retourne l’arctangente de l’argument.

La fonction renvoie l’angle en radians dans l’intervalle [-π/2 ; π/2].

Voir aussi :

[fblangref-scalarfuncs-atan2], [fblangref-scalarfuncs-tan].

`ATAN2()`

Disponible en

DSQL, PSQL

Syntaxe

ATAN2 (y, x)

Table 1. paramètres de fonction ATAN2
Paramètre	Description
y	Une expression de type numérique.
x	Une expression de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction ATAN2 retourne l’angle comme le rapport du sinus au cosinus, avec les arguments donnés par ces deux paramètres, et les signes du sinus et du cosinus correspondant aux signes des paramètres.Cela permet d’obtenir des résultats pour le cercle entier, y compris pour les angles de -π/2 et π/2.

Caractéristiques d’utilisation :

Le résultat est un angle dans l’intervalle [-π, π] radians ;
Si x est négatif, le résultat est π lorsque y est nul et -π lorsqu’il est égal à 0 ;
Si y et x sont tous deux égaux à 0, le résultat n’a pas de sens.

Note

La description entièrement équivalente de cette fonction est la suivante : ATAN2 (y, x) est l’angle entre l’axe des X positif et la droite allant de l’origine au point (x, y). Cela rend également évident que la valeur de ATAN2 (0, 0) est indéfinie ;
Si x est supérieur à 0, ATAN2 (y, x) est identique à ATAN (y/x) ;
Si le sinus et le cosinus de l’angle sont connus, ATAN2 (sin, cos) renvoie l’angle.

Voir aussi :

[fblangref-scalarfuncs-atan], [fblangref-scalarfuncs-sin], [fblangref-scalarfuncs-cos].

`ATANH()`

Disponible en

DSQL, PSQL

Syntaxe

ATANH (number)

Table 1. paramètres de fonction `ATANH`
Paramètre	Description
number	Une expression de type numérique.

Le type de résultat renvoyé :

DOUBLE PRECISION

La fonction ATANH retourne l’arctangente hyperbolique (en radians) de l’argument.

Voir aussi :

[fblangref-scalarfuncs-tanh].

`CEIL()`, `CEILING()`

Disponible en

DSQL, PSQL

Syntaxe

CEIL[ING] (number)

Table 1. paramètres de fonction CEIL[ING]
Paramètre	Description
number	Une expression de type numérique.

Le type de résultat renvoyé :

BIGINT, INT128, DECFLOAT ou DOUBLE PRECISION selon le type d’argument.

La fonction CEIL renvoie le plus petit entier supérieur ou égal à l’argument.

Voir aussi :

[fblangref-scalarfuncs-floor], [fblangref-scalarfuncs-trunc].

Fonctions pour travailler avec des chaînes de caractères

`ASCII_CHAR()`

Disponible en

DSQL, PSQL

Syntaxe

ASCII_CHAR (code)

Table 1. paramètres de fonction `ASCII_CHAR`
Paramètre	Description
code	Un nombre entier compris entre 0 et 255.

Le type de résultat renvoyé :

CHAR(1) CHARACTER SET NONE.

La fonction ASCII_CHAR renvoie un caractère ASCII correspondant au nombre passé en argument.

Voir aussi :

[fblangref-scalarfuncs-ascii-val].

`LEFT()`

Disponible en

DSQL, PSQL

Syntaxe

LEFT (string, length)

Table 1. paramètres de fonction `LEFT`
Paramètre	Description
string	Une expression de type chaîne de caractères.
length	Nombre entier. Spécifie le nombre de caractères retournés.

Le type de résultat renvoyé :

VARCHAR ou BLOB.

La fonction LEFT retourne le côté gauche de la chaîne de caractères, le nombre de caractères retournés est déterminé par le deuxième paramètre.

Caractéristiques d’utilisation :

La fonction prend en charge les blocs de texte de n’importe quelle longueur et avec n’importe quel jeu de caractères ;
Si l’argument chaîne est BLOB, le résultat sera BLOB, sinon le résultat sera VARCHAR(N), avec N étant la longueur du paramètre chaîne ;
Si le paramètre numérique dépasse la longueur du texte, le résultat sera le texte original.

Warning

Lorsque vous utilisez BLOB dans les paramètres d’une fonction, il peut être nécessaire de charger l’objet entier en mémoire. Avec de grandes quantités de BLOB, il peut y avoir des pertes de performance.

Example 1. Utilisation de la fonction LEFT

SELECT LEFT('ABC', 2) FROM rdb$database;
-- Résultat AB

Voir aussi :

[fblangref-scalarfuncs-right], [fblangref-scalarfuncs-substring].

`LOWER()`

Disponible en

DSQL, PSQL, ESQL

Syntaxe

LOWER (string)

Table 1. paramètres de fonction `LOWER`
Paramètre	Description
string	Une expression de type chaîne de caractères.

Le type de résultat renvoyé :

VAR[CHAR] ou BLOB

La fonction LOWER retourne la chaîne de caractères d’entrée en minuscules. Le résultat exact dépend du jeu de caractères de la chaîne d’entrée. Par exemple, pour les jeux de caractères NONE et ASCII, seuls les caractères ASCII sont convertis en minuscules ; pour les jeux de caractères OCTETS — la chaîne d’entrée entière est retournée inchangée.

Exemple `LOWER`

Example 1. Utilisation de la fonction LOWER

select Sherifffrom Townswhere lower(Name) = 'cooper''s valley'

Voir aussi :

[fblangref-scalarfuncs-upper].

`LPAD()`

Disponible en

DSQL, PSQL

Syntaxe

LPAD (str, endlen [, padstr])

Table 1. paramètres de fonction LPAD
Paramètre	Description
str	Une expression de type chaîne de caractères.
endlen	La longueur de la chaîne de sortie.
padstr	Une chaîne de caractères qui est ajoutée à la chaîne de caractères d’origine jusqu’à la longueur spécifiée. (“`' '`”).

Le type de résultat renvoyé :

VARCHAR ou BLOB.

La fonction LPAD étend la chaîne d’entrée vers la gauche avec des espaces ou une chaîne définie par l’utilisateur jusqu’à une longueur spécifiée.

Caractéristiques d’utilisation :

La fonction prend en charge les blocs de texte de n’importe quelle longueur et avec n’importe quel jeu de caractères ;
Si la chaîne d’entrée est de type BLOB, le résultat sera également BLOB, sinon le résultat sera VARCHAR(endlen).
Si l’argument padstr est donné mais est ` (chaîne vide), aucune chaîne n’est ajoutée ! Dans le cas où endlen est inférieur à la longueur de la chaîne d’entrée, le résultat est tronqué à la longueur de endlen, même si padstr est une chaîne vide.

Warning

Lorsque vous utilisez BLOB dans les paramètres d’une fonction, il peut être nécessaire de charger l’objet entier en mémoire, ce qui peut entraîner des pertes de performances si la quantité de BLOB est importante.

Exemple `LPAD`

Example 1. Utilisation de la fonction LPAD

LPAD ('Hello', 12)                -- renvoie '       Hello'
LPAD ('Hello', 12, '-')           -- renvoie '-------Hello'
LPAD ('Hello', 12, '')            -- renvoie 'Hello'
LPAD ('Hello', 12, 'abc')         -- renvoie 'abcabcaHello'
LPAD ('Hello', 12, 'abcdefghij')  -- renvoie 'abcdefgHello'
LPAD ('Hello', 2)                 -- renvoie 'He'
LPAD ('Hello', 2, '-')            -- renvoie 'He'
LPAD ('Hello', 2, '')             -- renvoie 'He'

Voir aussi :

[fblangref-scalarfuncs-rpad].

`OCTET_LENGTH()`

Disponible en

DSQL, PSQL

Syntaxe

OCTET_LENGTH (string)

Table 1. paramètres de fonction `OCTET_LENGTH`
Paramètre	Description
string	Une expression de type chaîne de caractères.

Le type de résultat renvoyé :

BIGINT

La fonction OCTET_LENGTH renvoie le nombre d’octets occupés par la chaîne de caractères.

Lorsqu’il s’agit de paramètres de type CHAR, la fonction renvoie la longueur totale de la chaîne formelle. Pour connaître la longueur logique de la chaîne en octets, RIGHT TRIM doit être appliqué avant de passer l’argument à la fonction.

Note	Notez que tous les jeux de caractères n’ont pas le même nombre d’octets que le nombre de caractères.

Exemple `OCTET_LENGTH`

Example 1. Utilisation de la fonction OCTET_LENGTH

SELECT OCTET_LENGTH('Hello!')
FROM rdb$database
-- retournera 6

SELECT OCTET_LENGTH(_iso8859_1 'Grüß di!')
FROM rdb$database
-- retournera 8 : ü et ß n'occupent pas plus d'un octet en ISO8859_1

SELECT
  OCTET_LENGTH(CAST(_iso8859_1 'Grüß di!' AS VARCHAR(24) CHARACTER SET utf8))
FROM rdb$database
-- retournera 10 : ü et ß occupent 2 octets en UTF8

SELECT
  OCTET_LENGTH(CAST(_iso8859_1 'Grüß di!' AS CHAR(24) CHARACTER SET utf8))
FROM rdb$database
-- retournera 26 : un total de 24 positions CHAR et deux d'entre elles occupent 2 octets.

Voir aussi :

[fblangref-scalarfuncs-bit-length], [fblangref-scalarfuncs-char-length].

`OVERLAY()`

Disponible en

DSQL, PSQL

Syntaxe

OVERLAY (string PLACING replacement FROM pos [FOR length])

Table 1. paramètres de fonction OVERLAY
Paramètre	Description
string	La ligne dans laquelle le remplacement a lieu.
replacement	La ligne à remplacer par.
pos	La position à partir de laquelle le remplacement a lieu.
length	Le nombre de caractères à supprimer de la chaîne originale.

Le type de résultat renvoyé :

VARCHAR ou BLOB

La fonction OVERLAY est utilisée pour remplacer une partie d’une chaîne de caractères par une autre chaîne.

Par défaut, le nombre de caractères à supprimer d’une chaîne est égal à la longueur de la chaîne à remplacer.Un quatrième paramètre facultatif permet à l’utilisateur de définir son propre nombre de caractères à supprimer.

Caractéristiques d’utilisation :

La fonction supporte entièrement le test BLOB avec n’importe quel jeu de caractères et n’importe quelle longueur ;
Si la chaîne d’entrée est de type BLOB, alors le résultat sera également de type BLOB. Sinon, le type de résultat sera VARCHAR(n), où n est la somme des longueurs des paramètres string et replacement ;
Comme dans toutes les fonctions de chaîne SQL, pos est le paramètre déterminant ;
Si pos est plus long que la longueur de la chaîne, remplacement est placé immédiatement après la fin de la chaîne ;
Si le nombre de caractères entre pos et la fin de la chaîne est inférieur à la longueur de remplacement (ou au paramètre length, s’il est spécifié), la chaîne est tronquée à pos et remplacement est placé après elle ;
Si le paramètre length est égal à zéro (FOR 0), replacement est simplement inséré dans la chaîne, en commençant à la position pos ;
Si l’un des paramètres a la valeur NULL, le résultat est NULL ;
Si les paramètres pos et length ne sont pas des entiers, l’arrondi bancaire (à un nombre pair) est utilisé : 0,5 devient 0, 1,5 devient 2, 2,5 devient 2, 3,5 devient 4, etc.

Warning

Lors de l’utilisation d’une fonction BLOB, il peut être nécessaire de charger l’objet entier en mémoire. Si la BLOB est grande, cela peut affecter les performances.

Exemple `OVERLAY`

Example 1. Utilisation de la fonction OVERLAY

OVERLAY ('Goodbye' PLACING 'Hello' FROM 2) -- Résultat: 'GHelloe'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 5) -- Résultat: 'GoodHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 8) -- Résultat: 'GoodbyeHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 20) -- Résultat: 'GoodbyeHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 0) -– Résultat: 'GHellooodbye'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 3) -- Résultat: 'GHellobye'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 6) -- Résultat: 'GHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 9) -- Résultat: 'Ghello'
OVERLAY ('Goodbye' PLACING '' FROM 4) -- Résultat: 'Goodbye'
OVERLAY ('Goodbye' PLACING '' FROM 4 FOR 3) -- Résultat: 'Gooe'
OVERLAY ('Goodbye' PLACING '' FROM 4 FOR 20) -- Résultat: 'Goo'
OVERLAY ('' PLACING 'Hello' FROM 4) -- Résultat: 'Hello'
OVERLAY ('' PLACING 'Hello' FROM 4 FOR 0) -- Résultat: 'Hello'
OVERLAY ('' PLACING 'Hello' FROM 4 FOR 20) -- Résultat: 'Hello'

Voir aussi :

[fblangref-scalarfuncs-substring], [fblangref-scalarfuncs-replace].

`POSITION()`

Disponible en

DSQL, PSQL

Syntaxe

  POSITION (substr IN string)
| POSITION (substr, string [, startpos])

Table 1. paramètres de fonction `POSITION`
Paramètre	Description
substr	Sous-chaîne dont la position est recherchée.
string	La ligne dans laquelle la position est recherchée.
startpos	La position à laquelle la recherche de sous-chaîne commence.

Le type de résultat renvoyé :

INTEGER

La fonction POSITION renvoie la position de la première occurrence d’une sous-chaîne dans la chaîne.Il commence par 1.Le troisième argument (facultatif) indique la position dans la chaîne à laquelle la recherche de la sous-chaîne commence, ignorant ainsi toutes les occurrences de la sous-chaîne dans la chaîne avant cette position.Si aucune correspondance n’est trouvée, la fonction renvoie 0.

Caractéristiques d’utilisation :

Un troisième paramètre facultatif n’est pris en charge que par la deuxième variante de la syntaxe (syntaxe à virgules séparées) ;
Une chaîne vide, la fonction la traite comme une sous-chaîne de n’importe quelle chaîne. Par conséquent, avec un paramètre d’entrée substr égal à ' (chaîne vide), et avec un paramètre string autre que NULL, le résultat sera :
- 1, si le paramètre startpos n’est pas donné ;
- startpos, si startpos ne dépasse pas la longueur du paramètre string ;
- 0 si startpos est supérieur à la longueur du paramètre string.

Exemple `POSITION`

Example 1. Utilisation de la fonction POSITION

POSITION ('be' IN 'To be or not to be')   -- Résultat: 4
POSITION ('be', 'To be or not to be')     -- Résultat: 4
POSITION ('be', 'To be or not to be', 4)  -- Résultat: 4
POSITION ('be', 'To be or not to be', 8)  -- Résultat: 17
POSITION ('be', 'To be or not to be', 18) -- Résultat: 0
POSITION ('be' in 'Alas, poor Yorick!') -- Résultat: 0

Voir aussi :

[fblangref-scalarfuncs-substring].

`REPLACE()`

Disponible en

DSQL, PSQL

Syntaxe

REPLACE (str, find, repl)

Table 1. paramètres de fonction `REPLACE`
Paramètre	Description
str	La ligne dans laquelle le remplacement est effectué.
find	La chaîne de caractères qui fait l’objet de la recherche.
repl	La ligne sur laquelle s’effectue le remplacement.

Le type de résultat renvoyé :

VARCHAR ou BLOB

La fonction REPLACE remplace toutes les occurrences d’une chaîne par une autre.

Caractéristiques d’utilisation :

La fonction prend en charge les blocs de texte de n’importe quelle longueur et avec n’importe quel jeu de caractères ;
Si l’un des arguments est de type BLOB, le résultat sera de type BLOB. Sinon, le résultat sera de type VARCHAR(N), où N est calculé à partir des longueurs de str, find et repl de telle sorte que même le nombre maximal de substitutions ne provoquera pas de dépassement de champ.
Si le paramètre find est une chaîne vide, str est retourné inchangé ;
Si le paramètre repl est une chaîne vide, toutes les occurrences de find sont supprimées de la chaîne str ;
Si l’un des arguments est NULL, le résultat est toujours NULL, même si aucune substitution n’a été faite.

Warning

Lorsque vous utilisez BLOB dans les paramètres d’une fonction, il peut être nécessaire de charger l’objet entier en mémoire. Avec de grandes quantités de BLOB, il peut y avoir des pertes de performance.

Exemple `REPLACE`

Example 1. Utilisation de la fonction REPLACE

REPLACE ('Billy Wilder', 'il', 'oog')  -- retourne 'Boogly Woogder'
REPLACE ('Billy Wilder', 'il', '')     -- retourne 'Bly Wder'
REPLACE ('Billy Wilder', null, 'oog')  -- retourne NULL
REPLACE ('Billy Wilder', 'il', null)   -- retourne NULL
REPLACE ('Billy Wilder', 'xyz', null)  -- retourne NULL (!)
REPLACE ('Billy Wilder', 'xyz', 'abc') -- retourne 'Billy Wilder'
REPLACE ('Billy Wilder', '', 'abc')    -- retourne 'Billy Wilder'

Voir aussi :

[fblangref-scalarfuncs-overlay].

`REVERSE()`

Disponible en

DSQL, PSQL

Syntaxe

REVERSE (string)

Table 1. paramètres de fonction REVERSE
Paramètre	Description
string	Une expression de type chaîne de caractères.

Le type de résultat renvoyé :

VARCHAR

La fonction REVERSE renvoie la chaîne de caractères inversée "à l’envers".

Exemple `REVERSE`

Example 1. Utilisation de la fonction REVERSE

REVERSE ('spoonful')             -- retourne 'lufnoops'
REVERSE ('Was it a cat I saw?')  -- retourne '?was I tac a ti saW'

Tip

Cette fonction est très utile si vous souhaitez traiter (trier ou grouper) des informations qui se trouvent à la fin d’une chaîne de caractères, par exemple des noms de domaine ou des adresses électroniques.

CREATE INDEX ix_people_email ON people
COMPUTED BY (reverse(email));

-- email = 'info@ledomaine.fr'
SELECT * FROM people
WHERE REVERSE(email) STARTING WITH reverse('rf.');

`RIGHT()`

Disponible en

DSQL, PSQL

Syntaxe

RIGHT (string, length)

Table 1. paramètres de fonction `RIGHT`
Paramètre	Description
string	Une expression de type chaîne de caractères.
length	Nombre entier. Spécifie le nombre de caractères retournés.

Le type de résultat renvoyé :

VARCHAR ou BLOB

La fonction RIGHT renvoie la partie finale (droite) de la chaîne de caractères d’entrée.La longueur de la sous-chaîne retournée est déterminée par le deuxième paramètre.

Caractéristiques d’utilisation :

La fonction prend en charge les blocs de texte de n’importe quelle longueur et avec n’importe quel jeu de caractères ;
Si l’argument chaîne est BLOB, le résultat est BLOB, sinon le résultat est VARCHAR(N), avec N — égal à la longueur du paramètre chaîne ;
Si le paramètre numérique dépasse la longueur du texte, le résultat sera le texte original.

Warning

Lorsque vous utilisez BLOB dans les paramètres d’une fonction, il peut être nécessaire de charger l’objet entier en mémoire, ce qui peut entraîner des pertes de performances si la taille du BLOB est importante.

Example 1. Utilisation de la fonction RIGHT

SELECT RIGHT('ABC', 1) FROM rdb$database;
-- Résultat C

Voir aussi :

[fblangref-scalarfuncs-left], [fblangref-scalarfuncs-substring].

`RPAD()`

Disponible en

DSQL, PSQL

Syntaxe

RPAD (str, endlen [, padstr])

Table 1. paramètres de fonction `RPAD`
Paramètre	Description
str	Une expression de type chaîne de caractères.
endlen	La longueur de la chaîne de sortie.
padstr	Une chaîne de caractères qui est ajoutée à la chaîne de caractères d’origine jusqu’à la longueur spécifiée (`' '`).

Le type de résultat renvoyé :

VARCHAR ou BLOB

La fonction RPAD complète la chaîne d’entrée de droite avec des espaces ou une chaîne définie par l’utilisateur jusqu’à une longueur spécifiée.

Caractéristiques d’utilisation :

La fonction prend en charge les blocs de texte de n’importe quelle longueur et avec n’importe quel jeu de caractères ;
Si la chaîne d’entrée est de type BLOB, le résultat sera également BLOB, sinon le résultat sera VARCHAR(endlen).
Si l’argument padstr est donné mais est '' (chaîne vide), aucune chaîne n’est ajoutée ! Dans le cas où endlen est inférieur à la longueur de la chaîne d’entrée, le résultat est tronqué à la longueur de endlen, même si padstr est une chaîne vide.

Warning

Lorsque vous utilisez BLOB dans les paramètres d’une fonction, il peut être nécessaire de charger l’objet entier en mémoire. Avec de grandes quantités de BLOB, il peut y avoir des pertes de performance.

Exemple `RPAD`

Example 1. Utilisation de la fonction RPAD

RPAD ('Hello', 12)                -- retourne 'Hello       '
RPAD ('Hello', 12, '-')           -- retourne 'Hello-------'
RPAD ('Hello', 12, '')            -- retourne 'Hello'
RPAD ('Hello', 12, 'abc')         -- retourne 'Helloabcabca'
RPAD ('Hello', 12, 'abcdefghij')  -- retourne 'Helloabcdefg'
RPAD ('Hello', 2)                 -- retourne 'He'
RPAD ('Hello', 2, '-')            -- retourne 'He'
RPAD ('Hello', 2, '')             -- retourne 'He'

Voir aussi :

[fblangref-scalarfuncs-lpad].

`ASCII_VAL()`

Disponible en

DSQL, PSQL

Syntaxe

ASCII_VAL (ch)

Table 1. paramètres de fonction `ASCII_VAL`
Paramètre	Description
ch	Type de données string [VAR]CHAR ou text BLOB d’une taille maximale de 32767 octets.

Le type de résultat renvoyé :

SMALLINT

La fonction ASCII_VAL renvoie le code ASCII du caractère passé en argument.

Caractéristiques d’utilisation :

Si la chaîne contient plus d’un caractère, le code du premier caractère de la chaîne est renvoyé ;
Si la chaîne est vide, elle renvoie null ;
Si l’argument est NULL, la valeur de retour est également NULL.

Voir aussi :

[fblangref-scalarfuncs-ascii-char].

`SUBSTRING()`

Disponible en

DSQL, PSQL

Syntaxe

SUBSTRING (<substring-args>)

<substring-args> ::=
    str FROM startpos [FOR length]
  | str SIMILAR <similar_pattern> ESCAPE <escape>

<similar-pattern> ::=
  <similar-pattern-R1>
  <escape>"<similar pattern_R2><escape>"
  <similar pattern-R3>

Table 1. paramètres de fonction `SUBSTRING`
Paramètre	Description
str	Une expression de type chaîne de caractères.
startpos	La position à laquelle l’extraction de la sous-chaîne commence. Expression entière.
length	Longueur de la sous-chaîne retournée. Expression entière.
similar-pattern	Le modèle de l’expression SQL régulière utilisée pour rechercher la sous-chaîne.
escape	Symbole d’échappement

Le type de résultat renvoyé :

VARCHAR ou BLOB

La fonction SUBSTRING renvoie une sous-chaîne de caractères à partir d’une position donnée jusqu’à la fin de la chaîne ou jusqu’à une longueur spécifiée, ou extrait une sous-chaîne en utilisant un motif SQL régulier.

Si l’un des paramètres d’entrée est défini comme NULL, le résultat sera également défini comme NULL.

Warning

Lorsque vous utilisez BLOB dans les paramètres d’une fonction, il peut être nécessaire de charger l’objet entier en mémoire. Avec de grandes quantités de BLOB, il peut y avoir des pertes de performance.

Position `SUBSTRING`

Sous une forme positionnelle simple (avec FROM), cette fonction renvoie une sous-chaîne commençant à la position du caractère startpos (la position du premier caractère est 1). Sans l’argument FOR, il retourne tous les caractères restants dans la chaîne.Avec FOR, il renvoie les caractères longueur ou le reste de la chaîne, selon ce qui est le plus court.

A partir de Firebird 4.0, startpos peut être inférieur à 1.Lorsque startpos est inférieur à 1, la sous-chaîne se comporte comme si elle avait un 1 - startpos supplémentaire devantle premier caractère réel à la position 1.La valeur de length est comptée à partir de ce début imaginaire de la chaîne, donc la chaîne résultante peut être plus courte que la length spécifiée ou même vide.

La fonction prend entièrement en charge les BLOB binaires et textuels de n’importe quelle longueur et avec n’importe quel jeu de caractères.Si le paramètre str est de type BLOB, le résultat sera également de type BLOB.Pour tout autre type, le résultat est de type VARCHAR.

Pour un paramètre d’entrée str qui n’est pas BLOB, la longueur du résultat de la fonction sera toujours égale à la longueur de la chaîne str, quelles que soient les valeurs des paramètres startpos et length.

Example 1. Utilisation de la fonction SUBSTRING

select substring('abcdef' from 1 for 2) from rdb$database;
-- Résultat: 'ab'

select substring('abcdef' from 2) from rdb$database;
-- Résultat: 'bcdef'

select substring('abcdef' from 0 for 2) from rdb$database;
-- Résultat: 'a'
-- pas "ab", car il n'y a pas de "rien" en position 0

select substring('abcdef' from -5 for 2) from rdb$database;
-- Résultat: ''
-- la longueur se termine avant le début réel de la ligne

`SUBSTRING` par une expression régulière

La fonction SUBSTRING avec une expression régulière (avec SIMILAR) retourne une partie d’une chaîne de caractères correspondant au modèle d’expression régulière du SQL. Si aucune correspondance n’est trouvée, NULL est retourné.

Le motif SIMILAR est formé de trois motifs d’expression régulière SQL : R1, R2 et R3. Le modèle complet a la forme R1 || '<escape>' || R2 || '<escape>' || R3, où <escape> est le caractère d’échappement défini dans la clause ESCAPE.R2 est le motif qui correspond à la sous-chaîne à extraire et qui est entouré de guillemets doubles échappés (<escape>, par exemple, #" avec le caractère d’échappement ‘`#’). R1 correspond au préfixe de la chaîne, et R3 au suffixe de la chaîne. R1 et R3 sont tous deux facultatifs (ils peuvent être vides), mais le motif doit correspondre à la chaîne entière. En d’autres termes, il ne suffit pas de spécifier un motif qui ne trouve qu’une sous-chaîne à extraire.

Tip

Les guillemets doubles échappés autour de R2 peuvent être comparés à la définition d’un groupe de capture unique dans une syntaxe d’expression régulière plus commune telle que PCRE. C’est-à-dire que le motif complet est équivalent à R1(R2)R3, qui doit correspondre à la chaîne d’entrée entière, et le groupe de capture est la sous-chaîne de retour.

La valeur de retour correspond à la partie R2 de l’expression régulière. Pour cette valeur, l’expression est vraie.

str SIMILAR TO R1 || R2 || R3 ESCAPE <escape>

Note	Si une partie d’un motif de R1, R2 ou R3 n’est pas une chaîne vide et n’a pas de format d’expression régulière SQL, une exception est levée.

Le format complet des instructions SQL régulières est décrit dans le document suivant Syntaxe des expressions régulières SQL.

Example 2. Utilisation de la fonction SUBSTRING avec des expressions régulières

SUBSTRING('abcabc' SIMILAR 'a#"bcab#"c' ESCAPE '#')  -- bcab
SUBSTRING('abcabc' SIMILAR 'a#"%#"c' ESCAPE '#')     -- bcab
SUBSTRING('abcabc' SIMILAR '_#"%#"_' ESCAPE '#')     -- bcab
SUBSTRING('abcabc' SIMILAR '#"(abc)*#"' ESCAPE '#')  -- abcabc
SUBSTRING('abcabc' SIMILAR '#"abc#"' ESCAPE '#')     -- <null>

Voir aussi :

[fblangref-scalarfuncs-position], [fblangref-scalarfuncs-left], [fblangref-scalarfuncs-right],[fblangref-scalarfuncs-char-length], [fblangref-commons-predsimilarto].

`TRIM()`

Disponible en

DSQL, PSQL

Syntaxe

TRIM ([<adjust>] str)

<adjust> ::=  {[<where>] [what]} FROM

<where> ::=  BOTH | LEADING | TRAILING

Table 1. paramètres de fonction `TRIM`
Paramètre	Description
str	Une expression de type chaîne de caractères.
where	De quel endroit la sous-chaîne doit être retirée — `BOTH` \| `LEADING` \| `TRAILING`. La valeur par défaut est `BOTH`.
what	Une sous-chaîne à supprimer (plusieurs fois, s’il y a plus d’une occurrence) de la chaîne d’entrée str au début et/ou à la fin. Par défaut, il s’agit d’un espace. (`' '`).

Le type de résultat renvoyé :

VARCHAR ou BLOB

La fonction TRIM supprime les espaces de début et/ou de fin (ou le texte tel que configuré) de la chaîne d’entrée.

Note

Caractéristiques d’utilisation

Si le paramètre d’entrée str est de type BLOB, le résultat sera également de type BLOB. Sinon, le résultat sera de type VARCHAR(n), où n est la longueur du paramètre str ;
La sous-chaîne à supprimer, si elle est spécifiée bien sûr, ne doit pas avoir une longueur supérieure à 32767 octets. Toutefois, si la sous-chaîne est répétée au début et/ou à la fin du paramètre d’entrée str, le nombre total d’octets à supprimer peut être beaucoup plus important.

Warning

Lorsque vous utilisez BLOB dans les paramètres d’une fonction, il peut être nécessaire de charger l’objet entier en mémoire. Avec de grandes quantités de BLOB, il peut y avoir des pertes de performance.

Exemple `TRIM`

Example 1. Utilisation de la fonction TRIM

SELECT TRIM (' Waste no space ')
FROM RDB$DATABASE -- Résultat: 'Waste no space'

SELECT TRIM (LEADING FROM ' Waste no space ')
FROM RDB$DATABASE -- Résultat: 'Waste no space '

SELECT TRIM (LEADING '.' FROM ' Waste no space ')
FROM RDB$DATABASE -- Résultat: ' Waste no space '

SELECT TRIM (TRAILING '!' FROM 'Help!!!!')
FROM RDB$DATABASE -- Résultat: 'Help'

SELECT TRIM ('la' FROM 'lalala I love you Ella')
FROM RDB$DATABASE -- Résultat: ' I love you El'

Voir aussi :

[fblangref-scalarfuncs-overlay], [fblangref-scalarfuncs-replace].

`UNICODE_CHAR()`

Disponible en

DSQL, PSQL

Syntaxe

UNICODE_CHAR (number)

Table 1. paramètres de fonction `UNICODE_CHAR`
Paramètre	Description
number	Un point de code UTF-32 acceptable se situe en dehors de la plage supérieure/inférieure des substituts (0xD800 à 0xDFFF). Sinon, une erreur sera émise.

Le type de résultat renvoyé :

CHAR CHARACTER SET UTF8

La fonction UNICODE_CHAR renvoie le caractère UNICODE pour un point de code donné.

Exemple `UNICODE_CHAR`

Example 1. Utilisation de la fonction UNICODE_CHAR

select unicode_char(x) from y;

Voir aussi :

[fblangref-scalarfuncs-unicodeval].

`UNICODE_VAL()`

Disponible en

DSQL, PSQL

Syntaxe

UNICODE_VAL (string)

Table 1. paramètres de fonction `UNICODE_VAL`
Paramètre	Description
string	chaine de caractères.

Le type de résultat renvoyé :

INTEGER

La fonction UNICODE_VAL renvoie le point de code UTF-32 du premier caractère de la chaîne. Renvoie 0 pour une chaîne vide.

Exemple `UNICODE_VAL`

Example 1. Utilisation de la fonction UNICODE_VAL

select unicode_val(x) from y;

Voir aussi :

[fblangref-scalarfuncs-unicodechar].

`UPPER()`

Disponible en

DSQL, PSQL

Syntaxe

UPPER (str)

Table 1. paramètres de fonction `UPPER`
Paramètre	Description
str	Une expression de type chaîne de caractères.

Le type de résultat renvoyé :

[VAR]CHAR ou BLOB

La fonction UPPER renvoie la chaîne de caractères d’entrée en majuscules. Le résultat exact dépend du jeu de caractères de la chaîne d’entrée. Par exemple, pour les jeux de caractères NONE et ASCII, seuls les caractères ASCII sont mis en majuscules ; pour les jeux de caractères OCTETS — la chaîne d’entrée entière est renvoyée inchangée.

Exemple `UPPER`

Example 1. Utilisation de la fonction UPPER

select upper(_iso8859_1 'Débâcle')
from rdb$database
-- retourne 'DÉBÂCLE'

select upper(_iso8859_1 'Débâcle' collate fr_fr)
from rdb$database
-- retourne 'DEBACLE',  Règles de mise en majuscules en français
-- résultat valide quand la BD est par défaut en UTF8 et le client configuré en iso8859_1

Voir aussi :

[fblangref-scalarfuncs-lower].

`BASE64_DECODE()`

Disponible en

DSQL, PSQL

Syntaxe

BASE64_DECODE (base64_data)

Table 1. paramètres de fonction `BASE64_DECODE`
Paramètre	Description
base64_data	Données codées en base64 augmentées de `=` jusqu’à une longueur multiple de 4

type de résultat de retour

`BLOB' ou `VARBINARY'.

BASE64_DECODE décode une chaîne avec des données codées par l’algorithme base64et retourne la valeur décodée sous forme de VARBINARY ou de BLOB selon l’argument d’entrée.

Si la longueur du type base64_data n’est pas un multiple de 4, une erreur se produit pendant la préparation.Si la longueur de base64_data n’est pas un multiple de 4, une erreur se produit au moment de l’exécution.

Lorsque l’argument d’entrée n’est pas BLOB, la longueur du type résultant est calculée comme suittype_length * 3/4, où type_length est la longueur maximale en octets du type de l’argument d’entrée.

Exemple `BASE64_DECODE`

Example 1. Utilisation de BASE64_DECODE

select cast(base64_decode('VGVzdCBiYXNlNjQ=') as varchar(12))
from rdb$database;

CAST

============
Test base64

Voir aussi :

[fblangref-scalarfuncs-base64encode].

`BASE64_ENCODE()`

Disponible en

DSQL, PSQL

Syntaxe

BASE64_ENCODE (binary_data)

Table 1. paramètres de fonction `BASE64_ENCODE`
Paramètre	Description
binary_data	Données binaires pour le codage

type de résultat de retour

VARCHAR CHARACTER SET ASCII ou BLOB SUB_TYPE TEXT CHARACTER SET ASCII.

La fonction BASE64_ENCODE encode les données_binaires en utilisant l’algorithme base64 etrenvoie la valeur encodée sous la forme VARCHAR CHARACTER SET ASCII ou BLOB SUB_TYPE TEXT CHARACTER SET ASCII.selon le type de l’argument d’entrée.La valeur de retour est complétée par “`=`” afin que sa longueur soit un multiple de 4.

Lorsque l’argument d’entrée n’est pas BLOB, la longueur du type résultant est calculée comme type_length * 4 / 3, arrondie à un multiple de quatre, où type_length est la longueur maximale du type d’entrée en octets.

Exemple `BASE64_ENCODE`

Example 1. Utilisation de la fonction BASE64_ENCODE

select base64_encode('Test base64')
from rdb$database;

BASE64_ENCODE
================
VGVzdCBiYXNlNjQ=

Voir aussi :

[fblangref-scalarfuncs-base64decode], [fblangref-scalarfuncs-hexencode].

`BIT_LENGTH()`

Disponible en

DSQL, PSQL

Syntaxe

BIT_LENGTH (string)

Table 1. paramètres de fonction `BIT_LENGTH`
Paramètre	Description
string	Une expression de type chaîne de caractères.

Le type de résultat renvoyé :

BIGINT

La fonction BIT_LENGTH renvoie la longueur de la chaîne d’entrée en bits.Pour les jeux de caractères multi-octets, le résultat peut être 8 fois le nombre de caractères dans le nombre formel d’octets par caractère écrit dans RDB$CHARACTER_SETS.

Avec les paramètres de type CHAR, cette fonction prend en compte la longueur totale de la chaîne formelle (par exemple, la longueur déclarée d’un champ ou d’une variable). Si vous voulez obtenir la longueur `logique' en bits, sans compter les espaces, vous devez effectuer une opération RIGHT TRIM sur l’argument avant de le passer à `BIT_LENGTH'.

Exemple `BIT_LENGTH`

Example 1. Utilisation de la fonction BIT_LENGTH

SELECT BIT_LENGTH ('Hello!') FROM RDB$DATABASE
-- renvoie 48

SELECT BIT_LENGTH (_ISO8859_1 'Grüß Di!')
FROM RDB$DATABASE
-- retourne 64 : chacun, ü et ß occupent un octet en ISO8859_1

SELECT BIT_LENGTH (
CAST (_ISO8859_1 'Grüß di!' AS VARCHAR (24)
CHARACTER SET UTF8))
FROM RDB$DATABASE
-- renvoie 80 : ü et ß occupent chacun deux octets en UTF8.

SELECT BIT_LENGTH (
CAST (_ISO8859_1 'Grüß di!' AS CHAR (24)
CHARACTER SET UTF8))
FROM RDB$DATABASE
-- renvoie 208 : la taille de l'ensemble des 24 positions CHAR et deux d'entre elles sont de 16 bits

Voir aussi :

[fblangref-scalarfuncs-char-length], [fblangref-scalarfuncs-octet-length].

`CHAR_LENGTH()`, `CHARACTER_LENGTH()`

Disponible en

DSQL, PSQL

Syntaxe

  CHAR_LENGTH (string)
| CHARACTER_LENGTH (string)

Table 1. paramètres de fonction `CHAR_LENGTH`
Paramètre	Description
string	Une expression de type chaîne de caractères.

Le type de résultat renvoyé :

BIGINT

La fonction CHAR_LENGTH renvoie la longueur (en caractères) de la chaîne passée en argument.

Note

Avec des paramètres de type CHAR, cette fonction prend en compte la longueur totale de la chaîne formelle (par exemple, la longueur déclarée d’un champ ou d’une variable). Si vous voulez obtenir une longueur `logique' sans espaces, vous devez effectuer une opération RIGHT TRIM sur l’argument avant de le passer à `CHAR[ACTER]_LENGTH'.

Voir aussi :

[fblangref-scalarfuncs-bit-length], [fblangref-scalarfuncs-octet-length].

`HASH()`

Disponible en

DSQL, PSQL

Syntaxe

HASH (str [USING <algorithm>])

<algorithm> ::= { CRC32 }

Table 1. paramètres de fonction `HASH`
Paramètre	Description
str	Une expression de type chaîne de caractères.

Le type de résultat renvoyé :

BIGINT

La fonction HASH renvoie un hachage non cryptographique de la chaîne d’entrée.Cette fonction prend entièrement en charge les `BLOB' de texte de n’importe quelle longueur et avec n’importe quel jeu de caractères.

La clause facultative USING spécifie l’algorithme de hachage non cryptographique à appliquer.Lorsque la clause USING n’est pas présente, l’algorithme PJW est appliqué, comme dans les versions précédentes de Firebird.

Algorithmes pris en charge :

non spécifié: Si aucun algorithme n’est spécifié, une version 64 bits de l’algorithme non cryptographique est utilisée.https://en.wikipedia.org/wiki/PJW_hash_function [fonction de hachage PJW^] (également connue sous le nom de ELF64) est utilisée.Cette fonction est très rapide et peut être utilisée à des fins générales (tables de hachage, etc.) mais présente un grand nombre de collisions.Pour un hachage plus sûr, vous devriez utiliser d’autres fonctions de hachage, explicitement spécifiées dans la clause USING, ou des hachages cryptographiques avec [fblangref-scalarfuncs-crypthash].

Pour cet algorithme de hachage, la fonction renvoie le type BIGINT.
CRC32: Si la clause USING spécifie l’algorithme CRC32, Firebird applique l’algorithme CRC32 en utilisant le polynôme 0x04C11DB7.

Pour cet algorithme, la fonction HASH renvoie un résultat de type INTEGER.

Exemple `HASH`

Example 1. Calcul du hachage avec algorithme PJW

SELECT HASH(x) FROM MyTable;
-- résultat du type BIGINT

Example 2. Calcul du hachage avec algorithme CRC32

SELECT HASH(x USING CRC32) FROM MyTable;
-- résultat du type INTEGER

Voir aussi :[fblangref-scalarfuncs-crypthash]

`HEX_DECODE()`

Disponible en

DSQL, PSQL

Syntaxe

HEX_DECODE (hex_data)

Table 1. paramètres de fonction `HEX_DECODE`
Paramètre	Description
hex_data	Données en représentation hexadécimale.

type de résultat de retour

VARBINARY ou BLOB.

La fonction HEX_DECODE décode une chaîne de caractères avec des données hexadécimales et retourne la valeur décodée.comme VARBINARY ou BLOB selon le type d’entrée et la taille de l’argument.Si la longueur du type hex_data n’est pas un multiple de 2, une erreur se produit pendant la préparation.Si la longueur de hex_data n’est pas un multiple de 2, une erreur se produit au moment de l’exécution.

Lorsque l’argument d’entrée n’est pas BLOB, la longueur du type résultant est calculée comme type_length / 2,où type_longueur est la longueur maximale en octets du type de l’argument d’entrée.

Exemple `HEX_DECODE`

Example 1. Utilisation de la fonction HEX_DECODE

select cast(hex_decode('48657861646563696D616C') as varchar(12))
from rdb$database;

CAST
============
Hexadecimal

Voir aussi :

[fblangref-scalarfuncs-hexencode], [fblangref-scalarfuncs-base64decode].

`HEX_ENCODE()`

Disponible en

DSQL, PSQL

Syntaxe

HEX_ENCODE (binary_data)

Table 1. paramètres de fonction `HEX_ENCODE`
Paramètre	Description
binary_data	Données binaires pour le codage

Le type de résultat renvoyé :

VARCHAR CHARACTER SET ASCII ou BLOB SUB_TYPE TEXT CHARACTER SET ASCII

La fonction HEX_ENCODE encode les données binaires avec un nombre hexadécimal et retourne la valeur encodée sous forme de VARCHAR CHARACTER SET ASCII ou de BLOB SUB_TYPE TEXT CHARACTER SET ASCII selon l’argument d’entrée.

Lorsque l’argument d’entrée n’est pas BLOB, la longueur du type résultant est calculée comme type_length * 2, où type_length est la longueur maximale en octets du type de l’argument d’entrée.

Exemple `HEX_ENCODE`

Example 1. Utilisation de la fonction HEX_ENCODE

select hex_encode('Hexadecimal')
from rdb$database;

HEX_ENCODE
======================
48657861646563696D616C

Voir aussi :

[fblangref-scalarfuncs-hexdecode], [fblangref-scalarfuncs-base64encode]

Fonctions pour travailler avec la date et l’heure

`DATEADD()`

Disponible en

DSQL, PSQL

Syntaxe

DATEADD (<args>)

<args> ::= <amount> <unit> TO <datetime>
         | <unit>, <amount>, <datetime>

<unit> ::=
    YEAR | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND

Table 1. paramètres de fonction `DATEADD`
Paramètre	Description
amount	Une expression de type `SMALLINT`, `INTEGER`, `BIGINT` ou `NUMERIC` (le négatif est soustrait).
unit	Composante date/heure.
datetime	Une expression de type `DATE`, `TIME` ou `TIMESTAMP`.

type de résultat de retour

DATE, TIME ou TIMESTAMP.

La fonction DATEADD vous permet d’ajouter un nombre donné d’années, de mois, de semaines, d’heures, de minutes, de secondes, de millisecondes à une valeur de date/heure donnée.

Note	Avec un argument de type `TIMESTAMP` et `DATE`, n’importe quel composant date/heure <unit> peut être utilisé ; Seuls `HOUR`, `MINUTE`, `SECOND` et `MILLISECOND` peuvent être utilisés pour le type de données `TIME`.

Exemple `DATEADD`

Example 1. Utilisation de la fonction DATEADD

DATEADD (28 DAY TO CURRENT_DATE)
DATEADD (-6 HOUR TO CURRENT_TIME)
DATEADD (MONTH, 9, DATEOFCONCEPTION)
DATEADD (-38 WEEK TO DATEOFBIRTH)
DATEADD (MINUTE, 90, CAST('NOW' AS TIME))
DATEADD (? YEAR TO DATE '11-SEP-1973')

SELECT
  CAST(DATEADD(-1 * EXTRACT(MILLISECOND FROM ts) MILLISECOND TO ts) AS VARCHAR(30)) AS t,
  EXTRACT(MILLISECOND FROM ts) AS ms
FROM (
    SELECT TIMESTAMP'2014-06-09 13:50:17.4971' as ts
    FROM RDB$DATABASE
) a

T                             MS
------------------------------------
2014-06-09 13:50:17.0000	497.1

Voir aussi :

[fblangref-scalarfuncs-datediff],[fblangref-datatypes-datetimeops].

`DATEDIFF()`

Disponible en

DSQL, PSQL

Syntaxe

DATEDIFF (<args>)

<args> ::= <unit> FROM <moment_1> TO <moment_2>
         | <unit>, <moment_1>, <moment_2>

<unit> ::=
    YEAR | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND

Table 1. paramètres de fonction `DATEDIFF`
Paramètre	Description
unit	Composante date/heure.
monent_1	Une expression de type `DATE`, `TIME` ou `TIMESTAMP`.
monent_2	Une expression de type `DATE`, `TIME` ou `TIMESTAMP`.

Le type de résultat renvoyé :

BIGINT

La fonction DATEDIFF renvoie le nombre d’années, de mois, de semaines, de jours, d’heures, de minutes, de secondes ou de millisecondes entre deux valeurs de date/heure.

Caractéristiques d’utilisation :

Les paramètres DATE et TIMESTAMP peuvent être utilisés ensemble. La co-utilisation du type TIME avec le type DATE et TIMESTAMP n’est pas autorisée ;
Avec un argument de type TIMESTAMP et DATE, n’importe quel composant date/heure <unit> peut être utilisé ;
Seuls HOUR, MINUTE, SECOND et MILLISECOND peuvent être utilisés pour le type de données TIME.

Note

La fonction DATEDIFF ne vérifie pas les différences dans les composants de date/heure plus petits que ceux spécifiés dans le premier argument <unit>. Le résultat est :
- DATEDIFF (YEAR, DATE '1-JAN-2009', DATE '31-DEC-2009') retournera 0, mais
- DATEDIFF (YEAR, DATE '31-DEC-2009', DATE '1-JAN-2010') retournera 1
Cependant, pour les plus petits composants de date/heure, nous avons :
- DATEDIFF (DAY, DATE '26-JUN-1908', DATE '11-SEP-1973') retournera 23818
- DATEDIFF (DAY, DATE '30-NOV-1971', DATE '8-JAN-1972') retourne 39
Une valeur négative de la fonction indique que la date/heure du moment_2 est inférieure à celle du moment_1.

Exemple `DATEDIFF`

Example 1. Utilisation de la fonction DATEDIFF

DATEDIFF (HOUR FROM CURRENT_TIMESTAMP TO TIMESTAMP '12-JUN-2059 06:00')
DATEDIFF (MINUTE FROM TIME '0:00' TO CURRENT_TIME)
DATEDIFF (MONTH, CURRENT_DATE, DATE '1-1-1900')
DATEDIFF (DAY FROM CURRENT_DATE TO CAST (? AS DATE))

Voir aussi :

[fblangref-scalarfuncs-dateadd],[fblangref-datatypes-datetimeops].

`EXTRACT()`

Disponible en

DSQL, PSQL

Syntaxe

EXTRACT (<part> FROM <datetime>)

<part> ::=
    YEAR | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND
  | TIMEZONE_HOUR | TIMEZONE_MINUTE

Table 1. paramètres de fonction `EXTRACT`
Paramètre	Description
part	Composante date/heure.
datetime	Une expression de type `DATE`, `TIME` ou `TIMESTAMP`.

Le type de résultat renvoyé :

SMALLINT ou NUNERIC.

La fonction EXTRACT extrait les composants de date et d’heure des types de données DATE, TIME et TIMESTAMP.

Table 2. Types et plages de résultats de fonctions `EXTRACT`
Composant date/heure	Type	Plage	Commentaire
`YEAR`	`SMALLINT`	1–9999	L’année
`QUARTER`	`SMALLINT`	1-4	Trimestre
`MONTH`	`SMALLINT`	1–12	Mois
`WEEK`	`SMALLINT`	1–53	Numéro de la semaine de l’année
`DAY`	`SMALLINT`	1–31	Jour
`WEEKDAY`	`SMALLINT`	0–6	Jour de la semaine. 0 — Dimanche
`YEARDAY`	`SMALLINT`	0–365	Le numéro du jour de l’année. 0 = 1 janvier
`HOUR`	`SMALLINT`	0–23	Heure
`MINUTE`	`SMALLINT`	0–59	Minute
`SECOND`	`NUMERIC(9,4)`	0.0000–59.9999	Secondes. Inclut les millisecondes
`MILLISECOND`	`NUMERIC(9,1)`	0.0–999.9	Millisecondes
`TIMEZONE_HOUR`	`SMALLINT`	de -14 à +14	Décalage des heures du fuseau horaire
`TIMEZONE_MINUTE`	`SMALLINT`	de -59 à +59	Décalage des minutes du fuseau horaire

Note	Si le composant date/heure n’est pas présent dans l’argument date/heure, par exemple SECOND dans un argument de type DATE ou YEAR dans TIME, la fonction provoquera une erreur.

À partir d’un argument de type DATE ou TIMESTAMP, vous pouvez extraire le numéro de la semaine. Selon la norme ISO-8601, la semaine commence le lundi et comprend toujours 7 jours. La première semaine de l’année est celle qui compte le plus de jours dans la nouvelle année (au moins 4) : les jours 1-3 peuvent appartenir à la semaine précédente (52 ou 53) de l’année précédente. Par analogie, les jours 1-3 de l’année en cours peuvent appartenir à la semaine 1 de l’année suivante.

Example 1. Utilisation de la fonction EXTRACT

/* récupérer le numéro du trimestre par la date */
SELECT (EXTRACT(MONTH FROM CURRENT_TIMESTAMP)-1)/3+1
FROM RDB$DATABASE

Voir aussi :

Types de données pour travailler avec la date et l’heure.

`FIRST_DAY()`

Disponible en

DSQL, PSQL

Syntaxe

FIRST_DAY(OF <period> FROM date_or_timestamp)

<period> ::= YEAR | QUARTER | MONTH | WEEK

Table 1. paramètres de fonction `FIRST_DAY`
Paramètre	Description
date_or_timestamp	Une expression de type `DATE` ou `TIMESTAMP [WITH

type de résultat de retour

DATE ou TIMESTAMP [WITH | WITHOUT] TIME ZONE.

Renvoie le premier jour de l’année, du mois ou de la semaine pour une date donnée.

Note	Le premier jour de la semaine est le dimanche, tel que retourné par la fonction `EXTRACT` avec la partie `WEEKDAY`. Lorsqu’une expression de type `TIMESTAMP` est passée comme argument à la fonction, la valeur de retour stocke la partie temps.

Exemple `FIRST_DAY`

Example 1. Utilisation de la fonction FIRST_DAY

SELECT FIRST_DAY(OF MONTH FROM current_date) FROM rdb$database;
SELECT FIRST_DAY(OF YEAR FROM current_timestamp) FROM rdb$database;
SELECT FIRST_DAY(OF WEEK FROM date '2022-11-01') FROM rdb$database;

Voir aussi :

[fblangref-scalarfuncs-lastday].

`LAST_DAY()`

Disponible en

DSQL, PSQL

Syntaxe

LAST_DAY(OF <period> FROM date_or_timestamp)

<period> ::=  YEAR | QUARTER | MONTH | WEEK

Table 1. paramètres de fonction `LAST_DAY`
Paramètre	Description
date_or_timestamp	Une expression de type `DATE` ou `TIMESTAMP [WITH

type de résultat de retour

DATE ou TIMESTAMP [WITH | WITHOUT] TIME ZONE.

Renvoie le dernier jour de l’année, du mois ou de la semaine pour une date donnée.

Note	Le dernier jour de la semaine est le samedi, tel que retourné par la fonction `EXTRACT` avec la partie `WEEKDAY`. Lorsqu’une expression de type `TIMESTAMP` est passée comme argument à la fonction, la valeur de retour stocke la partie temps.

Exemple `LAST_DAY`

Example 1. Utilisation de la fonction LAST_DAY

SELECT LAST_DAY(OF MONTH FROM current_date) FROM rdb$database;
SELECT LAST_DAY(OF YEAR FROM current_timestamp) FROM rdb$database;
SELECT LAST_DAY(OF WEEK FROM date '2017-11-01') FROM rdb$database;

Voir aussi :

[fblangref-scalarfuncs-firstday].

Fonctions permettant de travailler avec le type BLOB

`BLOB_APPEND()`

Disponible en

DSQL, PSQL

Syntaxe

BLOB_APPEND(<blob> [, <value1>, ... <valueN>]

Table 1. paramètres de fonction `BLOB_APPEND`
Paramètre	Description
blob	BLOB ou NULL.
value	La valeur de n’importe quel type.

type de résultat de retour

BLOB temporaire non fermée avec l’indicateur BLB_close_on_read.

La fonction BLOB_APPEND est conçue pour concaténer des BLOBs sans créer deBLOBs intermédiaires. Une opération de concaténation normale avec des arguments de type BLOB créera toujours autant de BLOB temporaires,autant de fois qu’il est utilisé.

Arguments d’entrée :

Le comportement suivant de la fonction est défini pour le premier argument en fonction de sa valeur :
- NULL : un nouveau BLOB vide et non fermé sera créé
- BLOB permanent (de la table) ou BLOB temporaire déjà fermé :un nouveau BLOB vide et non fermé sera créé et le contenu de l’espace de stockage du premier BLOB y sera ajouté.
- BLOB temporaire non fermé : il sera utilisé ultérieurement
- les autres types de données sont convertis en chaîne, un BLOB temporaire non fermé sera créé avec le contenu de cette chaîne.
Le reste des arguments peut être de n’importe quel type. Le comportement suivant est défini pour eux :
- NULL est ignoré
- les non-BLOB sont convertis en chaînes de caractères (selon les règles normales) et ajoutés au contenu du résultat.résultats
- Les BLOB, si nécessaire, sont translittérés dans le jeu de caractères du premier argument et leur contenuleur contenu est ajouté au résultat

Comme valeur de sortie, la fonction BLOB_APPEND renvoie un BLOB temporaire non fermé avec l’indicateur BLOB_close_on_read.Il s’agit soit d’un nouveau BLOB, soit du même que dans le premier argument. Ainsi, une série d’opérations commeblob = BLOB_APPEND(blob, …) créera au maximum un BLOB (sauf si vous essayez d’ajouter un BLOB à lui-même).Cette BLOB sera automatiquement fermée par le moteur lorsqu’une tentative est faite pour la lire par le client, l’écrire dans une table ou l’utiliser dans d’autres expressions qui nécessitent la lecture de son contenu.

Note	La vérification d’un BLOB pour NULL en utilisant l’opérateur `IS [NOT] NULL` ne le lit pas, et donc un BLOB temporaire ne sera pas fermé par de telles vérifications.

execute block
returns (b blob sub_type text)
as
begin
  -- créera un nouveau BLOB temporaire non fermé.
  -- et y écrira la chaîne de caractères du 2ème argument
  b = blob_append(null, 'Hello ');
  -- ajoute deux lignes au BLOB temporaire sans la fermer
  b = blob_append(b, 'World', '!');
  -- la comparaison d'une BLOB à une chaîne de caractères la fermera, car elle doit lire le contenu du BLOB
  if (b = 'Hello World!') then
  begin
  -- ...
  end
  -- va créer un BLOB fermé temporaire en y ajoutant une ligne
  b = b || 'Close';
  suspend;
end

Tip

Utilisez les fonctions LIST et BLOB_APPEND pour la concaténation des BLOB. Cela permet de réduire la consommation de mémoire, les entrées/sorties sur le disque et d’éviter la prolifération des bases de données due à la création de nombreux BLOB temporaires lors de l’utilisation d’instructions de concaténation.

Example 1. Utilisation de la fonction BLOB_APPEND

Supposons que vous ayez besoin de construire du JSON du côté du serveur. Nous avons un paquet PSQL JSON_UTILS avec un ensemble de fonctions pour convertir les types de données élémentaires en notation JSON. Ensuite, la construction du JSON en utilisant la fonction BLOB_APPEND ressemblera à ceci

EXECUTE BLOCK
RETURNS (
    JSON_STR BLOB SUB_TYPE TEXT CHARACTER SET UTF8)
AS
  DECLARE JSON_M BLOB SUB_TYPE TEXT CHARACTER SET UTF8;
BEGIN
  FOR
      SELECT
          HORSE.CODE_HORSE,
          HORSE.NAME,
          HORSE.BIRTHDAY
      FROM HORSE
      WHERE HORSE.CODE_DEPARTURE = 15
      FETCH FIRST 1000 ROW ONLY
      AS CURSOR C
  DO
  BEGIN
    SELECT
      LIST(
          '{' ||
          JSON_UTILS.NUMERIC_PAIR('age', MEASURE.AGE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('height', MEASURE.HEIGHT_HORSE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('length', MEASURE.LENGTH_HORSE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('chestaround', MEASURE.CHESTAROUND) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('wristaround', MEASURE.WRISTAROUND) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('weight', MEASURE.WEIGHT_HORSE) ||
          '}'
      ) AS JSON_M
    FROM MEASURE
    WHERE MEASURE.CODE_HORSE = :C.CODE_HORSE
    INTO JSON_M;

    JSON_STR = BLOB_APPEND(
      JSON_STR,
      IIF(JSON_STR IS NULL, '[', ',' || ascii_char(13)),
      '{',
      JSON_UTILS.INTEGER_PAIR('code_horse', C.CODE_HORSE),
      ',',
      JSON_UTILS.STRING_PAIR('name', C.NAME),
      ',',
      JSON_UTILS.TIMESTAMP_PAIR('birthday', C.BIRTHDAY),
      ',',
      JSON_UTILS.STRING_VALUE('measures') || ':[', JSON_M, ']',
      '}'
    );
  END
  JSON_STR = BLOB_APPEND(JSON_STR, ']');
  SUSPEND;
END

Un exemple similaire utilisant l’opérateur de concaténation conventionnel || est 18 fois plus lent, et effectue 1000 fois plus d’opérations d’écriture sur le disque.

IIF()

IIF()

Exemple IIF

MAXVALUE()

Exemple MAXVALUE

MINVALUE()

Exemple MINVALUE

NULLIF()

Exemple NULLIF

Autres fonctions

MAKE_DBKEY()

RDB$ERROR()

RDB$GET_TRANSACTION_CN()

RDB$ROLE_IN_USE()

RDB$SYSTEM_PRIVILEGE()

Fonctions mathématiques

ABS()

COS()

COSH()

COT()

EXP()

FLOOR()

LN()

LOG()

LOG10()

MOD()

PI()

ACOS()

POWER()

RAND()

ROUND()

Exemple ROUND

SIGN()

SIN()

SINH()

SQRT()

TAN()

TANH()

TRUNC()

ACOSH()

ASIN()

ASINH()

ATAN()

ATAN2()

ATANH()

CEIL(), CEILING()

Fonctions pour travailler avec des chaînes de caractères

ASCII_CHAR()

LEFT()

LOWER()

Exemple LOWER

LPAD()

Exemple LPAD

OCTET_LENGTH()

Exemple OCTET_LENGTH

OVERLAY()

Exemple OVERLAY

POSITION()

Exemple POSITION

REPLACE()

Exemple REPLACE

REVERSE()

Exemple REVERSE

RIGHT()

RPAD()

Exemple RPAD

ASCII_VAL()

SUBSTRING()

Position SUBSTRING

SUBSTRING par une expression régulière

TRIM()

Exemple TRIM

UNICODE_CHAR()

Exemple UNICODE_CHAR

UNICODE_VAL()

Exemple UNICODE_VAL

UPPER()

Exemple UPPER

BASE64_DECODE()

Exemple BASE64_DECODE

`IIF()`

Exemple `IIF`

`MAXVALUE()`

Exemple `MAXVALUE`

`MINVALUE()`

Exemple `MINVALUE`

`NULLIF()`

Exemple `NULLIF`

`MAKE_DBKEY()`

`RDB$ERROR()`

`RDB$GET_TRANSACTION_CN()`

`RDB$ROLE_IN_USE()`

`RDB$SYSTEM_PRIVILEGE()`

`ABS()`

`COS()`

`COSH()`

`COT()`

`EXP()`

`FLOOR()`

`LN()`

`LOG()`

`LOG10()`

`MOD()`

`PI()`

`ACOS()`

`POWER()`

`RAND()`

`ROUND()`

Exemple `ROUND`

`SIGN()`

`SIN()`

`SINH()`

`SQRT()`

`TAN()`

`TANH()`

`TRUNC()`

`ACOSH()`

`ASIN()`

`ASINH()`

`ATAN()`

`ATAN2()`

`ATANH()`

`CEIL()`, `CEILING()`

`ASCII_CHAR()`

`LEFT()`

`LOWER()`

Exemple `LOWER`

`LPAD()`

Exemple `LPAD`

`OCTET_LENGTH()`

Exemple `OCTET_LENGTH`

`OVERLAY()`

Exemple `OVERLAY`

`POSITION()`

Exemple `POSITION`

`REPLACE()`

Exemple `REPLACE`

`REVERSE()`

Exemple `REVERSE`

`RIGHT()`

`RPAD()`

Exemple `RPAD`

`ASCII_VAL()`

`SUBSTRING()`

Position `SUBSTRING`

`SUBSTRING` par une expression régulière

`TRIM()`

Exemple `TRIM`

`UNICODE_CHAR()`

Exemple `UNICODE_CHAR`

`UNICODE_VAL()`

Exemple `UNICODE_VAL`

`UPPER()`

Exemple `UPPER`

`BASE64_DECODE()`

Exemple `BASE64_DECODE`

`BASE64_ENCODE()`

Exemple `BASE64_ENCODE`

`BIT_LENGTH()`

Exemple `BIT_LENGTH`