Aracılığıyla paylaş

RAISERROR (Transact-SQL)

Şunlar için geçerlidir:SQL ServerAzure SQL VeritabanıAzure SQL Yönetilen ÖrneğiAzure Synapse AnalyticsAnaliz Platformu Sistemi (PDW)Microsoft Fabric'teki SQL analiz uç noktasıMicrosoft Fabric'teki ambarMicrosoft Fabric'teki SQL veritabanı

Note

deyimine RAISERROR uymuyor SET XACT_ABORT. Yeni uygulamalar yerine THROWkullanmalıdırRAISERROR.

Bir hata iletisi oluşturur ve oturum için hata işlemeyi başlatır. RAISERROR katalog görünümünde depolanan kullanıcı tanımlı bir iletiye sys.messages başvurabilir veya bir iletiyi dinamik olarak oluşturabilir. İleti, çağıran uygulamaya veya bir yapının ilişkili CATCH bloğuna TRY...CATCH sunucu hata iletisi olarak döndürülür. Bunun yerine yeni uygulamalar THROW kullanmalıdır.

Transact-SQL söz dizimi kuralları

Syntax

SQL Server, Azure SQL Veritabanı ve Azure SQL Yönetilen Örneği söz dizimi:

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

Azure Synapse Analytics ve Paralel Veri Ambarı söz dizimi:

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

Arguments

msg_id

sys.messages kullanılarak katalog görünümünde depolanan kullanıcı tanımlı bir hata iletisi numarası. Kullanıcı tanımlı hata iletileri için hata numaraları değerinden 50000büyük olmalıdır. msg_id belirtilmediğinde, RAISERROR hata numarasıyla 50000bir hata iletisi oluşturur.

Note

Azure SQL Veritabanı'nda ve Azure SQL Yönetilen Örneğinde sp_addmessage desteklenmez, bu nedenle değerinden büyük 50000 başvuramazsınız.

msg_str

C standart kitaplığındaki işleve benzer biçimlendirmeye printf sahip kullanıcı tanımlı bir ileti. Hata iletisinde en fazla 2.047 karakter olabilir. İletide 2.048 veya daha fazla karakter varsa, yalnızca ilk 2.044 görüntülenir; iletinin kesildiğini belirtmek için bir üç nokta eklenir. Değiştirme parametreleri, iç depolama davranışı nedeniyle çıktının gösterdiğinden daha fazla karakter tüketir. Örneğin, değerinin atanmış değeriyle %d değiştirme parametresi2, ileti dizesinde bir karakter oluşturur ancak dahili olarak üç ek depolama karakteri de alır. Bu depolama gereksinimi, ileti çıkışı için kullanılabilir karakter sayısını azaltır.

msg_str belirtildiğinde, RAISERROR hata numarasıyla 50000bir hata iletisi oluşturur.

msg_str , isteğe bağlı katıştırılmış dönüştürme belirtimlerine sahip bir karakter dizesidir. Her dönüştürme belirtimi, bağımsız değişken listesindeki bir değerin nasıl biçimlendirildiğini ve dönüştürme belirtiminin msg_str konumundaki bir alana nasıl yerleştirildiğini tanımlar. Dönüştürme belirtimleri şu biçime sahiptir:

% [[bayrak] [genişlik] [. duyarlık] [{h | l}]] tür

msg_str kullanılabilecek parametreler şunlardır:

bayrak

Değiştirilen değerin aralığını ve gerekçesini belirleyen bir kod.

