Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Summary
SQLGetConnectAttr mengembalikan pengaturan saat ini dari atribut koneksi.
Note
Untuk informasi lebih lanjut tentang apa yang dipetakan Driver Manager ke fungsi ini ketika aplikasi ODBC 3*.x* bekerja dengan driver ODBC 2*.x*, lihat Memetakan Fungsi Pengganti untuk Kompatibilitas Mundur Aplikasi.
Syntax
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
ConnectionHandle
[Input] Handle koneksi.
Atribut
[Input] Atribut untuk diambil.
ValuePtr
[Output] Penunjuk ke memori untuk mengembalikan nilai saat ini dari atribut yang ditentukan oleh Atribut. Untuk atribut tipe bilangan bulat, beberapa driver mungkin hanya menulis buffer 32-bit atau 16-bit yang lebih rendah dan membiarkan bit orde lebih tinggi tetap tidak berubah. Oleh karena itu, aplikasi harus menggunakan buffer SQLULEN dan menginisialisasi nilainya menjadi 0 sebelum memanggil fungsi ini.
Jika ValuePtr bernilai NULL, StringLengthPtr tetap akan mengembalikan total jumlah byte (tidak termasuk karakter null-termination untuk data karakter) yang tersedia untuk dikembalikan di buffer yang ditunjuk oleh ValuePtr.
BufferLength
[Input] Jika Atribut adalah atribut yang ditentukan ODBC dan ValuePtr menunjuk ke string karakter atau buffer biner, argumen ini harus panjangnya *ValuePtr. Jika Attribute adalah atribut yang didefinisikan ODBC dan *ValuePtr adalah bilangan bulat, BufferLength diabaikan. Jika nilai dalam *ValuePtr adalah string Unicode (saat memanggil SQLGetConnectAttrW), argumen BufferLength harus berupa angka genap.
Jika Attribute adalah atribut yang didefinisikan oleh driver, aplikasi akan menunjukkan sifat atribut tersebut kepada Driver Manager dengan mengatur argumen BufferLength . BufferLength dapat memiliki nilai berikut:
Jika *ValuePtr adalah pointer ke string karakter, BufferLength adalah panjang string tersebut.
Jika *ValuePtr adalah pointer ke buffer biner, aplikasi akan menempatkan hasil makro SQL_LEN_BINARY_ATTR(length) di BufferLength. Ini menempatkan nilai negatif di BufferLength.
Jika *ValuePtr adalah penunjuk ke nilai selain string karakter atau string biner, BufferLength seharusnya memiliki nilai SQL_IS_POINTER.
Jika *ValuePtr berisi tipe data dengan panjang tetap, BufferLength adalah SQL_IS_INTEGER atau SQL_IS_UINTEGER, sesuai kebutuhan.
StringLengthPtr
[Output] Sebuah pointer ke buffer untuk mengembalikan total jumlah byte (tidak termasuk karakter null-terminasi) yang tersedia untuk dikembalikan dalam *ValuePtr. Jika nilai atribut adalah string karakter dan jumlah byte yang tersedia untuk dikembalikan lebih besar dari BufferLength dikurangi panjang karakter null-terminasi, data dalam * ValuePtr dipotong menjadi BufferLength dikurangi panjang karakter null-terminasi dan null-terminated oleh driver.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostics
Ketika SQLGetConnectAttr mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE yang terkait dapat diperoleh dari struktur data diagnostik dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_DBC dan HandleConnectionHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLGetConnectAttr dan menjelaskan masing-masing dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATE 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 | Data yang dikembalikan dalam *ValuePtr dipotong menjadi BufferLength dikurangi panjang karakter null-terminasi. Panjang nilai string yang tidak terpotong dikembalikan dalam *StringLengthPtr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 08003 | Koneksi tidak terbuka | (DM) Nilai Atribut yang memerlukan koneksi terbuka telah ditentukan. |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| HY000 | Kesalahan umum | Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan dari struktur data diagnostik oleh argumen MessageText di SQLGetDiagField menjelaskan kesalahan dan penyebabnya. |
| HY001 | Kesalahan alokasi memori | Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY010 | Kesalahan urutan fungsi | (DM) SQLBrowseConnect dipanggil untuk ConnectionHandle dan mengembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum SQLBrowseConnect mengembalikan SQL_SUCCESS_WITH_INFO atau SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk ConnectionHandle dan mengembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. |
| 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) *ValuePtr adalah string karakter, dan BufferLength kurang dari nol tetapi tidak sama dengan SQL_NTS. |
| HY092 | Pengidentifikasi atribut/opsi tidak valid | Nilai yang ditentukan untuk argumen Attribute tidak valid untuk versi ODBC yang didukung oleh driver. |
| HY114 | Driver tidak mendukung eksekusi fungsi asinkron tingkat koneksi | (DM) Sebuah aplikasi mencoba mengaktifkan eksekusi fungsi asinkron dengan SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE untuk driver yang tidak mendukung operasi koneksi asinkron. |
| 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 | Nilai yang ditentukan untuk argumen Attribute adalah atribut koneksi ODBC yang valid untuk versi ODBC yang didukung oleh driver, tetapi tidak didukung oleh driver. |
| HYT01 | Waktu tunggu koneksi habis | 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 sesuai dengan ConnectionHandle tidak mendukung fungsi. |
Komentar
Untuk informasi umum tentang atribut koneksi, lihat Atribut Koneksi.
Untuk daftar atribut yang dapat diatur, lihat SQLSetConnectAttr. Perhatikan bahwa jika Attribute menentukan atribut yang mengembalikan string, ValuePtr harus menjadi pointer ke buffer untuk string tersebut. Panjang maksimum string yang dikembalikan, termasuk karakter null-terminasi, akan menjadi byte BufferLength .
Tergantung pada atribut, sebuah aplikasi tidak perlu membangun koneksi sebelum memanggil SQLGetConnectAttr. Namun, jika SQLGetConnectAttr dipanggil dan atribut yang ditentukan tidak memiliki default serta belum diatur oleh panggilan sebelumnya ke SQLSetConnectAttr, SQLGetConnectAttr akan mengembalikan SQL_NO_DATA.
Jika Attribute SQL_ATTR_ TRACE atau SQL_ATTR_ TRACEFILE, ConnectionHandle tidak harus valid, dan SQLGetConnectAttr tidak akan mengembalikan SQL_ERROR atau SQL_INVALID_HANDLE jika ConnectionHandle tidak valid. Atribut ini berlaku untuk semua koneksi. SQLGetConnectAttr akan mengembalikan SQL_ERROR atau SQL_INVALID_HANDLE jika argumen lain tidak valid.
Meskipun sebuah aplikasi dapat mengatur atribut pernyataan dengan menggunakan SQLSetConnectAttr, sebuah aplikasi tidak dapat menggunakan SQLGetConnectAttr untuk mengambil nilai atribut pernyataan; harus memanggil SQLGetStmtAttr untuk mengambil pengaturan atribut pernyataan.
Atribut koneksi SQL_ATTR_AUTO_IPD dan SQL_ATTR_CONNECTION_DEAD dapat dikembalikan melalui pemanggilan ke SQLGetConnectAttr tetapi tidak dapat diatur dengan pemanggilan ke SQLSetConnectAttr.
Note
Tidak ada dukungan asinkron untuk SQLGetConnectAttr. Saat mengimplementasikan SQLGetConnectAttr, driver dapat meningkatkan performa dengan meminimalkan jumlah kali informasi dikirim atau diminta dari server.
Fungsi Terkait
| Untuk informasi mengenai | Lihat |
|---|---|
| Mengembalikan pengaturan atribut pernyataan | Fungsi SQLGetStmtAttr |
| Mengatur atribut koneksi | Fungsi SQLSetConnectAttr |
| Mengatur atribut lingkungan | Fungsi SQLSetEnvAttr |
| Mengatur atribut pernyataan | Fungsi SQLSetStmtAttr |