RAISERROR (Transact-SQL)

Platí pro:SQL ServerAzure SQL DatabaseSpravovaná instance Azure SQLAzure Synapse AnalyticsAnalytics Platform System (PDW)Koncový bod analýzy SQL v Microsoft FabricSklad v Microsoft FabricDatabáze SQL v Microsoft Fabric

Note

Prohlášení RAISERROR nepoctí SET XACT_ABORT. Nové aplikace by měly používat THROW místo RAISERROR.

Vygeneruje chybovou zprávu a zahájí zpracování chyb pro relaci. RAISERROR může odkazovat na uživatelem definovanou zprávu uloženou sys.messages v zobrazení katalogu nebo dynamicky vytvořit zprávu. Tato zpráva se vrátí jako chybová zpráva serveru volající aplikaci nebo přidruženému CATCH bloku konstruktoru TRY...CATCH . Místo toho by nové aplikace měly používat funkci THROW .

Transact-SQL konvence syntaxe

Syntax

Syntaxe PRO SQL Server, Azure SQL Database a Azure SQL Managed Instance:

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

Syntaxe pro Azure Synapse Analytics a paralelní datový sklad:

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

Arguments

msg_id

Uživatelem definované číslo chybové zprávy uložené v sys.messages zobrazení katalogu pomocí sp_addmessage. Chybová čísla pro chybové zprávy definované uživatelem by měla být větší než 50000. Pokud není zadán msg_id , RAISERROR vyvolá chybovou zprávu s číslem 50000chyby .

Note

Ve službě Azure SQL Database a Azure SQL Managed Instance se nepodporuje, sp_addmessage takže nemůžete odkazovat na msg_id větší než 50000.

msg_str

Uživatelem definovaná zpráva s formátováním, které printf je podobné funkci ve standardní knihovně jazyka C. Chybová zpráva může mít maximálně 2 047 znaků. Pokud zpráva obsahuje 2 048 nebo více znaků, zobrazí se pouze prvních 2 044; Přidá se tři tečky, které značí, že je zpráva zkrácena. Parametry nahrazení spotřebovávají více znaků, než ukazuje výstup z důvodu interního chování úložiště. Například parametr %d nahrazení s přiřazenou hodnotou 2 ve skutečnosti vytvoří jeden znak v řetězci zprávy, ale také interně zabírá tři nadbytečné znaky úložiště. Tento požadavek na úložiště snižuje počet dostupných znaků pro výstup zprávy.

Při zadání msg_strRAISERROR vyvolá chybovou zprávu s číslem 50000chyby .

msg_str je řetězec znaků s volitelnými vloženými specifikacemi převodu. Každá specifikace převodu definuje, jak je hodnota v seznamu argumentů formátována a umístěna do pole v umístění specifikace převodu v msg_str. Specifikace převodu mají tento formát:

% [vlajka] [šířka] [. přesnost] [{h | l}]] typ

Parametry, které lze použít v msg_str , jsou:

vlajka

Kód, který určuje mezery a odůvodnění nahrazené hodnoty.

Code	Předpona nebo odůvodnění	Description
- (minus)	Levicově orientované	Doleva zarovnat hodnotu argumentu v dané šířce pole.
+ (plus)	Předpona znaku	Před hodnotou argumentu zadejte znaménko plus (+) nebo minus (-), pokud je hodnota typu se znaménkem.
0 (nula)	Nulové polstrování	Před výstupem se zobrazí nuly, dokud nedosáhnete minimální šířky. Když 0 se zobrazí - znaménko minus (0), bude ignorováno.
# (číslo)	0x předpona šestnáctkového x typu nebo X	Pokud se používá s znakem o, xnebo X formátem, značka čísla (#) označuje jakoukoli nenulovou hodnotu s 0, 0xnebo 0X, v uvedeném pořadí. Je-li dpříznakem iu čísla (#) označen příznakem , je příznak ignorován.
' ' (prázdné)	Vycpávání prostoru	Před výstupní hodnotu zadejte prázdné mezery, pokud je hodnota podepsaná a kladná. Toto odsazení se ignoruje, pokud je součástí příznaku plus (+).

width

Celé číslo, které definuje minimální šířku pole, do kterého je hodnota argumentu umístěna. Pokud je délka hodnoty argumentu rovna nebo delší než šířka, vytiskne se hodnota bez odsazení. Pokud je hodnota kratší než šířka, hodnota se zarovná na délku zadanou v šířce.

Hvězdička (*) znamená, že šířka je určena přidruženým argumentem v seznamu argumentů, což musí být celočíselná hodnota.

