Функция SQLDriverConnect

Соответствие
Введенная версия: Соответствие стандартам ODBC 1.0: ODBC

Сводка
SQLDriverConnect — это альтернатива SQLConnect. Он поддерживает источники данных, требующие больше информации о соединении, чем три аргумента в SQLConnect, диалоговые окна для запроса пользователя всей информации о соединениях и источники данных, не определённые в системной информации. Для получения дополнительной информации смотрите раздел «Подключение к SQLDriverConnect».

Syntax

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);

Arguments

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

WindowHandle
[Ввод] Ручка окна. Приложение может передавать дескриптор родительского окна, если применимо, или нулевый указатель, если дескриптор окна неприменим или если SQLDriverConnect не отображает никаких диалоговых окн.

InConnectionString
[Ввод] Full строка подключения (см. синтаксис в разделе «Comments»), partial строка подключения или пустая строка.

StringLength1
[Ввод] Длина *InConnectionString, в символах, если строка Unicode, или в байтах, если строка ANSI или DBCS.

OutConnectionString
[Выход] Указатель на буфер для завершённой строка подключения. После успешного подключения к целевому источнику данных этот буфер содержит завершённую строка подключения. Приложения должны выделить не менее 1 024 символа для этого буфера.

Если OutConnectionString — NULL, StringLength2Ptr всё равно вернёт общее количество символов (за исключением символа null-termination для данных символов), доступных для возврата в буфере, на который указывает OutConnectionString.

BufferLength
[Ввод] Длина буфера *OutConnectionString , в символах.

StringLength2Ptr
[Выход] Указатель на буфер, в котором можно вернуть общее количество символов (исключая символ нулевой терминации), доступных для возврата в *OutConnectionString. Если количество символов, доступных для возврата, превышает или равно BufferLength, завершённая строка подключения в *OutConnectionString усекается до BufferLength минус длина символа null-termination.

ПилотЗавершение
[Ввод] Флаг, указывающий, должен ли Driver Manager или водитель запросить дополнительную информацию о соединении:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED или SQL_DRIVER_NOPROMPT.

(Для дополнительной информации см. раздел «Комментарии».)

Returns

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

Diagnostics

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

SQLSTATE Ошибка Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004 Строковые данные, усеченные справа Буфер *OutConnectionString был недостаточно велик, чтобы вернуть всю строка подключения, поэтому строка подключения был усечён. Длина неусечённой строка подключения возвращается в *StringLength2Ptr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01S00 Атрибут invalid строка подключения В строка подключения (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 , но не DRIVER или FILEDSN . (Функция возвращает SQL_SUCCESS_WITH_INFO.)
08001 Клиент не может установить соединение Драйвер не смог установить соединение с источником данных.
08002 Используемое название соединения (DM) Указанный ConnectionHandle уже использовался для установления соединения с источником данных, и соединение оставалось открытым.
08004 Сервер отклонил соединение Источник данных отклонил установление соединения по причинам, определённым реализацией.
08S01 Сбой связи Связь между драйвером и источником данных, к которому драйвер пытался подключиться, не состоялась до завершения обработки функцией SQLDriverConnect .
28000 Некорректная спецификация авторизации Либо идентификатор пользователя, либо строка авторизации, либо оба, указанные в строка подключения (InConnectionString), нарушали ограничения, определённые источником данных.
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *szMessageText , описывает ошибку и её причину.
HY000 Общая ошибка: Некорректный файл dsn (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), не было найдено в системной информации, и стандартной спецификации драйвера не было.

(DM) Информация о источнике данных 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 см. раздел «Развитие Connection-Pool осведомлённости у водителя ODBC».
IM017 Опрос отключен в асинхронном режиме уведомлений При использовании модели уведомлений опрос отключается.
IM018 SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции.
S1118 Драйвер не поддерживает асинхронное уведомление Если драйвер не поддерживает асинхронное уведомление, нельзя установить SQL_ATTR_ASYNC_DBC_EVENT или SQL_ATTR_ASYNC_DBC_RETCODE_PTR.

Comments

Строка строка подключения имеет следующий синтаксис:

connection-string ::= пустая строка[;] | атрибут [;] | атрибут; строка соединения

пустая строка ::=атрибут ::= атрибут-ключевое слово=атрибут-значение | DRIVER=[{]attribute-value[}]

attribute-keyword ::= DSN | UID | Инвалидность | driver-defined-attribute-keyword

атрибут-значение ::= строка символа

driver-defined-attribute-keyword ::= идентификатор

где строка символов содержит ноль или более символов; идентификатор имеет один или несколько символов; Атрибут-ключевое слово не зависит от регистра; Атрибут-значение может быть чувствительным к регистру; и значение ключевого слова DSN не состоит только из пустых пробелов.

Из-за грамматики строка подключения и инициализационных файлов, ключевых слов и значений атрибутов, содержащих символы []{}(),;? *=!@ без брекетов следует избегать. Значение ключевого слова DSN не может состоять только из пробелов и не должно содержать начальные пробелы. Из-за грамматики системной информации ключевые слова и имена источников данных не могут содержать символ обратной косой черты (\).

Приложения не обязаны добавлять скобки вокруг значения атрибута после ключевого слова DRIVER , если только атрибут не содержит точку с запятой (;), в этом случае необходимы скобки. Если значение атрибута, которое получает драйвер, включает фигурные скобки, драйвер не должен удалять их, но они должны быть частью возвращаемой строки подключения.

DSN или значение строка подключения, заключённое с скобками ({}), содержащее любые символы []{}(),;? *=!@ передаётся водителю целым. Однако при использовании этих символов в ключевом слове менеджер драйверов возвращает ошибку при работе с файлами DSN, но передаёт строка подключения драйверу для обычных строк соединения. Избегайте использования внедренных фигурных скобок в значении ключевого слова.

Строка подключения может включать любое количество ключевых слов, определенных драйвером. Поскольку ключевое слово DRIVER не использует информацию из системной информации, драйвер должен определить достаточно ключевых слов, чтобы драйвер мог подключиться к источнику данных, используя только информацию из строка подключения. (Для получения дополнительной информации см. раздел «Руководства для водителей» позже в этом разделе.) Драйвер определяет, какие ключевые слова необходимы для подключения к источнику данных.

В следующей таблице описываются атрибутные значения ключевых слов DSN, FILEDSN, DRIVER, UID,PWD и SAVEFILE .

Keyword Описание значения атрибута
DSN Имя источника данных, возвращаемое SQLDataSources или в диалоговом окне источников данных SQLDriverConnect.
FILEDSN Название .dsn-файла, из которого будет построена строка подключения для источника данных. Эти источники данных называются файловыми источниками.
ВОДИТЕЛЬ Описание драйвера, возвращаемого функцией SQLDrivers . Например, Rdb или SQL Server.
UID Идентификатор пользователя.
PWD Пароль, соответствующий идентификатору пользователя, или пустая строка, если для этого идентификатора нет пароля (PWD=;).
СОХРАНЁННЫЙ файл Имя файла .dsn, в котором должны сохраняться атрибуты ключевых слов, использованных для успешного соединения.

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

Если в строка подключения повторяются ключевые слова, драйвер использует значение, связанное с первым появлением этого ключевого слова. Если ключевые слова DSN и DRIVER включены в одну строка подключения, Driver Manager и драйвер используют то ключевое слово, которое появится первым.

Ключевые слова FILEDSN и DSN взаимоисключают: используется первое ключевое слово, а второе — игнорируется. Ключевые слова FILEDSN и DRIVER , напротив, не исключают друг друга. Если в строка подключения с FILEDSN встречается любое ключевое слово, то в .dsn-файле используется атрибутное значение ключевого слова в строка подключения, а не атрибутное значение того же ключевого слова в .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».)

Note

.dsn-файл можно управлять напрямую, вызывая функции SQLReadFileDSN и SQLWriteFileDSN в DLL установщика.

Если используется ключевое слово SAVEFILE , значения атрибутов ключевых слов, использованных при успешном соединении, сохраняются в виде .dsn-файла с именем атрибута ключевого слова SAVEFILE . Ключевое слово SAVEFILE должно использоваться вместе с ключевым словом DRIVER , ключевым словом FILEDSN или обоими, иначе функция возвращает SQL_SUCCESS_WITH_INFO с SQLSTATE 01S09 (недопустимое ключевое слово). Ключевое слово SAVEFILE должно появиться перед ключевым словом DRIVER в строке connection, иначе результаты будут неопределёнными.

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

Driver Manager строит строка подключения, которую передаёт драйверу в аргументе InConnectionString функции SQLDriverConnect драйвера. Менеджер драйверов не изменяет аргумент InConnectionString , переданный ему приложением.

Действие Driver Manager основано на значении аргумента DriverCompletion :

  • SQL_DRIVER_PROMPT: Если строка подключения не содержит ни DRIVER, ни DSN, ни FILEDSN, Driver Manager отображает диалоговое окно «Источники данных». Он строит строка подключения из имени источника данных, возвращаемого в диалоговом окне, и других ключевых слов, переданных приложением. Если имя источника данных, возвращаемое в диалоговом окне, пусто, менеджер драйверов указывает пару ключевого слова значения DSN=Default. (В этом диалоговом окне не будет отображаться источник данных с названием «Default».)

  • SQL_DRIVER_COMPLETE или SQL_DRIVER_COMPLETE_REQUIRED: Если строка подключения, указанный приложением, содержит ключевое слово DSN, Driver Manager копирует строка подключения, указанный приложением. В противном случае он выполняет те же действия, что и при DriverCompletion SQL_DRIVER_PROMPT.

  • SQL_DRIVER_NOPROMPT: Менеджер драйверов копирует строка подключения, указанный приложением.

Если строка подключения, указанная приложением, содержит ключевое слово DRIVER, Driver Manager копирует строка подключения, указанную приложением.

Используя созданную строка подключения, Driver Manager определяет, какой драйвер использовать, подключается к этому драйверу и передаёт созданную строка подключения драйверу; для получения дополнительной информации о взаимодействии Driver Manager и драйвера см. раздел «Комментарии» в функции SQLConnect. Если строка подключения не содержит ключевого слова DRIVER, Driver Manager определяет, какой драйвер использовать следующим образом:

  1. Если строка подключения содержит ключевое слово DSN, менеджер драйверов извлекает драйвер, связанный с источником данных, из системной информации.

  2. Если строка подключения не содержит ключевого слова DSN или источник данных не найден, менеджер драйверов получает драйвер, связанный с источником данных по умолчанию, из системной информации. (Для дополнительной информации см. раздел Default Subkey.) Менеджер драйверов меняет значение ключевого слова DSN в строке строка подключения на ""DEFAULT.

  3. Если ключевое слово DSN в строка подключения установлено в «DEFAULT», менеджер драйверов извлекает драйвер, связанный с источником данных по умолчанию, из системной информации.

  4. Если источник данных не найден и не найден источник данных по умолчанию, менеджер драйверов возвращает SQL_ERROR с SQLSTATE IM002 (источник данных не найден и драйвер по умолчанию не указан).

Источники данных файлов

Если строка подключения, указанная приложением в вызове SQLDriverConnect, содержит ключевое слово FILEDSN, и это ключевое слово не заменяется ни DSN, ни DRIVER, то Driver Manager создаёт строка подключения, используя информацию из .dsn-файла и аргумент InConnectionString. Менеджер водителя продолжает следующее:

  1. Проверяет, корректно ли имя файла .dsn. Если нет, SQL_ERROR возвращается с SQLSTATE IM014 (неверное имя DSN файла). Если имя файла — пустая строка («») и SQL_DRIVER_NOPROMPT не указано, то отображается диалоговое окно «Открытие файла ». Если имя файла содержит допустимый путь, но нет имени файла или недействительного имени, и SQL_DRIVER_NOPROMPT не указано, то отображается диалоговое окно «Открытие файла » с текущей директорией, установленной на тот, что указано в имени файла. Если имя файла — пустая строка ("") или имя файла содержит допустимый путь, но нет имени файла или неверного имени, и SQL_DRIVER_NOPROMPT указано, то SQL_ERROR возвращается с SQLSTATE IM014 (Неверное имя файла DSN).

  2. Читает все ключевые слова в разделе [ODBC] файла .dsn. Если ключевое слово DRIVER отсутствует, оно возвращает SQL_ERROR с ошибкой синтаксиса SQLSTATE IM012 (ошибка в синтаксисе ключевого слова драйвера), за исключением случаев, когда файл .dsn недоступен для обмена и, следовательно, содержит только ключевое слово DSN .

    Если источник данных файла недоступен для обмена, Driver Manager считывает значение ключевого слова DSN и по необходимости подключается к пользователю или системному источнику данных, на который указывает недоступный источник данных. Шаги с 3 по 5 не выполняются.

  3. Строит строка подключения для драйвера. Driver строка подключения — это объединение ключевых слов, указанных в .dsn-файле, и тех, что заказаны в исходной строка подключения приложения. Правила построения строка подключения driver при пересечении ключевых слов следующие:

    • Если ключевое слово DRIVER существует в строка подключения приложения, а драйверы, указанные ключевыми словами DRIVER, не совпадают в файле .dsn и в приложении строка подключения, то информация о драйвере в файле .dsn игнорируется, и используется информация о драйвере в приложенной строка подключения. Если драйверы, указанные ключевым словом DRIVER, совпадают в .dsn файле и строка подключения приложения, то там, где все ключевые слова пересекаются, те, что указаны в приложенной строка подключения, имеют приоритет над теми, что указаны в .dsn-файле.

    • В новой строка подключения ключевое слово FILEDSN убирается.

  4. Драйвер загружается, заглядывая в запись реестра HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Driver Name>\Driver, где <Driver Name> задаётся ключевым словом DRIVER .

  5. Передаёт драйверу новую строку соединений.

