Udostępnij za pomocą

RAISERROR (Transact-SQL)

Dotyczy:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)Punkt końcowy analizy SQL w usłudze Microsoft FabricHurtownia danych w usłudze Microsoft FabricBaza danych SQL w usłudze Microsoft Fabric

Note

Instrukcja RAISERROR nie honoruje SET XACT_ABORT. Nowe aplikacje powinny używać zamiast THROW.RAISERROR

Generuje komunikat o błędzie i inicjuje przetwarzanie błędów dla sesji. RAISERROR może odwoływać się do komunikatu zdefiniowanego przez użytkownika przechowywanego sys.messages w widoku wykazu lub dynamicznie tworzyć komunikat. Komunikat jest zwracany jako komunikat o błędzie serwera do aplikacji wywołującej lub skojarzonego CATCHTRY...CATCH bloku konstrukcji. Zamiast tego nowe aplikacje powinny używać funkcji THROW .

Transact-SQL konwencje składni

Syntax

Składnia dla programu SQL Server, usługi Azure SQL Database i usługi Azure SQL Managed Instance:

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

Składnia dla usług Azure Synapse Analytics i Parallel Data Warehouse:

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

Arguments

msg_id

Numer komunikatu o błędzie zdefiniowany przez użytkownika przechowywany w sys.messages widoku wykazu przy użyciu sp_addmessage. Numery błędów dla komunikatów o błędach zdefiniowanych przez użytkownika powinny być większe niż 50000. Jeśli nie określono msg_id , RAISERROR zgłasza komunikat o błędzie z liczbą 50000błędów .

Note

W usługach Azure SQL Database i Azure SQL Managed Instance nie są obsługiwane, sp_addmessage więc nie można odwoływać się do msg_id większej niż 50000.

msg_str

Komunikat zdefiniowany przez użytkownika z formatowaniem podobnym do printf funkcji w standardowej bibliotece języka C. Komunikat o błędzie może mieć maksymalnie 2047 znaków. Jeśli komunikat zawiera co najmniej 2048 znaków, wyświetlane są tylko pierwsze 2044 znaki; dodawany jest wielokropek, aby wskazać, że komunikat jest obcięty. Parametry podstawienia zużywają więcej znaków niż dane wyjściowe z powodu zachowania magazynu wewnętrznego. Na przykład parametr podstawienia z %d przypisaną wartością 2 faktycznie tworzy jeden znak w ciągu komunikatu, ale także wewnętrznie zajmuje trzy dodatkowe znaki magazynu. To wymaganie dotyczące magazynu zmniejsza liczbę dostępnych znaków dla danych wyjściowych komunikatów.

Po określeniu RAISERROR pojawia się komunikat o błędzie z liczbą 50000błędów .

msg_str to ciąg znaków z opcjonalnymi specyfikacjami konwersji osadzonej. Każda specyfikacja konwersji definiuje sposób formatowania wartości na liście argumentów i umieszczania ich w polu w lokalizacji specyfikacji konwersji w msg_str. Specyfikacje konwersji mają następujący format:

% [[flaga] [width] [. precyzja] [{h | l}]] typ

Parametry, które mogą być używane w msg_str to:

flaga

Kod określający odstępy i uzasadnienie zastępczej wartości.

Code Prefiks lub uzasadnienie Description
- (minus) Lewicowe wyrównanie Wyjustuj wartość argumentu w obrębie podanej szerokości pola.
+ („plus”) Prefiks znaku Poprzedzaj wartość argumentu znakiem plus (+) lub minus (-), jeśli wartość jest typu podpisanego.
0 (zero) Zero wypełnienia Poprzedzaj dane wyjściowe zerami do momentu osiągnięcia minimalnej szerokości. Gdy 0 znak minus (-) jest wyświetlany, 0 jest ignorowany.
# (liczba) 0x prefiks typu szesnastkowego x lub X W przypadku użycia z formatem , lub znak numeru (o) poprzedza dowolną wartość niezerową odpowiednio z wartością x, Xlub #.00x0X Gdy dflaga , ilub u jest poprzedzona flagą znaku numeru (#), flaga jest ignorowana.
' ' (puste) Wypełnienie przestrzeni Przedstaw wartość wyjściową z pustymi spacjami, jeśli wartość jest podpisana i dodatnia. To wypełnienie jest ignorowane w przypadku dołączenia do flagi znaku plus (+).

width

Liczba całkowita, która definiuje minimalną szerokość pola, do którego jest umieszczona wartość argumentu. Jeśli długość wartości argumentu jest równa lub większa niż szerokość, wartość jest drukowana bez dopełnienia. Jeśli wartość jest krótsza niż szerokość, wartość jest dopełniona do długości określonej w szerokości.

Gwiazdka (*) oznacza, że szerokość jest określona przez skojarzony argument na liście argumentów, który musi być wartością całkowitą.

