Fungsi SQLPrepare
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLPrepare menyiapkan string SQL untuk eksekusi.
Sintaks
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
Argumen
StatementHandle
[Input] Handel pernyataan.
StatementText
[Input] String teks SQL.
TextLength
[Input] Panjang *StatementText dalam karakter.
Mengembalikan
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLPrepare 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 SQLPrepare 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 berubah | Atribut pernyataan tertentu tidak valid karena kondisi kerja implementasi, sehingga nilai serupa untuk sementara diganti. (SQLGetStmtAttr dapat dipanggil untuk menentukan nilai yang diganti sementara.) Nilai pengganti valid untuk StatementHandle hingga kursor ditutup. Atribut pernyataan yang dapat diubah adalah: SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR (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. |
| 21S01 | Sisipkan daftar nilai tidak cocok dengan daftar kolom | *StatementText berisi pernyataan INSERT , dan jumlah nilai yang akan disisipkan tidak cocok dengan tingkat tabel turunan. |
| 21S02 | Tingkat tabel turunan tidak cocok dengan daftar kolom | *StatementText berisi pernyataan CREATE VIEW , dan jumlah nama yang ditentukan bukan derajat yang sama dengan tabel turunan yang ditentukan oleh spesifikasi kueri. |
| 22018 | Nilai karakter tidak valid untuk spesifikasi cast | *StatementText berisi pernyataan SQL yang berisi literal atau parameter, dan nilainya tidak kompatibel dengan jenis data kolom tabel terkait. |
| 22019 | Karakter escape tidak valid | Argumen StatementText berisi predikat LIKE dengan ESCAPE dalam klausa WHERE, dan panjang karakter escape setelah ESCAPE tidak sama dengan 1. |
| 22025 | Urutan escape tidak valid | Argumen StatementText berisi "LIKE pattern value ESCAPE character" dalam klausul WHERE, dan karakter yang mengikuti karakter escape dalam nilai pola bukan "%" atau "_". |
| 24000 | Status kursor tidak valid | (DM) Kursor terbuka pada StatementHandle, dan SQLFetch atau SQLFetchScroll telah dipanggil. Kursor terbuka pada StatementHandle, tetapi SQLFetch atau SQLFetchScroll belum dipanggil. |
| 34000 | Nama kursor tidak valid | *StatementText berisi DELETE yang diposisikan atau UPDATE yang diposisikan, dan kursor yang direferensikan oleh pernyataan yang sedang disiapkan tidak terbuka. |
| 3D000 | Nama katalog tidak valid | Nama katalog yang ditentukan dalam StatementText tidak valid. |
| 3F000 | Nama skema tidak valid | Nama skema yang ditentukan dalam StatementText tidak valid. |
| 42000 | Kesalahan sintaks atau pelanggaran akses | *StatementText berisi pernyataan SQL yang tidak dapat disiapkan atau berisi kesalahan sintaks. *StatementText berisi pernyataan di mana pengguna tidak memiliki hak istimewa yang diperlukan. |
| 42S01 | Tabel dasar atau tampilan sudah ada | *StatementText berisi pernyataan CREATE TABLE atau CREATE VIEW , dan nama tabel atau nama tampilan yang ditentukan sudah ada. |
| 42S02 | Tabel dasar atau tampilan tidak ditemukan | *StatementText berisi pernyataan DROP TABLE atau DROP VIEW , dan nama tabel atau nama tampilan yang ditentukan tidak ada. *StatementText berisi pernyataan ALTER TABLE , dan nama tabel yang ditentukan tidak ada. *StatementText berisi pernyataan CREATE VIEW , dan nama tabel atau nama tampilan yang ditentukan oleh spesifikasi kueri tidak ada. *StatementText berisi pernyataan CREATE INDEX , dan nama tabel yang ditentukan tidak ada. *StatementText berisi pernyataan GRANT atau REVOKE , dan nama tabel atau nama tampilan yang ditentukan tidak ada. *StatementText berisi pernyataan SELECT , dan nama tabel atau nama tampilan tertentu tidak ada. *StatementText berisi pernyataan DELETE, INSERT, atau UPDATE , dan nama tabel yang ditentukan tidak ada. *StatementText berisi pernyataan CREATE TABLE , dan tabel yang ditentukan dalam batasan (mereferensikan tabel selain yang sedang dibuat) tidak ada. |
| 42S11 | Indeks sudah ada | *StatementText berisi pernyataan CREATE INDEX , dan nama indeks yang ditentukan sudah ada. |
| 42S12 | Indeks tidak ditemukan | *StatementText berisi pernyataan DROP INDEX , dan nama indeks yang ditentukan tidak ada. |
| 42S21 | Kolom sudah ada | *StatementText berisi pernyataan ALTER TABLE , dan kolom yang ditentukan dalam klausa ADD tidak unik atau mengidentifikasi kolom yang ada dalam tabel dasar. |
| 42S22 | Kolom tidak ditemukan | *StatementText berisi pernyataan CREATE INDEX , dan satu atau beberapa nama kolom yang ditentukan dalam daftar kolom tidak ada. *StatementText berisi pernyataan GRANT atau REVOKE , dan nama kolom tertentu tidak ada. *StatementText berisi pernyataan SELECT, DELETE, INSERT, atau UPDATE , dan nama kolom tertentu tidak ada. *StatementText berisi pernyataan CREATE TABLE , dan kolom yang ditentukan dalam batasan (mereferensikan tabel selain yang sedang dibuat) tidak ada. |
| 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 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. |
| HY009 | Penggunaan pointer null tidak valid | (DM) StatementText adalah pointer null. |
| HY010 | Kesalahan urutan fungsi | (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih dijalankan ketika fungsi SQLPrepare 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) 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. |
| HY090 | String atau panjang buffer tidak valid | (DM) Argumen TextLength kurang dari atau sama dengan 0 tetapi tidak sama dengan SQL_NTS. |
| 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 | Pengaturan konkurensi tidak valid untuk jenis kursor yang ditentukan. Atribut pernyataan SQL_ATTR_USE_BOOKMARKS diatur ke SQL_UB_VARIABLE, dan atribut pernyataan SQL_ATTR_CURSOR_TYPE diatur ke jenis kursor yang drivernya tidak mendukung marka buku. |
| HYT00 | Waktu habis kedaluwarsa | Periode batas waktu kedaluwarsa sebelum sumber data mengembalikan tataan hasil. 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
Aplikasi memanggil SQLPrepare untuk mengirim pernyataan SQL ke sumber data untuk persiapan. Untuk informasi selengkapnya tentang eksekusi yang disiapkan, lihat Eksekusi yang Disiapkan. Aplikasi dapat menyertakan satu atau beberapa penanda parameter dalam pernyataan SQL. Untuk menyertakan penanda parameter, aplikasi menyematkan tanda tanya (?) ke dalam string SQL pada posisi yang sesuai. Untuk informasi tentang parameter, lihat Parameter Pernyataan.
Catatan
Jika aplikasi menggunakan SQLPrepare untuk mempersiapkan dan SQLExecute untuk mengirimkan pernyataan COMMIT atau ROLLBACK , itu tidak akan dapat dioperasikan antara produk DBMS. Untuk menerapkan atau mengembalikan transaksi, hubungi SQLEndTran.
Driver dapat memodifikasi pernyataan untuk menggunakan bentuk SQL yang digunakan oleh sumber data dan kemudian mengirimkannya ke sumber data untuk persiapan. Secara khusus, driver memodifikasi urutan escape yang digunakan untuk menentukan sintaks SQL untuk fitur tertentu. (Untuk deskripsi tata bahasa pernyataan SQL, lihat Urutan Escape dalam ODBC dan Lampiran C: Tata Bahasa SQL.) Untuk driver, handel pernyataan mirip dengan pengidentifikasi pernyataan dalam kode SQL yang disematkan. Jika sumber data mendukung pengidentifikasi pernyataan, driver dapat mengirim pengidentifikasi pernyataan dan nilai parameter ke sumber data.
Setelah pernyataan disiapkan, aplikasi menggunakan handel pernyataan untuk merujuk ke pernyataan dalam panggilan fungsi selanjutnya. Pernyataan yang disiapkan yang terkait dengan handel pernyataan dapat dijalankan kembali dengan memanggil SQLExecute sampai aplikasi membebaskan pernyataan dengan panggilan ke SQLFreeStmt dengan opsi SQL_DROP atau sampai handel pernyataan digunakan dalam panggilan ke SQLPrepare, SQLExecDirect, atau salah satu fungsi katalog (SQLColumns, SQLTables, dan sebagainya). Setelah aplikasi menyiapkan pernyataan, aplikasi dapat meminta informasi tentang format kumpulan hasil. Untuk beberapa implementasi, memanggil SQLDescribeCol atau SQLDescribeParam setelah SQLPrepare mungkin tidak seefisien memanggil fungsi setelah SQLExecute atau SQLExecDirect.
Beberapa driver tidak dapat mengembalikan kesalahan sintaks atau pelanggaran akses saat aplikasi memanggil SQLPrepare. Driver dapat menangani kesalahan sintaksis dan pelanggaran akses, hanya kesalahan sintaksis, atau kesalahan sintaksis atau pelanggaran akses. Oleh karena itu, aplikasi harus dapat menangani kondisi ini saat memanggil fungsi terkait berikutnya seperti SQLNumResultCols, SQLDescribeCol, SQLColAttribute, dan SQLExecute.
Bergantung pada kemampuan driver dan sumber data, informasi parameter (seperti jenis data) dapat diperiksa ketika pernyataan disiapkan (jika semua parameter telah terikat) atau ketika dijalankan (jika semua parameter belum terikat). Untuk interoperabilitas maksimum, aplikasi harus membatalkan ikatan semua parameter yang diterapkan ke pernyataan SQL lama sebelum menyiapkan pernyataan SQL baru pada pernyataan yang sama. Ini mencegah kesalahan yang disebabkan oleh informasi parameter lama yang diterapkan ke pernyataan baru.
Penting
Melakukan transaksi, baik dengan secara eksplisit memanggil SQLEndTran atau dengan bekerja dalam mode autocommit, dapat menyebabkan sumber data menghapus paket akses untuk semua pernyataan pada koneksi. Untuk informasi selengkapnya, lihat jenis informasi SQL_CURSOR_COMMIT_BEHAVIOR dan SQL_CURSOR_ROLLBACK_BEHAVIOR di SQLGetInfo dan Efek Transaksi pada Kursor dan Pernyataan yang Disiapkan.
Contoh Kode
Lihat SQLBindParameter, SQLPutData, dan SQLSetPos.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengalokasikan handel pernyataan | Fungsi SQLAllocHandle |
| Mengikat buffer ke kolom dalam tataan hasil | Fungsi SQLBindCol |
| Mengikat buffer ke parameter | Fungsi SQLBindParameter |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Menjalankan operasi penerapan atau pembatalan | Fungsi SQLEndtran |
| Menjalankan pernyataan SQL | Fungsi SQLExecDirect |
| Menjalankan pernyataan SQL yang disiapkan | Fungsi SQLExecute |
| Mengembalikan jumlah baris yang dipengaruhi oleh pernyataan | Fungsi SQLRowCount |
| Mengatur nama kursor | Fungsi SQLSetCursorName |