Mssql raise error

message_text — сообщение, которое вы хотите показать при ошибке. Замечание: вы можете добавлять пользовательские сообщения для вывода информации об ошибке. Смотрите следующий раздел статьи.
message_id — id сообщения об ошибке. Если вы хотите вывести пользовательское сообщение, вы можете определить этот идентификатор. Посмотрите список идентификаторов сообщений в sys.messages DMV.
Запрос:

select * from sys.messages

Вывод:

severity — серьезность ошибки. Тип данных переменной severity — smallint, значения находятся в диапазоне от 0 до 25. Допустимыми значениями серьезности ошибки являются:

• 0-10

— информационные сообщения

• 11-18

— ошибки

• 19-25

— фатальные ошибки

Замечание: Если вы создаете пользовательское сообщение, сложность, указанная в этом сообщении, будет перебиваться сложностью, заданной в операторе RAISERROR.
state — уникальное идентификационное число, которое может использоваться для раздела кода, вызывающего ошибку. Тип данных параметра state — smallint, и допустимые значения между 0 и 255.

Теперь давайте перейдем к практическим примерам.

Пример 1: использование оператора SQL Server RAISERROR для вывода сообщения

В этом примере вы можете увидеть, как можно отобразить ошибку или информационное сообщение с помощью оператора RAISERROR.

Предположим, что вы хотите отобразить сообщение после вставки записей в таблицу. Мы можем использовать операторы PRINT или RAISERROR. Ниже — код:

SET nocount ON 

INSERT INTO tblpatients 

            (patient_id, 

             patient_name, 

             address, 

             city) 

VALUES     ('OPD00006', 

            'Nimesh Upadhyay', 

            'AB-14, Ratnedeep Flats', 

            'Mehsana') 

RAISERROR ( 'Patient detail added successfully',1,1) 

Вывод:

Как видно на рисунке выше, ID сообщения равно 50000, поскольку это пользовательское сообщение.

Пример 2: оператор SQL RAISERROR с текстом динамического сообщения

Теперь посмотрите, как мы можем создать текст динамического сообщения для оператора SQL RAISERROR.

Предположим, что мы хотим напечатать в сообщении ID пациента. Я описал локальную переменную с именем @PatientID, которая содержит patient_id. Чтобы отобразить значение переменной @PatientID в тексте сообщения, мы можем использовать следующий код:

DECLARE @PatientID VARCHAR(15) 

DECLARE @message NVARCHAR(max) 

SET @PatientID='OPD00007' 

SET @message ='Patient detail added successfully. The OPDID is %s' 

INSERT INTO tblpatients 

            (patient_id, 

             patient_name, 

             address, 

             city) 

VALUES     ('' + @PatientID + '', 

            'Nimesh Upadhyay', 

            'AB-14, Ratnedeep Flats', 

            'Mehsana') 

RAISERROR ( @message,1,1,@patientID) 

Вывод:

Для отображения строки в операторе RAISERROR, мы должны использовать операторы print в стиле языка Си.

Как видно на изображении выше, для вывода параметра в тексте сообщения я использую опцию %s, которая отображает строковое значение параметра. Если вы хотите вывести целочисленный параметр, вы можете использовать опцию %d.

Использование SQL RAISERROR в блоке TRY..CATCH

В этом примере мы добавляем SQL RAISERROR в блок TRY. При запуске этого кода он выполняет связанный блок CATCH. В блоке CATCH мы будем выводить подробную информацию о возникшей ошибке.

BEGIN try 

    RAISERROR ('Error invoked in the TRY code block.',16,1 ); 

END try 

BEGIN catch 

    DECLARE @ErrorMsg NVARCHAR(4000); 

    DECLARE @ErrSeverity INT; 

    DECLARE @ErrState INT; 

    SELECT @ErrorMsg = Error_message(), 

           @ErrSeverity = Error_severity(), 

           @ErrState = Error_state(); 

    RAISERROR (@ErrorMsg,

               @ErrSeverity,

               @ErrState 

    ); 

END catch;

Так мы добавили оператор RAISERROR с ВАЖНОСТЬЮ МЕЖДУ 11 И 19. Это вызывает выполнение блока CATCH.

В блоке CATCH мы показываем информацию об исходной ошибке, используя оператор RAISERROR.
Вывод:

Как вы можете увидеть, код вернул информацию об исходной ошибке.

