Fungsi SQLConnect

Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92

Ringkasan
SQLConnect membuat koneksi ke driver dan sumber data. Pegangan koneksi mereferensikan penyimpanan semua informasi tentang koneksi ke sumber data, termasuk status, status transaksi, dan informasi kesalahan.

Syntax

  
SQLRETURN SQLConnect(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      ServerName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      UserName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      Authentication,  
     SQLSMALLINT    NameLength3);  

Arguments

ConnectionHandle
[Input] Handel koneksi.

ServerName
[Masukan] Nama sumber data. Data mungkin terletak pada komputer yang sama dengan program, atau di komputer lain di suatu tempat pada jaringan. Untuk informasi tentang cara aplikasi memilih sumber data, lihat Memilih Sumber Data atau Driver.

NameLength1
[Masukan] Panjang *ServerName dalam karakter.

UserName
[Masukan] Pengidentifikasi pengguna.

NameLength2
[Masukan] Panjang *UserName dalam karakter.

Authentication
[Masukan] String autentikasi (biasanya kata sandi).

NameLength3
[Masukan] Panjang *Otentikasi dalam karakter.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE, atau SQL_STILL_EXECUTING.

Diagnostics

Saat SQLConnect mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_DBC dan HandleConnectionHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLConnect dan menjelaskan masing-masing nilai dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATE yang dikembalikan oleh Driver Manager. Kode pengembalian yang terkait dengan setiap nilai SQLSTATE SQL_ERROR, kecuali disebutkan sebaliknya.

Komentar

Untuk informasi tentang mengapa aplikasi menggunakan SQLConnect, lihat Menghubungkan dengan SQLConnect.

Manajer Driver tidak terhubung ke driver hingga aplikasi memanggil fungsi (SQLConnect, SQLDriverConnect, atau SQLBrowseConnect) untuk terhubung ke driver. Hingga saat itu, Pengelola Pengemudi bekerja dengan pegangan sendiri dan mengelola informasi koneksi. Saat aplikasi memanggil fungsi koneksi, Pengelola Driver memeriksa apakah driver saat ini terhubung ke untuk ConnectionHandle yang ditentukan:

• Jika driver tidak tersambung ke, Manajer Driver terhubung ke driver dan memanggil SQLAllocHandle dengan HandleType SQL_HANDLE_ENV, SQLAllocHandle dengan HandleType SQL_HANDLE_DBC, SQLSetConnectAttr (jika aplikasi menentukan atribut koneksi apa pun), dan fungsi koneksi di driver. Manajer Driver mengembalikan SQLSTATE IM006 ( SQLSetConnectOption Driver gagal) dan SQL_SUCCESS_WITH_INFO untuk fungsi koneksi jika driver mengembalikan kesalahan untuk SQLSetConnectAttr. Untuk informasi selengkapnya, lihat Menyambungkan ke Sumber Data atau Driver.

• Jika driver yang ditentukan sudah terhubung ke ConnectionHandle, Pengelola Driver hanya memanggil fungsi koneksi di driver. Dalam hal ini, driver harus memastikan bahwa semua atribut koneksi untuk ConnectionHandle mempertahankan pengaturan saat ini.

• Jika driver lain tersambung ke, Driver Manager memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_DBC, dan kemudian, jika tidak ada driver lain yang terhubung ke lingkungan tersebut, driver tersebut memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_ENV di driver yang terhubung dan kemudian memutuskan sambungan driver tersebut. Kemudian melakukan operasi yang sama seperti ketika driver tidak terhubung.

Driver kemudian mengalokasikan pegangan dan menginisialisasi dirinya sendiri.

Ketika aplikasi memanggil SQLDisconnect, Manajer Driver memanggil SQLDisconnect di driver. Namun, itu tidak memutuskan sambungan driver. Ini menjaga driver tetap dalam memori untuk aplikasi yang berulang kali terhubung ke dan memutuskan sambungan dari sumber data. Saat aplikasi memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_DBC, Manajer Driver memanggil SQLFreeHandle dengan HandleType SQL_HANDLE_DBC dan kemudian SQLFreeHandle dengan HandleType SQL_HANDLE_ENV di driver, lalu memutuskan sambungan driver.

