Fungsi SQLDriverConnect

Artikel
05/23/2023

Kesesuaian
Versi Diperkenalkan: Kepatuhan Standar ODBC 1.0: ODBC

Ringkasan
SQLDriverConnect adalah alternatif untuk SQLConnect. Ini mendukung sumber data yang memerlukan lebih banyak informasi koneksi daripada tiga argumen di SQLConnect, kotak dialog untuk meminta semua informasi koneksi kepada pengguna, dan sumber data yang tidak ditentukan dalam informasi sistem. Untuk informasi selengkapnya, lihat Menyambungkan dengan SQLDriverConnect.

Sintaks

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);

Argumen

ConnectionHandle
[Input] Handel koneksi.

WindowHandle
[Input] Handel jendela. Aplikasi dapat meneruskan handel jendela induk, jika berlaku, atau penunjuk null jika handel jendela tidak berlaku atau SQLDriverConnect tidak akan menyajikan kotak dialog apa pun.

InConnectionString
[Input] String koneksi lengkap (lihat sintaks di "Komentar"), string koneksi parsial, atau string kosong.

StringLength1
[Input] Panjang *InConnectionString, dalam karakter jika string adalah Unicode, atau byte jika string adalah ANSI atau DBCS.

OutConnectionString
[Output] Penunjuk ke buffer untuk string koneksi yang telah selesai. Setelah koneksi berhasil ke sumber data target, buffer ini berisi string koneksi yang selesai. Aplikasi harus mengalokasikan setidaknya 1.024 karakter untuk buffer ini.

Jika OutConnectionString adalah NULL, StringLength2Ptr masih akan mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null untuk data karakter) yang tersedia untuk dikembalikan dalam buffer yang diarahkan oleh OutConnectionString.

BufferLength
[Input] Panjang buffer *OutConnectionString , dalam karakter.

StringLength2Ptr
[Output] Penunjuk ke buffer untuk mengembalikan jumlah total karakter (tidak termasuk karakter penghentian null) yang tersedia untuk dikembalikan dalam *OutConnectionString. Jika jumlah karakter yang tersedia untuk dikembalikan lebih besar dari atau sama dengan BufferLength, string koneksi yang selesai di *OutConnectionString dipotong menjadi BufferLength dikurangi panjang karakter penghentian null.

DriverCompletion
[Input] Bendera yang menunjukkan apakah Manajer Driver atau driver harus meminta informasi koneksi lebih lanjut:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED, atau SQL_DRIVER_NOPROMPT.

(Untuk informasi tambahan, lihat "Komentar.")

Kembali

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE, atau SQL_STILL_EXECUTING.

Diagnostik

Saat SQLDriverConnect mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan fHandleType dari SQL_HANDLE_DBC dan hHandle ConnectionHandle. Tabel berikut mencantumkan nilai SQLSTATE yang umumnya dikembalikan oleh SQLDriverConnect 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.

SQLSTATE	Kesalahan	Deskripsi
01000	Peringatan umum	Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01004	Data string, terpotong kanan	Buffer *OutConnectionString tidak cukup besar untuk mengembalikan seluruh string koneksi, sehingga string koneksi terpotong. Panjang string koneksi yang tidak terpotong dikembalikan dalam *StringLength2Ptr. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01S00	Atribut string koneksi tidak valid	Kata kunci atribut yang tidak valid ditentukan dalam string koneksi (InConnectionString), tetapi driver tetap dapat tersambung ke sumber data. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01S02	Nilai opsi berubah	Driver tidak mendukung nilai yang ditentukan yang diarahkan oleh argumen ValuePtr di SQLSetConnectAttr dan menggantikan nilai yang sama. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01S08	Kesalahan saat menyimpan file DSN	String dalam InConnectionString berisi kata kunci FILEDSN* , tetapi file .dsn tidak disimpan. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
01S09	Kata kunci tidak valid	(DM) String dalam InConnectionString berisi kata kunci SAVEFILE* tetapi bukan driver atau kata kunci FILEDSN . (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
08001	Klien tidak dapat membuat koneksi	Pengandar tidak dapat membuat sambungan dengan sumber data.
08002	Nama koneksi yang digunakan	(DM) ConnectionHandle yang ditentukan telah digunakan untuk membuat koneksi dengan sumber data, dan koneksi masih terbuka.
08004	Server menolak koneksi	Sumber data menolak pembentukan koneksi karena alasan yang ditentukan implementasi.
08S01	Kegagalan tautan komunikasi	Tautan komunikasi antara driver dan sumber data tempat driver mencoba menyambungkan gagal sebelum fungsi SQLDriverConnect selesai diproses.
28000	Spesifikasi otorisasi tidak valid	Pengidentifikasi pengguna atau string otorisasi, atau keduanya, seperti yang ditentukan dalam string koneksi (InConnectionString), melanggar batasan yang ditentukan oleh sumber data.
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 szMessageText* menjelaskan kesalahan dan penyebabnya.
HY000	Kesalahan umum: File dsn tidak valid	(DM) String dalam *InConnectionString berisi kata kunci FILEDSN, tetapi nama file .dsn tidak ditemukan.
HY000	Kesalahan umum: Tidak dapat membuat buffer file	(DM) String dalam *InConnectionString berisi kata kunci FILEDSN, tetapi file .dsn tidak dapat dibaca.
HY001	Kesalahan alokasi memori	Manajer Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi SQLDriverConnect . Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi.
HY008	Operasi dibatalkan	Pemrosesan asinkron diaktifkan untuk ConnectionHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, fungsi SQLCancelHandle dipanggil pada ConnectionHandle, lalu fungsi SQLDriverConnect dipanggil lagi pada ConnectionHandle. Atau, fungsi SQLDriverConnect dipanggil, dan sebelum selesai dieksekusi, SQLCancelHandle dipanggil pada ConnectionHandle dari utas yang berbeda dalam aplikasi multithread.
HY010	Kesalahan urutan fungsi	(DM) Fungsi lain yang mengeksekusi secara asinkron (bukan SQLDriverConnect) dipanggil untuk ConnectionHandle dan masih dijalankan ketika fungsi SQLDriverConnect dipanggil.
HY013	Kesalahan manajemen memori	Panggilan fungsi SQLDriverConnect tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah.
HY090	String atau panjang buffer tidak valid	(DM) Nilai yang ditentukan untuk argumen StringLength1 kurang dari 0 dan tidak sama dengan SQL_NTS. (DM) Nilai yang ditentukan untuk argumen BufferLength kurang dari 0.
HY092	Pengidentifikasi atribut/opsi tidak valid	(DM) Argumen DriverCompletion SQL_DRIVER_PROMPT, dan argumen WindowHandle adalah pointer null.
HY110	Penyelesaian driver tidak valid	(DM) Nilai yang ditentukan untuk argumen DriverCompletion tidak sama dengan SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED, atau SQL_DRIVER_NOPROMPT. (DM) Pengumpulan koneksi diaktifkan, dan nilai yang ditentukan untuk argumen DriverCompletion tidak sama dengan SQL_DRIVER_NOPROMPT.
HYC00	Fitur opsional tidak diimplementasikan	Driver tidak mendukung versi perilaku ODBC yang diminta aplikasi.
HYT00	Waktu habis kedaluwarsa	Periode batas waktu masuk kedaluwarsa sebelum koneksi ke sumber data selesai. Periode batas waktu diatur melalui SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT.
HYT01	Kesalahan waktu habis koneksi kedaluwarsa	Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Driver tidak mendukung fungsi ini	(DM) Driver yang sesuai dengan nama sumber data yang ditentukan tidak mendukung fungsi.
IM002	Sumber data tidak ditemukan dan tidak ada driver default yang ditentukan	(DM) Nama sumber data yang ditentukan dalam string koneksi (InConnectionString) tidak ditemukan dalam informasi sistem, dan tidak ada spesifikasi driver default. (DM) Sumber data ODBC dan informasi driver default tidak dapat ditemukan dalam informasi sistem.
IM003	Pengandar yang ditentukan tidak dapat dimuat	(DM) Driver yang tercantum dalam spesifikasi sumber data dalam informasi sistem atau ditentukan oleh kata kunci DRIVER tidak ditemukan atau tidak dapat dimuat karena alasan lain.
IM004	SQLAllocHandle driver pada SQL_HANDLE_ENV gagal	(DM) Selama SQLDriverConnect, Manajer Driver memanggil fungsi SQLAllocHandle driver dengan fHandleType dari SQL_HANDLE_ENV dan driver mengembalikan kesalahan.
IM005	SQLAllocHandle driver pada SQL_HANDLE_DBC gagal.	(DM) Selama SQLDriverConnect, Manajer Driver memanggil fungsi SQLAllocHandle driver dengan fHandleType dari SQL_HANDLE_DBC dan driver mengembalikan kesalahan.
IM006	SQLSetConnectAttr driver gagal	(DM) Selama SQLDriverConnect, Manajer Driver memanggil fungsi SQLSetConnectAttr driver dan driver mengembalikan kesalahan.
IM007	Tidak ada sumber data atau driver yang ditentukan; dialog dilarang	Tidak ada nama sumber data atau driver yang ditentukan dalam string koneksi, dan DriverCompletion SQL_DRIVER_NOPROMPT.
IM008	Dialog gagal	Driver mencoba menampilkan kotak dialog masuknya dan gagal. WindowHandle adalah pointer null, dan DriverCompletion tidak SQL_DRIVER_NO_PROMPT.
IM009	Tidak dapat memuat DLL terjemahan	Pengandar tidak dapat memuat DLL terjemahan yang ditentukan untuk sumber data atau untuk koneksi.
IM010	Nama sumber data terlalu panjang	(DM) Nilai atribut untuk kata kunci DSN lebih panjang dari SQL_MAX_DSN_LENGTH karakter.
IM011	Nama driver terlalu panjang	(DM) Nilai atribut untuk kata kunci DRIVER lebih panjang dari 255 karakter.
IM012	Kesalahan sintaks kata kunci DRIVER	(DM) Pasangan nilai kata kunci untuk kata kunci DRIVER berisi kesalahan sintaks. (DM) String dalam InConnectionString berisi kata kunci FILEDSN* , tetapi file .dsn tidak berisi kata kunci DRIVER atau kata kunci DSN .
IM014	DSN yang ditentukan berisi ketidakcocokan arsitektur antara Driver dan Aplikasi	(DM) aplikasi 32-bit menggunakan DSN yang terhubung ke driver 64-bit; atau sebaliknya.
IM015	SQLDriverConnect driver pada SQL_HANDLE_DBC_INFO_HANDLE gagal	Jika driver mengembalikan SQL_ERROR, Driver Manager akan mengembalikan SQL_ERROR ke aplikasi dan koneksi akan gagal. Untuk informasi selengkapnya tentang SQL_HANDLE_DBC_INFO_TOKEN, lihat Mengembangkan Kesadaran Kumpulan Koneksi di Driver ODBC.
IM017	Polling dinonaktifkan dalam mode pemberitahuan asinkron	Setiap kali model pemberitahuan digunakan, polling dinonaktifkan.
IM018	SQLCompleteAsync belum dipanggil untuk menyelesaikan operasi asinkron sebelumnya pada handel ini.	Jika panggilan fungsi sebelumnya pada handel mengembalikan SQL_STILL_EXECUTING dan jika mode pemberitahuan diaktifkan, SQLCompleteAsync harus dipanggil pada handel untuk melakukan pasca-pemrosesan dan menyelesaikan operasi.
S1118	Driver tidak mendukung pemberitahuan asinkron	Ketika driver tidak mendukung pemberitahuan asinkron, Anda tidak dapat mengatur SQL_ATTR_ASYNC_DBC_EVENT atau SQL_ATTR_ASYNC_DBC_RETCODE_PTR.

Komentar

String koneksi memiliki sintaks berikut:

connection-string ::= empty-string[;] | atribut[;] | atribut; string koneksi

empty-string ::=attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]

atribut-kata kunci ::= DSN | UID | PWD | driver-defined-attribute-keyword

attribute-value ::= character-string

driver-defined-attribute-keyword ::= identifier

di mana karakter-string memiliki nol atau lebih karakter; pengidentifikasi memiliki satu atau beberapa karakter; atribut-kata kunci tidak peka huruf besar/kecil; nilai atribut mungkin peka huruf besar/kecil; dan nilai kata kunci DSN tidak hanya terdiri dari kosong.

Karena string koneksi dan tata bahasa file inisialisasi, kata kunci dan nilai atribut yang berisi karakter []{}(),;? *=!@ tidak diapit kurung kurawal harus dihindari. Nilai kata kunci DSN tidak boleh hanya terdiri dari kosong dan tidak boleh berisi kosong di depan. Karena tata bahasa informasi sistem, kata kunci dan nama sumber data tidak boleh berisi karakter garis miring terbelakang (\).

Aplikasi tidak perlu menambahkan kurung kurawal di sekitar nilai atribut setelah kata kunci DRIVER kecuali atribut berisi titik koma (;), dalam hal ini kurung kurawal diperlukan. Jika nilai atribut yang diterima driver menyertakan kurung kurawal, driver tidak boleh menghapusnya tetapi harus menjadi bagian dari string koneksi yang dikembalikan.

Nilai DSN atau string koneksi yang diapit kurung kurawal ({}) yang berisi salah satu karakter []{}(),;? *=!@ diteruskan utuh ke driver. Namun, saat menggunakan karakter ini dalam kata kunci, Manajer Driver mengembalikan kesalahan saat bekerja dengan DSN file tetapi meneruskan string koneksi ke driver untuk string koneksi reguler. Hindari menggunakan kurung kurawal yang disematkan dalam nilai kata kunci.

String koneksi dapat mencakup sejumlah kata kunci yang ditentukan driver. Karena kata kunci DRIVER tidak menggunakan informasi dari informasi sistem, driver harus menentukan kata kunci yang cukup sehingga driver dapat tersambung ke sumber data hanya menggunakan informasi dalam string koneksi. (Untuk informasi selengkapnya, lihat "Panduan Driver", nanti di bagian ini.) Driver menentukan kata kunci mana yang diperlukan untuk menyambungkan ke sumber data.

Tabel berikut ini menjelaskan nilai atribut kata kunci DSN, FILEDSN, DRIVER, UID, PWD, dan SAVEFILE .

Kata kunci	Deskripsi nilai atribut
DSN	Nama sumber data sebagaimana dikembalikan oleh SQLDataSources atau kotak dialog sumber data SQLDriverConnect.
FILEDSN	Nama file .dsn tempat string koneksi akan dibangun untuk sumber data. Sumber data ini disebut sumber data file.
DRIVER	Deskripsi driver seperti yang dikembalikan oleh fungsi SQLDrivers . Misalnya, Rdb atau SQL Server.
UID	ID pengguna.
PWD	Kata sandi yang sesuai dengan ID pengguna, atau string kosong jika tidak ada kata sandi untuk ID pengguna (PWD=;).
SAVEFILE	Nama file file .dsn tempat nilai atribut kata kunci yang digunakan dalam membuat koneksi saat ini dan berhasil harus disimpan.

Untuk informasi tentang cara aplikasi memilih sumber data atau driver, lihat Memilih Sumber Data atau Driver.

Jika ada kata kunci yang diulang dalam string koneksi, driver menggunakan nilai yang terkait dengan kemunculan pertama kata kunci. Jika kata kunci DSN dan DRIVER disertakan dalam string koneksi yang sama, Driver Manager dan driver menggunakan kata kunci mana pun yang muncul terlebih dahulu.

Kata kunci FILEDSN dan DSN saling eksklusif: kata kunci mana pun yang muncul pertama kali digunakan, dan kata kunci yang muncul kedua diabaikan. Kata kunci FILEDSN dan DRIVER , di sisi lain, tidak saling eksklusif. Jika ada kata kunci yang muncul dalam string koneksi dengan FILEDSN, maka nilai atribut kata kunci dalam string koneksi digunakan daripada nilai atribut kata kunci yang sama dalam file .dsn.

Jika kata kunci FILEDSN digunakan, kata kunci yang ditentukan dalam file .dsn digunakan untuk membuat string koneksi. (Untuk informasi selengkapnya, lihat "Sumber Data File," nanti di bagian ini.) Kata kunci UID bersifat opsional; file .dsn dapat dibuat hanya dengan kata kunci DRIVER . Kata kunci PWD tidak disimpan dalam file .dsn. Direktori default untuk menyimpan dan memuat file .dsn akan menjadi 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".)

Catatan

File .dsn dapat dimanipulasi secara langsung dengan memanggil fungsi SQLReadFileDSN dan SQLWriteFileDSN di DLL penginstal.

Jika kata kunci SAVEFILE digunakan, nilai atribut kata kunci yang digunakan dalam membuat saat ini, koneksi yang berhasil akan disimpan sebagai file .dsn dengan nama nilai atribut kata kunci SAVEFILE. Kata kunci SAVEFILE harus digunakan bersama dengan kata kunci DRIVER , kata kunci FILEDSN , atau keduanya, atau fungsi mengembalikan SQL_SUCCESS_WITH_INFO dengan SQLSTATE 01S09 (Kata kunci tidak valid). Kata kunci SAVEFILE harus muncul sebelum kata kunci DRIVER dalam string koneksi, atau hasilnya tidak akan ditentukan.

Pedoman Manajer Driver

Driver Manager membuat string koneksi untuk diteruskan ke driver dalam argumen InConnectionString dari fungsi SQLDriverConnect driver. Manajer Driver tidak mengubah argumen InConnectionString yang diteruskan oleh aplikasi.

Tindakan Driver Manager didasarkan pada nilai argumen DriverCompletion :

SQL_DRIVER_PROMPT: Jika string koneksi tidak berisi kata kunci DRIVER, DSN, atau FILEDSN , Manajer Driver menampilkan kotak dialog Sumber Data. Ini membangun string koneksi dari nama sumber data yang dikembalikan oleh kotak dialog dan kata kunci lain yang diteruskan oleh aplikasi. Jika nama sumber data yang dikembalikan oleh kotak dialog kosong, Manajer Driver menentukan pasangan nilai kata kunci DSN=Default. (Kotak dialog ini tidak akan menampilkan sumber data dengan nama "Default".)
SQL_DRIVER_COMPLETE atau SQL_DRIVER_COMPLETE_REQUIRED: Jika string koneksi yang ditentukan oleh aplikasi menyertakan kata kunci DSN , Driver Manager menyalin string koneksi yang ditentukan oleh aplikasi. Jika tidak, dibutuhkan tindakan yang sama seperti saat DriverCompletion SQL_DRIVER_PROMPT.
SQL_DRIVER_NOPROMPT: Driver Manager menyalin string koneksi yang ditentukan oleh aplikasi.

Jika string koneksi yang ditentukan oleh aplikasi berisi kata kunci DRIVER , Driver Manager menyalin string koneksi yang ditentukan oleh aplikasi.

Menggunakan string koneksi yang telah dibangunnya, Driver Manager menentukan driver mana yang akan digunakan, terhubung ke driver tersebut, dan meneruskan string koneksi yang telah dibangunnya ke driver; untuk informasi selengkapnya tentang interaksi Manajer Driver dan driver, lihat bagian "Komentar" di Fungsi SQLConnect. Jika string koneksi tidak berisi kata kunci DRIVER , Driver Manager menentukan driver mana yang akan digunakan sebagai berikut:

Jika string koneksi berisi kata kunci DSN , Manajer Driver mengambil driver yang terkait dengan sumber data dari informasi sistem.
Jika string koneksi tidak berisi kata kunci DSN atau sumber data tidak ditemukan, Manajer Driver mengambil driver yang terkait dengan sumber data Default dari informasi sistem. (Untuk informasi selengkapnya, lihat Subkunjuk Default.) Driver Manager mengubah nilai kata kunci DSN dalam string koneksi menjadi "DEFAULT".
Jika kata kunci DSN dalam string koneksi diatur ke "DEFAULT", Manajer Driver mengambil driver yang terkait dengan sumber data Default dari informasi sistem.
Jika sumber data tidak ditemukan dan sumber data Default tidak ditemukan, Driver Manager mengembalikan SQL_ERROR dengan SQLSTATE IM002 (Sumber data tidak ditemukan dan tidak ada driver default yang ditentukan).

Sumber Data File

Jika string koneksi yang ditentukan oleh aplikasi dalam panggilan ke SQLDriverConnect berisi kata kunci FILEDSN, dan kata kunci ini tidak digantikan oleh kata kunci DSN atau DRIVER, maka Manajer Driver membuat string koneksi menggunakan informasi dalam file .dsn dan argumen InConnectionString. Driver Manager melanjutkan sebagai berikut:

Memeriksa apakah nama file file .dsn valid. Jika tidak, ini mengembalikan SQL_ERROR dengan SQLSTATE IM014 (Nama file DSN tidak valid). Jika nama file adalah string kosong ("") dan SQL_DRIVER_NOPROMPT tidak ditentukan, maka kotak dialog Buka File ditampilkan. Jika nama file berisi jalur yang valid tetapi tidak ada nama file atau nama file yang tidak valid, dan SQL_DRIVER_NOPROMPT tidak ditentukan, maka kotak dialog Buka File ditampilkan dengan direktori saat ini diatur ke yang ditentukan dalam nama file. Jika nama file adalah string kosong ("") atau nama file berisi jalur yang valid tetapi tidak ada nama file atau nama file yang tidak valid, dan SQL_DRIVER_NOPROMPT ditentukan, maka SQL_ERROR dikembalikan dengan SQLSTATE IM014 (Nama file DSN tidak valid).
Membaca semua kata kunci di bagian [ODBC] dari file .dsn. Jika kata kunci DRIVER tidak ada, kata kunci mengembalikan SQL_ERROR dengan SQLSTATE IM012 (Kesalahan sintaks kata kunci driver), kecuali di mana file .dsn tidak dapat dibagikan dan dengan demikian hanya berisi kata kunci DSN.

Jika sumber data file tidak dapat dibagikan, Manajer Driver membaca nilai kata kunci DSN dan menyambungkan seperlunya ke pengguna atau sumber data sistem yang ditujukkan oleh sumber data file yang tidak dapat dibagikan. Langkah 3 sampai 5 tidak dilakukan.
Membuat string koneksi untuk driver. String koneksi driver adalah gabungan kata kunci yang ditentukan dalam file .dsn dan yang ditentukan dalam string koneksi aplikasi asli. Aturan untuk konstruksi string koneksi driver di mana kata kunci tumpang tindih adalah sebagai berikut:
- Jika kata kunci DRIVER ada dalam string koneksi aplikasi dan driver yang ditentukan oleh kata kunci DRIVER tidak sama dalam file .dsn dan string koneksi aplikasi, maka informasi driver dalam file .dsn diabaikan dan informasi driver dalam string koneksi aplikasi digunakan. Jika driver yang ditentukan oleh kata kunci DRIVER sama dalam file .dsn dan string koneksi aplikasi, maka di mana semua kata kunci tumpang tindih, yang ditentukan dalam string koneksi aplikasi lebih diutamakan daripada yang ditentukan dalam file .dsn.
- Dalam string koneksi baru, kata kunci FILEDSN dihilangkan.
Memuat driver dengan melihat entri registri HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST. INI\<Driver Name>\Driver di mana <Nama> Driver ditentukan oleh kata kunci DRIVER .
Meneruskan driver string koneksi baru.

Untuk contoh file .dsn, lihat Menyambungkan Menggunakan Sumber Data File.

Kata Kunci SAVEFILE

Jika string koneksi yang ditentukan oleh aplikasi berisi kata kunci SAVEFILE , maka Driver Manager menyimpan string koneksi dalam file .dsn. Driver Manager melanjutkan sebagai berikut:

Memeriksa apakah nama file file .dsn disertakan sebagai nilai atribut kata kunci SAVEFILE valid. Jika tidak, ini mengembalikan SQL_ERROR dengan SQLSTATE IM014 (Nama file DSN tidak valid). Validitas nama file ditentukan oleh aturan penamaan sistem standar. Jika nama file adalah string kosong ("") dan argumen DriverCompletion tidak SQL_DRIVER_NOPROMPT, maka nama file valid. Jika nama file sudah ada, maka jika DriverCompletion SQL_DRIVER_NOPROMPT, file akan ditimpa. Jika DriverCompletion SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, atau SQL_DRIVER_COMPLETE_REQUIRED, kotak dialog meminta pengguna untuk menentukan apakah file harus ditimpa. Jika Tidak dimasukkan, maka kotak dialog Simpan File akan muncul.
Jika driver mengembalikan SQL_SUCCESS dan nama file bukan string kosong, maka Manajer Driver menulis informasi koneksi yang dikembalikan dalam argumen OutConnectionString ke file yang ditentukan dengan format yang ditentukan di bagian "String Koneksi" sebelumnya di bagian ini.
Jika driver mengembalikan SQL_SUCCESS dan nama file adalah string kosong (""), maka Manajer Driver memanggil kotak dialog umum Simpan File dengan hwnd yang ditentukan dan menulis informasi koneksi yang dikembalikan di OutConnectionString ke file yang ditentukan dalam kotak dialog umum Simpan File dengan format yang ditentukan di bagian "String Koneksi" sebelumnya di bagian ini.
Jika driver mengembalikan SQL_SUCCESS, driver mengembalikan argumen OutConnectionString yang berisi string koneksi ke aplikasi.
Jika driver mengembalikan SQL_SUCCESS_WITH_INFO atau SQL_ERROR, maka Driver Manager mengembalikan SQLSTATE ke aplikasi.

Pedoman Driver

Driver memeriksa apakah string koneksi yang diteruskan oleh Manajer Driver berisi kata kunci DSN atau DRIVER . Jika string koneksi berisi kata kunci DRIVER , driver tidak dapat mengambil informasi tentang sumber data dari informasi sistem. Jika string koneksi berisi kata kunci DSN atau tidak berisi kata kunci DSN atau DRIVER , driver dapat mengambil informasi tentang sumber data dari informasi sistem sebagai berikut:

Jika string koneksi berisi kata kunci DSN , driver mengambil informasi untuk sumber data yang ditentukan.
Jika string koneksi tidak berisi kata kunci DSN , sumber data yang ditentukan tidak ditemukan, atau kata kunci DSN diatur ke "DEFAULT", driver mengambil informasi untuk sumber data Default.

Driver menggunakan informasi apa pun yang diambilnya dari informasi sistem untuk menambah informasi yang diteruskan ke dalam string koneksi. Jika informasi dalam informasi sistem menduplikasi informasi dalam string koneksi, driver menggunakan informasi dalam string koneksi.

Berdasarkan nilai DriverCompletion, driver meminta informasi koneksi kepada pengguna, seperti ID pengguna dan kata sandi, dan menyambungkan ke sumber data:

SQL_DRIVER_PROMPT: Driver menampilkan kotak dialog, menggunakan nilai dari string koneksi dan informasi sistem (jika ada) sebagai nilai awal. Saat pengguna keluar dari kotak dialog, driver tersambung ke sumber data. Ini juga membangun string koneksi dari nilai kata kunci DSN atau DRIVER di *InConnectionString dan informasi yang dikembalikan dari kotak dialog. Ini menempatkan string koneksi ini dalam buffer *OutConnectionString .
SQL_DRIVER_COMPLETE atau SQL_DRIVER_COMPLETE_REQUIRED: Jika string koneksi berisi informasi yang cukup, dan informasi tersebut benar, driver terhubung ke sumber data dan menyalin *InConnectionString ke *OutConnectionString. Jika ada informasi yang hilang atau salah, driver mengambil tindakan yang sama seperti saat DriverCompletion SQL_DRIVER_PROMPT, kecuali jika DriverCompletion SQL_DRIVER_COMPLETE_REQUIRED, driver menonaktifkan kontrol untuk informasi apa pun yang tidak diperlukan untuk terhubung ke sumber data.
SQL_DRIVER_NOPROMPT: Jika string koneksi berisi informasi yang cukup, driver terhubung ke sumber data dan menyalin *InConnectionString ke *OutConnectionString. Jika tidak, driver mengembalikan SQL_ERROR untuk SQLDriverConnect.

Pada koneksi yang berhasil ke sumber data, driver juga mengatur *StringLength2Ptr ke panjang string koneksi output yang tersedia untuk dikembalikan dalam *OutConnectionString.

Jika pengguna membatalkan kotak dialog yang disajikan oleh Manajer Driver atau driver, SQLDriverConnect mengembalikan SQL_NO_DATA.

Untuk informasi tentang bagaimana Manajer Driver dan driver berinteraksi selama proses koneksi, lihat Fungsi SQLConnect.

Jika driver mendukung SQLDriverConnect, bagian kata kunci driver dari informasi sistem untuk driver harus berisi kata kunci ConnectFunctions dengan karakter kedua yang diatur ke "Y".

Menyambungkan Saat Pengumpulan Koneksi Diaktifkan

Pengumpulan koneksi memungkinkan aplikasi untuk menggunakan kembali koneksi yang telah dibuat. Ketika SQLDriverConnect dipanggil, Manajer Driver mencoba membuat koneksi menggunakan koneksi yang merupakan bagian dari kumpulan koneksi di lingkungan yang telah ditunjuk untuk pengumpulan koneksi. Untuk informasi selengkapnya tentang pengumpulan koneksi, lihat Fungsi SQLConnect.

