Область диагностики

Область диагностики содержит информацию об условиях ошибки, которые были созданы оператором SQL, а также некоторую информацию об операторе, который их сгенерировал.

Информация об операторе

Область информации об операторе содержит следующие данные:

• NUMBER — это количество условий, присутствующих в области диагностики.
• ROW_COUNT имеет такое же значение, как функция ROW_COUNT() для оператора, который создал условия.

Информация об условии

Каждое условие имеет несколько свойств, которые здесь объясняются.

Типы и размеры данных

В следующей таблице показаны тип и размер всех свойств:

Эти свойства никогда не могут быть установлены в NULL. Если они пустые, используется пустая строка.

Общие свойства условия

Наиболее распространённые из них имеют значение для всех встроенных ошибок и могут быть прочитаны как через SQL, так и через API:

RETURNED_SQLSTATE — SQLSTATE условия. Это пятисимвольный код, состоящий из класса (первые два символа) и подкласса (последние три символа). Дополнительную информацию об этом свойстве можно найти на странице SQLSTATE.

MYSQL_ERRNO — код ошибки. Каждое встроенное условие имеет уникальный числовой код. 0 указывает на успех, но его нельзя явно установить или прочитать через SQL. Список встроенных кодов ошибок см. на странице MariaDB Error Codes. Функция API для чтения — mysql_errno().

MESSAGE_TEXT — описательное, читаемое человеком сообщение. Для встроенных ошибок разбор этой строки — единственный способ получить больше информации об ошибке. Например, при разборе сообщения «Таблица 'tab1' уже существует», программа может определить, что отсутствует таблица tab1. Функция API для чтения — mysql_error().

Для условий, созданных пользователем с помощью SIGNAL, если MYSQL_ERRNO и MESSAGE_TEXT не указаны, их значения по умолчанию зависят от первых двух символов SQLSTATE:

• '00' означает 'успех'. Его нельзя установить ни в каком виде, и его можно прочитать только через API.
• Для класса '01' значение по умолчанию MYSQL_ERRNO — 1642, а значение по умолчанию MESSAGE_TEXT — 'Необработанное пользовательское предупреждение'.
• Для класса '02' значение по умолчанию MYSQL_ERRNO — 1643, а значение по умолчанию MESSAGE_TEXT — 'Необработанное пользовательское условие отсутствия'.
• Во всех остальных случаях, включая значение '45000', значение по умолчанию MYSQL_ERRNO — 1644, а значение по умолчанию MESSAGE_TEXT — 'Необработанное пользовательское исключение'.

Специальные свойства условия

Существуют дополнительные свойства условия, которые никогда не устанавливаются для встроенных ошибок. Их можно установить только с помощью операторов SIGNAL и RESIGNAL, и их можно прочитать только с помощью GET DIAGNOSTICS — не через API. К таким свойствам относятся:

CLASS_ORIGIN указывает, использует ли SQLSTATE стандартный класс или класс, специфичный для программного обеспечения. Если он определен в документе стандартов SQL ISO 9075-2 (раздел 24.1, SQLSTATE), значение этого свойства должно быть 'ISO 9075', в противном случае — 'MySQL'. Однако принимается любая строка.

SUBCLASS_ORIGIN указывает, использует ли SQLSTATE стандартный подкласс или подкласс, специфичный для программного обеспечения. Если SQLSTATE определен в документе стандартов SQL ISO 9075-2 (раздел 24.1, SQLSTATE), значение этого свойства должно быть 'ISO 9075', в противном случае — 'MySQL'. Однако принимается любая строка.

SCHEMA_NAME указывает, в какой схеме (базе данных) произошла ошибка.

TABLE_NAME указывает имя таблицы, к которой обратился неудачный оператор.

COLUMN_NAME указывает имя столбца, к которому обратился неудачный оператор.

CONSTRAINT_NAME указывает имя ограничения, которое было нарушено.

CONSTRAINT_SCHEMA указывает, в какой схеме находится нарушенное ограничение.

CURSOR_NAME указывает имя курсора, вызвавшего ошибку.

Следующие свойства могут использоваться и определены в стандартном SQL, но не имеют значения, потому что MariaDB в настоящее время не поддерживает каталоги:

CATALOG_NAME используется стандартным SQL для указания, в каком каталоге произошла ошибка.

CONSTRAINT_CATALOG используется стандартным SQL для указания, в каком каталоге находится нарушенное ограничение.

Как заполняется и очищается область диагностики

Когда оператор создает одно или несколько условий ошибки (ошибки, предупреждения, заметки), условия вставляются в область диагностики, а область информации об операторе обновляется информацией об этом операторе. Обычно это также очищает все старые условия из области диагностики, но есть исключение: если новый оператор — правильно проанализированный RESIGNAL или GET DIAGNOSTICS, старое содержимое останется в области диагностики. SIGNAL очищает старые условия.

При выполнении оператора, основанного на таблице (например, INSERT), старые данные в области диагностики очищаются, даже если оператор не создает никаких условий. Однако если операторы, не обращающиеся к таблицам (например, SET или SELECT без предложения FROM), выполняются и не генерируют предупреждений, область диагностики остается неизменной.

Максимальное количество условий, которое может находиться в области диагностики, составляет max_error_count. Если это значение равно 0, область диагностики пуста. Если эта переменная изменена, новое значение вступит в силу с выполнением следующего оператора (то есть область диагностики не усекается немедленно).

Как получить доступ к области диагностики

Следующие операторы явно добавляют условия в область диагностики:

• SIGNAL: создает пользовательскую ошибку.
• RESIGNAL: после создания ошибки генерирует измененную версию этой ошибки.

Следующие операторы считывают содержимое из области диагностики:

• GET DIAGNOSTICS — единственный способ прочитать всю информацию
• SHOW WARNINGS отображает сводку ошибок, предупреждений и заметок
• SHOW ERRORS отображает сводку ошибок

DECLARE HANDLER может использоваться для обработки условий ошибки в хранимых процедурах.

DECLARE CONDITION может использоваться для сопоставления SQLSTATE или кода ошибки с именем. Это имя может быть использовано в операторах DECLARE HANDLER, SIGNAL и RESIGNAL.

Все эти операторы также могут быть выполнены внутри хранимой процедуры. Однако только SHOW WARNINGS и SHOW ERRORS могут быть выполнены как подготовленный оператор. После оператора EXECUTE область диагностики содержит информацию о подготовленном операторе, если он создает условия ошибки.

См. также

• RESIGNAL
• SIGNAL
• HANDLER
• GET DIAGNOSTICS
• SHOW WARNINGS
• SHOW ERRORS
• DECLARE HANDLER
• Коды ошибок MariaDB