Aplikasi ODBC dapat membuat lebih dari satu koneksi.

Pedoman Pengemudi Manager

Konten *ServerName memengaruhi cara Pengelola Driver dan driver bekerja sama untuk membuat koneksi ke sumber data.

• Jika *ServerName berisi nama sumber data yang valid, Pengelola Driver menemukan spesifikasi sumber data yang sesuai dalam informasi sistem dan terhubung ke driver terkait. Manajer Driver meneruskan setiap argumen SQLConnect ke driver.

• Jika nama sumber data tidak dapat ditemukan atau ServerName adalah penunjuk null, Manajer Driver menemukan spesifikasi sumber data default dan terhubung ke driver terkait. Manajer Driver meneruskan ke driver argumen UserName dan Authentication yang tidak dimodifikasi, dan "DEFAULT" untuk argumen ServerName .

• Jika argumen ServerName adalah "DEFAULT", Driver Manager menemukan spesifikasi sumber data default dan terhubung ke driver terkait. Manajer Driver meneruskan setiap argumen SQLConnect ke driver.

• Jika nama sumber data tidak dapat ditemukan atau ServerName adalah penunjuk null, dan spesifikasi sumber data default tidak ada, Driver Manager mengembalikan SQL_ERROR dengan SQLSTATE IM002 (Nama sumber data tidak ditemukan dan tidak ada driver default yang ditentukan).

Setelah terhubung dengan Manajer Driver, driver dapat menemukan spesifikasi sumber data yang sesuai dalam informasi sistem dan menggunakan informasi khusus driver dari spesifikasi untuk melengkapi kumpulan informasi koneksi yang diperlukan.

Jika pustaka terjemahan default ditentukan dalam informasi sistem untuk sumber data, driver akan terhubung ke perpustakaan tersebut. Pustaka terjemahan yang berbeda dapat dihubungkan dengan memanggil SQLSetConnectAttr dengan atribut SQL_ATTR_TRANSLATE_LIB. Opsi terjemahan dapat ditentukan dengan memanggil SQLSetConnectAttr dengan atribut SQL_ATTR_TRANSLATE_OPTION.

Jika driver mendukung SQLConnect, bagian kata kunci driver dari informasi sistem untuk driver harus berisi kata kunci ConnectFunctions dengan karakter pertama yang ditetapkan ke "Y".

Penyatuan Koneksi

Pengumpulan koneksi memungkinkan aplikasi untuk menggunakan kembali koneksi yang telah dibuat. Saat pengumpulan koneksi diaktifkan dan SQLConnect dipanggil, Manajer Driver mencoba membuat koneksi menggunakan koneksi yang merupakan bagian dari kumpulan koneksi di lingkungan yang telah ditetapkan untuk pengumpulan koneksi. Lingkungan ini adalah lingkungan bersama yang digunakan oleh semua aplikasi yang menggunakan koneksi di kumpulan.

Pengumpulan koneksi diaktifkan sebelum lingkungan dialokasikan dengan memanggil SQLSetEnvAttr untuk mengatur SQL_ATTR_CONNECTION_POOLING ke SQL_CP_ONE_PER_DRIVER (yang menentukan maksimum satu kumpulan per driver) atau SQL_CP_ONE_PER_HENV (yang menentukan maksimum satu kumpulan per lingkungan). SQLSetEnvAttr dalam hal ini dipanggil dengan EnvironmentHandle diatur ke null, yang menjadikan atribut sebagai atribut tingkat proses. Jika SQL_ATTR_CONNECTION_POOLING diatur ke SQL_CP_OFF, pengumpulan koneksi dinonaktifkan.