Теперь давайте разберемся, как добавить пользовательское сообщение, используя хранимую процедуру sp_addmessage.

Хранимая процедура sp_addmessage

Мы можем добавить пользовательское сообщение, выполнив хранимую процедуру sp_addmessages. Синтаксис процедуры:

EXEC Sp_addmessage 

  @msgnum= 70001, 

  @severity=16, 

  @msgtext='Please enter the numeric value', 

  @lang=NULL, 

  @with_log='TRUE', 

  @replace='Replace'; 

@msgnum: задает номер сообщения. Тип данных параметра — integer. Это ID пользовательского сообщения.
@severity: указывает уровень серьезности ошибки. Допустимые значения от 1 до 25. Тип данных параметра — smallint.
@messagetext: задает текст сообщения, который вы хотите выводить. Тип данных параметра nvarchar(255), значение по умолчанию NULL.
@lang: задает язык, который вы хотите использовать для вывода сообщения об ошибке. Значение по умолчанию NULL.
@with_log: этот параметр используется для записи сообщения в просмотрщик событий. Допустимые значения TRUE и FALSE. Если вы задаете TRUE, сообщение об ошибке будет записано в просмотрщик событий Windows. Если выбрать FALSE, ошибка не будет записана в журнал ошибок Windows.
@replace: если вы хотите заменить существующее сообщение об ошибке на пользовательское сообщение и уровень серьезности, вы можете указать это в хранимой процедуре.

Предположим, что вы хотите создать сообщение об ошибке, которое возвращает ошибку о недопустимом качестве (invalid quality). В операторе INSERT значение invalid_quality находится в диапазоне между 20 и 100. Сообщение следует рассматривать как ошибку с уровнем серьезности 16.

Чтобы создать такое сообщение, выполните следующий запрос:

USE master;

go 

EXEC Sp_addmessage 

  70001, 

  16, 

  N'Product Quantity must be between 20 and 100.'; 

go

После добавления сообщения выполните запрос ниже, чтобы увидеть его:

USE master 

go 

SELECT * FROM   sys.messages WHERE  message_id = 70001 

Вывод:

Как использовать пользовательские сообщения об ошибках

Как упоминалось выше, мы должны использовать message_id в операторе RAISERROR для пользовательских сообщений.

Мы создали сообщение с ID = 70001. Оператор RAISERROR должен быть таким:

USE master 

go 

RAISERROR (70001,16,1 ); 

go

Вывод:

Оператор RAISERROR вернул пользовательское сообщение.

Хранимая процедура sp_dropmessage

Хранимая процедура sp_dropmessage используется для удаления пользовательских сообщений. Синтаксис оператора:

EXEC Sp_dropmessage @msgnum

Здесь @msgnum задает ID сообщения, которое вы хотите удалить.

Теперь мы хотим удалить сообщение, с ID = 70001. Запрос:

EXEC Sp_dropmessage 70001

Выполним следующий запрос для просмотра сообщения после его удаления:

USE master 

go 

SELECT * FROM   sys.messages WHERE  message_id = 70001 

Вывод:

Как видно, сообщение было удалено.

SQL-Ex blog

Новости сайта «Упражнения SQL», статьи и переводы

Оператор SQL Server RAISERROR на простых примерах

Оператор RAISERROR используется для посылки подготовленного сообщения в клиентское приложение. Он также может использоваться для отладки приложения и применения механизма обработки ошибок.

Синтаксис и параметры оператора SQL RAISERROR

Оператор SQL RAISERROR имеет следующий синтаксис:

Ниже описание ключевых параметров RAISERROR, которые вы можете задать:

message_text — сообщение, которое вы хотите показать при ошибке. Замечание: вы можете добавлять пользовательские сообщения для вывода информации об ошибке. Смотрите следующий раздел статьи.
message_id — id сообщения об ошибке. Если вы хотите вывести пользовательское сообщение, вы можете определить этот идентификатор. Посмотрите список идентификаторов сообщений в sys.messages DMV.
Запрос:

severity — серьезность ошибки. Тип данных переменной severity — smallint, значения находятся в диапазоне от 0 до 25. Допустимыми значениями серьезности ошибки являются:

• 0-10 — информационные сообщения
• 11-18 — ошибки
• 19-25 — фатальные ошибки

Замечание: Если вы создаете пользовательское сообщение, сложность, указанная в этом сообщении, будет перебиваться сложностью, заданной в операторе RAISERROR.
state — уникальное идентификационное число, которое может использоваться для раздела кода, вызывающего ошибку. Тип данных параметра state — smallint, и допустимые значения между 0 и 255.

