Fungsi SQLCreateDataSource

Kesesuaian
Versi diperkenalkan: ODBC 2.0

Ringkasan
SQLCreateDataSource menampilkan kotak dialog tempat pengguna dapat menambahkan sumber data.

Sintaks

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);  

Argumen

hwnd
[Input] Handel jendela induk.

lpszDS
[Input] Nama sumber data. lpszDS dapat berupa pointer null atau string kosong.

Kembali

SQLCreateDataSource mengembalikan TRUE jika sumber data dibuat. Jika tidak, ia mengembalikan FALSE.

Diagnostik

Ketika SQLCreateDataSource 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_HWND	Handel jendela tidak valid	Argumen hwnd tidak valid atau NULL.
ODBC_ERROR_INVALID_DSN	DSN Tidak Valid	Argumen lpszDS berisi string yang tidak valid untuk DSN.
ODBC_ERROR_REQUEST_FAILED	Permintaan gagal	Panggilan ke ConfigDSN dengan opsi ODBC_ADD_DSN gagal.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Tidak dapat memuat pustaka penyetelan pengandar atau penerjemah	Pustaka penyetelan driver tidak dapat dimuat.
ODBC_ERROR_USER_CANCELED	Operasi pembatalan pengguna	Pengguna membatalkan pembuatan sumber data baru.
ODBC_ERROR_CREATE_DSN_FAILED	Tidak dapat membuat DSN yang diminta	Tidak dapat tersambung ke database; panggilan ke SQLDriverConnect untuk File DSN tidak mengembalikan koneksi yang berhasil. Tidak dapat menulis ke file.
ODBC_ERROR_OUT_OF_MEM	Kehabisan memori	Alat penginstal tidak dapat melakukan fungsi karena kurangnya memori.

Komentar

Jika hwnd null, SQLCreateDataSource mengembalikan FALSE. Jika tidak, kotak dialog Buat Sumber Data Baru dengan halaman panduan untuk memilih jenis sumber data yang akan disiapkan, seperti yang diperlihatkan dalam ilustrasi berikut ini.

Opsi defaultnya adalah Sumber Data File. Ketika sumber data telah dipilih dan Berikutnya diklik, halaman panduan berikut yang berisi daftar driver yang diinstal ditampilkan.

Jika Batal diklik, kotak dialog menghilang dan SQLCreateDataSource mengembalikan FALSE dengan kode kesalahan ODBC_ERROR_USER_CANCELED. Jika opsi Sumber Data Pengguna atau Sumber Data Sistem dipilih, tombol Tingkat Lanjut tidak tersedia.

Saat tombol Berikutnya diklik, salah satu hal berikut ini akan terjadi, bergantung pada jenis sumber data mana yang dipilih:

• Jika Sumber Data File dipilih, halaman wizard ditampilkan agar pengguna memasukkan nama file.

• Jika Sumber Data Pengguna atau Sumber Data Sistem dipilih, halaman wizard yang menampilkan jenis sumber data dan driver ditampilkan untuk ditinjau, dan ketika Selesai diklik, sumber data disiapkan.

Jika Tingkat Lanjut diklik dari halaman wizard Buat Sumber Data Baru, halaman panduan ditampilkan agar pengguna memasukkan informasi khusus driver. Dalam kotak teks kotak dialog ini, ketik driver dan kata kunci yang dipisahkan oleh pengembalian, seperti yang diperlihatkan dalam ilustrasi berikut.

Kata kunci khusus driver tambahan dapat ditemukan di bawah deskripsi SQLDriverConnect. Semua kecuali DSN diizinkan.

Default untuk opsi Verifikasi Koneksi Ini adalah TRUE. Default ini berlaku apakah halaman wisaya ini diaktifkan atau tidak. Jika OK diklik, string yang ditentukan dalam kotak teks dan nilai opsi Verifikasi Koneksi Ini di-cache. (Jika Tombol Tutup atau Batal diklik, informasi khusus driver yang baru dimasukkan hilang karena string yang ditentukan dalam kotak teks dan verifikasi nilai opsi Koneksi ini tidak di-cache.)

Jika Sumber Data File dipilih di halaman wizard pertama, maka setelah driver dipilih dan nilai kata kunci telah dimasukkan di halaman Panduan tingkat lanjut, pengguna diminta untuk memasukkan nama file. Klik Telusuri untuk mencari nama file, dalam hal ini direktori default dalam kotak Telusuri ditentukan oleh kombinasi jalur yang ditentukan oleh CommonFileDir di HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion dan "ODBC\DataSources". (Jika CommonFileDir adalah "C:\Program Files\Common Files", direktori defaultnya adalah "C:\Program Files\Common Files\ODBC\Data Sources".)

Ketika nama file telah dimasukkan dan Berikutnya diklik, nama file yang dimasukkan diperiksa validitasnya terhadap aturan penamaan file standar sistem operasi. Jika nama file tidak valid, kotak pesan kesalahan memberi tahu pengguna bahwa nama file yang tidak valid dimasukkan. Setelah pengguna mengakui kotak pesan, fokus dikembalikan ke halaman wizard tempat nama file dimasukkan. Jika nama file valid, halaman wizard yang memperlihatkan pasangan kata kunci-nilai yang dipilih ditampilkan untuk ditinjau, seperti yang diperlihatkan dalam ilustrasi berikut.

Jika Selesai diklik dan Sumber Data File dipilih sebagai jenis sumber data, dan jika opsi Verifikasi koneksi ini TRUE, SQLDriverConnect dipanggil dengan kata kunci SAVEFILE dan DRIVER . Argumen DriverCompletion diatur ke SQL_DRIVER_COMPLETE. Nama file untuk kata kunci SAVEFILE adalah nama yang dimasukkan atau dipilih, dan nama driver untuk kata kunci DRIVER adalah nama yang dipilih. Jika string koneksi khusus driver ditentukan di halaman Wizard tingkat lanjut, string tersebut ditambahkan setelah kata kunci DRIVER .

Jika SQLDriverConnect mengembalikan SQL_SUCCESS, Manajer Driver telah membuat File DSN. SQLCreateDataSource mengembalikan TRUE. Jika SQLDriverConnect tidak mengembalikan SQL_SUCCESS, kotak pesan peringatan menunjukkan bahwa koneksi tidak dapat dibuat ke sumber data. DSN dengan informasi koneksi minimal masih dapat dibuat. Kotak pesan ini memungkinkan pengguna membatalkan atau melanjutkan pembuatan File DSN.

Jika pengguna memilih untuk terus membuat DSN, proses ini berlanjut seolah-olah opsi Verifikasi koneksi ini diatur ke FALSE. Jika pengguna memilih untuk membatalkan, FALSE dikembalikan untuk SQLCreateDataSource dengan kode kesalahan ODBC_ERROR_CREATE_DSN_FAILED.

Jika Sumber Data File dipilih sebagai jenis sumber data dan opsi Verifikasi koneksi ini FALSE, File DSN dibuat dengan kata kunci DRIVER dan string koneksi yang ditentukan pengguna (jika ada) dari halaman Wizard tingkat lanjut. Jika pembuatan file berhasil, TRUE dikembalikan untuk SQLCreateDataSource. Jika pembuatan file tidak berhasil, kotak pesan kesalahan memberi tahu pengguna dengan kesalahan apa pun yang dikembalikan dari sistem operasi. FALSE dikembalikan untuk SQLCreateDataSource dengan kode kesalahan ODBC_ERROR_CREATE_DSN_FAILED. Untuk informasi selengkapnya tentang sumber data file, lihat Menyambungkan Menggunakan Sumber Data File, atau lihat SQLDriverConnect.

Jika Pengguna atau Sumber Data Sistem dipilih sebagai jenis sumber data, ConfigDSN di pustaka penyiapan driver dipanggil dengan ODBC_ADD_DSN fRequest. Untuk informasi selengkapnya, lihat ConfigDSN.

Fungsi Terkait

Untuk informasi tentang	Lihat
Mengelola sumber data	SQLManageDataSources