sp_cursorfetch (T-SQL)

Berlaku untuk:SQL Server

Mengambil buffer dari satu atau beberapa baris dari database. Grup baris dalam buffer ini disebut buffer pengambilan kursor. sp_cursorfetch dipanggil dengan menentukan ID = 7 dalam paket aliran data tabular (TDS).

Konvensi sintaks transact-SQL

Sintaks

  
sp_cursorfetch cursor  
    [ , fetchtype[ , rownum [ , nrows] ]]   

Argumen

Kursor
Adalah nilai handle yang dihasilkan oleh SQL Server dan dikembalikan oleh sp_cursoropen. kursor adalah parameter yang diperlukan yang memanggil nilai input int . Untuk informasi selengkapnya, lihat bagian Keterangan nanti dalam topik ini.

fetchtype
Menentukan buffer kursor mana yang akan diambil. fetchtype adalah parameter opsional yang memerlukan salah satu nilai input bilangan bulat berikut.

Nilai	Nama	Deskripsi
0x0001	PERTAMA	Mengambil buffer pertama baris nrows . Jika nrows sama dengan 0, kursor diposisikan sebelum tataan hasil dan tidak ada baris yang dikembalikan.
0x0002	NEXT	Mengambil buffer baris nrows berikutnya.
0x0004	PREV	Mengambil buffer baris nrows sebelumnya. Catatan: Menggunakan PREV untuk kursor FORWARD_ONLY mengembalikan pesan kesalahan karena FORWARD_ONLY hanya mendukung pengguliran ke satu arah.
0x0008	LAST	Mengambil buffer terakhir baris nrows . Jika nrows sama dengan 0, kursor diposisikan setelah tataan hasil dan tidak ada baris yang dikembalikan. Catatan: Menggunakan LAST untuk kursor FORWARD_ONLY mengembalikan pesan kesalahan karena FORWARD_ONLY hanya mendukung pengguliran ke satu arah.
0x10	MUTLAK	Mengambil buffer baris nrows yang dimulai dengan baris rownum . Catatan: Menggunakan ABSOLUTE untuk kursor DINAMIS atau kursor FORWARD_ONLY mengembalikan pesan kesalahan karena FORWARD_ONLY hanya mendukung pengguliran ke satu arah.
0x20	RELATIF	Mengambil buffer baris nrows yang dimulai dengan baris yang ditentukan sebagai nilai rownum baris dari baris pertama di blok saat ini. Dalam hal ini rownum dapat berupa angka negatif. Catatan: Menggunakan RELATIVE untuk kursor FORWARD_ONLY mengembalikan pesan kesalahan karena FORWARD_ONLY hanya mendukung pengguliran ke satu arah.
0x80	REFRESH	Isi ulang buffer dari tabel yang mendasar.
0x100	INFO	Mengambil informasi tentang kursor. Informasi ini dikembalikan dengan menggunakan parameter rownum dan nrows . Oleh karena itu, ketika INFO ditentukan, rownum dan nrows menjadi parameter output.
0x200	PREV_NOADJUST	Digunakan seperti PREV. Namun, jika bagian atas kumpulan hasil ditemui sebelum waktunya, hasilnya mungkin bervariasi.
0x400	SKIP_UPDT_CNCY	Harus digunakan dengan salah satu nilai fetchtype lainnya, kecuali untuk INFO.

Catatan

Tidak ada dukungan untuk nilai 0x40.

Untuk informasi selengkapnya, lihat bagian Keterangan nanti dalam topik ini.

rownum
Adalah parameter opsional yang digunakan untuk menentukan posisi baris untuk nilai fetchtype ABSOLUTE dan INFO dengan hanya menggunakan nilai bilangan bulat untuk input atau output, atau keduanya. rownum berfungsi sebagai offset baris untuk nilai bit fetchtype RELATIVE. rownum diabaikan untuk semua nilai lainnya. Untuk informasi selengkapnya, lihat bagian Keterangan nanti dalam topik ini.

nrows
Adalah parameter opsional yang digunakan untuk menentukan jumlah baris yang akan diambil. Jika nrows tidak ditentukan, nilai defaultnya adalah 20 baris. Untuk mengatur posisi tanpa mengembalikan data, tentukan nilai 0. Saat nrows diterapkan ke kueri INFO fetchtype , nrows mengembalikan jumlah total baris dalam kueri tersebut.

