Fungsi SQLInstallDriverEx
Kesesuaian
Versi diperkenalkan: ODBC 3.0
Ringkasan
SQLInstallDriverEx menambahkan informasi tentang driver ke entri Odbcinst.ini dalam informasi sistem dan menambah UsageCount driver sebesar 1. Namun, jika versi driver sudah ada tetapi nilai UsageCount untuk driver tidak ada, nilai UsageCount baru diatur ke 2.
Fungsi ini sebenarnya tidak menyalin file apa pun. Adalah tanggung jawab program panggilan untuk menyalin file driver ke direktori target dengan benar.
Fungsionalitas SQLInstallDriverEx juga dapat diakses dengan ODBCCONF.EXE.
Sintaks
BOOL SQLInstallDriverEx(
LPCSTR lpszDriver,
LPCSTR lpszPathIn,
LPSTR lpszPathOut,
WORD cbPathOutMax,
WORD * pcbPathOut,
WORD fRequest,
LPDWORD lpdwUsageCount);
Argumen
lpszDriver
[Input] Deskripsi driver (biasanya nama DBMS terkait) disajikan kepada pengguna alih-alih nama driver fisik. Argumen lpszDriver harus berisi daftar dua kali null-terminasi dari pasangan kata kunci-nilai yang menjelaskan driver. Untuk informasi selengkapnya tentang pasangan nilai kata kunci, lihat Subkunjuk Spesifikasi Driver. Untuk informasi selengkapnya tentang string doubly null-terminated, lihat Fungsi ConfigDSN.
lpszPathIn
[Input] Jalur lengkap direktori target penginstalan, atau penunjuk null. Jika lpszPathIn adalah penunjuk null, driver akan diinstal di direktori sistem.
lpszPathOut
[Output] Jalur direktori target tempat driver harus diinstal. Jika driver sebelumnya belum diinstal, lpszPathOut harus sama dengan lpszPathIn. Jika driver sebelumnya diinstal, lpszPathOut adalah jalur penginstalan sebelumnya.
cbPathOutMax
[Input] Panjang lpszPathOut.
pcbPathOut
[Output] Jumlah total byte (tidak termasuk karakter penghentian null) yang tersedia untuk dikembalikan di lpszPathOut. Jika jumlah byte yang tersedia untuk dikembalikan lebih besar dari atau sama dengan cbPathOutMax, jalur output di lpszPathOut dipotong menjadi cbPathOutMax dikurangi karakter null-termination. Argumen pcbPathOut dapat berupa penunjuk null.
fRequest
[Input] Jenis permintaan. Argumen fRequest harus berisi salah satu nilai berikut:
ODBC_INSTALL_INQUIRY: Tanyakan di mana driver dapat diinstal.
ODBC_INSTALL_COMPLETE: Selesaikan permintaan penginstalan.
lpdwUsageCount
[Output] Jumlah penggunaan driver setelah fungsi ini dipanggil.
Aplikasi tidak boleh mengatur jumlah penggunaan. ODBC akan mempertahankan jumlah ini.
Mengembalikan
Fungsi mengembalikan TRUE jika berhasil, FALSE jika gagal.
Diagnostik
Saat SQLInstallDriverEx mengembalikan FALSE, nilai *pfErrorCode terkait 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_GENERAL_ERR | Kesalahan penginstal umum | Terjadi kesalahan karena tidak ada kesalahan penginstal tertentu. |
| ODBC_ERROR_INVALID_BUFF_LEN | Panjang buffer tidak valid | Argumen lpszPathOut tidak cukup besar untuk berisi jalur output. Buffer berisi jalur terpotong. Argumen cbPathOutMax adalah 0, dan fRequest ODBC_INSTALL_COMPLETE. |
| ODBC_ERROR_INVALID_REQUEST_TYPE | Jenis permintaan tidak valid | Argumen fRequest bukan salah satu dari berikut ini: ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE |
| ODBC_ERROR_INVALID_KEYWORD_VALUE | Pasangan nilai kata kunci tidak valid | Argumen lpszDriver berisi kesalahan sintaks. |
| ODBC_ERROR_INVALID_PATH | Jalur penginstalan tidak valid | Argumen lpszPathIn berisi jalur yang tidak valid. |
| ODBC_ERROR_LOAD_LIBRARY_FAILED | Tidak dapat memuat pustaka penyetelan pengandar atau penerjemah | Pustaka penyetelan driver tidak dapat dimuat. |
| ODBC_ERROR_INVALID_PARAM_SEQUENCE | Urutan parameter tidak valid | Argumen lpszDriver tidak berisi daftar pasangan kata kunci-nilai. |
| ODBC_ERROR_USAGE_UPDATE_FAILED | Tidak dapat menaikkan atau mengurangi jumlah penggunaan komponen | Alat penginstal gagal menaikkan jumlah penggunaan driver. |
Komentar
Argumen lpszDriver adalah 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.) Format daftar ini adalah sebagai berikut:
driver-desc\ 0Driver=driver-DLL-filename\0[Setup-DLL-filename=\0]
[driver-attr-keyword1 value1=\0][driver-attr-keyword2=value2\0]...\0
di mana \0 adalah byte null dan driver-attr-keywordn adalah kata kunci atribut driver apa pun. Kata kunci harus muncul dalam urutan yang ditentukan. Misalnya, driver untuk file teks yang diformat memiliki driver terpisah dan menyiapkan DLL dan dapat menggunakan file dengan ekstensi .txt dan .csv. Argumen lpszDriver untuk driver ini mungkin sebagai berikut:
Text\0Driver=TEXT.DLL\0Setup=TXTSETUP.DLL\0FileUsage=1\0
FileExtns=*.txt,*.csv\0\0
Misalkan driver untuk SQL Server tidak memiliki DLL penyiapan terpisah dan tidak memiliki kata kunci atribut driver. Argumen lpszDriver untuk driver ini mungkin sebagai berikut:
SQL Server\0Driver=SQLSRVR.DLL\0\0
Setelah SQLInstallDriverEx mengambil informasi tentang driver dari argumen lpszDriver, SQLInstallDriverEx menambahkan deskripsi driver ke bagian [Driver ODBC] dari entri Odbcinst.ini dalam informasi sistem. Kemudian membuat bagian berjudul dengan deskripsi driver dan menambahkan jalur lengkap DLL driver dan DLL penyiapan. Akhirnya, ia mengembalikan jalur direktori target penginstalan tetapi tidak menyalin file driver ke dalamnya. Program pemanggilan harus benar-benar menyalin berkas pengandar ke direktori target.
SQLInstallDriverEx menaikkan jumlah penggunaan komponen untuk driver yang diinstal dengan 1. Jika versi driver sudah ada tetapi jumlah penggunaan komponen untuk driver tidak ada, nilai jumlah penggunaan komponen baru diatur ke 2.
Program penyiapan aplikasi bertanggung jawab untuk menyalin file driver secara fisik dan mempertahankan jumlah penggunaan file. Jika file driver sebelumnya belum diinstal, program penyiapan aplikasi harus menyalin file di jalur lpszPathIn dan membuat jumlah penggunaan file. Jika file sebelumnya telah diinstal, program penyiapan hanya menaikkan jumlah penggunaan file dan mengembalikan jalur penginstalan sebelumnya dalam argumen lpszPathOut .
Catatan
Untuk informasi selengkapnya tentang jumlah penggunaan komponen dan jumlah penggunaan file, lihat Penghitungan Penggunaan.
Jika versi lama file driver sebelumnya diinstal oleh aplikasi, driver harus dihapus instalannya lalu diinstal ulang, sehingga jumlah penggunaan komponen driver valid. SQLConfigDriver (dengan fRequest ODBC_REMOVE_DRIVER) harus terlebih dahulu dipanggil, lalu SQLRemoveDriver harus dipanggil untuk mengurangi jumlah penggunaan komponen. SQLInstallDriverEx kemudian harus dipanggil untuk menginstal ulang driver, meningkatkan jumlah penggunaan komponen. Program penyetelan aplikasi harus mengganti file lama dengan file baru. Jumlah penggunaan file akan tetap sama, dan aplikasi lain yang menggunakan file versi lama sekarang akan menggunakan versi yang lebih baru.
Catatan
Jika driver sebelumnya diinstal dan SQLInstallDriverEx dipanggil untuk menginstal driver di direktori yang berbeda, fungsi akan mengembalikan TRUE, tetapi lpszPathOut akan menyertakan direktori tempat driver sudah diinstal. Ini tidak akan menyertakan direktori yang dimasukkan dalam argumen lpszDriver .
Panjang jalur di lpszPathOut di SQLInstallDriverEx memungkinkan proses penginstalan dua fase, sehingga aplikasi dapat menentukan apa yang harus dilakukan cbPathOutMax dengan memanggil SQLInstallDriverEx dengan fRequest mode ODBC_INSTALL_INQUIRY. Ini akan mengembalikan jumlah total byte yang tersedia di buffer pcbPathOut . SQLInstallDriverEx kemudian dapat dipanggil dengan fRequest ODBC_INSTALL_COMPLETE dan argumen cbPathOutMax diatur ke nilai dalam buffer pcbPathOut , ditambah karakter null-termination.
Jika Anda memilih untuk tidak menggunakan model dua fase untuk SQLInstallDriverEx, Anda harus mengatur cbPathOutMax, yang menentukan ukuran penyimpanan untuk jalur direktori target, ke nilai _MAX_PATH, seperti yang didefinisikan dalam Stdlib.h, untuk mencegah pemotongan.
Saat fRequest ODBC_INSTALL_COMPLETE, SQLInstallDriverEx tidak mengizinkan lpszPathOut menjadi NULL (atau cbPathOutMax menjadi 0). Jika fRequest ODBC_INSTALL_COMPLETE, FALSE dikembalikan ketika jumlah byte yang tersedia untuk dikembalikan lebih besar dari atau sama dengan cbPathOutMax, dengan hasil pemotongan terjadi.
Setelah SQLInstallDriverEx dipanggil dan program penyiapan aplikasi telah menyalin file driver (jika perlu), DLL penyiapan driver harus memanggil SQLConfigDriver untuk mengatur konfigurasi untuk driver.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Menginstal Driver Manager | SQLInstallDriverManager |
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