Guide Du Langage SQL De Firebird 5.0

Fonctions Window (analytique)Gestion des transactions

`LOCALTIME`

Disponible en

DSQL, PSQL, ESQL

Syntaxe

LOCALTIME [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Contexte Paramètres de la variable LOCALTIME
Paramètre	Description
precision	Précision. La valeur par défaut est 0. Non supporté dans ESQL.

type de résultat de retour

TIME WITHOUT TIME ZONE

La variable LOCALTIME renvoie l’heure actuelle dans le fuseau horaire de la session, sans information sur le fuseau horaire. La précision détermine le nombre de décimales à considérer dans les fractions de seconde. La précision par défaut est 0.

Note

Dans un bloc de code PSQL (procédure, trigger, bloc exécutable), la valeur de LOCALTIME ne change pas lors de son exécution. Lors de l’invocation d’un code imbriqué, la valeur ne changera pas non plus et sera égale à la valeur du code de niveau supérieur. Utilisez CAST('NOW' AS TIME WITHOUT TIME ZONE) pour définir le temps réel.

Example 1. Utilisation d’une variable LOCALTIME

SELECT LOCALTIME(2) FROM RDB$DATABASE;
-- le résultat sera (par exemple) 23:35:33.1200

Voir aussi :

[fblangref-contextvars-current-time],[fblangref-contextvars-current-timestamp],[fblangref-contextvars-current-date].

`LOCALTIMESTAMP`

Disponible en

DSQL, PSQL, ESQL

Syntaxe

LOCALTIMESTAMP [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Contexte Paramètres de la variable LOCALTIMESTAMP
Paramètre	Description
precision	Précision. La valeur par défaut est 3. Non supporté dans ESQL.

type de résultat de retour

TIMESTAMP WITHOUT TIME ZONE

La variable LOCALTIMESTAMP renvoie la date et l’heure actuelles dans le fuseau horaire de la session, sans information sur le fuseau horaire. La précision détermine le nombre de décimales à considérer dans les fractions de seconde. La précision par défaut est de 3.

Note

Dans un bloc de code PSQL (procédure, trigger, bloc exécutable), la valeur de LOCALTIMESTAMP ne change pas au cours de son exécution. Lors de l’appel d’un code imbriqué, la valeur ne changera pas non plus et sera égale à la valeur du code de niveau supérieur. Utilisez CAST('NOW' AS TIMESTAMP WITHOUT TIME ZONE) pour définir le temps réel.

Example 1. Utilisation d’une variable LOCALTIMESTAMP

SELECT LOCALTIMESTAMP(2) FROM RDB$DATABASE;
-- le résultat sera (par exemple) 02.03.2014 23:35:33.1200

Voir aussi :

[fblangref-contextvars-current-timestamp],[fblangref-contextvars-current-time],[fblangref-contextvars-current-date].

`NEW`

Disponible en

PSQL

Syntaxe

NEW

La variable contextuelle NEW est uniquement disponible dans le code des triggers de table. La valeur de NEW contient les nouvelles valeurs des champs de données qui sont apparues dans la base de données pendant l’opération de mise à jour ou d’insertion.

Dans les déclencheurs AFTER, la variable est en lecture seule.

Note

Pour les triggers de table déclenchés par plusieurs types d’événements, la variable NEW est toujours disponible. Cependant, dans le cas où le trigger est déclenché par une opération de suppression, une nouvelle version des données n’a pas de sens pour lui. Dans cette situation, la lecture de la variable NEW retournera toujours NULL.

Important

La tentative d’écrire dans la variable NEW dans le déclencheur AFTER provoquera une exception dans le code.

Example 1. Utilisation d’une variable NEW

...
  IF (NEW.SERIAL_NUM IS NULL) THEN
    NEW.SERIAL_NUM = GEN_ID (GEN_SERIALS, 1);
...

Voir aussi :

[fblangref-contextvars-old].

`OLD`

Disponible en

PSQL

Syntaxe

OLD

La variable contextuelle OLD est uniquement disponible pour le code du déclencheur. La valeur contenue dans OLD stocke les valeurs passées des champs qui étaient dans la base de données avant l’opération de modification ou de suppression.

La variable OLD est en lecture seule.

Note

Pour les déclencheurs de table déclenchés par plusieurs types d’événements, les valeurs de la variable OLD sont toujours possibles. Cependant, pour les déclencheurs déclenchés par l’insertion d’un enregistrement, la valeur de cette variable n’a pas de sens, donc dans cette situation la lecture de OLD retournera NULL et essayer d’y écrire provoquera une exception dans le code.

Example 1. Utilisation d’une variable OLD

...
  IF (NEW.QUANTITY IS DISTINCT FROM OLD.QUANTITY) THEN
    DELTA = NEW.QUANTITY - OLD.QUANTITY;
...

Voir aussi :

[fblangref-contextvars-new].

`RESETTING`

Disponible en

PSQL

Syntaxe

RESETTING

type de résultat de retour

BOOLEAN

La variable contextuelle RESETTING n’est disponible que pour les déclencheurs d’événements ON CONNECT et ON DISCONNECT et peut être utilisée partout où un prédicat logique peut être utilisé. La variable système RESETTING permet de détecter quand un déclencheur de base de données est déclenché par une réinitialisation de session, par exemple avec l’instruction ALTER SESSION RESET. Sa valeur est TRUE si une réinitialisation de session est effectuée, et FALSE sinon.

Example 1. Utilisation d’une variable RESETTING

...
IF (RESETTING) THEN
BEGIN
  -- la session est réinitialisée
END
...

Voir aussi :

ALTER SESSION RESET.

`ROW_COUNT`

Disponible en

PSQL

Syntaxe

ROW_COUNT

type de résultat de retour

BIGINT

La variable contextuelle ROW_COUNT contient le nombre de lignes affectées par la dernière instruction DML.(INSERT, UPDATE, DELETE, SELECT ou FETCH) dans le déclencheur, la procédure stockée ou le bloc exécutable en cours.

Comportement avec SELECT et FETCH :

Après avoir exécuté une requête singleton SELECT (une requête qui ne peut retourner plus d’une ligne de données), ROW_COUNT est 1 si une chaîne de données a été récupérée et 0 sinon ;
Dans la boucle FOR SELECT, la variable ROW_COUNT est incrémentée à chaque itération (en commençant par 0 comme première valeur) ;
Après la sélection (FETCH) du curseur, ROW_COUNT vaut 1 si une chaîne de données a été récupérée et 0 sinon. La sélection de plusieurs enregistrements à partir du même curseur n’incrémente pas ROW_COUNT après 1.

Important

La variable ROW_COUNT ne peut pas être utilisée pour déterminer le nombre de lignes affectées par les instructions EXECUTE STATEMENT ou EXECUTE PROCEDURE. Pour l’instruction MERGE, la variable ROW_COUNT contiendra 0 ou 1, même si plus d’enregistrements ont été affectés.

Warning

N’utilisez pas la variable ROW_COUNT dans les instructions DML. En effet, cette variable remet sa valeur à 0 avant l’exécution de toute instruction DML, et vous risquez donc de ne pas obtenir ce que vous attendez.

...
UPDATE t2 SET
    evt='upd',
    old_id = old.id, old_x = old.x,
    new_id = new.id, new_x = new.x
WHERE new_id = old.id;

INSERT INTO t2log(evt, affected_rows) VALUES('upd', ROW_COUNT);
...

Dans l’exemple ci-dessus, la colonne affected_rows sera écrite avec des valeurs nulles, même si l’instruction UPDATE a été affectée. Pour corriger cette erreur, la valeur de la variable de contexte ROW_COUNT doit être enregistrée dans une variable locale du module PSQL et utilisée dans une instruction DML avec cette variable locale.

...
DECLARE rc INT;
...
UPDATE t2 SET
    evt='upd',
    old_id = old.id, old_x = old.x,
    new_id = new.id, new_x = new.x
WHERE new_id = old.id;

rc = ROW_COUNT;
INSERT INTO t2log(evt, affected_rows) VALUES('upd', rc);
...

Example 1. Utilisation d’une variable ROW_COUNT

...
UPDATE Figures SET Number = 0 WHERE id = :id;
IF (row_count = 0) THEN
  INSERT INTO Figures (id, Number)
  VALUES (:id, 0);
...

`SQLCODE`

Disponible en

PSQL

Syntaxe

SQLCODE

type de résultat de retour

INTEGER

Dans les blocs de gestion d’erreur WHEN … DO la variable contextuelle SQLCODE contient le code d’erreur SQL actuel.Avant Firebird 2.0, la valeur de SQLCODE ne pouvait être récupérée que dans les blocs d’erreur WHEN SQLCODE et WHEN ANY.Il peut maintenant être non nul dans les blocs WHEN GDSCODE et WHEN EXCEPTION à condition que l’erreur qui a déclenché le bloc corresponde au code d’erreur SQL.En dehors des gestionnaires d’erreurs, SQLCODE est toujours 0 et en dehors de PSQL, il n’existe pas du tout.

Example 1. Utilisation d’une variable SQLCODE

...
WHEN ANY DO
BEGIN
  IF (SQLCODE <> 0) THEN
    MSG = 'Erreur SQL détectée !';
  ELSE
    MSG = 'Il n''y a pas d''erreur !';
  EXCEPTION EX_CUSTOM MSG;
END
...

Voir aussi :

[fblangref-contextvars-gdscode], [fblangref-contextvars-sqlstate].

`SQLSTATE`

Disponible en

PSQL

Syntaxe

SQLSTATE

type de résultat de retour

CHAR(5)

Dans les blocs de gestion d’erreur WHEN … DO variable de contexte SQLSTATE variable contient 5 caractères du code d’état compatible SQL-2003 — passé par la déclaration causant l’erreur.En dehors des gestionnaires d’erreurs, SQLSTATE est toujours '00000' et en dehors de PSQL, il n’existe pas du tout.

Note

SQLSTATE est destiné à remplacer SQLCODE. Ce dernier est maintenant obsolète et sera supprimé dans les futures versions de Firebird ;
Tout code SQLSTATE se compose de deux caractères de classe et de trois caractères de sous-classe. Les classes 00 (exécution réussie), 01 (avertissement) et 02 (pas de données) représentent les conditions d’achèvement. Chaque code d’état en dehors de ces classes est une exception. Comme les classes 00, 01 et 02 ne provoquent pas d’erreur, elles ne seront jamais détectées dans la variable SQLSTATE.

Example 1. Utilisation d’une variable SQLSTATE

WHEN ANY DO
BEGIN
  MSG = CASE SQLSTATE
          WHEN '22003' THEN
            'Le nombre est hors de portée !'
          WHEN '22012' THEN
            'Division par zéro !'
          WHEN '23000' THEN
            'Violation du control d''intégrité !'
          ELSE 'Il n''y a pas d''erreurs ! SQLSTATE = ' || SQLSTATE;
        END;
  EXCEPTION EX_CUSTOM MSG;
END

Voir aussi :

[fblangref-contextvars-gdscode], [fblangref-contextvars-sqlcode], Codes d’erreur SQLSTATE.

`UPDATING`

Disponible en

PSQL

Syntaxe

UPDATING

type de résultat de retour

BOOLEAN

La variable contextuelle UPDATING n’est disponible que dans le code des triggers de table. Elle est utilisée dans les triggers pour plusieurs types d’événements et indique que le trigger a été déclenché lorsque l’opération UPDATE a été effectuée.

Example 1. Utilisation d’une variable UPDATING

...
IF (INSERTING OR UPDATING) THEN
BEGIN
  IF (NEW.SERIAL_NUM IS NULL) THEN
    NEW.SERIAL_NUM = GEN_ID (GEN_SERIALS, 1);
END
...

Voir aussi :

[fblangref-contextvars-inserting], [fblangref-contextvars-deleting].

`CURRENT_DATE`

Disponible en

DSQL, PSQL, ESQL

Syntaxe

CURRENT_DATE

type de résultat de retour

DATE

La variable CURRENT_DATE renvoie la date actuelle du serveur.

Note

Dans un module PSQL (procédure, fonction, trigger ou bloc exécutable), la valeur de CURRENT_DATE restera constante à chaque lecture.constante à chaque lecture. Si plusieurs modules s’appellent ou s’exécutent mutuellement, la valeur restera constante pour la durée du module externe lui-même.Si vous avez besoin d’une valeur progressive dans PSQL (par exemple, pour mesurer des intervalles de temps), utilisez la conversion littérale 'TODAY' en date ou en horodatage.

Example 1. Utilisation d’une variable CURRENT_DATE

Select current_date from rdb$database

Voir aussi :

[fblangref-contextvars-current-timestamp], [fblangref-contextvars-current-time].

`USER`

Disponible en

DSQL, PSQL

Syntaxe

USER

type de résultat de retour

VARCHAR(63)

La variable USER contient le nom de l’utilisateur de la base de données actuellement connecté.

Example 1. Utilisation d’une variable USER

NEW.ADDED_BY = USER;

Voir aussi :

[fblangref-contextvars-current-user], [fblangref-contextvars-current-role].

`CURRENT_ROLE`

Disponible en

DSQL, PSQL

Syntaxe

CURRENT_ROLE

type de résultat de retour

VARCHAR(63)

Une variable de contexte CURRENT_ROLE contenant le nom du rôle qui a été spécifié lors de la connexion à la base de données, ou le rôle défini avec l’opérateur SET ROLE.Dans le cas où une connexion s’est produite sans spécifier de rôle, et que le rôle n’a pas été spécifié plus tard en utilisant l’opérateur SET ROLE, la variable prend la valeur NONE.

CURRENT_ROLE représente toujours un rôle valide ou NONE. Si un utilisateur se connecte avec un rôle inexistant,le noyau le réinitialise silencieusement à NONE sans retourner d’erreur.

Note

La variable de contexte CURRENT_ROLE ne contient que le nom du rôle explicitement défini (à l’ouverture de session ou avec SET ROLE), les rôles implicitement définis (émis par l’instruction GRANT utilisant le mot-clé DEFAULT) ne seront pas inclus. Pour savoir si l’utilisateur actuel utilise un rôle implicitement défini, utilisez la fonction du système RDB$ROLE_IN_USE().

Example 1. Utilisation d’une variable CURRENT_ROLE

SELECT CURRENT_ROLE FROM RDB$DATABASE

Note	La même valeur sera également disponible en tant que résultat de la requête : `SELECT RDB$GET_CONTEXT ('SYSTEM', 'CURRENT_ROLE') FROM RDB$DATABASE;`

Voir aussi :

SET ROLE,RDB$GET_CONTEXT(),RDB$ROLE_IN_USE().

`CURRENT_TIME`

Disponible en

DSQL, PSQL, ESQL

Syntaxe

CURRENT_TIME [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Contexte Paramètres de la variable `CURRENT_TIME`
Paramètre	Description
precision	Précision. La valeur par défaut est 0. Non supporté dans ESQL.

type de résultat de retour

TIME WITH TIME ZONE

La variable CURRENT_TIME renvoie l’heure actuelle dans le fuseau horaire de la session, y compris les informations sur le fuseau horaire. La précision détermine le nombre de décimales à considérer dans les fractions de seconde. La précision par défaut est 0.

Note

Dans un bloc de code PSQL (procédure, trigger, bloc exécutable), la valeur de CURRENT_TIME ne change pas au cours de son exécution. Lors de l’appel de code imbriqué, la valeur ne changera pas non plus et sera égale à la valeur du code de niveau supérieur. Utilisez CAST('NOW' AS TIME) pour définir le temps réel.

Example 1. Utilisation d’une variable CURRENT_TIME

SELECT CURRENT_TIME(2) FROM RDB$DATABASE;
-- le résultat sera (par exemple) 23:35:33.1200 Europe/Moscow

Voir aussi :

[fblangref-contextvars-current-timestamp], [fblangref-contextvars-current-date].

`CURRENT_TIMESTAMP`

Disponible en

DSQL, PSQL, ESQL

Syntaxe

CURRENT_TIMESTAMP [(<precision>)]

<precision> ::= 0 | 1 | 2 | 3

Table 1. Contexte Paramètres de la variable CURRENT_TIMESTAMP
Paramètre	Description
precision	Précision. La valeur par défaut est 3. Non supporté dans ESQL.

type de résultat de retour

TIMESTAMP WITH TIME ZONE

La variable CURRENT_TIMESTAMP renvoie la date et l’heure actuelles dans le fuseau horaire de la session, y compris les informations sur le fuseau horaire. La précision détermine le nombre de décimales en fractions de seconde à prendre en compte. La précision par défaut est de 3.

Note

Dans un bloc de code PSQL (procédure, trigger, bloc exécutable), la valeur de CURRENT_TIMESTAMP ne change pas au cours de son exécution. Lors de l’appel d’un code imbriqué, la valeur ne change pas non plus et est égale à la valeur du code de niveau supérieur. Utilisez CAST('NOW' AS TIMESTAMP) pour définir le temps réel.

Example 1. Utilisation d’une variable CURRENT_TIMESTAMP

SELECT CURRENT_TIMESTAMP(2) FROM RDB$DATABASE;
-- le résultat sera (par exemple) 02.03.2014 23:35:33.1200 Europe/Moscow

Voir aussi :

[fblangref-contextvars-current-time], [fblangref-contextvars-current-date].

`CURRENT_TRANSACTION`

Disponible en

DSQL, PSQL

Syntaxe

CURRENT_TRANSACTION

type de résultat de retour

BIGINT

La variable CURRENT_TRANSACTION contient un numéro unique pour la transaction en cours.

La valeur de CURRENT_TRANSACTION est ``stockée dans la page d’en-tête de la base de données et remise à 0 lorsque la base est restaurée (ou créée). Il est incrémenté lorsqu’une nouvelle transaction est lancée.

Example 1. Utilisation d’une variable CURRENT_TRANSACTION

SELECT CURRENT_TRANSACTION FROM RDB$DATABASE;

NEW.TRANS_ID = CURRENT_TRANSACTION;

Voir aussi :

[fblangref-contextvars-current-connection], RDB$GET_CONTEXT().

`CURRENT_USER`

Disponible en

DSQL, PSQL

Syntaxe

CURRENT_USER

type de résultat de retour

VARCHAR(63)

La variable CURRENT_USER contient le nom de l’utilisateur de la base de données actuellement connecté.

Example 1. Utilisation d’une variable CURRENT_USER

NEW.ADDED_BY = CURRENT_USER;

Voir aussi :

[fblangref-contextvars-user], [fblangref-contextvars-current-role].

`DELETING`

Disponible en

PSQL

Syntaxe

DELETING

type de résultat de retour

BOOLEAN

La variable contextuelle DELETING est uniquement disponible dans le code des triggers de table. Elle est utilisée dans les triggers pour plusieurs types d’événements et indique que le trigger a été déclenché lorsque l’opération DELETE est exécutée.

Example 1. Utilisation d’une variable DELETING

...
IF (DELETING) THEN
BEGIN
  INSERT INTO REMOVED_CARS (
    ID, MAKE, MODEL, REMOVED)
  VALUES (
    OLD.ID, OLD.MAKE, OLD.MODEL, CURRENT_TIMESTAMP);
END
...

Voir aussi :

[fblangref-contextvars-inserting], [fblangref-contextvars-updating].

`GDSCODE`

Disponible en

PSQL

Syntaxe

GDSCODE

type de résultat de retour

INTEGER

Dans le bloc de gestion des erreurs WHEN … DO la variable contextuelle GDSCODE contient une représentation numérique du code d’erreur actuel de Firebird.Avant Firebird 2.0, GDSCODE ne pouvait être récupéré qu’en utilisant la construction WHEN GDSCODE.Maintenant, cette variable contextuelle peut aussi être utilisée dans les blocs WHEN ANY, WHEN SQLCODE et WHEN EXCEPTION, tant que le code d’erreur correspond au code d’erreur de Firebird.En dehors du gestionnaire d’erreur, GDSCODE est toujours 0.En dehors de PSQL, GDSCODE n’existe pas du tout.

Example 1. Utilisation d’une variable GDSCODE

...
WHEN GDSCODE GRANT_OBJ_NOTFOUND,
     GDSCODE GRANT_FLD_NOTFOUND,
     GDSCODE GRANT_NOPRIV,
     GDSCODE GRANT_NOPRIV_ON_BASE
DO
BEGIN
  EXECUTE PROCEDURE LOG_GRANT_ERROR(GDSCODE);
  EXIT;
END
...

Note	Attention : après, `WHEN GDSCODE` vous devez utiliser des noms symboliques — comme `grant_obj_notfound` etc. Mais la variable de contexte `GDSCODE` est un entier. Vous devez utiliser une valeur numérique pour la comparer à une erreur particulière, comme `335544551` pour `grant_obj_notfound`.

Voir aussi :

[fblangref-contextvars-sqlcode], [fblangref-contextvars-sqlstate].