precyzja

Maksymalna liczba znaków pobranych z wartości argumentu dla wartości ciągu. Jeśli na przykład ciąg ma pięć znaków, a precyzja to 3, używane są tylko pierwsze trzy znaki wartości ciągu.

W przypadku wartości całkowitych precyzja jest minimalną liczbą wydrukowanych cyfr.

Gwiazdka (*) oznacza, że precyzja jest określona przez skojarzony argument na liście argumentów, który musi być wartością całkowitą.

{h | l} typ

Używany z typami dznaków, , iosxXlub u, i tworzy wartości shortint (h) lub longint ().l

Specyfikacja typu Represents
d lub i Całkowita
o Niepodpisany oktal
s String
u Liczba całkowita bez znaku
x lub X Bezznakowy sześciastkowy

Te specyfikacje typów są oparte na pierwotnie zdefiniowanych dla printf funkcji w standardowej bibliotece języka C. Specyfikacje typów używane w RAISERROR ciągach komunikatów są mapowanie na Transact-SQL typów danych, podczas gdy specyfikacje używane w printf mapie na typy danych języka C. Specyfikacje typów używane w programie printf nie są obsługiwane, RAISERROR gdy Transact-SQL nie ma typu danych podobnego do skojarzonego typu danych C. Na przykład specyfikacja wskaźników nie jest obsługiwana, %pRAISERROR ponieważ Transact-SQL nie ma typu danych wskaźnika.

Aby przekonwertować wartość na typ danych bigint Transact-SQL, określ wartość %I64d.

@local_variable

Zmienna dowolnego prawidłowego typu danych znaków, która zawiera ciąg sformatowany w taki sam sposób, jak msg_str. @local_variable musi być char lub varchar lub może być niejawnie konwertowany na te typy danych.

severity

Poziom ważności zdefiniowany przez użytkownika skojarzony z tym komunikatem. W przypadku używania msg_id do zgłaszania komunikatu zdefiniowanego przez użytkownika utworzonego przy użyciu metody sp_addmessage, ważność określona na RAISERROR zastąpi ważność określoną w programie sp_addmessage.

W przypadku poziomów ważności od 19 do 25 wymagana WITH LOG jest opcja. Poziomy ważności mniejsze niż 0 są interpretowane jako 0. Poziomy ważności większe niż 25 są interpretowane jako 25.

Caution

Poziomy ważności od 20 do 25 są uznawane za śmiertelne. Jeśli napotkano poziom ważności krytycznej, połączenie klienta zostanie przerwane po otrzymaniu komunikatu, a błąd zostanie zarejestrowany w dziennikach błędów i aplikacji.

Możesz określić -1 , aby zwrócić wartość ważności skojarzona z błędem, jak pokazano w poniższym przykładzie.

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

Oto zestaw wyników.

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

state

Liczba całkowita z zakresu od 0 do 255. Wartości ujemne domyślnie to 1. Nie należy używać wartości większych niż 255.

Jeśli ten sam błąd zdefiniowany przez użytkownika jest zgłaszany w wielu lokalizacjach, użycie unikatowego numeru stanu dla każdej lokalizacji może pomóc w znalezieniu, która sekcja kodu zgłasza błędy.

argument

Parametry używane w podstawieniu zmiennych zdefiniowanych w msg_str lub komunikat odpowiadający msg_id. Może istnieć zero lub więcej parametrów podstawienia, ale łączna liczba parametrów podstawienia nie może przekraczać 20. Każdy parametr podstawienia może być zmienną lokalną lub dowolnym z tych typów danych: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary lub varbinary. Nie są obsługiwane żadne inne typy danych.

option

Opcja niestandardowa błędu i może być jedną z wartości w poniższej tabeli.

Value Description
LOG Rejestruje błąd w dzienniku błędów i dziennik aplikacji dla wystąpienia aparatu bazy danych programu SQL Server. Błędy zarejestrowane w dzienniku błędów są obecnie ograniczone do maksymalnie 440 bajtów. Tylko członek stałej roli serwera sysadmin lub użytkownik z uprawnieniami ALTER TRACE może określić .WITH LOG

Dotyczy: SQL Server
NOWAIT Wysyła komunikaty natychmiast do klienta.

Dotyczy: programu SQL Server, usługi Azure SQL Database i usługi Azure SQL Managed Instance
SETERROR @@ERROR Ustawia wartości i ERROR_NUMBERna msg_id lub 50000, niezależnie od poziomu ważności.

Dotyczy: programu SQL Server, usługi Azure SQL Database i usługi Azure SQL Managed Instance

Remarks

