Поделиться через

  • Статья

sp_addmessage (Transact-SQL)

Сохраняет новое пользовательское сообщение об ошибке в экземпляре компонента SQL Server Database Engine. Сообщения, сохраненные с помощью процедуры sp_addmessage, можно просмотреть с помощью представления каталога sys.messages.

Значок ссылки на разделСинтаксические обозначения в Transact-SQL

Синтаксис

sp_addmessage [ @msgnum= ] msg_id , [ @severity= ] severity , [ @msgtext= ] 'msg' 
     [ , [ @lang= ] 'language' ] 
     [ , [ @with_log= ] { 'TRUE' | 'FALSE' } ] 
     [ , [ @replace= ] 'replace' ]

Аргументы

  • [ @msgnum= ] msg_id
    Идентификатор сообщения. Аргумент msg_id имеет тип int и значение по умолчанию NULL. Для пользовательских сообщений аргумент msg_id может принимать целые значения в диапазоне от 50 001 до 2 147 483 647. Пара msg_id и language должна быть уникальной; в случае, если такой идентификатор уже задан для указанного языка, вызов вернет код ошибки.

  • [ @severity = ]severity
    Уровень серьезности ошибки. Аргумент severity имеет тип smallint и значение по умолчанию NULL. Допустимо значение уровня от 1 до 25. Дополнительные сведения о серьезности ошибок см. в разделе Степени серьезности ошибок компонента Database Engine.

  • [ @msgtext = ] 'msg'
    Текст сообщения об ошибке. Аргумент msg имеет тип nvarchar(255) и значение по умолчанию NULL.

  • [ @lang = ] 'language'
    Язык сообщения. Аргумент language имеет тип sysname и значение по умолчанию NULL. Поскольку на одном сервере могут быть установлены несколько языков, аргумент language определяет язык, на котором написано каждое сообщение. В том случае, если значение аргумента language не указано, используется язык по умолчанию для текущего сеанса.

  • [ @with_log = ] { 'TRUE' | 'FALSE' }
    Необходимо ли записывать данное сообщение в журнал приложений Windows. Аргумент @with_log имеет тип varchar(5) и значение по умолчанию FALSE. Если указано значение TRUE, сообщение об ошибке всегда записывается в журнал приложений Windows. Если указано значение FALSE, то сообщение об ошибке может попасть в журнал приложений Windows в зависимости от того, как эта ошибка возникла. Только члены предопределенной роли сервера sysadmin могут воспользоваться этим параметром.

    ПримечаниеПримечание

    Если сообщение заносится в журнал приложений Windows, оно также заносится и в журнал ошибок компонента Database Engine.

  • [ @replace = ] 'replace'
    Если указано строковое значение replace, то существующее сообщение об ошибке будет перезаписано с новым текстом и уровнем серьезности. Аргумент replace имеет тип varchar(7) и значение по умолчанию NULL. Этот аргумент должен быть указан, если уже существует сообщение с тем же аргументом msg_id. Если перезаписывается сообщение на языке «Английский (США)», то уровень серьезности будет переопределен для всех сообщений для всех языков с одинаковым значением аргумента msg_id.

Значения кодов возврата

0 (успешное завершение) или 1 (неуспешное завершение)

Результирующие наборы

Нет

Замечания

Для версий SQL Server на других языках версия сообщения на языке «Английский (США)» должна существовать перед добавлением сообщения на другом языке. Уровень серьезности двух разных версий одного сообщения должен совпадать.

При локализации сообщений, содержащих параметры, следует использовать номера параметров из исходного сообщения. После каждого номера параметра должен стоять восклицательный знак (!).

Исходное сообщение

Локализованное сообщение

'Параметр 1 оригинального сообщения: %s,

Параметр 2: %d»

'Параметр 1 оригинального сообщения: %1!,

Параметр 2: %2!'

В связи с различиями в синтаксисе языков номера параметров в локализованных сообщениях могут менять свой изначальный порядок.

Разрешения

Необходимо быть членом предопределенных ролей сервера sysadmin и serveradmin.

Примеры

А. Определение пользовательского сообщения

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

USE master
GO
EXEC sp_addmessage 50001, 16, 
   N'Percentage expects a value between 20 and 100. 
   Please reexecute with a more appropriate value.';
GO

Б. Добавление сообщения на двух языках

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

USE master;
GO
EXEC sp_addmessage @msgnum = 60000, @severity = 16, 
   @msgtext = N'The item named %s already exists in %s.', 
   @lang = 'us_english';

EXEC sp_addmessage @msgnum = 60000, @severity = 16, 
   @msgtext = N'L''élément nommé %1! existe déjà dans %2!', 
   @lang = 'French';
GO

В. Изменение порядка параметров

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

USE master;
GO

EXEC sp_addmessage 
    @msgnum = 60000, 
    @severity = 16,
    @msgtext = 
        N'This is a test message with one numeric
        parameter (%d), one string parameter (%s), 
        and another string parameter (%s).',
    @lang = 'us_english';

EXEC sp_addmessage 
    @msgnum = 60000, 
    @severity = 16,
    @msgtext = 
        -- In the localized version of the message,
        -- the parameter order has changed. The 
        -- string parameters are first and second
        -- place in the message, and the numeric 
        -- parameter is third place.
        N'Dies ist eine Testmeldung mit einem 
        Zeichenfolgenparameter (%3!),
        einem weiteren Zeichenfolgenparameter (%2!), 
        und einem numerischen Parameter (%1!).',
    @lang = 'German';
GO  

-- Changing the session language to use the U.S. English
-- version of the error message.
SET LANGUAGE us_english;
GO

RAISERROR(60000,1,1,15,'param1','param2') -- error, severity, state,
GO                                       -- parameters.

-- Changing the session language to use the German
-- version of the error message.
SET LANGUAGE German;
GO

RAISERROR(60000,1,1,15,'param1','param2') -- error, severity, state, 
GO                                       -- parameters.