Mengambil Baris Data

Untuk mengambil baris data, aplikasi memanggil SQLFetch. SQLFetch dapat dipanggil dengan segala jenis kursor, tetapi hanya memindahkan kursor set baris ke arah khusus ke depan. SQLFetch memajukan kursor ke baris berikutnya dan mengembalikan data untuk kolom apa pun yang terikat dengan panggilan ke SQLBindCol. Saat kursor mencapai akhir kumpulan hasil, SQLFetch mengembalikan SQL_NO_DATA. Untuk contoh panggilan SQLFetch, lihat Menggunakan SQLBindCol.

Persis bagaimana SQLFetch diimplementasikan khusus driver, tetapi pola umumnya adalah agar driver mengambil data untuk kolom terikat apa pun dari sumber data, mengonversinya sesuai dengan jenis variabel terikat, dan menempatkan data yang dikonversi dalam variabel tersebut. Jika driver tidak dapat mengonversi data apa pun, SQLFetch mengembalikan kesalahan. Aplikasi dapat terus mengambil baris, tetapi data untuk baris saat ini hilang. Apa yang terjadi pada data untuk kolom yang tidak terikat tergantung pada driver, tetapi sebagian besar driver mengambil dan membuangnya atau tidak pernah mengambilnya sama sekali.

Driver juga mengatur nilai buffer panjang/indikator apa pun yang telah terikat. Jika nilai data untuk kolom adalah NULL, driver mengatur buffer panjang/indikator yang sesuai ke SQL_NULL_DATA. Jika nilai data bukan NULL, driver mengatur buffer panjang/indikator ke panjang byte data setelah konversi. Jika panjang ini tidak dapat ditentukan, seperti kadang-kadang kasus dengan data panjang yang diambil oleh lebih dari satu panggilan fungsi, driver mengatur buffer panjang/indikator ke SQL_NO_TOTAL. Untuk jenis data dengan panjang tetap, seperti bilangan bulat dan struktur tanggal, panjang byte adalah ukuran jenis data.

Untuk data panjang variabel, seperti karakter dan data biner, driver memeriksa panjang byte data yang dikonversi terhadap panjang byte buffer yang terikat ke kolom; panjang buffer ditentukan dalam argumen BufferLength di SQLBindCol. Jika panjang byte data yang dikonversi lebih besar dari panjang byte buffer, driver memotong data agar pas di buffer, mengembalikan panjang yang tidak terpotong dalam buffer panjang/indikator, mengembalikan SQL_SUCCESS_WITH_INFO, dan menempatkan SQLSTATE 01004 (Data terpotong) dalam diagnostik. Satu-satunya pengecualian untuk ini adalah jika bookmark panjang variabel dipotong ketika dikembalikan oleh SQLFetch, yang mengembalikan SQLSTATE 22001 (Data string, terpotong kanan).

Data panjang tetap tidak pernah terpotong, karena driver mengasumsikan bahwa ukuran buffer terikat adalah ukuran jenis data. Pemotongan data cenderung jarang terjadi, karena aplikasi biasanya mengikat buffer yang cukup besar untuk menahan seluruh nilai data; ini menentukan ukuran yang diperlukan dari metadata. Namun, aplikasi mungkin secara eksplisit mengikat buffer yang diketahui terlalu kecil. Misalnya, ini mungkin mengambil dan menampilkan 20 karakter pertama dari deskripsi bagian atau 100 karakter pertama kolom teks panjang.

Data karakter harus dihentikan null oleh driver sebelum dikembalikan ke aplikasi, bahkan jika telah dipotong. Karakter penghentian null tidak disertakan dalam panjang byte yang dikembalikan tetapi memerlukan ruang dalam buffer terikat. Misalnya, aplikasi menggunakan string yang terdiri dari data karakter dalam kumpulan karakter ASCII, driver memiliki 50 karakter data untuk dikembalikan, dan buffer aplikasi panjangnya 25 byte. Dalam buffer aplikasi, driver mengembalikan 24 karakter pertama diikuti oleh karakter penghentian null. Dalam buffer panjang/indikator, ia mengembalikan panjang byte 50.

Aplikasi dapat membatasi jumlah baris dalam tataan hasil dengan mengatur atribut pernyataan SQL_ATTR_MAX_ROWS sebelum menjalankan pernyataan yang membuat tataan hasil. Misalnya, mode pratinjau dalam aplikasi yang digunakan untuk memformat laporan hanya memerlukan data yang cukup untuk menampilkan halaman pertama laporan. Dengan membatasi ukuran kumpulan hasil, fitur tersebut akan berjalan lebih cepat. Atribut pernyataan ini dimaksudkan untuk mengurangi lalu lintas jaringan dan mungkin tidak didukung oleh semua driver.