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".
Kembali
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 | Arti |
|---|---|
| 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 | Arti |
|---|---|
| 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 | SEBELUMNYA | 0 | 11 hingga 20 |
| Hapus baris 20 | SEBELUMNYA | 0 | 10 hingga 19 |
| Sisipkan baris antara baris 21 dan 22 | SEBELUMNYA | 0 | 11 hingga 20 |
| Sisipkan baris antara baris 20 dan 21 | SEBELUMNYA | 0 | 12 hingga 20, baris yang disisipkan |
| Hapus baris 21 | RELATIF | 0 | 22 hingga 31[2] |
| Hapus baris 21 | RELATIF | 1 | 22 hingga 31 |
| Sisipkan baris antara baris 21 dan 22 | RELATIF | 0 | 21, baris yang disisipkan, 22 hingga 29 |
| Sisipkan baris antara baris 21 dan 22 | RELATIF | 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.
Fungsi Terkait
| 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
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk