Функция SQLConnect

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

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

Синтаксис

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

Аргументы

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

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

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

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

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

Проверка подлинности
[Входные данные] Строка проверки подлинности (обычно пароль).

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

Возвраты

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

Диагностика

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

Комментарии

Сведения о том, почему приложение использует SQLConnect, см. в разделе "Подключение к SQLConnect".

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

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

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

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

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

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

Приложение ODBC может установить несколько подключений.

Рекомендации по диспетчеру драйверов

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

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

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

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

• Если имя источника данных не удается найти или имя сервера является пустым указателем, а спецификация источника данных по умолчанию не существует, диспетчер драйверов возвращает 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 с именем HandleTypeSQL_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 к ненулевому и наоборот. Это соединение, не заверяемое в распределенную транзакцию, для зачисления в распределенную транзакцию, и наоборот. В зависимости от того, как драйвер реализовал зачисление (настройка атрибута подключения 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