Для примеров .dsn-файлов см. раздел «Подключение с использованием источников данных файлов».

Ключевое слово SAVEFILE

Если строка подключения, указанная приложением, содержит ключевое слово SAVEFILE, то Driver Manager сохраняет строка подключения в .dsn-файле. Менеджер водителя продолжает следующее:

  1. Проверяет, действительно ли имя файла .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, диалоговое окно предлагает пользователю указать, следует ли перезаписывать файл. Если нет введён, появляется диалоговое окно «Сохранение файла ».

  2. Если драйвер возвращает SQL_SUCCESS и имя файла не было пустой строкой, тогда менеджер драйверов записывает информацию о соединении, вернувшуюся в аргументе OutConnectionString , в указанный файл в формате, указанном в разделе «Connection Strings» ранее в этом разделе.

  3. Если драйвер возвращает SQL_SUCCESS, а имя файла было пустой строкой (""), то Driver Manager вызывает общее диалоговое окно File-Save с указанным hwnd и записывает информацию о соединении, вернувшуюся в OutConnectionString , в файл, указанный в File-Save общем диалоговом окне, с форматом, указанным в разделе "Connection Strings" ранее в этом разделе.

  4. Если драйвер возвращает SQL_SUCCESS, он возвращает аргумент OutConnectionString, содержащий строка подключения, в приложение.

  5. Если драйвер возвращает SQL_SUCCESS_WITH_INFO или SQL_ERROR, то менеджер драйверов возвращает SQLSTATE приложению.

Руководство для водителей

Драйвер проверяет, содержит ли строка подключения, переданная менеджером драйверов, ключевое слово DSN или DRIVER. Если строка подключения содержит ключевое слово DRIVER, драйвер не может получить информацию о источнике данных из системных данных. Если строка подключения содержит ключевое слово DSN или не содержит ни DSN, ни DRIVER, драйвер может получить информацию о источнике данных из системных данных следующим образом:

  1. Если строка подключения содержит ключевое слово DSN, драйвер получает информацию для указанного источника данных.

  2. Если строка подключения не содержит ключевого слова 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.

Если пользователь отменяет диалоговое окно, представленное Driver Manager или драйвером, SQLDriverConnect возвращает SQL_NO_DATA.

Для информации о том, как менеджер драйверов и драйвер взаимодействуют в процессе подключения, см. SQLConnect Function.

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

Подключение при включении пула соединений

Пул соединений позволяет приложению повторно использовать уже созданное соединение. При вызове SQLDriverConnect менеджер драйверов пытается создать соединение, используя соединение, являющееся пулом соединений в среде, предназначенной для пула соединений. Для получения дополнительной информации о пуле соединений см. SQLConnect Function.

Приложение может задать SQL_ATTR_RESET_CONNECTION перед вызовом SQLDisconnect на соединении, где включено пулирование. Дополнительные сведения см. в разделе "Функция SQLSetConnectAttr".

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

  • Обработка пула соединений не выполняется, когда ключевое слово SAVEFILE указано в строка подключения.

  • Если объединение соединений включено, SQLDriverConnect можно вызвать только с аргументом DriverCompletion значения SQL_DRIVER_NOPROMPT; если SQLDriverConnect вызван вместе с любым другим DriverCompletion, будет возвращен SQLSTATE HY110 (Invalid driver completion).

Атрибуты подключения

Атрибут 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

См. также

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

  • Last updated on