RAISERROR (Transact-SQL)

Gäller för:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalysplattformssystem (PDW)SQL-analysslutpunkt i Microsoft FabricLager i Microsoft FabricSQL-databas i Förhandsversion av Microsoft Fabric

Genererar ett felmeddelande och initierar felbearbetning för sessionen. RAISERROR kan antingen referera till ett användardefinierat meddelande som lagras i sys.messages katalogvyn eller skapa ett meddelande dynamiskt. Meddelandet returneras som ett serverfelmeddelande till det anropande programmet eller till ett associerat CATCH block i en TRY...CATCH konstruktion. Nya program bör använda THROW i stället.

Transact-SQL syntaxkonventioner

Syntax

Syntax för SQL Server, Azure SQL Database och Azure SQL Managed Instance:

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

Syntax för Azure Synapse Analytics och Parallel Data Warehouse:

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

Arguments

msg_id

Ett användardefinierat felmeddelandenummer som lagras i sys.messages katalogvyn med hjälp av sp_addmessage. Felnummer för användardefinierade felmeddelanden bör vara större än 50000. När msg_id inte har angetts RAISERROR genererar ett felmeddelande med ett felnummer på 50000.

msg_str

Ett användardefinierat meddelande med formatering som liknar printf funktionen i C-standardbiblioteket. Felmeddelandet kan innehålla högst 2 047 tecken. Om meddelandet innehåller 2 048 eller fler tecken visas endast de första 2 044. en ellips läggs till för att indikera att meddelandet trunkeras. Ersättningsparametrar förbrukar fler tecken än vad utdata visar på grund av internt lagringsbeteende. Till exempel genererar ersättningsparametern %d för med ett tilldelat värde 2 faktiskt ett tecken i meddelandesträngen, men tar också upp tre extra tecken lagringsutrymme internt. Det här lagringskravet minskar antalet tillgängliga tecken för meddelandeutdata.

När msg_str anges RAISERROR genererar ett felmeddelande med ett felnummer på 50000.

msg_str är en sträng med tecken med valfria inbäddade konverteringsspecifikationer. Varje konverteringsspecifikation definierar hur ett värde i argumentlistan formateras och placeras i ett fält på platsen för konverteringsspecifikationen i msg_str. Konverteringsspecifikationer har det här formatet:

% [[flagga] [bredd] [. precision] [{h | l}]] typ

De parametrar som kan användas i msg_str är:

flag

En kod som avgör avståndet och motiveringen för det ersatta värdet.

width

Ett heltal som definierar den minsta bredden för fältet som argumentvärdet placeras i. Om längden på argumentvärdet är lika med eller längre än bredden skrivs värdet ut utan utfyllnad. Om värdet är kortare än bredden, vadderas värdet till den längd som anges i bredd.

En asterisk (*) innebär att bredden anges av det associerade argumentet i argumentlistan, som måste vara ett heltalsvärde.

precision

Det maximala antalet tecken som tas från argumentvärdet för strängvärden. Om en sträng till exempel har fem tecken och precisionen är 3 används endast de tre första tecknen i strängvärdet.

För heltalsvärden är precision det minsta antalet siffror som skrivs ut.

En asterisk (*) innebär att precisionen anges av det associerade argumentet i argumentlistan, som måste vara ett heltalsvärde.

{h | l} typ

Används med teckentyperna d, i, o, s, x, X, eller och uskapar kortint - värden (h) eller longint (l).

Dessa typspecifikationer baseras på de som ursprungligen definierades för printf funktionen i C-standardbiblioteket. De typspecifikationer som används i RAISERROR meddelandesträngar mappas till Transact-SQL datatyper, medan specifikationerna som används i printf mappning till C-språkdatatyper. Typspecifikationer som används i printf stöds inte av RAISERROR när Transact-SQL inte har någon datatyp som liknar den associerade C-datatypen. Specifikationen %p för pekare stöds till exempel inte i RAISERROR eftersom Transact-SQL inte har någon pekardatatyp.

Om du vill konvertera ett värde till Transact-SQL bigint-datatyp anger du %I64d.

@local_variable

En variabel för en giltig teckendatatyp som innehåller en sträng formaterad på samma sätt som msg_str. @local_variable måste vara tecken eller varchar, eller kunna konverteras implicit till dessa datatyper.

severity

Den användardefinierade allvarlighetsgrad som är associerad med det här meddelandet. När du använder msg_id för att skapa ett användardefinierat meddelande som skapats med , sp_addmessageåsidosätter allvarlighetsgraden som anges RAISERROR i sp_addmessage.

För allvarlighetsnivåer mellan 19 och 25 krävs alternativet WITH LOG . Allvarlighetsnivåer som är mindre än 0 tolkas som 0. Allvarlighetsgraderna större än 25 tolkas som 25.

Du kan ange -1 för att returnera det allvarlighetsgradsvärde som är associerat med felet, enligt följande exempel.

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

Här är resultatet.

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

