FirebirdSQL logo
 Instructions de procédure SQL (PSQL)Fonctions agrégées 

Les fonctions scalaires produisent une valeur scalaire unique pour chaque ligne qui répond au critère de recherche de la requête

Vous pouvez utiliser des fonctions scalaires pour convertir une valeur d’un type de données dans un autre et traiter les valeurs de date/heure. Vous pouvez également les utiliser pour manipuler des parties de chaînes de caractères et éviter les valeurs null.

Une fonction scalaire prend un ou plusieurs arguments d’entrée et renvoie un résultat de valeur unique. Une fonction scalaire peut être utilisée partout où une expression peut être utilisée.

Les restrictions relatives à l’utilisation des fonctions d’agrégation ne s’appliquent pas aux fonctions scalaires, car une fonction scalaire est appliquée à des valeurs de paramètre unique plutôt qu’à des ensembles de valeurs. L’argument d’une fonction scalaire peut être une fonction. Toutefois, les restrictions qui s’appliquent à l’utilisation d’expressions et de fonctions d’agrégation s’appliquent également lorsqu’une expression ou une fonction d’agrégation est utilisée dans une fonction scalaire. Par exemple, l’argument d’une fonction scalaire peut être une fonction d’agrégation uniquement si une fonction d’agrégation est autorisée dans le contexte dans lequel la fonction scalaire est utilisée.

Fonctions pour traiter les variables contextuelles

docnext count = 100

RDB$GET_CONTEXT()

Disponible en

DSQL, PSQL

Syntaxe
RDB$GET_CONTEXT('<namespace>', 'varname')

<namespace> ::= SYSTEM | DDL_TRIGGER | USER_SESSION | USER_TRANSACTION
Table 1. paramètres de fonction RDB$GET_CONTEXT
Paramètre Description

namespace

Namespace.

varname

Le nom de la variable.Sensible à la casse.La longueur maximale est de 80 octets.
Le type de résultat renvoyé :

VARCHAR(255) CHARACTER SET NONE

La fonction RDB$GET_CONTEXT renvoie la valeur d’une variable contextuelle de l’un des espaces de noms.

Les espaces de noms suivants existent actuellement :

  • SYSTEM — fournit un accès aux variables du contexte système. Ces variables sont en lecture seule ;

  • USER_SESSION — fournit un accès aux variables de contexte utilisateur définies via la fonction RDB$SET_CONTEXT. Les variables existent pour la durée de la connexion ;

  • USER_TRANSACTION — Fournit un accès aux variables de contexte utilisateur définies via la fonction RDB$SET_CONTEXT. Les variables existent pendant la transaction ;

  • DL_TRIGGER — fournit un accès aux variables de contexte du système disponibles uniquement pendant l’exécution du trigger DDL. Ces variables sont en lecture seule.

Les espaces de noms USER_SESSION et USER_TRANSACTION sont initialement vides et l’utilisateur crée les variables et les remplit avec la fonction RDB$SET_CONTEXT.

Note

Pour éviter les attaques DoS, il y a une limite de 1000 variables dans un "espace de noms".

Si la variable demandée par la fonction existe dans l’espace de noms, elle est retournée sous la forme d’une chaîne VARCHAR(255) CHARACTER SET NONE. Si une variable inexistante dans l’espace de noms SYSTEM est référencée, il y a une erreur si cela se produit dans les espaces de noms USER_SESSION ou USER_TRANSACTION - la fonction retourne NULL.

Espace de nommage SYSTEM

Variables de l’espace de nommage SYSTEM
CLIENT_ADDRESS

Adresse du client. Pour TCPv4 - adresse IP, pour XNET - ID du processus local. Pour les autres cas NULL.

CLIENT_HOST

Le nom d’hôte du protocole réseau du client distant. La valeur est renvoyée pour tous les protocoles pris en charge.

CLIENT_OS_USER

Le nom d’utilisateur du système d’exploitation de l’ordinateur client.

CLIENT_PID

Le PID du processus sur l’ordinateur client.

CLIENT_PROCESS

Chemin complet de l’application client se connectant à la base de données.

CLIENT_VERSION

La version de la bibliothèque client (fbclient) utilisée par l’application client.

CURRENT_ROLE

La variable globale CURRENT_ROLE.

CURRENT_USER

La variable globale CURRENT_USER.

DB_NAME

Le nom canonique de la base de données actuelle. C’est soit un nom d’alias (si la connexion au nom de fichier est interdite DatabaseAccess = NONE) ou, sinon, un nom de fichier de base de données entièrement étendu.

