Fungsi SQLInstallTranslatorEx

Kesesuaian
Versi diperkenalkan: ODBC 3.0

Ringkasan
SQLInstallTranslatorEx menambahkan informasi tentang penerjemah ke bagian Odbcinst.ini dari informasi sistem (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST. Kunci registri PENerjemah INI\ODBC).

Fungsionalitas SQLInstallTranslatorEx juga dapat diakses dengan ODBCCONF.EXE.

Sintaks

  
BOOL SQLInstallTranslatorEx(  
     LPCSTR    lpszTranslator,  
     LPCSTR    lpszPathIn,  
     LPSTR     lpszPathOut,  
     WORD      cbPathOutMax,  
     WORD *    pcbPathOut,  
     WORD      fRequest,  
     LPDWORD   lpdwUsageCount);  

Argumen

lpszTranslator
[Input] Ini harus berisi daftar pasangan kata kunci-nilai yang dihentikan dua kali lipat yang menjelaskan penerjemah. Untuk informasi selengkapnya tentang sintaks pasangan kata kunci-nilai, lihat Subkuntang Spesifikasi Penerjemah.

Kata kunci Penerjemah dan Penyiapan harus disertakan dalam string lpszTranslator. DLL terjemahan tercantum dengan kata kunci Penerjemah , dan DLL penyiapan penerjemah tercantum dengan kata kunci Penyetelan . Setiap pasangan dihentikan dengan byte NULL, dan seluruh daftar dihentikan dengan byte NULL. (Artinya, dua byte NULL menandai akhir daftar.) Format lpszTranslator adalah sebagai berikut:

\0Translator=translator-DLL-filename\0[Setup=setup-DLL-filename\0]\0

lpszPathIn
[Input] Jalur lengkap tempat penerjemah akan diinstal atau penunjuk null. Jika lpszPath adalah penunjuk null, penerjemah akan diinstal di direktori Sistem.

lpszPathOut
[Output] Jalur direktori target tempat penerjemah harus diinstal. Jika penerjemah belum pernah diinstal, lpszPathOut sama dengan lpszPathIn. Jika ada penginstalan penerjemah sebelumnya, lpszPathOut adalah jalur penginstalan sebelumnya.

cbPathOutMax
[Input] Panjang lpszPathOut.

pcbPathOut
[Output] Jumlah total byte 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 ke pcbPathOutMax dikurangi karakter null-termination. Argumen pcbPathOut dapat berupa penunjuk null.

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

ODBC_INSTALL_INQUIRY: Tanyakan di mana penerjemah dapat diinstal.

ODBC_INSTALL_COMPLETE: Selesaikan permintaan penginstalan.

lpdwUsageCount
[Output] Jumlah penggunaan penerjemah setelah fungsi ini dipanggil.

Aplikasi tidak boleh mengatur jumlah penggunaan. ODBC akan mempertahankan jumlah ini.

Kembali

Fungsi mengembalikan TRUE jika berhasil, FALSE jika gagal.

Diagnostik

Ketika SQLInstallTranslatorEx 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 argumen 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 lpszTranslator berisi kesalahan sintaks.
ODBC_ERROR_INVALID_PATH	Jalur penginstalan tidak valid	Argumen lpszPathIn berisi jalur yang tidak valid.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Urutan parameter tidak valid	Argumen lpszTranslator tidak berisi daftar pasangan kata kunci-nilai.
ODBC_ERROR_USAGE_UPDATE_FAILED	Tidak dapat menaikkan atau mengurangi jumlah penggunaan komponen registri	Alat penginstal gagal menaikkan jumlah penggunaan penerjemah.

Komentar

SQLInstallTranslatorEx menyediakan mekanisme untuk menginstal penerjemah saja. Fungsi ini sebenarnya tidak menyalin file apa pun. Program panggilan bertanggung jawab untuk menyalin file penerjemah.

SQLInstallTranslatorEx menaikkan jumlah penggunaan komponen untuk penerjemah yang diinstal dengan 1. Jika versi penerjemah sudah ada tetapi jumlah penggunaan komponen untuk penerjemah tidak ada, nilai jumlah penggunaan komponen baru diatur ke 2.

Program penyiapan aplikasi bertanggung jawab untuk menyalin file penerjemah secara fisik dan mempertahankan jumlah penggunaan file. Jika file penerjemah belum diinstal sebelumnya, program penyiapan aplikasi harus menyalin file atau file dan membuat jumlah penggunaan file atau file. Jika file sebelumnya telah diinstal, program penyiapan hanya akan menaikkan jumlah penggunaan file.

Jika versi penerjemah yang lebih lama sebelumnya diinstal oleh aplikasi, penerjemah harus dihapus instalasinya lalu diinstal ulang, sehingga jumlah penggunaan komponen penerjemah valid. SQLRemoveTranslator harus dipanggil untuk mendekremen jumlah penggunaan komponen, lalu SQLInstallTranslatorEx harus dipanggil untuk menaikkan jumlah penggunaan komponen. Program penyetelan aplikasi harus mengganti file atau file lama dengan file baru. Jumlah penggunaan file akan tetap sama, dan aplikasi lain yang menggunakan file versi yang lebih lama sekarang akan menggunakan versi yang lebih baru.

Panjang jalur di lpszPathOut di SQLInstallTranslatorEx memungkinkan proses penginstalan dua fase, sehingga aplikasi dapat menentukan apa yang harus dilakukan cbPathOutMax dengan memanggil SQLInstallTranslatorEx dengan fRequest mode ODBC_INSTALL_INQUIRY. Ini akan mengembalikan jumlah total byte yang tersedia di buffer pcbPathOut . SQLInstallTranslatorEx 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 SQLInstallTranslatorEx, 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.

Ketika fRequest ODBC_INSTALL_COMPLETE, SQLInstallTranslatorEx 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.

Fungsi Terkait

Untuk informasi tentang	Lihat
Mengembalikan opsi terjemahan default	ConfigTranslator
Memilih penerjemah	SQLGetTranslator
Menghapus penerjemah	SQLRemoveTranslator