Bagikan melalui


Fungsi SQLFetchScroll

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92

Ringkasan
SQLFetchScroll mengambil kumpulan baris data yang ditentukan dari kumpulan hasil dan mengembalikan data untuk semua kolom terikat. Kumpulan baris dapat ditentukan pada posisi absolut atau relatif atau berdasarkan marka buku.

Saat bekerja dengan driver ODBC 2.x, Manajer Driver memetakan fungsi ini ke SQLExtendedFetch. Untuk informasi selengkapnya, lihat Memetakan Fungsi Penggantian untuk Kompatibilitas Aplikasi Mundur.

Sintaks

  
SQLRETURN SQLFetchScroll(  
      SQLHSTMT      StatementHandle,  
      SQLSMALLINT   FetchOrientation,  
      SQLLEN        FetchOffset);  

Argumen

StatementHandle
[Input] Handel pernyataan.

FetchOrientation
[Input]

Jenis pengambilan:

SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_ABSOLUTE

SQL_FETCH_RELATIVE

SQL_FETCH_BOOKMARK

Untuk informasi selengkapnya, lihat "Memosisikan Kursor" di bagian "Komentar".

FetchOffset
[Input]

Jumlah baris yang akan diambil. Interpretasi argumen ini tergantung pada nilai argumen FetchOrientation . Untuk informasi selengkapnya, lihat "Memosisikan Kursor" di bagian "Komentar".

Mengembalikan

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostik

Ketika SQLFetchScroll mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan Handle of StatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLFetchScroll dan menjelaskan masing-masing dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATEs yang dikembalikan oleh Driver Manager. Kode pengembalian yang terkait dengan setiap nilai SQLSTATE SQL_ERROR, kecuali disebutkan sebaliknya. Jika kesalahan terjadi pada satu kolom, SQLGetDiagField dapat dipanggil dengan DiagIdentifier SQL_DIAG_COLUMN_NUMBER untuk menentukan kolom tempat kesalahan terjadi; dan SQLGetDiagField dapat dipanggil dengan DiagIdentifier SQL_DIAG_ROW_NUMBER untuk menentukan baris yang berisi kolom tersebut.

Untuk semua SQLSTATEs yang dapat mengembalikan SQL_SUCCESS_WITH_INFO atau SQL_ERROR (kecuali 01xxxx SQLSTATEs), SQL_SUCCESS_WITH_INFO dikembalikan jika kesalahan terjadi pada satu atau beberapa, tetapi tidak semua, baris operasi multirow, dan SQL_ERROR dikembalikan jika kesalahan terjadi pada operasi satu baris.

SQLSTATE Kesalahan Deskripsi
01000 Peringatan umum Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01004 Data string, terpotong kanan String atau data biner yang dikembalikan untuk kolom menghasilkan pemotongan karakter nonblank atau data biner non-NULL. Jika itu adalah nilai string, nilai tersebut dipotong kanan.
01S01 Kesalahan berturut-turut Terjadi kesalahan saat mengambil satu atau beberapa baris.

(Jika SQLSTATE ini dikembalikan ketika aplikasi ODBC 3*.x* bekerja dengan driver ODBC 2*.x*, itu dapat diabaikan.)
01S06 Mencoba mengambil sebelum tataan hasil mengembalikan set baris pertama Set baris yang diminta tumpang tindih dengan awal tataan hasil saat FetchOrientation SQL_FETCH_PRIOR, posisi saat ini berada di luar baris pertama, dan jumlah baris saat ini kurang dari atau sama dengan ukuran set baris.

Himpunan baris yang diminta tumpang tindih dengan awal tataan hasil saat FetchOrientation SQL_FETCH_PRIOR, posisi saat ini berada di luar akhir tataan hasil, dan ukuran set baris lebih besar dari ukuran kumpulan hasil.

Set baris yang diminta tumpang tindih dengan awal kumpulan hasil ketika FetchOrientation SQL_FETCH_RELATIVE, FetchOffset negatif, dan nilai absolut FetchOffset kurang dari atau sama dengan ukuran set baris.

Himpunan baris yang diminta tumpang tindih dengan awal kumpulan hasil ketika FetchOrientation SQL_FETCH_ABSOLUTE, FetchOffset negatif, dan nilai absolut FetchOffset lebih besar dari ukuran kumpulan hasil tetapi kurang dari atau sama dengan ukuran set baris.

(Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01S07 Pemotongan pecahan Data yang dikembalikan untuk kolom dipotong. Untuk jenis data numerik, bagian pecahan dari angka dipotong. Untuk jenis data waktu, tanda waktu, dan interval yang berisi komponen waktu, bagian pecahan waktu dipotong.

(Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
07006 Pelanggaran atribut jenis data terbatas Nilai data kolom dalam tataan hasil tidak dapat dikonversi ke jenis data yang ditentukan oleh TargetType di SQLBindCol.

Kolom 0 terikat dengan jenis data SQL_C_BOOKMARK, dan atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_VARIABLE.

Kolom 0 terikat dengan tipe data SQL_C_VARBOOKMARK, dan atribut pernyataan SQL_ATTR_USE_BOOKMARKS tidak diatur ke SQL_UB_VARIABLE.
07009 Indeks deskriptor tidak valid Driver adalah driver ODBC 2*.x* yang tidak mendukung SQLExtendedFetch, dan nomor kolom yang ditentukan dalam pengikatan untuk kolom adalah 0.

Kolom 0 terikat, dan atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_OFF.
08S01 Kegagalan tautan komunikasi Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses.
22001 Data string, terpotong kanan Bookmark panjang variabel yang dikembalikan untuk kolom dipotong.
22002 Variabel indikator diperlukan tetapi tidak disediakan Data NULL diambil ke dalam kolom yang StrLen_or_IndPtr diatur oleh SQLBindCol (atau SQL_DESC_INDICATOR_PTR diatur oleh SQLSetDescField atau SQLSetDescRec) adalah pointer null.
22003 Nilai numerik di luar rentang Mengembalikan nilai numerik (sebagai numerik atau string) untuk satu atau beberapa kolom terikat akan menyebabkan seluruh (dibandingkan dengan pecahan) bagian dari angka yang akan dipotong.

Untuk informasi selengkapnya, lihat Mengonversi Data dari SQL ke Jenis Data C di Lampiran D: Jenis Data.
22007 Format tanggalwaktu tidak valid Kolom karakter dalam tataan hasil terikat ke struktur C tanggal, waktu, atau tanda waktu, dan nilai dalam kolom masing-masing, tanggal, waktu, atau tanda waktu yang tidak valid.
22012 Pembagian dengan nol Nilai dari ekspresi aritmatika dikembalikan, yang menghasilkan pembagian dengan nol.
22015 Meluapnya bidang interval Menetapkan dari jenis SQL numerik atau interval yang tepat ke jenis C interval menyebabkan hilangnya digit signifikan di bidang utama.

Saat mengambil data ke jenis C interval, tidak ada representasi nilai jenis SQL dalam jenis C interval.
22018 Nilai karakter tidak valid untuk spesifikasi cast Kolom karakter dalam tataan hasil terikat ke buffer karakter C, dan kolom berisi karakter yang tidak ada representasi dalam kumpulan karakter buffer.

Jenis C adalah jenis data numerik, tanggalwaktu, atau interval yang tepat atau perkiraan; jenis SQL kolom adalah jenis data karakter; dan nilai dalam kolom bukan harfiah yang valid dari jenis C terikat.
24000 Status kursor tidak valid StatementHandle berada dalam status dijalankan tetapi tidak ada kumpulan hasil yang terkait dengan StatementHandle.
40001 Kegagalan serialisasi Transaksi di mana pengambilan dijalankan dihentikan untuk mencegah kebuntuan.
40003 Penyelesaian pernyataan tidak diketahui Koneksi terkait gagal selama eksekusi fungsi ini, dan status transaksi tidak dapat ditentukan.
HY000 Kesalahan umum Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan oleh SQLGetDiagRec di buffer *MessageText menjelaskan kesalahan dan penyebabnya.
HY001 Kesalahan alokasi memori Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi.
HY008 Operasi dibatalkan Pemrosesan asinkron diaktifkan untuk StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle. Kemudian fungsi dipanggil lagi pada StatementHandle.

Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle dari utas yang berbeda dalam aplikasi multithread.
HY010 Kesalahan urutan fungsi (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih dijalankan ketika fungsi SQLFetchScroll dipanggil.

(DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk StatementHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan.

(DM) StatementHandle yang ditentukan tidak dalam status dijalankan. Fungsi ini dipanggil tanpa terlebih dahulu memanggil fungsi SQLExecDirect, SQLExecute , atau katalog.

(DM) Fungsi eksekusi asinkron (bukan yang ini) dipanggil untuk StatementHandle dan masih dijalankan ketika fungsi ini dipanggil.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk StatementHandle dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution.

(DM) SQLFetch dipanggil untuk StatementHandle setelah SQLExtendedFetch dipanggil dan sebelum SQLFreeStmt dengan opsi SQL_CLOSE dipanggil.
HY013 Kesalahan manajemen memori Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah.
HY090 String atau panjang buffer tidak valid Atribut pernyataan SQL_ATTR_USE_BOOKMARK diatur ke SQL_UB_VARIABLE, dan kolom 0 terikat ke buffer yang panjangnya tidak sama dengan panjang maksimum untuk bookmark untuk tataan hasil ini. (Panjang ini tersedia di bidang SQL_DESC_OCTET_LENGTH IRD dan dapat diperoleh dengan memanggil SQLDescribeCol, SQLColAttribute, atau SQLGetDescField.)
HY106 Ambil jenis di luar rentang DM) Nilai yang ditentukan untuk argumen FetchOrientation tidak valid.

(DM) Argumen FetchOrientation SQL_FETCH_BOOKMARK, dan atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_OFF.

Nilai atribut pernyataan SQL_ATTR_CURSOR_TYPE SQL_CURSOR_FORWARD_ONLY, dan nilai argumen FetchOrientation tidak SQL_FETCH_NEXT.

Nilai atribut pernyataan SQL_ATTR_CURSOR_SCROLLABLE SQL_NONSCROLLABLE, dan nilai argumen FetchOrientation tidak SQL_FETCH_NEXT.
HY107 Nilai baris di luar rentang Nilai yang ditentukan dengan atribut pernyataan SQL_ATTR_CURSOR_TYPE SQL_CURSOR_KEYSET_DRIVEN, tetapi nilai yang ditentukan dengan atribut pernyataan SQL_ATTR_KEYSET_SIZE lebih besar dari 0 dan kurang dari nilai yang ditentukan dengan atribut pernyataan SQL_ATTR_ROW_ARRAY_SIZE.
HY111 Nilai marka buku tidak valid Argumen FetchOrientation SQL_FETCH_BOOKMARK, dan bookmark yang diacu oleh nilai dalam atribut pernyataan SQL_ATTR_FETCH_BOOKMARK_PTR tidak valid atau merupakan penunjuk null.
HY117 Koneksi ditangguhkan karena status transaksi yang tidak diketahui. Hanya fungsi putuskan sambungan dan baca-saja yang diizinkan. (DM) Untuk informasi selengkapnya tentang status ditangguhkan, lihat Fungsi SQLEndTran.
HYC00 Fitur opsional tidak diimplementasikan Driver atau sumber data tidak mendukung konversi yang ditentukan oleh kombinasi TargetType di SQLBindCol dan jenis data SQL dari kolom yang sesuai.
HYT00 Waktu habis kedaluwarsa Periode batas waktu kueri kedaluwarsa sebelum sumber data mengembalikan kumpulan hasil yang diminta. Periode batas waktu diatur melalui SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01 Kesalahan waktu habis koneksi kedaluwarsa Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Driver tidak mendukung fungsi ini (DM) Driver yang terkait dengan StatementHandle tidak mendukung fungsi.
IM017 Polling dinonaktifkan dalam mode pemberitahuan asinkron Setiap kali model pemberitahuan digunakan, polling dinonaktifkan.
IM018 SQLCompleteAsync belum dipanggil untuk menyelesaikan operasi asinkron sebelumnya pada handel ini. Jika panggilan fungsi sebelumnya pada handel mengembalikan SQL_STILL_EXECUTING dan jika mode pemberitahuan diaktifkan, SQLCompleteAsync harus dipanggil pada handel untuk melakukan pasca-pemrosesan dan menyelesaikan operasi.

Komentar

SQLFetchScroll mengembalikan set baris tertentu dari kumpulan hasil. Kumpulan baris dapat ditentukan berdasarkan posisi absolut atau relatif atau berdasarkan marka buku. SQLFetchScroll hanya dapat dipanggil saat kumpulan hasil ada - yaitu, setelah panggilan yang membuat tataan hasil dan sebelum kursor di atas kumpulan hasil tersebut ditutup. Jika ada kolom yang terikat, kolom akan mengembalikan data di kolom tersebut. Jika aplikasi telah menentukan penunjuk ke array status baris atau buffer untuk mengembalikan jumlah baris yang diambil, SQLFetchScroll juga mengembalikan informasi ini. Panggilan ke SQLFetchScroll dapat dicampur dengan panggilan ke SQLFetch tetapi tidak dapat dicampur dengan panggilan ke SQLExtendedFetch.

Untuk informasi selengkapnya, lihat Menggunakan Kursor Blok dan Menggunakan Kursor yang Dapat Digulir.

Memosisikan Kursor

Saat tataan hasil dibuat, kursor diposisikan sebelum awal kumpulan hasil. SQLFetchScroll memposisikan kursor blok berdasarkan nilai argumen FetchOrientation dan FetchOffset seperti yang ditunjukkan dalam tabel berikut. Aturan yang tepat untuk menentukan awal set baris baru ditampilkan di bagian berikutnya.

FetchOrientation Makna
SQL_FETCH_NEXT Mengembalikan set baris berikutnya. Ini setara dengan memanggil SQLFetch.

SQLFetchScroll mengabaikan nilai FetchOffset.
SQL_FETCH_PRIOR Mengembalikan set baris sebelumnya.

SQLFetchScroll mengabaikan nilai FetchOffset.
SQL_FETCH_RELATIVE Mengembalikan kumpulan baris FetchOffset dari awal set baris saat ini.
SQL_FETCH_ABSOLUTE Mengembalikan set baris mulai dari baris FetchOffset.
SQL_FETCH_FIRST Mengembalikan set baris pertama dalam tataan hasil.

SQLFetchScroll mengabaikan nilai FetchOffset.
SQL_FETCH_LAST Mengembalikan set baris lengkap terakhir dalam tataan hasil.

SQLFetchScroll mengabaikan nilai FetchOffset.
SQL_FETCH_BOOKMARK Mengembalikan baris FetchOffset set baris dari bookmark yang ditentukan oleh atribut pernyataan SQL_ATTR_FETCH_BOOKMARK_PTR.

Driver tidak diperlukan untuk mendukung semua orientasi pengambilan; aplikasi memanggil SQLGetInfo dengan jenis informasi SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1, atau SQL_STATIC_CURSOR_ATTRIBUTES1 (tergantung pada jenis kursor) untuk menentukan orientasi pengambilan mana yang didukung oleh driver. Aplikasi harus melihat bitmask SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE, dan WQL_CA1_BOOKMARK dalam jenis informasi ini. Selain itu, jika kursor bersifat forward-only dan FetchOrientation tidak SQL_FETCH_NEXT, SQLFetchScroll mengembalikan SQLSTATE HY106 (Jenis pengambilan di luar rentang).

Atribut pernyataan SQL_ATTR_ROW_ARRAY_SIZE menentukan jumlah baris dalam set baris. Jika kumpulan baris yang diambil oleh SQLFetchScroll tumpang tindih dengan akhir kumpulan hasil, SQLFetchScroll mengembalikan set baris parsial. Artinya, jika S + R - 1 lebih besar dari L, di mana S adalah baris awal dari set baris yang diambil, R adalah ukuran set baris, dan L adalah baris terakhir dalam tataan hasil, maka hanya baris L - S + 1 pertama dari set baris yang valid. Baris yang tersisa kosong dan memiliki status SQL_ROW_NOROW.

Setelah SQLFetchScroll kembali, baris saat ini adalah baris pertama dari set baris.

Aturan Penempatan Kursor

Bagian berikut menjelaskan aturan yang tepat untuk setiap nilai FetchOrientation. Aturan ini menggunakan notasi berikut.

Notasi Makna
Sebelum memulai Kursor blok diposisikan sebelum awal tataan hasil. Jika baris pertama dari set baris baru adalah sebelum awal kumpulan hasil, SQLFetchScroll mengembalikan SQL_NO_DATA.
Setelah selesai Kursor blok diposisikan setelah akhir tataan hasil. Jika baris pertama dari set baris baru adalah setelah akhir kumpulan hasil, SQLFetchScroll mengembalikan SQL_NO_DATA.
CurrRowsetStart Jumlah baris pertama dalam set baris saat ini.
LastResultRow Jumlah baris terakhir dalam tataan hasil.
RowsetSize Ukuran set baris.
FetchOffset Nilai argumen FetchOffset .
BookmarkRow Baris yang sesuai dengan bookmark yang ditentukan oleh atribut pernyataan SQL_ATTR_FETCH_BOOKMARK_PTR.

SQL_FETCH_NEXT

Aturan berikut berlaku.

Kondisi Baris pertama set baris baru
Sebelum memulai 1
CurrRowsetStart + RowsetSize[1] <= LastResultRow CurrRowsetStart + RowsetSize[1]
CurrRowsetStart + RowsetSize[1]> LastResultRow Setelah selesai
Setelah selesai Setelah selesai

[1] Jika ukuran set baris telah diubah sejak panggilan sebelumnya untuk mengambil baris, ini adalah ukuran set baris yang digunakan dengan panggilan sebelumnya.

SQL_FETCH_PRIOR

Aturan berikut berlaku.

Kondisi Baris pertama set baris baru
Sebelum memulai Sebelum memulai
CurrRowsetStart = 1 Sebelum memulai
1 < CurrRowsetStart <= RowsetSize [2] 1 [1]
CurrRowsetStart > RowsetSize [2] CurrRowsetStart - RowsetSize [2]
Setelah selesai DAN LastResultRow < RowsetSize [2] 1 [1]
After end AND LastResultRow >= RowsetSize [2] LastResultRow - RowsetSize + 1 [2]

[1] SQLFetchScroll mengembalikan SQLSTATE 01S06 (Coba ambil sebelum kumpulan hasil mengembalikan set baris pertama) dan SQL_SUCCESS_WITH_INFO.

[2] Jika ukuran set baris telah diubah sejak panggilan sebelumnya untuk mengambil baris, ini adalah ukuran set baris baru.

SQL_FETCH_RELATIVE

Aturan berikut berlaku.

Kondisi Baris pertama set baris baru
(Sebelum memulai DAN FetchOffset > 0) ATAU (Setelah akhir DAN FetchOffset < 0) --[1]
BeforeStart AND FetchOffset <= 0 Sebelum memulai
CurrRowsetStart = 1 AND FetchOffset < 0 Sebelum memulai
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | > RowsetSize [3] Sebelum memulai
CurrRowsetStart > 1 AND CurrRowsetStart + FetchOffset < 1 AND | FetchOffset | <= RowsetSize [3] 1 [2]
1 <= CurrRowsetStart + FetchOffset <= LastResultRow CurrRowsetStart + FetchOffset
CurrRowsetStart + FetchOffset > LastResultRow Setelah selesai
Setelah selesai DAN FetchOffset >= 0 Setelah selesai

[1] SQLFetchScroll mengembalikan set baris yang sama seolah-olah dipanggil dengan FetchOrientation diatur ke SQL_FETCH_ABSOLUTE. Untuk informasi selengkapnya, lihat bagian "SQL_FETCH_ABSOLUTE".

[2] SQLFetchScroll mengembalikan SQLSTATE 01S06 (Coba ambil sebelum kumpulan hasil mengembalikan set baris pertama) dan SQL_SUCCESS_WITH_INFO.

[3] Jika ukuran set baris telah diubah sejak panggilan sebelumnya untuk mengambil baris, ini adalah ukuran set baris baru.

SQL_FETCH_ABSOLUTE

Aturan berikut berlaku.

Kondisi Baris pertama set baris baru
FetchOffset < 0 AND | FetchOffset | <= LastResultRow LastResultRow + FetchOffset + 1
FetchOffset < 0 AND | FetchOffset | > LastResultRow DAN | FetchOffset | > RowsetSize [2] Sebelum memulai
FetchOffset < 0 AND | FetchOffset | > LastResultRow DAN | FetchOffset | <= RowsetSize [2] 1 [1]
FetchOffset = 0 Sebelum memulai
1 <= FetchOffset <= LastResultRow FetchOffset
FetchOffset > LastResultRow Setelah selesai

[1] SQLFetchScroll mengembalikan SQLSTATE 01S06 (Coba ambil sebelum kumpulan hasil mengembalikan set baris pertama) dan SQL_SUCCESS_WITH_INFO.

[2] Jika ukuran set baris telah diubah sejak panggilan sebelumnya untuk mengambil baris, ini adalah ukuran set baris baru.

Pengambilan absolut yang dilakukan terhadap kursor dinamis tidak dapat memberikan hasil yang diperlukan karena posisi baris dalam kursor dinamis tidak ditentukan. Operasi semacam itu setara dengan pengambilan terlebih dahulu diikuti oleh relatif pengambilan; ini bukan operasi atom, seperti halnya pengambilan absolut pada kursor statis.

SQL_FETCH_FIRST

Aturan berikut berlaku.

Kondisi Baris pertama set baris baru
Mana pun 1

SQL_FETCH_LAST

Aturan berikut berlaku.

Kondisi Baris pertama set baris baru
RowsetSize [1]<= LastResultRow LastResultRow - RowsetSize + 1 [1]
RowsetSize [1]> LastResultRow 1

[1] Jika ukuran set baris telah diubah sejak panggilan sebelumnya untuk mengambil baris, ini adalah ukuran set baris baru.

SQL_FETCH_BOOKMARK

Aturan berikut berlaku.

Kondisi Baris pertama set baris baru
BookmarkRow + FetchOffset < 1 Sebelum memulai
1 <= BookmarkRow + FetchOffset <= LastResultRow BookmarkRow + FetchOffset
BookmarkRow + FetchOffset > LastResultRow Setelah selesai

Untuk informasi tentang marka buku, lihat Marka Buku (ODBC).

Efek Baris Yang Dihapus, Ditambahkan, dan Kesalahan pada Gerakan Kursor

Kursor statis dan berbasis keyset terkadang mendeteksi baris yang ditambahkan ke kumpulan hasil dan menghapus baris yang dihapus dari kumpulan hasil. Dengan memanggil SQLGetInfo dengan opsi SQL_STATIC_CURSOR_ATTRIBUTES2 dan SQL_KEYSET_CURSOR_ATTRIBUTES2 dan melihat bitmask SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS, dan SQL_CA2_SENSITIVITY_UPDATES, aplikasi menentukan apakah kursor yang diterapkan oleh driver tertentu melakukan ini. Untuk driver yang dapat mendeteksi baris yang dihapus dan menghapusnya, paragraf berikut menjelaskan efek perilaku ini. Untuk driver yang dapat mendeteksi baris yang dihapus tetapi tidak dapat menghapusnya, penghapusan tidak berpengaruh pada gerakan kursor, dan paragraf berikut tidak berlaku.

Jika kursor mendeteksi baris yang ditambahkan ke kumpulan hasil atau menghapus baris yang dihapus dari kumpulan hasil, kursor akan muncul seolah-olah mendeteksi perubahan ini hanya saat mengambil data. Ini termasuk kasus ketika SQLFetchScroll dipanggil dengan FetchOrientation diatur ke SQL_FETCH_RELATIVE dan FetchOffset diatur ke 0 untuk mengambil kembali set baris yang sama, tetapi tidak menyertakan kasus ketika SQLSetPos dipanggil dengan fOption diatur ke SQL_REFRESH. Dalam kasus terakhir, data dalam buffer set baris di-refresh, tetapi tidak diambil kembali, dan baris yang dihapus tidak dihapus dari kumpulan hasil. Dengan demikian, ketika baris dihapus dari atau disisipkan ke dalam set baris saat ini, kursor tidak memodifikasi buffer set baris. Sebaliknya, ia mendeteksi perubahan saat mengambil set baris apa pun yang sebelumnya menyertakan baris yang dihapus atau sekarang menyertakan baris yang disisipkan.

Contohnya:

// Fetch the next rowset.  
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);  
// Delete third row of the rowset. Does not modify the rowset buffers.  
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);  
// The third row has a status of SQL_ROW_DELETED after this call.  
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);  
// Refetch the same rowset. The third row is removed, replaced by what  
// was previously the fourth row.  
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);  

