Функция SQLConnect

Статья
08/21/2023

Соответствия
Представлена версия: соответствие стандартам 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, если не указано иное.

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01S02	Изменено значение параметра	Драйвер не поддерживал указанное значение аргумента ValuePtr в SQLSetConnectAttr и заменил аналогичное значение. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
08001	Клиенту не удается установить подключение	Драйверу не удалось установить подключение к источнику данных.
08002	Имя подключения, используемое	(DM) Указанный connectionHandle уже использовался для установления подключения к источнику данных, и подключение по-прежнему открыто или пользователь просматривал подключение для подключения.
08004	Сервер отклонил подключение	Источник данных отклонил создание подключения по определенным причинам реализации.
08S01	Сбой связи	Связь между драйвером и источником данных, к которому драйвер пытался подключиться до завершения обработки функции.
28000	Недопустимая спецификация авторизации	Значение, указанное для аргумента UserName или значение, указанное для проверки подлинности аргумента, нарушило ограничения, определенные источником данных.
HY000	Общая ошибка	Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001	Ошибка выделения памяти	(DM) Диспетчер драйверов не смог выделить память, необходимую для поддержки выполнения или завершения функции.
HY008	Операция отменена	Асинхронная обработка была включена для ConnectionHandle. Функция SQLConnect была вызвана и до завершения выполнения функция SQLCancelHandle была вызвана в ConnectionHandle, а затем функция SQLConnect была вызвана снова в ConnectionHandle. Или функция SQLConnect была вызвана и до завершения выполнения SQLCancelHandle была вызвана в ConnectionHandle из другого потока в многопотоковом приложении.
HY010	Ошибка последовательности функций	(DM) асинхронно выполняющаяся функция (не эта) была вызвана для ConnectionHandle и по-прежнему выполнялась при вызове этой функции.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090	Недопустимая длина строки или буфера	(DM) Значение, указанное для аргумента NameLength1, NameLength2 или NameLength3, было меньше 0, но не равно SQL_NTS. (DM) Значение, указанное для аргумента NameLength1 , превысило максимальную длину имени источника данных.
HYT00	Время ожидания истекло.	Срок ожидания запроса истек до завершения подключения к источнику данных. Период времени ожидания задается через SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT.
HY114	Драйвер не поддерживает асинхронное выполнение асинхронной функции уровня подключения	(DM) Приложение включило асинхронную операцию в дескрипторе подключения перед подключением. Однако драйвер не поддерживает асинхронные операции с дескриптором подключения.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, указанный именем источника данных, не поддерживает функцию.
IM002	Источник данных не найден и драйвер по умолчанию не указан	(DM) Имя источника данных, указанное в аргументе ServerName , не найдено в системной информации, а также не было спецификации драйвера по умолчанию.
IM003	Не удалось подключить указанный драйвер к	(DM) Драйвер, указанный в спецификации источника данных в системной информации, не найден или не удалось подключиться по какой-либо другой причине.
IM004	Сбой драйвера SQLAllocHandle на SQL_HANDLE_ENV	(DM) Во время SQLConnect диспетчер драйверов назвал функцию SQLAllocHandle драйвера с помощью HandleType SQL_HANDLE_ENV, а драйвер вернул ошибку.
IM005	Ошибка sqlAllocHandle драйвера на SQL_HANDLE_DBC	(DM) Во время SQLConnect диспетчер драйверов назвал функцию SQLAllocHandle драйвера с помощью HandleType SQL_HANDLE_DBC, а драйвер вернул ошибку.
IM006	Ошибка SQLSetConnectAttr драйвера	Во время SQLConnect диспетчер драйверов назвал функцию SQLSetConnectAttr драйвера, а драйвер вернул ошибку. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
IM009	Не удается подключиться к библиотеке DLL перевода	Драйвер не удалось подключиться к библиотеке DLL перевода, указанной для источника данных.
IM010	Слишком длинное имя источника данных	(DM) *Имя сервера было длиннее SQL_MAX_DSN_LENGTH символов.
IM014	Указанный DSN содержит несоответствие архитектуры между драйвером и приложением	(DM) 32-разрядное приложение использует DSN, подключающееся к 64-разрядному драйверу; или наоборот.
IM015	Сбой sqlConnect драйвера в SQL_HANDLE_DBC_INFO_HANDLE	Если драйвер возвращает SQL_ERROR, диспетчер драйверов вернет SQL_ERROR приложению, а подключение завершится ошибкой. Дополнительные сведения о SQL_HANDLE_DBC_INFO_TOKEN см. в статье "Разработка осведомленности о пуле подключений" в драйвере ODBC.
IM017	Опрос отключен в асинхронном режиме уведомлений	При использовании модели уведомлений опрос отключается.
IM018	SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором.	Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции.
S1118	Драйвер не поддерживает асинхронное уведомление	Если драйвер не поддерживает асинхронное уведомление, нельзя задать SQL_ATTR_ASYNC_DBC_EVENT или SQL_ATTR_ASYNC_DBC_RETCODE_PTR.

Диспетчер драйверов не подключается к драйверу, пока приложение не вызывает функцию (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);  
   }  
}

Сведения	Раздел
Выделение дескриптора	Функция SQLAllocHandle
Обнаружение и перечисление значений, необходимых для подключения к источнику данных	Функция SQLBrowseConnect
Отключение от источника данных	Функция SQLDisconnect
Подключение к источнику данных с помощью строки подключения или диалогового окна	Функция SQLDriverConnect
Возврат параметра атрибута подключения	Функция SQLGetConnectAttr
Настройка атрибута подключения	Функция SQLSetConnectAttr

См. также

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

Поделиться через

Функция SQLConnect

Синтаксис

Аргументы

Возвраты

Диагностика

Комментарии

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

Объединение подключений в пул

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

Пример кода

См. также

Обратная связь

Дополнительные ресурсы

Поделиться через

Функция SQLConnect

Синтаксис

Аргументы

Возвраты

Диагностика

Комментарии

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

Объединение подключений в пул

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

Пример кода

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

См. также

Обратная связь

Дополнительные ресурсы