RAISERROR (Transact-SQL)

Bir hata iletisi üretir ve oturum için hata işleme başlatır. RAISERROR sys.messages katalog görünümündeki kullanıcı tarafından tanımlanmış bir iletiye başvurabilir veya dinamik olarak bir ileti oluşturabilir. İleti bir sunucu hata iletisi olarak çağıran uygulamaya veya bir TRY…CATCH yapısının ilişkili bir CATCH bloğuna döndürülür.

Yeni uygulamalar bunun yerine THROW kullanmalıdır.

Transact-SQL Sözdizim Kuralları

Sözdizimi

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

Bağımsız değişkenler

• msg_id
  sp_addmessage kullanılarak sys.messages katalog görünümünde depolanan, kullanıcı tarafından tanımlanmış bir hata iletisi numarasıdır. Kullanıcı tarafından tanımlanmış hata iletilerinin hata numaraları 50000'den daha büyük olmalıdır. msg_id belirtilmediğinde, RAISERROR, hata numarası 50000 ile bir hata iletisi üretir.

• msg_str
  C standart kitaplığındaki printf işlevine benzer biçimlendirmesi ola,n kullanıcı tarafından tanımlanan bir iletidir. Hata iletisinde en çok 2.047 karakter bulunabilir. İletide 2.048 veya daha fazla karakter varsa, yalnızca ilk 2.044 karakter gösterilir ve iletinin kesildiğini göstermek için üç nokta yan yana eklenir. Dahili depolama yöntemi nedeniyle değiştirme parametrelerinin çıktı gösterimlerinden daha fazla karakter tükettiklerine dikkat edin. Örneğin, 2 değeri atanan %d değiştirme parametresi, gerçekte ileti dizesinde tek karakter üretirken depolamak için dahili olarak üç ek karakterlik yer daha kullanır. Bu depolama gereksinimi, ileti çıktısında bulunan karakter sayısını azaltır.

  msg_str belirtildiğinde, RAISERROR, hata numarası 50000 ile bir hata iletisi üretir.

  msg_str isteğe bağlı dönüştürme belirtimleri olan bir karakter dizesidir. Her dönüştürme belirtimi değişken listesindeki bir değerin nasıl biçimlendirildiğini ve msg_str içindeki dönüştürme belirtimi konumundaki bir alana nasıl yerleştirildiğini tanımlar. Dönüştürme belirtimleri şu biçime sahiptir:

  % [[flag] [width] [. precision] [{h | l}]] type

  msg_str içinde kullanılabilecek parametreler şunlardır:

• flag

  Değiştirilen değerin yayılımını ve yanlara yaslamasını belirleyen bir koddur.

  Kod	Önek veya yanlara yaslama	Açıklama
  - (eksi)	Sola yaslı	Değişken değerini verili alan genişliği içinde sola yasla.
  + (artı)	İşaret öneki	Değer işaretli bir türdeyse, değişken değerinin önüne bir artı (+) veya eksi (-) koy.
  0 (sıfır)	Sıfır doldurma	Çıktının önüne, en kısa genişliğe ulaşılıncaya kadar sıfırlar koy. 0 ve eksi işareti (-) belirdiğinde, 0 yoksayılır.
  # (sayı)	x veya X türünde onaltılık tür için 0x öneki	o, x veya X biçimi ile kullanıldığında, sayı işareti (#) bayrağı sıfır olmayan değerlerin önüne sırasıyla 0, 0x veya 0X koyar. d, i veya u önüne sayı işareti (#) bayrağı geldiğinde, bayrak yoksayılır.
  ' ' (boş)	Boşluk doldurma	Değer işaretli ve artı ise çıktı değerinin önüne boşluklar koy. Bu, artı işareti (+) bayrağı ile eklendiğinde yoksayılır.

• width

  Değişken değerini yerleştirildiği alanın en kısa genişliğini tanımlayan bir tamsayıdır. Değişken değerinin uzunluğu width ayarına eşit veya bu ayardan uzunsa, değer dolgusuz olarak yazılır. Değer width ayarından kısa ise, değerin önüne, width ayarı ile belirtilen uzunluğa kadar dolgu konur.

  Yıldız (*) karakteri genişliğin değişken listesindeki tamsayı olması gereken ilişkili değişkenle belirtildiği anlamına gelir.

• precision

  Dize değerleri için değişken değerinden alınan en yüksek karakter sayısıdır. Örneğin dizenin beş karakteri varsa ve kesinliği 3 ise, dize değerinin yalnızca ilk üç karakteri kullanılır.

  Tamsayı değerlerinde precision yazılan en düşük rakam sayısıdır.

  Yıldız (*) karakteri kesinliğin değişken listesindeki tamsayı olması gereken ilişkili değişkenle belirtildiği anlamına gelir.

• {h | l} type

  d, i, o, s, x, X veya u karakter türleriyle kullanılır ve shortint (h) veya longint (l) değerleri oluşturur.

  Tür belirtimi	Gösterdiği
  d veya i	İşaretli tamsayı
  o	İşaretsiz sekizlik sayı
  s	Dize
  u	İşaretsiz tamsayı
  x veya X	İşaretsiz onaltılık sayı

  [!NOT]

  Bu tür belirtimleri, özgün olarak C standart kitaplığındaki printf işlevi için tanımlananlara dayanmaktadır. RAISERROR ileti dizelerinde kullanılan tür belirtimleri Transact-SQL veri türleriyle eşleşirken printf'te kullanılan belirtimler C dilinin veri türleriyle eşleşir. printf'te kullanılan tür belirtimleri, Transact-SQL ilişkili C veri türüne benzer bir veri türüne sahip olmadığında RAISERROR tarafından desteklenmez. Örneğin, işaretçiler için olan %p belirtimi, Transact-SQL işaretçi veri türüne sahip olmadığından RAISERROR'da desteklenmez.

  [!NOT]

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

• **@**local_variable
  msg_str ile aynı tarzda biçimlendirilmiş bir dize içeren geçerli herhangi bir karakter veri türünde bir değişkendir. **@**local_variable char veya varchar olmalı ya da bu veri türlerine örtülü olarak dönüştürülebilmelidir.

• severity
  Bu ileti ile ilişkili, kullanıcı tarafından tanımlanmış bir önem düzeyidir. sp_addmessage kullanılarak oluşturulmuş kullanıcı tarafından tanımlanmış bir ileti üretmek için msg_id kullanırken RAISERROR'da belirtilen önem düzeyi sp_addmessage yordamında belirtilen önem düzeyini geçersiz kılar.

  0 ile 18 arası önem düzeyleri her kullanıcı tarafından belirtilebilir. 19 ile 25 arası önem düzeyleri yalnızca sysadmin sabit sunucu rolünün üyeleri veya ALTER TRACE izinleri olan kullanıcılar tarafından belirtilebilir. 19 ile 25 arası önem düzeyleri için WITH LOG seçeneği gereklidir.

  Dikkat
  20 ile 25 arası önem düzeyleri ciddi kabul edilir. Ciddi bir önem düzeyi ile karşılaşılırsa, ileti alındıktan sonra istemci bağlantısı sonlandırılır ve hata, hata ve uygulama günlüklerine yazılır.

  [!NOT]

  0'dan küçük önem düzeyleri 0 olarak yorumlanır. 25'ten büyük önem düzeyleri 25 olarak yorumlanır.

• state
  0 ile 255 arasında bir tamsayıdır. Eksi değerler veya 255'ten büyük değerler bir hata üretir.

  Kullanıcı tarafından tanımlanmış aynı hata birden çok konumda oluşturulursa, bu konumlardan her biri için benzersiz bir durum numarası kullanmak kodun hangi bölümünün hata ürettiğini bulmaya yardımcı olabilir.

• argument
  msg_str değişkeninde veya msg_id değerine karşılık gelen iletide tanımlı değişkenlerin yerine geçmesi için kullanılan parametrelerdir. 0 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 şu veri türlerinden birinde yerel bir değişken olabilir: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary veya varbinary. Başka bir veri türü desteklenmez.

• option
  Hata için özel bir seçenektir ve aşağıdaki tablodaki değerlerden biri olabilir.

  Değer	Açıklama
  LOG	Hatayı Microsoft SQL Server Veritabanı Altyapısı örneğinin hata günlüğüne ve uygulama günlüğüne yazar. Hata günlüğüne yazılan hatalar şu anda en çok 440 bayt ile sınırlıdır. Yalnızca sysadmin sabit sunucu rolünün bir üyesi veya ALTER TRACE izinleri olan bir kullanıcı WITH LOG seçeneğini belirtebilir.
  NOWAIT	İletileri hemen istemciye gönderir.
  SETERROR	@@ERROR ve ERROR_NUMBER değerlerini, önem düzeyine bakmaksızın msg_id veya 50000'e ayarlar.

Açıklamalar

RAISERROR tarafından üretilen hatalar, Veritabanı Altyapısı kodu tarafından üretilen hatalarla aynı şekilde iş görür. RAISERROR tarafından belirtilen değerler ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE ve @@ERROR sistem işlevleri tarafından bildirilir. RAISERROR bir TRY bloğunda önem düzeyi 11 veya daha üstü ile çalıştırıldığında, denetimi ilişkili CATCH bloğuna devreder. RAISERROR aşağıdaki şekillerde çalıştırılırsa, hata, çağırana döndürülür:

• Herhangi bir TRY bloğu kapsamı dışında.

• 10 veya daha düşük bir önem düzeyi ile bir TRY bloğunda.

• Veritabanı bağlantısını sonlandıran 20 veya daha yüksek bir önem düzeyi ile.

CATCH blokları, ilk hata bilgilerini almak üzere ERROR_NUMBER ve ERROR_MESSAGE gibi sistem işlevlerini kullanarak, CATCH bloğunu çağıran hatayı yeniden üretmek için RAISERROR'ı kullanabilir. Önem düzeyi 1 ile 10 arasındaki iletiler için @@ERROR, varsayılan olarak 0'a ayarlanır.

msg_id sys.messages katalog görünümden kullanılabilen kullanıcı tarafından tanımlanmış bir ileti belirttiğinde, RAISERROR, msg_str ile belirtilmiş kullanıcı tarafından tanımlanmış bir iletinin metnine uygulananlarla aynı kuralları kullanarak, metin sütunundan alınan iletiyi işler. Kullanıcı tarafından tanımlanmış ileti metni dönüştürme belirtimleri içerebilir; RAISERROR değişken değerlerini dönüştürme belirtimleriyle eşleştirir. Kullanıcı tarafından tanımlanmış hata iletileri eklemek için sp_addmessage yordamını, kullanıcı tarafından tanımlanmış hata iletilerini silmek için sp_dropmessage yordamını kullanın.

RAISERROR, çağıran uygulamalara ileti döndürmek için PRINT'in yerine kullanılabilir. RAISERROR, C standart kitaplığındaki printf işlevinin işlevselliğine benzer karakter değiştirme sunarken Transact-SQL PRINT deyimi bunu yapmaz. PRINT deyimi TRY bloklarından etkilenmez; 11 ile 19 arasında bir önem düzeyi ile bir TRY bloğunda çalışan bir RAISERROR ise denetimi ilgili CATCH bloğuna devreder. RAISERROR'ı bir TRY bloğundan CATCH bloğunu çağırmadan ileti döndürmek üzere kullanmak için 10 veya daha düşük bir önem düzeyi belirtin.

Tipik olarak art arda değişkenler art arda dönüştürme belirtimlerinin yerine geçer; ilk değişken ilk dönüştürme belirtiminin, ikinci değişken ikinci dönüştürme belirtiminin vb. Örneğin, aşağıdaki RAISERROR deyiminde ilk N'number' değişkeni %s olan ilk dönüştürme belirtiminin; ikinci değişken olan 5 ise %d. olan ikinci dönüştürme belirtiminin yerine geçmektedir.

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

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

Bir dönüştürme belirtiminin genişliği veya kesinliği için bir yıldız (*) belirtilirse, genişlik veya kesinlik için kullanılacak olan değer bir tamsayı değişken değeri olarak belirtilir. Bu durumda bir dönüştürme belirtimi üçe kadar değişken kullanabilir: bir genişlik, bir kesinlik ve bir de değiştirme değeri için.

Örneğin, aşağıdaki RAISERROR deyimlerinin ikisi de aynı dizeyi döndürür. Biri değişken listesindeki genişlik ve kesinlik değerlerini belirtir; diğeri 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

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

Örnekler

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

Aşağıdaki kod örneği RAISERROR deyiminin bir TRY bloğu içinde, yürütme işleminin ilgili CATCH bloğuna atlamasını sağlamak üzere nasıl kullanılacağını göstermektedir. Ayrıca, RAISERROR deyiminin CATCH bloğunu çağıran hata hakkında bilgi döndürmek için nasıl kullanılacağını göstermektedir.

[!NOT]

RAISERROR yalnızca durumu 1 ile 127 arasında olan hatalar üretir. Veritabanı Altyapısı 0 durumu ile hatalar üretebileceğinden, RAISERROR deyiminin durum parametresine bir değer olarak geçmeden önce ERROR_STATE deyiminin döndürdüğü 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;

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'de ad hoc ileti oluşturma

Aşağıdaki örnek, sys.messages katalog görünümünde depolanan bir iletinin nasıl üretileceğini göstermektedir. İleti, sys.messages katalog görünümüne sp_addmessage sistem saklı yordamı kullanılarak, ileti numarası 50005 olarak eklenmiştir.

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
sp_dropmessage @msgnum = 50005;
GO

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
sp_dropmessage @msgnum = 50005;
GO

C.İleti metnini kullanmak için yerel bir değişkeni kullanma

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

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

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

Ayrıca bkz.

Başvuru

DECLARE @local\_variable (Transact-SQL)

Yerleşik İşlevler (Transact-SQL)

Yazdır (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)

DENEYİN...catch (Transact-sql)