Ketika SQLFetchScroll mengembalikan set baris baru yang memiliki posisi relatif terhadap set baris saat ini - yaitu, FetchOrientation SQL_FETCH_NEXT, SQL_FETCH_PRIOR, atau SQL_FETCH_RELATIVE - itu tidak menyertakan perubahan pada set baris saat ini saat menghitung posisi awal set baris baru. Namun, itu termasuk perubahan di luar set baris saat ini jika mampu mendeteksinya. Selain itu, ketika SQLFetchScroll mengembalikan set baris baru yang memiliki posisi independen dari set baris saat ini - yaitu, FetchOrientation SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE, atau SQL_FETCH_BOOKMARK - itu mencakup semua perubahan yang mampu dideteksi, bahkan jika berada di set baris saat ini.

Saat menentukan apakah baris yang baru ditambahkan berada di dalam atau di luar set baris saat ini, set baris parsial dianggap berakhir pada baris terakhir yang valid; artinya, baris terakhir yang status barisnya tidak SQL_ROW_NOROW. Misalnya, kursor mampu mendeteksi baris yang baru ditambahkan, set baris saat ini adalah set baris parsial, aplikasi menambahkan baris baru, dan kursor menambahkan baris ini ke akhir kumpulan hasil. Jika aplikasi memanggil SQLFetchScroll dengan FetchOrientation diatur ke SQL_FETCH_NEXT, SQLFetchScroll mengembalikan set baris yang dimulai dengan baris pertama yang baru ditambahkan.

