Fungsi ConfigDSN

Kesesuaian
Versi Diperkenalkan: ODBC 1.0

Ringkasan
ConfigDSN menambahkan, memodifikasi, atau menghapus sumber data dari informasi sistem. Ini dapat meminta pengguna untuk informasi koneksi. Ini bisa berada di DLL driver atau DLL penyetelan terpisah.

Sintaks

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);  

Argumen

hwndParent
[Input] Handel jendela induk. Fungsi tidak akan menampilkan kotak dialog apa pun jika handel null.

fRequest
[Input] Jenis permintaan. Argumen fRequest harus berisi salah satu nilai berikut:

ODBC_ADD_DSN: Tambahkan sumber data baru.

ODBC_CONFIG_DSN: Mengonfigurasi (memodifikasi) sumber data yang ada.

ODBC_REMOVE_DSN: Hapus sumber data yang sudah ada.

lpszDriver
[Input] Deskripsi driver (biasanya nama DBMS terkait) yang disajikan kepada pengguna alih-alih nama driver fisik.

lpszAttributes
[Input] Daftar atribut dua kali dihentikan null dalam bentuk pasangan kata kunci-nilai. Untuk informasi selengkapnya, lihat "Komentar."

Kembali

Fungsi mengembalikan TRUE jika berhasil, FALSE jika gagal.

Diagnostik

Ketika ConfigDSN mengembalikan FALSE, nilai *pfErrorCode terkait diposting ke buffer kesalahan penginstal dengan panggilan ke SQLPostInstallerError dan dapat diperoleh dengan memanggil SQLInstallerError. Tabel berikut mencantumkan nilai *pfErrorCode yang dapat dikembalikan oleh SQLInstallerError dan menjelaskan masing-masing nilai dalam konteks fungsi ini.

*pfErrorCode	Kesalahan	Deskripsi
ODBC_ERROR_INVALID_HWND	Handel jendela tidak valid	Argumen hwndParent tidak valid.
ODBC_ERROR_INVALID_KEYWORD_VALUE	Pasangan nilai kata kunci tidak valid	Argumen lpszAttributes berisi kesalahan sintaks.
ODBC_ERROR_INVALID_NAME	Nama pengandar atau penerjemah tidak valid	Argumen lpszDriver tidak valid. Ini tidak dapat ditemukan di registri.
ODBC_ERROR_INVALID_REQUEST_TYPE	Jenis permintaan tidak valid	Argumen fRequest bukan salah satu dari berikut ini: ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN
ODBC_ERROR_REQUEST_FAILED	Permintaan gagal	Tidak dapat melakukan operasi yang diminta oleh argumen fRequest .
ODBC_ERROR_DRIVER_SPECIFIC	Kesalahan khusus driver atau penerjemah	Kesalahan khusus driver yang tidak ada kesalahan penginstal ODBC yang ditentukan. Argumen SzError dalam panggilan ke fungsi SQLPostInstallerError harus berisi pesan kesalahan khusus driver.

Komentar

ConfigDSN menerima informasi koneksi dari DLL penginstal sebagai daftar atribut dalam bentuk pasangan kata kunci-nilai. Setiap pasangan dihentikan dengan byte null, dan seluruh daftar dihentikan dengan byte null. (Artinya, dua byte null menandai akhir daftar.) Spasi tidak diperbolehkan di sekitar tanda sama dengan pasangan kata kunci-nilai. ConfigDSN dapat menerima kata kunci yang bukan kata kunci yang valid untuk SQLBrowseConnect dan SQLDriverConnect. ConfigDSN tidak selalu mendukung semua kata kunci yang merupakan kata kunci yang valid untuk SQLBrowseConnect dan SQLDriverConnect. (ConfigDSN tidak menerima kata kunci DRIVER .) Kata kunci yang digunakan oleh fungsi ConfigDSN harus mendukung semua opsi yang diperlukan untuk membuat ulang sumber data menggunakan fitur penyiapan OTOMATIS alat penginstal. Ketika penggunaan nilai ConfigDSN dan nilai string koneksi sama, kata kunci yang sama harus digunakan.

Seperti dalam SQLBrowseConnect dan SQLDriverConnect, kata kunci dan nilainya tidak boleh berisi []{}(),;? *=!@ karakter, dan nilai kata kunci DSN tidak boleh hanya terdiri dari kosong. Karena tata bahasa registri, kata kunci dan nama sumber data tidak boleh berisi karakter garis miring terbelakang (\).

ConfigDSN harus memanggil SQLValidDSN untuk memeriksa panjang nama sumber data dan untuk memverifikasi bahwa tidak ada karakter yang tidak valid yang disertakan dalam nama. Jika nama sumber data lebih panjang dari SQL_MAX_DSN_LENGTH atau menyertakan karakter yang tidak valid, SQLValidDSN mengembalikan kesalahan dan ConfigDSN mengembalikan kesalahan. Panjang nama sumber data juga diperiksa oleh SQLWriteDSNToIni.

