4 Функции в MyODBC API

Эта глава руководства описывает каждую функцию (синтаксис, параметры и использование). Каждая функция определена как функция языка программирования C. Описания включают следующее:

ОБРАТИТЕ ВНИМАНИЕ: вообще все функции API возвращают следующие коды возврата:

Функции работы с набором результатов, например, SQLFetch, SQLFetchScroll, SQLGetData также умеют возвращать значения SQL_NO_DATA или SQL_NO_DATA_FOUND. А функции SQLExecute, SQLExecDirect и SQLParamData моугт возвращать SQL_NEED_DATA как код возврата при поставке длинных данных порциями.

4.1 Обзор функций MyODBC

Прикладная программа может вызывать функцию SQLGetInfo, чтобы получить информацию соответствия относительно MyODBC. Чтобы получать информацию относительно поддержки специфической функции в драйвере, прикладная программа может вызывать SQLGetFunctions. Обратите внимание, что драйвер MyODBC 3.51 для обратной совместимости поддерживает все устаревшие функции. Имеется список MyODBC API, сгруппированый исходя из задач:

ЗадачаИмя функции MyODBCMyODBC 3.51 СоответствиеНазначение
Соединение с источником данныхSQLAllocHandleНет ДаISO 92Получает среду, подключение, инструкцию, или дескриптор.
SQLConnectДаДаISO 92 Подключается к указанному драйверу, используя имя источника данных, user ID и password.
SQLDriverConnectДаДаODBC Подключается к указанному драферу, используя строку подключения или запрос, чтобы Driver Manager отобразил диалоговое окно подключения.
SQLAllocEnvДаДаУстарела Получает дескриптор среды, распределенный из драйвера.
SQLAllocConnectДаДаУстарела Получает дескриптор подключения.
Получение информации относительно драйвера и источника данных SQLDataSourcesНетНетISO 92Возвращает список доступных источников данных, обработанных Driver Manager.
SQLDriversНетНетODBC Возвращает список установленных драйверов и их атрибутов, обработанных Driver Manager
SQLGetInfoДаДаISO 92 Возвращает информацию относительно специфического драйвера и источника данных.
SQLGetFunctionsДаДаISO 92 Возвращает перечень функций, поддерживаемых драйвером.
SQLGetTypeInfoДаДаISO 92 Возвращает информацию относительно поддерживаемых типов данных.
Установка и получение атрибутов драйвера.SQLSetConnectAttr НетДаISO 92Устанавливает атрибуты связи.
SQLGetConnectAttrНетДаISO 92 Возвращает значение атрибута подключения.
SQLSetConnectOptionДаДаУстарела Устанавливает опции подключения.
SQLGetConnectOptionДаДаУстарела Возвращает значение опции подключения.
SQLSetEnvAttrНетДаISO 92 Устанавливает атрибут среды.
SQLGetEnvAttrНетДаISO 92 Возвращает значение атрибута среды.
SQLSetStmtAttrНетДаISO 92 Устанавливает операторный атрибут.
SQLGetStmtAttrНетДаISO 92 Возвращает значение операторного атрибута.
SQLSetStmtOptionДаДаУстарела Устанавливает операторную опцию.
SQLGetStmtOptionДаДаУстарела Возвращает значение операторной опции.
Подготовка SQL-запросов.SQLAllocStmtДаДа УстарелаРаспределяет операторный дескриптор.
SQLPrepareДаДаISO 92 Готовит инструкцию SQL для более позднего выполнения.
SQLBindParameterДаДаODBC Назначает память параметру в инструкции SQL.
SQLGetCursorNameДаДаISO 92 Возвращает имя курсора, связанное с операторным дескриптором.
SQLSetCursorNameДаДаISO 92 Определяет имя курсора.
SQLSetScrollOptionsДаДаODBC Устанавливает параметры, управляющие поведением курсора.
Передача запросов на рассмотрениеSQLExecuteДа ДаISO 92Выполняет подготовленную инструкцию.
SQLExecDirectДаДаISO 92 Выполняет инструкцию SQL.
SQLNativeSqlДаДаODBC Возвращает текст инструкции SQL для трансляции драйверу.
SQLDescribeParamДаДаODBC Возвращает описание для специфического параметра в инструкции.
SQLNumParamsДаДаISO 92 Возвращает число параметров в инструкции.
SQLParamDataДаДаISO 92 Использован вместе с SQLPutData, чтобы обеспечить передачу данных для параметров во время выполнения (полезно для длинных значений данных).
SQLPutDataДаДаISO 92 Посылает часть или все данные для параметра (полезно для длинных значений данных).
Получение результатов и информации относительно результатов. SQLRowCountДаДаISO 92Возвращает число строк, на которые воздействует запрос типа insert, update или delete.
SQLNumResultColsДаДаISO 92 Возвращает число столбцов в наборе результатов.
SQLDescribeColДаДаISO 92 Описывает столбец в наборе результатов.
SQLColAttributeНетДаISO 92 Описывает атрибуты столбца в наборе результатов.
SQLColAttributesДаДаУстарела Описывает атрибуты столбца в наборе результатов.
SQLFetchДаДаISO 92 Возвращает много строк результата.
SQLFetchScrollНетДаISO 92 Возвращает скроллируемые строки результата.
SQLExtendedFetchДаДаУстарела Возвращает скроллируемые строки результата.
SQLSetPosДаДаODBC Устанавливает курсор внутри выбранного блока данных и позволяет прикладной программе обновить данные в rowset, модифицировать или удалять данные в наборе результатов.
SQLBulkOperationsНетДаODBC Выполняет оптовые вставки и закладки, включая update, delete и выборку по закладке.
Получение ошибок или диагностической информацииSQLError ДаДаУстарелаВозвращает дополнительную информацию состояния или ошибки.
SQLGetDiagFieldДаДаISO 92 Возвращает дополнительную информацию диагностики (одиночное поле диагностической структуры данных).
SQLGetDiagRecДаДаISO 92 Возвращает дополнительную информацию диагностики (много полей диагностической структуры данных).
Получение информации относительно системных таблиц источника данных. SQLColumnPrivilegesДаДаODBC Возвращает список столбцов и связанных привилегий для одной или нескольких таблиц.
SQLColumnsДаДаX/Open Возвращает список имен столбцов в определенных таблицах.
SQLForeignKeysДаДаODBC Возвращает список имен столбцов, которые составляют внешние ключи, если они существуют для определенной таблицы.
SQLPrimaryKeysДаДаODBC Возвращает список имен столбцов, которые составляют первичный ключ для таблицы.
SQLSpecialColumnsДаДаX/Open Возвращает информацию относительно оптимального набора столбцов, который уникально идентифицирует строку в определенной таблице, или столбцов, которые автоматически модифицируются, когда любое значение в строке модифицируется транзакцией.
SQLStatisticsДаДаISO 92 Статистика относительно одной таблицы и списка индексов, связанных с таблицей.
SQLTablePrivilegesДаДаODBC Возвращает список таблиц и привилегий, связанных с каждой таблицей.
SQLTablesДаДаX/Open Возвращает список имен таблиц, сохраненных в специфическом источнике данных.
Выполнение транзакций.SQLTransactДаДа УстарелаЗавершает или отменяет транзакцию.
SQLEndTranНетДаISO 92 Завершает или отменяет транзакцию.
Прерывание команд.SQLFreeStmtДаДа ISO 92Заканчивает обработку инструкции, отбрасывает ждущие обработки результаты и, факультативно, освобождает все ресурсы, связанные с операторным дескриптором.
SQLCloseCursorДаДаISO 92 Закрывает курсор, который был открыт на операторном дескрипторе.
SQLCancelДаДаISO 92 Отменяет инструкцию SQL.
Прерывание соединения.SQLDisconnectДаДа ISO 92Закрывает подключение.
SQLFreeHandleНетДаISO 92 Освобождает дескрипторы среды, подключения и инструкции.
SQLFreeConnectДаДаУстарела Освобождает дескриптор подключения.
SQLFreeEnvДаДаУстарела Освобождает дескриптор среды.

4.2 Отображение устаревших функций

Этот раздел описывает, как устаревшие функции отображены ODBC 3.x Driver Manager, чтобы гарантировать обратную совместимость с MyODBC 2.50. Driver Manager выполняет это отображение независимо от версии прикладной программы. Поскольку каждая функция ODBC 2.x в следующем списке отображена к соответствующей функции ODBC 3.x, драйвер MyODBC 3.51 не должен выполнять функции ODBC 2.x вообще. Но ради прикладных программ, которые работают напрямую с драйвером в обход Driver Manager MyODBC 3.51 поддерживает все функции из версий 2.x.

Следующая таблица вносит в список все дублированные функции, которые представлены в драйвере MyODBC 3.51:

Функция ODBC 2.xФункция ODBC 3.x
SQLAllocConnectSQLAllocHandle с SQL_HANDLE_DBC
SQLAllocEnvSQLAllocHandle с SQL_HANDLE_ENV
SQLAllocStmtSQLAllocHandle с SQL_HANDLE_STMT
SQLColAttributesSQLColAttribute
SQLErrorSQLGetDiagRec
SQLFreeConnectSQLFreeHandle с SQL_HANDLE_DBC
SQLFreeEnvSQLFreeHandle с SQL_HANDLE_ENV
SQLFreeStmt with SQL_DROPSQLFreeHandle с SQL_HANDLE_STMT
SQLSetConnectOptionSQLSetConnectAttr
SQLGetConnectOptionSQLGetConnectAttr
SQLSetStmtAttrSQLSetStmtAttr
SQLGetStmtAttrSQLGetStmtAttr
SQLParamOptionsSQLSetStmtAttr
SQLSetScrollOptionSQLSetStmtAttr
SQLTransactSQLEndTran

4.3 Установление подключения

4.3.1 SQLAllocHandle

SQLAllocHandle распределяет среду, подключение, инструкцию и дескриптор.

Обратите внимание, что это универсальная функция для распределения дескрипторов, которая заменяет функции SQLAllocConnect, SQLAllocEnv и SQLAllocStmt из ODBC 2.0. Чтобы позволить работать прикладным программам, вызывающим SQLAllocHandle, вызов SQLAllocHandle отображен в Driver Manager на SQLAllocConnect, SQLAllocEnv или SQLAllocStmt.

4.3.1.1 Синтаксис

SQLRETURN SQLAllocHandle(SQLSMALLINT HandleType, SQLHANDLE InputHandle, SQLHANDLE* OutputHandlePtr);

4.3.1.2 Параметры

HandleType[Input] задает тип дескриптора, который будет распределен SQLAllocHandle. Должно быть одним из следующих значений: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT или SQL_HANDLE_DESC (не поддерживается драйвером).

InputHandle[Input] задает в каком контексте новый дескриптор должен быть распределен. Если HandleType равен SQL_HANDLE_ENV, это будет SQL_NULL_HANDLE. Если HandleType равен SQL_HANDLE_DBC, это должен быть дескриптор среды, и HandleType равен SQL_HANDLE_STMT или SQL_HANDLE_DESC, это будет дескриптор подключения.

OutputHandlePtr[Output] указывает на буфер, чтобы вернуть дескриптор недавно распределенной структуры данных.

4.3.1.3 Комментарии

SQLAllocHandle используется, чтобы распределить дескрипторы для сред, подключений и инструкций, как описано в следующих разделах. Обратите внимание, что MyODBC не поддерживает описатели.

Сколько угодно дескрипторов могут быть распределены прикладной программой одновременно, если драйвер поддерживает многократные распределения. В MyODBC никакое ограничение не определено на число дескрипторов, которые могут быть распределены в любой момент времени.

Если вызов с *OutputHandlePtr определяет дескриптор, который уже определен, он будет просто переопределен.

Обратите внимание, что это является неправильным ODBC программированием! Нельзя дважды вызывать SQLAllocHandle с той же самой переменной прикладной программы, определенной для *OutputHandlePtr без того, чтобы вызвать SQLFreeHandle, чтобы освободить дескриптор перед его перераспределением. Перезапись ODBC-дескриптора таким способом может привести к противоречивому поведению или сбою.

SQLAllocHandle не устанавливает атрибут среды SQL_ATTR_ODBC_VERSION, когда вызван, чтобы распределить дескриптор среды: атрибут среды должен быть установлен прикладной программой или будет возвращена SQLSTATE HY010 (Function sequence error), когда SQLAllocHandle вызвана, чтобы распределить дескриптор подключения.

Распределение дескриптора среды:
Дескриптор среды обеспечивает доступ к глобальной информации типа имеющих силу и активных дескрипторов подключения.

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

Распределение операторного дескриптора:
Операторный дескриптор обеспечивает доступ к операторной информации, типа сообщений об ошибках, имени курсора и информации состояния для обработки инструкции SQL.

4.3.2 SQLAllocEnv

SQLAllocEnv распределяет память для дескриптора среды.

4.3.2.1 Синтаксис

SQLRETURN SQLAllocEnv(HENV* EnvironmentHandle);

4.3.2.2 Комментарии

В ODBC 3.x SQLAllocHandle заменила функцию SQLAllocEnv из ODBC 2.x.

4.3.3 SQLAllocConnect

SQLAllocConnect распределяет память для дескриптора подключения.

4.3.3.1 Синтаксис

SQLRETURN SQLAllocConnect(HENV EnvironmentHandle, HDBC* ConnectionHandle);

4.3.3.2 Комментарии

В ODBC 3.x SQLAllocHandle заменила функцию SQLAllocConnect из ODBC 2.x.

4.3.4 SQLConnect

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

4.3.4.1 Синтаксис

SQLRETURN SQLConnect(SQLHDBC ConnectionHandle, SQLCHAR* ServerName, SQLSMALLINT NameLength1, SQLCHAR* UserName, SQLSMALLINT NameLength2, SQLCHAR* Authentication, SQLSMALLINT NameLength3);

4.3.4.2 Параметры

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

ServerName[Input] имя источника данных.

NameLength1[Input] длина *ServerName.

UserName[Input] User id.

NameLength2[Input] длина *UserName.

Authentication[Input] строка авторизации (обычно это пароль).

NameLength3[Input] длина *Authentication.

4.3.4.3 Комментарии

Подробно использование данной функции описано в разделе "3.4.5 Установление подключения, используя MyODBC".

4.3.5 SQLDriverConnect

SQLDriverConnect является альтернативой SQLConnect. Это поддерживает источники данных, которые требуют большего количества информации подключения чем три параметра в SQLConnect, диалоговые окна, чтобы запросить пользователя относительно всей информации о подключении, и источники данных, которые не определены в информации системы.

SQLDriverConnect обеспечивает следующие возможности подключения:

После того, как подключение установлено, SQLDriverConnect вернет завершенную строку подключения. Прикладная программа может использовать ее для выполнения последующих запросов подключения.

4.3.5.1 Синтаксис

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

4.3.5.2 Параметры

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

WndowHandle [Input] дескриптор окна. Прикладная программа может передавать дескриптор родительского окна, если оно есть, или null, если дескриптор окна не существует.

InConnectionString [Input] полное подключение, частичная строка подключения или пустая строка.

StringLength1 [Input] длина *InConnectionString в байтах.

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

BufferLength [Input] длина буфера *OutConnectionString.

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

DriverCompletion [Input] указывает должен ли Driver Manager запросить дополнительную информацию для подключения: SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED или SQL_DRIVER_NOPROMPT.

4.3.6 SQLBrowseConnect

Не поддерживается.

4.4 Получение информации источника данных и драйвера

4.4.1 SQLDataSources

SQLDataSources возвращает информацию относительно источника данных. Эта функция выполнена исключительно в Driver Manager. Для получения большего количества информации относительно этого API обратитесь к документации на соответствующий Driver Manager.

4.4.2 SQLDrivers

SQLDrivers вносит в список описания драйверов и ключевые слова атрибутов драйверов. Эта функция выполнена исключительно Driver Manager. Для получения большего количества информации относительно этого API обратитесь к документации на соответствующий Driver Manager.

4.4.3 SQLGetInfo

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

4.4.3.1 Синтаксис

SQLRETURN SQLGetInfo(SQLHDBC ConnectionHandle, SQLUSMALLINT InfoType, SQLPOINTER InfoValuePtr, SQLSMALLINT BufferLength, SQLSMALLINT* StringLengthPtr);

4.4.3.2 Параметры

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

InfoType [Input] тип информации, описанной в разделе комментариев.

InfoValuePtr [Output] указатель на буфер, предназначенный чтобы возвращать информацию. В зависимости от запрошенного InfoType, возвращенная информация будет одним из следующего: символьная строка с нулевым символом в конце, значение SQLUSMALLINT, битовая маска SQLUINTEGER, флажок (параметр) SQLUINTEGER или двоичное значение SQLUINTEGER.

Если параметр InfoType равен SQL_DRIVER_HDESC или SQL_DRIVER_HSTMT, параметр InfoValuePtr является вводом и выводом.

BufferLength [Input] длина буфера *InfoValuePtr. Если значение в *InfoValuePtr не является символьной строкой, или InfoValuePtr представляет собой null, параметр BufferLength игнорируется. Драйвер принимает, что размер *InfoValuePtr равен SQLUSMALLINT или SQLUINTEGER, исходя из InfoType. Если *InfoValuePtr является строкой в формате Unicode (при вызове SQLGetInfoW), параметр BufferLength должен быть четным числом, если это не так, будет возвращена ошибка SQLSTATE HY090 (Invalid string or buffer length).

StringLengthPtr [Output] указатель на буфер предназначенный для того, чтобы возвращать общее количество байт (за вычетом хвостовых нулей для символьных данных), доступных в *InfoValuePtr.

Для символьных данных, если число доступных байтов больше или равно BufferLength, информация в *InfoValuePtr обрезается до размера BufferLength.

Для всех других типов данных значение BufferLength игнорируется, и драйвер принимает, что размер *InfoValuePtr равен SQLUSMALLINT или SQLUINTEGER в зависимости от InfoType.

4.4.4 SQLGetFunctions

SQLGetFunctions возвращает информацию относительно того, поддерживает ли драйвер специфическую функцию ODBC.

4.4.4.1 Синтаксис

SQLRETURN SQLGetFunctions(SQLHDBC ConnectionHandle, SQLUSMALLINT FunctionId, SQLUSMALLINT* SupportedPtr);

4.4.4.2 Параметры

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

FunctionId [Input] SQL_API_ODBC3_ALL_FUNCTIONS или SQL_API_ALL_FUNCTIONS.

SQL_API_ODBC3_ALL_FUNCTIONS используется прикладными программами ODBC 3.x, чтобы определить поддержку ODBC 3.x и более ранних функций. SQL_API_ALL_FUNCTIONS используется прикладными программами ODBC 2.x, чтобы определить поддержку ODBC 2.x. Прикладная программа может передавать индивидуальный функциональный идентификатор, чтобы определить поддерживает ли драйвер функцию или нет.

SupportedPtr [Output] если FunctionId идентифицирует одиночную функцию ODBC, SupportedPtr указывает на одиночное значение SQLUSMALLINT, которое является SQL_TRUE, если определенная функция поддержана драйвером, или SQL_FALSE в противном случае.

Если FunctionId равно SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr указывает на массив SQLSMALLINT с рядом элементов, равных SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Прикладная программа ODBC 3.x может вызывать SQLGetFunctions с SQL_API_ODBC3_ALL_FUNCTIONS.

Если FunctionId равно SQL_API_ALL_FUNCTIONS, SupportedPtr указывает на массив SQLSMALLINT ровно из 100 элементов. Элемент равен SQL_TRUE, если он идентифицирует ODBC 2.x или более раннюю функцию, поддержанную драйвером. Элемент массива будет равен SQL_FALSE, если он идентифицирует функцию ODBC, не поддержанную драйвером, или не идентифицирует функцию ODBC вообще.

Массивы, возвращенные в *SupportedPtr используют индексацию, начиная с 0.

4.4.5 SQLGetTypeInfo

SQLGetTypeInfo возвращает информацию относительно типов данных, поддержанных сервером. Драйвер возвращает информацию в форме набора результатов SQL. Типы данных предназначены для использования в инструкциях Data Definition Language (DDL). Прикладные программы должны использовать имена типов, возвращенные в столбце TYPE_NAME набора результатов SQLGetTypeInfo. Для команд ALTER TABLE и CREATE TABLE возможен возврат больше, чем одной строки с тем же самым значением в DATA_TYPE столбце.

4.4.5.1 Синтаксис

SQLRETURN SQLGetTypeInfo(SQLHSTMT StatementHandle, SQLSMALLINT DataType);

4.4.5.2 Параметры

StatementHandle [Input] операторный дескриптор для набора результатов.

DataType [Input] SQL-тип данных. SQL_ALL_TYPES определяет, что должна быть возвращена информация относительно всех типов данных.

4.5 Установка и получение атрибутов драйвера

4.5.1 SQLSetConnectAttr

SQLSetConnectAttr устанавливает атрибуты, которые управляют аспектами подключений.

4.5.1.1 Синтаксис

SQLRETURN SQLSetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);

4.5.1.2 Параметры

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

Attribute [Input] атрибут для установки.

ValuePtr [Input] указатель на значение, которое будет связано с атрибутом. В зависимости от значения атрибута, ValuePtr будет 32-разрядным целым числом без знака или указателем на строку символов с нулем в конце. Обратите внимание, что если параметр Attribute представляет собой специфическое для драйвера значение, то ValuePtr может быть целым числом со знаком.

StringLength [Input] если Attribute определен в ODBC и ValuePtr указывает на строку или на двоичный буфер, этот параметр должен быть длиной *ValuePtr. Если Attribute определен в ODBC и ValuePtr является целым числом, StringLength игнорируется.

4.5.1.3 Комментарии

Имеется список атрибутов подключения, которые поддержаны драйвером MyODBC 3.51:

АтрибутСодержимое ValuePtr
SQL_ATTR_ACCESS_MODEЗначение SQLUINTEGER, и драйвер не позволяет пользователю устанавливать этот атрибут во что-либо, кроме SQL_MODE_READ_WRITE.
SQL_ATTR_ASYNC_ENABLEЗначение SQLUINTEGER, которое определяет асинхронное выполнение. Драйвер не поддерживает асинхронное выполнение, так что это можно устанавливать только в SQL_ASYNC_ENABLE_OFF.
SQL_ATTR_AUTO_IPDЗначение SQLUINTEGER только для чтения, драйвер возвращает значение по умолчанию как SQL_FALSE.
SQL_ATTR_AUTOCOMMITЗначение SQLUINTEGER, которое определяет использовать ли autocommit или ручной режим:
SQL_AUTOCOMMIT_OFF: драйвер работает в ручном режиме, и прикладная программа должна явно заверишть или отменить каждую транзакцию через SQLEndTran.
SQL_AUTOCOMMIT_ON: драйвер работает в режиме autocommit. Каждая инструкция выполняется сразу после передачи. Это значение по умолчанию. Любые открытые транзакции на подключении автоматически закрываются при смене SQL_ATTR_AUTOCOMMIT на SQL_AUTOCOMMIT_ON.
SQL_ATTR_CONNECTION_DEADЗначение SQLUINTERGER, которое указывает состояние подключения. Если это SQL_CD_TRUE, связь прервана. Если это SQL_CD_FALSE, подключение все еще активно.
SQL_ATTR_CONNECTION_TIMEOUTЗначение SQLUINTEGER, соответствующее числу секунд, которое надо ждать любой запрос на подключении перед возвратом прикладной программе. Драйвер должен возвратить SQLSTATE HYT00 (Timeout expired) по окончании тайм-аута. Если ValuePtr равно 0 (значение по умолчанию), не имеется никакого времени ожидания.
SQL_ATTR_CURRENT_CATALOGСимвольная строка, содержащая имя каталога, который нужно использовать как источник данных. Например, в SQL Server каталог является базой данных, так что драйвер посылает инструкцию USE источнику данных, где база данных определена в *ValuePtr.
SQL_ATTR_LOGIN_TIMEOUTЗначение SQLUINTEGER, соответствующее числу секунд, которое надлежит ждать при входе в систему перед возвратом прикладной программе. Значение по умолчанию зависит от драйвера. Если ValuePtr равно 0, время ожидания заблокировано, и попытка подключения будет ждать неопределенное время. Если определенное время ожидания превышает максимальное время ожидания входа в систему в источнике данных, значение из драйвера имеет приоритет, при этом драйвер вернет SQLSTATE 01S02 (Option value changed).
SQL_ATTR_METADATA_IDЗначение SQLUINTEGER, которое определяет как обрабатываются строковые параметры каталожных функций. Драйвер пока поддерживает только SQL_FALSE.
SQL_ATTR_ODBC_CURSORSЗначение SQLUINTEGER, определяющее, как Driver Manager использует библиотеку курсоров ODBC.
SQL_ATTR_PACKET_SIZEЗначение SQLUINTEGER, определяющее сетевой размер пакета в байтах.
SQL_ATTR_QUIET_MODE32-битный дескриптор окна (hwnd). Если он представляет собой null, драйвер не отображает никакие диалоговые окна. Если дескриптор окна не null, это должно быть родительским дескриптором окна прикладной программы. Это значение по умолчанию. Драйвер использует этот дескриптор, чтобы отобразить диалоговые окна.
SQL_ATTR_TRACEЗначение SQLUINTEGER, сообщающее Driver Manager, выполнять ли трассировку:
SQL_OPT_TRACE_OFF: трассировка выключена (по умолчанию),
SQL_OPT_TRACE_ON: трассировка включена.
SQL_ATTR_TRACEFILEСимвольная строка с нулевым символом в конце, содержащая имя файла трассировки.
SQL_ATTR_TRANSLATE_LIBСимвольная строка с нулевым символом в конце, содержащая имя библиотеки, содержащей функции SQLDriverToDataSource и SQLDataSourceToDriver, к которым драйвер обращается, чтобы выполнить задачи трансляции набора символов.
SQL_ATTR_TRANSLATE_OPTION32-битный параметр, который передано к трансляции DLL.
SQL_ATTR_TXN_ISOLATION32-битная маска, которая устанавливает уровень изоляции транзакции для текущего подключения. Прикладная программа должна вызвать SQLEndTran для завершения или отмены всех открытых транзакций на подключении перед вызовом SQLSetConnectAttr с этой опцией. Имеющие силу значения для ValuePtr могут быть определены, вызывая SQLGetInfo с InfoType равным SQL_TXN_ISOLATION_OPTIONS.

4.5.2 SQLGetConnectAttr

SQLGetConnectAttr возвращает текущую установку некоего атрибута подключения.

4.5.2.1 Синтаксис

SQLRETURN SQLGetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER* StringLengthPtr);

4.5.2.2 Параметры

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

Attribute [Input] интересующий атрибут.

ValuePtr [Input] указатель на память предназначенный, чтобы возвращать текущее значение атрибута.

BufferLength [Input]Если Attribute представляет собой ODBC-атрибут и ValuePtr указывает на символьную строку или двоичный буфер, этот параметр должен быть длиной *ValuePtr. Если же *ValuePtr не указатель, а целое число, BufferLength игнорируется.

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

4.5.3 SQLSetConnectOption

В ODBC 3.x SQLSetConnectAttr заменяет SQLSetConnectOption.

4.5.4 SQLGetConnectOption

В ODBC 3.x SQLGetConnectAttr заменяет SQLGetConnectOption.

4.5.5 SQLSetEnvAttr

SQLSetEnvAttr устанавливает атрибуты, которые управляют аспектами сред.

4.5.5.1 Синтаксис

SQLRETURN SQLSetEnvAttr(SQLHENV EnvironmentHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);

4.5.5.2 Параметры

EnvironmentHandle [Input] дескриптор среды.

Attribute [Input] атрибут для установки.

ValuePtr [Input] указатель на значение, которое будет связано с Attribute. В зависимости от значения Attribute, ValuePtr будет 32-битным целочисленным значением или указателем на символьную строку с нулевым символом в конце.

StringLength [Input]: если ValuePtr указатель на символьную строку с нулевым символом в конце или на двоичный буфер, здесь хранится длина *ValuePtr. Если ValuePtr представляет собой целое число, StringLength игнорируется.

4.5.5.3 Комментарии

Прикладная программа может вызывать SQLSetEnvAttr только, если никакой дескриптор подключения не распределен в текущей среде. Все атрибуты среды устанавливаются прикладной программой до обращения SQLFreeHandle. Следующая таблица вносит в список различные атрибуты среды, поддержанные драйвером:

АтрибутСодержимое ValuePtr
SQL_ATTR_CONNECTION_POOLING32-битное значение SQLUINTEGER, которое включает или отключает объединение подключений.
SQL_ATTR_CP_MATCH32-битное значение SQLUINTEGER, которое определяет как подключение выбрано из объединения подключений. Обратитесь к документации на конкретный Driver Manager за подробностями.
SQL_ATTR_ODBC_VERSION32-битное целое значение, которое определяет проявляют ли функциональные возможности поведение ODBC 2.x или ODBC 3.x. Следующие значения используются, чтобы установить значение этого атрибута: SQL_OV_ODBC3 и SQL_OV_ODBC2.
SQL_ATTR_OUTPUT_NTS 32-битное целое значение, которое определяет как драйвер возвращает строчные данные. Если SQL_TRUE, драйвер возвращает строки с нулевым символом в конце. Если SQL_FALSE, драйвер этого не делает. Сейчас драйвер поддерживает только значение по умолчанию SQL_TRUE.

4.5.6 SQLGetEnvAttr

SQLGetEnvAttr возвращает текущую установку атрибута среды.

4.5.6.1 Синтаксис

SQLRETURN SQLGetEnvAttr(SQLHENV EnvironmentHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER* StringLengthPtr);

4.5.6.2 Параметры

EnvironmentHandle [Input] дескриптор среды.

Attribute [Input] атрибут, значение которого нужно получить.

ValuePtr [Output] указатель на буфер нужный, чтобы возвращать текущее значение атрибута, определенного Attribute.

BufferLength [Input] если ValuePtr указывает на символьную строку, этот параметр должен быть длиной *ValuePtr. Если *ValuePtr целое число, BufferLength игнорируется. Если значение атрибута не строка, BufferLength не применяется.

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

4.5.7 SQLSetStmtAttr

SQLSetStmtAttr устанавливает атрибуты, связанные с инструкцией.

4.5.7.1 Синтаксис

SQLRETURN SQLSetStmtAttr(SQLHSTMT StatementHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);

4.5.7.2 Параметры

StatementHandle [Input] дескриптор инструкции.

Attribute [Input] атрибут для установки.

ValuePtr [Input] указатель на значение, которое будет связано с Attribute, ValuePtr может быть 32-битным целым числом числа без знака или указателем на символьную строку с нулевым символом в конце, двоичный буфер или определенное драйвером значение. Если параметр Attribute представляет собой специфическое для драйвера значение, ValuePtr может быть целым числом со знаком.

StringLength [Input] если Attribute определен в ODBC и ValuePtr указывает на строку или двоичный буфер, это длина *ValuePtr. Если Attribute определен в ODBC и ValuePtr целое число, StringLength игнорируется. Если Attribute определен драйвером, прикладная программа указывает характер атрибута Driver Manager: устанавливая аргумент StringLength. StringLength может иметь следующие значения:

4.5.7.3 Комментарии

Операторные атрибуты для инструкции остаются в силе, пока они не изменены другим обращением SQLSetStmtAttr.

АтрибутЗначение ValuePtr
SQL_ATTR_APP_PARAM_DESCНе поддерживается
SQL_ATTR_APP_ROW_DESCНе поддерживается
SQL_ATTR_ASYNC_ENABLEЗначение SQLUINTEGER, которое определяет выполнена ли функция асинхронно: SQL_ASYNC_ENABLE_OFF=Off (значение по умолчанию), SQL_ASYNC_ENABLE_ON=On. Драйвер не поддерживает асинхронное выполнение, так что прикладная программа может устанавливать это только в значение по умолчанию.
SQL_ATTR_CONCURRENCYЗначение SQLUINTEGER, которое определяет параллелизм курсора:
SQL_CONCUR_READ_ONLY: курсор только для чтения. Никакие модификации не позволяются.
SQL_CONCUR_LOCK: курсор использует самый низкий уровень блокировки, достаточный, чтобы гарантировать, что строка может модифицироваться.
SQL_CONCUR_ROWVER: курсор использует оптимистическое управление параллелизма.
SQL_CONCUR_VALUES: курсор использует оптимистическое управление параллелизма, сравнивая значения.
Значение по умолчанию для SQL_ATTR_CONCURRENCY равно SQL_CONCUR_READ_ONLY. Драйвер в настоящее время поддерживает только SQL_CONCUR_ROWVER.
SQL_ATTR_CURSOR_SCROLLABLEЗначение SQLUINTEGER, которое определяет уровень поддержки, который прикладная программа требует. Установка этого атрибута воздействует на последующие обращения к SQLExecDirect и SQLExecute. SQL_NONSCROLLABLE: скроллируемые курсоры не требуются на операторном дескрипторе. Если из прикладной программы вызван SQLFetchScroll на этом дескрипторе, единственное имеющее силу значение FetchOrientation: SQL_FETCH_NEXT. Это значение по умолчанию. SQL_SCROLLABLE: скроллируемые курсоры требуются на операторном дескрипторе. При вызове SQLFetchScroll прикладная программа может определять любое имеющее силу значение FetchOrientation, достигая позиционирования курсора в любом режиме.
SQL_ATTR_CURSOR_SENSITIVITYЗначение SQLUINTEGER, которое определяет делают ли курсоры на операторном дескрипторе видимыми изменения, сделанные другим курсором. Установка этого атрибута воздействует на последующие обращения к SQLExecDirect и SQLExecute. Прикладная программа может читать значение этого атрибута, чтобы получить информацию статуса. SQL_UNSPECIFIED: не определено, чем является тип курсора, и делают ли курсоры на операторном дескрипторе видимыми изменения, сделанные другим курсором. Курсоры на операторном дескрипторе могут делать видимыми изменения полностью или частично. Это значение по умолчанию. SQL_INSENSITIVE: все курсоры на операторном дескрипторе показывают набор результатов без того, чтобы отразить любые изменения, сделанные любым другим курсором. Нечувствительные курсоры только для чтения. Это соответствует статическому курсору, который имеет параллелизм и нужен только для чтения. SQL_SENSITIVE: все курсоры на операторном дескрипторе делают видимыми все изменения, сделанные другим курсором. Сейчас драйвер поддерживает только SQL_SENSITIVE и SQL_INSENSITIVE.
SQL_ATTR_CURSOR_TYPEЗначение SQLUINTEGER, которое определяет тип курсора: SQL_CURSOR_FORWARD_ONLY: курсор прокручивается только вперед. SQL_CURSOR_STATIC: данные в наборе результатов статические. SQL_CURSOR_KEYSET_DRIVEN: драйвер сохраняет и использует ключи для числа строк, определенных в инструкции SQL_ATTR_KEYSET_SIZE. SQL_CURSOR_DYNAMIC: драйвер сохраняет и использует только ключи для строк в rowset. Значение по умолчанию: SQL_CURSOR_FORWARD_ONLY. Этот атрибут не может быть определен после того, как инструкция SQL была подготовлена. Драйвер сейчас поддерживает только статический и "только вперед" типы курсора.
SQL_ATTR_KEYSET_SIZEЗначение SQLUINTEGER, который определяет число строк в ключе для управляемого ключом курсора. Поскольку драйвер не поддерживает управляемые ключами курсоры, этот атрибут игнорируется.
SQL_ATTR_MAX_LENGTHЗначение SQLUINTEGER, которое определяет максимальное количество данных, которое драйвер возвращает из символьного или двоичного столбца. Если ValuePtr меньше, чем длина доступных данных, SQLFetch или SQLGetData усекает данные и возвращает SQL_SUCCESS. Если ValuePtr равно 0 (значение по умолчанию), драйвер пытается возвращать все доступные данные.
SQL_ATTR_MAX_ROWSЗначение SQLUINTEGER, соответствующее максимальному числу строк, которое вернется прикладной программе для инструкции SELECT. Если *ValuePtr равно 0 (значение по умолчанию), драйвер возвращает все строки.
SQL_ATTR_METADATA_IDЗначение SQLUINTEGER, которое определяет как обрабатываются строчные параметры каталожной функции. Если SQL_TRUE, строчный параметр каталожной функции обрабатывается как идентификаторы. Регистр не важен. В случае SQL_FALSE параметр не обрабатывается как идентификатор. Регистр важен. Значение по умолчанию SQL_FALSE, и драйвер поддерживает только значение по умолчанию.
SQL_ATTR_NOSCANЗначение SQLUINTEGER, которое указывает должен ли драйвер просмотреть строки SQL на предмет наличия в них управляющих последовательностей. SQL_NOSCAN_OFF: драйвер просматривает строки SQL (значение по умолчанию). SQL_NOSCAN_ON: драйвер не просматривает строки SQL. Вместо этого драйвер посылает инструкцию непосредственно источнику данных.
SQL_ATTR_PARAM_BIND_OFFSET_PTRЗначение SQLUINTEGER*, которое указывает на смещение, добавленное к указателям, чтобы изменить связывание динамических параметров. Не поддерживается драйвером.
SQL_ATTR_PARAM_BIND_TYPEЗначение SQLUINTEGER, которое указывает ориентацию связывания, которую нужно использовать для динамических параметров. Это поле установлено в SQL_PARAM_BIND_BY_COLUMN (значение по умолчанию), чтобы выбрать поколоночное связывание. Чтобы выбрать строчное связывание, это поле должно быть установлено в длину структуры или в образец буфера, который будет привязан к набору динамических параметров. Эта длина должна включать место для всех связанных параметров и любого дополнения структуры или буфера, чтобы гарантировать, что, когда адрес связанного параметра будет увеличен на определенную длину, результат укажет на начало того же самого параметра в следующем наборе параметров.
SQL_ATTR_PARAM_OPERATION_PTRЗначение SQLUSMALLINT*, которое указывает на массив значений SQLUSMALLINT используемых, чтобы игнорировать параметр в течение выполнения инструкции SQL. Каждое значение установлено в SQL_PARAM_PROCEED (для параметра, который будет выполнен) или в SQL_PARAM_IGNORE (для параметра, который нужно игнорировать). Набор параметров может игнорироваться в течение обработки, устанавливая значение состояния в массиве, на который указывает SQL_DESC_ARRAY_STATUS_PTR в SQL_PARAM_IGNORE. Набор параметров обработан, если значение состояния установлено в SQL_PARAM_PROCEED или если никакие элементы в массиве не установлены. Этот операторный атрибут может быть установлен в null, тогда драйвер не возвращает значения состояния параметра. Этот атрибут может быть установлен в любое время, но новое значение не используется до следующего взоыва SQLExecDirect или SQLExecute.
SQL_ATTR_PARAM_STATUS_PTRЗначение SQLUSMALLINT*, которое указывает на массив значений SQLUSMALLINT содержащих информацию состояния для каждой строки значений параметра после обращения к SQLExecute или к SQLExecDirect. Это поле требуется только если PARAMSET_SIZE больше 1. Значения состояния могут содержать следующие значения: SQL_PARAM_SUCCESS: инструкция SQL была успешно выполнена для этого набора параметров. SQL_PARAM_SUCCESS_WITH_INFO: инструкция SQL была успешно выполнена для этого набора параметров, однако, в структуре данных диагностики доступно предупреждение. SQL_PARAM_ERROR: имелась ошибка в обработке этого набора параметров. Дополнительная информация об ошибке доступна в структуре данных диагностики. SQL_PARAM_UNUSED: набор параметров не пригодился, возможно, вследствие того, что некоторый предыдущий набор параметров вызвал ошибку, которая прервала обработку, или потому, что SQL_PARAM_IGNORE был установлен для этого набор параметров в массиве, определенном SQL_ATTR_PARAM_OPERATION_PTR. SQL_PARAM_DIAG_UNAVAILABLE: драйвер обрабатывает массивы параметров как монолитный модуль и не генерирует этот уровень информации ошибки. Этот операторный атрибут может быть установлен в null, тогда драйвер не возвращает значения состояния параметра. Этот атрибут может быть установлен в любое время, но новое значение не используется до очередного вызова SQLExecute или SQLExecDirect. Обратите внимание, что этот атрибут может воздействовать на поведение выходного параметра, выполненное драйвером.
SQL_ATTR_PARAMS_PROCESSED_PTRЗначение SQLUINTEGER*, которое указывает на буфер нужный, чтобы возвратить число наборов параметров, которые были обработаны, включая наборы ошибок. Ничего не будет возвращено, если здесь задан null.
SQL_ATTR_PARAMSET_SIZEЗначение SQLUINTEGER, которое определяет число значений для каждого параметра.
SQL_ATTR_QUERY_TIMEOUTЗначение SQLUINTEGER, соответствующее числу секунд, которое надо ждать инструкцию SQL перед возвратом прикладной программе. Если ValuePtr равен 0 (значению по умолчанию), не имеется никакого времени ожидания.
SQL_ATTR_RETRIEVE_DATAЗначение SQLUINTEGER: SQL_RD_ON: SQLFetchScroll и, в ODBC 3.x, SQLFetch получают данные после того, как устанавливают курсор в определенное расположение. Это значение по умолчанию. SQL_RD_OFF: SQLFetchScroll и, в ODBC 3.x, SQLFetch не получают данные после того, как устанавливают курсор. Драйвер поддерживает только значение по умолчанию.
SQL_ATTR_ROW_ARRAY_SIZEЗначение SQLUINTEGER, которое определяет число строк, возвращенных каждым обращением к SQLFetch или к SQLFetchScroll. Это также задает число строк в массиве закладок, используемом в оптовой операции закладки в SQLBulkOperations. Значение по умолчанию 1.
SQL_ATTR_ROW_BIND_OFFSET_PTRЗначение SQLUINTEGER*, которое указывает на смещение, добавленное к указателям, чтобы изменить связывание данных столбца.
SQL_ATTR_ROW_BIND_TYPEЗначение SQLUINTEGER, которое устанавливает ориентацию связывания, которую нужно использовать, когда SQLFetch или SQLFetchScroll обращаются к связанной инструкции. Поколоночное связывание выбрано, устанавливая значение в SQL_BIND_BY_COLUMN. Построчное связывание будет выбрано, устанавливая значение в длину структуры или в образец буфера, с которым столбцы результата будут связаны.
SQL_ATTR_ROW_NUMBERЗначение SQLUINTEGER, которое является номером текущей строки во всем наборе результатов. Если номер текущей строки не может быть определен или не имеется никакой текущей строки, драйвер возвращает 0. Этот атрибут может быть проверен обращением к SQLGetStmtAttr, но не может быть установлен через вызов SQLSetStmtAttr.
SQL_ATTR_ROW_OPERATION_PTRЗначение SQLUSMALLINT*, которое указывает на массив значений SQLUSMALLINT используемых, чтобы игнорировать строку в течение оптовой операции, использующей SQLSetPos. Каждое значение установлено в SQL_ROW_PROCEED (для строки, которая будет включена в оптовую операцию) или в SQL_ROW_IGNORE (для строки, которая будет исключена из оптовой операции). Строки не могут игнорироваться, используя этот массив в течение обращений к SQLBulkOperations. Этот операторный атрибут может быть установлен в null, когда драйвер не возвращает значения состояния строки. Этот атрибут может быть установлен в любое время, но новое значение не используется до очередного вызова SQLSetPos.
SQL_ATTR_ROW_STATUS_PTRЗначение SQLUSMALLINT*, которое указывает на массив значений SQLUSMALLINT, содержащих значения состояния строки после обращения к SQLFetch или SQLFetchScroll. Массив имеет так много элементов, сколько есть строк в rowset. Этот операторный атрибут может быть установлен в null, когда драйвер не возвращает значения состояния строки. Этот атрибут может быть установлен в любое время, но новое значение не используется до очередного вызова SQLBulkOperations, SQLFetch, SQLFetchScroll или SQLSetPos.
SQL_ATTR_ROWS_FETCHED_PTRЗначение SQLUINTEGER*, которое указывает на буфер нужный, чтобы возвратить число строк, выбранных после обращения к SQLFetch или SQLFetchScroll, число строк, на которые воздействует оптовая операция, выполняемая обращением к SQLSetPos с параметром Operation выставленным в SQL_REFRESH, или число строк, на которые воздействует оптовая операция, выполняемая SQLBulkOperations.
SQL_ATTR_SIMULATE_CURSORЗначение SQLUINTEGER, которое определяет драйверы, которые моделируют позиционные модификации и удаления и гарантируют, что такие инструкции воздействуют только на одну строку. SQL_SC_NON_UNIQUE: драйвер не гарантирует, что моделируемая инструкция будет воздействовать только на одну строку. SQL_SC_TRY_UNIQUE: драйвер пытается гарантировать, что моделируемая инструкция будет воздействовать только на одну строку. SQL_SC_UNIQUE: драйвер гарантирует, что моделируемая инструкция будет воздействовать только на одну строку.
SQL_ATTR_USE_BOOKMARKSЗакладки не поддерживаются.

4.5.8 SQLGetStmtAttr

SQLGetStmtAttr возвращает текущую установку операторного атрибута.

4.5.8.1 Синтаксис

SQLRETURN SQLGetStmtAttr(SQLHSTMT StatementHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER* StringLengthPtr);

4.5.8.2 Параметры

StatementHandle [Input] операторный дескриптор.

Attribute [Input] интересующий атрибут.

ValuePtr [Output] указатель на буфер, в который будет возвращено значение атрибута, определенного в Attribute.

BufferLength [Input] если Attribute определен в ODBC и ValuePtr указывает на символьную строку или двоичный буфер, этот параметр должен быть длиной *ValuePtr. Если Attribute определен в ODBC и *ValuePtr целое число, BufferLength игнорируется. BufferLength может иметь значения:

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

4.5.9 SQLSetStmtOption

В ODBC 3.x SQLSetStmtAttr заменяет SQLStmtOption.

4.5.10 SQLGetStmtOption

В ODBC 3.x SQLGetStmtAttr заменяет SQLCetStmtOption.

4.6 Подготовка SQL-запросов

4.6.1 SQLAllocStmt

SQLAllocStmt распределяет память для операторного дескриптора.

4.6.1.1 Синтаксис

SQLRETURN SQLAllocStmt(HDBC ConnectionHandle, HSTMT* StatementHandle);

4.6.1.2 Комментарии

В ODBC 3.x SQLAllocHandle заменяет функцию ODBC 2.x SQLAllocStmt.

4.6.2 SQLPrepare

SQLPrepare готовит команду SQL к выполнению.

4.6.2.1 Синтаксис

SQLRETURN SQLPrepare(SQLHSTMT StatementHandle, SQLCHAR* StatementText, SQLINTEGER TextLength);

4.6.2.2 Параметры

StatementHandle [Input] операторный дескриптор.

StatementText [Input] строка SQL-команды.

TextLength [Input] длина *StatementText.

4.6.3 SQLBindParameter

SQLBindParameter привязывает буфер к маркеру параметра в инструкции SQL. SQLBindParameter поддерживает связывание к Unicode-C типу данных, даже если основной драйвер не поддерживает Unicode-данные.

4.6.3.1 Синтаксис

SQLRETURN SQLBindParameter(SQLHSTMT StatementHandle, SQLUSMALLINT ParameterNumber, SQLSMALLINT InputOutputType, SQLSMALLINT ValueType, SQLSMALLINT ParameterType, SQLUINTEGER ColumnSize, SQLSMALLINT DecimalDigits, SQLPOINTER ParameterValuePtr, SQLINTEGER BufferLength, SQLINTEGER* StrLen_or_IndPtr);

4.6.3.2 Параметры

StatementHandle [Input] операторный дескриптор.

ParameterNumber [Input] номер параметра, упорядоченный последовательно в увеличивающемся порядке, начинающемся с 1.

InputOutputType [Input] тип параметра.

ValueType [Input] тип данных C для параметра.

ParameterType [Input] SQL-тип параметра.

ColumnSize [Input] размер столбца или выражения, соответствующего маркеру параметра.

DecimalDigits [Input] десятичные цифры столбца или выражения соответствующего маркеру параметра.

ParameterValuePtr [Deferred Input] указатель на буфер для данных параметра.

BufferLength [Input/Output] длина буфера ParameterValuePtr в байтах.

StrLen_or_IndPtr [Deferred Input] указатель на буфер для длины параметра.

4.6.4 SQLGetCursorName

SQLGetCursorName возвращает имя курсора, связанного с определенной инструкцией.

4.6.4.1 Синтаксис

SQLRETURN SQLGetCursorName(SQLHSTMT StatementHandle, SQLCHAR* CursorName, SQLSMALLINT BufferLength, SQLSMALLINT* NameLengthPtr);

4.6.4.2 Параметры

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

CursorName [Output] указатель на буфер для имени курсора.

BufferLength [Input] длина *CursorName в байтах.

NameLengthPtr [Output] указатель на память, куда будет записано возвращаемое значение. Если значение больше, чем BufferLength, *CursorName урезается до BufferLength за вычетом хвостового нуля.

4.6.5 SQLSetCursorName

SQLSetCursorName сопоставляет имя курсора с активной инструкцией. Если прикладная программа не вызывает SQLSetCursorName, драйвер генерирует имена курсора так, как необходимо для обработки инструкции SQL.

4.6.5.1 Синтаксис

SQLRETURN SQLSetCursorName(SQLHSTMT StatementHandle, SQLCHAR* CursorName, SQLSMALLINT NameLength);

4.6.5.2 Параметры

StatementHandle [Input] операторный дескриптор.

CursorName [Input] имя курсора. Для эффективной обработки имя курсора не должно включить никаких пробелов, а если имя курсора включает разграниченный идентификатор, разделитель должен быть установлен как первый символ в имени курсора.

NameLength [Input] длина *CursorName.

4.6.6 SQLSetScrollOptions

В ODBC 3.x SQLSetSetScrollOptions заменен обращением к 4.5.7 SQLSetStmtAttr и 4.4.3 SQLGetInfo.

4.7 Выполнение инструкций SQL

4.7.1 SQLExecute

SQLExecute выполняет подготовленную инструкцию, используя текущие (актуальные) значения переменных маркера параметра, если маркеры параметров существуют в инструкции.

4.7.1.1 Синтаксис

SQLRETURN SQLExecute(SQLHSTMT StatementHandle);

4.7.1.2 Параметры

StatementHandle [Input] операторный дескриптор.

4.7.1.3 Комментарии

SQLExecute выполняет инструкцию, подготовленную SQLPrepare.

4.7.2 SQLExecDirect

SQLExecDirect выполняет инструкцию, используя текущие (актуальные) значения переменных маркера параметра, если параметры существуют в инструкции. SQLExecDirect представляет собой самый быстрый способ представить серверу на рассмотрение инструкцию SQL для одного выполнения.

4.7.2.1 Синтаксис

SQLRETURN SQLExecDirect(SQLHSTMT StatementHandle, SQLCHAR* StatementText, SQLINTEGER TextLength);

4.7.2.2 Параметры

StatementHandle [Input] операторный дескриптор.

StatementText [Input] SQL-инструкция, которая будет выполнена.

TextLength [Input] длина *StatementText.

4.7.2.3 Комментарии

Прикладные программы вызывают SQLExecDirect, чтобы послать инструкцию SQL на сервер MySQL.

4.7.3 SQLNativeSql

SQLNativeSql возвращает строку SQL, обработанную драйвером. SQLNativeSql не выполняет инструкцию SQL.

4.7.3.1 Синтаксис

SQLRETURN SQLNativeSql(SQLHDBC ConnectionHandle, SQLCHAR* InStatementText, SQLINTEGER TextLength1, SQLCHAR* OutStatementText, SQLINTEGER BufferLength, SQLINTEGER* TextLength2Ptr);

4.7.3.2 Параметры

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

InStatementText [Input] текст инструкции SQL.

TextLength1 [Input] длина строки *InStatementText.

OutStatementText [Output] указатель на буфер распределенный, чтобы возвращать строку SQL.

BufferLength [Input] длина буфера *OutStatementText.

TextLength2Ptr [Output] указатель на буфер выделенный, чтобы возвращать общее количество байт, доступное в *OutStatementText. Если число доступных байт больше BufferLength, *OutStatementText урезается.

4.7.4 SQLDescribeParam

SQLDescribeParam возвращает описание маркера параметра, связанного с подготовленной инструкцией SQL.

4.7.4.1 Синтаксис

SQLRETURN SQLDescribeParam(SQLHSTMT StatementHandle, SQLUSMALLINT ParameterNumber, SQLSMALLINT* DataTypePtr, SQLUINTEGER* ParameterSizePtr, SQLSMALLINT* DecimalDigitsPtr, SQLSMALLINT* NullablePtr);

4.7.4.2 Параметры

StatementHandle [Input] операторный дескриптор.

ParameterNumber [Input] номер маркера, начиная с 1.

DataTypePtr [Output] указатель на буфер выделенный, чтобы возвращать SQL-тип данных параметра. В ODBC 3.x SQL_TYPE_DATE, SQL_TYPE_TIME, или SQL_TYPE_TIMESTAMP будут возвращен в *DataTypePtr для типов date, time или timestamp соответственно. В ODBC 2.x возвращаются SQL_DATE, SQL_TIME или SQL_TIMESTAMP.

ParameterSizePtr [Output] указатель на буфер для возврата размера столбца или выражения соответствующего маркера параметра.

DecimalDigitsPtr [Output] указатель на буфер для возврата количества десятичных цифр столбца или выражения соответствующего параметра как определено сервером.

NullablePtr [Output] указатель на буфер, куда будет возвращено значение, которое указывает позволяет ли параметр значения NULL. Это значение читается из поля SQL_DESC_NULLABLE в IPD. Один из следующего:

4.7.5 SQLNumParams

SQLNumParams возвращает число параметров в инструкции SQL.

4.7.5.1 Синтаксис

SQLRETURN SQLNumParams(SQLHSTMT StatementHandle, SQLSMALLINT* ParameterCountPtr);

4.7.5.2 Параметры

StatementHandle [Input] операторный дескриптор.

ParameterCountPtr [Output] указатель на буфер распределенный, чтобы возвращать число параметров в инструкции.

4.7.6 SQLParamData

SQLParamData используется вместе с SQLPutData, чтобы обеспечить данные для параметров во время выполнения.

4.7.6.1 Синтаксис

SQLRETURN SQLParamData(SQLHSTMT StatementHandle, SQLPOINTER* ValuePtrPtr);

4.7.6.2 Параметры

StatementHandle [Input] операторный дескриптор.

ValuePtrPtr [Output] указатель на буфер выделенный, чтобы возвращать адрес буфера ParameterValuePtr, определенного в SQLBindParameter (для данных параметра) или адрес буфера TargetValuePtr, определенного в SQLBindCol (для данных столбца), как указано в поле SQL_DESC_DATA_PTR записи операторного дескриптора.

4.7.7 SQLPutData

SQLPutData позволяет прикладной программе посылать данные для параметра или столбца драйверу во время выполнения. Эта функция может использоваться, чтобы послать символьные или двоичные значения данных частями к столбцу со специфическим типом данных (например, параметры типов SQL_LONGVARBINARY или SQL_LONGVARCHAR). SQLPutData поддерживает связывание с Unicode C-типом данных, даже если основной драйвер не поддерживает Unicode.

4.7.7.1 Синтаксис

SQLRETURN SQLPutData(SQLHSTMT StatementHandle, SQLPOINTER DataPtr, SQLINTEGER StrLen_or_Ind);

4.7.7.2 Параметры

StatementHandle [Input] операторный дескриптор.

DataPtr [Input] указатель на буфер с актуальными данными для для параметра или столбца. Данные должны быть в C-типе данных, определенном в параметре ValueType функции SQLBindParameter (для данных параметра) или в параметре TargetType функции SQLBindCol (для данных столбца).

StrLen_or_Ind [Input] длина *DataPtr. Определяет количество данных, переданное в вызове SQLPutData. Количество данных может измениться для каждого вызова. StrLen_or_Ind игнорируется, если не выполняется одно из следующих условий:

4.8 Получение результатов и информации о них

4.8.1 SQLRowCount

SQLRowCount возвращает число строк, на которые воздействует инструкция UPDATE, INSERT или DELETE.

4.8.1.1 Синтаксис

SQLRETURN SQLRowCount(SQLHSTMT StatementHandle, SQLINTEGER* RowCountPtr);

4.8.1.2 Параметры

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

RowCountPtr [Output] указывает на буфер для возврата числа строк. Для UPDATE, INSERT и DELETE, операций SQL_ADD в SQLBulkOperations и SQL_UPDATE или SQL_DELETE в SQLSetPos значение, возвращенное в *RowCountPtr, является числом строк, на которые воздействует запрос, или -1, если число строк не доступно.

При вызове SQLExecute, SQLExecDirect, SQLBulkOperations, SQLSetPos или SQLMoreResults поле SQL_DIAG_ROW_COUNT диагностической структуры данных установлено в число строк, которое кэшируется зависимым от реализации способом. SQLRowCount возвращает кэшируемое значение числа строк. Оно имеет силу, пока операторный дескриптор не перераспределен, не выполнена снова инструкция или не вызван SQLCloseCursor. Обратите внимание, что, если функция была вызвана, поле SQL_DIAG_ROW_COUNT было установлено, и значение, возвращенное SQLRowCount, может отличаться от значения в SQL_DIAG_ROW_COUNT, поскольку поле SQL_DIAG_ROW_COUNT сброшено в 0 любым обращением к функции.

Для других инструкций и функций, драйвер может определять значение, возвращенное в *RowCountPtr. Например, некоторые источники данных могут возвратить число строк, возвращенных инструкцией SELECT или функцией каталога перед выборкой строк.

Обратите внимание, что много источников данных не могут возвращать число строк в наборе результатов перед их выборкой.

4.8.2 SQLNumResultCols

SQLNumResultCols возвращает число столбцов в наборе результатов.

4.8.2.1 Синтаксис

SQLRETURN SQLNumResultCols(SQLHSTMT StatementHandle, SQLSMALLINT* ColumnCountPtr);

4.8.2.2 Параметры

StatementHandle [Input] операторный дескриптор.

ColumnCountPtr [Output] указатель на буфер, в который будет записано число столбцов в наборе результатов.

4.8.3 SQLDescribeCol

SQLDescribeCol возвращает имя дескрипторного столбца результата, тип, размер столбца, десятичные цифры и возможность принимать значение null для одного столбца в наборе результатов. Эта информация также доступна в полях IRD.

4.8.3.1 Синтаксис

SQLRETURN SQLDescribeCol(SQLHSTMT StatementHandle, SQLSMALLINT ColumnNumber, SQLCHAR* ColumnName, SQLSMALLINT BufferLength, SQLSMALLINT* NameLengthPtr, SQLSMALLINT* DataTypePtr, SQLUINTEGER* ColumnSizePtr, SQLSMALLINT* DecimalDigitsPtr, SQLSMALLINT* NullablePtr);

4.8.3.2 Параметры

StatementHandle [Input] операторный дескриптор.

ColumnNumber [Input] номер столбца данных результата, упорядоченных последовательно в увеличивающемся порядке, начиная с 1. Параметр ColumnNumber может быть также установлен в 0, чтобы описать столбец закладки.

ColumnName [Output] указатель на буфер, в который надо вернуть имя столбца. Это значение читается из поля SQL_DESC_NAME в IRD. Если столбец не назван, или имя столбца не может быть определено, драйвер возвращает пустую строку.

BufferLength [Input] длина буфера *ColumnName в символах.

NameLengthPtr [Output] указатель на буфер, куда надо записать общее количество байт, доступных для возврата в *ColumnName. Хвостовые нули не учитываются. Если значение в *ColumnName больше BufferLength, оно усекается до BufferLength.

DataTypePtr [Output] указатель на буфер, в который надо вернуть SQL-тип данных столбца. Это значение читается из поля SQL_DESC_CONCISE_TYPE в IRD. Если тип данных не может быть определен, драйвер возвращает SQL_UNKNOWN_TYPE.

ColumnSizePtr [Output] указатель на буфер предназначенный, чтобы возвращать размер столбца в источнике данных. Если размер столбца не может быть определен, драйвер возвращает 0.

DecimalDigitsPtr [Output] указатель на буфер предназначенный, чтобы возвращать число десятичных цифр столбца в источнике данных. Если число десятичных цифр не может быть определено или не применимо, драйвер вернет 0.

NullablePtr [Output] указатель на буфер предназначенный, чтобы возвращать значение, которое указывает, позволяет ли этот столбец применять в нем значения NULL. Это значение читается из поля SQL_DESC_NULLABLE в IRD. Значение одно из следующего:

4.8.4 SQLColAttribute

SQLColAttribute возвращает дескрипторную информацию для столбца в наборе результатов. Дескрипторная информация будет возвращена как символьная строка, 32-разрядное дескрипторно-зависимое значение или целочисленное значение.

4.8.4.1 Синтаксис

SQLRETURN SQLColAttribute(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLUSMALLINT FieldIdentifier, SQLPOINTER CharacterAttributePtr, SQLSMALLINT BufferLength, SQLSMALLINT* StringLengthPtr, SQLPOINTER NumericAttributePtr);

4.8.4.2 Параметры

StatementHandle [Input] операторный дескриптор.

ColumnNumber [Input] номер записи в IRD, из которой должно быть получено значение поля. Этот параметр соответствует номеру столбца данных результата, упорядоченных последовательно в увеличивающемся порядке, начиная с 1. Столбцы могут быть описаны в любом порядке. Столбец 0 может быть определен в этом параметре, но все параметры, за исключением SQL_DESC_TYPE и SQL_DESC_OCTET_LENGTH, возвратят неопределенные значения.

FieldIdentifier [Input] поле в строке ColumnNumber в IRD, которое должно быть возвращено.

CharacterAttributePtr [Output] указатель на буфер выделенный, чтобы возвращать значение в поле FieldIdentifier из строки ColumnNumber в IRD, если поле представляет собой символьную строку. Иначе поле не используется.

BufferLength [Input] если FieldIdentifier определен в ODBC и CharacterAttributePtr указывает на символьную строку или двоичный буфер, этот параметр должен быть длиной *CharacterAttributePtr. Если FieldIdentifier определен в ODBC и *CharacterAttributePtr целое число, это поле игнорируется. Если *CharacterAttributePtr является строкой в Unicode (при вызове SQLColAttributeW), параметр BufferLength должен быть четным числом.

Если FieldIdentifier определен в драйвере, прикладная программа указывает характер поля для Driver Manager, устанавливая параметр BufferLength. Он может иметь следующие значения:

StringLengthPtr [Output] указатель на буфер нужный, чтобы возвращать общее количество байт, доступное в *CharacterAttributePtr, кроме хвостовых нулей.

Для символьных данных если число доступных байт больше BufferLength, информация дескриптора в *CharacterAttributePtr урезается до BufferLength.

Для всех других типов данных значение BufferLength игнорируется, и драйвер принимает, что размер *CharacterAttributePtr равен 32 битам.

NumericAttributePtr [Output] указатель на целочисленный буфер нужный, чтобы возвращать значение в поле FieldIdentifier строки ColumnNumber из IRD, если поле числовой дескрипторный тип, например, SQL_DESC_COLUMN_LENGTH. Иначе поле не используется.

4.8.5 SQLColAttributes

В ODBC 3.x SQLColAttributes заменена SQLColAttribute.

4.8.6 SQLBindCol

SQLBindCol привязывает буферы данных прикладных программ к столбцам в наборе результатов.

4.8.6.1 Синтаксис

SQLRETURN SQLBindCol(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr, SQLINTEGER BufferLength, SQLLEN* StrLen_or_Ind);

4.8.6.2 Параметры

StatementHandle [Input] операторный дескриптор.

ColumnNumber [Input] номер столбца в наборе результатов, с которым надо связать буфер. Столбцы пронумерованы в увеличивающемся порядке, начиная с 0, где столбец с номером 0 является закладкой. Если закладки не используются, то есть атрибут инструкции SQL_ATTR_USE_BOOKMARKS установлен в SQL_UB_OFF, столбцы нумеруются, начиная с 1.

TargetType [Input] идентификатор C-типа данных буфера *TargetValuePtr. При получении данных из источника данных с помощью SQLFetch, SQLFetchScroll, SQLBulkOperations или SQLSetPos, драйвер преобразовывает данные к этому типу, а при посылке данных источнику данных с помощью SQLBulkOperations или SQLSetPos, драйвер преобразовывает данные из этого типа.

TargetValuePtr [Deferred Input/Output] указатель на буфер для связи со столбцом. SQLFetch и SQLFetchScroll возвращают данные в этом буфере. SQLBulkOperations получает данные из этого буфера, когда Operation равен SQL_ADD. SQLSetPos возвращает данные в этом буфере, когда Operation равен SQL_REFRESH и получает данные из этого буфера, когда Operation равен SQL_UPDATE.

Если TargetValuePtr равен null, драйвер отвязывает буфер данных от столбца. Прикладная программа может отвязать все столбцы, вызывая SQLFreeStmt с опцией SQL_UNBIND. Прикладная программа может отвязать буфер данных от столбца, но все еще иметь буфер длин связанный со столбцом, если параметр TargetValuePtr в вызове SQLBindCol равен null, но аргумент StrLen_or_IndPtr представляет собой имеющее силу значение.

BufferLength [Input] длина в бвйтах *TargetValuePtr. Драйвер использует BufferLength, чтобы не перезаписать хвост буфера *TargetValuePtr при возврате данных переменной длины, типа символьных или двоичных данных. Обратите внимание, что драйвер учитывает хвостовой нулевой символ при возврате символьных данных в *TargetValuePtr. *TargetValuePtr, следовательно, должен содержать место для этого символа, или драйвер усечет данные.

Когда данные фиксированной длины, типа целого числа или структуры даты, драйвер игнорирует BufferLength и принимают, что буфер достаточно большой, чтобы сохранить данные. Следовательно, для прикладной программы важно распределить достаточно большой буфер для данных фиксированной длины во избежание проблем с переполнением.

SQLBindCol возвращает ошибку SQLSTATE HY090 (Invalid string or buffer length), когда BufferLength меньше 0, но не когда BufferLength равен 0. Однако, если TargetType определяет символьный тип, прикладная программа не должна устанавливать BufferLength в 0, поскольку драйверы ISO CLI в этом случае возвращают SQLSTATE HY090 (Invalid string or buffer length).

StrLen_or_IndPtr [Deferred Input/Output] указатель на буфер длин для свяхи со столбцом. SQLFetch и SQLFetchScroll возвращают значение в этом буфере. SQLBulkOperations получает значение из этого буфера, когда параметр Operation равен SQL_ADD. SQLSetPos возвращает значение в этом буфере, когда Operation равен SQL_REFRESH и получает значение из этого буфера, когда Operation равен SQL_UPDATE. SQLFetch, SQLFetchScroll, SQLBulkOperations и SQLSetPos могут возвращать следующие значения в буфере длин:

Прикладная программа может помещать следующие значения в буфер длин для использования с SQLBulkOperations или с SQLSetPos:

Если буфер индикаторов и буфер длин разделены, буфер индикаторов может возвращать только SQL_NULL_DATA, в то время как буфер длин может возвращать все остальные значения. Если StrLen_or_IndPtr равно null, значения длины или индикаторов не применяются.

4.8.7 SQLFetch

SQLFetch выбирает следующий rowset данных из набора результатов и возвращает данные для всех связанных столбцов.

4.8.7.1 Синтаксис

SQLRETURN SQLFetch(SQLHSTMT StatementHandle);

4.8.7.2 Параметры

StatementHandle [Input] операторный дескриптор.

4.8.7.3 Комментарии

SQLFetch возвращает следующий rowset в наборе результатов. Это может быть вызвано только в то время, когда набор результатов существует, то есть после обращения, которое создает набор результатов и прежде, чем курсор будет закрыт. Если любые столбцы связаны с данными, этот вызов возвращает данные в этих столбцах. Если прикладная программа определила указатель на массив состояния или на буфер нужный, чтобы возвращать число выбранных строк, SQLFetch возвращает также и эту информацию. Обращение к SQLFetch может быть смешано с обращениями к SQLFetchScroll, но не может быть смешано с обращениями к SQLExtendedFetch.

4.8.8 SQLFetchScroll

SQLFetchScroll выбирает определенный rowset данных из набора результатов и возвращает данные для всех связанных столбцов. Rowset может быть определен в абсолютной или относительной позиции или закладкой. При работе с драйвером ODBC 2.x Driver Manager отображает эту функцию на SQLExtendedFetch.

4.8.8.1 Синтаксис

SQLRETURN SQLFetchScroll(SQLHSTMT StatementHandle, SQLSMALLINT FetchOrientation, SQLINTEGER FetchOffset);

4.8.8.2 Параметры

StatementHandle [Input] операторный дескриптор.

FetchOrientation [Input] тип выборки:

FetchOffset [Input] номер строки для выборки. Интерпретация этого параметра зависит от значения параметра FetchOrientation.

4.8.8.3 Комментарии

Когда набор результатов создан, курсор установлен перед началом набора результатов. SQLFetchScroll устанавливает блочный курсор, исходя из значений параметров FetchOrientation и FetchOffset как показано в следующей таблице.

FetchOritentationСмысл
SQL_FETCH_NEXTВернет следующий rowset. Это эквивалентно вызову SQLFetch. SQLFetchScroll игнорирует значение FetchOffset.
SQL_FETCH_PRIORВернет предшествующий rowset. SQLFetchScroll игнорирует значение FetchOffset.
SQL_FETCH_RELATIVEВернет FetchOffset от начала текущего (актуального) rowset.
SQL_FETCH_ABSOLUTEВернет rowset, начинающийся в строке FetchOffset.
SQL_FETCH_FIRSTВернет первый rowset в наборе результатов. SQLFetchScroll игнорирует значение FetchOffset.
SQL_FETCH_LASTВернет последний полный rowset в наборе результатов. SQLFetchScroll игнорирует значение FetchOffset.

4.8.9 SQLExtendedFetch

SQLExtendedFetch выбирает определенный rowset данных из набора результатов и возвращает данные для всех связанных столбцов. Rowset может быть определен в абсолютной или относительной позиции.

Обратите внимание в ODBC 3.x SQLExtendedFetch заменен на SQLFetchScroll. Прикладные программы ODBC 3.x не должны вызвать SQLExtendedFetch: взамен они должны вызвать SQLFetchScroll.

4.8.9.1 Синтаксис

SQLRETURN SQLExtendedFetch(SQLHSTMT StatementHandle, SQLUSMALLINT FetchOrientation, SQLINTEGER FetchOffset, SQLUINTEGER* RowCountPtr, SQLUSMALLINT* RowStatusArray);

4.8.9.2 Параметры

StatementHandle [Input] операторный дескриптор.

FetchOrientation [Input] тип выборки. Это аналогично FetchOrientation в SQLFetchScroll.

FetchOffset [Input] номер столбца для выборки. Аналогично FetchOffset в SQLFetchScroll.

RowCountPtr [Output] указатель на буфер, куда надо записать число фактически выбранных строк. Этот буфер используется тем же самым способом, что и буфер, определенный атрибутом инструкции SQL_ATTR_ROWS_FETCHED_PTR. Этот буфер используется только SQLExtendedFetch. Это не используется SQLFetch или SQLFetchScroll.

RowStatusArray [Output] указатель на буфер, куда надо записать состояние каждой строки. Этот массив используется тем же самым способом, что и массив, определенный атрибутом инструкции SQL_ATTR_ROW_STATUS_PTR.

Однако, адрес этого массива не сохранен в поле SQL_DESC_STATUS_ARRAY_PTR в IRD. Кроме того, этот массив используется только SQLExtendedFetch, SQLBulkOperations при параметре Operation равном SQL_ADD или SQLSetPos, когда это вызвано после SQLExtendedFetch. SQLFetch или SQLFetchScroll не используют это вообще, а SQLBulkOperations или SQLSetPos не используют, когда они вызваны после SQLFetch или SQLFetchScroll. Это также не используется, когда SQLBulkOperations с параметром Operation равным SQL_ADD вызван прежде, чем выполнена любая функция выборки. Прикладные программы должны обеспечить имеющий силу указатель в параметре RowStatusArray. Если это не так, последствия будут непредсказуемыми.

4.8.9.3 Комментарии

Логика работы SQLExtendedFetch идентична SQLFetchScroll, но:

4.8.10 SQLGetData

SQLGetData получает данные для одиночного столбца в наборе результатов. Это может быть вызвано неоднократно, чтобы получить данные переменной длины по частям.

4.8.10.1 Синтаксис

SQLRETURN SQLGetData(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber, SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr, SQLINTEGER BufferLength, SQLINTEGER* StrLen_or_IndPtr);

4.8.10.2 Параметры

StatementHandle [Input] операторный дескриптор.

ColumnNumber [Input] номер столбца для возврата данных. Все столбцы в наборе результатов пронумерованы в увеличивающемся порядке, начиная с 1. Столбец закладки имеет номер столбца, равный 0, это может быть определено только, если закладки допускаются.

TargetType [Input] идентификатор C-типа данных буфера *TargetValuePtr. Если это равно SQL_C_DEFAULT, драйвер выбирает заданный по умолчанию C-тип данных, основываясь на SQL-типе данных источника.

TargetValuePtr [Input] указатель на буфер для приема данных.

BufferLength [Input] длина буфера *TargetValuePtr в байтах. Драйвер использует BufferLength, чтобы избежать столкновения с *TargetValuePtr при возврате данных переменной длины, типа символьных или двоичных данных. Обратите внимание, что драйвер считает хвостовой нуль.

Когда данные имеют фиксированную длину, типа целого числа или структуры даты, драйвер игнорирует BufferLength и принимает, что буфер достаточно большой, чтобы сохранить в нем данные.

SQLGetData вернет SQLSTATE HY090 (Invalid string or buffer length), когда BufferLength меньше 0, но не когда BufferLength равен 0. Если TargetValuePtr равен null, BufferLength игнорируется драйвером.

StrLen_or_IndPtr [Deferred Input/Output] указатель на буфер нужный, чтобы возвращать длину или значение индикатора. Если это null, не будет возвращено ничего. Это возвращает ошибку, когда выбираемые данные NULL. SQLGetData может возвращать следующие значения в буфере длин/индикатора:

4.8.11 SQLSetPos

SQLSetPos устанавливает позицию курсора в rowset и позволяет прикладной программе обновить данные в rowset, модифицировать или удалять данные в наборе результатов.

4.8.11.1 Синтаксис

SQLRETURN SQLSetPos(SQLHSTMT StatementHandle, SQLUSMALLINT RowNumber, SQLUSMALLINT Operation, SQLUSMALLINT LockType);

4.8.11.2 Параметры

StatementHandle [Input]] операторный дескриптор.

RowNumber [Input] позиция строки в rowset над которой надо выполнить операцию, определенную параметром Operation. Если RowNumber равен 0, операция применяется к каждой строке в rowset.

Operation [Input] операция для выполнения:

LockType [Input] определяет, как блокировать строку после выполнения операции, определенной в параметре Operation:

4.8.11.3 Комментарии

Row Number: параметр RowNumber определяет номер строки в rowset, с которой надо работать. Если RowNumber равен 0, операция применяется к каждой строке в rowset. RowNumber должен быть значением от 0 до максимального количества строк в rowset. Обратите внимание, что в языке C массивы отсчитываются от 0, RowNumber реально отсчитывается от 1. Например, чтобы модифицировать пятую строку rowset, прикладная программа изменяет буфер rowset в массиве с индексом 4, но определяет RowNumber=5! Все операции устанавливают курсор в строку, определенную RowNumber. Следующие операции требуют позиционирования курсора:

Например, если RowNumber=2, при обращении к SQLSetPos с Operation равным SQL_DELETE, курсор установлен во вторую строку rowset, и эта строка будет удалена. Запись в массиве состояний строк (указан атрибутом инструкции SQL_ATTR_ROW_STATUS_PTR) для второй строки изменена на SQL_ROW_DELETED.

Прикладная программа может определять позицию курсора, когда вызывает SQLSetPos. Вообще, это вызывает SQLSetPos с параметром SQL_POSITION или SQL_REFRESH, чтобы установить курсор перед выполнением позиционной инструкции или вызовом SQLGetData. Параметр Operation поддерживает следующие операции. Чтобы понять, какие именно параметры поддержаны источником данных, вызовите из прикладной программы SQLGetInfo с информационными типами SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1 и SQL_STATIC_CURSOR_ATTRIBUTES1.

