Эта глава руководства описывает каждую функцию (синтаксис, параметры и использование). Каждая функция определена как функция языка программирования C. Описания включают следующее:
ОБРАТИТЕ ВНИМАНИЕ: вообще все функции API возвращают
следующие коды возврата:
Функции работы с набором результатов, например, SQLFetch, SQLFetchScroll,
SQLGetData также умеют возвращать значения SQL_NO_DATA или
SQL_NO_DATA_FOUND. А функции SQLExecute, SQLExecDirect и
SQLParamData моугт возвращать SQL_NEED_DATA как код возврата
при поставке длинных данных порциями.
Прикладная программа может вызывать функцию SQLGetInfo, чтобы получить информацию соответствия относительно MyODBC. Чтобы получать информацию относительно поддержки специфической функции в драйвере, прикладная программа может вызывать SQLGetFunctions. Обратите внимание, что драйвер MyODBC 3.51 для обратной совместимости поддерживает все устаревшие функции. Имеется список MyODBC API, сгруппированый исходя из задач:
| Задача | Имя функции | MyODBC | MyODBC 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 | Да | Да | Устарела | Освобождает дескриптор среды. |
Этот раздел описывает, как устаревшие функции отображены 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 |
| SQLAllocConnect | SQLAllocHandle с SQL_HANDLE_DBC |
| SQLAllocEnv | SQLAllocHandle с SQL_HANDLE_ENV |
| SQLAllocStmt | SQLAllocHandle с SQL_HANDLE_STMT |
| SQLColAttributes | SQLColAttribute |
| SQLError | SQLGetDiagRec |
| SQLFreeConnect | SQLFreeHandle с SQL_HANDLE_DBC |
| SQLFreeEnv | SQLFreeHandle с SQL_HANDLE_ENV |
| SQLFreeStmt with SQL_DROP | SQLFreeHandle с SQL_HANDLE_STMT |
| SQLSetConnectOption | SQLSetConnectAttr |
| SQLGetConnectOption | SQLGetConnectAttr |
| SQLSetStmtAttr | SQLSetStmtAttr |
| SQLGetStmtAttr | SQLGetStmtAttr |
| SQLParamOptions | SQLSetStmtAttr |
| SQLSetScrollOption | SQLSetStmtAttr |
| SQLTransact | SQLEndTran |
SQLAllocHandle распределяет среду, подключение, инструкцию и дескриптор.
Обратите внимание, что это универсальная функция для распределения дескрипторов, которая заменяет функции SQLAllocConnect, SQLAllocEnv и SQLAllocStmt из ODBC 2.0. Чтобы позволить работать прикладным программам, вызывающим SQLAllocHandle, вызов SQLAllocHandle отображен в Driver Manager на SQLAllocConnect, SQLAllocEnv или SQLAllocStmt.
SQLRETURN SQLAllocHandle(SQLSMALLINT HandleType, SQLHANDLE InputHandle,
SQLHANDLE* OutputHandlePtr);
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] указывает на буфер, чтобы вернуть
дескриптор недавно распределенной структуры данных.
SQLAllocHandle используется, чтобы распределить дескрипторы
для сред, подключений и инструкций, как описано в следующих разделах.
Обратите внимание, что MyODBC не поддерживает описатели.
Сколько угодно дескрипторов могут быть распределены прикладной программой одновременно, если драйвер поддерживает многократные распределения. В MyODBC никакое ограничение не определено на число дескрипторов, которые могут быть распределены в любой момент времени.
Если вызов с *OutputHandlePtr определяет дескриптор, который уже определен, он будет просто переопределен.
Обратите внимание, что это является неправильным ODBC
программированием! Нельзя дважды вызывать SQLAllocHandle с той
же самой переменной прикладной программы, определенной для *OutputHandlePtr
без того, чтобы вызвать SQLFreeHandle, чтобы освободить
дескриптор перед его перераспределением. Перезапись ODBC-дескриптора таким
способом может привести к противоречивому поведению или сбою.
SQLAllocHandle не устанавливает атрибут среды
SQL_ATTR_ODBC_VERSION, когда вызван, чтобы распределить дескриптор среды:
атрибут среды должен быть установлен прикладной программой или будет
возвращена SQLSTATE HY010 (Function sequence error), когда SQLAllocHandle
вызвана, чтобы распределить дескриптор подключения.
Распределение дескриптора среды:
Дескриптор среды обеспечивает доступ к глобальной информации типа имеющих
силу и активных дескрипторов подключения.
Распределение дескриптора подключения:
Дескриптор подключения обеспечивает доступ к информации типа имеющих силу
операторных дескрипторов подключения и открытых в настоящее время транзакций.
Распределение операторного дескриптора:
Операторный дескриптор обеспечивает доступ к операторной информации, типа
сообщений об ошибках, имени курсора и информации состояния для
обработки инструкции SQL.
SQLAllocEnv распределяет память для дескриптора среды.
SQLRETURN SQLAllocEnv(HENV* EnvironmentHandle);
В ODBC 3.x SQLAllocHandle заменила функцию SQLAllocEnv из ODBC 2.x.
SQLAllocConnect распределяет память для дескриптора подключения.
SQLRETURN SQLAllocConnect(HENV EnvironmentHandle, HDBC* ConnectionHandle);
В ODBC 3.x SQLAllocHandle заменила функцию SQLAllocConnect из ODBC 2.x.
SQLConnect устанавливает связи с драйвером и источником данных. Дескриптор подключения ссылается на адрес в памяти всей информации относительно подключению к источнику данных, включая состояние подключения и транзакции, а также информацию об ошибках.
SQLRETURN SQLConnect(SQLHDBC ConnectionHandle, SQLCHAR* ServerName,
SQLSMALLINT NameLength1, SQLCHAR* UserName,
SQLSMALLINT NameLength2, SQLCHAR* Authentication,
SQLSMALLINT NameLength3);
ConnectionHandle[Input] дескриптор подключения.
ServerName[Input] имя источника данных.
NameLength1[Input] длина *ServerName.
UserName[Input] User id.
NameLength2[Input] длина *UserName.
Authentication[Input] строка авторизации (обычно это пароль).
NameLength3[Input] длина *Authentication.
Подробно использование данной функции описано в разделе "3.4.5 Установление подключения, используя MyODBC".
SQLDriverConnect является альтернативой SQLConnect. Это поддерживает источники данных, которые требуют большего количества информации подключения чем три параметра в SQLConnect, диалоговые окна, чтобы запросить пользователя относительно всей информации о подключении, и источники данных, которые не определены в информации системы.
SQLDriverConnect обеспечивает следующие возможности подключения:
После того, как подключение установлено, SQLDriverConnect вернет завершенную строку подключения. Прикладная программа может использовать ее для выполнения последующих запросов подключения.
SQLRETURN SQLDriverConnect(SQLHDBC ConnectionHandle, SQLHWND WindowHandle,
SQLCHAR* InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR* OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT* StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
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.
Не поддерживается.
SQLDataSources возвращает информацию относительно источника данных. Эта функция выполнена исключительно в Driver Manager. Для получения большего количества информации относительно этого API обратитесь к документации на соответствующий Driver Manager.
SQLDrivers вносит в список описания драйверов и ключевые слова атрибутов драйверов. Эта функция выполнена исключительно Driver Manager. Для получения большего количества информации относительно этого API обратитесь к документации на соответствующий Driver Manager.
SQLGetInfo возвращает общую информацию относительно драйвера и сервера, связанных с подключением.
4.4.3.1 Синтаксис
SQLRETURN SQLGetInfo(SQLHDBC ConnectionHandle, SQLUSMALLINT InfoType,
SQLPOINTER InfoValuePtr, SQLSMALLINT BufferLength,
SQLSMALLINT* StringLengthPtr);
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.
SQLGetFunctions возвращает информацию относительно того, поддерживает ли драйвер специфическую функцию ODBC.
4.4.4.1 Синтаксис
SQLRETURN SQLGetFunctions(SQLHDBC ConnectionHandle, SQLUSMALLINT FunctionId,
SQLUSMALLINT* SupportedPtr);
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.
SQLGetTypeInfo возвращает информацию относительно типов данных, поддержанных сервером. Драйвер возвращает информацию в форме набора результатов SQL. Типы данных предназначены для использования в инструкциях Data Definition Language (DDL). Прикладные программы должны использовать имена типов, возвращенные в столбце TYPE_NAME набора результатов SQLGetTypeInfo. Для команд ALTER TABLE и CREATE TABLE возможен возврат больше, чем одной строки с тем же самым значением в DATA_TYPE столбце.
SQLRETURN SQLGetTypeInfo(SQLHSTMT StatementHandle, SQLSMALLINT DataType);
StatementHandle [Input] операторный дескриптор
для набора результатов.
DataType [Input] SQL-тип данных. SQL_ALL_TYPES определяет,
что должна быть возвращена информация относительно всех типов данных.
SQLSetConnectAttr устанавливает атрибуты, которые управляют аспектами подключений.
SQLRETURN SQLSetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER StringLength);
ConnectionHandle [Input] дескриптор подключения.
Attribute [Input] атрибут для установки.
ValuePtr [Input] указатель на значение, которое будет связано
с атрибутом. В зависимости от значения атрибута, ValuePtr будет 32-разрядным
целым числом без знака или указателем на строку символов с нулем в конце.
Обратите внимание, что если параметр Attribute представляет собой
специфическое для драйвера значение, то ValuePtr может быть целым
числом со знаком.
StringLength [Input] если Attribute определен в ODBC и
ValuePtr указывает на строку или на двоичный буфер, этот параметр должен
быть длиной *ValuePtr. Если Attribute определен в ODBC и ValuePtr является
целым числом, StringLength игнорируется.
Имеется список атрибутов подключения, которые поддержаны драйвером 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_MODE | 32-битный дескриптор окна (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_OPTION | 32-битный параметр, который передано к трансляции DLL. |
| SQL_ATTR_TXN_ISOLATION | 32-битная маска, которая устанавливает уровень изоляции транзакции для текущего подключения. Прикладная программа должна вызвать SQLEndTran для завершения или отмены всех открытых транзакций на подключении перед вызовом SQLSetConnectAttr с этой опцией. Имеющие силу значения для ValuePtr могут быть определены, вызывая SQLGetInfo с InfoType равным SQL_TXN_ISOLATION_OPTIONS. |
SQLGetConnectAttr возвращает текущую установку некоего атрибута подключения.
SQLRETURN SQLGetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER BufferLength,
SQLINTEGER* StringLengthPtr);
ConnectionHandle [Input] дескриптор подключения.
Attribute [Input] интересующий атрибут.
ValuePtr [Input] указатель на память предназначенный, чтобы
возвращать текущее значение атрибута.
BufferLength [Input]Если Attribute представляет собой
ODBC-атрибут и ValuePtr указывает на символьную строку или двоичный буфер,
этот параметр должен быть длиной *ValuePtr. Если же *ValuePtr не указатель, а
целое число, BufferLength игнорируется.
StringLengthPtr [Output] указатель на буфер предназначенный,
чтобы возвращать общее количество байт, доступных в *ValuePtr (кроме нулевых
символов в конце). Если *ValuePtr равен null, длина не возвращена. Если
значением атрибута является символьная строка, и число байт больше
BufferLength, данные в *ValuePtr обрезаются до BufferLength.
В ODBC 3.x SQLSetConnectAttr заменяет SQLSetConnectOption.
В ODBC 3.x SQLGetConnectAttr заменяет SQLGetConnectOption.
SQLSetEnvAttr устанавливает атрибуты, которые управляют аспектами сред.
SQLRETURN SQLSetEnvAttr(SQLHENV EnvironmentHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER StringLength);
EnvironmentHandle [Input] дескриптор среды.
Attribute [Input] атрибут для установки.
ValuePtr [Input] указатель на значение, которое будет связано
с Attribute. В зависимости от значения Attribute, ValuePtr будет 32-битным
целочисленным значением или указателем на символьную строку с
нулевым символом в конце.
StringLength [Input]: если ValuePtr указатель на символьную
строку с нулевым символом в конце или на двоичный буфер, здесь хранится длина
*ValuePtr. Если ValuePtr представляет собой целое число,
StringLength игнорируется.
Прикладная программа может вызывать SQLSetEnvAttr только, если никакой дескриптор подключения не распределен в текущей среде. Все атрибуты среды устанавливаются прикладной программой до обращения SQLFreeHandle. Следующая таблица вносит в список различные атрибуты среды, поддержанные драйвером:
| Атрибут | Содержимое ValuePtr |
| SQL_ATTR_CONNECTION_POOLING | 32-битное значение SQLUINTEGER, которое включает или отключает объединение подключений. |
| SQL_ATTR_CP_MATCH | 32-битное значение SQLUINTEGER, которое определяет как подключение выбрано из объединения подключений. Обратитесь к документации на конкретный Driver Manager за подробностями. |
| SQL_ATTR_ODBC_VERSION | 32-битное целое значение, которое
определяет проявляют ли функциональные возможности поведение ODBC 2.x или
ODBC 3.x. Следующие значения используются, чтобы установить значение этого
атрибута: SQL_OV_ODBC3 и SQL_OV_ODBC2. |
| SQL_ATTR_OUTPUT_NTS | 32-битное целое значение, которое определяет как драйвер возвращает строчные данные. Если SQL_TRUE, драйвер возвращает строки с нулевым символом в конце. Если SQL_FALSE, драйвер этого не делает. Сейчас драйвер поддерживает только значение по умолчанию SQL_TRUE. |
SQLGetEnvAttr возвращает текущую установку атрибута среды.
SQLRETURN SQLGetEnvAttr(SQLHENV EnvironmentHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER BufferLength,
SQLINTEGER* StringLengthPtr);
EnvironmentHandle [Input] дескриптор среды.
Attribute [Input] атрибут, значение которого нужно получить.
ValuePtr [Output] указатель на буфер нужный, чтобы возвращать
текущее значение атрибута, определенного Attribute.
BufferLength [Input] если ValuePtr указывает на символьную
строку, этот параметр должен быть длиной *ValuePtr. Если *ValuePtr целое
число, BufferLength игнорируется. Если значение атрибута не строка,
BufferLength не применяется.
StringLength [Output] указатель на буфер предназначенный,
чтобы возвращать общее количество байт, доступных в *ValuePtr (кроме нулевых
символов в конце). Если *ValuePtr равен null, длина не возвращена. Если
значением атрибута является символьная строка, и число байт больше
BufferLength, данные в *ValuePtr обрезаются до BufferLength.
SQLSetStmtAttr устанавливает атрибуты, связанные с инструкцией.
SQLRETURN SQLSetStmtAttr(SQLHSTMT StatementHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER StringLength);
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
может иметь следующие значения:
Операторные атрибуты для инструкции остаются в силе, пока они не изменены другим обращением SQLSetStmtAttr.
| Атрибут | Значение ValuePtr |
| SQL_ATTR_APP_PARAM_DESC | Не поддерживается |
| SQL_ATTR_APP_ROW_DESC | Не поддерживается |
| SQL_ATTR_ASYNC_ENABLE | Значение SQLUINTEGER, которое
определяет выполнена ли функция асинхронно: SQL_ASYNC_ENABLE_OFF=Off
(значение по умолчанию), |
| 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 | Закладки не поддерживаются. |
SQLGetStmtAttr возвращает текущую установку операторного атрибута.
SQLRETURN SQLGetStmtAttr(SQLHSTMT StatementHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER BufferLength,
SQLINTEGER* StringLengthPtr);
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.
В ODBC 3.x SQLSetStmtAttr заменяет SQLStmtOption.
В ODBC 3.x SQLGetStmtAttr заменяет SQLCetStmtOption.
SQLAllocStmt распределяет память для операторного дескриптора.
SQLRETURN SQLAllocStmt(HDBC ConnectionHandle, HSTMT* StatementHandle);
В ODBC 3.x SQLAllocHandle заменяет функцию ODBC 2.x SQLAllocStmt.
SQLPrepare готовит команду SQL к выполнению.
SQLRETURN SQLPrepare(SQLHSTMT StatementHandle, SQLCHAR* StatementText,
SQLINTEGER TextLength);
StatementHandle [Input] операторный дескриптор.
StatementText [Input] строка SQL-команды.
TextLength [Input] длина *StatementText.
SQLBindParameter привязывает буфер к маркеру параметра в инструкции SQL. SQLBindParameter поддерживает связывание к Unicode-C типу данных, даже если основной драйвер не поддерживает Unicode-данные.
SQLRETURN SQLBindParameter(SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT InputOutputType,
SQLSMALLINT ValueType, SQLSMALLINT ParameterType,
SQLUINTEGER ColumnSize, SQLSMALLINT DecimalDigits,
SQLPOINTER ParameterValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER* StrLen_or_IndPtr);
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] указатель на буфер
для длины параметра.
SQLGetCursorName возвращает имя курсора, связанного с определенной инструкцией.
SQLRETURN SQLGetCursorName(SQLHSTMT StatementHandle, SQLCHAR* CursorName,
SQLSMALLINT BufferLength,
SQLSMALLINT* NameLengthPtr);
StatementHandle [Input] дескриптор подключения.
CursorName [Output] указатель на буфер для имени курсора.
BufferLength [Input] длина *CursorName в байтах.
NameLengthPtr [Output] указатель на память, куда будет
записано возвращаемое значение. Если значение больше, чем BufferLength,
*CursorName урезается до BufferLength за вычетом хвостового нуля.
SQLSetCursorName сопоставляет имя курсора с активной инструкцией. Если прикладная программа не вызывает SQLSetCursorName, драйвер генерирует имена курсора так, как необходимо для обработки инструкции SQL.
4.6.5.1 Синтаксис
SQLRETURN SQLSetCursorName(SQLHSTMT StatementHandle, SQLCHAR* CursorName,
SQLSMALLINT NameLength);
StatementHandle [Input] операторный дескриптор.
CursorName [Input] имя курсора. Для эффективной обработки имя
курсора не должно включить никаких пробелов, а если имя курсора включает
разграниченный идентификатор, разделитель должен быть установлен как первый
символ в имени курсора.
NameLength [Input] длина *CursorName.
В ODBC 3.x SQLSetSetScrollOptions заменен обращением к 4.5.7 SQLSetStmtAttr и 4.4.3 SQLGetInfo.
SQLExecute выполняет подготовленную инструкцию, используя текущие (актуальные) значения переменных маркера параметра, если маркеры параметров существуют в инструкции.
4.7.1.1 Синтаксис
SQLRETURN SQLExecute(SQLHSTMT StatementHandle);
StatementHandle [Input] операторный дескриптор.
SQLExecute выполняет инструкцию, подготовленную SQLPrepare.
SQLExecDirect выполняет инструкцию, используя текущие (актуальные) значения переменных маркера параметра, если параметры существуют в инструкции. SQLExecDirect представляет собой самый быстрый способ представить серверу на рассмотрение инструкцию SQL для одного выполнения.
4.7.2.1 Синтаксис
SQLRETURN SQLExecDirect(SQLHSTMT StatementHandle, SQLCHAR* StatementText,
SQLINTEGER TextLength);
StatementHandle [Input] операторный дескриптор.
StatementText [Input] SQL-инструкция, которая будет выполнена.
TextLength [Input] длина *StatementText.
Прикладные программы вызывают SQLExecDirect, чтобы послать инструкцию SQL на сервер MySQL.
SQLNativeSql возвращает строку SQL, обработанную драйвером. SQLNativeSql не выполняет инструкцию SQL.
4.7.3.1 Синтаксис
SQLRETURN SQLNativeSql(SQLHDBC ConnectionHandle, SQLCHAR* InStatementText,
SQLINTEGER TextLength1, SQLCHAR* OutStatementText,
SQLINTEGER BufferLength, SQLINTEGER* TextLength2Ptr);
ConnectionHandle [Input] дескриптор подключения.
InStatementText [Input] текст инструкции SQL.
TextLength1 [Input] длина строки *InStatementText.
OutStatementText [Output] указатель на буфер распределенный,
чтобы возвращать строку SQL.
BufferLength [Input] длина буфера *OutStatementText.
TextLength2Ptr [Output] указатель на буфер выделенный, чтобы
возвращать общее количество байт, доступное в *OutStatementText. Если число
доступных байт больше BufferLength, *OutStatementText урезается.
SQLDescribeParam возвращает описание маркера параметра, связанного с подготовленной инструкцией SQL.
SQLRETURN SQLDescribeParam(SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT* DataTypePtr,
SQLUINTEGER* ParameterSizePtr,
SQLSMALLINT* DecimalDigitsPtr,
SQLSMALLINT* NullablePtr);
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. Один из следующего:
SQL_NO_NULLS: параметр не позволяет значения NULL (это
значение по умолчанию).
SQL_NULLABLE: параметр позволяет значения NULL.
SQL_NULLABLE_UNKNOWN: драйвер не может определить, позволяет
ли параметр значения NULL.SQLNumParams возвращает число параметров в инструкции SQL.
SQLRETURN SQLNumParams(SQLHSTMT StatementHandle,
SQLSMALLINT* ParameterCountPtr);
StatementHandle [Input] операторный дескриптор.
ParameterCountPtr [Output] указатель на буфер распределенный,
чтобы возвращать число параметров в инструкции.
SQLParamData используется вместе с SQLPutData, чтобы обеспечить данные для параметров во время выполнения.
4.7.6.1 Синтаксис
SQLRETURN SQLParamData(SQLHSTMT StatementHandle, SQLPOINTER* ValuePtrPtr);
StatementHandle [Input] операторный дескриптор.
ValuePtrPtr [Output] указатель на буфер выделенный, чтобы
возвращать адрес буфера ParameterValuePtr, определенного в SQLBindParameter
(для данных параметра) или адрес буфера TargetValuePtr, определенного в
SQLBindCol (для данных столбца), как указано в поле SQL_DESC_DATA_PTR
записи операторного дескриптора.
SQLPutData позволяет прикладной программе посылать данные для параметра или столбца драйверу во время выполнения. Эта функция может использоваться, чтобы послать символьные или двоичные значения данных частями к столбцу со специфическим типом данных (например, параметры типов SQL_LONGVARBINARY или SQL_LONGVARCHAR). SQLPutData поддерживает связывание с Unicode C-типом данных, даже если основной драйвер не поддерживает Unicode.
4.7.7.1 Синтаксис
SQLRETURN SQLPutData(SQLHSTMT StatementHandle, SQLPOINTER DataPtr,
SQLINTEGER StrLen_or_Ind);
StatementHandle [Input] операторный дескриптор.
DataPtr [Input] указатель на буфер с актуальными данными для
для параметра или столбца. Данные должны быть в C-типе данных, определенном в
параметре ValueType функции SQLBindParameter (для данных параметра) или в
параметре TargetType функции SQLBindCol (для данных столбца).
StrLen_or_Ind [Input] длина *DataPtr. Определяет количество
данных, переданное в вызове SQLPutData. Количество данных может измениться
для каждого вызова. StrLen_or_Ind игнорируется, если не выполняется одно
из следующих условий:
SQLRowCount возвращает число строк, на которые воздействует инструкция UPDATE, INSERT или DELETE.
SQLRETURN SQLRowCount(SQLHSTMT StatementHandle, SQLINTEGER* RowCountPtr);
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 или функцией каталога перед выборкой строк.
Обратите внимание, что много источников данных не могут
возвращать число строк в наборе результатов перед их выборкой.
SQLNumResultCols возвращает число столбцов в наборе результатов.
SQLRETURN SQLNumResultCols(SQLHSTMT StatementHandle,
SQLSMALLINT* ColumnCountPtr);
StatementHandle [Input] операторный дескриптор.
ColumnCountPtr [Output] указатель на буфер, в который будет
записано число столбцов в наборе результатов.
SQLDescribeCol возвращает имя дескрипторного столбца результата, тип, размер столбца, десятичные цифры и возможность принимать значение null для одного столбца в наборе результатов. Эта информация также доступна в полях IRD.
SQLRETURN SQLDescribeCol(SQLHSTMT StatementHandle, SQLSMALLINT ColumnNumber,
SQLCHAR* ColumnName, SQLSMALLINT BufferLength,
SQLSMALLINT* NameLengthPtr,
SQLSMALLINT* DataTypePtr,
SQLUINTEGER* ColumnSizePtr,
SQLSMALLINT* DecimalDigitsPtr,
SQLSMALLINT* NullablePtr);
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. Значение одно из следующего:
SQL_NO_NULLS: столбец не позволяет значения NULL.
SQL_NULLABLE: столбец позволяет значения NULL.
SQL_NULLABLE_UNKNOWN: драйвер не может определить, позволяет
ли столбец значения NULL.SQLColAttribute возвращает дескрипторную информацию для столбца в наборе результатов. Дескрипторная информация будет возвращена как символьная строка, 32-разрядное дескрипторно-зависимое значение или целочисленное значение.
SQLRETURN SQLColAttribute(SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLUSMALLINT FieldIdentifier,
SQLPOINTER CharacterAttributePtr,
SQLSMALLINT BufferLength,
SQLSMALLINT* StringLengthPtr,
SQLPOINTER NumericAttributePtr);
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. Иначе поле не используется.
В ODBC 3.x SQLColAttributes заменена SQLColAttribute.
SQLBindCol привязывает буферы данных прикладных программ к столбцам в наборе результатов.
SQLRETURN SQLBindCol(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber,
SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr,
SQLINTEGER BufferLength, SQLLEN* StrLen_or_Ind);
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, значения длины или индикаторов не применяются.
SQLFetch выбирает следующий rowset данных из набора результатов и возвращает данные для всех связанных столбцов.
SQLRETURN SQLFetch(SQLHSTMT StatementHandle);
StatementHandle [Input] операторный дескриптор.
SQLFetch возвращает следующий rowset в наборе результатов. Это может быть вызвано только в то время, когда набор результатов существует, то есть после обращения, которое создает набор результатов и прежде, чем курсор будет закрыт. Если любые столбцы связаны с данными, этот вызов возвращает данные в этих столбцах. Если прикладная программа определила указатель на массив состояния или на буфер нужный, чтобы возвращать число выбранных строк, SQLFetch возвращает также и эту информацию. Обращение к SQLFetch может быть смешано с обращениями к SQLFetchScroll, но не может быть смешано с обращениями к SQLExtendedFetch.
SQLFetchScroll выбирает определенный rowset данных из набора результатов и возвращает данные для всех связанных столбцов. Rowset может быть определен в абсолютной или относительной позиции или закладкой. При работе с драйвером ODBC 2.x Driver Manager отображает эту функцию на SQLExtendedFetch.
SQLRETURN SQLFetchScroll(SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLINTEGER FetchOffset);
StatementHandle [Input] операторный дескриптор.
FetchOrientation [Input] тип выборки:
FetchOffset [Input] номер строки для выборки. Интерпретация
этого параметра зависит от значения параметра FetchOrientation.
Когда набор результатов создан, курсор установлен перед началом набора результатов. 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. |
SQLExtendedFetch выбирает определенный rowset данных из набора результатов и возвращает данные для всех связанных столбцов. Rowset может быть определен в абсолютной или относительной позиции.
Обратите внимание в ODBC 3.x SQLExtendedFetch заменен на
SQLFetchScroll. Прикладные программы ODBC 3.x не должны вызвать
SQLExtendedFetch: взамен они должны вызвать SQLFetchScroll.
SQLRETURN SQLExtendedFetch(SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLINTEGER FetchOffset, SQLUINTEGER* RowCountPtr,
SQLUSMALLINT* RowStatusArray);
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. Если это не так, последствия будут непредсказуемыми.
Логика работы SQLExtendedFetch идентична SQLFetchScroll, но:
SQLGetData получает данные для одиночного столбца в наборе результатов. Это может быть вызвано неоднократно, чтобы получить данные переменной длины по частям.
SQLRETURN SQLGetData(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber,
SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr,
SQLINTEGER BufferLength, SQLINTEGER* StrLen_or_IndPtr);
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 может возвращать следующие значения в буфере длин/индикатора:
SQLSetPos устанавливает позицию курсора в rowset и позволяет прикладной программе обновить данные в rowset, модифицировать или удалять данные в наборе результатов.
SQLRETURN SQLSetPos(SQLHSTMT StatementHandle, SQLUSMALLINT RowNumber,
SQLUSMALLINT Operation, SQLUSMALLINT LockType);
StatementHandle [Input]] операторный дескриптор.
RowNumber [Input] позиция строки в rowset над которой надо
выполнить операцию, определенную параметром Operation. Если RowNumber равен
0, операция применяется к каждой строке в rowset.
Operation [Input] операция для выполнения:
LockType [Input] определяет, как блокировать строку после
выполнения операции, определенной в параметре Operation:
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. |
SQLBulkOperations выполняет оптовые вставки и операции закладки, включая update, delete и выборку по закладке.
SQLRETURN SQLBulkOperations(SQLHSTMT StatementHandle,
SQLUSMALLINT Operation);
StatementHandle [Input] операторный дескриптор.
Operation [Input] операция для выполнения:
SQL_ADD. Обратите внимание: сейчас никакие операции с закладками
драйвером не поддерживаются.
Выполнение оптовых вставок:
Чтобы вставлять данные с помощью SQLBulkOperations, прикладная программа выполняет следующую последовательность шагов:
SQLBindCol, чтобы привязать данные, которые
требуется вставлять. Данные будут привязаны к массиву с размером, равным
значению SQL_ATTR_ROW_ARRAY_SIZE. Обратите внимание, что размер массива,
указанного атрибутом инструкции SQL_ATTR_ROW_STATUS_PTR должен быть равен
SQL_ATTR_ROW_ARRAY_SIZE, или SQL_ATTR_ROW_STATUS_PTR должен быть null.
SQLBulkOperations(StatementHandle,
SQL_ADD), чтобы выполнить вставку.
SQLError возвращает информацию состояния или ошибку. Прикладная программа обычно вызывает SQLError, когда предыдущая функция ODBC возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO. В ODBC 3.x SQLGetDiagRec заменила функцию ODBC 2.0 SQLError.
SQLGetDiagField возвращает текущее (актуальное) значение поля записи диагностической структуры данных (связанной с определенным дескриптором), которое содержит ошибку, предупреждение и информацию состояния.
SQLRETURN SQLGetDiagField(SQLSMALLINT HandleType, SQLHANDLE Handle,
SQLSMALLINT RecNumber, SQLSMALLINT DiagIdentifier,
SQLPOINTER DiagInfoPtr, SQLSMALLINT BufferLength,
SQLSMALLINT* StringLengthPtr);
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 (только для
символьных данных, хвостовые нули не считаются).
SQLGetDiagField не регистрирует диагностические записи для себя. Это использует следующие значения возврата, чтобы сообщить результат собственного выполнения:
Прикладная программа обычно вызывает SQLGetDiagField, чтобы выполнить одну из трех целей:
DiagIdentifier: ниже приведен полный список диагностических идентификаторов, поддержанных драйвером.
| DiagIdentifier | Тип возврата | Возвращаемое значение |
| SQL_DIAG_CURSOR_ROW_COUNT | SQLINTEGER | Это поле содержит число строк в курсоре. |
| SQL_DIAG_NUMBER | SQLINTEGER | Число записей состояния, которые являются доступными для определенного дескриптора. В настоящее время драйвер всегда возвращает 1. |
| SQL_DIAG_RETURNCODE | SQLRETURN | Код возврата, возвращенный функцией. |
| SQL_DIAG_ROW_COUNT | SQLINTEGER | Число строк, на которые воздействует операция insert, delete или update, вызванная через SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos. |
| SQL_DIAG_CLASS_ORIGIN | SQLCHAR* | Строка, которая указывает документ который определяет часть класса значения SQLSTATE в этой записи. Значение "ISO 9075" для всех SQLSTATE определено X/Open и интерфейсом уровня обращения ISO. Для ODBC-специфических SQLSTATE (все те, чей класс SQLSTATE равен "IM"), это значение равно "ODBC 3.0". |
| SQL_DIAG_COLUMN_NUMBER | SQLINTEGER | Если поле SQL_DIAG_ROW_NUMBER представляет собой имеющий силу номер строки в наборе строк или наборе параметров, это поле содержит значение, которое представляет номер столбца в наборе результатов или номер параметра в наборе параметров. Номера столбцов всегда начинаются с 1. Если эта запись состояния относится к столбцу закладки, поле может быть нулевым. Номера параметров начинаются с 1. Это имеет значение SQL_NO_COLUMN_NUMBER, если запись состояния не связана с номером столбца или номером параметра. Если драйвер не может определять номер столбца или номер параметра, с которым эта запись связана, это поле имеет значение SQL_COLUMN_NUMBER_UNKNOWN. Содержимое этого поля определено только для операторных дескрипторов. |
| SQL_DIAG_CONNECTION_ NAME | SQLCHAR* | Строка, которая указывает имя подключения, к которому относится эта диагностическая запись. Драйвер возвращает DSN как имя подключения, а для DSN-LESS-подключения это поле является строкой нулевой длины. |
| SQL_DIAG_MESSAGE_TEXT | SQLCHAR* | Информационное сообщение об ошибке или текста предупреждения. Подробности ниже. |
| SQL_DIAG_NATIVE | SQLINTEGER | Исходно-специфический местный код ошибки драйвера или данных. Если не имеется никакого местного кода ошибки, драйвер возвращает 0. |
| SQL_DIAG_ROW_NUMBER | SQLINTEGER | Это поле содержит номер строки в наборе строк, или номер параметра в наборе параметров, с которыми запись состояния связана. Номера начинаются с 1. Это поле имеет значение SQL_NO_ROW_NUMBER, если эта запись состояния не связана с номером строки или параметра. Если драйвер не может определять номер строки или параметра, с которым эта запись связана, это поле имеет значение SQL_ROW_NUMBER_UNKNOWN. Содержимое этого поля определено только для операторных дескрипторов. |
| SQL_DIAG_SERVER_NAME | SQLCHAR* | Строка, которая указывает имя сервера для этой диагностической записи. Это равно значению, возвращенному для обращения к SQLGetInfo с опцией SQL_DATA_SOURCE_NAME. |
| SQL_DIAG_SQLSTATE | SQLCHAR* | Код диагностики пятисимвольного SQLSTATE. |
| SQL_DIAG_SUBCLASS_ORIGIN | SQLCHAR* | Строка с тем же самым форматом и имеющими силу значениями, что и SQL_DIAG_CLASS_ORIGIN, которая идентифицирует часть определения части подкласса кода SQLSTATE. ODBC-специфические SQLSTATE для ODBC 3.0 возвращаются. |
SQLGetDiagRec возвращает текущие значения нескольких полей диагностической записи, которая содержит ошибку, предупреждение и информацию состояния. В отличие от SQLGetDiagField, которая возвращает одно диагностическое поле на обращение, SQLGetDiagRec возвращает несколько обычно используемых полей диагностической записи, включая SQLSTATE, местный код ошибки и диагностический текст сообщения.
SQLRETURN SQLGetDiagRec(SQLSMALLINT HandleType, SQLHANDLE Handle,
SQLSMALLINT RecNumber, SQLCHAR* Sqlstate,
SQLINTEGER* NativeErrorPtr, SQLCHAR* MessageText,
SQLSMALLINT BufferLength, SQLSMALLINT* TextLengthPtr);
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 (кроме хвостовых нулей).
Прикладная программа обычно вызывает SQLGetDiagRec, когда предыдущее обращение к функции ODBC возвратило SQL_SUCCESS или SQL_SUCCESS_WITH_INFO. Однако, поскольку любая функция ODBC может регистрировать ноль или большее количество диагностических записей каждый вызов, прикладная программа может вызывать SQLGetDiagRec после любого обращения к функции ODBC.
SQLColumnPrivileges возвращает список столбцов и связанных привилегий для определенной таблицы. Драйвер возвращает информацию как набор результатов на определенном StatementHandle.
SQLRETURN SQLColumnPrivileges(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLCHAR* ColumnName,
SQLSMALLINT NameLength4);
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.
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);
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.
SQLForeignKeys может вернуть:
Драйвер возвращает каждый список в наборе результатов на определенной инструкции.
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);
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 в байтах.
SQLPrimaryKeys возвращает имена столбцов, которые составляют первичный ключ для таблицы. Драйвер возвращает информацию в наборе результатов. Эта функция не поддерживает первичные ключи из нескольких таблиц сразу в одном обращении.
SQLRETURN SQLPrimaryKeys(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3);
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не
имеют имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть
null. TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
SQLSpecialColumns возвращает следующую информацию относительно столбцов внутри определенной таблицы:
SQLRETURN SQLSpecialColumns(SQLHSTMT StatementHandle,
SQLSMALLINT IdentifierType, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLSMALLINT Scope,
SQLSMALLINT Nullable);
StatementHandle [Input] операторный дескриптор.
IdentifierType [Input] тип столбца для возврата. Должен быть
одним из следующих значений:
SQL_BEST_ROWID: возвращает оптимальный столбец или набор
столбцов, который позволяет уникально идентифицировать любую строку в
определенной таблице. Столбец может быть столбцом (или набором столбцов)
любого уникального индекса для таблицы или псевдостолбцом, специально
разработанным для этой цели.
SQL_ROWVER: возвращает столбец или столбцы в определенной
таблице, которые автоматически модифицируются источником данных, когда любое
значение в строке модифицируется транзакцией (если такие столбцы есть).CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не
имеют имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть
null. TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
Scope [Input] минимум требуемой области rowid. Возвращенный
rowid может иметь большую область. Должен быть одним из следующего:
SQL_SCOPE_CURROW: rowid точно будет иметь силу только в
то время, когда выполнено позиционирование в эту строку. Более поздний
перевыбор, использующий rowid, не может возвращать строку, если строка
модифицирована или удалена другой транзакцией.
SQL_SCOPE_TRANSACTION: rowid будет иметь силу
для текущей транзакции.
SQL_SCOPE_SESSION: rowid будет иметь силу для текущего
сеанса связи (игнорируя границы транзакции).Nullable [Input] определяет, возвратить ли специальные
столбцы, которые могут иметь значение NULL. Должен быть одним из следующего:
SQL_NO_NULLS: исключить специальные столбцы, которые
могут иметь значения NULL. Некоторые драйверы не могут поддерживать
SQL_NO_NULLS, и эти драйверы возвратят пустой набор результатов, если был
определен SQL_NO_NULLS. Прикладные программы должны быть подготовлены к этому
случаю и запрашивать SQL_NO_NULLS только, если это абсолютно необходимо.
SQL_NULLABLE: вернуть специальные столбцы, даже если они
могут иметь значения NULL.SQLStatistics возвращает статистику относительно одной таблицы и индексов, связанных с этой таблицей. Драйвер возвращает информацию в наборе результатов.
SQLRETURN SQLStatistics(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLUSMALLINT Unique,
SQLUSMALLINT Reserved);
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 не возвращены):
SQL_ENSURE требует, чтобы драйвер безоговорочно получил
статистику. Драйверы, которые согласовываются только со стандартом X/Open и
не поддерживают ODBC-расширения, не способны поддерживать SQL_ENSURE.
SQL_QUICK требует, чтобы драйвер получил CARDINALITY и PAGES
только если они легко доступны с сервера. В этом случае драйвер не
гарантирует, что значения актуальны. Прикладные программы, которые написаны в
стандарте X/Open, будут всегда получать SQL_QUICK из драйверов ODBC 3.x.SQLTablePrivileges возвращает список таблиц и привилегий, связанных с каждой таблицей. Драйвер возвращает информацию в наборе результатов на определенной инструкции.
SQLRETURN SQLTablePrivileges(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3);
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не
имеют имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть
null. TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
SQLTables возвращает список имен таблиц, каталогов, схем и типов таблиц, сохраненных в специфическом источнике данных. Драйвер возвращает информацию в наборе результатов.
SQLRETURN SQLTables(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLCHAR* TableType,
SQLSMALLINT NameLength4);
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.
SQLTransact запрашивает завершение или отмену для всех активных операций на всех инструкциях, связанных с подключением. SQLTransact может также запрашивать это для всех подключений, связанных со средой. В ODBC 3.x SQLEndTran заменил функцию ODBC 2.x SQLTransact.
SQLEndTran запрашивает завершение или отмену для всех активных операций на всех инструкциях, связанных с подключением. SQLEndTran может также запрашивать это для всех подключений, связанных со средой.
SQLRETURN SQLEndTran(SQLSMALLINT HandleType, SQLHANDLE Handle,
SQLSMALLINT CompletionType);
HandleType [Input] идентификатор типа дескриптора. Содержит
SQL_HANDLE_ENV (если Handle дескриптор среды) или SQL_HANDLE_DBC (если Handle
представляет собой дескриптор подключения).
Handle [Input] дескриптор, тип коего задан в HandleType,
указывает контекст транзакции.
CompletionType [Input] одно из следующтх двух значений:
SQL_COMMIT или
SQL_ROLLBACK.SQLFreeStmt останавливает обработку, связанную со специфической инструкцией, закрывает любые открытые курсоры, связанные с этой инструкцией, отбрасывает ждущие обработки результаты и, факультативно, освобождает все ресурсы, связанные с операторным дескриптором.
SQLRETURN SQLFreeStmt(SQLHSTMT StatementHandle, SQLUSMALLINT Option);
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 для данного операторного дескриптора. |
SQLCloseCursor закрывает курсор, который был открыт на инструкции и отбрасывает ждущие обработки результаты.
SQLRETURN SQLCloseCursor(SQLHSTMT StatementHandle);
StatementHandle [Input] операторный дескриптор.
SQLCancel отменяет обработку инструкции.
SQLRETURN SQLCancel(SQLHSTMT StatementHandle);
StatementHandle [Input] операторный дескриптор.
SQLCancel может отменять следующие типы обработки инструкции:
В ODBC 2.x, если из прикладной программы вызвана SQLCancel, когда обработка не делается на инструкции, SQLCancel имеют тот же самый эффект, что и SQLFreeStmt с опцией SQL_CLOSE. Это поведение определено только для законченности реализации, и прикладные программы должны вызвать SQLFreeStmt или SQLCloseCursor, чтобы закрыть курсоры.
SQLDisconnect закрывает подключение, связанное со специфическим дескриптором подключения.
SQLRETURN SQLDisconnect(SQLHDBC ConnectionHandle);
ConnectionHandle [Input] дескриптор подключения.
Если из прикладной программы вызвана SQLDisconnect, в то время как имеется незавершенная транзакция, связанная с дескриптором подключения, драйвер возвращает SQLSTATE 25000 (Invalid transaction state) указывая, что транзакция является неизменяемой, и подключение открыто. Незавершенной транзакцией является такая, которая не была ни завершена, ни отменена с помощью вызова SQLEndTran.
Если из прикладной программы вызвана SQLDisconnect прежде, чем были освобождены все инструкции, связанные с подключением, драйвер после того, как успешно завершит отсоединение от сервера, освобождает те инструкции и все дескрипторы, которые были явно распределены на подключении.
SQLFreeHandle освобождает ресурсы, связанные со специфической средой, подключением, инструкцией или дескриптором.
Обратите внимание, что это универсальная функция для
освобождения дескрипторов. Это заменяет функции ODBC 2.0 SQLFreeConnect (для
освобождения дескриптора подключения) и SQLFreeEnv (для освобождения
дескриптора среды). SQLFreeConnect и SQLFreeEnv устарели в ODBC 3.x.
SQLFreeHandle также заменяет функцию ODBC 2.0 SQLFreeStmt (с Option равным
SQL_DROP) для освобождения операторного дескриптора.
SQLRETURN SQLFreeHandle(SQLSMALLINT HandleType, SQLHANDLE Handle);
HandleType [Input] тип дескриптора, который будет освобожден
SQLFreeHandle. Должен быть одним из следующих значений:
SQL_HANDLE_ENV,
SQL_HANDLE_DBC,
SQL_HANDLE_STMT или
SQL_HANDLE_DESC (не поддерживается)Если HandleType не одно из этих значений, SQLFreeHandle возвращает SQL_INVALID_HANDLE.
Handle [Input] дескриптор, который будет освобожден.
Освобождение дескриптора среды:
До вызова 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 автоматически уничтожает любые инструкции и дескрипторы,
открытые на подключении.
SQLFreeConnect освобождает дескриптор подключения и всю память, связанную с этим дескриптором. В ODBC 3.x SQLFreeHandle заменил собой функцию ODBC 2.0 SQLFreeConnect.
SQLFreeEnv освобождает дескриптор среды и всю память, связанную с дескриптором среды. В ODBC 3.x SQLFreeHandle заменил собой функцию ODBC 2.0 SQLFreeEnv.