RAISERROR(Transact-SQL)

적용 대상: Microsoft Fabric의 Microsoft Fabric SQL 데이터베이스에 있는 Microsoft Fabric Warehouse의 SQL Server Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System(PDW) SQL 분석 엔드포인트

참고 항목

문은 RAISERROR 존중 SET XACT_ABORT하지 않습니다. 새 애플리케이션은 RAISERROR 대신 THROW를 사용해야 합니다.

오류 메시지를 생성하고 세션에 대한 오류 처리를 시작합니다. RAISERROR는 sys.messages 카탈로그 뷰에 저장된 사용자 정의 메시지를 참조하거나 동적으로 메시지를 작성할 수 있습니다. 메시지는 호출하는 애플리케이션 또는 연결된 TRY...CATCH 구문의 CATCH 블록에 서버 오류 메시지로 반환됩니다. 새 애플리케이션에서는 THROW를 대신 사용해야 합니다.

Transact-SQL 구문 표기 규칙

구문

SQL Server, Azure SQL Database 및 Azure SQL Managed Instance용 구문:

RAISERROR ( { msg_id | msg_str | @local_variable }
    { , severity , state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

Azure Synapse Analytics 및 병렬 데이터 웨어하우스용 구문:

RAISERROR ( { msg_str | @local_variable }
    { , severity , state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

인수

msg_id

sp_addmessage를 사용하여 sys.messages 카탈로그 뷰에 저장되는 사용자 정의 오류 메시지 번호입니다. 사용자 정의 오류 메시지의 오류 번호는 .보다 50000커야 합니다. msg_id 지정 RAISERROR 되지 않으면 오류 번호50000가 있는 오류 메시지가 발생합니다.

msg_str

C 표준 라이브러리의 printf 함수와 유사한 형식을 가진 사용자 정의 메시지입니다. 오류 메시지는 최대 2,047자까지 지정할 수 있습니다. 메시지에 2,048자 이상의 문자가 포함된 경우 처음 2,044개만 표시됩니다. 메시지가 잘렸음을 나타내기 위해 줄임표가 추가됩니다. 대체 매개 변수는 내부 스토리지 동작으로 인해 출력에 표시되는 것보다 더 많은 문자를 사용합니다. 예를 들어 할당된 값 2 이 %d 있는 대체 매개 변수는 실제로 메시지 문자열에 하나의 문자를 생성하지만 내부적으로는 3개의 추가 스토리지 문자를 사용합니다. 이러한 스토리지 요구 사항 때문에 메시지 출력에 사용 가능한 문자 수가 감소됩니다.

msg_str 지정 RAISERROR 하면 오류 번호50000가 있는 오류 메시지가 발생합니다.

msg_str는 선택적으로 포함된 변환 사양을 가진 문자열입니다. 각각의 변환 사양은 인수 목록의 값이 msg_str의 각 변환 사양 위치에 어떤 형식으로 어떻게 배치되는지 정의합니다. 변환 사양의 형식은 다음과 같습니다.

% [[flag] [width] [. precision] [{h | l}]] type

msg_str에서 사용할 수 있는 매개 변수는 다음과 같습니다.

flag

대체 값의 공백 처리 및 맞춤을 결정하는 코드입니다.

코드	접두사 또는 맞춤	설명
- (빼기)	왼쪽 정렬	지정한 필드 너비 내에서 인수 값을 왼쪽으로 정렬합니다.
+ (더하기)	부호 접두사	값이 부호 있는 형식인 경우 인수 값 앞에 더하기(+) 또는 빼기(-)가 있습니다.
0 (0)	0 패딩	최소 너비에 도달할 때까지 출력 앞에 0을 붙입니다. 빼기 기호(-)가 표시되는 0 경우 0 무시됩니다.
# (number)	0x 16진수 형식 x 의 접두사 또는 X	숫자 X x기호(#) 플래그는 o0이 아닌 값 앞에 각각 또는 0이 아닌 값을 0X00x사용합니다. iu 숫자 기호(#) 플래그가 앞에 표시되거나 앞에 표시되면 d플래그가 무시됩니다.
' ' (공백)	공간 채움	부호 있는 양수일 경우 출력 값 앞에 공백을 붙입니다. 더하기 기호(+) 플래그에 포함된 경우 이 패딩은 무시됩니다.

width

인수 값이 배치될 필드의 최소 너비를 정의하는 정수입니다. 인수 값의 길이가 width와 같거나 길면 값은 패딩 없이 출력됩니다. 값이 width보다 짧으면 값은 width에 지정된 길이로 패딩됩니다.

별표(*)는 인수 목록의 연결된 인수에 의해 너비가 지정됨을 의미하며 정수 값이어야 합니다.

전체 자릿수

문자열 값의 경우 인수 값에서 가져온 문자의 최대 개수입니다. 예를 들어 문자열에 5개의 문자가 있고 precision이 3이면 문자열 값의 처음 3개 문자만 사용됩니다.

정수 값의 경우 precision은 출력되는 최소 자릿수입니다.

별표(*)는 정수 값이어야 하는 인수 목록의 연결된 인수에 의해 전체 자릿수가 지정됨을 의미합니다.

{h | l} 형식

문자 형식, ,i, o, xsX또는 u문자 형식d과 함께 사용되며 shortint(h) 또는 longint(l) 값을 만듭니다.

형식 사양	나타내는 대상
d 또는 i	부호 있는 정수
o	부호 없는 8진수
s	문자열
u	부호 없는 정수
x 또는 X	부호 없는 16진수

이 형식 사양들은 원래 C 표준 라이브러리의 printf 함수용으로 정의된 것들을 기반으로 합니다. RAISERROR 메시지 문자열에 사용된 형식 사양들은 Transact-SQL 데이터 형식으로 매핑되고 printf에서 사용된 사양들은 C 언어 데이터 형식에 매핑됩니다. Transact-SQL에 printf 연결된 C 데이터 형식과 유사한 데이터 형식이 없는 경우 사용되는 형식 사양은 지원 RAISERROR 되지 않습니다. 예를 들어 %p Transact-SQL에는 포인터 데이터 형식이 없으므로 포인터 사양이 지원 RAISERROR 되지 않습니다.

값을 Transact-SQL bigint 데이터 형식 %I64d으로 변환하려면 .

@local_variable

msg_str 같은 방식으로 형식이 지정된 문자열을 포함하는 유효한 문자 데이터 형식의 변수입니다. local_variable은 char 또는 varchar이거나 암시적으로 이러한 데이터 형식으로 변환될 수 있어야 합니다.

severity

이 메시지에 연결된 사용자 정의 심각도 수준입니다. sp_addmessage를 사용하여 만든 사용자 정의 메시지를 발생시키기 위해 msg_id를 사용할 경우 RAISERROR에 지정된 심각도가 sp_addmessage에 지정된 심각도보다 우선합니다.

19에서 25 WITH LOG 까지의 심각도 수준의 경우 옵션이 필요합니다. 심각도 수준이 로 해석되는 것보다 0 작습니다 0. 25보다 작은 심각도 수준은 25로 해석됩니다.

주의

20부터 25까지의 심각도는 치명적인 심각도입니다. 치명적인 심각도가 발생하면 메시지를 받은 다음 클라이언트 연결이 종료되고 오류 및 애플리케이션 로그에 오류가 기록됩니다.

다음 예제와 같이 오류와 연결된 심각도 값을 반환하도록 지정할 -1 수 있습니다.

RAISERROR (15600, -1, -1, 'mysp_CreateCustomer');

결과 집합은 다음과 같습니다.

Msg 15600, Level 15, State 1, Line 1
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

상태

0에서 255 사이의 정수입니다. 음수 값은 기본적으로 1입니다. 255보다 큰 값은 사용하면 안 됩니다.

여러 위치에서 동일한 사용자 정의 오류가 발생하는 경우 각 위치의 고유 상태 번호를 사용하면 코드의 어떤 부분에서 오류가 발생하는지 찾는 데 도움이 됩니다.

argument

msg_str에서 정의된 변수의 대체에 사용되는 매개 변수 또는 msg_id에 해당하는 메시지입니다. 대체 매개 변수가 0개 이상 있을 수 있지만 대체 매개 변수의 총 수는 20을 초과할 수 없습니다. 각 대체 매개 변수는 지역 변수이거나 tinyint, smallint, int, char, varchar, nchar, nvarchar, binary 또는 varbinary의 데이터 형식 중 하나일 수 있습니다. 다른 데이터 형식은 지원되지 않습니다.

옵션

오류에 대한 사용자 지정 옵션이며 다음 값 중 하나일 수 있습니다.

값	설명
LOG	오류 로그 및 SQL Server 데이터베이스 엔진 인스턴스의 애플리케이션 로그에 오류를 기록합니다. 오류 로그에 기록되는 오류는 현재 최대 440바이트로 제한됩니다. sysadmin 고정 서버 역할의 멤버 또는 권한이 있는 ALTER TRACE 사용자만 지정할 WITH LOG수 있습니다. 적용 대상: SQL Server
NOWAIT	즉시 클라이언트에게 메시지를 전송합니다. 적용 대상: SQL Server, Azure SQL 데이터베이스, Azure SQL Managed Instance
SETERROR	심각도에 상관없이 @@ERROR 및 ERROR_NUMBER 값을 msg_id나 50000으로 설정합니다. 적용 대상: SQL Server, Azure SQL 데이터베이스, Azure SQL Managed Instance

설명

RAISERROR에 의해 생성된 오류는 데이터베이스 엔진 코드에 의해 생성된 오류와 동일하게 동작합니다. RAISERROR에 의해 지정된 값은 ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE 및 @@ERROR 시스템 함수에 의해 보고됩니다. RAISERROR 블록에서 심각도가 11 이상인 TRY 경우 컨트롤을 연결된 CATCH 블록으로 전송합니다. RAISERROR가 다음과 같이 실행되면 호출자에게 오류가 반환됩니다.

• TRY 블록 외부에서 실행된 경우
• TRY 블록의 심각도가 10 이하인 경우
• 데이터베이스 연결이 종료되는 20 이상의 심각도인 경우

CATCH 블록은 ERROR_NUMBER 및 ERROR_MESSAGE와 같은 시스템 함수를 사용하여 원래 오류의 정보를 얻는 방식으로 RAISERROR를 사용하여 CATCH 블록을 호출한 오류를 다시 throw합니다. @@ERROR 는 심각도가 1에서 10인 메시지에 대해 기본적으로 설정 0 됩니다.

msg_id 카탈로그 뷰에서 sys.messages 사용할 수 있는 사용자 정의 메시지를 지정하는 경우 msg_str RAISERROR 사용하여 지정된 사용자 정의 메시지의 텍스트에 적용되는 것과 동일한 규칙을 사용하여 텍스트 열의 메시지를 처리합니다. 사용자 정의 메시지 텍스트는 변환 사양을 포함할 수 있으며 RAISERROR 인수 값을 변환 사양에 매핑합니다. sp_addmessage를 사용하여 사용자 정의 오류 메시지를 추가하고 sp_dropmessage를 사용하여 사용자 정의 오류 메시지를 삭제하세요.

RAISERROR 는 호출 애플리케이션에 메시지를 반환하는 PRINT 대신 사용할 수 있습니다. RAISERROR 는 C 표준 라이브러리의 printf 함수 기능과 유사한 문자 대체를 지원하지만 Transact-SQL PRINT 문은 지원하지 않습니다. 이 문은 PRINT 블록의 영향을 TRY 받지 않지만 TRY 블록 RAISERROR 에서 심각도가 11에서 19인 실행은 연결된 CATCH 블록으로 제어를 전송합니다. CATCH 블록을 호출하지 않고 TRY 블록의 메시지를 반환하려면 RAISERROR에서 심각도를 10 이하로 지정하세요.

일반적으로 연속적인 인수는 첫 번째 인수가 첫 번째 변환 사양을, 두 번째 인수가 두 번째 변환 사양을 대체하는 식으로 연속적인 변환 사양을 대체합니다. 예를 들어 다음 RAISERROR 문에서 첫 번째 인수인 N'number'는 첫 번째 변환 사양인 %s를 대체하고 두 번째 인수인 5는 두 번째 변환 사양인 %d.를 대체합니다.

RAISERROR (N'This is message %s %d.', -- Message text.
    10, -- Severity,
    1, -- State,
    N'number', -- First argument.
    5); -- Second argument.
-- The message text returned is: This is message number 5.
GO

변환 사양의 width 또는 precision으로 별표(*)를 지정하면 너비나 전체 자릿수로 사용될 값은 정수 인수 값으로 지정됩니다. 이 경우 한 개의 변환 사양은 최대 3개의 인수(각각 너비, 전체 자릿수 및 대체 값)를 사용할 수 있습니다.

예를 들어 다음 RAISERROR 문은 모두 동일한 문자열을 반환합니다. 첫 번째 경우는 인수 목록에서 너비와 전체 자릿수를 지정하며 두 번째 경우는 변환 사양에서 이를 지정합니다.

RAISERROR (N'<\<%*.*s>>', -- Message text.
    10, -- Severity,
    1, -- State,
    7, -- First argument used for width.
    3, -- Second argument used for precision.
    N'abcde'); -- Third argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
RAISERROR (N'<\<%7.3s>>', -- Message text.
    10, -- Severity,
    1, -- State,
    N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

사용 권한

모든 사용자는 0에서 18까지의 심각도 수준을 지정할 수 있습니다. 19에서 25까지의 심각도 수준은 sysadmin 고정 서버 역할의 멤버 또는 사용 권한이 있는 ALTER TRACE 사용자만 지정할 수 있습니다.

예제

A. CATCH 블록에서 오류 정보 반환

다음 코드 예제에서는 RAISERROR 블록 내의 TRY를 사용하여 관련 CATCH 블록으로 실행을 이동하는 방법을 보여 줍니다. 또한 RAISERROR 블록을 호출한 오류에 관한 정보를 반환하는 방법을 CATCH을 사용하여 보여 줍니다.

참고

RAISERROR는 1에서 127까지 상태의 오류만 생성합니다. 데이터베이스 엔진 상태 0에서 오류가 발생할 수 있으므로 ERROR_STATE 반환된 오류 상태를 확인한 후 해당 상태 매개 변수RAISERROR에 값으로 전달하는 것이 좋습니다.

BEGIN TRY
    -- RAISERROR with severity 11-19 will cause execution to
    -- jump to the CATCH block.
    RAISERROR ('Error raised in TRY block.', -- Message text.
        16, -- Severity.
        1 -- State.
    );
END TRY
BEGIN CATCH
    DECLARE @ErrorMessage NVARCHAR(4000);
    DECLARE @ErrorSeverity INT;
    DECLARE @ErrorState INT;

    SELECT
        @ErrorMessage = ERROR_MESSAGE(),
        @ErrorSeverity = ERROR_SEVERITY(),
        @ErrorState = ERROR_STATE();

    -- Use RAISERROR inside the CATCH block to return error
    -- information about the original error that caused
    -- execution to jump to the CATCH block.
    RAISERROR (@ErrorMessage, -- Message text.
        @ErrorSeverity, -- Severity.
        @ErrorState -- State.
    );
END CATCH;

B. sys.messages에서 임시 메시지 만들기

다음 예제에서는 카탈로그 뷰에 sys.messages 저장된 메시지를 발생 하는 방법을 보여 있습니다. 시스템 저장 프로시저를 sys.messages 메시지 번호50005로 사용하여 sp_addmessage 카탈로그 뷰에 메시지를 추가했습니다.

EXEC sp_addmessage @msgnum = 50005,
    @severity = 10,
    @msgtext = N'<\<%7.3s>>';
GO
RAISERROR (50005, -- Message ID.
    10, -- Severity,
    1, -- State,
    N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
EXEC sp_dropmessage @msgnum = 50005;
GO

C. 지역 변수를 사용하여 메시지 텍스트 제공

다음 코드 예제에서는 지역 변수를 사용하여 RAISERROR 문에 메시지 텍스트를 제공하는 방법을 보여 줍니다.

DECLARE @StringVariable NVARCHAR(50);
SET @StringVariable = N'<\<%7.3s>>';

RAISERROR (@StringVariable, -- Message text.
    10, -- Severity,
    1, -- State,
    N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

관련 콘텐츠

• SQL 데이터베이스 함수란?
• DECLARE @local_variable (Transact-SQL)
• PRINT(Transact-SQL)
• sp_addmessage(Transact-SQL)
• sp_dropmessage(Transact-SQL)
• sys.messages(Transact-SQL)
• xp_logevent(Transact-SQL)
• @@ERROR(Transact-SQL)
• ERROR_LINE(Transact-SQL)
• ERROR_MESSAGE(Transact-SQL)
• ERROR_NUMBER(Transact-SQL)
• ERROR_PROCEDURE(Transact-SQL)
• ERROR_SEVERITY(Transact-SQL)
• ERROR_STATE(Transact-SQL)
• TRY...CATCH(Transact-SQL)