FirebirdSQL logo
 Responsables du traitement des données(DML)fonctions scalaires 

EXCEPTION

Destination

Déclencher une exception personnalisée ou rappeler une exception.

Disponible en

PSQL

Syntaxe
EXCEPTION [
    exception_name
    [ custom_message | USING (<value_list>)]
  ]

<value_list> ::= <val> [, <val> ...]
Table 1. Paramètres de l’instruction EXCEPTION
Paramètre Description

exception_name

Le nom de l’exception.

custom_message

Texte du message alternatif donné lorsqu’une exception se produit. La longueur maximale d’un message texte est de 1021 octets.

val

Les valeurs par lesquelles les créneaux sont remplacés dans le texte du message d’exception.

L’Instruction EXCEPTION lance une exception personnalisée avec un nom spécifié. Lorsque vous lancez une exception, vous pouvez également spécifier un texte de message alternatif pour remplacer le texte de message spécifié lors de la création de l’exception.

Le texte du message d’exception peut contenir des emplacements de paramètres qui sont remplis lorsque l’exception est levée.La clause USING est utilisée pour passer des valeurs de paramètres dans l’exception.Les paramètres sont évalués de gauche à droite.Chaque paramètre est transmis à l’instruction qui lève l’exception sous la forme `N-y', N commençant par 1 :

  • Si le paramètre N n’est pas passé, son emplacement n’est pas remplacé ;

  • Si NULL est passé, le slot sera remplacé par la chaîne “*** null ***” ;

  • Si le nombre de paramètres passés est supérieur au nombre de paramètres contenus dans le message d’exception, les paramètres supplémentaires seront ignorés ;

  • Le nombre maximum de paramètres est de 9 ;

  • La longueur totale du message, y compris les valeurs des paramètres, est limitée à 1053 octets.

Note

Le vecteur d’état est généré en utilisant une combinaison de codes isc_except, <numéro d’exception>, isc_formatted_exception, <message d’exception formaté>, <paramètres d’exception>.

Comme un nouveau code d’erreur (isc_formatted_exception) est utilisé, le client doit être en version 3.0 ou au moins utiliser firebird.msg à partir de la version 3.0 afin de convertir correctement le vecteur d’état en chaîne de caractères.
Warning

Si le texte du message contient un numéro d’emplacement de paramètre supérieur à 9, le deuxième caractère et les suivants seront considérés comme des littéraux. Par exemple, @10 sera considéré comme @1 suivi du littéral ‘`0`’.

 
CREATE EXCEPTION ex1
'something wrong in @1 @2 @3 @4 @5 @6 @7 @8 @9 @10 @11';

EXECUTE BLOCK AS
BEGIN
  EXCEPTION ex1 USING ('a','b','c','d','e','f','g','h','i');
END^
Statement failed, SQLSTATE = HY000
exception 1
-EX1
-something wrong in a b c d e f g h i a0 a1

L’exception peut être traitée par l’Instruction WHEN …​ DO.Si une exception utilisateur n’a pas été traitée dans un déclencheur ou une procédure stockée, les actions effectuées dans cette procédure stockée (déclencheur) sont annulées et le programme appelant reçoit le texte spécifié lors de la création de l’exception ou un autre texte de message.

Dans le bloc de traitement des exceptions (et uniquement dans celui-ci), vous pouvez rappeler une exception ou une erreur capturée en appelant l’instruction EXCEPTION sans paramètres. En dehors du bloc d’exception, un tel appel n’a aucun effet.

Note

Les exceptions des utilisateurs sont stockées dans la table du système RDB$EXCEPTIONS.

Exemples EXCEPTION

Example 1. Appeler une exception
CREATE OR ALTER PROCEDURE SHIP_ORDER (
    PO_NUM CHAR(8))
AS
DECLARE VARIABLE ord_stat  CHAR(7);
DECLARE VARIABLE hold_stat CHAR(1);
DECLARE VARIABLE cust_no   INTEGER;
DECLARE VARIABLE any_po    CHAR(8);
BEGIN
  SELECT
      s.order_status,
      c.on_hold,
      c.cust_no
  FROM
      sales s, customer c
  WHERE
      po_number = :po_num AND
      s.cust_no = c.cust_no
  INTO :ord_stat,
       :hold_stat,
       :cust_no;

  /* Cette commande a déjà été envoyée pour être livrée. */
  IF (ord_stat = 'shipped') THEN
    EXCEPTION order_already_shipped;
  /* Autres Instructions */
END
Example 2. Appeler une exception et remplacer le message original par un message alternatif
CREATE OR ALTER PROCEDURE SHIP_ORDER (
    PO_NUM CHAR(8))
AS
DECLARE VARIABLE ord_stat  CHAR(7);
DECLARE VARIABLE hold_stat CHAR(1);
DECLARE VARIABLE cust_no   INTEGER;
DECLARE VARIABLE any_po    CHAR(8);
BEGIN
  SELECT
      s.order_status,
      c.on_hold,
      c.cust_no
  FROM
      sales s, customer c
  WHERE
      po_number = :po_num AND
      s.cust_no = c.cust_no
  INTO :ord_stat,
       :hold_stat,
       :cust_no;

  /* Cette commande a déjà été envoyée pour être livrée. */
  IF (ord_stat = 'shipped') THEN
    EXCEPTION order_already_shipped 'Order status is "' || ord_stat || '"';
  /* Autres Instructions */
END
Example 3. Utilisation d’une exception paramétrée
CREATE EXCEPTION EX_BAD_SP_NAME
  'Name of procedures must start with ''@1'' : ''@2''';
...
CREATE TRIGGER TRG_SP_CREATE BEFORE CREATE PROCEDURE
AS
  DECLARE SP_NAME VARCHAR(255);
BEGIN
  SP_NAME = RDB$GET_CONTEXT('DDL_TRIGGER', 'OBJECT_NAME');
  IF (SP_NAME NOT STARTING 'SP_') THEN
    EXCEPTION EX_BAD_SP_NAME USING ('SP_', SP_NAME);
END^
Voir aussi :

CREATE EXCEPTION, WHEN …​ DO.

WHEN …​ DO

Destination

Traitement des erreurs.

Disponible en

PSQL

Syntaxe
WHEN {<error> [, <error> ...] | ANY}
DO <compound_statement>

<error> ::= {
    EXCEPTION exception_name
  | SQLCODE number
  | GDSCODE errcode
  | SQLSTATE 'sqlstate_code'
}
Table 1. Paramètres de l’instruction WHEN …​ DO
Paramètre Description

exception_name

Le nom de l’exception.

number

Code d’erreur SQLCODE.

errcode

Le nom symbolique de l’erreur est GDSCODE.

sqlstate_code

Code d’erreur SQLSTATE.

compound_statement

Instruction ou bloc d’Instructions.

Le WHEN …​ DO est utilisé pour gérer les situations d’erreur et les exceptions de l’utilisateur.L’Instruction intercepte toutes les erreurs et les exceptions utilisateur énumérées après le mot-clé WHEN.Si le mot clé ANY est spécifié après le mot clé WHEN, l’Instruction intercepte toutes les erreurs et les exceptions utilisateur, même si elles ont déjà été traitées dans le bloc WHEN ci-dessus.

Le WHEN …​ DO doit se trouver à la toute fin du bloc d’instructions, avant l’instruction END.

Le mot-clé DO est suivi d’une instruction composée où une erreur ou une exception peut être traitée.Une instruction composée est une instruction ou un bloc d’instructions entouré de crochets Instructions BEGIN et END.Les variables contextuelles sont disponibles dans cette déclaration GDSCODE, SQLCODE, SQLSTATE.Pour récupérer le nom d’une exception utilisateur active ou le texte d’un message d’erreur interprété, vous pouvez utiliser la fonction systèmeRDB$ERROR.Un Instruction de rappel en cas d’erreur ou de situation exceptionnelle est également disponible dans ce bloc.EXCEPTION (aucun paramètre).

Important

Après la clause WHEN GDSCODE vous devez utiliser des noms symboliques — tels que grant_obj_notfound etc. Mais dans une instruction composée, après le mot clé DO une variable contextuelle GDSCODE est disponible qui contient un entier. Pour la comparer à une erreur particulière vous devez utiliser une valeur numérique, telle que 335544551 pour grant_obj_notfound.

Le WHEN …​ IF l’instruction est exécutée (même si aucune action n’y a été effectuée), une erreur ou une exception utilisateur n’interrompt pas ou n’annule pas l’action du déclencheur ou de la procédure stockée où cette instruction a été émise, l’opération se poursuit comme si aucune situation exceptionnelle ne s’était produite.Toutefois, dans ce cas, l’instruction DML (SELECT, INSERT, UPDATE, DELETE, MERGE) qui a provoqué l’erreur sera annulée et toutes les instructions suivantes du même bloc d’instructions ne seront pas exécutées.

Important

Si l’erreur n’est pas causée par l’une des instructions DML (SELECT, INSERT, UPDATE, DELETE, MERGE), non seulement l’instruction qui a causé l’erreur sera annulée, mais tout le bloc d’instructions. De plus, les actions de l’instruction WHEN …​ Ceci s’applique également à l’instruction de procédure stockée `EXECUTE PROCEDURE. Pour plus d’informations, voir CORE-4483.