RAISERROR (SQL bertransaksi)

Berlaku untuk:yes SQL Server (semua versi yang didukung) YesAzure SQL Database YesAzure SQL Managed Instance yesAzure Synapse Analytics Analytics yesPlatform System (PDW)

Catatan

Pernyataan RAISERROR tidak menghormati SET XACT_ABORT. Aplikasi baru harus menggunakan THROW alih-alih RAISERROR.

Menghasilkan pesan kesalahan dan memulai pemrosesan kesalahan untuk sesi tersebut. RAISERROR dapat mereferensikan pesan yang ditentukan pengguna yang disimpan dalam tampilan katalog sys.messages atau membangun pesan secara dinamis. Pesan dikembalikan sebagai pesan kesalahan server ke aplikasi panggilan atau ke blok CATCH terkait dari TRY... KONSTRUKSI CATCH. Aplikasi baru harus menggunakan THROW sebagai gantinya.

Topic link iconKonvensi Sintaksis T-SQL

Sintaks

-- Syntax for SQL Server and Azure SQL Database  
  
RAISERROR ( { msg_id | msg_str | @local_variable }  
    { ,severity ,state }  
    [ ,argument [ ,...n ] ] )  
    [ WITH option [ ,...n ] ]  
-- Syntax for Azure Synapse Analytics and Parallel Data Warehouse  
  
RAISERROR ( { msg_str | @local_variable }  
    { ,severity ,state }  
    [ ,argument [ ,...n ] ] )  
    [ WITH option [ ,...n ] ]  

Catatan

Untuk melihat sintaks transact-SQL untuk SQL Server 2014 dan yang lebih lama, lihat Dokumentasi versi sebelumnya.

Argumen

msg_id
Adalah nomor pesan kesalahan yang ditentukan pengguna yang disimpan dalam tampilan katalog sys.messages menggunakan sp_addmessage. Nomor kesalahan untuk pesan kesalahan yang ditentukan pengguna harus lebih besar dari 50000. Ketika msg_id tidak ditentukan, RAISERROR memunculkan pesan kesalahan dengan jumlah kesalahan 50000.

msg_str
Adalah pesan yang ditentukan pengguna dengan pemformatan yang mirip dengan fungsi printf di pustaka standar C. Pesan kesalahan dapat memiliki maksimal 2.047 karakter. Jika pesan berisi 2.048 karakter atau lebih, hanya 2.044 karakter pertama yang ditampilkan dan elipsis ditambahkan untuk menunjukkan bahwa pesan telah dipotong. Perhatikan bahwa parameter substitusi menggunakan lebih banyak karakter daripada yang ditunjukkan oleh output karena perilaku penyimpanan internal. Misalnya, parameter substitusi %d dengan nilai 2 yang ditetapkan benar-benar menghasilkan satu karakter dalam string pesan tetapi juga secara internal mengambil tiga karakter penyimpanan tambahan. Persyaratan penyimpanan ini mengurangi jumlah karakter yang tersedia untuk output pesan.

Ketika msg_str ditentukan, RAISERROR memunculkan pesan kesalahan dengan jumlah kesalahan 50000.

msg_str adalah serangkaian karakter dengan spesifikasi konversi opsional yang disematkan. Setiap spesifikasi konversi menentukan bagaimana nilai dalam daftar argumen diformat dan ditempatkan ke dalam bidang di lokasi spesifikasi konversi di msg_str. Spesifikasi konversi memiliki format ini:

% [[bendera] [lebar] [. presisi] [{h | l}]] Jenis

Parameter yang dapat digunakan dalam msg_str adalah:

Bendera

Adalah kode yang menentukan penspasian dan pertimbangan nilai yang diganti.

Kode Awalan atau justifikasi Deskripsi
- (minus) Rata kiri Rata kiri nilai argumen dalam lebar bidang yang diberikan.
+ (plus) Tanda tangani awalan Awali nilai argumen dengan plus (+) atau minus (-) jika nilainya adalah jenis yang ditandatangani.
0 (zero) Padding nol Awali output dengan nol hingga lebar minimum tercapai. Ketika 0 dan tanda minus (-) muncul, 0 diabaikan.
# (angka) Awalan 0x untuk jenis heksadesimal x atau X Saat digunakan dengan format o, x, atau X, bendera tanda angka (#) mengawali nilai bukan nol dengan masing-masing 0, 0x, atau 0X. Ketika d, i, atau Anda diawali dengan bendera tanda angka (#), bendera diabaikan.
' ' (kosong) Padding spasi Awali nilai output dengan spasi kosong jika nilai ditandatangani dan positif. Ini diabaikan ketika disertakan dengan bendera tanda plus (+).

width

Adalah bilangan bulat yang menentukan lebar minimum untuk bidang tempat nilai argumen ditempatkan. Jika panjang nilai argumen sama dengan atau lebih panjang dari lebar, nilai dicetak tanpa padding. Jika nilai lebih pendek dari lebar, nilai diisi ke panjang yang ditentukan dalam lebar.

Tanda bintang (*) berarti bahwa lebar ditentukan oleh argumen terkait dalam daftar argumen, yang harus berupa nilai bilangan bulat.

Presisi

Adalah jumlah maksimum karakter yang diambil dari nilai argumen untuk nilai string. Misalnya, jika string memiliki lima karakter dan presisi adalah 3, hanya tiga karakter pertama dari nilai string yang digunakan.

Untuk nilai bilangan bulat, presisi adalah jumlah minimum digit yang dicetak.

Tanda bintang (*) berarti bahwa presisi ditentukan oleh argumen terkait dalam daftar argumen, yang harus berupa nilai bilangan bulat.

{h | l} Jenis

Digunakan dengan jenis karakter d, i, o, s, x, X, atau u, dan membuat nilai shortint (h) atau longint (l).

Spesifikasi jenis Merepresentasikan
d atau i Bilangan bulat bertanda tangan
o Oktal yang tidak ditandatangani
s String
u Bilangan bulat tidak ditandatangani
x atau X Heksadesimal tidak bertanda

Catatan

Spesifikasi jenis ini didasarkan pada spesifikasi yang awalnya ditentukan untuk fungsi printf di pustaka standar C. Spesifikasi jenis yang digunakan dalam string pesan RAISERROR dipetakan ke jenis data Transact-SQL, sementara spesifikasi yang digunakan dalam peta cetak ke jenis data bahasa C. Spesifikasi jenis yang digunakan dalam printf tidak didukung oleh RAISERROR ketika Transact-SQL tidak memiliki jenis data yang mirip dengan jenis data C terkait. Misalnya, spesifikasi %p untuk pointer tidak didukung di RAISERROR karena Transact-SQL tidak memiliki tipe data penunjuk.

Catatan

Untuk mengonversi nilai ke tipe data bigint Transact-SQL, tentukan %I64d.

@local_variable
Adalah variabel dari setiap jenis data karakter valid yang berisi string yang diformat dengan cara yang sama seperti msg_str. @local_variable harus karakter atau varchar, atau dapat dikonversi secara implisit ke jenis data ini.

keparahan
Adalah tingkat keparahan yang ditentukan pengguna yang terkait dengan pesan ini. Saat menggunakan msg_id untuk menaikkan pesan yang ditentukan pengguna yang dibuat menggunakan sp_addmessage, tingkat keparahan yang ditentukan pada RAISERROR mengambil alih tingkat keparahan yang ditentukan dalam sp_addmessage.
Untuk tingkat keparahan dari 19 hingga 25, opsi WITH LOG diperlukan. Tingkat keparahan kurang dari 0 ditafsirkan sebagai 0. Tingkat keparahan yang lebih besar dari 25 ditafsirkan sebagai 25.

Perhatian

Tingkat keparahan dari 20 hingga 25 dianggap fatal. Jika tingkat keparahan fatal ditemui, koneksi klien dihentikan setelah menerima pesan, dan kesalahan dicatat dalam kesalahan dan log aplikasi.

Anda dapat menentukan -1 untuk mengembalikan nilai tingkat keparahan yang terkait dengan kesalahan seperti yang ditunjukkan dalam contoh berikut.

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

Berikut adalah hasil yang ditetapkan.

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

state
Adalah bilangan bulat dari 0 hingga 255. Nilai negatif default ke 1. Nilai yang lebih besar dari 255 tidak boleh digunakan.

Jika kesalahan yang ditentukan pengguna yang sama muncul di beberapa lokasi, menggunakan nomor status unik untuk setiap lokasi dapat membantu menemukan bagian kode mana yang menimbulkan kesalahan.

Argumen
Apakah parameter yang digunakan dalam substitusi untuk variabel yang ditentukan dalam msg_str atau pesan yang sesuai dengan msg_id. Mungkin ada 0 atau lebih parameter substitusi, tetapi jumlah total parameter substitusi tidak boleh melebihi 20. Setiap parameter substitusi dapat berupa variabel lokal atau salah satu jenis data ini: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary, atau varbinary. Tidak ada jenis data lain yang didukung.

Pilihan
Adalah opsi kustom untuk kesalahan dan bisa menjadi salah satu nilai dalam tabel berikut.

Nilai Deskripsi
LOG Mencatat kesalahan dalam log kesalahan dan log aplikasi untuk instans mesin database Microsoft SQL Server. Kesalahan yang dicatat dalam log kesalahan saat ini dibatasi hingga maksimum 440 byte. Hanya anggota peran server tetap sysadmin atau pengguna dengan izin ALTER TRACE yang dapat menentukan WITH LOG.

Berlaku untuk: SQL Server, SQL Database
SEKARANGAIT Mengirim pesan segera ke klien.

Berlaku untuk: SQL Server, SQL Database
SETERROR Mengatur nilai @@ERROR dan ERROR_NUMBER ke msg_id atau 50000, terlepas dari tingkat keparahannya.

Berlaku untuk: SQL Server, SQL Database

Keterangan

Kesalahan yang dihasilkan oleh RAISERROR beroperasi sama dengan kesalahan yang dihasilkan oleh kode Mesin Database. Nilai yang ditentukan oleh RAISERROR dilaporkan oleh fungsi sistem ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE, dan @@ERROR. Ketika RAISERROR dijalankan dengan tingkat keparahan 11 atau lebih tinggi dalam blok TRY, RAISERROR mentransfer kontrol ke blok CATCH terkait. Kesalahan dikembalikan ke pemanggil jika RAISERROR dijalankan:

  • Di luar cakupan blok TRY apa pun.

  • Dengan tingkat keparahan 10 atau lebih rendah di blok TRY.

  • Dengan tingkat keparahan 20 atau lebih tinggi yang mengakhiri koneksi database.

Blok CATCH dapat menggunakan RAISERROR untuk memunculkan kembali kesalahan yang memanggil blok CATCH dengan menggunakan fungsi sistem seperti ERROR_NUMBER dan ERROR_MESSAGE untuk mengambil informasi kesalahan asli. @@ERROR diatur ke 0 secara default untuk pesan dengan tingkat keparahan dari 1 hingga 10.

Saat msg_id menentukan pesan yang ditentukan pengguna yang tersedia dari tampilan katalog sys.messages, RAISERROR memproses pesan dari kolom teks menggunakan aturan yang sama seperti yang diterapkan ke teks pesan yang ditentukan pengguna yang ditentukan menggunakan msg_str. Teks pesan yang ditentukan pengguna dapat berisi spesifikasi konversi, dan RAISERROR akan memetakan nilai argumen ke dalam spesifikasi konversi. Gunakan sp_addmessage untuk menambahkan pesan kesalahan yang ditentukan pengguna dan sp_dropmessage untuk menghapus pesan kesalahan yang ditentukan pengguna.

