Функция SQLBrowseConnect
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ODBC
Сводка
SQLBrowseConnect поддерживает итеративный метод обнаружения и перечисления атрибутов и значений атрибутов, необходимых для подключения к источнику данных. Каждый вызов SQLBrowseConnect возвращает последовательные уровни атрибутов и значений атрибутов. После перечисления всех уровней подключение к источнику данных завершается, а полный строка подключения возвращается SQLBrowseConnect. Возвращаемый код SQL_SUCCESS или SQL_SUCCESS_WITH_INFO указывает, что указаны все сведения о подключении, а приложение теперь подключено к источнику данных.
Синтаксис
SQLRETURN SQLBrowseConnect(
SQLHDBC ConnectionHandle,
SQLCHAR * InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR * OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT * StringLength2Ptr);
Аргументы
ConnectionHandle
[Input] Дескриптор подключения
InConnectionString
[Входные данные] Обзор запроса строка подключения (см. раздел "Аргумент InConnectionString" в разделе "Комментарии").
StringLength1
[Входные данные] Длина *InConnectionString в символах.
OutConnectionString
[Выходные данные] Указатель на буфер символов, в котором возвращается результат обзора строка подключения (см. раздел "Аргумент OutConnectionString" в разделе "Комментарии").
Если OutConnectionString имеет значение NULL, StringLength2Ptr по-прежнему возвращает общее количество символов (за исключением символа завершения null для символов), доступное для возврата в буфер, на который указывает OutConnectionString.
BufferLength
[Входные данные] Длина в символах буфера *OutConnectionString .
StringLength2Ptr
[Выходные данные] Общее количество символов (за исключением завершения null), доступное для возврата в *OutConnectionString. Если число символов, доступных для возврата, больше или равно BufferLength, строка подключения в *OutConnectionString усечен до BufferLength минус длина символа завершения null.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_ERROR, SQL_INVALID_HANDLE или SQL_STILL_EXECUTING.
Диагностика
Когда SQLBrowseConnect возвращает SQL_ERROR, SQL_SUCCESS_WITH_INFO или SQL_NEED_DATA, можно получить связанное значение SQLSTATE путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и дескриптора ConnectionHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLBrowseConnect и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01004 | Строковые данные, усеченные справа | Буфер *OutConnectionString был недостаточно велик, чтобы вернуть весь результат обзора строка подключения, поэтому строка была усечена. Буфер *StringLength2Ptr содержит длину ненадежного результата обзора строка подключения. (Функция возвращает SQL_NEED_DATA.) |
| 01S00 | Недопустимый атрибут строка подключения | Недопустимое ключевое слово атрибута было указано в запросе обзора строка подключения (InConnectionString). (Функция возвращает SQL_NEED_DATA.) Ключевое слово атрибута было указано в запросе обзора строка подключения (InConnectionString), который не применяется к текущему уровню подключения. (Функция возвращает SQL_NEED_DATA.) |
| 01S02 | Изменено значение | Драйвер не поддерживал указанное значение аргумента ValuePtr в SQLSetConnectAttr и заменил аналогичное значение. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 08001 | Клиенту не удается установить подключение | Драйверу не удалось установить подключение к источнику данных. |
| 08002 | Имя подключения, используемое | (DM) Указанное подключение уже использовалось для установления соединения с источником данных, и подключение было открыто. |
| 08004 | Сервер отклонил подключение | Источник данных отклонил создание подключения по определенным причинам реализации. |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому драйвер пытался подключиться до завершения обработки функции. |
| 28000 | Недопустимая спецификация авторизации | Идентификатор пользователя или строка авторизации или оба, указанные в запросе обзора строка подключения (InConnectionString), нарушили ограничения, определенные источником данных. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | (DM) Диспетчер драйверов не смог выделить память, необходимую для поддержки выполнения или завершения функции. Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная операция была отменена путем вызова функции SQLCancelHandle. Затем исходная функция снова была вызвана в ConnectionHandle. Операция была отменена путем вызова SQLCancelHandle в ConnectionHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) асинхронно выполняющаяся функция (не эта) была вызвана для ConnectionHandle и по-прежнему выполнялась при вызове этой функции. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY090 | Недопустимая длина строки или буфера | (DM) Значение, указанное для аргумента StringLength1 , было меньше 0 и не равно SQL_NTS. (DM) Значение, указанное для аргумента BufferLength , было меньше 0. |
| HY114 | Драйвер не поддерживает асинхронное выполнение асинхронной функции уровня подключения | (DM) Приложение включило асинхронную операцию в дескрипторе подключения перед подключением. Однако драйвер не поддерживает асинхронную операцию в дескрипторе подключения. |
| 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) Во время SQLBrowseConnect диспетчер драйверов назвал функцию SQLAllocHandle драйвера с дескриптором SQL_HANDLE_ENV, а драйвер вернул ошибку. |
| IM005 | Сбой sqlAllocHandle драйвера на SQL_HANDLE_DBC | (DM) Во время SQLBrowseConnect диспетчер драйверов назвал функцию SQLAllocHandle драйвера с дескриптором SQL_HANDLE_DBC, а драйвер вернул ошибку. |
| IM006 | Ошибка SQLSetConnectAttr драйвера | (DM) Во время SQLBrowseConnect диспетчер драйверов назвал функцию SQLSetConnectAttr драйвера, а драйвер вернул ошибку. |
| IM009 | Не удалось загрузить библиотеку DLL перевода | Драйверу не удалось загрузить библиотеку DLL перевода, указанную для источника данных или подключения. |
| IM010 | Слишком длинное имя источника данных | (DM) Значение атрибута для ключевого слова DSN превышает SQL_MAX_DSN_LENGTH символов. |
| IM011 | Слишком длинное имя драйвера | (DM) Значение атрибута для ключевого слова DRIVER было длиннее 255 символов. |
| IM012 | Ошибка синтаксиса ключевого слова DRIVER | (DM) Пара "ключевое слово-значение" для ключевого слова DRIVER содержит синтаксическую ошибку. |
| IM014 | Указанный DSN содержит несоответствие архитектуры между драйвером и приложением | (DM) 32-разрядное приложение использует DSN, подключающееся к 64-разрядному драйверу; или наоборот. |
| IM017 | Опрос отключен в асинхронном режиме уведомлений | При использовании модели уведомлений опрос отключается. |
| IM018 | SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. | Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
| S1118 | Драйвер не поддерживает асинхронное уведомление | Если драйвер не поддерживает асинхронное уведомление, нельзя задать SQL_ATTR_ASYNC_DBC_EVENT или SQL_ATTR_ASYNC_DBC_RETCODE_PTR. |
Аргумент InConnectionString
Запрос обзора строка подключения имеет следующий синтаксис:
connection-string ::= attribute[;] | строка подключения атрибута;;
атрибут ::= attribute-keyword=attribute-valueDRIVER= | [{]attribute-value[}]
attribute-keyword ::= DSN | | UIDPWD | driver-defined-attribute-keyword
атрибут-значение ::= символьная строка
идентификатор driver-defined-attribute-keyword ::=
где строка символов имеет ноль или больше символов; идентификатор имеет один или несколько символов; атрибут-ключевое слово не учитывает регистр; Атрибут-значение может быть чувствительным к регистру, и значение ключевого слова DSN не состоит исключительно из пустых. Из-за строка подключения и грамматики файла инициализации, ключевых слов и значений атрибутов, содержащих символы []{}(),?? *=!@ следует избежать. Из-за грамматики в системной информации ключевые слова и имена источников данных не могут содержать символ обратной косой черты (\). Для ODBC 2.X driver, фигурные скобки требуются вокруг значения атрибута для ключевого слова DRIVER.
Если в запросе обзора повторяются ключевые слова строка подключения, драйвер использует значение, связанное с первым вхождением ключевого слова. Если ключевые слова DSN и DRIVER включены в один запрос на просмотр строка подключения, диспетчер драйверов и драйвер используют любое ключевое слово.
Сведения о том, как приложение выбирает источник данных или драйвер, см. в разделе "Выбор источника данных" или "Драйвер".
Аргумент OutConnectionString
Результат обзора строка подключения — это список атрибутов подключения. Атрибут подключения состоит из ключевого слова атрибута и соответствующего значения атрибута. Результат обзора строка подключения имеет следующий синтаксис:
connection-string ::= attribute[;] | строка подключения атрибута ;
атрибут ::= [*]attribute-keyword-value=
attribute-keyword ::= ODBC-attribute-keyword | driver-defined-attribute-keyword
ODBC-attribute-keyword = {UID | PWD}[:localized-identifier] driver-defined-attribute-keyword ::= identifier[:localized-identifier] attribute-value ::= { attribute-value-list } | ? (фигурные скобки являются литеральными; они возвращаются драйвером.)
attribute-value-list ::= character-string [:локализованная строка символов] | символьная строка [:локализованная строка символа] , атрибут-value-list
где строка символов и локализованная символьная строка имеют ноль или более символов; идентификатор и локализованный идентификатор имеют один или несколько символов; атрибут-ключевое слово не учитывает регистр. Значение атрибута может быть учитывает регистр. Из-за строка подключения и инициализации грамматики, ключевых слов, локализованных идентификаторов и значений атрибутов, содержащих символы []{}(),?? *=!@ следует избежать. Из-за грамматики в системной информации ключевые слова и имена источников данных не могут содержать символ обратной косой черты (\).
Синтаксис результатов обзора строка подключения используется в соответствии со следующими семантические правила:
Если звездочка (*) предшествует ключевому слову атрибута, атрибут необязателен и может быть опущен в следующем вызове SQLBrowseConnect.
Ключевые слова атрибутов UID и PWD имеют то же значение, что и в SQLDriverConnect.
Определяемый драйвером атрибут-ключевое слово называет тип атрибута, для которого может быть предоставлено значение атрибута. Например, это может быть SERVER, DATABASE, HOST или СУБД.
Ключевые слова ODBC-attribute-keywords и driver-defined-attribute-keywords включают локализованную или пользовательскую версию ключевого слова. Это может использоваться приложениями в качестве метки в диалоговом окне. Однако при передаче строки запроса обзора драйверу необходимо использовать только идентификатор UID, PWD или идентификатор.
{attribute-value-list} — это перечисление фактических значений, допустимых для соответствующего ключевого слова атрибута. Обратите внимание, что фигурные скобки ({}) не указывают список вариантов выбора; они возвращаются водителем. Например, это может быть список имен серверов или список имен баз данных.
Если атрибут-значение является одним вопросительным знаком (?), одно значение соответствует ключевому слову атрибута. Например, UID=JohnS; PWD=Sesame.
Каждый вызов SQLBrowseConnect возвращает только сведения, необходимые для удовлетворения следующего уровня процесса подключения. Драйвер связывает сведения о состоянии с дескриптором подключения, чтобы контекст всегда можно было определить при каждом вызове.
Использование SQLBrowseConnect
ДЛЯ SQLBrowseConnect требуется выделенное подключение. Диспетчер драйверов загружает драйвер, указанный в или соответствующий имени источника данных, указанному в первоначальном запросе на просмотр строка подключения; сведения о том, когда это происходит, см. в разделе "Комментарии" в функции SQLConnect. Драйвер может установить подключение к источнику данных во время просмотра. Если SQLBrowseConnect возвращает SQL_ERROR, выдающиеся подключения завершаются и подключение возвращается в несоединяемое состояние.
Примечание.
SQLBrowseConnect не поддерживает пул подключений. Если sqlBrowseConnect вызывается во время включения пула подключений, возвращается SQLSTATE HY000 (общая ошибка).
При первом вызове SQLBrowseConnect запрос обзора строка подключения должен содержать ключевое слово DSN или ключевое слово DRIVER. Если запрос обзора строка подключения содержит ключевое слово DSN, диспетчер драйверов находит соответствующую спецификацию источника данных в системной информации:
Если диспетчер драйверов находит соответствующую спецификацию источника данных, она загружает связанную библиотеку DLL драйвера; Драйвер может получить сведения об источнике данных из системных сведений.
Если диспетчер драйверов не может найти соответствующую спецификацию источника данных, он находит спецификацию источника данных по умолчанию и загружает связанную библиотеку DLL драйвера; Драйвер может получить сведения об источнике данных по умолчанию из системных сведений. Значение DEFAULT передается драйверу для dsN.
Если диспетчер драйверов не может найти соответствующую спецификацию источника данных и нет спецификации источника данных по умолчанию, он возвращает SQL_ERROR с SQLSTATE IM002 (источник данных не найден и не указан драйвер по умолчанию).
Если запрос обзора строка подключения содержит ключевое слово DRIVER, диспетчер драйверов загружает указанный драйвер; он не пытается найти источник данных в системной информации. Так как ключевое слово DRIVER не использует сведения из системных сведений, драйвер должен определить достаточно ключевых слов, чтобы драйвер смог подключиться к источнику данных, используя только сведения в запросе обзора строка подключения.
При каждом вызове SQLBrowseConnect приложение указывает значения атрибута подключения в запросе обзора строка подключения. Драйвер возвращает последовательные уровни атрибутов и значений атрибутов в результатах обзора строка подключения; он возвращает SQL_NEED_DATA, если в строка подключения запросе обзора еще не перечислены атрибуты подключения. Приложение использует содержимое результата обзора строка подключения для создания запроса обзора строка подключения для следующего вызова SQLBrowseConnect. Все обязательные атрибуты (не предшествующие звездочку в аргументе OutConnectionString ) должны быть включены в следующий вызов SQLBrowseConnect. Обратите внимание, что приложение не может использовать содержимое предыдущих строка подключения результатов обзора при создании текущего запроса обзора строка подключения; то есть не может указывать разные значения атрибутов, заданных на предыдущих уровнях.
После перечисления всех уровней подключения и связанных с ними атрибутов драйвер возвращает SQL_SUCCESS, подключение к источнику данных завершено, а полный строка подключения возвращается приложению. Строка подключения подходит для использования в сочетании с SQLDriverConnect с параметром SQL_DRIVER_NOPROMPT для установления другого подключения. Полный строка подключения нельзя использовать в другом вызове SQLBrowseConnect, однако, если SQLBrowseConnect был вызван еще раз, все последовательности вызовов придется повторяться.
SQLBrowseConnect также возвращает SQL_NEED_DATA, если во время обзора возможны восстановление, нефатальные ошибки, например недопустимый пароль или ключевое слово атрибута, предоставленное приложением. Когда возвращается SQL_NEED_DATA и результат обзора строка подключения не изменяется, произошла ошибка, и приложение может вызвать SQLGetDiagRec, чтобы вернуть SQLSTATE для ошибок во время просмотра. Это позволяет приложению исправить атрибут и продолжить обзор.
Приложение может завершить процесс просмотра в любое время путем вызова SQLDisconnect. Драйвер завершит все невыполненные подключения и возвратит подключение к несоединяемому состоянию.
Если в дескрипторе подключения включены асинхронные операции, SQLBrowseConnect также может вернуть SQL_STILL_EXECUTING. При возвращении SQL_NEED_DATA приложение должно использовать SQLDisconnect для отмены процесса просмотра. Если SQLBrowseConnect возвращает SQL_STILL_EXECUTING, приложение должно использовать SQLCancelHandle для отмены операции. Вызов SQLCancelHandle после возврата функции SQL_NEED_DATA не действует.
Дополнительные сведения см. в разделе "Подключение с помощью SQLBrowseConnect".
Если драйвер поддерживает SQLBrowseConnect, раздел ключевого слова драйвера в системной информации для драйвера должен содержать ключевое слово ConnectFunctions с третьим символом, равным "Y".
Пример кода
Примечание.
Если вы подключаетесь к поставщику источников данных, который поддерживает проверка подлинности Windows, следует указать Trusted_Connection=yes вместо идентификатора пользователя и пароля в строка подключения.
В следующем примере приложение многократно вызывает SQLBrowseConnect . Каждый раз, когда SQLBrowseConnect возвращает SQL_NEED_DATA, он передает сведения о данных, необходимых в *OutConnectionString. Приложение передает OutConnectionString в свою подпрограмму GetUserInput (не отображается). GetUserInput анализирует сведения, создает и отображает диалоговое окно и возвращает сведения, введенные пользователем в *InConnectionString. Приложение передает данные пользователя драйверу в следующем вызове SQLBrowseConnect. После того как приложение предоставило все необходимые сведения для подключения драйвера к источнику данных, SQLBrowseConnect возвращает SQL_SUCCESS и приложение продолжается.
Более подробный пример подключения к драйверу SQL Server путем вызова SQLBrowseConnect см . в примере просмотра SQL Server.
Например, чтобы подключиться к источнику данных Sales, могут возникнуть следующие действия. Во-первых, приложение передает следующую строку в SQLBrowseConnect:
"DSN=Sales"
Диспетчер драйверов загружает драйвер, связанный с источником данных Sales. Затем он вызывает функцию SQLBrowseConnect драйвера с теми же аргументами, которые он получил от приложения. Драйвер возвращает следующую строку в *OutConnectionString:
"HOST:Server={red,blue,green};UID:ID=?;PWD:Password=?"
Приложение передает эту строку в подпрограмму GetUserInput , которая создает диалоговое окно, которое просит пользователя выбрать красный, синий или зеленый сервер, а также ввести идентификатор пользователя и пароль. Подпрограмма передает следующие данные, указанные пользователем, обратно в *InConnectionString, который приложение передает в SQLBrowseConnect:
"HOST=red;UID=Smith;PWD=Sesame"
SQLBrowseConnect использует эту информацию для подключения к красному серверу в качестве Смита с паролем Sesame, а затем возвращает следующую строку в *OutConnectionString:
"*DATABASE:Database={SalesEmployees,SalesGoals,SalesOrders}"
Приложение передает эту строку в подпрограмму GetUserInput , которая создает диалоговое окно, которое просит пользователя выбрать базу данных. Пользователь выбирает empdata, а приложение вызывает SQLBrowseConnect окончательное время с этой строкой:
"DATABASE=SalesOrders"
Это окончательный фрагмент информации, которую драйвер должен подключиться к источнику данных; SQLBrowseConnect возвращает SQL_SUCCESS, а *OutConnectionString содержит завершенные строка подключения:
// SQLBrowseConnect_Function.cpp
// compile with: odbc32.lib
#include <windows.h>
#include <sqltypes.h>
#include <sqlext.h>
#define BRWS_LEN 100
SQLHENV henv;
SQLHDBC hdbc;
SQLHSTMT hstmt;
SQLRETURN retcode;
SQLCHAR szConnStrIn[BRWS_LEN], szConnStrOut[BRWS_LEN];
SQLSMALLINT cbConnStrOut;
void GetUserInput(SQLCHAR * szConnStrOut, SQLCHAR * szConnStrIn) {}
int main() {
// Allocate the environment handle.
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
// Set the version environment attribute.
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
// Allocate the connection handle.
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
// Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA
// (pass data source name the first time). If SQL_NEED_DATA is returned, call GetUserInput
// (not shown) to build a dialog from the values in szConnStrOut. The user-supplied values
// are returned in szConnStrIn, which is passed in the next call to SQLBrowseConnect.
strcpy_s((char*)szConnStrIn, _countof(szConnStrIn), "DSN=Sales");
do {
retcode = SQLBrowseConnect(hdbc, szConnStrIn, SQL_NTS,
szConnStrOut, BRWS_LEN, &cbConnStrOut);
if (retcode == SQL_NEED_DATA)
GetUserInput(szConnStrOut, szConnStrIn);
} while (retcode == SQL_NEED_DATA);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){
// Allocate the statement handle.
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)
// Process data after successful connection
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
SQLDisconnect(hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
}
}
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
Связанные функции
| Сведения | Смотрите |
|---|---|
| Выделение дескриптора подключения | Функция SQLAllocHandle |
| подключение к источнику данных; | Функция SQLConnect |
| Отключение от источника данных | Функция SQLDisconnect |
| Подключение к источнику данных с помощью строка подключения или диалогового окна | Функция SQLDriverConnect |
| Возврат описания и атрибуты драйвера | Функция SQLDrivers |
| Освобождение дескриптора подключения | Функция SQLFreeHandle |