Megosztás a következőn keresztül:

RAISERROR (Transact-SQL)

A következőkre vonatkozik:SQL ServerAzure SQL DatabaseFelügyelt Azure SQL-példányAzure Synapse AnalyticsElemzési platformrendszer (PDW)SQL Analytics-végpont a Microsoft FabricbenRaktár a Microsoft FabricbenSQL-adatbázis a Microsoft Fabricben

Note

Az RAISERROR utasítás nem tiszteli SET XACT_ABORT. AhelyettTHROW, hogy új alkalmazásokat használnálRAISERROR.

Hibaüzenetet hoz létre, és hibafeldolgozást kezdeményez a munkamenethez. RAISERROR hivatkozhat a katalógus nézetben tárolt felhasználó által definiált sys.messages üzenetekre, vagy dinamikusan hozhat létre üzenetet. Az üzenet kiszolgálói hibaüzenetként jelenik meg a hívó alkalmazásnak vagy egy CATCH szerkezet társított TRY...CATCH blokkjának. Az új alkalmazásoknak inkább a THROW-t kell használniuk.

Transact-SQL szintaxis konvenciók

Syntax

Szintaxis az SQL Serverhez, az Azure SQL Database-hez és a felügyelt Azure SQL-példányhoz:

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

Az Azure Synapse Analytics és a párhuzamos adattárház szintaxisa:

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

Arguments

msg_id

Felhasználó által definiált hibaüzenet, amely a sys.messages katalógusnézetben sp_addmessage használatával van tárolva. A felhasználó által definiált hibaüzenetek hibaszámainak nagyobbnak kell lenniük, mint 50000a . Ha a msg_id nincs megadva, RAISERROR hibaüzenet jelenik meg a következő hibaszámmal 50000: .

Note

Az Azure SQL Database-ben és a felügyelt Azure SQL-példányon sp_addmessage nem támogatott, ezért nem hivatkozhat nagyobb msg_id50000.

msg_str

Felhasználó által definiált üzenet a C standard kódtárban lévő függvényhez printf hasonló formázással. A hibaüzenet legfeljebb 2047 karakter hosszúságú lehet. Ha az üzenet 2048 vagy több karaktert tartalmaz, csak az első 2044 jelenik meg; egy három pontot ad hozzá, amely azt jelzi, hogy az üzenet csonkolt. A helyettesítési paraméterek a belső tárolási viselkedés miatt több karaktert használnak, mint amennyit a kimenet mutat. Például a hozzárendelt értékkel rendelkező helyettesítési %d2 paraméter valójában egy karaktert hoz létre az üzenetsztringben, de belsőleg három további karaktert is felvesz. Ez a tárolási követelmény csökkenti az üzenetkimenethez elérhető karakterek számát.

Ha msg_str van megadva, RAISERROR egy hibaüzenet jelenik meg, amelynek hibaszáma a következő 50000:

msg_str egy karaktersorozat, amely opcionális beágyazott konverziós specifikációkkal rendelkezik. Minden konverziós specifikáció meghatározza, hogy az argumentumlistában szereplő értékek hogyan formázhatók és helyezhetők egy mezőbe az msg_str konverziós specifikációjának helyén. A konvertálási specifikációk formátuma a következő:

% [[zászló] [szélesség] [. pontosság] [{h | l}]] típus

A msg_str használható paraméterek a következők:

zászló

A helyettesítő érték térközét és indoklását meghatározó kód.

Code Előtag vagy indoklás Description
- (mínusz) Balra igazított Az argumentumérték balra igazítása a megadott mezőszélességen belül.
+ (plusz) Jelelőtag Az argumentumérték előtagja plusz (+) vagy mínusz (-), ha az érték aláírt típusú.
0 (nulla) Nulla párnázás Adja meg a kimenetet nullákkal, amíg el nem éri a minimális szélességet. Amikor 0 és a mínuszjel (-) megjelenik, 0 a rendszer figyelmen kívül hagyja.
# (szám) 0xhexadecimális vagy xX Ha a oszámjel () jelölő a , xvagy X formátum használatával van használva, a számjel (#) jelölő minden nem nulla értéket 0előtagként a , 0xvagy 0X, értékkel előtaggal jelöl. Amikor da iszámjel (u) jelölő előtagja, vagy # előtagja van, a rendszer figyelmen kívül hagyja a jelölőt.
' ' (üres) Tér párnázás A kimeneti érték előtagja üres szóközökkel, ha az érték aláírt és pozitív. Ezt a kitöltést a rendszer figyelmen kívül hagyja, ha a pluszjel (+) jelző szerepel benne.

width

Egész szám, amely meghatározza annak a mezőnek a minimális szélességét, amelybe az argumentumérték kerül. Ha az argumentum értéke egyenlő vagy hosszabb, mint a szélesség, az érték kitöltés nélkül lesz kinyomtatva. Ha az érték rövidebb, mint a szélesség, az érték a szélességben megadott hosszúságra van kipárnázva.