přesnost

Maximální počet znaků převzatých z hodnoty argumentu pro řetězcové hodnoty. Pokud má například řetězec pět znaků a přesnost je 3, použijí se pouze první tři znaky řetězcové hodnoty.

Pro celočíselné hodnoty je přesnost minimálním počtem číslic vytištěných.

Hvězdička (*) znamená, že přesnost je určena přidruženým argumentem v seznamu argumentů, což musí být celočíselná hodnota.

{h | l} typ

Používá se s typy dznaků , , i, osxXnebo u, a vytvoří krátké (h) nebo dlouhé (l) hodnoty.

Specifikace typu	Represents
d nebo i	Podepsané celé číslo
o	Nepodepsáný oktal
s	String
u	Celé číslo bez znaménka
x nebo X	Bezznameční hexadecimální

Tyto specifikace typu jsou založeny na specifikacích, které byly původně definovány pro printf funkci ve standardní knihovně jazyka C. Specifikace typů používané v RAISERROR řetězcích zpráv se mapují na Transact-SQL datových typů, zatímco specifikace použité v printf mapě na datové typy jazyka C. Specifikace typů používané v printf aplikaci nejsou podporovány RAISERROR , pokud Transact-SQL nemá datový typ podobný přidruženému datovému typu C. Například specifikace ukazatelů není podporována%p, RAISERROR protože Transact-SQL nemá datový typ ukazatele.

Chcete-li převést hodnotu na datový typ Transact-SQL bigint , zadejte %I64d.

@local_variable

Proměnná libovolného platného datového typu znaku, který obsahuje řetězec formátovaný stejným způsobem jako msg_str. @local_variable musí být znak nebo varchar nebo musí být možné implicitně převést na tyto datové typy.

severity

Úroveň závažnosti definovaná uživatelem přidružená k této zprávě. Při použití msg_id k vyvolání uživatelem definované zprávy vytvořené pomocí sp_addmessage, závažnost zadaná při RAISERROR přepsání závažnosti zadané v sp_addmessage.

U úrovní závažnosti od 19 do 25 je tato WITH LOG možnost povinná. Úrovně závažnosti menší, než 0 jsou interpretovány jako 0. Úrovně závažnosti větší než 25 jsou interpretovány jako 25.

Caution

Úrovně závažnosti od 20 do 25 jsou považovány za závažné. Pokud je zjištěna závažná úroveň závažnosti, připojení klienta se po přijetí zprávy ukončí a chyba se zaprotokoluje v protokolech chyb a aplikací.

Můžete zadat -1 , aby se vrátila hodnota závažnosti přidružená k chybě, jak je znázorněno v následujícím příkladu.

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

Tady je soubor výsledků.

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

state

Celé číslo od 0 do 255. Záporné hodnoty mají výchozí hodnotu 1. Hodnoty větší než 255 by se neměly používat.

Pokud je stejná uživatelsky definovaná chyba vyvolána na více místech, může použití jedinečného čísla stavu pro každé umístění pomoct zjistit, která část kódu vyvolává chyby.

argument

Parametry použité v nahrazení proměnných definovaných v msg_str nebo zprávě odpovídající msg_id. Může existovat nulový nebo více parametrů nahrazení, ale celkový počet parametrů nahrazení nesmí překročit 20. Každý parametr nahrazení může být místní proměnná nebo jakýkoli z těchto datových typů: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary nebo varbinary. Nejsou podporovány žádné jiné datové typy.

option

Vlastní možnost chyby a může být jednou z hodnot v následující tabulce.

Value	Description
LOG	Zaznamená chybu v protokolu chyb a protokolu aplikace pro instanci databázového stroje SQL Serveru. Chyby protokolované v protokolu chyb jsou aktuálně omezeny na maximálně 440 bajtů. Může zadat pouze člen pevné role serveru ALTER TRACE nebo uživatel s oprávněními WITH LOG . platí pro: SQL Server
NOWAIT	Odešle zprávy okamžitě klientovi. platí pro: SQL Server, Azure SQL Database a Azure SQL Managed Instance
SETERROR	@@ERROR Nastaví hodnoty na ERROR_NUMBERmsg_id nebo 50000 bez ohledu na úroveň závažnosti. platí pro: SQL Server, Azure SQL Database a Azure SQL Managed Instance

Remarks

