Bagikan melalui

sp_cursorfetch (T-SQL)

  • Artikel

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

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.

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 NEXT Mengambil buffer baris nrows berikutnya.
0x0004 PREV Mengambil buffer baris nrows sebelumnya.

Catatan: Menggunakan PREV untuk FORWARD_ONLY kursor 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 FORWARD_ONLY kursor mengembalikan pesan kesalahan karena FORWARD_ONLY hanya mendukung pengguliran ke satu arah.
0x10 ABSOLUTE Mengambil buffer baris nrows yang dimulai dengan baris rownum .

Catatan: Menggunakan ABSOLUTE untuk DYNAMIC kursor atau FORWARD_ONLY kursor mengembalikan pesan kesalahan karena FORWARD_ONLY hanya mendukung pengguliran ke satu arah.
0x20 RELATIVE 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 FORWARD_ONLY kursor 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.

rownum

Parameter opsional yang digunakan untuk menentukan posisi baris untuk ABSOLUTE nilai dan INFO fetchtype dengan hanya menggunakan nilai bilangan bulat untuk input atau output, atau keduanya. rownum berfungsi sebagai offset baris untuk nilai RELATIVEbit fetchtype . rownum diabaikan untuk semua nilai lainnya. Untuk informasi selengkapnya, lihat bagian Keterangan.

nrows

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 fetchtypeINFO, nrows mengembalikan jumlah total baris dalam kueri tersebut.

nrows diabaikan oleh REFRESH nilai bit fetchtype . Untuk informasi selengkapnya, lihat bagian Keterangan.

Mengembalikan nilai kode

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

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 KEYSET dan STATIC kursor Nomor baris absolut dari posisi saat ini dalam tataan hasil
Untuk DYNAMIC kursor 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 KEYSET dan STATIC kursor Biasanya, ukuran set kunci saat ini.

-m jika kursor berada dalam pembuatan asinkron dengan baris m yang ditemukan hingga saat ini.
Untuk DYNAMIC kursor -1

Keterangan

Parameter kursor

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

Parameter fetchtype

Kecuali untuk SKIP_UPD_CNCY, nilai fetchtype saling eksklusif.

Ketika 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 KEYSET kursor, ini berarti bahwa tabel set kunci memiliki nilai yang ditetapkan selama nonskip FETCHterakhir , jika dilakukan. Jika tidak, itu adalah nilai yang ditetapkan selama populasi.

Untuk DYNAMIC kursor, ini berarti bahwa jika lompat dilakukan dengan refresh, itu 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 terdefinisi. Oleh karena itu, ketika Anda menjalankan sp_cursorfetch DYNAMIC kursor, hindari penggunaan 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 abaikan parameter ini.

Saat Anda menentukan nilai fetchtype dari FIRST itu adalah nilai nrow 0, kursor diposisikan sebelum tataan hasil yang bukan baris dalam buffer pengambilan.

Saat Anda menentukan nilai fetchtype dari LAST itu adalah nilai nrow 0, kursor diposisikan setelah kumpulan hasil yang bukan baris dalam buffer pengambilan saat ini.

Untuk nilai fetchtype dari NEXT, , PREVABSOLUTE, RELATIVE, dan PREV_NOADJUST, nilai 0 nrow tidak valid.

Pertimbangan RPC

Status pengembalian RPC menunjukkan apakah parameter ukuran keyset bersifat final atau tidak; artinya, jika keyset 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 tataan hasil umum: format kolom (0x2a), baris (0xd1), diikuti oleh DONE (0xfd). Token metadata dikirim dalam format yang sama seperti yang ditentukan untuk sp_cursoropen: 0x81, 0xa5 dan 0xa4 untuk pengguna SQL Server, dan sebagainya. Indikator status baris dikirim sebagai kolom tersembunyi, mirip BROWSE dengan mode, di akhir setiap baris dengan rowstat nama kolom dan tipe data int. 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 yang dapat diubah ke null diatur ke null, dan bidang panjang tetap diatur ke 0, kosong, atau default untuk kolom tersebut, yang sesuai.

Rowcount DONE selalu 0. 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 di mana nrows 5 akan secara logis memosisikan kursor dua baris sebelum baris pertama dari kumpulan hasil. Dalam kasus ini, kursor disesuaikan untuk memulai di baris pertama dan mengembalikan jumlah baris yang diminta. Ini sering berarti bahwa ia mengembalikan baris yang berada di PRIOR buffer pengambilan.

Catatan

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

B. Gunakan 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 nrows. Mengingat posisi saat ini dalam Contoh A sebelumnya, saat PREV diterapkan, sp_cursorfetch (h2, 4, 1, 5) mengambil baris berikut:

row1 contents
row2 contents
row3 contents
row4 contents
row5 contents

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

row1 contents
row2 contents
row3 contents

Konten terkait