Функция SQLDriverConnect
Соответствия
Представлена версия: соответствие стандартам ODBC 1.0: ODBC
Сводка
SQLDriverConnect — это альтернатива SQLConnect. Он поддерживает источники данных, для которых требуется больше сведений о подключении, чем три аргумента в SQLConnect, диалоговые окна запрашивают пользователю все сведения о подключении и источники данных, которые не определены в системной информации. Дополнительные сведения см. в разделе "Подключение с помощью SQLDriverConnect".
Синтаксис
SQLRETURN SQLDriverConnect(
SQLHDBC ConnectionHandle,
SQLHWND WindowHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
Аргументы
ConnectionHandle
[Input] Дескриптор подключения
WindowHandle
[Входные данные] Дескриптор окна. Приложение может передать дескриптор родительского окна, если применимо, или пустой указатель, если дескриптор окна неприменим или SQLDriverConnect не будет представлять диалоговых окон.
InConnectionString
[Входные данные] Полная строка подключения (см. синтаксис в "Комментарии"), частичная строка подключения или пустая строка.
StringLength1
[Входные данные] Длина *InConnectionString в символах, если строка является Юникодом или байтами, если строка — ANSI или DBCS.
OutConnectionString
[Выходные данные] Указатель на буфер для завершенной строки подключения. После успешного подключения к целевому источнику данных этот буфер содержит завершенную строку подключения. Приложения должны выделять не менее 1024 символов для этого буфера.
Если OutConnectionString имеет значение NULL, StringLength2Ptr по-прежнему возвращает общее количество символов (за исключением символа завершения null для символов), доступное для возврата в буфер, на который указывает OutConnectionString.
BufferLength
[Входные данные] Длина буфера *OutConnectionString в символах.
StringLength2Ptr
[Выходные данные] Указатель на буфер, в котором возвращается общее число символов (за исключением символа завершения null), доступное для возврата в *OutConnectionString. Если число символов, доступных для возврата, больше или равно BufferLength, завершенная строка подключения в *OutConnectionString усечена в BufferLength минус длину символа завершения null.
DriverCompletion
[Входные данные] Флаг, указывающий, должен ли диспетчер драйверов или драйвер запрашивать дополнительные сведения о подключении:
SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED или SQL_DRIVER_NOPROMPT.
(Дополнительные сведения см. в разделе "Комментарии".")
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE или SQL_STILL_EXECUTING.
Диагностика
Когда SQLDriverConnect возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE может быть получено путем вызова SQLGetDiagRec с fHandleType SQL_HANDLE_DBC и hHandle of ConnectionHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLDriverConnect и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01004 | Строковые данные, усеченные справа | Буфер *OutConnectionString был недостаточно велик, чтобы вернуть всю строку подключения, поэтому строка подключения была усечена. Длина ненадежной строки подключения возвращается в *StringLength2Ptr. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S00 | Недопустимый атрибут строки подключения | Недопустимое ключевое слово атрибута было указано в строке подключения (InConnectionString), но драйвер мог подключиться к источнику данных в любом случае. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Изменено значение параметра | Драйвер не поддерживал указанное значение, указываемое аргументом ValuePtr в SQLSetConnectAttr и заменял аналогичное значение. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S08 | Ошибка сохранения файлов DSN | Строка в *InConnectionString содержала ключевое слово FILEDSN , но DSN-файл не был сохранен. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S09 | Недопустимое ключевое слово | (DM) Строка в *InConnectionString содержит ключевое слово SAVEFILE , но не драйвер или ключевое слово FILEDSN . (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 08001 | Клиенту не удается установить подключение | Драйверу не удалось установить подключение к источнику данных. |
| 08002 | Имя подключения, используемое | (DM) Указанный connectionHandle уже использовался для установления соединения с источником данных, и подключение по-прежнему открыто. |
| 08004 | Сервер отклонил подключение | Источник данных отклонил создание подключения по определенным причинам реализации. |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому драйвер пытался подключиться до завершения обработки функции SQLDriverConnect . |
| 28000 | Недопустимая спецификация авторизации | Либо идентификатор пользователя, либо строка авторизации, либо оба, как указано в строке подключения (InConnectionString), нарушили ограничения, определенные источником данных. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *szMessageText , описывает ошибку и ее причину. |
| HY000 | Общая ошибка: недопустимая папка файлов | (DM) Строка в *InConnectionString содержит ключевое слово FILEDSN, но имя DSN-файла не найдено. |
| HY000 | Общая ошибка: не удалось создать буфер файла | (DM) Строка в *InConnectionString содержала ключевое слово FILEDSN, но DSN-файл был нечитаемым. |
| HY001 | Ошибка выделения памяти | Диспетчер драйверов не смог выделить память, необходимую для поддержки выполнения или завершения функции SQLDriverConnect . Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ConnectionHandle. Функция была вызвана, и до завершения выполнения функция SQLCancelHandle была вызвана в ConnectionHandle, а затем функция SQLDriverConnect была вызвана снова в ConnectionHandle. Или функция SQLDriverConnect была вызвана и до завершения выполнения SQLCancelHandle была вызвана в ConnectionHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Еще одна асинхронная функция выполнения (не SQLDriverConnect) была вызвана для ConnectionHandle и по-прежнему выполнялась при вызове функции SQLDriverConnect. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции SQLDriverConnect, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY090 | Недопустимая длина строки или буфера | (DM) Значение, указанное для аргумента StringLength1 , было меньше 0 и не равно SQL_NTS. (DM) Значение, указанное для аргумента BufferLength , было меньше 0. |
| HY092 | Недопустимый идентификатор атрибута или параметра | (DM) Аргумент DriverCompletion был SQL_DRIVER_PROMPT, и аргумент WindowHandle был пустым указателем. |
| HY110 | Недопустимое завершение драйвера | (DM) Значение, указанное для аргумента DriverCompletion , не равно SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED или SQL_DRIVER_NOPROMPT. (DM) Пул подключений включен, и значение, указанное для аргумента DriverCompletion , не равно SQL_DRIVER_NOPROMPT. |
| HYC00 | Необязательный компонент не реализован | Драйвер не поддерживает версию поведения ODBC, запрошенную приложением. |
| HYT00 | Время ожидания истекло. | Срок ожидания входа истек до завершения подключения к источнику данных. Период времени ожидания задается через SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, соответствующий указанному имени источника данных, не поддерживает функцию. |
| IM002 | Источник данных не найден и драйвер по умолчанию не указан | (DM) Имя источника данных, указанное в строке подключения (InConnectionString), не найдено в системной информации, и не было спецификации драйвера по умолчанию. Источник данных ODBC и сведения об драйвере по умолчанию не найдены в системной информации. |
| IM003 | Не удалось загрузить указанный драйвер | (DM) Драйвер, указанный в спецификации источника данных в системной информации или указанный ключевым словом DRIVER , не найден или не может быть загружен по какой-либо другой причине. |
| IM004 | Ошибка SQLAllocHandle драйвера на SQL_HANDLE_ENV | (DM) Во время SQLDriverConnect диспетчер драйверов назвал функцию SQLAllocHandle драйвера с fHandleType SQL_HANDLE_ENV, а драйвер вернул ошибку. |
| IM005 | Сбой sqlAllocHandle драйвера на SQL_HANDLE_DBC. | (DM) Во время SQLDriverConnect диспетчер драйверов назвал функцию SQLAllocHandle драйвера с fHandleType SQL_HANDLE_DBC, а драйвер вернул ошибку. |
| IM006 | Ошибка SQLSetConnectAttr драйвера | (DM) Во время SQLDriverConnect диспетчер драйверов назвал функцию SQLSetConnectAttr драйвера и драйвер вернул ошибку. |
| IM007 | Не указан источник данных или драйвер; Диалоговое окно запрещено | Имя источника данных или драйвер не указан в строке подключения, и DriverCompletion SQL_DRIVER_NOPROMPT. |
| IM008 | Сбой диалогового окна | Драйвер попытался отобразить диалоговое окно входа и завершился ошибкой. WindowHandle был пустым указателем, и DriverCompletion не SQL_DRIVER_NO_PROMPT. |
| IM009 | Не удалось загрузить библиотеку DLL перевода | Драйверу не удалось загрузить библиотеку DLL перевода, указанную для источника данных или подключения. |
| IM010 | Слишком длинное имя источника данных | (DM) Значение атрибута для ключевого слова DSN превышает SQL_MAX_DSN_LENGTH символов. |
| IM011 | Слишком длинное имя драйвера | (DM) Значение атрибута для ключевого слова DRIVER было длиннее 255 символов. |
| IM012 | Ошибка синтаксиса ключевого слова DRIVER | (DM) Пара "ключевое слово-значение" для ключевого слова DRIVER содержит синтаксическую ошибку. (DM) Строка в *InConnectionString содержит ключевое слово FILEDSN , но DSN-файл не содержал ключевое слово DRIVER или ключевое слово DSN . |
| IM014 | Указанный DSN содержит несоответствие архитектуры между драйвером и приложением | (DM) 32-разрядное приложение использует DSN, подключающееся к 64-разрядному драйверу; или наоборот. |
| IM015 | Сбой драйвера SQLDriverConnect в 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. |
Комментарии
Строка подключения имеет следующий синтаксис:
connection-string ::= empty-string[;] | attribute[;] | атрибут; строка подключения
empty-string ::=attribute ::= attribute-keyword= attribute-value | DRIVER=[{]attribute-value[}]
атрибут-ключевое слово ::= DSN | UID | PWD | ключевое слово driver-defined-attribute
атрибут-значение ::= символьная строка
идентификатор driver-defined-attribute-keyword ::=
где строка символов имеет ноль или больше символов; идентификатор имеет один или несколько символов; атрибут-ключевое слово не учитывает регистр; Атрибут-значение может быть чувствительным к регистру, и значение ключевого слова DSN не состоит исключительно из пустых.
Из-за строки подключения и грамматики файла инициализации, ключевых слов и значений атрибутов, содержащих символы []{}(),?? *=!@ не заключен в скобки следует избегать. Значение ключевого слова DSN не может состоять только из пустых и не должно содержать пустые в начале. Из-за грамматики системной информации ключевые слова и имена источников данных не могут содержать символ обратной косой черты (\).
Приложениям не нужно добавлять фигурные скобки вокруг значения атрибута после ключевого слова DRIVER , если атрибут не содержит точку с запятой (;), в этом случае требуются фигурные скобки. Если значение атрибута, которое получает драйвер, включает фигурные скобки, драйвер не должен удалять их, но они должны быть частью возвращаемой строки подключения.
Значение строки DSN или строки подключения, заключенное в фигурные скобки ({}) с любым из символов []{}(),?? *=!@ передается в драйвер без изменений. Однако при использовании этих символов в ключевом слове диспетчер драйверов возвращает ошибку при работе с доменными именами файлов, но передает строку подключения драйверу для регулярных строк подключения. Избегайте использования внедренных фигурных скобок в значении ключевого слова.
Строка подключения может включать любое количество ключевых слов, определенных драйвером. Так как ключевое слово DRIVER не использует сведения из системных сведений, драйвер должен определить достаточно ключевых слов, чтобы драйвер смог подключиться к источнику данных, используя только сведения в строке подключения. (Дополнительные сведения см. в разделе "Рекомендации по драйверам" далее в этом разделе.) Драйвер определяет, какие ключевые слова необходимы для подключения к источнику данных.
В следующей таблице описаны значения атрибутов ключевых слов DSN, FILEDSN, DRIVER, UID, PWD и SAVEFILE.
| Ключевое слово | Описание значения атрибута |
|---|---|
| DSN | Имя источника данных, возвращаемого SQLDataSources или диалоговым окном источников данных SQLDriverConnect. |
| FILEDSN | Имя DSN-файла, из которого будет создана строка подключения для источника данных. Эти источники данных называются источниками данных файлов. |
| ДРАЙВЕР | Описание драйвера, возвращаемого функцией SQLDrivers . Например, Rdb или SQL Server. |
| UID | Идентификатор пользователя. |
| PWD | Пароль, соответствующий идентификатору пользователя, или пустая строка, если для идентификатора пользователя нет пароля (PWD=;). |
| SAVEFILE | Имя файла DSN, в котором следует сохранить значения атрибутов ключевых слов, используемых при наличии текущего, успешное подключение. |
Сведения о том, как приложение выбирает источник данных или драйвер, см. в разделе "Выбор источника данных" или "Драйвер".
Если в строке подключения повторяются какие-либо ключевые слова, драйвер использует значение, связанное с первым вхождением ключевого слова. Если ключевые слова DSN и DRIVER включены в ту же строку подключения, диспетчер драйверов и драйвер используют любое ключевое слово.
Ключевые слова FILEDSN и DSN являются взаимоисключающими: любое ключевое слово, которое отображается первым, и тот, который отображается вторым, игнорируется. Ключевые слова FILEDSN и DRIVER , с другой стороны, не являются взаимоисключающими. Если какое-либо ключевое слово отображается в строке подключения с ПОМОЩЬЮ FILESN, то используется значение атрибута ключевого слова в строке подключения, а не значение атрибута того же ключевого слова в DSN-файле.
Если используется ключевое слово FILEDSN , ключевые слова, указанные в DSN-файле, используются для создания строки подключения. (Дополнительные сведения см. в разделе "Источники данных файлов" далее в этом разделе.) Ключевое слово UID является необязательным; файл .dsn может быть создан только с ключевым словом DRIVER . Ключевое слово PWD не хранится в DSN-файле. Каталог по умолчанию для сохранения и загрузки DSN-файла будет сочетанием пути, указанного CommonFileDir в HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion и ODBC\DataSources. (Если CommonFileDir были "C:\Program Files\Common Files", каталог по умолчанию будет "C:\Program Files\Common Files\ODBC\Data Sources".
Заметка
DSN-файл можно управлять непосредственно путем вызова функций SQLReadFileDSN и SQLWriteFileDSN в библиотеке DLL установщика.
Если используется ключевое слово SAVEFILE, значения атрибутов ключевых слов, используемых в создании настоящего, успешное подключение будет сохранено в виде DSN-файла с именем значения атрибута ключевого слова SAVEFILE. Ключевое слово SAVEFILE должно использоваться в сочетании с ключевым словом DRIVER , ключевым словом FILEDSN или обоими, либо функция возвращает SQL_SUCCESS_WITH_INFO с SQLSTATE 01S09 (недопустимое ключевое слово). Ключевое слово SAVEFILE должно отображаться перед ключевым словом DRIVER в строке подключения или результаты будут неопределенными.
Рекомендации по диспетчеру драйверов
Диспетчер драйверов создает строку подключения для передачи драйверу в аргументе InConnectionString функции SQLDriverConnect драйвера. Диспетчер драйверов не изменяет аргумент InConnectionString , переданный в него приложением.
Действие диспетчера драйверов основано на значении аргумента DriverCompletion :
SQL_DRIVER_PROMPT. Если строка подключения не содержит ключевое слово DRIVER, DSN или FILEDSN , диспетчер драйверов отображает диалоговое окно "Источники данных". Он создает строку подключения из имени источника данных, возвращаемого диалоговым окном, и любые другие ключевые слова, передаваемые в него приложением. Если имя источника данных, возвращаемое диалоговым окном, пусто, диспетчер драйверов указывает пару "ключевое слово-значение" DSN=Default. (Это диалоговое окно не будет отображать источник данных с именем Default.)
SQL_DRIVER_COMPLETE или SQL_DRIVER_COMPLETE_REQUIRED. Если строка подключения, указанная приложением , включает ключевое слово DSN , диспетчер драйверов копирует строку подключения, указанную приложением. В противном случае он выполняет те же действия, что и при SQL_DRIVER_PROMPT DriverCompletion .
SQL_DRIVER_NOPROMPT. Диспетчер драйверов копирует строку подключения, указанную приложением.
Если строка подключения, указанная приложением, содержит ключевое слово DRIVER , диспетчер драйверов копирует строку подключения, указанную приложением.
Используя созданную строку подключения, диспетчер драйверов определяет, какой драйвер следует использовать, подключается к нему и передает строку подключения, созданную драйверу; Дополнительные сведения о взаимодействии диспетчера драйверов и драйвера см. в разделе "Комментарии" в функции SQLConnect. Если строка подключения не содержит ключевое слово DRIVER , диспетчер драйверов определяет, какой драйвер следует использовать следующим образом:
Если строка подключения содержит ключевое слово DSN , диспетчер драйверов извлекает драйвер, связанный с источником данных, из системных сведений.
Если строка подключения не содержит ключевое слово DSN или источник данных не найден, диспетчер драйверов извлекает драйвер, связанный с источником данных по умолчанию, из системной информации. (Дополнительные сведения см. в разделе Подраздел по умолчанию.) Диспетчер драйверов изменяет значение ключевого слова DSN в строке подключения на DEFAULT.
Если ключевое слово DSN в строке подключения имеет значение DEFAULT, диспетчер драйверов извлекает драйвер, связанный с источником данных по умолчанию, из системных сведений.
Если источник данных не найден и источник данных по умолчанию не найден, диспетчер драйверов возвращает SQL_ERROR с SQLSTATE IM002 (источник данных не найден и не указан драйвер по умолчанию).
Файловые источники данных
Если строка подключения, указанная приложением в вызове SQLDriverConnect, содержит ключевое слово FILEDSN, и это ключевое слово не заменяется ключевым словом DSN или DRIVER, диспетчер драйверов создает строку подключения, используя сведения в DSN-файле и аргументе InConnectionString. Диспетчер драйверов продолжается следующим образом:
Проверяет, является ли допустимым имя файла DSN. В противном случае возвращается SQL_ERROR с SQLSTATE IM014 (недопустимое имя dsN файла). Если имя файла является пустой строкой ("") и SQL_DRIVER_NOPROMPT не указано, отображается диалоговое окно "Открыть файл". Если имя файла содержит допустимый путь, но имя файла или недопустимое имя файла, а SQL_DRIVER_NOPROMPT не указано, диалоговое окно "Открыть файл" отображается с текущим каталогом, заданным в имени файла. Если имя файла является пустой строкой ("") или имя файла содержит допустимый путь, но имя файла или недопустимое имя файла, а SQL_DRIVER_NOPROMPT указано, то SQL_ERROR возвращается с помощью SQLSTATE IM014 (недопустимое имя dsN файла).
Считывает все ключевые слова в разделе [ODBC] файла DSN. Если ключевое слово DRIVER отсутствует, он возвращает SQL_ERROR с SQLSTATE IM012 (ошибка синтаксиса ключевого слова драйвера), за исключением случаев, когда dsn-файл не является общим и поэтому содержит только ключевое слово DSN .
Если источник данных файла недоступен, диспетчер драйверов считывает значение ключевого слова DSN и подключается по мере необходимости к источнику данных пользователя или системы, на который указывает источник данных без общего доступа. Шаги 3–5 не выполняются.
Создает строку подключения для драйвера. Строка подключения драйвера — это объединение ключевых слов, указанных в DSN-файле, и тех, которые указаны в исходной строке подключения приложения. Правила построения строки подключения драйвера, в которой перекрываются ключевые слова, следующим образом:
Если ключевое слово DRIVER существует в строке подключения приложения, а драйверы, указанные ключевыми словами DRIVER, не совпадают в DSN-файле и строке подключения приложения, то сведения о драйвере в DSN-файле игнорируются, а сведения о драйвере в строке подключения приложения используются. Если драйверы, указанные ключевым словом DRIVER , совпадают в DSN-файле и строке подключения приложения, то все ключевые слова перекрываются, те, которые указаны в строке подключения приложения, имеют приоритет над теми, которые указаны в DSN-файле.
В новой строке подключения ключевое слово FILEDSN устраняется.
Загружает драйвер, просматривая запись реестра HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST. INI\<Driver Name>\Driver, где <имя> драйвера указано ключевым словом DRIVER .
Передает драйверу новую строку подключений.
Примеры dsn-файлов см. в разделе "Подключение с помощью источников данных файлов".
Ключевое слово SAVEFILE
Если строка подключения, указанная приложением, содержит ключевое слово SAVEFILE , диспетчер драйверов сохраняет строку подключения в DSN-файле. Диспетчер драйверов продолжается следующим образом:
Проверяет допустимость имени файла DSN-файла, включенного в качестве значения атрибута ключевого слова SAVEFILE . В противном случае возвращается SQL_ERROR с SQLSTATE IM014 (недопустимое имя dsN файла). Допустимость имени файла определяется стандартными правилами именования системы. Если имя файла является пустой строкой ("") и аргумент DriverCompletion не SQL_DRIVER_NOPROMPT, то имя файла допустимо. Если имя файла уже существует, то если DriverCompletion SQL_DRIVER_NOPROMPT, файл перезаписывается. Если DriverCompletion SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE или SQL_DRIVER_COMPLETE_REQUIRED, диалоговое окно предложит пользователю указать, должен ли файл быть перезаписан. Если нет, появится диалоговое окно "Сохранить файл".
Если драйвер возвращает SQL_SUCCESS, а имя файла не было пустой строкой, диспетчер драйверов записывает сведения о подключении, возвращаемые в аргументе OutConnectionString, в указанный файл с форматом, указанным в разделе "Строки подключения" выше в этом разделе.
Если драйвер возвращает SQL_SUCCESS, а имя файла было пустой строкой (""), диспетчер драйверов вызывает общее диалоговое окно "Сохранить файл" с заданным hwnd и записывает сведения о подключении, возвращенные в OutConnectionString, в файл, указанный в общем диалоговом окне "Сохранить файл" с форматом, указанным в разделе "Строки подключения" ранее в этом разделе.
Если драйвер возвращает SQL_SUCCESS, он возвращает аргумент OutConnectionString , содержащий строку подключения к приложению.
Если драйвер возвращает SQL_SUCCESS_WITH_INFO или SQL_ERROR, диспетчер драйверов возвращает SQLSTATE приложению.
Рекомендации по драйверам
Драйвер проверяет, передается ли в него строка подключения диспетчером драйверов ключевое слово DSN или DRIVER . Если строка подключения содержит ключевое слово DRIVER , драйвер не может получить сведения об источнике данных из системных сведений. Если строка подключения содержит ключевое слово DSN или не содержит dsN или ключевое слово DRIVER, драйвер может получить сведения об источнике данных из системных сведений следующим образом:
Если строка подключения содержит ключевое слово DSN , драйвер извлекает сведения для указанного источника данных.
Если строка подключения не содержит ключевое слово DSN, указанный источник данных не найден или ключевое слово DSN имеет значение DEFAULT, драйвер получает сведения для источника данных по умолчанию.
Драйвер использует любую информацию, полученную из системной информации, для расширения информации, переданной в нее в строке подключения. Если сведения в системной информации дублируют сведения в строке подключения, драйвер использует сведения в строке подключения.
В зависимости от значения DriverCompletion драйвер запрашивает пользователю сведения о подключении, такие как идентификатор пользователя и пароль, и подключается к источнику данных:
SQL_DRIVER_PROMPT. Драйвер отображает диалоговое окно, используя значения из строки подключения и системной информации (если таковые есть) в качестве начальных значений. Когда пользователь выходит из диалогового окна, драйвер подключается к источнику данных. Она также создает строку подключения из значения ключевого слова DSN или DRIVER в *InConnectionString и сведения, возвращаемые из диалогового окна. Он помещает эту строку подключения в буфер *OutConnectionString .
SQL_DRIVER_COMPLETE или SQL_DRIVER_COMPLETE_REQUIRED. Если строка подключения содержит достаточно сведений, а эта информация правильна, драйвер подключается к источнику данных и копирует *InConnectionString в *OutConnectionString. Если отсутствуют или неверные сведения, драйвер выполняет те же действия, что и при SQL_DRIVER_PROMPT DriverCompletion, за исключением того, что если DriverCompletion SQL_DRIVER_COMPLETE_REQUIRED, драйвер отключает элементы управления для каких-либо сведений, не необходимых для подключения к источнику данных.
SQL_DRIVER_NOPROMPT. Если строка подключения содержит достаточно сведений, драйвер подключается к источнику данных и копирует *InConnectionString в *OutConnectionString. В противном случае драйвер возвращает SQL_ERROR для SQLDriverConnect.
При успешном подключении к источнику данных драйвер также задает *StringLength2Ptr длину строки выходного подключения, доступной для возврата в *OutConnectionString.
Если пользователь отменяет диалоговое окно, представленное диспетчером драйверов или драйвером, SQLDriverConnect возвращает SQL_NO_DATA.
Сведения о взаимодействии диспетчера драйверов и драйвера во время процесса подключения см. в разделе "Функция SQLConnect".
Если драйвер поддерживает SQLDriverConnect, раздел ключевого слова драйвера системной информации драйвера должен содержать ключевое слово ConnectFunctions со вторым символом Y.
Подключение при включенном пуле подключений
Пул подключений позволяет приложению повторно использовать подключение, которое уже создано. При вызове SQLDriverConnect диспетчер драйверов пытается сделать подключение с помощью подключения, являющегося частью пула подключений в среде, которая была назначена для пула подключений. Дополнительные сведения о пуле подключений см. в разделе "Функция SQLConnect".
Приложение может задать SQL_ATTR_RESET_CONNECTION перед вызовом SQLDisconnect в подключении, в котором включена пуловая связь. Дополнительные сведения см. в разделе "Функция SQLSetConnectAttr".
Следующие ограничения применяются, когда приложение вызывает SQLDriverConnect для подключения к пулу:
Обработка пула соединений не выполняется, если ключевое слово SAVEFILE указано в строке подключения.
Если пул подключений включен, sqlDriverConnect можно вызывать только с аргументом DriverCompletion SQL_DRIVER_NOPROMPT; если SQLDriverConnect вызывается с любым другим драйверомCompletion, функция SQLSTATE HY110 (недопустимое завершение драйвера) будет возвращена.
Атрибуты подключения
Атрибут подключения SQL_ATTR_LOGIN_TIMEOUT, заданный с помощью SQLSetConnectAttr, определяет количество секунд, ожидающих завершения запроса входа с успешным подключением драйвером перед возвращением в приложение. Если пользователю будет предложено завершить строку подключения, период ожидания для каждого запроса входа начинается при запуске драйвера процесса подключения.
Драйвер открывает подключение в режиме доступа SQL_MODE_READ_WRITE по умолчанию. Чтобы задать режим доступа для SQL_MODE_READ_ONLY, приложение должно вызвать SQLSetConnectAttr с атрибутом SQL_ATTR_ACCESS_MODE перед вызовом SQLDriverConnect.
Если библиотека перевода по умолчанию указана в системной информации для источника данных, драйвер загружает его. Можно загрузить другую библиотеку перевода, вызвав SQLSetConnectAttr с атрибутом SQL_ATTR_TRANSLATE_LIB. Параметр перевода можно указать путем вызова SQLSetConnectAttr с параметром SQL_ATTR_TRANSLATE_OPTION.
Дополнительные сведения см. в разделе "Подключение с помощью SQLDriverConnect".
// SQLDriverConnect_ref.cpp
// compile with: odbc32.lib user32.lib
#include <windows.h>
#include <sqlext.h>
int main() {
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR OutConnStr[255];
SQLSMALLINT OutConnStrLen;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
// 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, (SQLPOINTER*)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);
retcode = SQLDriverConnect( // SQL_NULL_HDBC
hdbc,
desktopHandle,
(SQLCHAR*)"driver=SQL Server",
_countof("driver=SQL Server"),
OutConnStr,
255,
&OutConnStrLen,
SQL_DRIVER_PROMPT );
// 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);
}
}
См. также пример программы ODBC.
Связанные функции
| Сведения | Раздел |
|---|---|
| Выделение дескриптора | Функция SQLAllocHandle |
| Обнаружение и перечисление значений, необходимых для подключения к источнику данных | Функция SQLBrowseConnect |
| подключение к источнику данных; | Функция SQLConnect |
| Отключение от источника данных | Функция SQLDisconnect |
| Возврат описания и атрибуты драйвера | Функция SQLDrivers |
| Освобождение дескриптора | Функция SQLFreeHandle |
| Настройка атрибута подключения | Функция SQLSetConnectAttr |
См. также
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по