Fungsi SQLGetEnvAttr
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLGetEnvAttr mengembalikan pengaturan atribut lingkungan saat ini.
Sintaks
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argumen
EnvironmentHandle
[Input] Penanganan lingkungan.
Atribut
[Input] Atribut yang akan diambil.
ValuePtr
[Output] Penunjuk ke buffer untuk mengembalikan nilai atribut saat ini yang ditentukan oleh Atribut.
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 ValuePtr menunjuk ke string karakter, argumen ini harus panjang *ValuePtr. Jika *ValuePtr adalah bilangan bulat, BufferLength diabaikan. Jika *ValuePtr adalah string Unicode (saat memanggil SQLGetEnvAttrW), argumen BufferLength harus berupa angka genap. Jika nilai atribut bukan string karakter, BufferLength tidak digunakan.
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 atau sama dengan BufferLength, 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 SQLGetEnvAttr mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_ENV dan Handle of EnvironmentHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLGetEnvAttr 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 karakter penghentian null. Panjang nilai string yang tidak terpotong dikembalikan dalam *StringLengthPtr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 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. |
| HY010 | Kesalahan urutan fungsi | (DM) SQL_ATTR_ODBC_VERSION belum ditetapkan melalui SQLSetEnvAttr. Anda tidak perlu mengatur SQL_ATTR_ODBC_VERSION secara eksplisit jika Anda menggunakan SQLAllocHandleStd. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY092 | Pengidentifikasi atribut/opsi tidak valid | Nilai yang ditentukan untuk atribut argumen tidak valid untuk versi ODBC yang didukung oleh driver. |
| 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 lingkungan ODBC yang valid untuk versi ODBC yang didukung oleh driver tetapi tidak didukung oleh driver. |
| IM001 | Driver tidak mendukung fungsi ini | (DM) Driver yang sesuai dengan EnvironmentHandle tidak mendukung fungsi. |
Komentar
Untuk daftar atribut, lihat SQLSetEnvAttr. Tidak ada atribut lingkungan khusus driver. Jika Atribut menentukan atribut yang mengembalikan string, ValuePtr harus menjadi penunjuk ke buffer untuk mengembalikan string. Panjang maksimum string, termasuk byte penghentian null, akan menjadi byte BufferLength .
SQLGetEnvAttr dapat dipanggil kapan saja antara alokasi dan pengosongan handel lingkungan. Semua atribut lingkungan berhasil diatur oleh aplikasi untuk lingkungan bertahan hingga SQLFreeHandle dipanggil pada EnvironmentHandle dengan HandleType SQL_HANDLE_ENV. Lebih dari satu handel lingkungan dapat dialokasikan secara bersamaan di ODBC 3*.x*. Atribut lingkungan pada satu lingkungan tidak terpengaruh ketika lingkungan lain telah dialokasikan.
Catatan
Atribut lingkungan SQL_ATTR_OUTPUT_NTS didukung oleh aplikasi yang mematuhi standar. Ketika SQLGetEnvAttr dipanggil, Manajer Driver ODBC 3*.x* selalu mengembalikan SQL_TRUE untuk atribut ini. SQL_ATTR_OUTPUT_NTS dapat diatur ke SQL_TRUE hanya dengan panggilan ke SQLSetEnvAttr.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengembalikan pengaturan atribut koneksi | Fungsi SQLGetConnectAttr |
| Mengembalikan pengaturan atribut pernyataan | Fungsi SQLGetStmtAttr |
| Mengatur atribut koneksi | Fungsi SQLSetConnectAttr |
| Mengatur atribut lingkungan | Fungsi SQLSetEnvAttr |
| Mengatur atribut pernyataan | Fungsi SQLSetStmtAttr |