sp_cursorfetch (T-SQL)

Berlaku untuk: SQL Server (semua versi yang didukung)

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

tautan topikIkon Konvensi Sintaks Transact-SQL

Sintaks

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

Argumen

cursor
Adalah nilai handel 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 FIRST Mengambil buffer pertama baris nrows . Jika nrows sama dengan 0, kursor diposisikan sebelum tataan hasil dan tidak ada baris yang dikembalikan.
0x0002 BERIKUTNYA 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 Mengisi 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 tataan 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> Set 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 DINAMIS 1
Untuk ABSOLUTE -1 mengembalikan baris terakhir dalam satu set.

-2 mengembalikan baris kedua hingga 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> Set 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 titik 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 di-refresh. 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 terdefinisi.

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

Untuk kursor DYNAMIC, ini berarti bahwa jika skip dilakukan dengan refresh, ia menghasilkan hasil yang sama dengan KEYSET. Untuk jenis pengambilan lainnya, tabel set kunci dipotok. Ini berarti bahwa baris sedang disisipkan dan nilai untuk kolom tanda waktu tidak terdefinisi. Oleh karena itu, saat Anda menjalankan sp_cursorfetch untuk kursor DYNAMIC, 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 di 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 set kunci 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 tataan hasil, ketika pengambilan akan secara logis sebelum hasil.
0x10 Kursor maju cepat ditutup secara otomatis.

Baris dikembalikan sebagai tataan 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 jenis 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, yang 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 pilihan kursor dikembalikan di aliran TDS, atur RPC RETURN_METADATA bendera input ke 1.

Contoh

A. 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 memposisikan kursor dua baris sebelum baris pertama dari kumpulan hasil. Dalam kasus ini, kursor disesuaikan untuk memulai pada baris pertama dan mengembalikan jumlah baris yang diminta. Ini sering berarti bahwa ia akan mengembalikan baris yang ada di buffer pengambilan PRIOR.

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 apa pun 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 (Transact-SQL)
Prosedur Tersimpan Sistem (Transact-SQL)