Setelah pengumpulan koneksi diaktifkan, SQLAllocHandle dengan HandleType SQL_HANDLE_ENV dipanggil untuk mengalokasikan lingkungan. Lingkungan yang dialokasikan oleh panggilan ini adalah lingkungan bersama karena pengumpulan koneksi telah diaktifkan. Namun, lingkungan yang akan digunakan tidak ditentukan sampai SQLAllocHandle dengan HandleType SQL_HANDLE_DBC dipanggil.

SQLAllocHandle dengan HandleType SQL_HANDLE_DBC dipanggil untuk mengalokasikan koneksi. Pengelola Driver mencoba menemukan lingkungan bersama yang ada yang cocok dengan atribut lingkungan yang ditetapkan oleh aplikasi. Jika tidak ada lingkungan seperti itu, lingkungan tersebut dibuat sebagai lingkungan bersama implisit. Jika lingkungan bersama yang cocok ditemukan, pegangan lingkungan dikembalikan ke aplikasi dan jumlah referensinya bertambah.

Namun, koneksi yang akan digunakan tidak ditentukan sampai SQLConnect dipanggil. Pada saat itu, Manajer Driver mencoba menemukan koneksi yang ada di kumpulan koneksi yang cocok dengan kriteria yang diminta oleh aplikasi. Kriteria ini mencakup opsi koneksi yang diminta dalam panggilan ke SQLConnect (nilai kata kunci ServerName, UserName, dan Authentication ) dan atribut koneksi apa pun yang ditetapkan sejak SQLAllocHandle dengan HandleType SQL_HANDLE_DBC dipanggil. Manajer Driver memeriksa kriteria ini terhadap kata kunci dan atribut koneksi yang sesuai dalam koneksi di kumpulan. Jika kecocokan ditemukan, koneksi di kolam digunakan. Jika tidak ada kecocokan yang ditemukan, koneksi baru akan dibuat.

Jika atribut lingkungan SQL_ATTR_CP_MATCH diatur ke SQL_CP_STRICT_MATCH, kecocokan harus tepat untuk koneksi dalam kumpulan yang akan digunakan. Jika atribut lingkungan SQL_ATTR_CP_MATCH diatur ke SQL_CP_RELAXED_MATCH, opsi koneksi dalam panggilan ke SQLConnect harus cocok tetapi tidak semua atribut koneksi harus cocok.

Aturan berikut diterapkan ketika atribut koneksi, seperti yang ditetapkan oleh aplikasi sebelum SQLConnect dipanggil, tidak cocok dengan atribut koneksi koneksi dalam kumpulan:

• Jika atribut koneksi harus diatur sebelum koneksi dibuat:

  Jika SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE dalam koneksi gabungan harus identik dengan atribut yang ditetapkan oleh aplikasi. Jika SQL_CP_RELAXED_MATCH, nilai SQL_ATTR_PACKET_SIZE bisa berbeda.

  Nilai SQL_ATTR_LOGIN_VALUE tidak mempengaruhi kecocokan.

• Jika atribut koneksi dapat diatur sebelum atau sesudah koneksi dibuat:

  Jika atribut koneksi belum diatur oleh aplikasi tetapi telah diatur pada koneksi di kumpulan, dan ada default, atribut koneksi dalam koneksi yang dikumpulkan diatur kembali ke default dan kecocokan dideklarasikan. Jika tidak ada default, koneksi gabungan tidak dianggap cocok.

  Jika atribut koneksi telah diatur oleh aplikasi tetapi belum diatur pada koneksi di kumpulan, atribut koneksi pada kumpulan diubah menjadi yang ditetapkan oleh aplikasi dan kecocokan dideklarasikan.

  Jika atribut koneksi telah diatur oleh aplikasi, dan juga telah diatur pada koneksi di kumpulan tetapi nilainya berbeda, nilai atribut koneksi aplikasi digunakan dan kecocokan dideklarasikan.

• Jika nilai atribut koneksi khusus driver tidak identik dan SQL_ATTR_CP_MATCH diatur ke SQL_CP_STRICT_MATCH, koneksi di kumpulan tidak digunakan.

