Fungsi SQLFetch
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLFetch mengambil kumpulan baris data berikutnya dari kumpulan hasil dan mengembalikan data untuk semua kolom terikat.
Sintaks
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Argumen
StatementHandle
[Input] Handel pernyataan.
Mengembalikan
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLFetch mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil Fungsi SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan Handle of StatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLFetch 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 terjadi kesalahan 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.) |
| 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 SQLFetch dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle. Kemudian fungsi SQLFetch dipanggil lagi pada StatementHandle. Atau, fungsi SQLFetch 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 SQLFetch 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.) |
| 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. |
| 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
SQLFetch mengembalikan set baris berikutnya dalam tataan hasil. Ini 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, SQLFetch juga mengembalikan informasi ini. Panggilan ke SQLFetch dapat dicampur dengan panggilan ke SQLFetchScroll tetapi tidak dapat dicampur dengan panggilan ke SQLExtendedFetch. Untuk informasi selengkapnya, lihat Mengambil Baris Data.
Jika aplikasi ODBC 3*.x* berfungsi dengan driver ODBC 2*.x*, Manajer Driver memetakan panggilan SQLFetch ke SQLExtendedFetch untuk driver ODBC 2*.x* yang mendukung SQLExtendedFetch. Jika driver ODBC 2*.x* tidak mendukung SQLExtendedFetch, Manajer Driver memetakan panggilan SQLFetch ke SQLFetch di driver ODBC 2*.x*, yang hanya dapat mengambil satu baris.
Untuk informasi selengkapnya, lihat Memblokir Kursor, Kursor yang Dapat Digulir, dan Kompatibilitas Mundur dalam Lampiran G: Panduan Driver untuk Kompatibilitas Mundur.
Memosisikan Kursor
Saat tataan hasil dibuat, kursor diposisikan sebelum awal kumpulan hasil. SQLFetch mengambil set baris berikutnya. Setara dengan memanggil SQLFetchScroll dengan FetchOrientation diatur ke SQL_FETCH_NEXT. Untuk informasi selengkapnya tentang kursor, lihat Kursor dan Blokir Kursor.
Atribut pernyataan SQL_ATTR_ROW_ARRAY_SIZE menentukan jumlah baris dalam set baris. Jika kumpulan baris yang diambil oleh SQLFetch tumpang tindih dengan akhir kumpulan hasil, SQLFetch 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 SQLFetch kembali, baris saat ini adalah baris pertama dari set baris.
Aturan yang tercantum dalam tabel berikut ini menjelaskan penempatan kursor setelah panggilan ke SQLFetch, berdasarkan kondisi yang tercantum dalam tabel kedua di bagian ini.
| Kondisi | Baris pertama set baris baru |
|---|---|
| Sebelum memulai | 1 |
| CurrRowsetStart<= LastResultRow - RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow - RowsetSize[1] | Setelah selesai |
| Setelah selesai | Setelah selesai |
[1] Jika ukuran set baris diubah di antara pengambilan, ini adalah ukuran set baris yang digunakan dengan pengambilan sebelumnya.
[2] Jika ukuran set baris diubah di antara pengambilan, ini adalah ukuran set baris yang digunakan dengan pengambilan baru.
| Notasi | Makna |
|---|---|
| Sebelum memulai | Kursor blok diposisikan sebelum awal tataan hasil. Jika baris pertama dari set baris baru adalah sebelum awal kumpulan hasil, SQLFetch mengembalikan SQL_NO_DATA. |
| Setelah selesai | Kursor blok diposisikan setelah akhir tataan hasil. Jika baris pertama dari set baris baru setelah akhir tataan hasil, SQLFetch mengembalikan SQL_NO_DATA. |
| CurrRowsetStart | Jumlah baris pertama dalam set baris saat ini. |
| LastResultRow | Jumlah baris terakhir dalam tataan hasil. |
| RowsetSize | Ukuran set baris. |
Misalnya, set hasil memiliki 100 baris dan ukuran set baris adalah 5. Tabel berikut ini memperlihatkan set baris dan mengembalikan kode yang dikembalikan oleh SQLFetch untuk posisi awal yang berbeda.
| Set baris saat ini | Mengembalikan kode | Set baris baru | # dari baris yang diambil |
|---|---|---|---|
| Sebelum memulai | SQL_SUCCESS | 1 hingga 5 | 5 |
| 1 hingga 5 | SQL_SUCCESS | 6 hingga 10 | 5 |
| 52 hingga 56 | SQL_SUCCESS | 57 hingga 61 | 5 |
| 91 hingga 95 | SQL_SUCCESS | 96 hingga 100 | 5 |
| 93 hingga 97 | SQL_SUCCESS | 98 sampai 100. Baris 4 dan 5 dari array status baris diatur ke SQL_ROW_NOROW. | 3 |
| 96 hingga 100 | SQL_NO_DATA | Tidak ada. | 0 |
| 99 hingga 100 | SQL_NO_DATA | Tidak ada. | 0 |
| Setelah selesai | SQL_NO_DATA | Tidak ada. | 0 |
Mengembalikan Data dalam Kolom Terikat
Saat SQLFetch mengembalikan setiap baris, SQLFetch menempatkan data untuk setiap kolom terikat di buffer yang terikat ke kolom tersebut. Jika tidak ada kolom yang terikat, SQLFetch tidak mengembalikan data tetapi memindahkan kursor blok ke depan. Data masih dapat diambil dengan menggunakan SQLGetData. Jika kursor adalah kursor multirow (yaitu, SQL_ATTR_ROW_ARRAY_SIZE lebih besar dari 1), SQLGetData dapat dipanggil hanya jika SQL_GD_BLOCK dikembalikan ketika SQLGetInfo dipanggil dengan InfoType SQL_GETDATA_EXTENSIONS. (Untuk informasi selengkapnya, lihat SQLGetData.)
Untuk setiap kolom terikat berturut-turut, SQLFetch melakukan hal berikut:
Mengatur buffer panjang/indikator ke SQL_NULL_DATA dan melanjutkan ke kolom berikutnya jika data adalah NULL. Jika data NULL dan tidak ada buffer panjang/indikator yang terikat, SQLFetch mengembalikan SQLSTATE 22002 (Variabel indikator diperlukan tetapi tidak disediakan) untuk baris dan melanjutkan ke baris berikutnya. Untuk informasi tentang cara menentukan alamat buffer panjang/indikator, lihat "Alamat Buffer" di SQLBindCol.
Jika data untuk kolom bukan NULL, SQLFetch melanjutkan ke langkah 2.
Jika atribut pernyataan SQL_ATTR_MAX_LENGTH diatur ke nilai bukan nol dan kolom berisi karakter atau data biner, data dipotong menjadi SQL_ATTR_MAX_LENGTH byte.
Catatan
Atribut pernyataan SQL_ATTR_MAX_LENGTH dimaksudkan untuk mengurangi lalu lintas jaringan. Ini umumnya diimplementasikan oleh sumber data, yang memotong data sebelum mengembalikannya melalui jaringan. Driver dan sumber data tidak diperlukan untuk mendukungnya. Oleh karena itu, untuk menjamin bahwa data dipotong ke ukuran tertentu, aplikasi harus mengalokasikan buffer ukuran tersebut dan menentukan ukuran dalam argumen cbValueMax di SQLBindCol.
Mengonversi data ke jenis yang ditentukan oleh TargetType di SQLBindCol.
Jika data dikonversi ke jenis data panjang variabel, seperti karakter atau biner, SQLFetch memeriksa apakah panjang data melebihi panjang buffer data. Jika panjang data karakter (termasuk karakter penghentian null) melebihi panjang buffer data, SQLFetch memotong data ke panjang buffer data kurang panjang karakter penghentian null. Kemudian, data akan dihentikan null. Jika panjang data biner melebihi panjang buffer data, SQLFetch memotongnya hingga panjang buffer data. Panjang buffer data ditentukan dengan BufferLength di SQLBindCol.
SQLFetch tidak pernah memotong data yang dikonversi ke jenis data dengan panjang tetap; SQLFetch selalu mengasumsikan bahwa panjang buffer data adalah ukuran jenis data.
Menempatkan data yang dikonversi (dan mungkin terpotong) dalam buffer data. Untuk informasi tentang cara menentukan alamat buffer data, lihat "Alamat Buffer" di SQLBindCol.
Menempatkan panjang data dalam buffer panjang/indikator. Jika penunjuk indikator dan penunjuk panjang keduanya diatur ke buffer yang sama (seperti panggilan ke SQLBindCol ), panjangnya ditulis dalam buffer untuk data yang valid dan SQL_NULL_DATA ditulis dalam buffer untuk data NULL. Jika tidak ada buffer panjang/indikator yang terikat, SQLFetch tidak mengembalikan panjangnya.
Untuk data karakter atau biner, ini adalah panjang data setelah konversi dan sebelum pemotongan karena buffer data terlalu kecil. Jika driver tidak dapat menentukan panjang data setelah konversi, seperti halnya kadang-kadang dengan data panjang, driver mengatur panjang ke SQL_NO_TOTAL. Jika data dipotong karena atribut pernyataan SQL_ATTR_MAX_LENGTH, nilai atribut ini dimasukkan ke dalam buffer panjang/indikator alih-alih panjang aktual . Ini karena atribut ini dirancang untuk memotong data pada server sebelum konversi, sehingga driver tidak memiliki cara untuk mencari tahu berapa panjang sebenarnya.
Untuk semua jenis data lainnya, ini adalah panjang data setelah konversi; artinya, itu adalah ukuran jenis yang datanya dikonversi.
Untuk informasi tentang cara menentukan alamat buffer panjang/indikator, lihat "Alamat Buffer" di SQLBindCol.
Jika data dipotong selama konversi tanpa kehilangan digit signifikan (misalnya, angka riil 1,234 dipotong ke bilangan bulat 1 saat dikonversi), SQLFetch mengembalikan SQLSTATE 01S07 (Pemotongan pecahan) dan SQL_SUCCESS_WITH_INFO. Jika data dipotong karena panjang buffer data terlalu kecil (misalnya, string "abcdef" dimasukkan ke dalam buffer 4 byte), SQLFetch mengembalikan SQLSTATE 01004 (Data terpotong) dan SQL_SUCCESS_WITH_INFO. Jika data dipotong karena atribut pernyataan SQL_ATTR_MAX_LENGTH, SQLFetch mengembalikan SQL_SUCCESS dan tidak mengembalikan SQLSTATE 01S07 (Pemotongan pecahan) atau SQLSTATE 01004 (Data terpotong). Jika data dipotong selama konversi dengan hilangnya digit signifikan (misalnya, jika nilai SQL_INTEGER yang lebih besar dari 100.000 dikonversi ke SQL_C_TINYINT), SQLFetch mengembalikan SQLSTATE 22003 (Nilai numerik di luar rentang) dan SQL_ERROR (jika ukuran set baris adalah 1) atau SQL_SUCCESS_WITH_INFO (jika ukuran set baris lebih besar dari 1).
Konten buffer data terikat dan buffer panjang/indikator tidak ditentukan jika SQLFetch atau SQLFetchScroll tidak mengembalikan SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO.
Array Status Baris
Array status baris digunakan untuk mengembalikan status setiap baris dalam set baris. Alamat array ini ditentukan dengan atribut pernyataan SQL_ATTR_ROW_STATUS_PTR. Array dialokasikan oleh aplikasi dan harus memiliki elemen sebanyak yang ditentukan oleh atribut pernyataan SQL_ATTR_ROW_ARRAY_SIZE. Nilainya ditetapkan oleh SQLFetch, SQLFetchScroll, dan SQLBulkOperations atau SQLSetPos (kecuali ketika mereka telah dipanggil setelah kursor diposisikan oleh SQLExtendedFetch). Jika nilai atribut pernyataan SQL_ATTR_ROW_STATUS_PTR adalah penunjuk null, fungsi-fungsi ini tidak mengembalikan status baris.
Konten buffer array status baris tidak ditentukan jika SQLFetch atau SQLFetchScroll tidak mengembalikan SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO.
Nilai berikut dikembalikan dalam array status baris.
| Nilai array status baris | Deskripsi |
|---|---|
| SQL_ROW_SUCCESS | Baris berhasil diambil dan belum berubah sejak terakhir diambil dari kumpulan hasil ini. |
| SQL_ROW_SUCCESS_WITH_INFO | Baris berhasil diambil dan belum berubah sejak terakhir diambil dari kumpulan hasil ini. Namun, peringatan dikembalikan tentang baris tersebut. |
| SQL_ROW_ERROR | Terjadi kesalahan saat mengambil baris. |
| SQL_ROW_UPDATED[1],[2], dan [3] | Baris berhasil diambil dan telah berubah sejak terakhir diambil dari kumpulan hasil ini. Jika baris diambil lagi dari kumpulan hasil ini atau di-refresh oleh SQLSetPos, status diubah ke status baru baris. |
| SQL_ROW_DELETED[3] | Baris telah dihapus sejak terakhir kali diambil dari kumpulan hasil ini. |
| SQL_ROW_ADDED[4] | Baris disisipkan oleh SQLBulkOperations. Jika baris diambil lagi dari kumpulan hasil ini atau di-refresh oleh SQLSetPos, statusnya adalah SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | Set baris tumpang tindih pada akhir kumpulan hasil, dan tidak ada baris yang dikembalikan yang sesuai dengan elemen array status baris ini. |
[1] Untuk kursor keyset, campuran, dan dinamis, jika nilai kunci diperbarui, baris data dianggap telah dihapus dan baris baru ditambahkan.
[2] Beberapa driver tidak dapat mendeteksi pembaruan pada data dan karenanya tidak dapat mengembalikan nilai ini. Untuk menentukan apakah driver dapat mendeteksi pembaruan untuk baris yang diambil ulang, aplikasi memanggil SQLGetInfo dengan opsi SQL_ROW_UPDATES.
[3] SQLFetch hanya dapat mengembalikan nilai ini ketika diintermiks dengan panggilan ke SQLFetchScroll. Ini karena SQLFetch bergerak maju melalui tataan hasil dan ketika digunakan secara eksklusif, tidak mengambil ulang baris apa pun. Karena tidak ada baris yang diambil ulang, SQLFetch tidak mendeteksi perubahan yang dibuat pada baris yang diambil sebelumnya. Namun, jika SQLFetchScroll memposisikan kursor sebelum baris yang diambil sebelumnya dan SQLFetch digunakan untuk mengambil baris tersebut, SQLFetch dapat mendeteksi perubahan apa pun pada baris tersebut.
[4] Dikembalikan oleh SQLBulkOperations saja. Tidak diatur oleh SQLFetch atau SQLFetchScroll.
Baris Mengambil Buffer
Buffer yang diambil baris digunakan untuk mengembalikan jumlah baris yang diambil, termasuk baris yang tidak ada data yang dikembalikan karena terjadi kesalahan saat diambil. Dengan kata lain, ini adalah jumlah baris yang nilainya dalam array status baris tidak SQL_ROW_NOROW. Alamat buffer ini ditentukan dengan atribut pernyataan SQL_ATTR_ROWS_FETCHED_PTR. Buffer dialokasikan oleh aplikasi. Ini diatur oleh SQLFetch dan SQLFetchScroll. Jika nilai atribut pernyataan SQL_ATTR_ROWS_FETCHED_PTR adalah penunjuk null, fungsi ini tidak mengembalikan jumlah baris yang diambil. Untuk menentukan jumlah baris saat ini dalam kumpulan hasil, aplikasi dapat memanggil SQLGetStmtAttr dengan atribut SQL_ATTR_ROW_NUMBER.
Konten baris yang diambil buffer tidak ditentukan jika SQLFetch atau SQLFetchScroll tidak mengembalikan SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO, kecuali ketika SQL_NO_DATA dikembalikan, dalam hal ini nilai dalam baris buffer yang diambil diatur ke 0.
Penanganan Kesalahan
Kesalahan dan peringatan dapat berlaku untuk baris individual atau ke seluruh fungsi. Untuk informasi selengkapnya tentang catatan diagnostik, lihat Diagnostik dan SQLGetDiagField.
Kesalahan dan Peringatan pada Seluruh Fungsi
Jika kesalahan berlaku untuk seluruh fungsi, seperti SQLSTATE HYT00 (Waktu Habis kedaluwarsa) atau SQLSTATE 24000 (Status kursor tidak valid), SQLFetch mengembalikan SQL_ERROR dan SQLSTATE yang berlaku. Konten buffer set baris tidak terdefinisi dan posisi kursor tidak berubah.
Jika peringatan berlaku untuk seluruh fungsi, SQLFetch mengembalikan SQL_SUCCESS_WITH_INFO dan SQLSTATE yang berlaku. Rekaman status untuk peringatan yang berlaku untuk seluruh fungsi dikembalikan sebelum rekaman status yang berlaku untuk baris individual.
Kesalahan dan Peringatan dalam Baris Individual
Jika kesalahan (seperti SQLSTATE 22012 (Divisi dengan nol)) atau peringatan (seperti SQLSTATE 01004 (Data terpotong)) berlaku untuk satu baris, SQLFetchmelakukan hal berikut:
Mengatur elemen terkait dari array status baris ke SQL_ROW_ERROR untuk kesalahan atau SQL_ROW_SUCCESS_WITH_INFO untuk peringatan.
Menambahkan nol atau lebih rekaman status yang berisi SQLSTATEs untuk kesalahan atau peringatan.
Mengatur bidang baris dan nomor kolom dalam rekaman status. Jika SQLFetch tidak dapat menentukan nomor baris atau kolom, SQLFetch mengatur angka tersebut ke SQL_ROW_NUMBER_UNKNOWN atau SQL_COLUMN_NUMBER_UNKNOWN. Jika catatan status tidak berlaku untuk kolom tertentu, SQLFetch mengatur nomor kolom ke SQL_NO_COLUMN_NUMBER.
SQLFetch terus mengambil baris hingga mengambil semua baris dalam set baris. Ini mengembalikan SQL_SUCCESS_WITH_INFO kecuali kesalahan terjadi di setiap baris set baris (tidak termasuk baris dengan status SQL_ROW_NOROW), dalam hal ini mengembalikan SQL_ERROR. Secara khusus, jika ukuran set baris adalah 1 dan kesalahan terjadi di baris tersebut, SQLFetch mengembalikan SQL_ERROR.
SQLFetch mengembalikan rekaman status dalam urutan nomor baris. Artinya, ia mengembalikan semua rekaman status untuk baris yang tidak diketahui (jika ada); selanjutnya mengembalikan semua rekaman status untuk baris pertama (jika ada), lalu mengembalikan semua rekaman status untuk baris kedua (jika ada), dan sebagainya. Rekaman status untuk setiap baris diurutkan sesuai dengan aturan normal untuk mengurutkan rekaman status; untuk informasi selengkapnya, lihat "Urutan Rekaman Status" di SQLGetDiagField.
Deskriptor dan SQLFetch
Bagian berikut menjelaskan bagaimana SQLFetch berinteraksi dengan deskriptor.
Pemetaan Argumen
Driver tidak mengatur bidang deskriptor apa pun berdasarkan argumen SQLFetch.
Bidang Deskriptor Lainnya
Bidang deskriptor berikut digunakan oleh SQLFetch.
| Bidang deskriptor | Desc. | Bidang dalam | Atur melalui |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | {i>header | atribut pernyataan SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | {i>header | atribut pernyataan SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | ARD | {i>header | atribut pernyataan SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | ARD | {i>header | atribut pernyataan SQL_ATTR_ROW_BIND_TYPE |
| SQL_DESC_COUNT | ARD | {i>header | Argumen ColumnNumber dari SQLBindCol |
| SQL_DESC_DATA_PTR | ARD | Catatan | Argumen TargetValuePtr dari SQLBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | Catatan | argumen StrLen_or_IndPtr di SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | Catatan | Argumen BufferLength di SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | Catatan | argumen StrLen_or_IndPtr di SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | {i>header | atribut pernyataan SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | ARD | Catatan | Argumen TargetType di SQLBindCol |
Semua bidang deskriptor juga dapat diatur melalui SQLSetDescField.
Panjang Terpisah dan Buffer Indikator
Aplikasi dapat mengikat buffer tunggal atau dua buffer terpisah yang dapat digunakan untuk menahan panjang dan nilai indikator. Ketika aplikasi memanggil SQLBindCol, driver mengatur bidang SQL_DESC_OCTET_LENGTH_PTR dan SQL_DESC_INDICATOR_PTR ARD ke alamat yang sama, yang diteruskan dalam argumen StrLen_or_IndPtr . Saat aplikasi memanggil SQLSetDescField atau SQLSetDescRec, aplikasi dapat mengatur kedua bidang ini ke alamat yang berbeda.
SQLFetch menentukan apakah aplikasi telah menentukan panjang terpisah dan buffer indikator. Dalam hal ini, ketika data bukan NULL, SQLFetch mengatur buffer indikator ke 0 dan mengembalikan panjang dalam buffer panjang. Ketika data NULL, SQLFetch mengatur buffer indikator ke SQL_NULL_DATA dan tidak mengubah buffer panjang.
Contoh Kode
Lihat SQLBindCol, SQLColumns, SQLGetData, dan SQLProcedures.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat buffer ke kolom dalam tataan hasil | Fungsi SQLBindCol |
| 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 blok data atau menggulir melalui kumpulan hasil | Fungsi SQLFetchScroll |
| Menutup kursor pada pernyataan | Fungsi SQLFreeStmt |
| Mengambil bagian atau semua kolom data | Fungsi SQLGetData |
| Mengembalikan jumlah kolom tataan hasil | Fungsi SQLNumResultCols |
| Menyiapkan pernyataan untuk eksekusi | Fungsi SQLPrepare |