Функция 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 Error Description
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

См. также

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