Code Ön ek veya gerekçe Description
- (eksi) Sol düzlemeli Bağımsız değişken değerini verilen alan genişliği içinde sola yaslama.
+ (artı) İşaret öneki Değer imzalı bir türdeyse, bağımsız değişken değerinin başına artı (+) veya eksi (-) koyun.
0 (sıfır) Sıfır dolgu Minimum genişliğe ulaşılana kadar çıkışın önüne sıfır ekleyin. ve eksi işareti (0) görüntülendiğinde -0 yoksayılır.
# (sayı) 0x veya onaltılık türü x için ön ek X , oveya biçimiyle xkullanıldığında, sayı işareti (X) işareti sırasıyla , #veya 0ile 0xsıfır olmayan herhangi bir değerin 0X önüne eklenir. d, iveya u sayı işareti (#) bayrağının başına geldiğinde, bayrak yoksayılır.
' ' (boş) Uzay dolgusu Değer imzalı ve pozitifse çıkış değerinin önüne boş boşluklar ekleyin. Bu doldurma, artı işareti (+) bayrağına eklendiğinde yoksayılır.

Genişlik

Bağımsız değişken değerinin yerleştirildiği alan için minimum genişliği tanımlayan tamsayı. Bağımsız değişken değerinin uzunluğu genişliğe eşit veya daha uzunsa, değer doldurma olmadan yazdırılır. Değer genişlikten daha kısaysa, değer genişlikte belirtilen uzunluğa doldurulur.

Yıldız işareti (*), genişliğin bir tamsayı değeri olması gereken bağımsız değişken listesindeki ilişkili bağımsız değişken tarafından belirtildiği anlamına gelir.

kesinlik

Dize değerleri için bağımsız değişken değerinden alınan en fazla karakter sayısı. Örneğin, bir dizenin beş karakteri varsa ve duyarlık 3 ise, dize değerinin yalnızca ilk üç karakteri kullanılır.

Tamsayı değerleri için duyarlık , yazdırılan en az basamak sayısıdır.

Yıldız işareti (*), duyarlığı bir tamsayı değeri olması gereken bağımsız değişken listesindeki ilişkili bağımsız değişken tarafından belirtildiği anlamına gelir.

{h | l} tür

, di, o, s, xveya Xkarakter türleriyle ukullanılır ve shortint (h) veya longint (l) değerleri oluşturur.

Tip spesifikasyonu Represents
d veya i İmzalı tam sayı
o İşaretsiz sekizlik
s String
u İşaretsiz tamsayı
x veya X İşaretsiz onaltılık

Bu tür belirtimleri, C standart kitaplığındaki işlev için printf başlangıçta tanımlananları temel alır. İleti dizelerinde RAISERROR kullanılan tür belirtimleri Transact-SQL veri türleriyle, kullanılan printf belirtimler ise C dili veri türleriyle eşler. içinde kullanılan printf tür belirtimleri, Transact-SQL ilişkili C veri türüne benzer bir veri türüne sahip olmadığında tarafından RAISERROR desteklenmez. Örneğin, %p Transact-SQL işaretçi veri türü olmadığından işaretçi belirtimi 'de RAISERROR desteklenmez.

Bir değeri Transact-SQL bigint veri türüne dönüştürmek için belirtin %I64d.

@local_variable

msg_str ile aynı şekilde biçimlendirilmiş bir dize içeren geçerli karakter veri türlerinin değişkeni. @local_variablekarakter veya varchar olmalıdır ya da örtük olarak bu veri türlerine dönüştürülebilir.

severity

Bu iletiyle ilişkili kullanıcı tanımlı önem düzeyi . kullanılarak oluşturulan sp_addmessagekullanıcı tanımlı bir ileti oluşturmak için msg_id kullanılırken, üzerinde RAISERROR belirtilen önem derecesi içinde sp_addmessagebelirtilen önem derecesini geçersiz kılar.

19 ile 25 arasında önem derecesi düzeyleri için WITH LOG seçenek gereklidir. 'den 0 küçük önem düzeyleri olarak 0yorumlanır. 25'ten büyük önem düzeyleri 25 olarak yorumlanır.

Caution

20 ile 25 arasında önem derecesi düzeyleri ölümcül olarak kabul edilir. Önemli önem düzeyiyle karşılaşılırsa, ileti alındıktan sonra istemci bağlantısı sonlandırılır ve hata hata ve uygulama günlüklerinde günlüğe kaydedilir.

