Spec-Zone .ru
спецификации, руководства, описания, API

13.6.7.5. SIGNAL Синтаксис

SIGNAL condition_value    [SET signal_information_item    [, signal_information_item] ...]condition_value:    SQLSTATE [VALUE] sqlstate_value  | condition_namesignal_information_item:    condition_information_item_name = simple_value_specificationcondition_information_item_name:    CLASS_ORIGIN  | SUBCLASS_ORIGIN  | MESSAGE_TEXT  | MYSQL_ERRNO  | CONSTRAINT_CATALOG  | CONSTRAINT_SCHEMA  | CONSTRAINT_NAME  | CATALOG_NAME  | SCHEMA_NAME  | TABLE_NAME  | COLUMN_NAME  | CURSOR_NAMEcondition_name, simple_value_specification:    (see following discussion)

SIGNAL способ "возвратить" ошибку. SIGNAL предоставляет информацию об ошибке обработчику, внешней части приложения, или клиенту. Кроме того, это обеспечивает управление характеристиками ошибки (код ошибки, SQLSTATE значение, сообщение). Без SIGNAL, необходимо обратиться к обходным решениям, таким как преднамеренное обращение к несуществующей таблице, чтобы заставить подпрограмму возвращать ошибку.

Никакие специальные полномочия не обязаны выполняться SIGNAL оператор.

Чтобы получить информацию от области диагностики, используйте GET DIAGNOSTICS оператор (см. Раздел 13.6.7.3,"GET DIAGNOSTICS Синтаксис"). Для получения информации об области диагностики см. Раздел 13.6.7.7, "MySQL Diagnostics Area".

condition_value в a SIGNAL оператор указывает на ошибочное значение, которое будет возвращено. Это может быть SQLSTATE значение (5-символьный строковый литерал) или a condition_name это обращается к именованному условию, ранее определенному с помощью DECLARE ... CONDITION (см. Раздел 13.6.7.1,"DECLARE ... CONDITION Синтаксис").

SQLSTATE значение может указать на ошибки, предупреждения, или "не найденный." Первые два символа значения указывают на его ошибку class, как обсуждено в Разделе 13.6.7.5.1, "Единицы информации Условия Сигнала". Некоторый сигнал оценивает завершение оператора причины; см. Раздел 13.6.7.5.2, "Эффект Сигналов на Обработчиках, Курсорах, и Операторах".

SQLSTATE значение для a SIGNAL оператор не должен запуститься с '00' потому что такие значения указывают на успех и не допустимы для того, чтобы сигнализировать ошибку. Это - истина ли SQLSTATE значение определяется непосредственно в SIGNAL оператор или в именованном условии упоминается в операторе. Если значение недопустимо, a Bad SQLSTATE ошибка происходит.

Сигнализировать обобщение SQLSTATE значение, использовать '45000', что означает "необработанное определяемое пользователем исключение."

SIGNAL оператор дополнительно включает a SET пункт, который содержит многократные элементы сигнала в списке разделенных запятой значений condition_information_item_name = simple_value_specification присвоения.

Каждый condition_information_item_name может быть определен только однажды в SET пункт. Иначе, a Duplicate condition information item ошибка происходит.

Допустимый simple_value_specification указатели могут быть определены, используя хранимую процедуру или параметры функции, сохраненные локальные переменные программы, объявленные с DECLARE, определяемые пользователем переменные, системные переменные, или литералы. Символьный литерал может включать a _charset introducer.

Для получения информации о допустимом condition_information_item_name значения, см. Раздел 13.6.7.5.1, "Единицы информации Условия Сигнала".

Следующая процедура сигнализирует ошибку или предупреждение в зависимости от значения pval, его входной параметр:

CREATE PROCEDURE p (pval INT)BEGIN  DECLARE specialty CONDITION FOR SQLSTATE '45000';  IF pval = 0 THEN    SIGNAL SQLSTATE '01000';  ELSEIF pval = 1 THEN    SIGNAL SQLSTATE '45000'      SET MESSAGE_TEXT = 'An error occurred';  ELSEIF pval = 2 THEN    SIGNAL specialty      SET MESSAGE_TEXT = 'An error occurred';  ELSE    SIGNAL SQLSTATE '01000'      SET MESSAGE_TEXT = 'A warning occurred', MYSQL_ERRNO = 1000;    SIGNAL SQLSTATE '45000'      SET MESSAGE_TEXT = 'An error occurred', MYSQL_ERRNO = 1001;  END IF;END;

Если pval 0, p() сигнализирует предупреждение потому что SQLSTATE значения, которые начинаются '01' сигналы в предупреждении class. Предупреждение не завершает процедуру, и может быть замечено с SHOW WARNINGS после возвратов процедуры.