Chyby vygenerované provozem RAISERROR fungují stejně jako chyby vygenerované kódem databázového stroje. Hodnoty zadané RAISERROR funkcí , , ERROR_LINEERROR_MESSAGEERROR_NUMBERERROR_PROCEDUREERROR_SEVERITY, a ERROR_STATE systémových funkcí.@@ERROR Při RAISERROR spuštění se závažností 11 nebo vyšší v TRY bloku přenese řízení do přidruženého CATCH bloku. Chyba se vrátí volajícímu, pokud RAISERROR je spuštěna:

• Mimo rozsah jakéhokoli TRY bloku.
• Závažnost 10 nebo nižší v TRY bloku.
• Se závažností 20 nebo vyšší, která ukončí připojení k databázi.

CATCH bloky mohou použít RAISERROR k opětovnému rozšíření chyby, která vyvolala CATCH blok pomocí systémových funkcí, jako ERROR_NUMBER jsou a ERROR_MESSAGE načtení původních informací o chybě. @@ERROR je ve výchozím nastavení nastavena 0 pro zprávy se závažností od 1 do 10.

Pokud msg_id určuje uživatelem definovanou zprávu dostupnou sys.messages ze zobrazení katalogu, RAISERROR zpracuje zprávu z textového sloupce pomocí stejných pravidel, která se použijí na text zprávy definované uživatelem zadaný pomocí msg_str. Text zprávy definovaný uživatelem může obsahovat specifikace převodu a RAISERROR mapuje hodnoty argumentů na specifikace převodu. Slouží sp_addmessage k přidání uživatelem definovaných chybových zpráv a sp_dropmessage k odstranění chybových zpráv definovaných uživatelem.

RAISERROR lze použít jako alternativu k PRINT vrácení zpráv do volajících aplikací. RAISERROR podporuje nahrazení znaků podobné funkci printf ve standardní knihovně jazyka C, zatímco příkaz Transact-SQL PRINT ne. Příkaz PRINT není ovlivněn TRY bloky, zatímco RAISERROR spuštění se závažností 11 až 19 v bloku TRY přenese řízení do přidruženého CATCH bloku. Zadejte závažnost 10 nebo nižší, která se má použít RAISERROR k vrácení zprávy z TRY bloku bez vyvolání CATCH bloku.

Následující argumenty obvykle nahrazují po sobě jdoucí specifikace převodu; První argument nahradí první specifikaci převodu, druhý argument nahradí druhou specifikaci převodu atd. Například v následujícím RAISERROR příkazu první argument N'number' nahradí první specifikaci převodu ; %sa druhý argument nahradí druhou specifikaci převodu 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

Pokud je zadána hvězdička (*) pro šířku nebo přesnost specifikace převodu, hodnota, která se má použít pro šířku nebo přesnost, je zadána jako celočíselná hodnota argumentu. V tomto případě může jedna specifikace převodu použít až tři argumenty, jeden pro šířku, přesnost a hodnotu nahrazení.

Například oba následující RAISERROR příkazy vrátí stejný řetězec. Jedna určuje hodnoty šířky a přesnosti v seznamu argumentů; ostatní je specifikují ve specifikaci převodu.

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

Permissions

Každý uživatel může zadat úroveň závažnosti od 0 do 18. Úrovně závažnosti od 19 do 25 lze určit pouze členy pevné role serveru správce systému nebo uživatele s oprávněními ALTER TRACE .

Examples

A. Vrácení informací o chybě z bloku CATCH

Následující příklad kódu ukazuje, jak použít RAISERROR uvnitř TRY bloku k tomu, aby provádění přeskočí na přidružený CATCH blok. Také ukazuje, jak použít RAISERROR k vrácení informací o chybě, která vyvolala CATCH blok.

Note

RAISERROR Generuje pouze chyby se stavem od 1 do 127. Vzhledem k tomu, že databázový stroj může vyvolat chyby se stavem 0, doporučujeme před předáním jako hodnoty parametru RAISERRORstavu zkontrolovat stav vrácený ERROR_STATE.

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. Vytvoření ad hoc zprávy v sys.messages

Následující příklad ukazuje, jak vyvolat zprávu uloženou sys.messages v zobrazení katalogu. Zpráva byla přidána do sys.messages zobrazení katalogu pomocí sp_addmessage systémové uložené procedury jako číslo 50005zprávy .

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. Použití místní proměnné k zadání textu zprávy

Následující příklad kódu ukazuje, jak použít místní proměnnou k zadání textu zprávy pro RAISERROR příkaz.

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

Související obsah

• Jaké jsou funkce databáze SQL?
• DECLARE @local_variable (Transact-SQL)
• TISK (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)
• VYZKOUŠET... ZACHYTIT (Transact-SQL)