RAISERROR (Transact-SQL)

Van toepassing op:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)SQL Analytics-eindpunt in Microsoft FabricMagazijn in Microsoft FabricSQL-database in Microsoft Fabric Preview

Hiermee wordt een foutbericht gegenereerd en wordt de foutverwerking voor de sessie gestart. RAISERROR kan verwijzen naar een door de gebruiker gedefinieerd bericht dat is opgeslagen in de sys.messages catalogusweergave of dynamisch een bericht maken. Het bericht wordt geretourneerd als een serverfoutbericht naar de aanroepende toepassing of naar een gekoppeld CATCH blok van een TRY...CATCH constructie. Nieuwe toepassingen moeten in plaats daarvan THROW gebruiken.

Transact-SQL syntaxis-conventies

Syntax

Syntaxis voor SQL Server, Azure SQL Database en Azure SQL Managed Instance:

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

Syntaxis voor Azure Synapse Analytics en Parallel Data Warehouse:

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

Arguments

msg_id

Een door de gebruiker gedefinieerd foutberichtnummer dat is opgeslagen in de sys.messages catalogusweergave met behulp van sp_addmessage. Foutnummers voor door de gebruiker gedefinieerde foutberichten moeten groter zijn dan 50000. Wanneer msg_id niet is opgegeven, RAISERROR wordt een foutbericht met een foutnummer gegenereerd.50000

msg_str

Een door de gebruiker gedefinieerd bericht met opmaak die vergelijkbaar is met de printf functie in de standaardbibliotheek van C. Het foutbericht mag maximaal 2047 tekens bevatten. Als het bericht 2048 of meer tekens bevat, worden alleen de eerste 2044 weergegeven; er wordt een beletselteken toegevoegd om aan te geven dat het bericht wordt afgekapt. Vervangingsparameters verbruiken meer tekens dan de uitvoer vanwege intern opslaggedrag. De vervangingsparameter van %d bijvoorbeeld een toegewezen waarde van 2 de tekenreeks produceert één teken in de berichtreeks, maar neemt ook intern drie extra tekens in beslag. Deze opslagvereiste vermindert het aantal beschikbare tekens voor berichtuitvoer.

Wanneer msg_str is opgegeven, RAISERROR wordt een foutbericht met een foutnummer gegenereerd.50000

msg_str is een tekenreeks met optionele ingesloten conversiespecificaties. Elke conversiespecificatie definieert hoe een waarde in de lijst met argumenten wordt opgemaakt en in een veld wordt geplaatst op de locatie van de conversiespecificatie in msg_str. Conversiespecificaties hebben deze indeling:

% [[vlag] [breedte] [. precisie] [{h | l}]] type

De parameters die kunnen worden gebruikt in msg_str zijn:

flag

Een code die de afstand en rechtvaardiging van de vervangende waarde bepaalt.

width

Een geheel getal dat de minimale breedte definieert voor het veld waarin de argumentwaarde wordt geplaatst. Als de lengte van de argumentwaarde gelijk is aan of langer is dan breedte, wordt de waarde afgedrukt zonder opvulling. Als de waarde korter is dan de breedte, wordt de waarde opgevuld tot de lengte die is opgegeven in de breedte.

Een sterretje (*) betekent dat de breedte wordt opgegeven door het bijbehorende argument in de lijst met argumenten. Dit moet een geheel getal zijn.

precision

Het maximum aantal tekens dat afkomstig is van de argumentwaarde voor tekenreekswaarden. Als een tekenreeks bijvoorbeeld vijf tekens heeft en precisie 3 is, worden alleen de eerste drie tekens van de tekenreekswaarde gebruikt.

Voor gehele getallen is precisie het minimumaantal afgedrukte cijfers.

Een sterretje (*) betekent dat de precisie wordt opgegeven door het bijbehorende argument in de lijst met argumenten. Dit moet een geheel getal zijn.

{h | l} type

Wordt gebruikt met tekentypen d, i, o, s, x, , Xof u, en maakt korteint (h) of longint (l) waarden.

