Bagikan melalui

Fungsi SQLMoreResults

  • Artikel

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 1.0: ODBC

Ringkasan
SQLMoreResults menentukan apakah lebih banyak hasil tersedia pada pernyataan yang berisi pernyataan SELECT, UPDATE, INSERT, atau DELETE dan, jika demikian, menginisialisasi pemrosesan untuk hasil tersebut.

Sintaks

  
SQLRETURN SQLMoreResults(  
     SQLHSTMT     StatementHandle);

Argumen

StatementHandle
[Input] Handel pernyataan.

Kembali

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE, ATAU SQL_PARAM_DATA_AVAILABLE.

Diagnostik

Saat SQLMoreResults 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 SQLMoreResults 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.

SQLSTATE Kesalahan Deskripsi
01000 Peringatan umum Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01S02 Nilai opsi telah berubah Nilai atribut pernyataan berubah saat batch sedang diproses. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
08S01 Kegagalan tautan komunikasi Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses.
40001 Kegagalan serialisasi Transaksi digulung balik karena kebuntuan sumber daya dengan transaksi lain.
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 SQLMoreResults dipanggil dan, sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle. Kemudian fungsi SQLMoreResults dipanggil lagi pada StatementHandle.

Fungsi SQLMoreResults 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 SQLMoreResults dipanggil.

