Fungsi SQLSetEnvAttr
Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 3.0: ISO 92
Ringkasan
SQLSetEnvAttr menetapkan atribut yang mengatur aspek lingkungan.
Sintaks
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Argumen
EnvironmentHandle
[Input] Penanganan lingkungan.
Atribut
[Input] Atribut yang akan diatur, tercantum dalam "Komentar."
ValuePtr
[Input] Penunjuk ke nilai yang akan dikaitkan dengan Atribut. Bergantung pada nilai Atribut, ValuePtr akan menjadi nilai bilangan bulat 32-bit atau menunjuk ke string karakter yang dihentikan null.
StringLength
[Input] Jika ValuePtr menunjuk ke string karakter atau buffer biner, argumen ini harus panjang *ValuePtr. Untuk data string karakter, argumen ini harus berisi jumlah byte dalam string.
Jika ValuePtr adalah bilangan bulat, StringLength diabaikan.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLSetEnvAttr 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 biasanya dikembalikan oleh SQLSetEnvAttr 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. Jika driver tidak mendukung atribut lingkungan, kesalahan hanya dapat dikembalikan selama waktu koneksi.
| SQLSTATE | Kesalahan | Deskripsi |
|---|---|---|
| 01000 | Peringatan umum | Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Nilai opsi berubah | Driver tidak mendukung nilai yang ditentukan dalam ValuePtr dan menggantikan 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 Atribut mengidentifikasi atribut lingkungan yang memerlukan nilai string, dan argumen ValuePtr adalah penunjuk null. |
| HY010 | Kesalahan urutan fungsi | (DM) Handel koneksi telah dialokasikan pada 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 atribut argumen adalah atribut lingkungan ODBC yang valid untuk versi ODBC yang didukung oleh driver, tetapi tidak didukung oleh driver. (DM) Argumen Atribut SQL_ATTR_OUTPUT_NTS, dan ValuePtr SQL_FALSE. |
Komentar
Aplikasi dapat memanggil SQLSetEnvAttr hanya jika tidak ada handel koneksi yang dialokasikan di lingkungan. Semua atribut lingkungan berhasil diatur oleh aplikasi untuk lingkungan bertahan hingga SQLFreeHandle dipanggil pada lingkungan. Lebih dari satu handel lingkungan dapat dialokasikan secara bersamaan di ODBC 3.x.
Format informasi yang ditetapkan melalui ValuePtr tergantung pada Atribut yang ditentukan. SQLSetEnvAttr akan menerima informasi atribut dalam salah satu dari dua format berbeda: string karakter null-terminated atau nilai bilangan bulat 32-bit. Format masing-masing dicatat dalam deskripsi atribut.
Tidak ada atribut lingkungan khusus driver.
Atribut koneksi tidak dapat diatur oleh panggilan ke SQLSetEnvAttr. Mencoba melakukan ini akan mengembalikan SQLSTATE HY092 (Pengidentifikasi atribut/opsi tidak valid).
| Atribut | Konten ValuePtr |
|---|---|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) | Nilai SQLUINTEGER 32-bit yang memungkinkan atau menonaktifkan pengumpulan koneksi di tingkat lingkungan. Nilai berikut digunakan: SQL_CP_OFF = Pengumpulan koneksi dinonaktifkan. Ini adalah default. SQL_CP_ONE_PER_DRIVER = Satu kumpulan koneksi didukung untuk setiap driver. Setiap koneksi dalam kumpulan dikaitkan dengan satu driver. SQL_CP_ONE_PER_HENV = Satu kumpulan koneksi didukung untuk setiap lingkungan. Setiap koneksi dalam kumpulan dikaitkan dengan satu lingkungan. SQL_CP_DRIVER_AWARE = Gunakan fitur kesadaran kumpulan koneksi driver, jika tersedia. Jika driver tidak mendukung kesadaran kumpulan koneksi, SQL_CP_DRIVER_AWARE diabaikan dan SQL_CP_ONE_PER_HENV digunakan. Untuk informasi selengkapnya, lihat Pengumpulan Koneksi Sadar Driver. Di lingkungan di mana beberapa driver mendukung dan beberapa driver tidak mendukung kesadaran kumpulan koneksi, SQL_CP_DRIVER_AWARE dapat mengaktifkan fitur kesadaran kumpulan koneksi pada driver pendukung tersebut, tetapi setara dengan pengaturan ke SQL_CP_ONE_PER_HENV pada driver yang tidak mendukung fitur kesadaran kumpulan koneksi. Pengumpulan koneksi 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. Handel lingkungan dalam panggilan ke SQLSetEnvAttr diatur ke null, yang membuat SQL_ATTR_CONNECTION_POOLING atribut tingkat proses. Setelah pengumpulan koneksi diaktifkan, aplikasi kemudian mengalokasikan lingkungan bersama implisit dengan memanggil SQLAllocHandle dengan argumen InputHandle yang diatur ke SQL_HANDLE_ENV. Setelah pengumpulan koneksi diaktifkan dan lingkungan bersama telah dipilih untuk aplikasi, SQL_ATTR_CONNECTION_POOLING tidak dapat diatur ulang untuk lingkungan tersebut, karena SQLSetEnvAttr dipanggil dengan handel lingkungan null saat mengatur atribut ini. Jika atribut ini diatur saat pengumpulan koneksi sudah diaktifkan pada lingkungan bersama, atribut hanya memengaruhi lingkungan bersama yang dialokasikan kemudian. Dimungkinkan juga untuk mengaktifkan pengumpulan koneksi pada lingkungan. Perhatikan hal berikut tentang pengumpulan koneksi lingkungan: - Mengaktifkan pengumpulan koneksi pada handel NULL adalah atribut tingkat proses. Lingkungan yang dialokasikan berikutnya akan menjadi lingkungan bersama, dan akan mewarisi pengaturan pengumpulan koneksi tingkat proses. - Setelah lingkungan dialokasikan, aplikasi masih dapat mengubah pengaturan kumpulan koneksinya. - Jika pengumpulan koneksi lingkungan diaktifkan dan driver koneksi menggunakan pengumpulan driver, pengumpulan lingkungan mengambil preferensi. SQL_ATTR_CONNECTION_POOLING diimplementasikan di dalam Driver Manager. Driver tidak perlu menerapkan SQL_ATTR_CONNECTION_POOLING. Aplikasi ODBC 2.0 dan 3.0 dapat mengatur atribut lingkungan ini. Untuk informasi selengkapnya, lihat Pengumpulan Koneksi ODBC. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) | Nilai SQLUINTEGER 32-bit yang menentukan bagaimana koneksi dipilih dari kumpulan koneksi. Ketika SQLConnect atau SQLDriverConnect dipanggil, Manajer Driver menentukan koneksi mana yang digunakan kembali dari kumpulan. Driver Manager mencoba mencocokkan opsi koneksi dalam panggilan dan atribut koneksi yang diatur oleh aplikasi ke kata kunci dan atribut koneksi koneksi di kumpulan. Nilai atribut ini menentukan tingkat presisi kriteria pencocokan. Nilai berikut digunakan untuk mengatur nilai atribut ini: SQL_CP_STRICT_MATCH = Hanya koneksi yang sama persis dengan opsi koneksi dalam panggilan dan atribut koneksi yang diatur 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 cocok, tetapi tidak semua atribut koneksi harus cocok. Untuk informasi selengkapnya tentang bagaimana Manajer Driver melakukan kecocokan dalam menyambungkan ke koneksi terkumpul, lihat SQLConnect. Untuk informasi selengkapnya tentang pengumpulan koneksi, lihat Pengumpulan Koneksi ODBC. |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | Bilangan bulat 32-bit yang menentukan apakah fungsionalitas tertentu menunjukkan perilaku ODBC 2.x atau perilaku ODBC 3.x . Nilai berikut digunakan untuk mengatur nilai atribut ini: SQL_OV_ODBC3_80 = Manajer Driver dan driver menunjukkan perilaku ODBC 3.8 berikut: - Driver mengembalikan dan mengharapkan kode ODBC 3.x untuk tanggal, waktu, dan tanda waktu. - Driver mengembalikan kode ODBC 3.x SQLSTATE saat SQLError, SQLGetDiagField, atau SQLGetDiagRec dipanggil. - Argumen CatalogName dalam panggilan ke SQLTables menerima pola pencarian. - Driver Manager mendukung ekstensibilitas jenis data C. Untuk informasi selengkapnya tentang ekstensibilitas jenis data C, lihat Tipe Data C di ODBC. Untuk informasi selengkapnya, lihat Apa yang Baru di ODBC 3.8. SQL_OV_ODBC3 = Manajer Driver dan driver menunjukkan perilaku ODBC 3.x berikut: - Driver mengembalikan dan mengharapkan kode ODBC 3.x untuk tanggal, waktu, dan tanda waktu. - Driver mengembalikan kode ODBC 3.x SQLSTATE saat SQLError, SQLGetDiagField, atau SQLGetDiagRec dipanggil. - Argumen CatalogName dalam panggilan ke SQLTables menerima pola pencarian. - Driver Manager tidak mendukung ekstensibilitas jenis data C. SQL_OV_ODBC2 = Manajer Driver dan driver menunjukkan perilaku ODBC 2.x berikut. Ini sangat berguna untuk aplikasi ODBC 2.x yang bekerja dengan driver ODBC 3.x . - Driver mengembalikan dan mengharapkan kode ODBC 2.x untuk tanggal, waktu, dan tanda waktu. - Driver mengembalikan kode ODBC 2.x SQLSTATE saat SQLError, SQLGetDiagField, atau SQLGetDiagRec dipanggil. - Argumen CatalogName dalam panggilan ke SQLTables tidak menerima pola pencarian. - Driver Manager tidak mendukung ekstensibilitas jenis data C. Aplikasi harus mengatur atribut lingkungan ini sebelum memanggil fungsi apa pun yang memiliki argumen SQLHENV, atau panggilan akan mengembalikan SQLSTATE HY010 (Kesalahan urutan fungsi). Ini khusus driver apakah perilaku tambahan ada untuk bendera lingkungan ini. - Untuk informasi selengkapnya, lihat Mendeklarasikan Versi ODBC aplikasi dan Perubahan Perilaku. |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | Bilangan bulat 32-bit yang menentukan bagaimana driver mengembalikan data string. Jika SQL_TRUE, driver mengembalikan data string yang dihentikan null. Jika SQL_FALSE, driver tidak mengembalikan data string yang dihentikan null. Atribut ini default ke SQL_TRUE. Panggilan ke SQLSetEnvAttr untuk mengaturnya ke SQL_TRUE mengembalikan SQL_SUCCESS. Panggilan ke SQLSetEnvAttr untuk mengaturnya ke SQL_FALSE mengembalikan SQL_ERROR dan SQLSTATE HYC00 (Fitur opsional tidak diimplementasikan). |
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengalokasikan handel | Fungsi SQLAllocHandle |
| Mengembalikan pengaturan atribut lingkungan | Fungsi SQLGetEnvAttr |
Lihat Juga
Referensi API ODBC
File Header ODBC
Apa yang Baru di ODBC 3.8
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