Теперь давайте перейдем к практическим примерам.

Пример 1: использование оператора SQL Server RAISERROR для вывода сообщения

В этом примере вы можете увидеть, как можно отобразить ошибку или информационное сообщение с помощью оператора RAISERROR.

Предположим, что вы хотите отобразить сообщение после вставки записей в таблицу. Мы можем использовать операторы PRINT или RAISERROR. Ниже — код:

Вывод:

Как видно на рисунке выше, ID сообщения равно 50000, поскольку это пользовательское сообщение.

Пример 2: оператор SQL RAISERROR с текстом динамического сообщения

Теперь посмотрите, как мы можем создать текст динамического сообщения для оператора SQL RAISERROR.

Предположим, что мы хотим напечатать в сообщении ID пациента. Я описал локальную переменную с именем @PatientID, которая содержит patient_id. Чтобы отобразить значение переменной @PatientID в тексте сообщения, мы можем использовать следующий код:

Вывод:

Для отображения строки в операторе RAISERROR, мы должны использовать операторы print в стиле языка Си.

Как видно на изображении выше, для вывода параметра в тексте сообщения я использую опцию %s, которая отображает строковое значение параметра. Если вы хотите вывести целочисленный параметр, вы можете использовать опцию %d.

Использование SQL RAISERROR в блоке TRY..CATCH

В этом примере мы добавляем SQL RAISERROR в блок TRY. При запуске этого кода он выполняет связанный блок CATCH. В блоке CATCH мы будем выводить подробную информацию о возникшей ошибке.

Так мы добавили оператор RAISERROR с ВАЖНОСТЬЮ МЕЖДУ 11 И 19. Это вызывает выполнение блока CATCH.

В блоке CATCH мы показываем информацию об исходной ошибке, используя оператор RAISERROR.
Вывод:

Как вы можете увидеть, код вернул информацию об исходной ошибке.

Теперь давайте разберемся, как добавить пользовательское сообщение, используя хранимую процедуру sp_addmessage.

Хранимая процедура sp_addmessage

Мы можем добавить пользовательское сообщение, выполнив хранимую процедуру sp_addmessages. Синтаксис процедуры:

@msgnum: задает номер сообщения. Тип данных параметра — integer. Это ID пользовательского сообщения.
@severity: указывает уровень серьезности ошибки. Допустимые значения от 1 до 25. Тип данных параметра — smallint.
@messagetext: задает текст сообщения, который вы хотите выводить. Тип данных параметра nvarchar(255), значение по умолчанию NULL.
@lang: задает язык, который вы хотите использовать для вывода сообщения об ошибке. Значение по умолчанию NULL.
@with_log: этот параметр используется для записи сообщения в просмотрщик событий. Допустимые значения TRUE и FALSE. Если вы задаете TRUE, сообщение об ошибке будет записано в просмотрщик событий Windows. Если выбрать FALSE, ошибка не будет записана в журнал ошибок Windows.
@replace: если вы хотите заменить существующее сообщение об ошибке на пользовательское сообщение и уровень серьезности, вы можете указать это в хранимой процедуре.

Предположим, что вы хотите создать сообщение об ошибке, которое возвращает ошибку о недопустимом качестве (invalid quality). В операторе INSERT значение invalid_quality находится в диапазоне между 20 и 100. Сообщение следует рассматривать как ошибку с уровнем серьезности 16.

Чтобы создать такое сообщение, выполните следующий запрос:

После добавления сообщения выполните запрос ниже, чтобы увидеть его:

Как использовать пользовательские сообщения об ошибках

Как упоминалось выше, мы должны использовать message_id в операторе RAISERROR для пользовательских сообщений.

Мы создали сообщение с Оператор RAISERROR должен быть таким:

Оператор RAISERROR вернул пользовательское сообщение.

Хранимая процедура sp_dropmessage

Хранимая процедура sp_dropmessage используется для удаления пользовательских сообщений. Синтаксис оператора:

Здесь @msgnum задает ID сообщения, которое вы хотите удалить.

Теперь мы хотим удалить сообщение, с Запрос:

Выполним следующий запрос для просмотра сообщения после его удаления:

Как видно, сообщение было удалено.

Обратные ссылки

Нет обратных ссылок

Комментарии