Если pval 1, p() сигнализирует ошибку и устанавливает MESSAGE_TEXT единица информации условия. Ошибка завершает процедуру, и текст возвращается с информацией об ошибке.

Если pval 2, та же самая ошибка сообщается, хотя SQLSTATE значение определяется, используя именованное условие в этом случае.

Если pval что-либо еще, p() первые сигналы предупреждение и наборы текст сообщения и единицы информации условия кода ошибки. Это предупреждение не завершает процедуру, таким образом, выполнение продолжается и p() тогда сигнализирует ошибку. Ошибка действительно завершает процедуру. Текст сообщения и код ошибки, установленный предупреждением, заменяются значениями, установленными ошибкой, которые возвращаются с информацией об ошибке.

SIGNAL обычно используется в пределах сохраненных программ, но это - расширение MySQL, что этому разрешают внешний контекст обработчика. Например, если Вы вызываете mysql клиентскую программу, можно ввести любой из этих операторов при подсказке:

mysql> SIGNAL SQLSTATE '77777';mysql> CREATE TRIGGER t_bi BEFORE INSERT ON t    -> FOR EACH ROW SIGNAL SQLSTATE '77777';mysql> CREATE EVENT e ON SCHEDULE EVERY 1 SECOND    -> DO SIGNAL SQLSTATE '77777';

SIGNAL выполняется согласно следующим правилам:

Если SIGNAL оператор указывает на деталь SQLSTATE значение, то значение используется, чтобы сигнализировать определенное условие. Пример:

CREATE PROCEDURE p (divisor INT)BEGIN  IF divisor = 0 THEN    SIGNAL SQLSTATE '22012';  END IF;END;

Если SIGNAL оператор использует именованное условие, условие должно быть объявлено в некотором контексте, который применяется к SIGNAL оператор, и должен быть определен, используя SQLSTATE значение, не код ошибки MySQL. Пример:

CREATE PROCEDURE p (divisor INT)BEGIN  DECLARE divide_by_zero CONDITION FOR SQLSTATE '22012';  IF divisor = 0 THEN    SIGNAL divide_by_zero;  END IF;END;

Если именованное условие не существует в пределах SIGNAL оператор, Undefined CONDITION ошибка происходит.

Если SIGNAL обращается к именованному условию, которое определяется с помощью кода ошибки MySQL, а не SQLSTATE значение, a SIGNAL/RESIGNAL can only use a CONDITION defined with SQLSTATE ошибка происходит. Следующие операторы вызывают ту ошибку, потому что именованное условие связывается с кодом ошибки MySQL:

DECLARE no_such_table CONDITION FOR 1051;SIGNAL no_such_table;

Если условие с именем объявляется многократно в различных контекстах, объявление с самым локальным контекстом применяется. Рассмотрите следующую процедуру:

CREATE PROCEDURE p (divisor INT)BEGIN  DECLARE my_error CONDITION FOR SQLSTATE '45000';  IF divisor = 0 THEN    BEGIN      DECLARE my_error CONDITION FOR SQLSTATE '22012';      SIGNAL my_error;    END;  END IF;  SIGNAL my_error;END;

Если divisor 0, первое SIGNAL оператор выполняется. Самое внутреннее my_error объявление условия применяется, повышая SQLSTATE '22012'.

Если divisor не 0, второе SIGNAL оператор выполняется. Наиболее удаленное my_error объявление условия применяется, повышая SQLSTATE '45000'.

Для получения информации о том, как сервер выбирает обработчики, когда условие происходит, см. Раздел 13.6.7.6, "Правила контекста для Обработчиков".

Сигналы могут быть повышены в пределах обработчиков исключений:

CREATE PROCEDURE p ()BEGIN  DECLARE EXIT HANDLER FOR SQLEXCEPTION  BEGIN    SIGNAL SQLSTATE VALUE '99999'      SET MESSAGE_TEXT = 'An error occurred';  END;  DROP TABLE no_such_table;END;

CALL p() достигает DROP TABLE оператор. Нет никакой названной таблицы no_such_table, таким образом, обработчик ошибок активируется. Обработчик ошибок уничтожает исходную ошибку ("никакая такая таблица") и делает новую ошибку с SQLSTATE '99999' и сообщение An error occurred.

13.6.7.5.1. Единицы информации Условия сигнала

Следующая таблица приводит имена единиц информации условия области диагностики, которые могут быть установлены в a SIGNAL (или RESIGNAL) оператор. Все элементы являются стандартным SQL кроме MYSQL_ERRNO, который является расширением MySQL. Для получения дополнительной информации об этих элементах см. Раздел 13.6.7.7, "MySQL Diagnostics Area".