Catatan

nrows diabaikan oleh nilai bit fetchtype REFRESH.

Untuk informasi selengkapnya, lihat bagian Keterangan nanti dalam topik ini.

Mengembalikan Nilai Kode

Saat Anda menentukan INFO nilai bit, nilai yang mungkin dikembalikan diperlihatkan dalam tabel berikut.

Catatan

: Jika tidak ada baris yang dikembalikan, konten buffer tetap seperti sebelumnya.

<rownum>	Atur ke
Jika tidak terbuka	0
Jika diposisikan sebelum tataan hasil	0
Jika diposisikan setelah tataan hasil	-1
Untuk kursor KEYSET dan STATIC	Nomor baris absolut dari posisi saat ini dalam tataan hasil
Untuk kursor DYNAMIC	1
Untuk ABSOLUTE	-1 mengembalikan baris terakhir dalam satu set. -2 mengembalikan baris kedua ke terakhir dalam satu set, dan sebagainya. Catatan: Jika lebih dari satu baris diminta untuk diambil dalam kasus ini, dua baris terakhir dari kumpulan hasil dikembalikan.

<nrows>	Atur ke
Jika tidak terbuka	0
Untuk kursor KEYSET dan STATIC	Biasanya, ukuran set kunci saat ini. -m jika kursor dalam pembuatan asinkron dengan baris m ditemukan sampai saat ini.
Untuk kursor DYNAMIC	-1

Keterangan

Parameter kursor

Sebelum ada operasi pengambilan, posisi default kursor adalah sebelum baris pertama dari kumpulan hasil.

Parameter fetchtype

Kecuali untuk SKIP_UPD_CNCY, nilai fetchtype saling eksklusif.

Saat SKIP_UPDT_CNCY ditentukan, nilai kolom tanda waktu tidak ditulis ke tabel set kunci saat baris diambil atau disegarkan. Jika baris set kunci sedang diperbarui, nilai kolom tanda waktu tetap sebagai nilai sebelumnya. Jika baris set kunci sedang disisipkan, nilai untuk kolom tanda waktu tidak ditentukan.

Untuk kursor KEYSET, ini berarti bahwa tabel set kunci memiliki nilai yang ditetapkan selama FETCH nonskip terakhir, jika dilakukan. Jika tidak, nilainya ditetapkan selama populasi.

Untuk kursor DYNAMIC, ini berarti bahwa jika lompat dilakukan dengan refresh, kursor menghasilkan hasil yang sama dengan KEYSET. Untuk jenis pengambilan lainnya, tabel set kunci dipotong. Ini berarti bahwa baris sedang disisipkan dan nilai untuk kolom tanda waktu tidak ditentukan. Oleh karena itu, saat Anda menjalankan sp_cursorfetch untuk kursor DINAMIS, hindari menggunakan SKIP_UPDT_CNCY untuk operasi apa pun selain REFRESH.

Jika operasi pengambilan gagal karena posisi kursor yang diminta berada di luar tataan hasil, posisi kursor diatur tepat setelah baris terakhir. Jika operasi pengambilan gagal karena posisi kursor yang diminta diposisikan sebelum tataan hasil, posisi kursor diatur sebelum baris pertama.

Parameter rownum

Saat Anda menggunakan rownum, buffer diisi dimulai dengan baris yang ditentukan.

Nilai fetchtype ABSOLUTE mengacu pada posisi rownum dalam seluruh tataan hasil. Angka negatif dengan ABSOLUTE menentukan bahwa operasi menghitung baris dari akhir kumpulan hasil.

Nilai fetchtype RELATIVE mengacu pada posisi rownum sehubungan dengan posisi kursor pada awal buffer saat ini. Angka negatif dengan RELATIVE menentukan bahwa kursor mundur dari posisi kursor saat ini.

Parameter nrows

Nilai fetchtype REFRESH dan INFO mengabaikan parameter ini.

Saat Anda menentukan nilai fetchtype FIRST yang memiliki nilai nrow 0, kursor diposisikan sebelum tataan hasil yang tidak memiliki baris dalam buffer pengambilan.