A csillag (*) azt jelenti, hogy a szélességet az argumentumlistában szereplő társított argumentum határozza meg, amelynek egész számnak kell lennie.

precizitás

A sztringértékek argumentumértékéből vett karakterek maximális száma. Ha például egy sztring öt karakterből áll, és a pontosság 3, akkor csak a sztringérték első három karakterét használja a rendszer.

Egész számértékek esetén a pontosság a kinyomtatott számjegyek minimális száma.

A csillag (*) azt jelenti, hogy a pontosságot az argumentumlistában szereplő társított argumentum határozza meg, amelynek egész számnak kell lennie.

{h | l} típus

Karaktertípusokkald, i, , os, x, Xuvagy , és rövid (h) vagy hosszú (l) értékeket hoz létre.

Típusspecifikáció Represents
d vagy i Aláírt egész szám
o Jel nélküli nyolcpont
s String
u Aláíratlan egész szám
x vagy X Ábrázolás nélküli hexadecimális

Ezek a típusspecifikációk a C standard kódtárban lévő függvényhez printf eredetileg meghatározottakon alapulnak. Az üzenetsztringekben használt RAISERROR típusspecifikációk Transact-SQL adattípusokra, míg a C nyelvre való leképezésben printf használt specifikációk. A használt printf típusspecifikációkat nem támogatja RAISERROR , ha Transact-SQL nem rendelkezik a társított C adattípushoz hasonló adattípussal. A mutatók specifikációja például nem támogatott%p, RAISERROR mert Transact-SQL nem rendelkezik mutató adattípussal.

Ha egy értéket Transact-SQL bigint adattípusra szeretne konvertálni, adja meg %I64d.

@local_variable

Bármely érvényes karakter adattípusú változó, amely a msg_str-hez hasonlóan formázott sztringet tartalmaz. @local_variablekarakternek vagy varcharnak kell lennie, vagy implicit módon konvertálhatónak kell lennie ezekre az adattípusokra.

severity

Az üzenethez társított felhasználó által megadott súlyossági szint . Ha a msg_id használatával hoz létre felhasználó által definiált sp_addmessageüzenetet, a megadott súlyosság RAISERROR felülbírálja a megadott sp_addmessagesúlyosságot.

A 19 és 25 közötti súlyossági szintekhez a WITH LOG beállítás szükséges. A súlyossági szintek kisebbek, mint 0 a .0 A 25-nél nagyobb súlyossági szinteket a rendszer 25-ként értelmezi.

Caution

A súlyossági szintek 20 és 25 között végzetesnek minősülnek. Súlyossági szint esetén az ügyfélkapcsolat az üzenet fogadása után megszakad, a hiba és az alkalmazásnaplók pedig naplózva lesznek.

Megadhatja -1 , hogy a hibához tartozó súlyossági értéket adja vissza, ahogy az az alábbi példában is látható.

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

Itt van az eredmények összessége.

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

state

0 és 255 közötti egész szám. A negatív értékek alapértelmezett értéke 1. A 255-nél nagyobb értékeket nem szabad használni.

Ha ugyanazt a felhasználó által megadott hibát több helyen is észleli, az egyes helyek egyedi állapotszámával megtalálhatja, hogy a kód melyik szakasza növeli a hibákat.

argument

A msg_str definiált változók helyettesítéséhez használt paraméterek vagy a msg_id megfelelő üzenet. Nulla vagy több helyettesítési paraméter is lehet, de a helyettesítési paraméterek teljes száma nem haladhatja meg a 20-t. Minden helyettesítési paraméter lehet helyi változó, vagy bármelyik ilyen adattípus: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary vagy varbinary. Más adattípusok nem támogatottak.

option

A hiba egyéni lehetősége, amely az alábbi táblázatban szereplő értékek egyike lehet.

Value Description
LOG Naplózza a hibát a hibanaplóban és az SQL Server-adatbázismotor példányának alkalmazásnaplójában. A hibanaplóban naplózott hibák száma jelenleg legfeljebb 440 bájt lehet. Csak a sysadmin rögzített kiszolgálói szerepkör tagja vagy engedélyekkel rendelkező ALTER TRACE felhasználó adhat meg.WITH LOG

A következőkre vonatkozik: SQL Server
NOWAIT Azonnal üzeneteket küld az ügyfélnek.

A következőkre vonatkozik: SQL Server, Azure SQL-adatbázis és Azure SQL Felügyelt Példány
SETERROR A súlyossági szinttől függetlenül @@ERRORERROR_NUMBER vagy 50000 értékre állítja az értékeket.

A következőkre vonatkozik: SQL Server, Azure SQL-adatbázis és Azure SQL Felügyelt Példány

Remarks