Item Name             Definition---------             ----------CLASS_ORIGIN          VARCHAR(64)SUBCLASS_ORIGIN       VARCHAR(64)CONSTRAINT_CATALOG    VARCHAR(64)CONSTRAINT_SCHEMA     VARCHAR(64)CONSTRAINT_NAME       VARCHAR(64)CATALOG_NAME          VARCHAR(64)SCHEMA_NAME           VARCHAR(64)TABLE_NAME            VARCHAR(64)COLUMN_NAME           VARCHAR(64)CURSOR_NAME           VARCHAR(64)MESSAGE_TEXT          VARCHAR(128)MYSQL_ERRNO           SMALLINT UNSIGNED

Набор символов для символьных элементов является UTF-8.

Это недопустимо, чтобы присвоиться NULL к единице информации условия в a SIGNAL оператор.

A SIGNAL оператор всегда определяет SQLSTATE значение, или непосредственно, или косвенно обращаясь к именованному условию, определенному с помощью SQLSTATE значение. Первые два символа SQLSTATE значением является свой class, и class определяет значение по умолчанию для единиц информации условия:

  • Класс = '00' (успех)

    Недопустимый. SQLSTATE значения, которые начинаются '00' укажите на успех, и не допустимы для SIGNAL.

  • Класс = '01' (предупреждение)

    MESSAGE_TEXT = 'Unhandled user-defined warning';MYSQL_ERRNO = ER_SIGNAL_WARN
  • Класс = '02' (не найденный)

    MESSAGE_TEXT = 'Unhandled user-defined not found';MYSQL_ERRNO = ER_SIGNAL_NOT_FOUND
  • Класс> '02' (исключение)

    MESSAGE_TEXT = 'Unhandled user-defined exception';MYSQL_ERRNO = ER_SIGNAL_EXCEPTION

Для юридических классов другие единицы информации условия устанавливаются следующим образом:

CLASS_ORIGIN = SUBCLASS_ORIGIN = '';CONSTRAINT_CATALOG = CONSTRAINT_SCHEMA = CONSTRAINT_NAME = '';CATALOG_NAME = SCHEMA_NAME = TABLE_NAME = COLUMN_NAME = '';CURSOR_NAME = '';

Ошибочные значения, которые доступны после SIGNAL выполняется SQLSTATE значение, повышенное SIGNAL оператор и MESSAGE_TEXT и MYSQL_ERRNO элементы. Эти значения доступны от API C:

От SQL, вывода от SHOW WARNINGS и SHOW ERRORS указывает MYSQL_ERRNO и MESSAGE_TEXT значения в Code и Message столбцы.

Чтобы получить информацию от области диагностики, используйте GET DIAGNOSTICS оператор (см. Раздел 13.6.7.3,"GET DIAGNOSTICS Синтаксис"). Для получения информации об области диагностики см. Раздел 13.6.7.7, "MySQL Diagnostics Area".

13.6.7.5.2. Эффект Сигналов на Обработчиках, Курсорах, и Операторах

Сигналы имеют различные эффекты на выполнение оператора в зависимости от сигнала class. class определяет, насколько серьезный ошибка. MySQL игнорирует значение sql_mode системная переменная; в частности строгий режим SQL не имеет значения. MySQL также игнорирует IGNORE: Намерение SIGNAL должен повысить сгенерированную пользователем ошибку явно, таким образом, сигнал никогда не игнорируется.

В следующих описаниях, "необработанных", означает что никакой обработчик для сообщенного SQLSTATE значение было определено с помощью DECLARE ... HANDLER.

  • Класс = '00' (успех)

    Недопустимый. SQLSTATE значения, которые начинаются '00' укажите на успех, и не допустимы для SIGNAL.

  • Класс = '01' (предупреждение)

    Значение warning_count системная переменная восстанавливает работоспособность. SHOW WARNINGS показывает сигнал. SQLWARNING обработчики ловят сигнал. Если сигнал необрабатывается в функции, операторы не заканчиваются.

  • Класс = '02' (не найденный)

    NOT FOUND обработчики ловят сигнал. Нет никакого эффекта на курсоры. Если сигнал необрабатывается в функции, конце операторов.

  • Класс> '02' (исключение)

    SQLEXCEPTION обработчики ловят сигнал. Если сигнал необрабатывается в функции, конце операторов.

  • Класс = '40'

    Обработанный как обычное исключение.

Пример:

mysql> delimiter
            //mysql> CREATE FUNCTION f () RETURNS INT    -> BEGIN    ->   SIGNAL SQLSTATE
            '01234'; -- signal a warning    ->   RETURN
            5;    -> END//mysql> delimiter ;mysql> CREATE
            TABLE t (s1 INT);mysql> INSERT INTO t VALUES
            (f());

Результат состоит в том, что строка, содержащая 5, вставляется в таблицу t. Предупреждение, которое сообщается, может быть просмотрено с SHOW WARNINGS.