АргументДействие
SQL_POSITIONДрайвер устанавливает курсор в строку, определенную RowNumber. Содержание массива состояний строк, указанного атрибутом инструкции SQL_ATTR_ROW_OPERATION_PTR игнорируется в SQL_POSITION.
SQL_REFRESHДрайвер устанавливает курсор в строку, определенную RowNumber и регенерирует данные в буферах rowset для этой строки. SQLSetPos с Operation равным SQL_REFRESH модифицирует состояние и содержание строк внутри текущего (актуального) выбранного rowset. Поскольку данные в буферах регенерируются, но не выбираются заново, членство в rowset фиксировано. Это отличается от регенерации, выполняемой обращением к SQLFetchScroll с FetchOrientation равным SQL_FETCH_RELATIVE и RowNumber равным 0, что заново выбирает rowset из набора результатов так, чтобы он мог показывать добавленные данные и удалить удаленные данные, если эти операции поддержаны драйвером и курсором.
SQL_UPDATEДрайвер устанавливает курсор в строку, определенную RowNumber и модифицирует основную строку данных значениями в буферах rowset (параметр TargetValuePtr в SQLBindCol).
SQL_DELETEДрайвер устанавливает курсор в строку, определенную RowNumber и удаляет основную строку данных. Это изменяет соответствующий элемент массива состояний строк на SQL_ROW_DELETED. После того, как строка была удалена, следующее не имеет силу для строки: вызов SQLGetData, позиционная модификация и удаление и обращение к SQLSetPos с любым значением параметра Operation, кроме SQL_POSITION.

4.8.12 SQLBulkOperations

SQLBulkOperations выполняет оптовые вставки и операции закладки, включая update, delete и выборку по закладке.

4.8.12.1 Синтаксис

SQLRETURN SQLBulkOperations(SQLHSTMT StatementHandle, SQLUSMALLINT Operation);

4.8.12.2 Параметры

StatementHandle [Input] операторный дескриптор.

Operation [Input] операция для выполнения: SQL_ADD. Обратите внимание: сейчас никакие операции с закладками драйвером не поддерживаются.

4.8.12.3 Комментарии

Выполнение оптовых вставок:

Чтобы вставлять данные с помощью SQLBulkOperations, прикладная программа выполняет следующую последовательность шагов:

4.9 Получение информации об ошибках и диагностике

4.9.1 SQLError

SQLError возвращает информацию состояния или ошибку. Прикладная программа обычно вызывает SQLError, когда предыдущая функция ODBC возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO. В ODBC 3.x SQLGetDiagRec заменила функцию ODBC 2.0 SQLError.

4.9.2 SQLGetDiagField

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

4.9.2.1 Синтаксис

SQLRETURN SQLGetDiagField(SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLSMALLINT DiagIdentifier, SQLPOINTER DiagInfoPtr, SQLSMALLINT BufferLength, SQLSMALLINT* StringLengthPtr);

4.9.2.2 Параметры

HandleType [Input] идентификатор типа дескриптора, который описывает тип дескриптора для которого требуется диагностика. Должен быть одним из следующего: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT или SQL_HANDLE_DESC (не поддерживается).

Handle [Input] дескриптор для диагностической структуры данных. Тип обозначен в HandleType.

RecNumber [Input] указывает запись состояния, из которой прикладная программа ищет информацию. Записи состояния пронумерованы, начиная с 1. Если параметр DiagIdentifier указывает, любое поле диагностического заголовка, RecNumber игнорируется. В противном случае это должно быть больше 0.

DiagIdentifier [Input] указывает поле диагностики, чье значение должно быть возвращено.

DiagInfoPtr [Output] указатель на буфер выделенный, чтобы возвращать диагностическую информацию. Тип данных зависит от значения DiagIdentifier.

BufferLength [Input] если DiagIdentifier определен в ODBC и DiagInfoPtr указывает на строку или двоичный буфер, этот параметр должен быть длиной *DiagInfoPtr. Если DiagIdentifier определен в ODBC и *DiagInfoPtr является целым числом, BufferLength игнорируется. BufferLength может иметь следующие значения:

StringLengthPtr [Output] указатель на буфер распределенный, чтобы возвращать общее количество байт, доступных в *DiagInfoPtr (только для символьных данных, хвостовые нули не считаются).

4.9.2.3 Комментарии

SQLGetDiagField не регистрирует диагностические записи для себя. Это использует следующие значения возврата, чтобы сообщить результат собственного выполнения:

Прикладная программа обычно вызывает SQLGetDiagField, чтобы выполнить одну из трех целей:

  1. Получить специфическую информацию об ошибке или предупреждение, когда обращение к функции возвратило SQL_ERROR или SQL_SUCCESS_WITH_INFO.
  2. Чтобы выяснить число строк в источнике данных, на которые воздействовали операции insert, delete или update при вызове SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos (из поля SQL_DIAG_ROW_COUNT заголовка), или выяснить число строк, открытом курсоре, если драйвер способен обеспечить эту информацию (из поля SQL_DIAG_CURSOR_ROW_COUNT заголовка).

DiagIdentifier: ниже приведен полный список диагностических идентификаторов, поддержанных драйвером.

DiagIdentifierТип возврата Возвращаемое значение
SQL_DIAG_CURSOR_ROW_COUNTSQLINTEGERЭто поле содержит число строк в курсоре.
SQL_DIAG_NUMBERSQLINTEGERЧисло записей состояния, которые являются доступными для определенного дескриптора. В настоящее время драйвер всегда возвращает 1.
SQL_DIAG_RETURNCODESQLRETURNКод возврата, возвращенный функцией.
SQL_DIAG_ROW_COUNTSQLINTEGERЧисло строк, на которые воздействует операция insert, delete или update, вызванная через SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos.
SQL_DIAG_CLASS_ORIGINSQLCHAR*Строка, которая указывает документ который определяет часть класса значения SQLSTATE в этой записи. Значение "ISO 9075" для всех SQLSTATE определено X/Open и интерфейсом уровня обращения ISO. Для ODBC-специфических SQLSTATE (все те, чей класс SQLSTATE равен "IM"), это значение равно "ODBC 3.0".
SQL_DIAG_COLUMN_NUMBERSQLINTEGERЕсли поле SQL_DIAG_ROW_NUMBER представляет собой имеющий силу номер строки в наборе строк или наборе параметров, это поле содержит значение, которое представляет номер столбца в наборе результатов или номер параметра в наборе параметров. Номера столбцов всегда начинаются с 1. Если эта запись состояния относится к столбцу закладки, поле может быть нулевым. Номера параметров начинаются с 1. Это имеет значение SQL_NO_COLUMN_NUMBER, если запись состояния не связана с номером столбца или номером параметра. Если драйвер не может определять номер столбца или номер параметра, с которым эта запись связана, это поле имеет значение SQL_COLUMN_NUMBER_UNKNOWN. Содержимое этого поля определено только для операторных дескрипторов.
SQL_DIAG_CONNECTION_ NAMESQLCHAR*Строка, которая указывает имя подключения, к которому относится эта диагностическая запись. Драйвер возвращает DSN как имя подключения, а для DSN-LESS-подключения это поле является строкой нулевой длины.
SQL_DIAG_MESSAGE_TEXTSQLCHAR*Информационное сообщение об ошибке или текста предупреждения. Подробности ниже.
SQL_DIAG_NATIVESQLINTEGERИсходно-специфический местный код ошибки драйвера или данных. Если не имеется никакого местного кода ошибки, драйвер возвращает 0.
SQL_DIAG_ROW_NUMBERSQLINTEGERЭто поле содержит номер строки в наборе строк, или номер параметра в наборе параметров, с которыми запись состояния связана. Номера начинаются с 1. Это поле имеет значение SQL_NO_ROW_NUMBER, если эта запись состояния не связана с номером строки или параметра. Если драйвер не может определять номер строки или параметра, с которым эта запись связана, это поле имеет значение SQL_ROW_NUMBER_UNKNOWN. Содержимое этого поля определено только для операторных дескрипторов.
SQL_DIAG_SERVER_NAMESQLCHAR*Строка, которая указывает имя сервера для этой диагностической записи. Это равно значению, возвращенному для обращения к SQLGetInfo с опцией SQL_DATA_SOURCE_NAME.
SQL_DIAG_SQLSTATESQLCHAR* Код диагностики пятисимвольного SQLSTATE.
SQL_DIAG_SUBCLASS_ORIGINSQLCHAR*Строка с тем же самым форматом и имеющими силу значениями, что и SQL_DIAG_CLASS_ORIGIN, которая идентифицирует часть определения части подкласса кода SQLSTATE. ODBC-специфические SQLSTATE для ODBC 3.0 возвращаются.

4.9.3 SQLGetDiagRec

SQLGetDiagRec возвращает текущие значения нескольких полей диагностической записи, которая содержит ошибку, предупреждение и информацию состояния. В отличие от SQLGetDiagField, которая возвращает одно диагностическое поле на обращение, SQLGetDiagRec возвращает несколько обычно используемых полей диагностической записи, включая SQLSTATE, местный код ошибки и диагностический текст сообщения.

4.9.3.1 Синтаксис

SQLRETURN SQLGetDiagRec(SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT RecNumber, SQLCHAR* Sqlstate, SQLINTEGER* NativeErrorPtr, SQLCHAR* MessageText, SQLSMALLINT BufferLength, SQLSMALLINT* TextLengthPtr);

4.9.3.2 Параметры

HandleType [Input] идентификатор типа дескриптора, который описывает тип дескриптора, для которого диагностика требуется. Должен быть одним из следующего: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT или SQL_HANDLE_DESC (не поддерживается).

Handle [Input] дескриптор для диагностической структуры данных. Тип задан в HandleType.

RecNumber [Input] указывает запись состояния, из которой прикладная программа получает информацию. Записи состояния пронумерованы с 1.

SQLState [Output] указатель на буфер нужный, чтобы возвращать код пятисимвольного SQLSTATE, имеющий отношение к диагностической записи RecNumber.

NativeErrorPtr [Output] указатель на буфер выделенный, чтобы возвращать местный код ошибки, специфический для источника данных. Эта информация содержится в диагностическом поле SQL_DIAG_NATIVE.

MessageText [Output] указатель на буфер выделенный, чтобы возвращать диагностический текст сообщения. Эта информация содержится в диагностическом поле SQL_DIAG_MESSAGE_TEXT.

BufferLength [Input] длина буфера *MessageText в символах. Не имеется никакой максимальной длины диагностического текста сообщения.

TextLengthPtr [Output] указатель на буфер для возврата общего количество байтов, доступных в *MessageText (кроме хвостовых нулей).

4.9.3.3 Комментарии

Прикладная программа обычно вызывает SQLGetDiagRec, когда предыдущее обращение к функции ODBC возвратило SQL_SUCCESS или SQL_SUCCESS_WITH_INFO. Однако, поскольку любая функция ODBC может регистрировать ноль или большее количество диагностических записей каждый вызов, прикладная программа может вызывать SQLGetDiagRec после любого обращения к функции ODBC.

4.10 Получение метаинформации

4.10.1 SQLColumnPrivileges

SQLColumnPrivileges возвращает список столбцов и связанных привилегий для определенной таблицы. Драйвер возвращает информацию как набор результатов на определенном StatementHandle.

4.10.1.1 Синтаксис

SQLRETURN SQLColumnPrivileges(SQLHSTMT StatementHandle, SQLCHAR* CatalogName, SQLSMALLINT NameLength1, SQLCHAR* SchemaName, SQLSMALLINT NameLength2, SQLCHAR* TableName, SQLSMALLINT NameLength3, SQLCHAR* ColumnName, SQLSMALLINT NameLength4);

4.10.1.2 Параметры

StatementHandle [Input] операторный дескриптор.

CatalogName [Input] имя каталога. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *CatalogName.

SchemaName [Input] имя схемы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *SchemaName.

TableName [Input] имя таблицы. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *TableName.

ColumnName [Input] образец поиска строки с именем столбца.

NameLength4 [Input] длина *ColumnName.

4.10.2 SQLColumns

SQLColumns возвращает список имен столбцов в определенных таблицах. Драйвер возвращает эту информацию в наборе результатов на определенном StatementHandle.

4.10.2.1 Синтаксис

SQLRETURN SQLColumns(SQLHSTMT StatementHandle, SQLCHAR* CatalogName, SQLSMALLINT NameLength1, SQLCHAR* SchemaName, SQLSMALLINT NameLength2, SQLCHAR* TableName, SQLSMALLINT NameLength3, SQLCHAR* ColumnName, SQLSMALLINT NameLength4);

4.10.2.2 Параметры

StatementHandle [Input] операторный дескриптор.

CatalogName [Input] имя каталога. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *CatalogName.

SchemaName [Input] имя схемы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *SchemaName.

TableName [Input] имя таблицы. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *TableName.

ColumnName [Input] образец поиска строки с именем столбца.

NameLength4 [Input] длина *ColumnName.

4.10.3 SQLForeignKeys

SQLForeignKeys может вернуть:

Драйвер возвращает каждый список в наборе результатов на определенной инструкции.

4.10.3.1 Синтаксис

SQLRETURN SQLForeignKeys(SQLHSTMT StatementHandle, SQLCHAR* PKCatalogName, SQLSMALLINT NameLength1, SQLCHAR* PKSchemaName, SQLSMALLINT NameLength2, SQLCHAR* PKTableName, SQLSMALLINT NameLength3, SQLCHAR* FKCatalogName, SQLSMALLINT NameLength4, SQLCHAR* FKSchemaName, SQLSMALLINT NameLength5, SQLCHAR* FKTableName, SQLSMALLINT NameLength6);

4.10.3.2 Параметры

StatementHandle [Input] операторный дескриптор.

PKCatalogName [Input] имя каталога первичного ключа таблицы. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *PKCatalogName в байтах.

PKSchemaName [Input] имя схемы первичного ключа таблицы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *PKSchemaName в байтах.

PKTableName [Input] имя таблицы с первичным ключом. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *PKTableName в байтах.

PKCatalogName [Input] имя каталога внешнего ключа таблицы. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength4 [Input] длина *FKCatalogName в байтах.

PKSchemaName [Input] имя схемы внешнего ключа таблицы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength5 [Input] длина *FKSchemaName в байтах.

FKTableName [Input] имя таблицы с внешним ключом. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength6 [Input] длина *FKTableName в байтах.

4.10.4 SQLPrimaryKeys

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

4.10.4.1 Синтаксис

SQLRETURN SQLPrimaryKeys(SQLHSTMT StatementHandle, SQLCHAR* CatalogName, SQLSMALLINT NameLength1, SQLCHAR* SchemaName, SQLSMALLINT NameLength2, SQLCHAR* TableName, SQLSMALLINT NameLength3);

4.10.4.2 Параметры

StatementHandle [Input] операторный дескриптор.

CatalogName [Input] имя каталога. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *CatalogName.

SchemaName [Input] имя схемы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *SchemaName.

TableName [Input] имя таблицы. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *TableName.

4.10.5 SQLSpecialColumns

SQLSpecialColumns возвращает следующую информацию относительно столбцов внутри определенной таблицы:

4.10.5.1 Синтаксис

SQLRETURN SQLSpecialColumns(SQLHSTMT StatementHandle, SQLSMALLINT IdentifierType, SQLCHAR* CatalogName, SQLSMALLINT NameLength1, SQLCHAR* SchemaName, SQLSMALLINT NameLength2, SQLCHAR* TableName, SQLSMALLINT NameLength3, SQLSMALLINT Scope, SQLSMALLINT Nullable);

4.10.5.2 Параметры

StatementHandle [Input] операторный дескриптор.

IdentifierType [Input] тип столбца для возврата. Должен быть одним из следующих значений:

CatalogName [Input] имя каталога. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *CatalogName.

SchemaName [Input] имя схемы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *SchemaName.

TableName [Input] имя таблицы. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *TableName.

Scope [Input] минимум требуемой области rowid. Возвращенный rowid может иметь большую область. Должен быть одним из следующего:

Nullable [Input] определяет, возвратить ли специальные столбцы, которые могут иметь значение NULL. Должен быть одним из следующего:

4.10.6 SQLStatistics

SQLStatistics возвращает статистику относительно одной таблицы и индексов, связанных с этой таблицей. Драйвер возвращает информацию в наборе результатов.

4.10.6.1 Синтаксис

SQLRETURN SQLStatistics(SQLHSTMT StatementHandle, SQLCHAR* CatalogName, SQLSMALLINT NameLength1, SQLCHAR* SchemaName, SQLSMALLINT NameLength2, SQLCHAR* TableName, SQLSMALLINT NameLength3, SQLUSMALLINT Unique, SQLUSMALLINT Reserved);

4.10.6.2 Параметры

StatementHandle [Input] операторный дескриптор.

CatalogName [Input] имя каталога. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *CatalogName.

SchemaName [Input] имя схемы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *SchemaName.

TableName [Input] имя таблицы. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *TableName.

Unique [Input] тип индекса: SQL_INDEX_UNIQUE или SQL_INDEX_ALL.

Reserved [Input] указывает важность CARDINALITY в столбце PAGES набора результатов. Следующие параметры воздействуют на возврат только столбцов CARDINALITY и PAGES (индексная информация возвращена, даже если CARDINALITY и PAGES не возвращены):

4.10.7 SQLTablePrivileges

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

4.10.7.1 Синтаксис

SQLRETURN SQLTablePrivileges(SQLHSTMT StatementHandle, SQLCHAR* CatalogName, SQLSMALLINT NameLength1, SQLCHAR* SchemaName, SQLSMALLINT NameLength2, SQLCHAR* TableName, SQLSMALLINT NameLength3);

4.10.7.2 Параметры

StatementHandle [Input] операторный дескриптор.

CatalogName [Input] имя каталога. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *CatalogName.

SchemaName [Input] имя схемы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *SchemaName.

TableName [Input] имя таблицы. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *TableName.

4.10.8 SQLTables

SQLTables возвращает список имен таблиц, каталогов, схем и типов таблиц, сохраненных в специфическом источнике данных. Драйвер возвращает информацию в наборе результатов.

4.10.8.1 Синтаксис

SQLRETURN SQLTables(SQLHSTMT StatementHandle, SQLCHAR* CatalogName, SQLSMALLINT NameLength1, SQLCHAR* SchemaName, SQLSMALLINT NameLength2, SQLCHAR* TableName, SQLSMALLINT NameLength3, SQLCHAR* TableType, SQLSMALLINT NameLength4);

4.10.8.2 Параметры

StatementHandle [Input] операторный дескриптор.

CatalogName [Input] имя каталога. Если драйвер поддерживает имена для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют имен. CatalogName не может содержать образец поиска строки!

NameLength1 [Input] длина *CatalogName.

SchemaName [Input] имя схемы. Если драйвер поддерживает схемы для некоторых каталогов, но не для всех (например, при одновременной работе с разными СУБД), пустая строка обозначает те схемы, которые не имеют имен. SchemaName не может содержать образец поиска строки!

NameLength2 [Input] длина *SchemaName.

TableName [Input] имя таблицы. Этот параметр не может быть null. TableName не может содержать образец поиска строки.

NameLength3 [Input] длина *TableName.

Table Type [Input] список типов таблиц.

NameLength4 [Input] длина *TableType.

4.11 Управление транзакциями

4.11.1 SQLTransact

SQLTransact запрашивает завершение или отмену для всех активных операций на всех инструкциях, связанных с подключением. SQLTransact может также запрашивать это для всех подключений, связанных со средой. В ODBC 3.x SQLEndTran заменил функцию ODBC 2.x SQLTransact.

4.11.2 SQLEndTran

SQLEndTran запрашивает завершение или отмену для всех активных операций на всех инструкциях, связанных с подключением. SQLEndTran может также запрашивать это для всех подключений, связанных со средой.

4.11.2.1 Синтаксис

SQLRETURN SQLEndTran(SQLSMALLINT HandleType, SQLHANDLE Handle, SQLSMALLINT CompletionType);

4.11.2.2 Параметры

HandleType [Input] идентификатор типа дескриптора. Содержит SQL_HANDLE_ENV (если Handle дескриптор среды) или SQL_HANDLE_DBC (если Handle представляет собой дескриптор подключения).

Handle [Input] дескриптор, тип коего задан в HandleType, указывает контекст транзакции.

CompletionType [Input] одно из следующтх двух значений:

4.12 Прерыванеие команд и соединений с сервером

4.12.1 SQLFreeStmt

SQLFreeStmt останавливает обработку, связанную со специфической инструкцией, закрывает любые открытые курсоры, связанные с этой инструкцией, отбрасывает ждущие обработки результаты и, факультативно, освобождает все ресурсы, связанные с операторным дескриптором.

4.12.1.1 Синтаксис

SQLRETURN SQLFreeStmt(SQLHSTMT StatementHandle, SQLUSMALLINT Option);

4.12.1.2 Параметры

StatementHandle [Input] операторный дескриптор.

Option [Input] одни из следующих параметров:

ОпцияДействие
SQL_CLOSEЗакрывает курсор, связанный с StatementHandle (если он был определен) и отбрасывает все ждущие обработки результаты. Прикладная программа может вновь открыть этот курсор позже, выполняя инструкцию SELECT с теми же самыми или иными значениями параметра. Если никакой курсор не открыт, эта опция не имеет никакого эффекта для прикладной программы. SQLCloseCursor может также быть вызван, чтобы закрыть курсор.
SQL_DROPОсвобождает операторный дескриптор: освобождает все ресурсы, связанных с ним, отбрасывает все ждущие обработки операции и закрывает курсор. Операторный дескриптор должен быть перераспределен для повторного использования. Эта опция устарела в MyODBC 3.51. Вызов SQLFreeStmt с параметром Option равным SQL_DROP отображается на вызов SQLFreeHandle.
SQL_UNBINDОсвобождает все буферы столбцов, связанные SQLBindCol для данного операторного дескриптора.
SQL_RESET_PARAMSОсвобождает весь набор буферов параметров SQLBindParameter для данного операторного дескриптора.

4.12.2 SQLCloseCursor

SQLCloseCursor закрывает курсор, который был открыт на инструкции и отбрасывает ждущие обработки результаты.

4.12.2.1 Синтаксис

SQLRETURN SQLCloseCursor(SQLHSTMT StatementHandle);

4.12.2.2 Параметры

StatementHandle [Input] операторный дескриптор.

4.12.3 SQLCancel

SQLCancel отменяет обработку инструкции.

4.12.3.1 Синтаксис

SQLRETURN SQLCancel(SQLHSTMT StatementHandle);

4.12.3.2 Параметры

StatementHandle [Input] операторный дескриптор.

4.12.3.3 Комментарии

SQLCancel может отменять следующие типы обработки инструкции:

В ODBC 2.x, если из прикладной программы вызвана SQLCancel, когда обработка не делается на инструкции, SQLCancel имеют тот же самый эффект, что и SQLFreeStmt с опцией SQL_CLOSE. Это поведение определено только для законченности реализации, и прикладные программы должны вызвать SQLFreeStmt или SQLCloseCursor, чтобы закрыть курсоры.

4.12.4 SQLDisconnect

SQLDisconnect закрывает подключение, связанное со специфическим дескриптором подключения.

4.12.4.1 Синтаксис

SQLRETURN SQLDisconnect(SQLHDBC ConnectionHandle);

4.12.4.2 Параметры

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

4.12.4.3 Комментарии

Если из прикладной программы вызвана SQLDisconnect, в то время как имеется незавершенная транзакция, связанная с дескриптором подключения, драйвер возвращает SQLSTATE 25000 (Invalid transaction state) указывая, что транзакция является неизменяемой, и подключение открыто. Незавершенной транзакцией является такая, которая не была ни завершена, ни отменена с помощью вызова SQLEndTran.

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

4.12.5 SQLFreeHandle

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

Обратите внимание, что это универсальная функция для освобождения дескрипторов. Это заменяет функции ODBC 2.0 SQLFreeConnect (для освобождения дескриптора подключения) и SQLFreeEnv (для освобождения дескриптора среды). SQLFreeConnect и SQLFreeEnv устарели в ODBC 3.x. SQLFreeHandle также заменяет функцию ODBC 2.0 SQLFreeStmt (с Option равным SQL_DROP) для освобождения операторного дескриптора.

4.12.5.1 Синтаксис

SQLRETURN SQLFreeHandle(SQLSMALLINT HandleType, SQLHANDLE Handle);

4.12.5.2 Параметры

HandleType [Input] тип дескриптора, который будет освобожден SQLFreeHandle. Должен быть одним из следующих значений:

Если HandleType не одно из этих значений, SQLFreeHandle возвращает SQL_INVALID_HANDLE.

Handle [Input] дескриптор, который будет освобожден.

4.12.5.3 Комментарии

Освобождение дескриптора среды:
До вызова SQLFreeHandle с HandleType равным SQL_HANDLE_ENV прикладная программа должна вызвать SQLFreeHandle с HandleType равным SQL_HANDLE_DBC для всех подключений, распределенных средой. Иначе обращение к SQLFreeHandle возвращает SQL_ERROR, а среда и любое активное подключение остаются прежними.

Освобождение дескриптора подключения:
До вызова SQLFreeHandle с HandleType равным SQL_HANDLE_DBC прикладная программа должна вызвать SQLDisconnect для подключения, если имеется подключение на этом дескрипторе. Иначе обращение к SQLFreeHandle возвращает SQL_ERROR, а подключение остается прежним.

Освобождение операторного дескриптора:
Обращение к SQLFreeHandle с HandleType равным SQL_HANDLE_STMT освобождает все ресурсы, которые были распределены обращением SQLAllocHandle с HandleType равным SQL_HANDLE_STMT. Когда из прикладной программы вызывается SQLFreeHandle, чтобы освободить инструкцию, которая имеет ждущие обработки результаты, они будут автоматически удалены. Обратите внимание, что SQLDisconnect автоматически уничтожает любые инструкции и дескрипторы, открытые на подключении.

4.12.6 SQLFreeConnect

SQLFreeConnect освобождает дескриптор подключения и всю память, связанную с этим дескриптором. В ODBC 3.x SQLFreeHandle заменил собой функцию ODBC 2.0 SQLFreeConnect.

4.12.7 SQLFreeEnv

SQLFreeEnv освобождает дескриптор среды и всю память, связанную с дескриптором среды. В ODBC 3.x SQLFreeHandle заменил собой функцию ODBC 2.0 SQLFreeEnv.