A létrehozott RAISERROR hibák ugyanúgy működnek, mint az adatbázismotor kódja által generált hibák. A megadott értékeket a rendszerfüggvények RAISERRORERROR_LINEERROR_MESSAGEERROR_NUMBERERROR_PROCEDUREERROR_SEVERITYjelentik.ERROR_STATE@@ERROR Ha RAISERROR egy blokkban TRY 11 vagy annál nagyobb súlyosságú futtatás történik, a vezérlőt a társított CATCH blokkba továbbítja. A rendszer visszaadja a hibát a hívónak, ha RAISERROR fut:

  • Bármely TRY blokk hatókörén kívül.
  • Egy blokkban 10 vagy annál kisebb TRY súlyossággal.
  • 20 vagy annál nagyobb súlyossággal, amely megszakítja az adatbázis-kapcsolatot.

CATCHA blokkok a blokkot meghívó RAISERROR hiba ismételt kijavítására használhatók CATCH olyan rendszerfüggvények használatával, mint például ERROR_NUMBERERROR_MESSAGE az eredeti hibainformációk lekérése. @@ERROR alapértelmezés szerint az 0 1 és 10 közötti súlyosságú üzenetek esetében van beállítva.

Ha msg_id a katalógusnézetből sys.messages elérhető, felhasználó által definiált üzenetet ad meg, a szövegoszlop üzenetét ugyanazokkal a szabályokkal dolgozza fel, RAISERROR mint a msg_str használatával megadott felhasználó által megadott üzenetek szövegére. A felhasználó által definiált üzenetszöveg tartalmazhat konverziós specifikációkat, és RAISERROR az argumentumértékeket a konvertálási specifikációkba képezi le. Felhasználó által definiált hibaüzenetek hozzáadására és sp_addmessage felhasználó által definiált hibaüzenetek törlésére használhatósp_dropmessage.

RAISERROR alternatívaként használható az PRINT alkalmazások hívására szolgáló üzenetek visszaküldésére. RAISERROR támogatja a C standard kódtárban található függvény funkcióhoz printf hasonló karakterhelyettesítést, míg a Transact-SQL PRINT utasítás nem. Az PRINT utasítást nem érintik TRY a blokkok, míg a RAISERROR TRY blokkátviteli vezérlőben 11–19 súlyosságú futtatás a társított CATCH blokkra. Adjon meg egy 10 vagy annál alacsonyabb súlyosságot, RAISERROR amely a blokkból érkező TRY üzenetek meghívása nélkül CATCH küld vissza üzenetet.

Az egymást követő argumentumok általában felváltják az egymást követő konverziós specifikációkat; az első argumentum az első konverziós specifikációt, a második argumentum a második konverziós specifikációt és így tovább. A következő RAISERROR utasításban például az első argumentum N'number' a ; első konverziós specifikációját %s, a második argumentum 5 pedig a második konverziós specifikációt cseréli le. %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

Ha egy konverziós specifikáció szélességéhez vagy pontosságához csillag (*) van megadva, a szélességhez vagy pontossághoz használandó érték egész szám argumentumértékként van megadva. Ebben az esetben egy konverziós specifikáció legfeljebb három argumentumot használhat, egyet a szélesség, a pontosság és a helyettesítési érték alapján.

Például az alábbi RAISERROR utasítások mindegyike ugyanazt a sztringet adja vissza. Az egyik megadja az argumentumlistában szereplő szélességi és pontossági értékeket; a másik az átalakítás specifikációjában határozza meg őket.

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

Bármely felhasználó megadhat egy súlyossági szintet 0 és 18 között. A 19 és 25 közötti súlyossági szinteket csak a sysadmin rögzített kiszolgálói szerepkör tagjai vagy az engedélyekkel rendelkező ALTER TRACE felhasználók adhatja meg.

Examples

A. Hibainformációk visszaadása CATCH blokkból

Az alábbi példakód bemutatja, hogyan használható RAISERROR blokkon TRY belül, hogy a végrehajtás a társított CATCH blokkra ugorjon. Azt is bemutatja, hogyan lehet RAISERROR adatokat visszaadni a blokkot meghívó CATCH hibáról.

Note

RAISERROR csak 1 és 127 közötti állapotú hibákat generál. Mivel az adatbázismotor hibát jelezhet a 0 állapottal kapcsolatban, javasoljuk, hogy ellenőrizze a ERROR_STATE által visszaadott hibaállapotot, mielőtt értéket adna át a következő állapotparaméternek 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. Alkalmi üzenet létrehozása a sys.messagesben

Az alábbi példa bemutatja, hogyan hozhat létre egy katalógusnézetben tárolt sys.messages üzenetet. Az üzenet a rendszer által tárolt eljárással lett hozzáadva a sys.messagessp_addmessage katalógusnézethez üzenetszámként 50005.

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. Helyi változó használata az üzenet szövegének megadásához

Az alábbi példakód bemutatja, hogyan használható helyi változó az üzenet szövegének megadására egy RAISERROR utasításhoz.

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

Kapcsolódó tartalom

  • Last updated on