Misalnya, set baris saat ini terdiri dari baris 21 hingga 30, ukuran set baris adalah 10, kursor menghapus baris yang dihapus dari kumpulan hasil, dan kursor mendeteksi baris yang ditambahkan ke kumpulan hasil. Tabel berikut ini memperlihatkan baris yang dikembalikan SQLFetchScroll dalam berbagai situasi.

Ubah Jenis pengambilan FetchOffset Set baris baru[1]
Hapus baris 21 NEXT 0 31 hingga 40
Hapus baris 31 NEXT 0 32 hingga 41
Sisipkan baris antara baris 21 dan 22 NEXT 0 31 hingga 40
Sisipkan baris antara baris 30 dan 31 NEXT 0 Baris yang disisipkan, 31 hingga 39
Hapus baris 21 DULU 0 11 hingga 20
Hapus baris 20 DULU 0 10 hingga 19
Sisipkan baris antara baris 21 dan 22 DULU 0 11 hingga 20
Sisipkan baris antara baris 20 dan 21 DULU 0 12 hingga 20, baris yang disisipkan
Hapus baris 21 SANAK 0 22 hingga 31[2]
Hapus baris 21 SANAK 1 22 hingga 31
Sisipkan baris antara baris 21 dan 22 SANAK 0 21, baris yang disisipkan, 22 hingga 29
Sisipkan baris antara baris 21 dan 22 SANAK 1 22 hingga 31
Hapus baris 21 MUTLAK 21 22 hingga 31[2]
Hapus baris 22 MUTLAK 21 21, 23 hingga 31
Sisipkan baris antara baris 21 dan 22 MUTLAK 22 Baris yang disisipkan, 22 hingga 29

[1] Kolom ini menggunakan nomor baris sebelum baris disisipkan atau dihapus.

[2] Dalam hal ini, kursor mencoba mengembalikan baris yang dimulai dengan baris 21. Karena baris 21 telah dihapus, baris pertama yang dikembalikannya adalah baris 22.

Baris kesalahan (yaitu, baris dengan status SQL_ROW_ERROR) tidak memengaruhi gerakan kursor. Misalnya, jika set baris saat ini dimulai dengan baris 11 dan status baris 11 SQL_ROW_ERROR, memanggil SQLFetchScroll dengan FetchOrientation diatur ke SQL_FETCH_RELATIVE dan FetchOffset diatur ke 5 mengembalikan set baris yang dimulai dengan baris 16, sama seperti jika status untuk baris 11 SQL_SUCCESS.

Mengembalikan Data dalam Kolom Terikat

SQLFetchScroll mengembalikan data dalam kolom terikat dengan cara yang sama seperti SQLFetch. Untuk informasi selengkapnya, lihat "Mengembalikan Data dalam Kolom Terikat" di Fungsi SQLFetch.

Jika tidak ada kolom yang terikat, SQLFetchScroll tidak mengembalikan data tetapi memindahkan kursor blok ke posisi yang ditentukan. Apakah data dapat diambil dari kolom kursor blok yang tidak terikat dengan SQLGetData bergantung pada driver. Kemampuan ini didukung jika panggilan ke SQLGetInfo mengembalikan bit SQL_GD_BLOCK untuk jenis informasi SQL_GETDATA_EXTENSIONS.

