Mengirim Data Panjang

  • Artikel

DBMS mendefinisikan data panjang sebagai karakter atau data biner apa pun dalam ukuran tertentu, seperti 254 karakter. Mungkin tidak dimungkinkan untuk menyimpan seluruh item data panjang dalam memori, seperti ketika item mewakili dokumen teks panjang atau bitmap. Karena data tersebut tidak dapat disimpan dalam satu buffer, sumber data mengirimkannya ke driver di bagian dengan SQLPutData ketika pernyataan dijalankan. Parameter yang datanya dikirim pada waktu eksekusi dikenal sebagai parameter data-at-execution.

Catatan

Aplikasi benar-benar dapat mengirim semua jenis data pada waktu eksekusi dengan SQLPutData, meskipun hanya karakter dan data biner yang dapat dikirim dalam beberapa bagian. Namun, jika data cukup kecil agar pas dalam satu buffer, umumnya tidak ada alasan untuk menggunakan SQLPutData. Jauh lebih mudah untuk mengikat buffer dan membiarkan driver mengambil data dari buffer.

Untuk mengirim data pada waktu eksekusi, aplikasi melakukan tindakan berikut:

  1. Meneruskan nilai 32-bit yang mengidentifikasi parameter dalam argumen ParameterValuePtr di SQLBindParameter daripada meneruskan alamat buffer. Nilai ini tidak dianalisis oleh driver. Ini akan dikembalikan ke aplikasi nanti, jadi itu harus berarti sesuatu untuk aplikasi. Misalnya, mungkin jumlah parameter atau handel file yang berisi data.

  2. Meneruskan alamat buffer panjang/indikator dalam argumen StrLen_or_IndPtr SQLBindParameter.

  3. Menyimpan SQL_DATA_AT_EXEC atau hasil makro SQL_LEN_DATA_AT_EXEC(panjang) dalam buffer panjang/indikator. Kedua nilai ini menunjukkan kepada driver bahwa data untuk parameter akan dikirim dengan SQLPutData. SQL_LEN_DATA_AT_EXEC(panjang) digunakan saat mengirim data panjang ke sumber data yang perlu mengetahui berapa banyak byte data panjang yang akan dikirim sehingga dapat melakukan pra-alokasi ruang. Untuk menentukan apakah sumber data memerlukan nilai ini, aplikasi memanggil SQLGetInfo dengan opsi SQL_NEED_LONG_DATA_LEN. Semua driver harus mendukung makro ini; jika sumber data tidak memerlukan panjang byte, driver dapat mengabaikannya.

  4. Memanggil SQLExecute atau SQLExecDirect. Driver menemukan bahwa buffer panjang/indikator berisi nilai SQL_DATA_AT_EXEC atau hasil makro SQL_LEN_DATA_AT_EXEC(panjang) dan mengembalikan SQL_NEED_DATA sebagai nilai pengembalian fungsi.

  5. Memanggil SQLParamData sebagai respons terhadap nilai pengembalian SQL_NEED_DATA. Jika data panjang perlu dikirim, SQLParamData mengembalikan SQL_NEED_DATA. Dalam buffer yang ditunjukkan oleh argumen ValuePtrPtr , driver mengembalikan nilai yang mengidentifikasi parameter data-at-execution. Jika ada lebih dari satu parameter data-at-execution, aplikasi harus menggunakan nilai ini untuk menentukan parameter mana yang akan dikirim datanya; driver tidak diperlukan untuk meminta data untuk parameter data-at-execution dalam urutan tertentu.

  6. Memanggil SQLPutData untuk mengirim data parameter ke driver. Jika data parameter tidak masuk ke dalam satu buffer, seperti yang sering terjadi dengan data panjang, aplikasi memanggil SQLPutData berulang kali untuk mengirim data dalam beberapa bagian; terserah driver dan sumber data untuk menyusun ulang data. Jika aplikasi meneruskan data string yang dihentikan null, driver atau sumber data harus menghapus karakter penghentian null sebagai bagian dari proses pembuatan ulang.

  7. Memanggil SQLParamData lagi untuk menunjukkan bahwa SQLParamData telah mengirim semua data untuk parameter . Jika ada parameter data-at-execution yang datanya belum dikirim, driver mengembalikan SQL_NEED_DATA dan nilai yang mengidentifikasi parameter berikutnya; aplikasi kembali ke langkah 6. Jika data telah dikirim untuk semua parameter data-at-execution, pernyataan akan dijalankan. SQLParamData mengembalikan SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO dan dapat mengembalikan nilai atau diagnostik yang dapat dikembalikan oleh SQLExecute atau SQLExecDirect .

Setelah SQLExecute atau SQLExecDirect mengembalikan SQL_NEED_DATA dan sebelum data benar-benar dikirim untuk parameter data-at-execution terakhir, pernyataan berada dalam status Perlu Data. Saat pernyataan dalam status Perlu Data, aplikasi hanya dapat memanggil SQLPutData, SQLParamData, SQLCancel, SQLGetDiagField, atau SQLGetDiagRec; semua fungsi lainnya mengembalikan SQLSTATE HY010 (Kesalahan urutan fungsi). Memanggil SQLCancel membatalkan eksekusi pernyataan dan mengembalikannya ke status sebelumnya. Untuk informasi selengkapnya, lihat Lampiran B: Tabel Transisi Status ODBC.

Untuk contoh pengiriman data pada waktu eksekusi, lihat deskripsi fungsi SQLPutData .