Saat aplikasi memanggil SQLDisconnect untuk memutuskan sambungan, koneksi dikembalikan ke kumpulan koneksi dan tersedia untuk digunakan kembali.

Mengoptimalkan Performa Pengumpulan Koneksi

Ketika transaksi terdistribusi terlibat, dimungkinkan untuk mengoptimalkan performa pengumpulan koneksi dengan menggunakan SQL_DTC_TRANSITION_COST, yang merupakan topeng bit SQLUINTEGER. Transisi yang dimaksud adalah transisi atribut koneksi SQL_ATTR_ENLIST_IN_DTC beralih dari nilai 0 ke bukan nol, dan sebaliknya. Ini adalah koneksi yang beralih dari tidak terdaftar dalam transaksi terdistribusi menjadi terdaftar dalam transaksi terdistribusi, dan sebaliknya. Bergantung pada bagaimana pengemudi telah menerapkan pendaftaran (mengatur SQL_ATTR_ENLIST_IN_DTC atribut koneksi), transisi ini mungkin mahal dan oleh karena itu harus dihindari untuk kinerja terbaik.

Nilai yang dikembalikan oleh driver berisi kombinasi bit berikut:

• SQL_DTC_ENLIST_EXPENSIVE, ketika ditetapkan, menyiratkan transisi nol ke bukan nol secara signifikan lebih mahal daripada transisi dari nilai bukan nol ke nilai bukan nol lainnya (mendaftarkan koneksi yang sebelumnya terdaftar dalam transaksi berikutnya).

• SQL_DTC_UNENLIST_EXPENSIVE, ketika diatur, menyiratkan transisi bukan nol ke nol secara signifikan lebih mahal daripada menggunakan koneksi yang atribut SQL_ATTR_ENLIST_IN_DTC sudah diatur ke nol.

Ada pengorbanan kinerja versus penggunaan koneksi. Jika driver menunjukkan bahwa satu atau beberapa transisi ini mahal, pengumpul koneksi manajer driver merespons ini dengan menyimpan lebih banyak koneksi di kumpulan. Beberapa koneksi dalam kumpulan lebih disukai untuk penggunaan nontransaksional, dan beberapa lebih disukai untuk penggunaan transaksional. Namun, jika driver menunjukkan bahwa transisi ini tidak mahal, lebih sedikit koneksi yang dapat digunakan, mungkin bergantian antara penggunaan nontransaksional dan transaksional.

Driver yang tidak mendukung SQL_ATTR_ENLIST_IN_DTC tidak perlu mendukung SQL_DTC_TRANSITION_COST. Untuk driver yang mendukung SQL_ATTR_ENLIST_IN_DTC tetapi tidak SQL_DTC_TRANSITION_COST, diasumsikan bahwa transisi tidak mahal, seolah-olah driver mengembalikan 0 (tidak ada bit yang ditetapkan) untuk nilai ini.

Meskipun SQL_DTC_TRANSITION_COST diperkenalkan di ODBC 3.5, ODBC 2. X driver juga dapat mendukungnya karena pengelola driver akan mengkueri informasi ini terlepas dari versi driver.

Contoh Kode

Dalam contoh berikut, aplikasi mengalokasikan lingkungan dan pegangan koneksi. Kemudian terhubung ke sumber data SalesOrders dengan ID pengguna JohnS dan kata sandi Sesame dan memproses data. Setelah selesai memproses data, ia terputus dari sumber data dan membebaskan pegangan.

// SQLConnect_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR * OutConnStr = (SQLCHAR * )malloc(255);  
   SQLSMALLINT * OutConnStrLen = (SQLSMALLINT *)malloc(255);  
  
   // 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, (void*)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);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLCHAR*) "NorthWind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
  
            // 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);  
   }  
}  

Fungsi Terkait

Lihat Juga

Referensi API ODBC
File Header ODBC