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

Exceptions personnalisées

Les exceptions personnalisées peuvent être déclarées comme des objets persistants dans la base de données et peuvent être appelées à partir du code PSQL pour signaler une erreur lorsque certaines règles de gestion sont violées.Le texte d’une exception personnalisée est limité à 1021 octets.Voir CREATE EXCEPTION pour plus de détails.

Dans le code PSQL, les exceptions sont traitées par l’Instruction WHEN.Si l’exception est gérée dans votre code, vous fournissez un correctif ou une solution de contournement et permettez à l’exécution de se poursuivre, aucun message d’exception n’est renvoyé au client.

L’exception entraîne l’arrêt de l’exécution dans le bloc.Au lieu de passer l’exécution à l’instruction finale END, la procédure remonte maintenant les niveaux dans les blocs imbriqués, en commençant par le bloc où l’erreur a été levée, et va dans les blocs externes pour trouver le code du gestionnaire qui connait l’exception.Il cherche la première instruction WHEN qui peut gérer cette erreur.

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.