Alamat Buffer

SQLFetchScroll menggunakan rumus yang sama untuk menentukan alamat buffer data dan panjang/indikator sebagai SQLFetch. Untuk informasi selengkapnya, lihat "Alamat Buffer" di Fungsi SQLBindCol.

Array Status Baris

SQLFetchScroll menetapkan nilai dalam array status baris dengan cara yang sama seperti SQLFetch. Untuk informasi selengkapnya, lihat "Array Status Baris" di Fungsi SQLFetch.

Baris Mengambil Buffer

SQLFetchScroll mengembalikan jumlah baris yang diambil dalam baris yang diambil buffer dengan cara yang sama seperti SQLFetch. Untuk informasi selengkapnya, lihat "Baris Yang Diambil Buffer" di Fungsi SQLFetch.

Penanganan Kesalahan

Ketika aplikasi memanggil SQLFetchScroll di driver ODBC 3.x, Manajer Driver memanggil SQLFetchScroll di driver. Ketika aplikasi memanggil SQLFetchScroll di driver ODBC 2.x, Manajer Driver memanggil SQLExtendedFetch di driver. Karena SQLFetchScroll dan SQLExtendedFetch menangani kesalahan dengan cara yang sedikit berbeda, aplikasi melihat perilaku kesalahan yang sedikit berbeda ketika memanggil SQLFetchScroll di driver ODBC 2.x dan ODBC 3.x.

SQLFetchScroll mengembalikan kesalahan dan peringatan dengan cara yang sama seperti SQLFetch; untuk informasi selengkapnya, lihat "Penanganan Kesalahan" di SQLFetch. SQLExtendedFetch mengembalikan kesalahan dengan cara yang sama seperti SQLFetch, dengan pengecualian berikut:

Saat peringatan terjadi yang berlaku untuk baris tertentu dalam set baris, SQLExtendedFetch mengatur entri terkait dalam array status baris ke SQL_ROW_SUCCESS, bukan SQL_ROW_SUCCESS_WITH_INFO.

Jika kesalahan terjadi di setiap baris dalam set baris, SQLExtendedFetch mengembalikan SQL_SUCCESS_WITH_INFO, bukan SQL_ERROR.

Di setiap grup rekaman status yang berlaku untuk baris individual, rekaman status pertama yang dikembalikan oleh SQLExtendedFetch harus berisi SQLSTATE 01S01 (Kesalahan dalam baris); SQLFetchScroll tidak mengembalikan SQLSTATE ini. Jika SQLExtendedFetch tidak dapat mengembalikan SQLSTATEs tambahan, SQLSTATE ini masih harus mengembalikan SQLSTATE ini.

SQLFetchScroll dan Konkurensi Optimis