Błędy generowane przez program RAISERROR działają tak samo jak błędy generowane przez kod aparatu bazy danych. Wartości określone RAISERROR przez są zgłaszane przez ERROR_LINEfunkcje systemowe , , ERROR_MESSAGEERROR_NUMBERERROR_PROCEDUREERROR_SEVERITYERROR_STATEi .@@ERROR Gdy RAISERROR jest uruchamiany z ważnością 11 lub większą w TRY bloku, przenosi kontrolkę do skojarzonego CATCH bloku. Błąd jest zwracany do elementu wywołującego, jeśli RAISERROR jest uruchomiony:

  • Poza zakresem dowolnego TRY bloku.
  • Z ważnością 10 lub mniejszą w TRY bloku.
  • Z ważnością 20 lub większą, która przerywa połączenie z bazą danych.

CATCH bloki mogą służyć RAISERROR do ponownego przerośnięcia błędu, który wywołał CATCH blok przy użyciu funkcji systemowych, takich jak ERROR_NUMBER i ERROR_MESSAGE w celu pobrania oryginalnych informacji o błędzie. @@ERROR parametr jest domyślnie 0 ustawiony dla komunikatów o ważności od 1 do 10.

Gdy msg_id określa komunikat zdefiniowany przez użytkownika dostępny w sys.messages widoku wykazu, RAISERROR przetwarza komunikat z kolumny tekstowej przy użyciu tych samych reguł, które są stosowane do tekstu komunikatu zdefiniowanego przez użytkownika określonego przy użyciu msg_str. Tekst komunikatu zdefiniowanego przez użytkownika może zawierać specyfikacje konwersji i RAISERROR mapować wartości argumentów na specyfikacje konwersji. Służy sp_addmessage do dodawania komunikatów o błędach zdefiniowanych przez użytkownika i sp_dropmessage usuwania komunikatów o błędach zdefiniowanych przez użytkownika.

RAISERROR Może służyć jako alternatywa do zwracania PRINT komunikatów do wywoływania aplikacji. RAISERROR obsługuje podstawianie printf znaków podobne do funkcjonalności funkcji w standardowej bibliotece języka C, a instrukcja Transact-SQL PRINT nie. Instrukcja PRINT nie ma wpływu na TRY bloki, podczas gdy RAISERROR przebieg o ważności od 11 do 19 w kontrolce transferów bloków TRY do skojarzonego CATCH bloku. Określ ważność 10 lub niższą, która ma być używana RAISERROR do zwracania komunikatu TRY z CATCH bloku bez wywoływania bloku.

Zazwyczaj kolejne argumenty zastępują kolejne specyfikacje konwersji; pierwszy argument zastępuje pierwszą specyfikację konwersji, drugi argument zastępuje drugą specyfikację konwersji itd. Na przykład w poniższej RAISERROR instrukcji pierwszy argument N'number' zamienia pierwszą specyfikację %skonwersji ; a drugi argument 5 zamienia drugą specyfikację konwersji %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

Jeśli gwiazdka (*) jest określona dla szerokości lub precyzji specyfikacji konwersji, wartość, która ma być używana dla szerokości lub precyzji, jest określana jako wartość argumentu liczby całkowitej. W takim przypadku jedna specyfikacja konwersji może używać maksymalnie trzech argumentów, po jednym dla wartości szerokości, dokładności i podstawienia.

Na przykład obie poniższe RAISERROR instrukcje zwracają ten sam ciąg. Jeden określa wartości szerokości i dokładności na liście argumentów; drugi określa je w specyfikacji konwersji.

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żdy użytkownik może określić poziom ważności z zakresu od 0 do 18. Poziomy ważności od 19 do 25 można określić tylko przez członków stałej roli serwera sysadmin lub użytkowników z uprawnieniami ALTER TRACE .

Examples

A. Zwracanie informacji o błędzie z bloku CATCH

Poniższy przykład kodu pokazuje, jak używać RAISERROR wewnątrz TRY bloku, aby spowodować przejście wykonywania do skojarzonego CATCH bloku. Pokazano również, jak użyć polecenia RAISERROR , aby zwrócić informacje o błędzie, który wywołał CATCH blok.

Note

RAISERROR Generuje tylko błędy ze stanem od 1 do 127. Ponieważ aparat bazy danych może zgłaszać błędy ze stanem 0, zalecamy sprawdzenie stanu błędu zwróconego przez ERROR_STATE przed przekazaniem go jako wartości do parametru RAISERRORstanu .

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. Tworzenie komunikatu ad hoc w pliku sys.messages

W poniższym przykładzie pokazano, jak zgłosić komunikat przechowywany w sys.messages widoku wykazu. Komunikat został dodany do sys.messages widoku wykazu przy użyciu procedury składowanej systemu jako numeru sp_addmessagekomunikatu 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. Użyj zmiennej lokalnej, aby podać tekst komunikatu

W poniższym przykładzie kodu pokazano, jak za pomocą zmiennej lokalnej podać tekst komunikatu dla RAISERROR instrukcji.

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

Treści powiązane

  • Last updated on