Saat Anda menentukan nilai fetchtype LAST yang memiliki nilai nrow 0, kursor diposisikan setelah tataan hasil yang tidak memiliki baris dalam buffer pengambilan saat ini.

Untuk nilai fetchtype NEXT, PREV, ABSOLUTE, RELATIVE, dan PREV_NOADJUST, nilai nrow 0 tidak valid.

Pertimbangan RPC

Status pengembalian RPC menunjukkan apakah parameter ukuran keyset bersifat final atau tidak, yaitu jika set kunci atau tabel sementara sedang diisi secara asinkron.

Parameter status RPC diatur ke salah satu nilai yang diperlihatkan dalam tabel berikut.

Nilai	Deskripsi
0	Prosedur berhasil dijalankan.
0x0001	Prosedur gagal.
0x0002	Pengambilan ke arah negatif menyebabkan posisi kursor diatur ke awal kumpulan hasil, ketika pengambilan akan secara logis sebelum hasil.
0x10	Kursor maju cepat ditutup secara otomatis.

Baris dikembalikan sebagai kumpulan hasil umum, yaitu: format kolom (0x2a), baris (0xd1), diikuti dengan selesai (0xfd). Token metadata dikirim dalam format yang sama seperti yang ditentukan untuk sp_cursoropen, yaitu: 0x81, 0xa5 dan 0xa4 untuk pengguna SQL Server 7.0, dan sebagainya. Indikator status baris dikirim sebagai kolom tersembunyi, mirip dengan mode TELUSURI, di akhir setiap baris dengan rowstat nama kolom dan tipe data INT4. Kolom rowstat ini memiliki salah satu nilai yang diperlihatkan dalam tabel berikut ini.

Nilai	Deskripsi
0x0001	FETCH_SUCCEEDED
0x0002	FETCH_MISSING

Karena protokol TDS tidak menyediakan cara untuk mengirim kolom status berikutnya tanpa mengirim kolom sebelumnya, data dummy dikirim untuk baris yang hilang (bidang nullable diatur ke null, bidang panjang tetap diatur ke 0, kosong, atau default untuk kolom tersebut, sesuai).

Rowcount DONE akan selalu nol. Pesan DONE berisi rowcount tataan hasil aktual, dan pesan kesalahan atau informasi mungkin muncul di antara pesan TDS apa pun.

Untuk meminta metadata tentang daftar pilih kursor dikembalikan di aliran TDS, atur bendera input RPC RETURN_METADATA ke 1.

Contoh

J. Menggunakan PREV untuk mengubah posisi kursor

Asumsikan bahwa kursor h2 akan menghasilkan tataan hasil yang memiliki konten berikut dengan posisi saat ini seperti yang ditunjukkan:

row 1 contents      
row 2 contents  
row 3 contents  
row 4 contents  <-- current position  
row 5 contents   
row 6 contents  

Selanjutnya, sp_cursorfetch PREV yang memiliki nilai nrows 5 akan secara logis memosisikan kursor dua baris sebelum baris pertama dari tataan hasil. Dalam kasus ini, kursor disesuaikan untuk memulai di baris pertama dan mengembalikan jumlah baris yang diminta. Ini sering berarti bahwa ia akan mengembalikan baris yang berada di buffer pengambilan SEBELUMNYA.

Catatan

Ini adalah kasus yang tepat di mana parameter status RPC diatur ke 2.

B. Menggunakan PREV_NOADJUST untuk mengembalikan lebih sedikit baris daripada PREV

PREV_NOADJUST tidak pernah menyertakan baris pada atau setelah posisi kursor saat ini di blok baris yang dikembalikannya. Dalam kasus di mana PREV mengembalikan baris setelah posisi saat ini, PREV_NOADJUST mengembalikan lebih sedikit baris daripada yang diminta dalam nrow. Mengingat posisi saat ini dalam Contoh A sebelumnya, ketika PREV diterapkan, sp_cursorfetch(h2, 4, 1, 5) mengambil baris berikut:

row1 contents   
row2 contents  
row3 contents  
row4 contents  
row5 contents  

Namun, ketika PREV_NOADJUST diterapkan, sp_cursorfetch(h2, 512, 6, 5) hanya mengambil baris berikut:

row1 contents   
row2 contents  
row3 contents   

Lihat Juga

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