(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.
HY013 Kesalahan manajemen memori Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah.
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.
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

Pernyataan SELECT mengembalikan tataan hasil. Pernyataan UPDATE, INSERT, dan DELETE mengembalikan jumlah baris yang terpengaruh. Jika salah satu pernyataan ini di-batch, dikirimkan dengan array parameter (bernomor dalam urutan parameter yang meningkat, dalam urutan yang muncul dalam batch), atau dalam prosedur, mereka dapat mengembalikan beberapa kumpulan hasil atau jumlah baris. Untuk informasi tentang batch pernyataan dan array parameter, lihat Batch Pernyataan SQL dan Array Nilai Parameter.

Setelah menjalankan batch, aplikasi diposisikan pada tataan hasil pertama. Aplikasi ini dapat memanggil SQLBindCol, SQLBulkOperations, SQLFetch, SQLGetData, SQLFetchScroll, SQLSetPos, dan semua fungsi metadata, pada kumpulan hasil pertama atau berikutnya, sama seperti jika hanya ada satu tataan hasil. Setelah selesai dengan tataan hasil pertama, aplikasi memanggil SQLMoreResults untuk pindah ke tataan hasil berikutnya. Jika kumpulan atau jumlah hasil lain tersedia, SQLMoreResults mengembalikan SQL_SUCCESS dan menginisialisasi kumpulan hasil atau hitungan untuk pemrosesan tambahan. Jika ada pernyataan pembuatan jumlah baris yang muncul di antara pernyataan pembuatan set hasil, pernyataan tersebut dapat dilangkahi dengan memanggil SQLMoreResults. Setelah memanggil SQLMoreResults untuk pernyataan UPDATE, INSERT, atau DELETE, aplikasi dapat memanggil SQLRowCount.

Jika ada tataan hasil saat ini dengan baris yang tidak di-fetch, SQLMoreResults akan membuang tataan hasil tersebut dan membuat tataan hasil atau hitungan berikutnya tersedia. Jika semua hasil telah diproses, SQLMoreResults mengembalikan SQL_NO_DATA. Untuk beberapa driver, parameter output dan nilai pengembalian tidak tersedia sampai semua tataan hasil dan jumlah baris telah diproses. Untuk driver tersebut, parameter output dan nilai pengembalian tersedia saat SQLMoreResults mengembalikan SQL_NO_DATA.

Setiap pengikatan yang ditetapkan untuk kumpulan hasil sebelumnya masih tetap valid. Jika struktur kolom berbeda untuk kumpulan hasil ini, maka memanggil SQLFetch atau SQLFetchScroll dapat mengakibatkan kesalahan atau pemotongan. Untuk mencegah hal ini, aplikasi harus memanggil SQLBindCol untuk secara eksplisit mengikat ulang sebagaimana mestinya (atau melakukannya dengan mengatur bidang deskriptor). Atau, aplikasi dapat memanggil SQLFreeStmt dengan Opsi SQL_UNBIND untuk membongkar semua buffer kolom.

Nilai atribut pernyataan, seperti jenis kursor, konkurensi kursor, ukuran set kunci, atau panjang maksimum, dapat berubah saat aplikasi menavigasi melalui batch dengan panggilan ke SQLMoreResults. Jika ini terjadi, SQLMoreResults akan mengembalikan SQL_SUCCESS_WITH_INFO dan SQLSTATE 01S02 (Nilai opsi telah berubah).

Memanggil SQLCloseCursor, atau SQLFreeStmt dengan Opsi SQL_CLOSE, membuang semua kumpulan hasil dan jumlah baris yang tersedia sebagai akibat dari eksekusi batch. Handel pernyataan kembali ke status yang dialokasikan atau disiapkan. Memanggil SQLCancel untuk membatalkan fungsi eksekusi asinkron ketika batch telah dijalankan dan handel pernyataan berada dalam status dijalankan, diposisikan kursor, atau asinkron menghasilkan semua kumpulan hasil dan jumlah baris yang dihasilkan oleh batch yang dibuang jika panggilan pembatalan berhasil. Pernyataan kemudian kembali ke status yang disiapkan atau dialokasikan.

Jika kumpulan pernyataan atau prosedur mencampur pernyataan SQL lainnya dengan pernyataan SELECT, UPDATE, INSERT, dan DELETE , pernyataan lain ini tidak memengaruhi SQLMoreResults.

Untuk informasi selengkapnya, lihat Beberapa Hasil.

Jika pernyataan pembaruan, sisipkan, atau hapus yang dicari dalam kumpulan pernyataan tidak memengaruhi baris apa pun di sumber data, SQLMoreResults mengembalikan SQL_SUCCESS. Ini berbeda dari kasus pembaruan yang dicari, sisipkan, atau hapus pernyataan yang dijalankan melalui SQLExecDirect, SQLExecute, atau SQLParamData, yang mengembalikan SQL_NO_DATA jika tidak memengaruhi baris apa pun di sumber data. Jika aplikasi memanggil SQLRowCount untuk mengambil jumlah baris setelah panggilan ke SQLMoreResults belum memengaruhi baris apa pun, SQLRowCount akan mengembalikan SQL_NO_DATA.

Untuk informasi tambahan tentang pengurutan fungsi pemrosesan hasil yang valid, lihat Lampiran B: Tabel Transisi Status ODBC.

Untuk informasi selengkapnya tentang parameter output SQL_PARAM_DATA_AVAILABLE dan streaming, lihat Mengambil Parameter Output Menggunakan SQLGetData.

Ketersediaan Jumlah Baris

Saat batch berisi beberapa pernyataan pembuatan jumlah baris berturut-turut, ada kemungkinan jumlah baris ini digulung menjadi hanya satu jumlah baris. Misalnya, jika batch memiliki lima pernyataan sisipan, sumber data tertentu mampu mengembalikan lima jumlah baris individual. Sumber data tertentu lainnya hanya mengembalikan satu jumlah baris yang mewakili jumlah lima jumlah baris individual.

Saat batch berisi kombinasi hasil yang dihasilkan set dan pernyataan pembuatan jumlah baris, jumlah baris mungkin atau mungkin tidak tersedia sama sekali. Perilaku driver sehubungan dengan ketersediaan jumlah baris dijumlahkan dalam jenis informasi SQL_BATCH_ROW_COUNT yang tersedia melalui panggilan ke SQLGetInfo. Misalnya, misalkan bahwa batch berisi SELECT, diikuti oleh dua INSERTs dan SELECT lainnya. Kemudian kasus-kasus berikut dimungkinkan:

  • Jumlah baris yang sesuai dengan dua pernyataan INSERT tidak tersedia sama sekali. Panggilan pertama ke SQLMoreResults akan memposisikan Anda pada kumpulan hasil pernyataan SELECT kedua.

  • Jumlah baris yang sesuai dengan dua pernyataan INSERT tersedia satu per satu. (Panggilan ke SQLGetInfo tidak mengembalikan bit SQL_BRC_ROLLED_UP untuk jenis informasi SQL_BATCH_ROW_COUNT.) Panggilan pertama ke SQLMoreResults akan memposisikan Anda pada jumlah baris INSERT pertama, dan panggilan kedua akan memposisikan Anda pada jumlah baris INSERT kedua. Panggilan ketiga ke SQLMoreResults akan memposisikan Anda pada kumpulan hasil pernyataan SELECT kedua.

  • Jumlah baris yang sesuai dengan dua INSERT digulung menjadi satu jumlah baris tunggal yang tersedia. (Panggilan ke SQLGetInfo mengembalikan bit SQL_BRC_ROLLED_UP untuk jenis informasi SQL_BATCH_ROW_COUNT.) Panggilan pertama ke SQLMoreResults akan memposisikan Anda pada jumlah baris yang digulung, dan panggilan kedua ke SQLMoreResults akan memposisikan Anda pada kumpulan hasil SELECT kedua.

Driver tertentu membuat jumlah baris hanya tersedia untuk batch eksplisit dan bukan untuk prosedur tersimpan.

Untuk informasi tentang Lihat
Membatalkan pemrosesan pernyataan Fungsi SQLCancel
Mengambil blok data atau menggulir melalui kumpulan hasil Fungsi SQLFetchScroll
Mengambil satu baris atau blok data dalam arah terusan saja Fungsi SQLFetch
Mengambil bagian atau semua kolom data Fungsi SQLGetData

Lihat Juga

Referensi API ODBC
File Header ODBC
Mengambil Parameter Output Menggunakan SQLGetData