Jika kursor menggunakan konkurensi optimis - yaitu, atribut pernyataan SQL_ATTR_CONCURRENCY memiliki nilai SQL_CONCUR_VALUES atau SQL_CONCUR_ROWVER - SQLFetchScroll memperbarui nilai konkurensi optimis yang digunakan oleh sumber data untuk mendeteksi apakah baris telah berubah. Ini terjadi setiap kali SQLFetchScroll mengambil set baris baru, termasuk ketika mengambil kembali set baris saat ini. (Ini disebut dengan FetchOrientation diatur ke SQL_FETCH_RELATIVE dan FetchOffset diatur ke 0.)

Driver SQLFetchScroll dan ODBC 2.x

Ketika aplikasi memanggil SQLFetchScroll di driver ODBC 2.x, Manajer Driver memetakan panggilan ini ke SQLExtendedFetch. Ini meneruskan nilai berikut untuk argumen SQLExtendedFetch.

Argumen SQLExtendedFetch Nilai
StatementHandle StatementHandle di SQLFetchScroll.
FetchOrientation FetchOrientation di SQLFetchScroll.
FetchOffset Jika FetchOrientation tidak SQL_FETCH_BOOKMARK, nilai argumen FetchOffset di SQLFetchScroll digunakan.

Jika FetchOrientation SQL_FETCH_BOOKMARK, nilai yang disimpan di alamat yang ditentukan oleh atribut pernyataan SQL_ATTR_FETCH_BOOKMARK_PTR digunakan.
RowCountPtr Alamat yang ditentukan oleh atribut pernyataan SQL_ATTR_ROWS_FETCHED_PTR.
RowStatusArray Alamat yang ditentukan oleh atribut pernyataan SQL_ATTR_ROW_STATUS_PTR.

Untuk informasi selengkapnya, lihat Memblokir Kursor, Kursor yang Dapat Digulir, dan Kompatibilitas Mundur dalam Lampiran G: Panduan Driver untuk Kompatibilitas Mundur.

Deskriptor dan SQLFetchScroll

SQLFetchScroll berinteraksi dengan deskriptor dengan cara yang sama seperti SQLFetch. Untuk informasi selengkapnya, lihat bagian "Deskriptor dan SQLFetchScroll" di Fungsi SQLFetch.

Contoh Kode

Lihat Pengikatan Kolom-Bijaksana, Pengikatan Row-Wise, Pernyataan Pembaruan dan Penghapusan Yang Diposisikan, dan Memperbarui Baris di Set Baris dengan SQLSetPos.

Untuk informasi tentang Lihat
Mengikat buffer ke kolom dalam tataan hasil Fungsi SQLBindCol
Melakukan operasi menyisipkan, memperbarui, atau menghapus secara massal Fungsi SQLBulkOperations
Membatalkan pemrosesan pernyataan Fungsi SQLCancel
Mengembalikan informasi tentang kolom dalam tataan hasil Fungsi SQLDescribeCol
Menjalankan pernyataan SQL Fungsi SQLExecDirect
Menjalankan pernyataan SQL yang disiapkan Fungsi SQLExecute
Mengambil satu baris atau blok data dalam arah terusan saja Fungsi SQLFetch
Menutup kursor pada pernyataan Fungsi SQLFreeStmt
Mengembalikan jumlah kolom tataan hasil Fungsi SQLNumResultCols
Memosisikan kursor, merefresh data di set baris, atau memperbarui atau menghapus data dalam tataan hasil Fungsi SQLSetPos
Mengatur atribut pernyataan Fungsi SQLSetStmtAttr

Lihat Juga

Referensi API ODBC
File Header ODBC