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
SQLSetEnvAttr mengatur atribut yang mengatur aspek lingkungan.
Syntax
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Arguments
EnvironmentHandle
[Input] Pengelolaan lingkungan.
Atribut
[Input] Atribut ke set, tercantum di "Komentar."
ValuePtr
[Input] Pointer ke nilai yang akan diasosiasikan dengan Atribut. Tergantung pada nilai Atribut,ValuePtr akan berupa nilai integer 32-bit atau mengarah ke string karakter yang diakhiri null.
StringLength
[Input] Jika ValuePtr menunjuk ke string karakter atau buffer biner, argumen ini harus berupa panjang *ValuePtr. Untuk data string karakter, argumen ini harus berisi jumlah byte dalam string.
Jika ValuePtr adalah bilangan bulat, StringLength diabaikan.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostics
Ketika SQLSetEnvAttr mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE yang terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_ENV dan HandleEnvironmentHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLSetEnvAttr 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. Jika driver tidak mendukung atribut lingkungan, kesalahan hanya dapat dikembalikan selama waktu terhubung.
| SQLSTATE | Kesalahan | Description |
|---|---|---|
| 01000 | Peringatan umum | Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Nilai opsi berubah | Driver tidak mendukung nilai yang ditentukan di ValuePtr dan mengganti nilai serupa. (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. |
| HY009 | Penggunaan pointer null tidak valid | Argumen Attribute mengidentifikasi atribut lingkungan yang memerlukan nilai string, dan argumen ValuePtr adalah null pointer. |
| HY010 | Kesalahan urutan fungsi | (DM) Sebuah handle koneksi telah dialokasikan di EnvironmentHandle. (DM) SQL_ATTR_ODBC_VERSION belum diatur dengan SQLSetEnvAttr dan Atribut tidak sama dengan SQL_ATTR_ODBC_VERSION. 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. |
| HY024 | Nilai atribut tidak valid | Mengingat nilai Atribut yang ditentukan, nilai yang tidak valid ditentukan dalam ValuePtr. |
| HY090 | String atau panjang buffer tidak valid | Argumen StringLength kurang dari 0 tetapi tidak SQL_NTS. |
| HY092 | Pengidentifikasi atribut/opsi tidak valid | (DM) 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 argumen Attribute adalah atribut lingkungan ODBC yang valid untuk versi ODBC yang didukung oleh driver, tetapi tidak didukung oleh driver. (DM) Argumen Attribute adalah SQL_ATTR_OUTPUT_NTS, dan ValuePtr adalah SQL_FALSE. |
Komentar
Sebuah aplikasi hanya dapat memanggil SQLSetEnvAttr jika tidak ada handle koneksi yang dialokasikan di lingkungan. Semua atribut lingkungan yang berhasil diatur oleh aplikasi untuk lingkungan tersebut akan tetap ada hingga SQLFreeHandle dipanggil ke lingkungan. Lebih dari satu handle lingkungan dapat dialokasikan secara bersamaan di ODBC 3.x.
Format informasi yang ditetapkan melalui ValuePtr bergantung pada Atribut yang ditentukan. SQLSetEnvAttr akan menerima informasi atribut dalam salah satu dari dua format berbeda: string karakter null-terminated atau nilai integer 32-bit. Format masing-masing dicatat dalam deskripsi atribut.
Tidak ada atribut lingkungan khusus pengemudi.
Atribut koneksi tidak dapat diatur dengan panggilan ke SQLSetEnvAttr. Mencoba melakukan ini akan mengembalikan SQLSTATE HY092 (Identifier atribut/opsi tidak valid).
| Atribut | Konten ValuePtr |
|---|---|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) | Nilai SQLUINTEGER 32-bit yang mengaktifkan atau menonaktifkan connection pooling di tingkat lingkungan. Nilai-nilai berikut digunakan: SQL_CP_OFF = Connection pooling dimatikan. Ini adalah default. SQL_CP_ONE_PER_DRIVER = Satu pool koneksi didukung untuk setiap driver. Setiap koneksi dalam pool dikaitkan dengan satu driver. SQL_CP_ONE_PER_HENV = Satu pool koneksi didukung untuk setiap lingkungan. Setiap koneksi dalam pool terhubung dengan satu lingkungan. SQL_CP_DRIVER_AWARE = Gunakan fitur kesadaran connection-pool dari driver, jika tersedia. Jika driver tidak mendukung kesadaran connection-pool, SQL_CP_DRIVER_AWARE diabaikan dan SQL_CP_ONE_PER_HENV digunakan. Untuk informasi selengkapnya, lihat Pengumpulan Koneksi Sadar Driver. Dalam lingkungan di mana beberapa driver mendukung dan beberapa driver tidak mendukung kesadaran connection-pool, SQL_CP_DRIVER_AWARE dapat mengaktifkan fitur connection-pool awareness pada driver pendukung tersebut, tetapi ini setara dengan mengatur ke SQL_CP_ONE_PER_HENV pada driver yang tidak mendukung fitur connection-pool awareness. Connection pooling diaktifkan dengan memanggil SQLSetEnvAttr untuk mengatur atribut SQL_ATTR_CONNECTION_POOLING ke SQL_CP_ONE_PER_DRIVER atau SQL_CP_ONE_PER_HENV. Panggilan ini harus dilakukan sebelum aplikasi mengalokasikan lingkungan bersama tempat pengumpulan koneksi akan diaktifkan. Handle lingkungan dalam pemanggilan SQLSetEnvAttr diatur ke null, yang menjadikan SQL_ATTR_CONNECTION_POOLING atribut tingkat proses. Setelah connection pooling diaktifkan, aplikasi kemudian mengalokasikan lingkungan bersama implisit dengan memanggil SQLAllocHandle dengan argumen InputHandle diatur ke SQL_HANDLE_ENV. Setelah connection pooling diaktifkan dan lingkungan bersama dipilih untuk sebuah aplikasi, SQL_ATTR_CONNECTION_POOLING tidak dapat direset untuk lingkungan tersebut, karena SQLSetEnvAttr dipanggil dengan handle null environment saat mengatur atribut ini. Jika atribut ini diatur saat connection pooling sudah diaktifkan pada lingkungan bersama, atribut ini hanya memengaruhi lingkungan bersama yang dialokasikan selanjutnya. Juga memungkinkan untuk mengaktifkan connection pooling di sebuah lingkungan. Perhatikan hal berikut tentang pengumpulan koneksi lingkungan: - Mengaktifkan connection pooling pada handle NULL adalah atribut tingkat proses. Selanjutnya, lingkungan yang dialokasikan akan menjadi lingkungan bersama, dan akan mewarisi pengaturan pooling koneksi tingkat proses. - Setelah sebuah lingkungan dialokasikan, aplikasi masih dapat mengubah pengaturan kolam koneksinya. - Jika environment connection pooling diaktifkan dan driver koneksi menggunakan driver pooling, environment pooling menjadi prioritas. SQL_ATTR_CONNECTION_POOLING diimplementasikan di dalam Driver Manager. Driver tidak perlu mengimplementasikan SQL_ATTR_CONNECTION_POOLING. Aplikasi ODBC 2.0 dan 3.0 dapat mengatur atribut lingkungan ini. Untuk informasi selengkapnya, lihat Pooling Koneksi ODBC. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) | Nilai SQLUINTEGER 32-bit yang menentukan bagaimana koneksi dipilih dari pool koneksi. Ketika SQLConnect atau SQLDriverConnect dipanggil, Driver Manager menentukan koneksi mana yang digunakan kembali dari pool. Driver Manager mencoba mencocokkan opsi koneksi dalam panggilan dan atribut koneksi yang diatur oleh aplikasi dengan kata kunci dan atribut koneksi dari koneksi dalam pool. Nilai atribut ini menentukan tingkat presisi kriteria pencocokan. Nilai-nilai berikut digunakan untuk mengatur nilai atribut ini: SQL_CP_STRICT_MATCH = Hanya koneksi yang persis sesuai dengan opsi koneksi dalam panggilan dan atribut koneksi yang ditetapkan oleh aplikasi yang digunakan kembali. Ini adalah default. SQL_CP_RELAXED_MATCH = Koneksi dengan kata kunci string koneksi yang cocok dapat digunakan. Kata kunci harus sama, tetapi tidak semua atribut koneksi harus cocok. Untuk informasi lebih lanjut tentang bagaimana Driver Manager melakukan pencocokan dalam menghubungkan ke koneksi pooled, lihat SQLConnect. Untuk informasi selengkapnya tentang pengumpulan koneksi, lihat Pengumpulan Koneksi ODBC. |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | Sebuah bilangan bulat 32-bit yang menentukan apakah fungsi tertentu menunjukkan perilaku ODBC 2.x atau perilaku ODBC 3.x . Nilai-nilai berikut digunakan untuk mengatur nilai atribut ini: SQL_OV_ODBC3_80 = Driver Manager dan driver menunjukkan perilaku ODBC 3.8 berikut: - Pengemudi mengembalikan dan mengharapkan kode ODBC 3.x untuk tanggal, waktu, dan timestamp. - Driver mengembalikan kode ODBC 3.x SQLSTATE ketika SQLError, SQLGetDiagField, atau SQLGetDiagRec dipanggil. - Argumen CatalogName dalam pemanggilan SQLTables menerima pola pencarian. - Driver Manager mendukung ekstensibilitas tipe data C. Untuk informasi lebih lanjut tentang ekstensibilitas tipe data C, lihat Tipe Data C di ODBC. Untuk informasi lebih lanjut, lihat Apa yang Baru di ODBC 3.8. SQL_OV_ODBC3 = Driver Manager dan driver menunjukkan perilaku ODBC 3.x berikut: - Pengemudi mengembalikan dan mengharapkan kode ODBC 3.x untuk tanggal, waktu, dan timestamp. - Driver mengembalikan kode ODBC 3.x SQLSTATE ketika SQLError, SQLGetDiagField, atau SQLGetDiagRec dipanggil. - Argumen CatalogName dalam pemanggilan SQLTables menerima pola pencarian. - Driver Manager tidak mendukung ekstensibilitas tipe data C. SQL_OV_ODBC2 = Driver Manager dan driver menunjukkan perilaku ODBC 2.x berikut. Ini sangat berguna untuk aplikasi ODBC 2.x yang bekerja dengan driver ODBC 3.x . - Pengemudi mengembalikan dan mengharapkan kode ODBC 2.x untuk tanggal, waktu, dan timestamp. - Driver mengembalikan kode ODBC 2.x SQLSTATE ketika SQLError, SQLGetDiagField, atau SQLGetDiagRec dipanggil. - Argumen CatalogName dalam pemanggilan SQLTables tidak menerima pola pencarian. - Driver Manager tidak mendukung ekstensibilitas tipe data C. Sebuah aplikasi harus mengatur atribut lingkungan ini sebelum memanggil fungsi apa pun yang memiliki argumen SQLHENV, atau panggilan akan mengembalikan SQLSTATE HY010 (kesalahan urutan fungsi). Tergantung pada pengemudi apakah ada perilaku tambahan untuk bendera lingkungan ini. - Untuk informasi lebih lanjut, lihat Mendeklarasikan Versi ODBC Aplikasi dan Perubahan Perilaku. |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | Sebuah bilangan bulat 32-bit yang menentukan bagaimana driver mengembalikan data string. Jika SQL_TRUE, driver mengembalikan data string tanpa henti. Jika SQL_FALSE, driver tidak mengembalikan data string tanpa henti. Atribut ini secara default adalah SQL_TRUE. Pemanggilan ke SQLSetEnvAttr untuk mengaturnya ke SQL_TRUE mengembalikan SQL_SUCCESS. Pemanggilan ke SQLSetEnvAttr untuk mengaturnya ke SQL_FALSE mengembalikan SQL_ERROR dan SQLSTATE HYC00 (Fitur opsional tidak diimplementasikan). |
Fungsi Terkait
| Untuk informasi mengenai | Lihat |
|---|---|
| Mengalokasikan pegangan | Fungsi SQLAllocHandle |
| Mengembalikan pengaturan atribut lingkungan | Fungsi SQLGetEnvAttr |