Функция 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, если не указано иное.
| 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, см. в разделе "Подключение к 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);
}
}
Связанные функции
| Сведения | Раздел |
|---|---|
| Выделение дескриптора | Функция SQLAllocHandle |
| Обнаружение и перечисление значений, необходимых для подключения к источнику данных | Функция SQLBrowseConnect |
| Отключение от источника данных | Функция SQLDisconnect |
| Подключение к источнику данных с помощью строки подключения или диалогового окна | Функция SQLDriverConnect |
| Возврат параметра атрибута подключения | Функция SQLGetConnectAttr |
| Настройка атрибута подключения | Функция SQLSetConnectAttr |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по