Показывать комментарии Как список | Древовидной структурой

Автор не разрешил комментировать эту запись

Источник

RAISERROR (Transact-SQL)

Область применения: SQL Server (все поддерживаемые версии) База данных SQL Azure Управляемый экземпляр SQL Azure Azure Synapse Analytics Analytics Platform System (PDW)

Инструкция RAISERROR не учитывает SET XACT_ABORT . Новые приложения должны использовать THROW вместо RAISERROR .

Создает сообщение об ошибке и запускает обработку ошибок для сеанса. RAISERROR может либо ссылаться на определяемое пользователем сообщение, хранящееся в sys.messages , либо динамически создавать сообщение. Это сообщение возвращается как сообщение об ошибке сервера вызывающему приложению или соответствующему блоку CATCH конструкции TRY. CATCH . В новых же приложениях следует использовать инструкцию THROW.

Соглашения о синтаксисе Transact-SQL

Синтаксис

Синтаксис для SQL Server и Базы данных SQL Azure:

Синтаксис для Azure Synapse Analytics и Parallel Data Warehouse:

Ссылки на описание синтаксиса Transact-SQL для SQL Server 2014 и более ранних версий, см. в статье Документация по предыдущим версиям.

Аргументы

msg_id

Определяемый пользователем номер сообщения об ошибке, который хранится в представлении каталога sys.messages с помощью sp_addmessage . Номера пользовательских сообщений об ошибках должны быть больше 50 000. Если аргумент msg_id не определен, то инструкция RAISERROR создает сообщение об ошибке с номером ошибки 50000.

msg_str

Определяемое пользователем сообщение с форматом, аналогичным формату функции printf из стандартной библиотеки языка С. Это сообщение об ошибке не должно содержать более 2 047 символов. Если сообщение содержит 2 048 и более символов, то отображаются только первые 2 044, а за ними появляется знак многоточия, показывающий, что сообщение было усечено. Обратите внимание, что параметры подстановки содержат больше символов, чем видно на выходе из-за внутренней структуры хранения. Например, если параметр подстановки %d имеет значение 2, он выводит один символ в строку сообщения, хотя при хранении занимает три дополнительных символа. Из-за этой особенности хранения количество доступных символов для выходного сообщения уменьшается.

Если аргумент msg_str определен, то инструкция RAISERROR создает сообщение об ошибке с номером ошибки 50000.

Аргумент msg_str является символьной строкой, которая может содержать спецификации преобразования. Каждая спецификация преобразования определяет, каким образом значение из списка аргументов будет отформатировано и помещено в поле в местоположении спецификации преобразования в строке msg_str. Спецификации преобразования имеют следующий формат:

В строке msg_str могут использоваться следующие параметры:

Код, определяющий промежутки и выравнивание подставляемого значения.

width

Целое число, определяющее минимальную ширину поля, в которое помещается значение аргумента. Если длина значения аргумента равна значению параметра width или превышает его, то значение записывается без заполнения. Если значение короче, чем значение параметра width, оно дополняется до длины, определенной в параметре width.

Символ «звездочка» (*) означает, что ширина определяется соответствующим аргументом в списке аргументов, значение которого должно быть целым числом.

precision

Максимальное число символов, берущееся из значения аргумента для значения строки. Например, если в строке содержится пять символов, а точность равна 3, то для значения строки используются первые три символа.

Для целых значений аргумент precision определяет минимальное количество отображаемых цифр.

Символ «звездочка» (*) означает, что точность определяется соответствующим аргументом в списке аргументов, значение которого должно быть целым числом.

Используется с типами символов d, i, o, s, x, X или u, создает значения типа данных shortint (h) или longint (l).

Эти спецификации типа основаны на изначально определенных доя функции printf в стандартной библиотеке C. Спецификации типов, используемые в строках сообщений инструкции RAISERROR , сопоставляются с типами данных языка Transact-SQL, а спецификации, используемые в функции printf , сопоставляются с типами данных языка C. Спецификации типов, используемые в функции printf , не поддерживаются инструкцией RAISERROR , если в языке Transact-SQL нет типов данных, схожих с соответствующими типами данных языка C. Например, спецификация %p для указателей не поддерживается инструкцией RAISERROR , так как в языке Transact-SQL нет типа данных для указателей.

Для преобразования какого-либо значения в тип данных Transact-SQL bigint нужно указать спецификацию %I64d.

@local_variable