state

Ett heltal från 0 till 255. Negativa värden är som standard 1. Värden som är större än 255 ska inte användas.

Om samma användardefinierade fel utlöses på flera platser kan du använda ett unikt tillståndsnummer för varje plats för att hitta vilket kodavsnitt som genererar felen.

argument

Parametrarna som används i ersättningen för variabler som definierats i msg_str eller meddelandet som motsvarar msg_id. Det kan finnas noll eller fler ersättningsparametrar, men det totala antalet ersättningsparametrar får inte överstiga 20. Varje ersättningsparameter kan vara en lokal variabel eller någon av dessa datatyper: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary eller varbinary. Inga andra datatyper stöds.

option

Ett anpassat alternativ för felet och kan vara ett av värdena i följande tabell.

Remarks

Felen som genereras av RAISERROR fungerar på samma sätt som fel som genereras av koden för databasmotorn. De värden som anges av RAISERROR rapporteras av systemfunktionerna ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITYoch ERROR_STATE@@ERROR . När RAISERROR körs med allvarlighetsgraden 11 eller högre i ett TRY block överförs kontrollen till det associerade CATCH blocket. Felet returneras till anroparen om RAISERROR det körs:

• Utanför omfånget för alla TRY block.
• Med en allvarlighetsgrad på 10 eller lägre i ett TRY block.
• Med en allvarlighetsgrad på 20 eller högre som avslutar databasanslutningen.

CATCH block kan använda RAISERROR för att återväxa felet som anropade CATCH blocket med hjälp av systemfunktioner som ERROR_NUMBER och ERROR_MESSAGE för att hämta den ursprungliga felinformationen. @@ERROR är inställt på 0 som standard för meddelanden med allvarlighetsgrad från 1 till 10.

När msg_id anger ett användardefinierat meddelande som är tillgängligt från sys.messages katalogvyn bearbetar RAISERROR du meddelandet från textkolumnen med samma regler som tillämpas på texten i ett användardefinierat meddelande som anges med hjälp av msg_str. Den användardefinierade meddelandetexten kan innehålla konverteringsspecifikationer och RAISERROR mappa argumentvärden till konverteringsspecifikationerna. Använd sp_addmessage för att lägga till användardefinierade felmeddelanden och sp_dropmessage för att ta bort användardefinierade felmeddelanden.

RAISERROR kan användas som ett alternativ till att PRINT returnera meddelanden till anropande program. RAISERROR stöder teckenersättning som liknar funktionens funktioner printf i C-standardbiblioteket, medan Transact-SQL-instruktionen PRINT inte gör det. Instruktionen PRINT påverkas inte av TRY block, medan en RAISERROR körning med allvarlighetsgraden 11 till 19 i ett TRY-block överför kontrollen till det associerade CATCH blocket. Ange allvarlighetsgraden 10 eller lägre för att RAISERROR returnera ett meddelande från ett TRY block utan att CATCH anropa blocket.

Vanligtvis ersätter efterföljande argument efterföljande konverteringsspecifikationer. det första argumentet ersätter den första konverteringsspecifikationen, det andra argumentet ersätter den andra konverteringsspecifikationen och så vidare. I följande RAISERROR instruktion ersätter till exempel det första argumentet N'number' i den första konverteringsspecifikationen för %s; och det andra argumentet 5 i ersätter den andra konverteringsspecifikationen för %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

Om en asterisk (*) anges för antingen bredden eller precisionen för en konverteringsspecifikation anges det värde som ska användas för bredden eller precisionen som ett heltalsargumentvärde. I det här fallet kan en konverteringsspecifikation använda upp till tre argument, en vardera för bredd, precision och ersättningsvärde.

Båda följande RAISERROR uttryck returnerar till exempel samma sträng. En anger bredd- och precisionsvärdena i argumentlistan. den andra anger dem i konverteringsspecifikationen.

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

Alla användare kan ange en allvarlighetsgrad från 0 till 18. Allvarlighetsgradsnivåer från 19 till 25 kan endast anges av medlemmar i den fasta sysadmin-serverrollen eller användare med ALTER TRACE behörighet.

Examples

A. Returnera felinformation från ett CATCH-block

I följande kodexempel visas hur du använder RAISERROR i ett TRY block för att få körningen att hoppa till det associerade CATCH blocket. Den visar också hur du använder RAISERROR för att returnera information om felet som anropade CATCH blocket.

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. Skapa ett ad hoc-meddelande i sys.messages

I följande exempel visas hur du skapar ett meddelande som lagras i sys.messages katalogvyn. Meddelandet lades till i sys.messages katalogvyn med hjälp av den sp_addmessage system lagrade proceduren som meddelandenummer 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. Använd en lokal variabel för att ange meddelandetexten

I följande kodexempel visas hur du använder en lokal variabel för att ange meddelandetexten för en RAISERROR instruktion.

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

Related content

• Vilka är SQL-databasfunktionerna?
• 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)