Aplikasi dapat mengatur SQL_ATTR_RESET_CONNECTION sebelum memanggil SQLDisconnect pada koneksi tempat pengumpulan diaktifkan. Untuk informasi selengkapnya, lihat Fungsi SQLSetConnectAttr.

Pembatasan berikut berlaku saat aplikasi memanggil SQLDriverConnect untuk menyambungkan ke koneksi terkumpul:

Tidak ada pemrosesan pengumpulan koneksi yang dilakukan ketika kata kunci SAVEFILE ditentukan dalam string koneksi.
Jika pengumpulan koneksi diaktifkan, SQLDriverConnect hanya dapat dipanggil dengan argumen DriverCompletion SQL_DRIVER_NOPROMPT; jika SQLDriverConnect dipanggil dengan DriverCompletion lainnya, SQLSTATE HY110 (Penyelesaian driver tidak valid) akan dikembalikan.

Atribut Sambungan

Atribut koneksi SQL_ATTR_LOGIN_TIMEOUT, diatur menggunakan SQLSetConnectAttr, menentukan jumlah detik untuk menunggu permintaan masuk selesai dengan koneksi yang berhasil oleh driver sebelum kembali ke aplikasi. Jika pengguna diminta untuk menyelesaikan string koneksi, periode tunggu untuk setiap permintaan masuk dimulai ketika driver memulai proses koneksi.

Driver membuka koneksi dalam mode akses SQL_MODE_READ_WRITE secara default. Untuk mengatur mode akses ke SQL_MODE_READ_ONLY, aplikasi harus memanggil SQLSetConnectAttr dengan atribut SQL_ATTR_ACCESS_MODE sebelum memanggil SQLDriverConnect.

Jika pustaka terjemahan default ditentukan dalam informasi sistem untuk sumber data, driver akan memuatnya. Pustaka terjemahan yang berbeda dapat dimuat dengan memanggil SQLSetConnectAttr dengan atribut SQL_ATTR_TRANSLATE_LIB. Opsi terjemahan dapat ditentukan dengan memanggil SQLSetConnectAttr dengan opsi SQL_ATTR_TRANSLATE_OPTION.

Untuk informasi selengkapnya, lihat Menyambungkan dengan SQLDriverConnect.

// SQLDriverConnect_ref.cpp  
// compile with: odbc32.lib user32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR OutConnStr[255];  
   SQLSMALLINT OutConnStrLen;  
  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            retcode = SQLDriverConnect( // SQL_NULL_HDBC  
               hdbc,   
               desktopHandle,   
               (SQLCHAR*)"driver=SQL Server",   
               _countof("driver=SQL Server"),  
               OutConnStr,  
               255,   
               &OutConnStrLen,  
               SQL_DRIVER_PROMPT );  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {                 
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}

Lihat juga Contoh Program ODBC.

Untuk informasi tentang	Lihat
Mengalokasikan handel	Fungsi SQLAllocHandle
Menemukan dan menghitung nilai yang diperlukan untuk menyambungkan ke sumber data	Fungsi SQLBrowseConnect
Menyambungkan ke sumber data	Fungsi SQLConnect
Memutuskan sambungan dari sumber data	Fungsi SQLDisconnect
Mengembalikan deskripsi dan atribut driver	Fungsi SQLDrivers
Mengosongkan handel	Fungsi SQLFreeHandle
Mengatur atribut koneksi	Fungsi SQLSetConnectAttr

Lihat Juga

Referensi API ODBC
File Header ODBC

Bagikan melalui

Fungsi SQLDriverConnect

Sintaks

Argumen

Kembali

Diagnostik

Komentar

Pedoman Manajer Driver

Sumber Data File

Kata Kunci SAVEFILE

Pedoman Driver

Menyambungkan Saat Pengumpulan Koneksi Diaktifkan

Atribut Sambungan

Lihat Juga

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Fungsi SQLDriverConnect

Sintaks

Argumen

Kembali

Diagnostik

Komentar

Pedoman Manajer Driver

Sumber Data File

Kata Kunci SAVEFILE

Pedoman Driver

Menyambungkan Saat Pengumpulan Koneksi Diaktifkan

Atribut Sambungan

Fungsi Terkait

Lihat Juga

Saran dan Komentar

Sumber Daya Tambahan: