Функция SQLDriverConnect

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

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

Синтаксис

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

Аргументы

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

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

InConnectionString
[Входные данные] Полная строка подключения (см. синтаксис в "Комментарии"), частичная строка подключения или пустая строка.

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

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

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

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

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

DriverCompletion
[Входные данные] Флаг, указывающий, должен ли диспетчер драйверов или драйвер запрашивать дополнительные сведения о подключении:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED или SQL_DRIVER_NOPROMPT.

(Дополнительные сведения см. в разделе "Комментарии".")

Возвраты

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

Диагностика

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

Комментарии

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

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

empty-string ::=attribute ::= attribute-keyword= attribute-value | DRIVER=[{]attribute-value[}]

атрибут-ключевое слово ::= DSN | UID | PWD | ключевое слово driver-defined-attribute

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

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

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

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

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

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

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

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

Сведения о том, как приложение выбирает источник данных или драйвер, см. в разделе "Выбор источника данных" или "Драйвер".

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

Ключевые слова FILEDSN и DSN являются взаимоисключающими: любое ключевое слово, которое отображается первым, и тот, который отображается вторым, игнорируется. Ключевые слова FILEDSN и DRIVER , с другой стороны, не являются взаимоисключающими. Если какое-либо ключевое слово отображается в строке подключения с ПОМОЩЬЮ FILESN, то используется значение атрибута ключевого слова в строке подключения, а не значение атрибута того же ключевого слова в DSN-файле.

Если используется ключевое слово FILEDSN , ключевые слова, указанные в DSN-файле, используются для создания строки подключения. (Дополнительные сведения см. в разделе "Источники данных файлов" далее в этом разделе.) Ключевое слово UID является необязательным; файл .dsn может быть создан только с ключевым словом DRIVER . Ключевое слово PWD не хранится в DSN-файле. Каталог по умолчанию для сохранения и загрузки DSN-файла будет сочетанием пути, указанного CommonFileDir в HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion и ODBC\DataSources. (Если CommonFileDir были "C:\Program Files\Common Files", каталог по умолчанию будет "C:\Program Files\Common Files\ODBC\Data Sources".

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

Рекомендации по диспетчеру драйверов

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

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

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

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

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

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

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

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

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

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

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

Файловые источники данных

Если строка подключения, указанная приложением в вызове SQLDriverConnect, содержит ключевое слово FILEDSN, и это ключевое слово не заменяется ключевым словом DSN или DRIVER, диспетчер драйверов создает строку подключения, используя сведения в 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 .

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

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

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

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

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

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

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

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

Если строка подключения, указанная приложением, содержит ключевое слово SAVEFILE , диспетчер драйверов сохраняет строку подключения в 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, в указанный файл с форматом, указанным в разделе "Строки подключения" выше в этом разделе.

3. Если драйвер возвращает SQL_SUCCESS, а имя файла было пустой строкой (""), диспетчер драйверов вызывает общее диалоговое окно "Сохранить файл" с заданным hwnd и записывает сведения о подключении, возвращенные в OutConnectionString, в файл, указанный в общем диалоговом окне "Сохранить файл" с форматом, указанным в разделе "Строки подключения" ранее в этом разделе.

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.

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

Сведения о взаимодействии диспетчера драйверов и драйвера во время процесса подключения см. в разделе "Функция SQLConnect".

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

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

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

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

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

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

• Если пул подключений включен, sqlDriverConnect можно вызывать только с аргументом DriverCompletion SQL_DRIVER_NOPROMPT; если SQLDriverConnect вызывается с любым другим драйверомCompletion, функция SQLSTATE HY110 (недопустимое завершение драйвера) будет возвращена.

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

Атрибут подключения SQL_ATTR_LOGIN_TIMEOUT, заданный с помощью SQLSetConnectAttr, определяет количество секунд, ожидающих завершения запроса входа с успешным подключением драйвером перед возвращением в приложение. Если пользователю будет предложено завершить строку подключения, период ожидания для каждого запроса входа начинается при запуске драйвера процесса подключения.

Драйвер открывает подключение в режиме доступа SQL_MODE_READ_WRITE по умолчанию. Чтобы задать режим доступа для SQL_MODE_READ_ONLY, приложение должно вызвать SQLSetConnectAttr с атрибутом SQL_ATTR_ACCESS_MODE перед вызовом SQLDriverConnect.

Если библиотека перевода по умолчанию указана в системной информации для источника данных, драйвер загружает его. Можно загрузить другую библиотеку перевода, вызвав SQLSetConnectAttr с атрибутом SQL_ATTR_TRANSLATE_LIB. Параметр перевода можно указать путем вызова SQLSetConnectAttr с параметром SQL_ATTR_TRANSLATE_OPTION.

Дополнительные сведения см. в разделе "Подключение с помощью SQLDriverConnect".

// SQLDriverConnect_ref.cpp  
// compile with: odbc32.lib user32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR OutConnStr[255];  
   SQLSMALLINT OutConnStrLen;  
  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            retcode = SQLDriverConnect( // SQL_NULL_HDBC  
               hdbc,   
               desktopHandle,   
               (SQLCHAR*)"driver=SQL Server",   
               _countof("driver=SQL Server"),  
               OutConnStr,  
               255,   
               &OutConnStrLen,  
               SQL_DRIVER_PROMPT );  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {                 
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}  

См. также пример программы ODBC.

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

См. также

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