Rechercher dans le manuel MySQL

13.6.7.2 DECLARE ... HANDLER Syntax

Table des matières
  1. DECLARE handler_action HANDLER
  2.     FOR condition_value [, condition_value] ...
  3.     statement
  4.  
  5. handler_action: {
  6.     CONTINUE
  7.   | EXIT
  8.   | UNDO
  9. }
  10.  
  11. condition_value: {
  12.     mysql_error_code
  13.   | SQLSTATE [VALUE] sqlstate_value
  14.   | condition_name
  15.   | SQLWARNING
  16.   | NOT FOUND
  17.   | SQLEXCEPTION
  18. }

The DECLARE ... HANDLER statement specifies a handler that deals with one or more conditions. If one of these conditions occurs, the specified statement executes. statement can be a simple statement such as SET var_name = value, or a compound statement written using BEGIN and END (see Section 13.6.1, “BEGIN ... END Compound-Statement Syntax”).

Handler declarations must appear after variable or condition declarations.

The handler_action value indicates what action the handler takes after execution of the handler statement:

  • CONTINUE: Execution of the current program continues.

  • EXIT: Execution terminates for the BEGIN ... END compound statement in which the handler is declared. This is true even if the condition occurs in an inner block.

  • UNDO: Not supported.

The condition_value for DECLARE ... HANDLER indicates the specific condition or class of conditions that activates the handler. It can take the following forms:

  • mysql_error_code: An integer literal indicating a MySQL error code, such as 1051 to specify “unknown table”:

    1. DECLARE CONTINUE HANDLER FOR 1051
    2.   BEGIN
    3.     -- body of handler
    4.   END;

    Do not use MySQL error code 0 because that indicates success rather than an error condition. For a list of MySQL error codes, see Section B.3.1, “Server Error Message Reference”.

  • SQLSTATE [VALUE] sqlstate_value: A 5-character string literal indicating an SQLSTATE value, such as '42S01' to specify “unknown table”:

    1. DECLARE CONTINUE HANDLER FOR SQLSTATE '42S02'
    2.   BEGIN
    3.     -- body of handler
    4.   END;

    Do not use SQLSTATE values that begin with '00' because those indicate success rather than an error condition. For a list of SQLSTATE values, see Section B.3.1, “Server Error Message Reference”.

  • condition_name: A condition name previously specified with DECLARE ... CONDITION. A condition name can be associated with a MySQL error code or SQLSTATE value. See Section 13.6.7.1, “DECLARE ... CONDITION Syntax”.

  • SQLWARNING: Shorthand for the class of SQLSTATE values that begin with '01'.

    1. DECLARE CONTINUE HANDLER FOR SQLWARNING
    2.   BEGIN
    3.     -- body of handler
    4.   END;

  • NOT FOUND: Shorthand for the class of SQLSTATE values that begin with '02'. This is relevant within the context of cursors and is used to control what happens when a cursor reaches the end of a data set. If no more rows are available, a No Data condition occurs with SQLSTATE value '02000'. To detect this condition, you can set up a handler for it or for a NOT FOUND condition.

    1. DECLARE CONTINUE HANDLER FOR NOT FOUND
    2.   BEGIN
    3.     -- body of handler
    4.   END;

    For another example, see Section 13.6.6, “Cursors”. The NOT FOUND condition also occurs for SELECT ... INTO var_list statements that retrieve no rows.

  • SQLEXCEPTION: Shorthand for the class of SQLSTATE values that do not begin with '00', '01', or '02'.

    1. DECLARE CONTINUE HANDLER FOR SQLEXCEPTION
    2.   BEGIN
    3.     -- body of handler
    4.   END;

For information about how the server chooses handlers when a condition occurs, see Section 13.6.7.6, “Scope Rules for Handlers”.

If a condition occurs for which no handler has been declared, the action taken depends on the condition class:

  • For SQLEXCEPTION conditions, the stored program terminates at the statement that raised the condition, as if there were an EXIT handler. If the program was called by another stored program, the calling program handles the condition using the handler selection rules applied to its own handlers.

  • For SQLWARNING conditions, the program continues executing, as if there were a CONTINUE handler.

  • For NOT FOUND conditions, if the condition was raised normally, the action is CONTINUE. If it was raised by SIGNAL or RESIGNAL, the action is EXIT.

