sp_cursoropen (T-SQL)

  • Artikel

Berlaku untuk:SQL Server

Membuka kursor. sp_cursoropen menentukan pernyataan SQL yang terkait dengan opsi kursor dan kursor, lalu mengisi kursor. sp_cursoropen setara dengan kombinasi pernyataan Transact-SQL DECLARE_CURSOR dan OPEN. Prosedur ini dipanggil dengan menentukan ID =2 dalam paket aliran data tabular (TDS).

Konvensi sintaks transact-SQL

Sintaks

  
sp_cursoropen cursor OUTPUT, stmt  
    [, scrollopt[ OUTPUT ] [ , ccopt[ OUTPUT ]  
    [ ,rowcount OUTPUT [ ,boundparam][,...n]]] ]]

Argumen

Kursor
Pengidentifikasi kursor yang dihasilkan SQL Server. kursor adalah nilai handle yang harus disediakan pada semua prosedur berikutnya yang melibatkan kursor, seperti sp_cursorfetch. kursor adalah parameter yang diperlukan dengan nilai pengembalian int .

kursor memungkinkan beberapa kursor aktif pada satu koneksi database.

stmt
Adalah parameter yang diperlukan yang menentukan kumpulan hasil kursor. Setiap string kueri yang valid (sintaks dan pengikatan) dari jenis string apa pun (terlepas dari Unicode, ukuran, dll.) dapat berfungsi sebagai jenis nilai stmt yang valid.

scrollopt
Opsi gulir. scrollopt adalah parameter opsional yang memerlukan salah satu nilai input int berikut.

Nilai Deskripsi
0x0001 SET KUNCI
0x0002 DINAMIS
0x0004 FORWARD_ONLY
0x0008 STATIS
0x10 FAST_FORWARD
0x1000 PARAMETERIZED_STMT
0x2000 AUTO_FETCH
0x4000 AUTO_CLOSE
0x8000 CHECK_ACCEPTED_TYPES
0x10000 KEYSET_ACCEPTABLE
0x20000 DYNAMIC_ACCEPTABLE
0x40000 FORWARD_ONLY_ACCEPTABLE
0x80000 STATIC_ACCEPTABLE
0x100000 FAST_FORWARD_ACCEPTABLE

Karena kemungkinan bahwa nilai yang diminta tidak sesuai untuk kursor yang ditentukan oleh stmt, parameter ini berfungsi sebagai input dan output. Dalam kasus seperti itu, SQL Server menetapkan nilai yang sesuai.

ccopt
Opsi kontrol konkurensi. ccopt adalah parameter opsional yang memerlukan salah satu nilai input int berikut.

Nilai Deskripsi
0x0001 READ_ONLY
0x0002 SCROLL_LOCKS (sebelumnya dikenal sebagai LOCKCC)
0x0004 OPTIMIS (sebelumnya dikenal sebagai OPTCC)
0x0008 OPTIMIS (sebelumnya dikenal sebagai OPTCCVAL)
0x2000 ALLOW_DIRECT
0x4000 UPDT_IN_PLACE
0x8000 CHECK_ACCEPTED_OPTS
0x10000 READ_ONLY_ACCEPTABLE
0x20000 SCROLL_LOCKS_ACCEPTABLE
0x40000 OPTIMISTIC_ACCEPTABLE
0x80000 OPTIMISITC_ACCEPTABLE

Seperti halnya scrollopt, SQL Server dapat mengambil alih nilai ccopt yang diminta.

rowcount
Jumlah baris buffer pengambilan yang akan digunakan dengan AUTO_FETCH. Defaultnya adalah 20 baris. rowcount bertingkah berbeda saat ditetapkan sebagai nilai input versus nilai pengembalian.

Sebagai nilai input Sebagai nilai yang dikembalikan
Ketika nilai AUTO_FETCH scrollopt ditentukan rowcount mewakili jumlah baris yang akan ditempatkan ke dalam buffer pengambilan.

Catatan: >0 adalah nilai yang valid saat AUTO_FETCH ditentukan, tetapi diabaikan.		 Mewakili jumlah baris dalam kumpulan hasil, kecuali ketika nilai AUTO_FETCH scrollopt ditentukan.

-

boundparam
Menandakan penggunaan parameter tambahan. boundparam adalah parameter opsional yang harus ditentukan jika nilai PARAMETERIZED_STMT scrollopt diatur ke AKTIF.

