Fungsi SQLSetCursorName
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLSetCursorName mengaitkan nama kursor dengan pernyataan aktif. Jika aplikasi tidak memanggil SQLSetCursorName, driver menghasilkan nama kursor sesuai kebutuhan untuk pemrosesan pernyataan SQL.
Sintaks
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
Argumen
StatementHandle
[Input] Handel pernyataan.
CursorName
[Input] Nama kursor. Untuk pemrosesan yang efisien, nama kursor tidak boleh menyertakan spasi di depan atau berikutnya dalam nama kursor, dan jika nama kursor menyertakan pengidentifikasi yang dibatasi, pemisah harus diposisikan sebagai karakter pertama dalam nama kursor.
NameLength
[Input] Panjang karakter *CursorName.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLSetCursorName 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 SQLSetCursorName 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.) |
| 01004 | Data string, terpotong kanan | Nama kursor melebihi batas maksimum, sehingga hanya jumlah karakter maksimum yang diizinkan yang digunakan. |
| 24000 | Status kursor tidak valid | Pernyataan yang sesuai dengan StatementHandle sudah dalam status dieksekusi atau diposisikan kursor. |
| 34000 | Nama kursor tidak valid | Nama kursor yang ditentukan dalam *CursorName tidak valid karena melebihi panjang maksimum seperti yang ditentukan oleh driver, atau dimulai dengan "SQLCUR" atau "SQL_CUR." |
| 3C000 | Nama kursor duplikat | Nama kursor yang ditentukan dalam *CursorName sudah 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. |
| HY009 | Penggunaan pointer null tidak valid | (DM) Argumen CursorName adalah pointer null. |
| HY010 | Kesalahan urutan fungsi | (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi ainkron ini masih dijalankan ketika fungsi SQLSetCursorName dipanggil. (DM) Fungsi eksekusi asinkron 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 NameLength kurang dari 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. |
| 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
Nama kursor hanya digunakan dalam pernyataan pembaruan dan penghapusan yang diposisikan (misalnya, PERBARUInama tabel ...WHERE CURRENT OFcursor-name). Untuk informasi selengkapnya, lihat Pernyataan Pembaruan dan Penghapusan yang Diposisikan. Jika aplikasi tidak memanggil SQLSetCursorName untuk menentukan nama kursor, pada eksekusi pernyataan kueri, driver menghasilkan nama yang dimulai dengan huruf SQL_CUR dan panjangnya tidak melebihi 18 karakter.
Semua nama kursor dalam koneksi harus unik. Panjang maksimum nama kursor ditentukan oleh driver. Untuk interoperabilitas maksimum, disarankan agar aplikasi membatasi nama kursor hingga tidak lebih dari 18 karakter. Dalam ODBC 3*.x*, jika nama kursor adalah pengidentifikasi yang dikutip, itu diperlakukan dengan cara yang peka huruf besar/kecil dan dapat berisi karakter yang tidak diizinkan oleh sintaks SQL atau akan memperlakukan secara khusus, seperti kata kunci kosong atau yang dipesan. Jika nama kursor harus diperlakukan dengan cara yang peka huruf besar/kecil, nama kursor harus diteruskan sebagai pengidentifikasi yang dikutip.
Nama kursor yang diatur secara eksplisit atau implisit tetap ditetapkan hingga pernyataan yang terkait dengannya dihilangkan, menggunakan SQLFreeHandle. SQLSetCursorName dapat dipanggil untuk mengganti nama kursor pada pernyataan selama kursor berada dalam status dialokasikan atau disiapkan.
Contoh Kode
Dalam contoh berikut, aplikasi menggunakan SQLSetCursorName untuk mengatur nama kursor untuk pernyataan. Kemudian menggunakan pernyataan tersebut untuk mengambil hasil dari tabel PELANGGAN. Akhirnya, ia melakukan pembaruan yang diposisikan untuk mengubah nomor telepon John Smith. Perhatikan bahwa aplikasi menggunakan handel pernyataan yang berbeda untuk pernyataan SELECT dan UPDATE .
Untuk contoh kode lain, lihat SQLSetPos.
#define NAME_LEN 50
#define PHONE_LEN 10
SQLHSTMT hstmtSelect,
SQLHSTMT hstmtUpdate;
SQLRETURN retcode;
SQLHDBC hdbc;
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER cbName, cbPhone;
/* Allocate the statements and set the cursor name. */
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);
/* SELECT the result set and bind its columns to local buffers. */
SQLExecDirect(hstmtSelect,
"SELECT NAME, PHONE FROM CUSTOMERS",
SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
/* Read through the result set until the cursor is */
/* positioned on the row for John Smith. */
do
retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&
(strcmp(szName, "Smith, John") != 0));
/* Perform a positioned update of John Smith's name. */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLExecDirect(hstmtUpdate,
"UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",
SQL_NTS);
}
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Menjalankan pernyataan SQL | Fungsi SQLExecDirect |
| Menjalankan pernyataan SQL yang disiapkan | Fungsi SQLExecute |
| Mengembalikan nama kursor | Fungsi SQLGetCursorName |
| Mengatur opsi gulir kursor | Fungsi SQLSetScrollOptions |
Lihat Juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk