Функция SQLConnect

Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92

Сводка
SQLConnect устанавливает соединения с драйвером и источником данных. Дескриптор соединения ссылается на хранение всей информации о соединении с источником данных, включая статус, состояние транзакции и информацию об ошибках.

Syntax

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

Arguments

ConnectionHandle
[Input] Дескриптор подключения

Имя сервера
[Ввод] Имя источника данных. Данные могут находиться на том же компьютере, что и программа, или на другом компьютере в сети. Для получения информации о том, как приложение выбирает источник данных, см. раздел «Выбор источника данных или драйвера».

NameLength1
[Ввод] Длина *ServerName в символах.

UserName
[Ввод] Идентификатор пользователя.

NameLength2
[Ввод] Длина *UserName в символах.

Authentication
[Ввод] Строка аутентификации (обычно пароль).

NameLength3
[Ввод] Длина *Аутентификация в символах.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE или SQL_STILL_EXECUTING.

Diagnostics

Когда SQLConnect возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, соответствующее значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_DBC и HandleType of ConnectionHandle. В следующей таблице перечислены значения SQLSTATE, обычно возвращаемые SQLConnect , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

Comments

Для получения информации о том, почему приложение использует SQLConnect, см. раздел «Подключение к SQLConnect».

Менеджер драйверов не подключается к драйверу, пока приложение не вызовет функцию (SQLConnect, SQLDriverConnect или SQLBrowseConnect) для подключения к драйверу. До этого момента менеджер драйверов работает со своими собственными дескрипторами и управляет информацией о соединении. Когда приложение вызывает функцию подключения, менеджер драйверов проверяет, подключён ли драйвер к указанному ConnectionHandle:

• Если драйвер не подключён, менеджер драйверов подключается к нему и вызывает SQLAllocHandle с HandleType SQL_HANDLE_ENV, SQLAllocHandle с HandleType SQL_HANDLE_DBC, SQLSetConnectAttr (если приложение указывало какие-либо атрибуты соединения) и функцию подключения в драйвере. Менеджер драйверов возвращает SQLSTATE IM006 ( SQLSetConnectOption драйвера failed) и SQL_SUCCESS_WITH_INFO функции подключения, если драйвер возвращает ошибку для SQLSetConnectAttr. Для получения дополнительной информации см. раздел «Подключение к источнику данных или драйверу».

• Если указанный драйвер уже подключён к ConnectionHandle, Driver Manager вызывает только функцию соединения в драйвере. В этом случае драйвер должен убедиться, что все атрибуты соединения ConnectionHandle сохраняют текущие настройки.

• Если к нему подключён другой драйвер, менеджер драйверов вызывает SQLFreeHandle с HandleType SQL_HANDLE_DBC, а если в этой среде не подключён другой драйвер, вызывает SQLFreeHandle с HandleType SQL_HANDLE_ENV в подключённом драйвере и затем отключает этот драйвер. Затем он выполняет те же операции, что и когда драйвер не подключён.

Драйвер затем выделяет дескрипторы и инициализируется.

Когда приложение вызывает SQLDisconnect, диспетчер драйверов вызывает SQLDisconnect в драйвере. Однако драйвер не отключается. Это сохраняет драйвер в памяти для приложений, которые постоянно подключаются к источнику данных и отключаются от него. Когда приложение вызывает SQLFreeHandle с HandleType SQL_HANDLE_DBC, Driver Manager вызывает SQLFreeHandle с HandleType SQL_HANDLE_DBC, затем SQLFreeHandle с HandleType SQL_HANDLE_ENV в драйвере, после чего отключает драйвер.

Приложение ODBC может устанавливать более одного соединения.

Руководящие принципы для менеджеров водителей

Содержимое *ServerName влияет на то, как менеджер драйверов и драйвер работают вместе для установления соединения с источником данных.

• Если *ServerName содержит допустимое имя источника данных, менеджер драйверов находит соответствующую спецификацию источника данных в системной информации и подключается к соответствующему драйверу. Менеджер драйверов передаёт каждый аргумент SQLConnect драйверу.

• Если имя источника данных не удаётся найти или ServerName является нулевым указателем, менеджер драйверов находит стандартную спецификацию источника данных и подключается к соответствующему драйверу. Менеджер драйверов передаёт драйверу аргументы имени пользователя и аутентификации без изменений, а также "DEFAULT" для аргумента имени ServerName .

• Если аргумент ServerName — «DEFAULT», менеджер драйверов находит спецификацию источника данных по умолчанию и подключается к соответствующему драйверу. Менеджер драйверов передаёт каждый аргумент SQLConnect драйверу.

• Если имя источника данных не удаётся найти или ServerName является нулевым указателем, а стандартная спецификация источника данных отсутствует, Driver Manager возвращает SQL_ERROR с SQLSTATE IM002 (имя источника данных не найдено и драйвер по умолчанию не указан).

После подключения менеджера драйверов драйвер может найти соответствующую спецификацию источника данных в системной информации и использовать специфическую для драйвера информацию из спецификации для завершения необходимого набора необходимых соединений.

Если в системной информации для источника данных указана библиотека перевода по умолчанию, драйвер подключается к ней. К другой библиотеке перевода можно подключиться, вызвав SQLSetConnectAttr с атрибутом SQL_ATTR_TRANSLATE_LIB. Опцию перевода можно задать путём вызова SQLSetConnectAttr с атрибутом SQL_ATTR_TRANSLATE_OPTION.

Если драйвер поддерживает SQLConnect, раздел ключевого слова драйвера в системной информации для драйвера должен содержать ключевое слово ConnectFunctions с первым символом, установленным как «Y».

Пул подключений

Пул соединений позволяет приложению повторно использовать уже созданное соединение. Когда активирован пул соединений и вызывается SQLConnect , менеджер драйверов пытается создать соединение, используя соединение, являющееся пулом соединений в среде, предназначенной для пула соединений. Эта среда является общей средой, используемой всеми приложениями, использующими соединения в пуле.

Пул соединений включается до выделения среды путём вызова SQLSetEnvAttr для установки SQL_ATTR_CONNECTION_POOLING в SQL_CP_ONE_PER_DRIVER (что означает максимум один пул на драйвер) или SQL_CP_ONE_PER_HENV (где максимум один пул на среду). SQLSetEnvAttr в данном случае вызывается с EnvironmentHandle в null, что делает атрибут атрибутом на уровне процесса. Если SQL_ATTR_CONNECTION_POOLING настроен на SQL_CP_OFF, пул соединений отключается.

После включения пула соединений вызывается SQLAllocHandle с HandleType SQL_HANDLE_ENV для выделения среды. Окружение, выделенное этим вызовом, является общей средой, поскольку объединение соединений было включено. Однако используемая среда определяется только после вызова SQLAllocHandle с HandleType SQL_HANDLE_DBC.

SQLAllocHandle с HandleType SQL_HANDLE_DBC вызывается для выделения соединения. Менеджер драйверов пытается найти существующую общую среду, соответствующую атрибутам среды, установленным приложением. Если такой среды нет, она создаётся как неявная общая среда. Если найдена совпадающая общая среда, дескриптор окружения возвращается приложению, а количество ссылок увеличивается.

Однако используемое соединение определяется только после вызова SQLConnect . В этот момент менеджер драйверов пытается найти существующее соединение в пуле соединений, соответствующее требованиям приложения. К этим критериям относятся опции соединения, запрошенные при вызове SQLConnect (значения ключевых слов ServerName, UserName и Authentication ), а также любые атрибуты соединения, установленные с момента вызова SQLAllocHandle с HandleType SQL_HANDLE_DBC. Менеджер драйверов проверяет эти критерии по соответствующим ключевым словам соединения и атрибутам соединений в пуле. Если совпадение найдено, используется соединение в пуле. Если совпадения не находятся, создаётся новое соединение.

Если атрибут среды SQL_ATTR_CP_MATCH установлен в SQL_CP_STRICT_MATCH, совпадение должно быть точным для использования соединения в пуле. Если атрибут среды SQL_ATTR_CP_MATCH установлен в SQL_CP_RELAXED_MATCH, опции соединения в вызове SQLConnect должны совпадать, но не все атрибуты соединения совпадают.

Следующие правила применяются, когда атрибут соединения, установленный приложением до вызова SQLConnect , не совпадает с атрибутом соединения в пуле:

• Если атрибут соединения должен быть установлен до установления соединения:

  Если SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE в пуле соединения должно быть идентично атрибуту, установленному приложением. Если SQL_CP_RELAXED_MATCH, значения SQL_ATTR_PACKET_SIZE могут отличаться.

  Стоимость SQL_ATTR_LOGIN_VALUE не влияет на матч.

• Если атрибут соединения можно установить либо до, либо после установления соединения:

  Если атрибут соединения не был установлен приложением, но установлен на соединении в пуле, и есть оно по умолчанию, атрибут соединения в пуле возвращается к стандартному статусу, и объявляется совпадение. Если по умолчанию нет, пуловое соединение не считается совпадением.

  Если атрибут соединения был установлен приложением, но не был установлен на соединении в пуле, атрибут соединения в пуле меняется на тот, который задаёт приложение, и объявляется совпадение.

  Если атрибут соединения был установлен приложением и также установлен на соединении в пуле, но значения разные, используется значение атрибута соединения приложения, и объявляется совпадение.

• Если значения атрибутов соединения, специфичных для драйвера, не совпадают, и SQL_ATTR_CP_MATCH установлено в SQL_CP_STRICT_MATCH, соединение в пуле не используется.

Когда приложение вызывает SQLDisconnect для отключения, соединение возвращается в пул соединений и доступно для повторного использования.

Оптимизация производительности пула соединений

Когда речь идёт о распределённых транзакциях, возможно оптимизировать производительность пула соединений с помощью SQL_DTC_TRANSITION_COST, который является битовой маской SQLUINTEGER. Переходы, о которых речь, — это переходы атрибута соединения SQL_ATTR_ENLIST_IN_DTC перехода от значения 0 к ненулевому и наоборот. Это соединение, которое переходит от незарегистрированного в распределённой транзакции к зарегистрированному в распределённой транзакции, и наоборот. В зависимости от того, как драйвер реализовал enlistment (установка атрибута соединения SQL_ATTR_ENLIST_IN_DTC), эти переходы могут быть дорогими и поэтому их следует избегать для лучшей производительности.

Значение драйвера содержит любую комбинацию следующих битов:

• SQL_DTC_ENLIST_EXPENSIVE, когда это установлено, подразумевает, что переход от нуля к ненулю значительно дороже, чем переход от ненулевой к другому ненулевому значению (при использовании ранее зарегистрированного соединения в следующей транзакции).

• SQL_DTC_UNENLIST_EXPENSIVE, когда это установлено, означает, что переход от ненулевой к нулю значительно дороже, чем использование соединения, атрибут SQL_ATTR_ENLIST_IN_DTC которого уже установлен равным нулю.

Существует компромисс производительности и использования соединения. Если драйвер указывает, что один или несколько переходов дорогие, пулер соединений менеджера драйверов отвечает на это, сохраняя больше соединений в пуле. Некоторые соединения в пуле предпочтительны для нетранзакционного использования, а некоторые — для транзакционного. Однако если драйвер указывает, что эти переходы недорогие, можно использовать меньше соединений, возможно, чередуя нетранзакционное и транзакционное.

Драйверы, которые не поддерживают SQL_ATTR_ENLIST_IN_DTC, не обязаны поддерживать SQL_DTC_TRANSITION_COST. Для драйверов, поддерживающих SQL_ATTR_ENLIST_IN_DTC, но не SQL_DTC_TRANSITION_COST, предполагается, что переходы недорогие, как если бы драйвер вернул 0 (без установленных бит) для этого значения.

Хотя SQL_DTC_TRANSITION_COST был представлен в ODBC 3.5, ODBC 2. Драйвер X также поддерживает это, потому что менеджер драйверов будет запрашивать эту информацию независимо от версии драйвера.

Пример кода

В следующем примере приложение выделяет дескрипторы среды и соединения. Затем он подключается к источнику данных SalesOrders с идентификатором пользователя JohnS и паролем Sesame и обрабатывает данные. После завершения обработки данных он отключается от источника данных и освобождает дескрипторы.

// 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);  
   }  
}  

Связанные функции

См. также

Справочник по API ODBC
Файлы заголовков ODBC