Переменная любого допустимого типа данных для символов, содержащая строку того же формата, что и строка msg_str. Аргумент @local_variable должен иметь тип char или varchar, либо поддерживать неявное преобразование в эти типы данных.

severity

Определенный пользователем уровень серьезности, связанный с этим сообщением. Если при помощи аргумента msg_id вызываются определяемые пользователем сообщения, созданные процедурой sp_addmessage , то уровень серьезности, указанный в RAISERROR , заменяет уровень серьезности, указанный в процедуре sp_addmessage .

Для степеней серьезности от 19 до 25 требуется параметр WITH LOG. Степени серьезности меньше 0 интерпретируются как 0. Степени серьезности больше 25 интерпретируются как 25.

Уровни серьезности от 20 до 25 считаются неустранимыми. Если обнаруживается неустранимый уровень серьезности, то после получения сообщения соединение с клиентом обрывается и регистрируется сообщение об ошибке в журналах приложений и ошибок.

Можно указать -1 , чтобы получить степень серьезности, связанную с ошибкой, как показано в следующем примере.

state

Целое число от 0 до 255. Для отрицательных значений по умолчанию используется 1. Значения больше 255 использовать не следует.

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

argument

Параметры, использующиеся при подстановке для переменных, определенных в msg_str, или для сообщений, соответствующих аргументу msg_id. Число параметров подстановки может быть от 0 и более, при этом общее количество параметров подстановки не может превышать 20. Каждый параметр подстановки может быть локальной переменной или любым из этих типов данных: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary или varbinary. Другие типы данных не поддерживаются.

Параметр

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

Ошибки, созданные инструкцией RAISERROR , аналогичны ошибкам, созданным кодом компонента «Ядро СУБД». Значения, указанные RAISERROR , передаются системными функциями ERROR_LINE , ERROR_MESSAGE , ERROR_NUMBER , ERROR_PROCEDURE , ERROR_SEVERITY , ERROR_STATE и @@ERROR . Если инструкция RAISERROR с уровнем серьезности 11 или выше выполняется в блоке TRY, управление передается соответствующему блоку CATCH . Ошибка возвращается вызывающему объекту, если инструкция RAISERROR вызывается:

за пределами области любого блока TRY ;

с уровнем серьезности, равным 10 и менее в блоке TRY ;

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

В блоках CATCH инструкция RAISERROR может использоваться для передачи сообщения об ошибке, вызывающего блок CATCH , во время получения исходных сведений об ошибке при помощи таких системных функций, как ERROR_NUMBER и ERROR_MESSAGE . По умолчанию для сообщений с серьезностью от 1 до 10 параметр @@ERROR устанавливается в значение 0.

Если при помощи аргумента msg_id задано определяемое пользователем сообщение, доступное в представлении каталога sys.messages, RAISERROR обрабатывает сообщение из текстового столбца при помощи тех же правил, которые применялись к тексту определяемого пользователем сообщения, заданного аргументом msg_str. Текст сообщения, определяемого пользователем, может содержать спецификации преобразования, а RAISERROR сопоставит значения аргументов данным спецификациям преобразования. Процедура sp_addmessage позволяет добавить пользовательские сообщения об ошибках, процедура sp_dropmessage — удалять их.

Инструкция RAISERROR может использоваться в качестве альтернативы инструкции PRINT для возвращения сообщений вызывающим приложениям. Инструкция RAISERROR поддерживает функцию подстановки символов, сходную с функцией printf стандартной библиотеки языка С, которая отличается от инструкции Transact-SQL PRINT . Инструкция PRINT не зависит от блоков TRY , в то время как инструкция RAISERROR , выполняемая с уровнем серьезности от 11 до 19 в блоке TRY, передает управление процессом соответствующему блоку CATCH . Задайте уровень серьезности, равный 10 или меньше, чтобы инструкция RAISERROR возвращала сообщения из блока TRY без вызова блока CATCH .

Обычно последовательные аргументы заменяют последовательные спецификации преобразования; первый аргумент заменяет первую спецификацию преобразования, второй аргумент заменяет вторую спецификацию преобразования и так далее. Например, в следующей инструкции RAISERROR первый аргумент N’number’ подставляется на место первой спецификации преобразования %s , а второй аргумент 5 — на место второй спецификации преобразования %d. .