DB_FILE_ID

Identifiant unique de la base de données actuelle au niveau du système de fichiers.

DB_GUID

GUID de la base de données.

EFFECTIVE_USER

L’utilisateur effectif à l’heure actuelle. Indique l’utilisateur avec des privilèges dont la procédure, la fonction ou le déclencheur est en cours d’exécution.

ENGINE_VERSION

Version du serveur Firebird.

EXT_CONN_POOL_SIZE

Taille du pool de connexions externes.

EXT_CONN_POOL_LIFETIME

La durée de vie des connexions inactives dans le pool de connexion externe.

EXT_CONN_POOL_IDLE_COUNT

Le nombre actuel de connexions inactives dans le pool de connexions externes.connexions.

EXT_CONN_POOL_ACTIVE_COUNT

Le nombre actuel de connexions actives dans le pool de connexions externes.

GLOBAL_CN

Dernière valeur du compteur global actuel de Commit Number

ISOLATION_LEVEL

Le niveau d’isolement de la transaction actuelle — CURRENT_TRANSACTION. Valeurs : 'READ_COMMITED', 'SNAPSHOT' ou 'CONSISTENCY'.

LOCK_TIMEOUT

Le temps qu’une transaction attend pour que la ressource soit libérée lorsqu’elle est bloquée, en secondes.

NETWORK_PROTOCOL

Le protocole utilisé pour se connecter à la base de données. Valeurs possibles : 'TCPv4', 'TCPv6', 'WNET', 'XNET', NULL.

PARALLEL_WORKERS

Nombre maximal de flux de travail parallèles dans la connexion actuelle.

READ_ONLY

Indique si la transaction est une transaction en lecture seule. 'FALSE' pour les transactions en lecture-écriture 'TRUE' pour la lecture seule.

REPLICA_MODE

Mode de réplication : chaîne vide ou NULL--base de données primaire, READ-ONLY--réplique en lecture seule, READ-WRITE--réplique en lecture-écriture.

REPLICATION_SEQUENCE

La valeur actuelle de la séquence de réplication (le numéro du dernier segment écrit dans le journal de réplication).

SESSION_ID

Variable globale CURRENT_CONNECTION.

SESSION_IDLE_TIMEOUT

Contient la valeur actuelle du délai d’inactivité de la connexion en secondes, qui a été définie au niveau de la connexion, ou zéro si aucun délai n’a été défini.

SESSION_TIMEZONE

Le fuseau horaire actuel défini dans la session en cours.

SNAPSHOT_NUMBER

Nombre d’instantanés de la base de données : niveau transaction (pour la transaction SNAPSHOT ou CONSISTENCY) ou niveau requête (pour la transaction READ COMMITTED READ CONSISTENCY). NULL si le snapshot n’existe pas.

STATEMENT_TIMEOUT

Contient la valeur actuelle du délai d’exécution de l’opérateur en millisecondes, qui a été défini au niveau de la connexion, ou zéro si aucun délai n’a été défini.

TRANSACTION_ID

Variable globale CURRENT_TRANSACTION.

WIRE_COMPRESSED

Si la compression du trafic réseau est utilisée ou non. Si la compression du trafic réseau est utilisée, elle renvoie 'TRUE', sinon 'FALSE'. Pour les connexions embarquées — renvoie NULL.

WIRE_ENCRYPTED

Si le cryptage du trafic réseau est utilisé. Si le cryptage du trafic réseau est utilisé, renvoie "VRAI", sinon "FAUX". Pour les connexions embarquées — renvoie NULL.

WIRE_CRYPT_PLUGIN

Si le cryptage du trafic réseau est utilisé, renvoie le nom du plugin de cryptage actuel, sinon NULL.

Espace de nommage`DDL_TRIGGER`

L’utilisation de l’espace de nom DDL_TRIGGER n’est autorisée que pendant l’exécution du déclencheur DDL. Son utilisation est également autorisée dans les procédures stockées et les fonctions appelées par les déclencheurs DDL.

Le contexte DDL_TRIGGER fonctionne comme une pile. Avant que le trigger DDL ne soit déclenché, les valeurs liées à la commande en cours d’exécution sont placées sur cette pile. Lorsque le trigger est terminé, les valeurs sont éjectées.Ainsi, dans le cas d’instructions DDL en cascade, lorsque chaque commande DDL utilisateur déclenche un trigger DDL et que ce trigger déclenche d’autres commandes DDL, avec EXECUTE STATEMENT, les valeurs des variables dans l’espace de noms DDL_TRIGGER correspondront à la commande qui a déclenché le dernier trigger DDL dans la pile d’appels.

Variables de l’espace de nommage DDL_TRIGGER
EVENT_TYPE

type d’événement (CREATE, ALTER, DROP).

OBJECT_TYPE

type d’objet (TABLE, VIEW et al.).

DDL_EVENT

(<ddl event item>), où <ddl_event_item> c’est EVENT_TYPE || ' ' || OBJECT_TYPE

OBJECT_NAME

le nom de l’objet de métadonnées.

OLD_OBJECT_NAME

le nom de l’objet de métadonnées avant son renommage.

NEW_OBJECT_NAME

le nom de l’objet de métadonnées après renommage.

SQL_TEXT

le texte de la requête SQL.

Note

Une fois de plus, notez que les noms d’espaces de noms et de variables sont sensibles à la casse, doivent être des chaînes de caractères non vides, et sont entourés de guillemets !

Exemples

Example 1. Utilisation de la fonction RDB$GET_CONTEXT
NEW.USER_ADR = RDB$GET_CONTEXT ('SYSTEM', 'CLIENT_ADDRESS');
Voir aussi :

RDB$SET_CONTEXT.

RDB$SET_CONTEXT()

Disponible en

DSQL, PSQL

Syntaxe
RDB$SET_CONTEXT('<namespace>', 'varname', {<value> | NULL})

<namespace> ::= USER_SESSION | USER_TRANSACTION
Table 1. paramètres de fonction RDB$SET_CONTEXT
Paramètre Description

namespace

Namespace.

varname

Nom de la variable, sensible à la casse. Longueur maximale de 80 octets.

value

Données de tout type, à condition qu’elles puissent être converties en CHARACTER SET NONE de type VARCHAR(255).
Type de résultat de retour

INTEGER

La fonction RDB$SET_CONTEXT crée, définit ou efface une variable dans l’un des espaces de noms utilisés par l’utilisateur : USER_SESSION ou USER_TRANSACTION.

La fonction renvoie 1 si la variable existait déjà avant l’appel et 0 si ce n’est pas le cas. Pour supprimer une variable, mettez-la à NULL. Si l’espace de noms donné n’existe pas, la fonction renverra une erreur. L’espace de noms et le nom de la variable sont sensibles à la casse, doivent être des chaînes de caractères non vides, et entourées de guillemets.

Note

  • L’espace de nom SYSTEM est en lecture seule ;

  • Le nombre maximum de variables dans une connexion (pour l’espace USER_SESSION) ou une transaction (pour l’espace USER_TRANSACTION) est de 1000 ;

  • Toutes les variables de l’espace de nom USER_TRANSACTION sont sauvegardées lorsque ROLLBACK RETAIN ou ROLLBACK TO SAVEPOINT, indépendamment de l’endroit où elles sont définies au moment de la transaction.
Example 1. Utilisation de la fonction RDB$SET_CONTEXT
SELECT RDB$SET_CONTEXT ('USER_SESSION', 'DEBUGL', 3)
FROM RDB$DATABASE;

-- la syntaxe suivante est disponible dans PSQL
RDB$SET_CONTEXT('USER_SESSION', 'RECORDSFOUND', RECCOUNTER);

SELECT RDB$SET_CONTEXT ('USER_TRANSACTION', 'SAVEPOINTS', 'YES')
FROM RDB$DATABASE;
Example 2. Utilisation de fonctions pour travailler avec des variables contextuelles
SET TERM ^;
CREATE PROCEDURE set_context(User_ID VARCHAR(40),
                             Trn_ID INT) AS
BEGIN
  RDB$SET_CONTEXT('USER_TRANSACTION', 'Trn_ID', Trn_ID);
  RDB$SET_CONTEXT('USER_TRANSACTION', 'User_ID', User_ID);
END^
SET TERM ;^

CREATE TABLE journal (
   jrn_id INTEGER NOT NULL PRIMARY KEY,
   jrn_lastuser VARCHAR(40),
   jrn_lastaddr VARCHAR(255),
   jrn_lasttran INTEGER
);

SET TERM ^;
CREATE TRIGGER UI_JOURNAL
FOR JOURNAL BEFORE INSERT OR UPDATE
AS
BEGIN
  new.jrn_lastuser = RDB$GET_CONTEXT('USER_TRANSACTION',
                                     'User_ID');
  new.jrn_lastaddr = RDB$GET_CONTEXT('SYSTEM',
                                     'CLIENT_ADDRESS');
  new.jrn_lasttran = RDB$GET_CONTEXT('USER_TRANSACTION',
                                         'Trn_ID');
END^
SET TERM ;^

EXECUTE PROCEDURE set_context('skidder', 1);

INSERT INTO journal(jrn_id) VALUES(0);

COMMIT;
Voir aussi :

RDB$GET_CONTEXT.

Fonctions pour traiter les UUID

CHAR_TO_UUID()

Disponible en

DSQL, PSQL

Syntaxe
CHAR_TO_UUID (ascii_uuid)
Table 1. paramètres de fonction CHAR_TO_UUID
Paramètre Description

ascii_uuid

Représentation de l’UUID en 36 caractères : “-” (trait d’union) dans les positions 9, 14, 19 et 24 ; chiffres hexadécimaux valides dans toutes les autres positions, c’est-à-dire : “-”.'A0bF4E45-3029-2a44-D493-4998c9b439A3'.
type de résultat de retour

BINARY(16)

La fonction CHAR_TO_UUID convertit un UUID lisible de 36 caractères en la valeur UUID correspondante de 16 octets.

Exemple CHAR_TO_UUID

Example 1. Utilisation de la fonction CHAR_TO_UUID
SELECT CHAR_TO_UUID('A0bF4E45-3029-2a44-D493-4998c9b439A3') FROM rdb$database
-- returns A0BF4E4530292A44D4934998C9B439A3 (16-byte string)

SELECT CHAR_TO_UUID('A0bF4E45-3029-2A44-X493-4998c9b439A3') FROM rdb$database
-- erreur : -L'argument UUID lisible par l'homme pour CHAR_TO_UUID doit être
-- un chiffre hexagonal à la position 20 au lieu de "X (ASCII 88)"
Voir aussi :

[fblangref-scalarfuncs-gen-uuid], [fblangref-scalarfuncs-uuid-to-char].

GEN_UUID()

Disponible en

DSQL, PSQL

Syntaxe
GEN_UUID()
type de résultat de retour

BINARY(16)

La fonction renvoie un identifiant unique universel sous la forme d’une chaîne de caractères de 16 octets conforme à la norme RFC-4122. La fonction renvoie une chaîne UUID de version 4, où quelques bits sont réservés et le reste est aléatoire.

Exemple GEN_UUID

Example 1. Utilisation de la fonction GEN_UUID
SELECT GEN_UUID() AS GUID FROM RDB$DATABASE
GUID
========

017347BFE212B2479C00FA4323B36320
Voir aussi :

CHAR_TO_UUID, UUID_TO_CHAR.

UUID_TO_CHAR()

Disponible en

DSQL, PSQL

Syntaxe
UUID_TO_CHAR (uuid)
Table 1. paramètres de fonction UUID_TO_CHAR
Paramètre Description

uuid

UUID à 16 octets.
type de résultat de retour

CHAR(36)

La fonction UID_TO_CHAR convertit un UUID de 16 octets en sa représentation lisible par l’homme de 36 caractères ASCII. Le type de valeur de retour est CHAR(36).

Exemple UUID_TO_CHAR

Example 1. Utilisation de la fonction UUID_TO_CHAR
SELECT UUID_TO_CHAR(GEN_UUID()) FROM RDB$DATABASE;

SELECT UUID_TO_CHAR(x'876C45F4569B320DBCB4735AC3509E5F') FROM RDB$DATABASE;
-- returns '876C45F4-569B-320D-BCB4-735AC3509E5F'

SELECT UUID_TO_CHAR(GEN_UUID()) FROM RDB$DATABASE;
-- returns e.g. '680D946B-45FF-DB4E-B103-BB5711529B86'

SELECT UUID_TO_CHAR('Firebird swings!') FROM RDB$DATABASE;
-- returns '46697265-6269-7264-2073-77696E677321'
Voir aussi :

[fblangref-scalarfuncs-gen-uuid], [fblangref-scalarfuncs-char-to-uuid].

Fonctions pour travailler avec des générateurs (séquences)

GEN_ID()

Disponible en

DSQL, PSQL

Syntaxe
GEN_ID (generator-name, step)
Table 1. paramètres de fonction GEN_ID
Paramètre Description

generator-name

Nom du générateur (séquence).

step

Increment Step.
type de résultat de retour

BIGINT

La fonction GEN_ID incrémente la valeur du générateur ou de la séquence et renvoie la nouvelle valeur.

Si step est 0, la fonction ne fera rien avec la valeur du générateur et retournera sa valeur actuelle.

  • Depuis Firebird 2.0, il est désormais possible d’utiliser un générateur conforme aux normes SQL pour récupérer la valeur de la séquence suivante (générateur).Opérateur compatible avec SQL NEXT VALUE FOR.

Si la valeur de step est inférieure à zéro, la valeur du générateur sera diminuée. Soyez extrêmement prudent avec de telles manipulations dans la base de données, elles peuvent entraîner une perte d’intégrité des données.

Exemple GEN_ID

Example 1. Utilisation de la fonction GEN_ID
NEW.ID = GEN_ID (GEN_TABLE_ID, 1);
Voir aussi :

NEXT VALUE FOR,SEQUENCE (GENERATOR),ALTER SEQUENCE,SET GENERATOR.

Fonctions conditionnelles

COALESCE()

Disponible en

DSQL, PSQL

Syntaxe
COALESCE (<exp1>, <exp2> [, <expN> ... ])
Table 1. paramètres de fonction COALESCE
Paramètre Description

exp1, exp2 …​ expN

Expressions de tout type compatible.
type de résultat de retour

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

La fonction COALESCE prend deux arguments ou plus et retourne la valeur du premier argument non NULL. Si tous les arguments sont NULL, le résultat est également NULL.

Exemple COALESCE

Example 1. Utilisation de la fonction COALESCE

Cet exemple tente d’utiliser toutes les données disponibles pour composer un nom complet. Le champ NICKNAME de la table PERSONS est sélectionné. S’il est NULL, la valeur du champ FIRSTNAME est prise. S’il est également NULL, la chaîne de caractères "Mr./Mrs.`" est utilisée. Ensuite le nom de famille (le champ `LASTNAME) est ajouté à la valeur de la fonction COALESCE. Notez que ce schéma ne fonctionne correctement que si les champs à sélectionner sont NULL ou non vides : si l’un d’eux est une chaîne vide, c’est ce qui sera renvoyé comme valeur de la fonction COALESCE.

SELECT
  COALESCE(PE.NICKNAME, PE.FIRSTNAME, 'Mr./Mrs.') ||
  ' ' || PE.LASTNAME AS FULLNAME
FROM PERSONS PE
Example 2. Utilisation de la fonction COALESCE avec des fonctions agrégées

Dans cet exemple, si la requête renvoie NULL lors du calcul de la somme, elle renverra 0.

SELECT coalesce (sum (q), 0)
FROM bills
WHERE ...
Voir aussi :

CASE.

DECODE()

Disponible en

DSQL, PSQL

Syntaxe
DECODE(<testexpr>,
  <expr1>, <result1>
  [<expr2>, <result2> …]
  [, <defaultresult>])

construction équivalente CASE

CASE <testexpr>
  WHEN <expr1> THEN <result1>
  [WHEN <expr2> THEN <result2> …]
  [ELSE <defaultresult>]
END
Table 1. paramètres de fonction DECODE
Paramètre Description

testexpr

Expressions de tout type compatible qui sont comparées à des expressions <expr1>, <expr2> …​ <exprN>

expr1, expr2, …​ exprN

Expressions de tout type compatible par rapport à l’expression <testexpr>.

result1, result2, …​ resultN

Retourne des expressions de n’importe quel type.

defaultresult

Une expression renvoyée si aucune des conditions n’a été remplie.
type de résultat de retour

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

Cette fonction est équivalente à la construction Simple CASE, dans laquelle une expression donnée est comparée à d’autres expressions avant qu’une correspondance soit trouvée.Le résultat est la valeur donnée après l’expression avec laquelle la correspondance est trouvée.Si aucune correspondance n’est trouvée, la valeur par défaut est retournée (si elle est, bien sûr, donnée — sinon NULL est retourné).

Caution

Une correspondance est équivalente à l’opérateur ‘=’, c’est-à-dire que si testexpr est défini à NULL alors il ne correspond à aucune des expr, même celles qui sont définies à NULL.

Exemple DECODE

Example 1. Utilisation de la fonction DECODE
select name,
  age,
  decode(upper(sex),
         'M', 'Male',
         'F', 'Female',
         'Unknown'),
  religion
from people
Voir aussi :

CASE.

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

  1. 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.

  2. 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é.

  3. 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.

  4. 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é.

  5. Le quatrième argument (ppnum) — est le numéro de page de l’index logique (PP) dans la table.

  6. Tous les nombres commencent par zéro. La valeur maximale autorisée pour dpnum et ppnum est 232 (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é.

  7. Si l’un des arguments spécifiés est NULL, le résultat est également NULL.

  8. 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:

  1. 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)

  2. 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)

  3. 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)

  4. 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, enombre.

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 (xy).

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].