Mengembalikan Nilai Kode

Jika tidak ada kesalahan yang muncul, sp_cursoropen mengembalikan salah satu nilai berikut.

0
Prosedur berhasil dijalankan.

0x0001
Terjadi kesalahan selama eksekusi (kesalahan kecil, tidak cukup parah untuk memunculkan kesalahan dalam operasi).

0x0002
Operasi asinkron sedang berlangsung.

0x0002
Operasi FETCH sedang dalam proses.

A
Kursor ini telah dibatalkan alokasinya oleh SQL Server dan tidak tersedia.

Ketika kesalahan dimunculkan, nilai yang dikembalikan mungkin tidak konsisten dan akurasi tidak dapat dijamin.

Saat parameter rowcount ditentukan sebagai nilai pengembalian, kumpulan hasil berikut terjadi.

-1
Dikembalikan jika jumlah baris tidak diketahui atau tidak berlaku.

-n
Dikembalikan ketika populasi asinkron berlaku. Mewakili jumlah baris yang ditempatkan ke dalam buffer pengambilan saat nilai scrollopt AUTO_FETCH ditentukan.

Jika RPC sedang digunakan, nilai yang dikembalikan adalah sebagai berikut.

0
Prosedur berhasil.

1
Prosedur gagal.

2
Kursor set kunci sedang dihasilkan secara asinkron.

16
Kursor maju cepat telah ditutup secara otomatis.

Catatan

Jika prosedur sp_cursoropen berhasil dijalankan, parameter pengembalian RPC dan tataan hasil dengan informasi format kolom TDS (0xa0 &0xa1 pesan) dikirim. Jika tidak berhasil, satu atau beberapa pesan kesalahan TDS dikirim. Dalam kedua kasus, tidak ada data baris yang akan dikembalikan dan jumlah pesan yang selesai akan menjadi nol. Jika Anda menggunakan versi SQL Server yang lebih lama dari 7.0, 0xa0, 0xa1 (standar untuk pernyataan SELECT) dikembalikan bersama dengan aliran token 0xa5 dan 0xa4. Jika Anda menggunakan SQL Server 7.0, 0x81 dikembalikan (standar untuk pernyataan SELECT) bersama dengan aliran token 0xa5 dan 0xa4.

Keterangan

Parameter stmt

Jika stmt menentukan eksekusi prosedur tersimpan, parameter input dapat didefinisikan sebagai konstanta sebagai bagian dari string stmt , atau ditentukan sebagai argumen boundparam . Variabel yang dideklarasikan dapat diteruskan sebagai parameter terikat dengan cara ini.

Konten parameter stmt yang diizinkan bergantung pada apakah nilai ccopt ALLOW_DIRECT return telah ditautkan oleh OR ke nilai ccopt lainnya, yaitu:

  • Jika ALLOW_DIRECT tidak ditentukan, pernyataan Transact-SQL SELECT atau EXECUTE yang memanggil prosedur tersimpan yang berisi satu pernyataan SELECT harus digunakan. Selain itu, pernyataan SELECT harus memenuhi syarat sebagai kursor; artinya, kata kunci tidak boleh berisi kata kunci SELECT INTO atau FOR BROWSE.

  • Jika ALLOW_DIRECT ditentukan, ini dapat mengakibatkan satu atau beberapa pernyataan Transact-SQL, termasuk yang, pada gilirannya, menjalankan prosedur tersimpan lainnya dengan beberapa pernyataan. Pernyataan Non-SELECT atau pernyataan SELECT apa pun yang berisi kata kunci SELECT INTO atau FOR BROWSE hanya akan dijalankan dan tidak akan menghasilkan pembuatan kursor. Hal yang sama berlaku untuk setiap pernyataan SELECT yang disertakan dalam batch beberapa pernyataan. Dalam kasus di mana pernyataan SELECT berisi klausul yang hanya berkaitan dengan kursor, klausa tersebut diabaikan. Misalnya, ketika nilai ccopt 0x2002, ini adalah permintaan untuk:

    • Kursor dengan kunci gulir, jika hanya ada satu pernyataan SELECT yang memenuhi syarat sebagai kursor, atau

    • Eksekusi pernyataan langsung jika ada beberapa pernyataan, satu pernyataan non-SELECT, atau pernyataan SELECT yang tidak memenuhi syarat sebagai kursor.

Parameter scrollopt