Если в качестве ширины или точности спецификации преобразования задан символ «звездочка» ( * ), то используемое для ширины или для точности значение определяется как значение аргумента целого типа. В этом случае одна спецификация преобразования может использоваться до трех аргументов — для значений ширины, точности и подстановки.

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

Разрешения

Степень серьезности от 0 до 18 может указать любой пользователь. Уровни серьезности от 19 до 25 могут быть указаны только членами предопределенной роли сервера sysadmin и пользователями с разрешениями ALTER TRACE.

Примеры

A. Возвращение сведений об ошибке из блока CATCH

Следующий пример кода показывает, как можно использовать инструкцию RAISERROR внутри блока TRY , чтобы передать управление блоку CATCH . Также в этом примере показано, каким образом для возвращения сведений об ошибке используется инструкция RAISERROR , которая вызывает блок CATCH .

Инструкция RAISERROR может формировать только ошибки с состоянием от 1 до 127 включительно. Так как компонент «Ядро СУБД» может вызывать ошибки с состоянием 0, рекомендуется проверять состояние ошибки, возвращаемое функцией ERROR_STATE, перед передачей его по значению в виде параметра состояния для RAISERROR .

Б. Создание нерегламентированного сообщения в представлении каталога sys.messages

В следующем примере показано, как инициировать сообщение, хранящееся в представлении каталога sys.messages. Это сообщение было добавлено в представление каталога sys.messages при помощи системной хранимой процедуры sp_addmessage как сообщение с номером 50005 .

В. Использование локальной переменной для предоставления текста сообщения

В следующем примере кода показано, как использовать локальную переменную для предоставления текста сообщения для инструкции RAISERROR .

Источник

Raise error in case of error

   <source lang="sql">

6> DECLARE @sql AS NVARCHAR(4000),
7> @b AS VARBINARY(1000), @s AS VARCHAR(2002);
8> SET @s = «0x0123456789abcdef»;
9>
10> IF @s NOT LIKE «0x%» OR @s LIKE «0x%[^0-9a-fA-F]%»
11> BEGIN
12> RAISERROR(«Possible SQL Injection attempt.», 16, 1);
13> RETURN;
14> END
15>
16> SET @sql = N»SET @o = » + @s + N»;»;
17> EXEC sp_executesql
18> @stmt = @sql,
19> @params = N»@o AS VARBINARY(1000) OUTPUT»,
20> @o = @b OUTPUT;
21>
22> SELECT @b;
23> GO

0x0123456789ABCDEF

1>
2></source>

Raise error out of a procedure

   <source lang="sql">

