Bagikan melalui


Fungsi SQLGetConnectAttr

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92

Ringkasan
SQLGetConnectAttr mengembalikan pengaturan atribut koneksi saat ini.

Catatan

Untuk informasi selengkapnya tentang apa manajer driver memetakan fungsi ini ketika aplikasi ODBC 3*.x* bekerja dengan driver ODBC 2*.x*, lihat Memetakan Fungsi Penggantian untuk Kompatibilitas Mundur Aplikasi.

Sintaks

  
SQLRETURN SQLGetConnectAttr(  
     SQLHDBC        ConnectionHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);  

Argumen

ConnectionHandle
[Input] Handel koneksi.

Atribut
[Input] Atribut yang akan diambil.

ValuePtr
[Output] Pointer ke memori untuk mengembalikan nilai atribut saat ini yang ditentukan oleh Atribut. Untuk atribut jenis bilangan bulat, beberapa driver hanya dapat menulis buffer 32-bit atau 16-bit yang lebih rendah dan membiarkan bit berurutan lebih tinggi tidak berubah. Oleh karena itu, aplikasi harus menggunakan buffer SQLULEN dan menginisialisasi nilai ke 0 sebelum memanggil fungsi ini.

Jika ValuePtr adalah NULL, StringLengthPtr masih akan mengembalikan jumlah total byte (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang ditujukkan 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 Atribut adalah atribut yang ditentukan 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 Atribut adalah atribut yang ditentukan driver, aplikasi menunjukkan sifat atribut ke Driver Manager dengan mengatur argumen BufferLength . BufferLength dapat memiliki nilai berikut:

  • Jika *ValuePtr adalah penunjuk ke string karakter, BufferLength adalah panjang string.

  • Jika *ValuePtr adalah penunjuk ke buffer biner, aplikasi menempatkan hasil makro SQL_LEN_BINARY_ATTR(panjang) di BufferLength. Ini menempatkan nilai negatif di BufferLength.

  • Jika *ValuePtr adalah penunjuk ke nilai selain string karakter atau string biner, BufferLength harus memiliki nilai SQL_IS_POINTER.

  • Jika *ValuePtr berisi jenis data dengan panjang tetap, BufferLength SQL_IS_INTEGER atau SQL_IS_UINTEGER, sebagaimana mewajibkan.

StringLengthPtr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total byte (tidak termasuk karakter penghentian null) 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 penghentian null, data dalam *ValuePtr dipotong menjadi BufferLength dikurangi panjang karakter null-termination dan dihentikan null oleh driver.

Kembali

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostik

Saat SQLGetConnectAttr mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dari struktur data diagnostik dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_DBC dan Handle of ConnectionHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLGetConnectAttr 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 Data yang dikembalikan dalam *ValuePtr dipotong menjadi BufferLength dikurangi panjang karakter penghentian null. 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 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 dikembalikan 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 dikembalikan 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 atribut argumen tidak valid untuk versi ODBC yang didukung oleh driver.
HY114 Driver tidak mendukung eksekusi fungsi asinkron tingkat koneksi (DM) 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 atribut argumen adalah atribut koneksi ODBC yang valid untuk versi ODBC yang didukung oleh driver, tetapi tidak didukung oleh driver.
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 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 Atribut menentukan atribut yang mengembalikan string, ValuePtr harus menjadi penunjuk ke buffer untuk string. Panjang maksimum string yang dikembalikan, termasuk karakter penghentian null, akan menjadi byte BufferLength .

Bergantung pada atribut , aplikasi tidak perlu membuat koneksi sebelum memanggil SQLGetConnectAttr. Namun, jika SQLGetConnectAttr dipanggil dan atribut yang ditentukan tidak memiliki default dan belum ditetapkan oleh panggilan sebelumnya ke SQLSetConnectAttr, SQLGetConnectAttr akan mengembalikan SQL_NO_DATA.

Jika Atribut 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 aplikasi dapat mengatur atribut pernyataan dengan menggunakan SQLSetConnectAttr, aplikasi tidak dapat menggunakan SQLGetConnectAttr untuk mengambil nilai atribut pernyataan; aplikasi harus memanggil SQLGetStmtAttr untuk mengambil pengaturan atribut pernyataan.

Atribut koneksi SQL_ATTR_AUTO_IPD dan SQL_ATTR_CONNECTION_DEAD dapat dikembalikan dengan panggilan ke SQLGetConnectAttr tetapi tidak dapat diatur oleh panggilan ke SQLSetConnectAttr.

Catatan

Tidak ada dukungan asinkron untuk SQLGetConnectAttr. Saat menerapkan SQLGetConnectAttr, driver dapat meningkatkan performa dengan meminimalkan berapa kali informasi dikirim atau diminta dari server.

Untuk informasi tentang Lihat
Mengembalikan pengaturan atribut pernyataan Fungsi SQLGetStmtAttr
Mengatur atribut koneksi Fungsi SQLSetConnectAttr
Mengatur atribut lingkungan Fungsi SQLSetEnvAttr
Mengatur atribut pernyataan Fungsi SQLSetStmtAttr

Lihat Juga

Referensi API ODBC
File Header ODBC