Fungsi SQLExtendedFetch
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: Tidak digunakan lagi
Ringkasan
SQLExtendedFetch 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.
Catatan
Di ODBC 3*.x*, SQLExtendedFetch telah digantikan oleh SQLFetchScroll. Aplikasi ODBC 3*.x* tidak boleh memanggil SQLExtendedFetch; sebaliknya mereka harus memanggil SQLFetchScroll. Driver Manager memetakan SQLFetchScroll ke SQLExtendedFetch saat bekerja dengan driver ODBC 2*.x*. Driver ODBC 3*.x* harus mendukung SQLExtendedFetch jika mereka ingin bekerja dengan aplikasi ODBC 2*.x* yang menyebutnya. Untuk informasi selengkapnya, lihat "Komentar" dan Blokir Kursor, Kursor yang Dapat Digulir, dan Kompatibilitas Mundur dalam Lampiran G: Panduan Driver untuk Kompatibilitas Mundur.
Sintaks
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Argumen
StatementHandle
[Input] Handel pernyataan.
FetchOrientation
[Input] Jenis pengambilan. Ini sama dengan FetchOrientation di SQLFetchScroll.
FetchOffset
[Input] Jumlah baris yang akan diambil. Ini sama dengan FetchOffset di SQLFetchScroll, dengan satu pengecualian. Ketika FetchOrientation SQL_FETCH_BOOKMARK, FetchOffset adalah bookmark panjang tetap, bukan offset dari bookmark. Dengan kata lain, SQLExtendedFetch mengambil marka buku dari argumen ini, bukan atribut pernyataan SQL_ATTR_FETCH_BOOKMARK_PTR. Ini tidak mendukung marka buku panjang variabel dan tidak mendukung pengambilan set baris pada offset (selain 0) dari marka buku.
RowCountPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah baris yang benar-benar diambil. Buffer ini digunakan dengan cara yang sama seperti buffer yang ditentukan oleh atribut pernyataan SQL_ATTR_ROWS_FETCHED_PTR. Buffer ini hanya digunakan oleh SQLExtendedFetch. Ini tidak digunakan oleh SQLFetch atau SQLFetchScroll.
RowStatusArray
[Output] Penunjuk ke array untuk mengembalikan status setiap baris. Array ini digunakan dengan cara yang sama dengan array yang ditentukan oleh atribut pernyataan SQL_ATTR_ROW_STATUS_PTR.
Namun, alamat array ini tidak disimpan di bidang SQL_DESC_STATUS_ARRAY_PTR di IRD. Selain itu, array ini hanya digunakan oleh SQLExtendedFetch dan oleh SQLBulkOperations dengan Operasi SQL_ADD atau SQLSetPos ketika dipanggil setelah SQLExtendedFetch. Ini tidak digunakan oleh SQLFetch atau SQLFetchScroll, dan tidak digunakan oleh SQLBulkOperations atau SQLSetPos ketika dipanggil setelah SQLFetch atau SQLFetchScroll. Ini juga tidak digunakan ketika SQLBulkOperations dengan Operasi SQL_ADD dipanggil sebelum fungsi pengambilan dipanggil. Dengan kata lain, ini hanya digunakan dalam status pernyataan S7. Ini tidak digunakan dalam pernyataan menyatakan S5 atau S6. Untuk informasi selengkapnya, lihat Transisi Pernyataan di Lampiran B: Tabel Transisi Status ODBC.
Aplikasi harus menyediakan penunjuk yang valid dalam argumen RowStatusArray ; jika tidak, perilaku SQLExtendedFetch dan perilaku panggilan ke SQLBulkOperations atau SQLSetPos setelah kursor diposisikan oleh SQLExtendedFetch tidak ditentukan.
Mengembalikan
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Ketika SQLExtendedFetch mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLError. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLExtendedFetch 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.
| 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. Jika itu adalah nilai numerik, bagian pecahan dari angka tersebut dipotong. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 01S01 | Kesalahan berturut-turut | Terjadi kesalahan saat mengambil satu atau beberapa baris. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 01S06 | Mencoba mengambil sebelum tataan hasil mengembalikan set baris pertama | Himpunan baris yang diminta tumpang tindih dengan awal tataan hasil ketika posisi saat ini berada di luar baris pertama, dan FetchOrientation SQL_PRIOR atau FetchOrientation SQL_RELATIVE dengan FetchOffset negatif yang nilai absolutnya kurang dari atau sama dengan SQL_ROWSET_SIZE saat ini. (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 tidak dapat dikonversi ke jenis data C yang ditentukan oleh TargetType di SQLBindCol. |
| 07009 | Indeks deskriptor tidak valid | Kolom 0 terikat dengan SQLBindCol, 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. |
| 22002 | Variabel indikator diperlukan tetapi tidak disediakan | Data NULL diambil ke dalam kolom yang StrLen_or_IndPtr diatur oleh SQLBindCol adalah penunjuk null. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 22003 | Nilai numerik di luar rentang | Mengembalikan nilai numerik (sebagai numerik atau string) untuk satu atau beberapa kolom akan menyebabkan seluruh (dibandingkan dengan pecahan) bagian dari angka yang akan dipotong. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) Untuk informasi selengkapnya, lihat Panduan untuk Jenis Data Interval dan Numerik 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. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 22012 | Pembagian dengan nol | Nilai dari ekspresi aritmatika dikembalikan, yang menghasilkan pembagian dengan nol. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 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. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 22018 | Nilai karakter tidak valid untuk spesifikasi cast | 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. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 24000 | Status kursor tidak valid | StatementHandle berada dalam status dijalankan, tetapi tidak ada kumpulan hasil yang dikaitkan dengan StatementHandle. |
| HY000 | Kesalahan umum | Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan oleh SQLError 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, dan 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 SQLExtendedFetch 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) SQLExtendedFetch dipanggil untuk StatementHandle setelah SQLFetch atau SQLFetchScroll dipanggil dan sebelum SQLFreeStmt dipanggil dengan opsi SQL_CLOSE. (DM) SQLBulkOperations dipanggil untuk pernyataan sebelum SQLFetch, SQLFetchScroll, atau SQLExtendedFetch dipanggil, dan kemudian SQLExtendedFetch dipanggil sebelum SQLFreeStmt dipanggil dengan opsi SQL_CLOSE. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY106 | Ambil jenis di luar rentang | (DM) Nilai yang ditentukan untuk argumen FetchOrientation tidak valid. (Lihat "Komentar.") Argumen FetchOrientation SQL_FETCH_BOOKMARK, dan atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_OFF. Nilai opsi pernyataan SQL_CURSOR_TYPE SQL_CURSOR_FORWARD_ONLY, dan nilai argumen FetchOrientation tidak SQL_FETCH_NEXT. Argumen FetchOrientation SQL_FETCH_RESUME. |
| HY107 | Nilai baris di luar rentang | Nilai yang ditentukan dengan opsi pernyataan SQL_CURSOR_TYPE SQL_CURSOR_KEYSET_DRIVEN, tetapi nilai yang ditentukan dengan atribut pernyataan SQL_KEYSET_SIZE lebih besar dari 0 dan kurang dari nilai yang ditentukan dengan atribut pernyataan SQL_ROWSET_SIZE. |
| HY111 | Nilai marka buku tidak valid | Argumen FetchOrientation SQL_FETCH_BOOKMARK, dan bookmark yang ditentukan dalam argumen FetchOffset tidak valid. |
| 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 jenis pengambilan yang ditentukan. Driver atau sumber data tidak mendukung konversi yang ditentukan oleh kombinasi TargetType di SQLBindCol dan jenis data SQL dari kolom yang sesuai. Kesalahan ini hanya berlaku ketika jenis data SQL kolom dipetakan ke jenis data SQL khusus driver. |
| HYT00 | Waktu habis kedaluwarsa | Periode batas waktu kueri kedaluwarsa sebelum sumber data mengembalikan tataan hasil. Periode batas waktu diatur melalui SQLSetStmtOption, SQL_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. |
Komentar
Perilaku SQLExtendedFetch identik dengan SQLFetchScroll, dengan pengecualian berikut:
SQLExtendedFetch dan SQLFetchScroll menggunakan metode yang berbeda untuk mengembalikan jumlah baris yang diambil. SQLExtendedFetch mengembalikan jumlah baris yang diambil dalam *RowCountPtr; SQLFetchScroll mengembalikan jumlah baris yang diambil langsung ke buffer yang ditunjukkan oleh SQL_ATTR_ROWS_FETCHED_PTR. Untuk informasi selengkapnya, lihat argumen RowCountPtr .
SQLExtendedFetch dan SQLFetchScroll mengembalikan status setiap baris dalam array yang berbeda. Untuk informasi selengkapnya, lihat argumen RowStatusArray .
SQLExtendedFetch dan SQLFetchScroll menggunakan metode yang berbeda untuk mengambil marka buku saat FetchOrientation SQL_FETCH_BOOKMARK. SQLExtendedFetch tidak mendukung bookmark panjang variabel atau mengambil set baris pada offset selain 0 dari bookmark. Untuk informasi selengkapnya, lihat argumen FetchOffset .
SQLExtendedFetch dan SQLFetchScroll menggunakan ukuran set baris yang berbeda. SQLExtendedFetch menggunakan nilai atribut pernyataan SQL_ROWSET_SIZE, dan SQLFetchScroll menggunakan nilai atribut pernyataan SQL_ATTR_ROW_ARRAY_SIZE.
SQLExtendedFetch memiliki semantik penanganan kesalahan yang sedikit berbeda dari SQLFetchScroll. Untuk informasi selengkapnya, lihat "Penanganan Kesalahan" di bagian "Komentar" di SQLFetchScroll.
SQLExtendedFetch tidak mendukung offset pengikatan (atribut pernyataan SQL_ATTR_ROW_BIND_OFFSET_PTR).
Panggilan ke SQLExtendedFetch tidak dapat dicampur dengan panggilan ke SQLFetch atau SQLFetchScroll, dan jika SQLBulkOperations dipanggil sebelum fungsi pengambilan dipanggil, SQLExtendedFetch tidak dapat dipanggil sampai kursor ditutup dan dibuka kembali. Artinya, SQLExtendedFetch hanya dapat dipanggil dalam status pernyataan S7. Untuk informasi selengkapnya, lihat Transisi Pernyataan di Lampiran B: Tabel Transisi Status ODBC.
Ketika aplikasi memanggil SQLFetchScroll saat menggunakan driver ODBC 2*.x*, Manajer Driver memetakan panggilan ini ke SQLExtendedFetch. Untuk informasi selengkapnya, lihat "Driver SQLFetchScroll dan ODBC 2*.x* di SQLFetchScroll.
Di ODBC 2*.x*, SQLExtendedFetch dipanggil untuk mengambil beberapa baris dan SQLFetch dipanggil untuk mengambil satu baris. Di ODBC 3*.x*, di sisi lain, SQLFetch dapat dipanggil untuk mengambil beberapa baris.
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 |
| 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 |