13> create table Billings (
14> BankerID INTEGER,
15> BillingNumber INTEGER,
16> BillingDate datetime,
17> BillingTotal INTEGER,
18> TermsID INTEGER,
19> BillingDueDate datetime ,
20> PaymentTotal INTEGER,
21> CreditTotal INTEGER
22>
23> );
24> GO
1>
2> INSERT INTO Billings VALUES (1, 1, «2005-01-22″, 165, 1,»2005-04-22»,123,321);
3> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (2, 2, «2001-02-21″, 165, 1,»2002-02-22»,123,321.);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (3, 3, «2003-05-02″, 165, 1,»2005-04-12»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (4, 4, «1999-03-12″, 165, 1,»2005-04-18»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (5, 5, «2000-04-23″, 165, 1,»2005-04-17»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (6, 6, «2001-06-14″, 165, 1,»2005-04-18»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (7, 7, «2002-07-15″, 165, 1,»2005-04-19»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (8, 8, «2003-08-16″, 165, 1,»2005-04-20»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (9, 9, «2004-09-17″, 165, 1,»2005-04-21»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (0, 0, «2005-10-18″, 165, 1,»2005-04-22»,123,321);
2> GO
(1 rows affected)
1>
2>
3> CREATE PROC spInsertBilling
4> @BankerID int, @BillingNumber varchar(50),
5> @BillingDate smalldatetime, @BillingTotal money,
6> @TermsID int, @BillingDueDate smalldatetime
7> AS
8> IF EXISTS(SELECT * FROM Billings WHERE BankerID = @BankerID)
9> BEGIN
10> INSERT Billings (BankerID)
11> VALUES (@BankerID)
12> END
13> ELSE
14> BEGIN
15> RAISERROR(«Not a valid BankerID!»,1,1)
16> RETURN -100
17> END
18> GO
1>
2>
3> DECLARE @ReturnVar int
4> EXEC @ReturnVar = spInsertBilling
5> 799,»ZXK-799″,»2002-07-01″,299.95,1,»2001-08-01″
6> PRINT «Return code was: » + CONVERT(varchar,@ReturnVar)
7> GO
Not a valid BankerID!
Return code was: -100
1>
2> drop PROC spInsertBilling;
3> GO
1>
2>
3> drop table Billings;
4> GO</source>

Raise exception with parameters

   <source lang="sql">

6> DECLARE @ProductId INT
7> SET @ProductId = 100
8>
9>
10> RAISERROR(«Problem with ProductId %i», 16, 1, @ProductId)
11> GO
Msg 50000, Level 16, State 1, Server JSQLEXPRESS, Line 10
Problem with ProductId 100
1></source>

RAISERROR ( -1, @parm1, @parm2)

   <source lang="sql">

28> DECLARE @parm1 varchar(30), @parm2 int
29> SELECT @parm1=USER_NAME(), @parm2=@@spid
30> RAISERROR (50001, 15, -1, @parm1, @parm2)
31> GO
Msg 50001, Level 15, State 1, Server JSQLEXPRESS, Line 30
The specified value for dbo was invalid.
1></source>

RAISERROR syntax

   <source lang="sql">

RAISERROR ({msg_id | msg_str}, severity, state[, argument1
[, argumentn]])
[WITH LOG]|[WITH NOWAIT]
RAISERROR Options Value Description
LOG Logs the error in the SQL Server error log and the application log.
NOWAIT Sends messages immediately to the client.
SETERROR Sets @@ERROR value to msg_id or 50000, regardless of the severity level.</source>

Raising a message not defined in sysmessages.

   <source lang="sql">

6> DECLARE @chrPrintMsg CHAR(255)
7>
8> RAISERROR(«Undefined error raised using the WITH SETERROR option»,1,2) WITH SETERROR
9>
10> SELECT @chrPrintMsg = «Using WITH SETERROR sets the error number generated to » + CONVERT(char,@@error)
11> PRINT @chrPrintMsg
12> GO
Undefined error raised using the WITH SETERROR option
Using WITH SETERROR sets the error number generated to 50000</source>

The syntax of the RAISERROR statement: RAISERROR ({message_id|message_string}, severity, state [, argument]…)

   <source lang="sql">

13> create table Billings (
14> BankerID INTEGER,
15> BillingNumber INTEGER,
16> BillingDate datetime,
17> BillingTotal INTEGER,
18> TermsID INTEGER,
19> BillingDueDate datetime ,
20> PaymentTotal INTEGER,
21> CreditTotal INTEGER
22>
23> );
24> GO
1>
2> INSERT INTO Billings VALUES (1, 1, «2005-01-22″, 165, 1,»2005-04-22»,123,321);
3> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (2, 2, «2001-02-21″, 165, 1,»2002-02-22»,123,321.);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (3, 3, «2003-05-02″, 165, 1,»2005-04-12»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (4, 4, «1999-03-12″, 165, 1,»2005-04-18»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (5, 5, «2000-04-23″, 165, 1,»2005-04-17»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (6, 6, «2001-06-14″, 165, 1,»2005-04-18»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (7, 7, «2002-07-15″, 165, 1,»2005-04-19»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (8, 8, «2003-08-16″, 165, 1,»2005-04-20»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (9, 9, «2004-09-17″, 165, 1,»2005-04-21»,123,321);
2> GO
(1 rows affected)
1> INSERT INTO Billings VALUES (0, 0, «2005-10-18″, 165, 1,»2005-04-22»,123,321);
2> GO
(1 rows affected)
1>
2>
3> CREATE PROC spInsertBilling
4> @BankerID int, @BillingNumber varchar(50),
5> @BillingDate smalldatetime, @BillingTotal money,
6> @TermsID int, @BillingDueDate smalldatetime
7> AS
8> IF EXISTS(SELECT * FROM Bankers WHERE BankerID = @BankerID)
9> BEGIN
10> INSERT Billings (BankerID)
11> VALUES (@BankerID)
12> END
13> ELSE
14> BEGIN
15> RAISERROR(«Not a valid BankerID!»,1,1)
16> RETURN -100
17> END
18> GO
1>
2>
3> drop PROC spInsertBilling;
4> GO
1>
2>
3> drop table Billings;
4> GO</source>

Using RAISERROR without an Error Number

   <source lang="sql">

3>
4> RAISERROR («we have a problem.», 16, 1)
5></source>

Using RAISERROR with the SETERROR Option

   <source lang="sql">

6> sp_addmessage
7> 60000,
8> 16,
9> «Unable to find ID %09d»
10> GO
Msg 15043, Level 16, State 1, Server BCE67B1242DE45ASQLEXPRESS, Procedure sp_addmessage, Line 137
You must specify «REPLACE» to overwrite an existing message.
1>
2>
3> RAISERROR (60000, 1, 2)
4> SELECT @@ERROR
5> GO
Unable to find ID (null)

         0

(1 rows affected)
1> RAISERROR (60000, 1, 2) WITH SETERROR
2> SELECT @@ERROR
3>
4> sp_dropmessage
5> 60000
6> GO
Msg 102, Level 15, State 1, Server BCE67B1242DE45ASQLEXPRESS, Line 5
Incorrect syntax near «60000».
1></source>

When something goes wrong in your T-SQL, you want to fix the problem quickly with minimal digging around and disruption to users. SQL Server-generated error messages are highly technical and hard to understand, which can make it difficult to isolate issues and can slow down resolution time. Fortunately, DBAs can implement SQL Server RAISERROR as an alternative to SQL Server error messages.

RAISERROR is a SQL Server error handling statement that generates an error message and initiates error processing. RAISERROR can either reference a user-defined message that is stored in the sys.messages catalog view or it can build a message dynamically. The message is returned as a server error message to the calling application or to an associated CATCH block of a TRY…CATCH construct.

There are several scenarios in which it’s appropriate to use the RAISERROR statement:

• Transact-SQL code troubleshooting
• Returning messages that contain variable text
• Examining data values
• When you need the execution to jump from a TRY block to the associated CATCH block or return error information from the CATCH block to the callers

It’s important to note that when developing new applications, a THROW statement is now preferable to RAISERROR for error handling. But more on that later.

Why Use RAISERROR for SQL Server Error Handling?

There are two primary reasons for choosing RAISERROR over SQL Server-generated error handling:

1. The RAISERROR messages are customizable with regard to level of severity and state
2. They can be written in natural language that is easy to understand

RAISERROR returns error messages to the application in the same format that is generated by SQL Server Database Engine. It allows developers to generate their own error messages, so anyone reading the message will be able to understand what the actual problem is instead of trying to decipher SQL Server’s technical error message. Developers can also set their own severity level, message ID, and state for error messages. 

Using RAISERROR with the TRY…CATCH Construct

TRY…CATCH is an error handling construct that lets you execute code in the TRY section and handle errors in the CATCH section. In general, TRY…CATCH is an effective way to identify many T-SQL errors, but there are a few exceptions. 

This tutorial provides a detailed walkthrough of how to use RAISERROR in conjunction with TRY…CATCH. The author uses an example showing how to use the RAISERROR inside a TRY block to cause execution to jump to the associated CATCH block. Inside the CATCH block, the author demonstrates how to use the RAISERROR to return the error information that invoked the CATCH block. The output displays the message ID, level of severity, and error state.

RAISERROR vs. THROW Error Handling Statements

RAISERROR was introduced in SQL Server 7.0 and has been an effective way to handle T-SQL errors for many years. But if you are developing new apps, Microsoft now recommends using THROW statements instead of RAISERROR. 

As organizations update to SQL Server 2012 and above, RAISERROR is being phased out. In fact, RAISERROR can’t be used in SQL Server 2014’s natively compiled Stored Procedures. THROW is considered an improvement over RAISERROR because it is easier to use. 

Microsoft’s SQL Server documentation breaks down the differences between the RAISERROR and THROW error handling statements as follows:

RAISERROR statement

• If a msg_id is passed to RAISERROR, the ID must be defined in sys.messages.
• The msg_str parameter can contain printf formatting styles.

The severity parameter specifies the severity of the exception.

THROW statement

• The error_number parameter does not have to be defined in sys.messages.
• The message parameter does not accept printf style formatting.
• There is no severity parameter. The exception severity is always set to 16.

Although RAISERROR’s days may be numbered, it remains a viable error handling option on older versions of SQL Server. Microsoft is pushing users of newer versions of SQL Server (SQL SERVER 2012 and above) to use the THROW statement instead of RAISERROR for implementing error handling. Microsoft hasn’t announced RAISERROR deprecation yet, but it seems likely that it will sooner rather than later.