The following example uses a handler for SQLSTATE '23000', which occurs for a duplicate-key error:

  1. mysql> CREATE TABLE test.t (s1 INT, PRIMARY KEY (s1));
  2. Query OK, 0 rows affected (0.00 sec)
  3.  
  4. mysql> delimiter //
  5.  
  6. mysql> CREATE PROCEDURE handlerdemo ()
  7.        BEGIN
  8.          DECLARE CONTINUE HANDLER FOR SQLSTATE '23000' SET @x2 = 1;
  9.          SET @x = 1;
  10.          INSERT INTO test.t VALUES (1);
  11.          SET @x = 2;
  12.          INSERT INTO test.t VALUES (1);
  13.          SET @x = 3;
  14.        END;
  15.        //
  16. Query OK, 0 rows affected (0.00 sec)
  17.  
  18. mysql> CALL handlerdemo()//
  19. Query OK, 0 rows affected (0.00 sec)
  20.  
  21. mysql> SELECT @x//
  22.     +------+
  23.     | @x   |
  24.     +------+
  25.     | 3    |
  26.     +------+
  27.     1 row in set (0.00 sec)

Notice that @x is 3 after the procedure executes, which shows that execution continued to the end of the procedure after the error occurred. If the DECLARE ... HANDLER statement had not been present, MySQL would have taken the default action (EXIT) after the second INSERT failed due to the PRIMARY KEY constraint, and SELECT @x would have returned 2.

To ignore a condition, declare a CONTINUE handler for it and associate it with an empty block. For example:

  1. DECLARE CONTINUE HANDLER FOR SQLWARNING BEGIN END;

The scope of a block label does not include the code for handlers declared within the block. Therefore, the statement associated with a handler cannot use ITERATE or LEAVE to refer to labels for blocks that enclose the handler declaration. Consider the following example, where the REPEAT block has a label of retry:

  1. CREATE PROCEDURE p ()
  2. BEGIN
  3.   DECLARE i INT DEFAULT 3;
  4.   retry:
  5.     REPEAT
  6.       BEGIN
  7.         DECLARE CONTINUE HANDLER FOR SQLWARNING
  8.           BEGIN
  9.             ITERATE retry;    # illegal
  10.           END;
  11.         IF i < 0 THEN
  12.           LEAVE retry;        # legal
  13.         END IF;
  14.         SET i = i - 1;
  15.       END;
  16.     UNTIL FALSE END REPEAT;
  17. END;

The retry label is in scope for the IF statement within the block. It is not in scope for the CONTINUE handler, so the reference there is invalid and results in an error: 

ERROR 1308 (42000): LEAVE with no matching label: retry

To avoid references to outer labels in handlers, use one of these strategies:


Rechercher dans le manuel MySQL

Traduction non disponible

Le manuel MySQL n'est pas encore traduit en français sur l'infobrol. Seule la version anglaise est disponible pour l'instant.

Document créé le 26/06/2006, dernière modification le 26/10/2018
Source du document imprimé : https://www.gaudry.be/mysql-rf-declare-handler.html

L'infobrol est un site personnel dont le contenu n'engage que moi. Le texte est mis à disposition sous licence CreativeCommons(BY-NC-SA). Plus d'info sur les conditions d'utilisation et sur l'auteur.

Références

  1. Consulter le document html Langue du document :en Manuel MySQL : https://dev.mysql.com/

Ces références et liens indiquent des documents consultés lors de la rédaction de cette page, ou qui peuvent apporter un complément d'information, mais les auteurs de ces sources ne peuvent être tenus responsables du contenu de cette page.
L'auteur de ce site est seul responsable de la manière dont sont présentés ici les différents concepts, et des libertés qui sont prises avec les ouvrages de référence. N'oubliez pas que vous devez croiser les informations de sources multiples afin de diminuer les risques d'erreurs.

Table des matières Haut