Deze typespecificaties zijn gebaseerd op de specificaties die oorspronkelijk zijn gedefinieerd voor de printf functie in de C-standaardbibliotheek. De typespecificaties die in RAISERROR berichtreeksen worden gebruikt, worden toegewezen aan Transact-SQL gegevenstypen, terwijl de specificaties die in kaart worden gebruikt voor printf gegevenstypen in de C-taal. Typespecificaties die worden gebruikt, printf worden niet ondersteund RAISERROR wanneer Transact-SQL geen gegevenstype heeft dat vergelijkbaar is met het bijbehorende C-gegevenstype. De specificatie voor aanwijzers wordt bijvoorbeeld %p niet ondersteund RAISERROR omdat Transact-SQL geen gegevenstype aanwijzer heeft.

Als u een waarde wilt converteren naar het Transact-SQL gegevenstype bigint , geeft u op %I64d.

@local_variable

Een variabele van een geldig tekengegevenstype dat een tekenreeks bevat die op dezelfde manier is opgemaakt als msg_str. @local_variable moet teken of varchar zijn of impliciet kunnen worden geconverteerd naar deze gegevenstypen.

severity

Het door de gebruiker gedefinieerde ernstniveau dat aan dit bericht is gekoppeld. Wanneer u msg_id gebruikt om een door de gebruiker gedefinieerd bericht te verhogen dat is gemaakt met behulp sp_addmessagevan de ernst die is opgegeven bij RAISERROR het overschrijven van de ernst die is opgegeven in sp_addmessage.

Voor ernstniveaus van 19 tot en met 25 is de WITH LOG optie vereist. Ernstniveaus die kleiner zijn dan 0 worden geïnterpreteerd als 0. Ernstniveaus groter dan 25 worden geïnterpreteerd als 25.

U kunt opgeven -1 dat de ernstwaarde moet worden geretourneerd die is gekoppeld aan de fout, zoals wordt weergegeven in het volgende voorbeeld.

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

Hier is het resultatenoverzicht.

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

state

Een geheel getal van 0 tot en met 255. Negatieve waarden zijn standaard ingesteld op 1. Waarden die groter zijn dan 255 mogen niet worden gebruikt.

Als dezelfde door de gebruiker gedefinieerde fout op meerdere locaties wordt gegenereerd, kan het gebruik van een uniek statusnummer voor elke locatie helpen bij het vinden van de fouten in welke sectie code de fouten veroorzaakt.

argument

De parameters die worden gebruikt in de vervanging voor variabelen die zijn gedefinieerd in msg_str of het bericht dat overeenkomt met msg_id. Er kunnen nul of meer vervangingsparameters zijn, maar het totale aantal vervangingsparameters mag niet groter zijn dan 20. Elke vervangingsparameter kan een lokale variabele of een van deze gegevenstypen zijn: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary of varbinary. Er worden geen andere gegevenstypen ondersteund.

option

Een aangepaste optie voor de fout en kan een van de waarden in de volgende tabel zijn.

Remarks

De fouten die door RAISERROR de database-engine worden gegenereerd, werken hetzelfde als fouten die zijn gegenereerd door de database-enginecode. De waarden die zijn RAISERROR opgegeven door, worden gerapporteerd door de ERROR_LINEfuncties , , ERROR_MESSAGEERROR_NUMBER, ERROR_PROCEDURE, en ERROR_SEVERITYERROR_STATE@@ERROR systeemfuncties. Wanneer RAISERROR wordt uitgevoerd met een ernst van 11 of hoger in een TRY blok, wordt het besturingselement overgedragen naar het bijbehorende CATCH blok. De fout wordt geretourneerd naar de aanroeper als RAISERROR deze wordt uitgevoerd:

• Buiten het bereik van een TRY blok.
• Met een ernst van 10 of lager in een TRY blok.
• Met een ernst van 20 of hoger die de databaseverbinding beëindigt.