Aşağıdaki örnekte gösterildiği gibi hatayla ilişkili önem derecesi değerini döndürmeyi belirtebilirsiniz -1 .

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

Sonuç kümesi aşağıdadır.

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

state

0 ile 255 arasında bir tamsayı. Negatif değerler varsayılan olarak 1'e ayarlı. 255'ten büyük değerler kullanılmamalıdır.

Aynı kullanıcı tanımlı hata birden çok konumda oluşursa, her konum için benzersiz bir durum numarası kullanmak, kodun hangi bölümünün hataları tetiklediğini bulmanıza yardımcı olabilir.

argument

msg_str veya msg_id karşılık gelen iletide tanımlanan değişkenler için değiştirmede kullanılan parametreler. Sıfır veya daha fazla değiştirme parametresi olabilir, ancak değiştirme parametrelerinin toplam sayısı 20'yi aşamaz. Her değiştirme parametresi yerel bir değişken veya şu veri türlerinden herhangi biri olabilir: tinyint, smallint, int, char, varchar, nchar, nvarchar, ikili veya varbinary. Başka hiçbir veri türü desteklenmez.

option

Hata için özel bir seçenektir ve aşağıdaki tabloda yer alan değerlerden biri olabilir.

Value Description
LOG Hatayı SQL Server Veritabanı Altyapısı örneğinin hata günlüğüne ve uygulama günlüğüne kaydeder. Hata günlüğüne kaydedilen hatalar şu anda en fazla 440 bayt ile sınırlıdır. Yalnızca sysadmin sabit sunucu rolünün bir üyesi veya izinleri olan ALTER TRACE bir kullanıcı belirtebilir WITH LOG.

Şunlar için geçerlidir: SQL Server
NOWAIT İletileri istemciye hemen gönderir.

Şunlar için geçerlidir: SQL Server, Azure SQL Veritabanı ve Azure SQL Yönetilen Örneği
SETERROR önem düzeyinden @@ERROR bağımsız olarak ve ERROR_NUMBER değerlerini msg_id veya 50000 olarak ayarlar.

Şunlar için geçerlidir: SQL Server, Azure SQL Veritabanı ve Azure SQL Yönetilen Örneği

Remarks

tarafından RAISERROR oluşturulan hatalar, Veritabanı Altyapısı kodu tarafından oluşturulan hatalara benzer şekilde çalışır. tarafından RAISERROR belirtilen değerler , , ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, , ERROR_SEVERITYve ERROR_STATE sistem işlevleri tarafından @@ERRORbildirilir. Bir blokta RAISERROR 11 veya daha yüksek önem derecesiyle çalıştırıldığındaTRY, denetimi ilişkili CATCH bloğa aktarır. Hata, çalıştırılırsa RAISERROR çağırana döndürülür:

  • Herhangi bir TRY bloğun kapsamı dışında.
  • Bir blokta 10 veya daha düşük önem derecesine TRY sahip.
  • Veritabanı bağlantısını sonlandıran önem derecesi 20 veya üzeridir.

CATCHblokları, ve gibi RAISERROR sistem işlevlerini kullanarak bloğu çağıran CATCH hatayı yeniden göndermek ve ERROR_NUMBER özgün hata bilgilerini almak için kullanabilirERROR_MESSAGE. @@ERROR , önem derecesi 1 ile 10 arasında olan iletiler için varsayılan olarak olarak ayarlanır 0 .

msg_id katalog görünümünde kullanılabilen sys.messages kullanıcı tanımlı bir ileti belirttiğinde, metin sütunundaki iletiyi, RAISERRORmsg_str kullanılarak belirtilen kullanıcı tanımlı iletinin metnine uygulanan kuralların aynısını kullanarak işler. Kullanıcı tanımlı ileti metni dönüştürme belirtimleri içerebilir ve RAISERROR bağımsız değişken değerlerini dönüştürme belirtimleriyle eşler. Kullanıcı tanımlı hata iletileri eklemek ve sp_addmessage kullanıcı tanımlı hata iletilerini silmek için kullanınsp_dropmessage.

RAISERROR , çağrı uygulamalarına ileti döndürmek için PRINT alternatif olarak kullanılabilir. RAISERROR , C standart kitaplığındaki işlevin printf işlevselliğine benzer karakter değişimini desteklerken, Transact-SQL PRINT deyimi desteklemez. PRINT Deyimi bloklardan etkilenmezken TRYRAISERROR, TRY bloğunda önem derecesi 11 ile 19 arasında olan bir çalıştırma denetimi ilişkili CATCH bloğa aktarır. Bloğu çağırmadan RAISERROR bir bloktan ileti döndürmek için kullanılacak TRY 10 veya daha düşük bir CATCH önem derecesi belirtin.

Genellikle ardışık bağımsız değişkenler ardışık dönüştürme belirtimlerinin yerini alır; birinci bağımsız değişken ilk dönüştürme belirtiminin yerini alır, ikinci bağımsız değişken ikinci dönüştürme belirtiminin yerini alır ve bu şekilde devam eder. Örneğin, aşağıdaki RAISERROR deyimde öğesinin ilk bağımsız değişkeni N'number' öğesinin ilk dönüştürme belirtiminin %s, ikinci bağımsız değişkeni 5 ise öğesinin ikinci dönüştürme belirtiminin yerini alı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

Dönüştürme belirtiminin genişliği veya duyarlığı için yıldız işareti (*) belirtilirse, genişlik veya duyarlık için kullanılacak değer tamsayı bağımsız değişken değeri olarak belirtilir. Bu durumda, bir dönüştürme belirtimi genişlik, duyarlık ve değiştirme değeri için her biri olmak üzere en fazla üç bağımsız değişken kullanabilir.

Örneğin, aşağıdaki RAISERROR deyimlerin her ikisi de aynı dizeyi döndürür. Bağımsız değişken listesindeki genişlik ve duyarlık değerlerini belirtir; diğer, bunları dönüştürme belirtiminde belirtir.

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

Herhangi bir kullanıcı 0 ile 18 arasında bir önem düzeyi belirtebilir. 19 ile 25 arasında önem derecesi düzeyleri yalnızca sysadmin sabit sunucu rolünün üyeleri veya izinleri olan ALTER TRACE kullanıcılar tarafından belirtilebilir.

Examples

A. CATCH bloğundan hata bilgileri döndürme

Aşağıdaki kod örneği, yürütmenin ilişkili RAISERROR bloğa atlaması için bir TRY bloğun içinde nasıl kullanılacağını CATCH gösterir. Ayrıca, bloğu çağıran RAISERROR hata hakkında bilgi döndürmek için nasıl kullanılacağını CATCH da gösterir.

Note

RAISERROR yalnızca 1 ile 127 arasında durumla ilgili hatalar oluşturur. Veritabanı Altyapısı durum 0 ile hata oluşturabileceğinden, değerini state parametresine RAISERRORgeçirmeden önce ERROR_STATE tarafından döndürülen hata durumunu denetlemenizi öneririz.

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. sys.messages içinde geçici ileti oluşturma

Aşağıdaki örnekte katalog görünümünde depolanan bir iletinin nasıl yükseltilmesi gösterilmektedir sys.messages . İleti, sistem saklı yordamı ileti numarası sys.messagesolarak kullanılarak katalog görünümüne sp_addmessage eklendi50005.

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. İleti metnini sağlamak için yerel değişken kullanma

Aşağıdaki kod örneği, bir deyiminin ileti metnini sağlamak için RAISERROR yerel değişkenin nasıl kullanılacağını gösterir.

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

İlgili içerik

  • Last updated on