Lima nilai scrollopt pertama (KEYSEY, DYNAMIC, FORWARD_ONLY, STATIC, dan FAST_FORWARD) saling eksklusif.

PARAMETERIZED_STMT dan CHECK_ACCEPTED_TYPES dapat ditautkan oleh ATAU ke salah satu dari lima nilai pertama.

AUTO_FETCH dan AUTO_CLOSE dapat ditautkan oleh OR ke FAST_FORWARD.

Jika CHECK_ACCEPTED_TYPES AKTIF, setidaknya satu dari lima nilai scrollopt terakhir (KEYSET_ACCEPTABLE, DYNAMIC_ACCEPTABLE, FORWARD_ONLY_ACCEPTABLE, STATIC_ACCEPTABLE, atau FAST_FORWARD_ACCEPTABLE) juga harus AKTIF.

Kursor STATIK selalu dibuka sebagai READ_ONLY. Ini berarti bahwa tabel yang mendasar tidak dapat diperbarui melalui kursor ini.

Parameter ccopt

Empat nilai ccopt pertama (READ_ONLY, SCROLL_LOCKS, dan kedua nilai OPTIMIS) saling eksklusif.

Catatan

Memilih salah satu dari empat nilai ccopt pertama menentukan apakah kursor bersifat baca-saja, atau jika metode penguncian atau optimis digunakan untuk mencegah pembaruan yang hilang. Jika nilai ccopt tidak ditentukan, nilai defaultnya adalah OPTIMIS.

ALLOW_DIRECT dan CHECK_ACCEPTED_TYPES dapat ditautkan oleh ATAU ke salah satu dari empat nilai pertama.

UPDT_IN_PLACE dapat ditautkan oleh ATAU ke READ_ONLY, SCROLL_LOCKS, atau salah satu nilai OPTIMIS.

Jika CHECK_ACCEPTED_TYPES AKTIF, setidaknya salah satu dari empat nilai ccopt terakhir (READ_ONLY_ACCEPTABLE, SCROLL_LOCKS_ACCEPTABLE, dan salah satu nilai OPTIMISTIC_ACCEPTABLE) juga harus AKTIF.

Fungsi UPDATE dan DELETE yang diposisikan hanya dapat dilakukan dalam buffer pengambilan dan hanya jika nilai ccopt sama dengan SCROLL_LOCKS atau OPTIMIS. Jika SCROLL_LOCKS adalah nilai yang ditentukan, operasi dijamin berhasil. Jika OPTIMIS ADALAH nilai yang ditentukan, operasi akan gagal jika baris telah berubah sejak terakhir diambil.

Alasan kegagalan ini adalah bahwa ketika OPTIMIS adalah nilai yang ditentukan, fungsi kontrol mata uang optimis dilakukan dengan membandingkan tanda waktu atau nilai checksum, seperti yang ditentukan oleh SQL Server. Jika salah satu baris ini tidak cocok, operasi akan gagal.

Menentukan UPDT_IN_PLACE sebagai nilai pengembalian mengatur hasil berikut:

  • Jika tidak diatur saat melakukan pembaruan yang diposisikan pada tabel dengan indeks unik, kursor menghapus baris dari tabel kerjanya dan menyisipkannya di akhir salah satu kolom kunci yang digunakan oleh kursor, sehingga mengubah kolom tersebut.

  • Jika diatur AKTIF, kursor hanya akan memperbarui kolom kunci di baris asli tabel kerja.

Parameter bound_param

Nama parameter harus paramdef ketika PARAMETERIZED_STMT ditentukan, sesuai dengan pesan kesalahan dalam kode. Ketika PARAMETERIZED_STMT tidak ditentukan, tidak ada nama yang ditentukan dalam pesan kesalahan.

Pertimbangan RPC

Bendera input RETURN_METADATA RPC dapat diatur ke 0x0001 untuk meminta kursor tersebut memilih metadata daftar yang dikembalikan di aliran TDS.

Contoh

Parameter bound_param

Parameter apa pun setelah kelima diteruskan ke rencana pernyataan sebagai parameter input. Parameter pertama tersebut harus berupa string dalam bentuk:

{ jenis data nama variabel lokal } [,... n]

Parameter berikutnya digunakan untuk meneruskan nilai yang akan digantikan dengan nama variabel lokal dalam pernyataan.

Lihat Juga

sp_cursorfetch (T-SQL)
Prosedur Tersimpan Sistem (Transact-SQL)