Misalnya, untuk mengonfigurasi sumber data yang memerlukan ID pengguna, kata sandi, dan nama database, aplikasi penyiapan mungkin melewati pasangan nilai kata kunci berikut:

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0  

Untuk informasi selengkapnya tentang kata kunci ini, lihat SQLDriverConnect dan dokumentasi setiap driver.

Untuk menampilkan kotak dialog, hwndParent tidak boleh null.

Menambahkan Sumber Data

Jika nama sumber data diteruskan ke ConfigDSN di lpszAttributes, ConfigDSN memeriksa apakah nama tersebut valid. Jika nama sumber data cocok dengan nama sumber data yang ada dan hwndParent null, ConfigDSN menimpa nama yang ada. Jika cocok dengan nama yang ada dan hwndParent tidak null, ConfigDSN meminta pengguna untuk menimpa nama yang ada.

Jika lpszAttributes berisi informasi yang cukup untuk menyambungkan ke sumber data, ConfigDSN dapat menambahkan sumber data atau menampilkan kotak dialog tempat pengguna dapat mengubah informasi koneksi. Jika lpszAttributes tidak berisi informasi yang cukup untuk terhubung ke sumber data, ConfigDSN harus menentukan informasi yang diperlukan; jika hwndParent tidak null, maka akan menampilkan kotak dialog untuk mengambil informasi dari pengguna.

Jika ConfigDSN menampilkan kotak dialog, itu harus menampilkan informasi koneksi apa pun yang diteruskan ke dalam lpszAttributes. Secara khusus, jika nama sumber data diteruskan ke nama tersebut, ConfigDSN menampilkan nama tersebut tetapi tidak memungkinkan pengguna untuk mengubahnya. ConfigDSN dapat menyediakan nilai default untuk informasi koneksi yang tidak diteruskan ke dalam lpszAttributes.

Jika ConfigDSN tidak bisa mendapatkan informasi koneksi lengkap untuk sumber data, maka akan mengembalikan FALSE.

Jika ConfigDSN bisa mendapatkan informasi koneksi lengkap untuk sumber data, ConfigDSNToIni memanggil SQLWriteDSNToIni di DLL penginstal untuk menambahkan spesifikasi sumber data baru ke file Odbc.ini (atau registri). SQLWriteDSNToIni menambahkan nama sumber data ke bagian [Sumber Data ODBC], membuat bagian spesifikasi sumber data, dan menambahkan kata kunci DRIVER dengan deskripsi driver sebagai nilainya. ConfigDSN memanggil SQLWritePrivateProfileString di DLL penginstal untuk menambahkan kata kunci dan nilai tambahan yang digunakan oleh driver.

Memodifikasi Sumber Data

Untuk mengubah sumber data, nama sumber data harus diteruskan ke ConfigDSN di lpszAttributes. ConfigDSN memeriksa bahwa nama sumber data berada dalam file Odbc.ini (atau registri).

Jika hwndParent null, ConfigDSN menggunakan informasi di lpszAttributes untuk memodifikasi informasi dalam file Odbc.ini (atau registri). Jika hwndParent tidak null, ConfigDSN menampilkan kotak dialog menggunakan informasi di lpszAttributes; untuk informasi yang tidak ada di lpszAttributes, ini menggunakan informasi dari informasi sistem. Pengguna dapat mengubah informasi sebelum ConfigDSN menyimpannya dalam informasi sistem.

Jika nama sumber data diubah, ConfigDSN terlebih dahulu memanggil SQLRemoveDSNFromIni di DLL penginstal untuk menghapus spesifikasi sumber data yang ada dari file Odbc.ini (atau registri). Kemudian mengikuti langkah-langkah di bagian sebelumnya untuk menambahkan spesifikasi sumber data baru. Jika nama sumber data tidak diubah, ConfigDSN memanggil SQLWritePrivateProfileString di DLL penginstal untuk membuat perubahan lain. ConfigDSN mungkin tidak menghapus atau mengubah nilai kata kunci Driver .

Menghapus Sumber Data

Untuk menghapus sumber data, nama sumber data harus diteruskan ke ConfigDSN di lpszAttributes. ConfigDSN memeriksa bahwa nama sumber data berada dalam file Odbc.ini (atau registri). Kemudian memanggil SQLRemoveDSNFromIni di DLL penginstal untuk menghapus sumber data.

Catatan

Jika menulis versi Unicode dari rutinitas ini, itu harus disebut ConfigDSNW, dengan argumen LPCWSTR alih-alih LPCSTR.

Fungsi Terkait

Untuk informasi tentang	Lihat
Menambahkan, memodifikasi, atau menghapus sumber data	SQLConfigDataSource
Mendapatkan nilai dari file Odbc.ini atau registri	SQLGetPrivateProfileString
Menghapus sumber data default	SQLRemoveDefaultDataSource
Menghapus nama sumber data dari Odbc.ini (atau registri)	SQLRemovedsnFromIni
Menambahkan nama sumber data ke Odbc.ini (atau registri)	SQLWritedsnToIni
Menulis nilai ke file Odbc.ini atau registri	SQLWritePrivateProfileString