RAISERROR dapat digunakan sebagai alternatif untuk PRINT untuk mengembalikan pesan ke aplikasi panggilan. RAISERROR mendukung penggantian karakter yang mirip dengan fungsionalitas fungsi printf di pustaka standar C, sementara pernyataan Transact-SQL PRINT tidak. Pernyataan PRINT tidak terpengaruh oleh blok TRY, sementara RAISERROR berjalan dengan tingkat keparahan 11 hingga 19 dalam blok TRY mentransfer kontrol ke blok CATCH terkait. Tentukan tingkat keparahan 10 atau lebih rendah untuk menggunakan RAISERROR untuk mengembalikan pesan dari blok TRY tanpa memanggil blok CATCH.

Biasanya, argumen berturut-turut menggantikan spesifikasi konversi berturut-turut; argumen pertama menggantikan spesifikasi konversi pertama, argumen kedua menggantikan spesifikasi konversi kedua, dan sebagainya. Misalnya, dalam pernyataan berikut RAISERROR , argumen N'number' pertama menggantikan spesifikasi konversi pertama ; %sdan argumen 5 kedua menggantikan spesifikasi konversi kedua dari %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  

Jika tanda bintang (*) ditentukan untuk lebar atau presisi spesifikasi konversi, nilai yang akan digunakan untuk lebar atau presisi ditentukan sebagai nilai argumen bilangan bulat. Dalam hal ini, satu spesifikasi konversi dapat menggunakan hingga tiga argumen, masing-masing satu untuk lebar, presisi, dan nilai substitusi.

Misalnya, kedua pernyataan berikut RAISERROR mengembalikan string yang sama. Satu menentukan nilai lebar dan presisi dalam daftar argumen; yang lain menentukannya dalam spesifikasi konversi.

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  

Izin

Tingkat keparahan dari 0 hingga 18 dapat ditentukan oleh pengguna mana pun. Tingkat keparahan dari 19 hingga 25 hanya dapat ditentukan oleh anggota peran server tetap sysadmin atau pengguna dengan izin ALTER TRACE.

Contoh

A. Mengembalikan informasi kesalahan dari blok CATCH

Contoh kode berikut menunjukkan cara menggunakan RAISERROR di dalam TRY blok untuk menyebabkan eksekusi melompat ke blok terkait CATCH . Ini juga menunjukkan cara menggunakan RAISERROR untuk mengembalikan informasi tentang kesalahan yang memanggil CATCH blok.

Catatan

RAISERROR hanya menghasilkan kesalahan dengan status dari 1 hingga 127. Karena Mesin Database dapat menimbulkan kesalahan dengan status 0, kami sarankan Anda memeriksa status kesalahan yang dikembalikan oleh ERROR_STATE sebelum meneruskannya sebagai nilai ke parameter status RAISERROR.

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. Membuat pesan ad hoc di sys.messages

Contoh berikut menunjukkan cara menaikkan pesan yang disimpan dalam tampilan katalog sys.messages. Pesan ditambahkan ke tampilan katalog sys.messages dengan menggunakan prosedur tersimpan sp_addmessage sistem sebagai nomor 50005pesan .

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. Menggunakan variabel lokal untuk menyediakan teks pesan

Contoh kode berikut menunjukkan cara menggunakan variabel lokal untuk menyediakan teks pesan untuk pernyataan RAISERROR .

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  

Lihat juga

Fungsi Bawaan (SQL Transact)
DECLARE @local_variable (Transact-SQL)
PRINT (SQL Bertransaksi)
sp_addmessage (SQL Bertransaksi)
sp_dropmessage (SQL Bertransaksi)
sys.messages (Transact-SQL)
xp_logevent (SQL Bertransaksi)
@@ERROR (SQL Bertransaksi)
ERROR_LINE (SQL Bertransaksi)
ERROR_MESSAGE (SQL Bertransaksi)
ERROR_NUMBER (SQL Bertransaksi)
ERROR_PROCEDURE (SQL Bertransaksi)
ERROR_SEVERITY (SQL Bertransaksi)
ERROR_STATE (SQL Bertransaksi)
MENCOBA... CATCH (Transact-SQL)