CATCH blokken kunnen worden gebruikt RAISERROR om de fout die het CATCH blok heeft aangeroepen opnieuw te werpen met behulp van systeemfuncties, zoals ERROR_NUMBER en ERROR_MESSAGE om de oorspronkelijke foutgegevens op te halen. @@ERROR is standaard ingesteld 0 op berichten met een ernst van 1 tot en met 10.

Wanneer msg_id een door de gebruiker gedefinieerd bericht opgeeft dat beschikbaar is in de sys.messages catalogusweergave, RAISERROR verwerkt u het bericht uit de tekstkolom met dezelfde regels als die worden toegepast op de tekst van een door de gebruiker gedefinieerd bericht dat is opgegeven met behulp van msg_str. De door de gebruiker gedefinieerde berichttekst kan conversiespecificaties bevatten en RAISERROR argumentwaarden toewijzen aan de conversiespecificaties. Hiermee sp_addmessage voegt u door de gebruiker gedefinieerde foutberichten toe en sp_dropmessage verwijdert u door de gebruiker gedefinieerde foutberichten.

RAISERROR kan worden gebruikt als alternatief voor PRINT het retourneren van berichten naar aanroepende toepassingen. RAISERROR ondersteunt het vervangen van tekens die vergelijkbaar zijn met de functionaliteit van de printf functie in de standaardbibliotheek van C, terwijl de Transact-SQL-instructie PRINT dat niet doet. De PRINT instructie wordt niet beïnvloed door TRY blokken, terwijl een RAISERROR uitvoering met een ernst van 11 tot 19 in een TRY-blokoverdrachtsbeheer naar het bijbehorende CATCH blok wordt uitgevoerd. Geef een ernst van 10 of lager op om RAISERROR een bericht van een TRY blok te retourneren zonder het CATCH blok aan te roepen.

Normaal gesproken vervangen opeenvolgende argumenten opeenvolgende conversiespecificaties; het eerste argument vervangt de eerste conversiespecificatie, het tweede argument vervangt de tweede conversiespecificatie, enzovoort. In de volgende RAISERROR instructie vervangt het eerste argument N'number' bijvoorbeeld de eerste conversiespecificatie van %s; en het tweede argument van vervangt de tweede conversiespecificatie van 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

Als een sterretje (*) is opgegeven voor de breedte of precisie van een conversiespecificatie, wordt de waarde die moet worden gebruikt voor de breedte of precisie opgegeven als een waarde voor een geheel getal. In dit geval kan één conversiespecificatie maximaal drie argumenten gebruiken, één voor de breedte, precisie en vervangingswaarde.

Beide van de volgende RAISERROR instructies retourneren bijvoorbeeld dezelfde tekenreeks. Eén geeft de breedte- en precisiewaarden in de lijst met argumenten aan; de andere specificeert deze in de conversiespecificatie.

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

Elke gebruiker kan een ernstniveau opgeven van 0 tot en met 18. Ernstniveaus van 19 tot en met 25 kunnen alleen worden opgegeven door leden van de vaste serverrol sysadmin of gebruikers met ALTER TRACE machtigingen.

Examples

A. Foutinformatie retourneren uit een CATCH-blok

In het volgende codevoorbeeld ziet u hoe u in een TRY blok kunt gebruiken RAISERROR om uitvoering naar het bijbehorende CATCH blok te laten springen. Ook ziet u hoe u RAISERROR informatie kunt retourneren over de fout die het CATCH blok heeft aangeroepen.

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. Een ad-hocbericht maken in sys.messages

In het volgende voorbeeld ziet u hoe u een bericht genereert dat is opgeslagen in de sys.messages catalogusweergave. Het bericht is toegevoegd aan de catalogusweergave met behulp van de door het sys.messagessp_addmessage systeem opgeslagen procedure als berichtnummer 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. Een lokale variabele gebruiken om de berichttekst op te geven

In het volgende codevoorbeeld ziet u hoe u een lokale variabele gebruikt om de berichttekst voor een RAISERROR instructie op te geven.

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

• Wat zijn de SQL-databasefuncties?
• 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)