Функция 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, если не указано иное.

Аргумент 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 запрос обзора строка подключения должен содержать ключевое слово 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".

Пример кода

В следующем примере приложение многократно вызывает 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);  
}  

Связанные функции

См. также

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