RAISERROR (Transact-SQL)

  • Artikel

Berlaku untuk:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)Titik akhir analitik SQL di Microsoft FabricWarehouse di Microsoft Fabric

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 sys.messages tampilan katalog, atau membangun pesan secara dinamis. Pesan dikembalikan sebagai pesan kesalahan server ke aplikasi panggilan atau ke blok TRY...CATCH konstruksi terkaitCATCH. Aplikasi baru harus menggunakan THROW sebagai gantinya.

Konvensi sintaks transact-SQL

Sintaks

Sintaks untuk SQL Server dan Azure SQL Database:

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

Sintaks untuk Azure Synapse Analytics dan Gudang Data Paralel:

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

Catatan

Untuk melihat sintaks Transact-SQL untuk SQL Server 2014 (12.x) dan versi yang lebih lama, lihat Dokumentasi versi sebelumnya.

Argumen

msg_id

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

msg_str

Pesan yang ditentukan pengguna dengan pemformatan yang mirip printf dengan fungsi 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.

Saat msg_str ditentukan, RAISERROR munculkan 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:

% [[flag] [width] [. presisi] [{h | l}]] tipe

Parameter yang dapat digunakan dalam msg_str adalah:

Bendera

Kode yang menentukan penspasian dan pertimbangan nilai yang diganti.

Kode Awalan atau pertahan 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 (nol) Nol padding Awali output dengan nol hingga lebar minimum tercapai. Ketika 0 dan tanda minus (-) muncul, 0 diabaikan.
# (angka) Awalan 0x untuk tipe heksadesimal x atau X Saat digunakan dengan format o, x, atau X, bendera tanda angka (#) mengawali nilai nonzero dengan masing-masing 0, 0x, atau 0X. Ketika d, i, atau Anda diawali dengan bendera tanda angka (#), bendera diabaikan.
' ' (kosong) Ruang padding Awali nilai output dengan spasi kosong jika nilai ditandatangani dan positif. Ini diabaikan ketika disertakan dengan bendera tanda plus (+).

width

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

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 yang tidak ditandatangani

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

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

@local_variable

Adalah variabel dari jenis data karakter valid apa pun 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

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 log kesalahan dan 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

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 dimunculkan di beberapa lokasi, menggunakan nomor status unik untuk setiap lokasi dapat membantu menemukan bagian kode mana yang meningkatkan kesalahan.

argument

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, biner, atau varbinary. Tidak ada jenis data lain yang didukung.

Pilihan

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
NOWAIT Mengirim pesan segera ke klien.

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

Berlaku untuk: SQL Server, SQL Database

Keterangan

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

  • Di luar cakupan blok mana pun TRY .

  • Dengan tingkat keparahan 10 atau lebih rendah dalam satu TRY blok.

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

CATCH blok dapat digunakan RAISERROR untuk menumbuhkan CATCH kembali kesalahan yang memanggil blok 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 printf fungsi di pustaka standar C, sementara pernyataan Transact-SQL PRINT tidak. Pernyataan PRINT ini tidak dipengaruhi oleh TRY blok, sementara RAISERROR eksekusi dengan tingkat keparahan 11 hingga 19 dalam blok TRY mentransfer kontrol ke blok terkait CATCH . Tentukan tingkat keparahan 10 atau lebih rendah untuk digunakan RAISERROR untuk mengembalikan pesan dari TRY blok tanpa memanggil CATCH blok.

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 lebar dan nilai 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

J. 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 RAISERRORstatus .

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 .

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. 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

Baca juga