Эта глава руководства описывает каждую функцию (синтаксис, параметры и
использование). Каждая функция определена как функция языка программирования C.
Описания включают следующее:
- Назначение
- Синтаксис
- Параметры
- Значения возврата
- Комментарии относительно использования
ОБРАТИТЕ ВНИМАНИЕ: вообще все функции API возвращают следующие
коды возврата:
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
Функции работы с набором результатов, например, SQLFetch, SQLFetchScroll,
SQLGetData также умеют возвращать значения SQL_NO_DATA или
SQL_NO_DATA_FOUND. А функции SQLExecute, SQLExecDirect и
SQLParamData моугт возвращать SQL_NEED_DATA как код возврата при
поставке длинных данных порциями.
Прикладная программа может вызывать функцию SQLGetInfo, чтобы получить
информацию соответствия относительно MyODBC. Чтобы получать информацию
относительно поддержки специфической функции в драйвере, прикладная программа
может вызывать SQLGetFunctions. Обратите внимание, что драйвер MyODBC 3.51 для
обратной совместимости поддерживает все устаревшие функции.
Имеется список
MyODBC API, сгруппированый исходя из задач:
Этот раздел описывает, как устаревшие функции отображены 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.
4.3.1.1 Синтаксис
SQLRETURN SQLAllocHandle(SQLSMALLINT HandleType, SQLHANDLE InputHandle,
SQLHANDLE* OutputHandlePtr);
4.3.1.2 Параметры
HandleType[Input] задает тип дескриптора, который будет
распределен SQLAllocHandle. Должно быть одним из следующих значений:
SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT или SQL_HANDLE_DESC (не
поддерживается драйвером).
InputHandle[Input] задает в каком контексте новый дескриптор
должен быть распределен. Если HandleType равен SQL_HANDLE_ENV, это будет
SQL_NULL_HANDLE. Если HandleType равен SQL_HANDLE_DBC, это должен быть
дескриптор среды, и HandleType равен SQL_HANDLE_STMT или SQL_HANDLE_DESC, это
будет дескриптор подключения.
OutputHandlePtr[Output] указывает на буфер, чтобы вернуть
дескриптор недавно распределенной структуры данных.
4.3.1.3 Комментарии
SQLAllocHandle используется, чтобы распределить дескрипторы для
сред, подключений и инструкций, как описано в следующих разделах. Обратите
внимание, что MyODBC не поддерживает описатели.
Сколько угодно дескрипторов могут быть распределены прикладной программой
одновременно, если драйвер поддерживает многократные распределения. В MyODBC
никакое ограничение не определено на число дескрипторов, которые могут быть
распределены в любой момент времени.
Если вызов с *OutputHandlePtr определяет дескриптор, который уже определен,
он будет просто переопределен.
Обратите внимание, что это является неправильным ODBC
программированием! Нельзя дважды вызывать SQLAllocHandle с той же
самой переменной прикладной программы, определенной для *OutputHandlePtr без
того, чтобы вызвать SQLFreeHandle, чтобы освободить дескриптор
перед его перераспределением. Перезапись ODBC-дескриптора таким способом может
привести к противоречивому поведению или сбою.
SQLAllocHandle не устанавливает атрибут среды
SQL_ATTR_ODBC_VERSION, когда вызван, чтобы распределить дескриптор среды:
атрибут среды должен быть установлен прикладной программой или будет возвращена
SQLSTATE HY010 (Function sequence error), когда SQLAllocHandle вызвана, чтобы
распределить дескриптор подключения.
Распределение дескриптора среды:
Дескриптор среды
обеспечивает доступ к глобальной информации типа имеющих силу и активных
дескрипторов подключения.
Распределение дескриптора подключения:
Дескриптор
подключения обеспечивает доступ к информации типа имеющих силу операторных
дескрипторов подключения и открытых в настоящее время транзакций.
Распределение операторного дескриптора:
Операторный
дескриптор обеспечивает доступ к операторной информации, типа сообщений об
ошибках, имени курсора и информации состояния для обработки инструкции SQL.
SQLAllocEnv распределяет память для дескриптора среды.
4.3.2.1 Синтаксис
SQLRETURN SQLAllocEnv(HENV* EnvironmentHandle);
4.3.2.2 Комментарии
В ODBC 3.x SQLAllocHandle заменила функцию SQLAllocEnv из ODBC 2.x.
SQLAllocConnect распределяет память для дескриптора
подключения.
4.3.3.1 Синтаксис
SQLRETURN SQLAllocConnect(HENV EnvironmentHandle, HDBC* ConnectionHandle);
4.3.3.2 Комментарии
В ODBC 3.x SQLAllocHandle заменила функцию SQLAllocConnect из ODBC 2.x.
SQLConnect устанавливает связи с драйвером и источником
данных. Дескриптор подключения ссылается на адрес в памяти всей информации
относительно подключению к источнику данных, включая состояние подключения и
транзакции, а также информацию об ошибках.
4.3.4.1 Синтаксис
SQLRETURN SQLConnect(SQLHDBC ConnectionHandle, SQLCHAR* ServerName,
SQLSMALLINT NameLength1, SQLCHAR* UserName,
SQLSMALLINT NameLength2, SQLCHAR* Authentication,
SQLSMALLINT NameLength3);
4.3.4.2 Параметры
ConnectionHandle[Input] дескриптор подключения.
ServerName[Input] имя источника данных.
NameLength1[Input] длина *ServerName.
UserName[Input] User id.
NameLength2[Input] длина *UserName.
Authentication[Input] строка авторизации (обычно это пароль).
NameLength3[Input] длина *Authentication.
4.3.4.3 Комментарии
Подробно использование данной функции описано в разделе "3.4.5
Установление подключения, используя MyODBC".
SQLDriverConnect является альтернативой SQLConnect. Это
поддерживает источники данных, которые требуют большего количества информации
подключения чем три параметра в SQLConnect, диалоговые окна, чтобы запросить
пользователя относительно всей информации о подключении, и источники данных,
которые не определены в информации системы.
SQLDriverConnect обеспечивает следующие возможности
подключения:
- Устанавливает подключение, использующее строку подключения, которая
содержит имя источника данных, идентификатор пользователя, пароль и другую
информацию, требуемую сервером.
- Устанавливает подключение, используя частичную строку подключения. В этом
случае Driver Manager выдаст запрос пользователю для получения от него
дополнительной информации о подключении.
- Устанавливает подключение к источнику данных, который не определен в
информации системы. Если прикладная программа обеспечивает частичную строку
подключения, драйвер может запрашивать пользователя относительно
дополнительной информации для подключения.
- Устанавливает подключение к источнику данных, используя строку
подключения, созданную из информации в .dsn-файле.
После того, как подключение установлено, SQLDriverConnect
вернет завершенную строку подключения. Прикладная программа может использовать
ее для выполнения последующих запросов подключения.
4.3.5.1 Синтаксис
SQLRETURN SQLDriverConnect(SQLHDBC ConnectionHandle, SQLHWND WindowHandle,
SQLCHAR* InConnectionString,
SQLSMALLINT StringLength1,
SQLCHAR* OutConnectionString,
SQLSMALLINT BufferLength,
SQLSMALLINT* StringLength2Ptr,
SQLUSMALLINT DriverCompletion);
4.3.5.2 Параметры
ConnectionHandle [Input] дескриптор подключения.
WndowHandle [Input] дескриптор окна. Прикладная программа может
передавать дескриптор родительского окна, если оно есть, или null, если
дескриптор окна не существует.
InConnectionString [Input] полное подключение, частичная строка
подключения или пустая строка.
StringLength1 [Input] длина *InConnectionString в байтах.
OutConnectionString [Output] указатель на буфер для завершенной
строки подключения. При успешном подключении к целевому источнику данных этот
буфер содержит завершенную строку подключения. Прикладные программы должны
распределить по крайней мере 1024 байта для этого буфера.
BufferLength [Input] длина буфера *OutConnectionString.
StringLength2Ptr [Output] указатель на буфер, предназанченный
чтобы возвращать общее количество символов (кроме завершающего нуля) в
*OutConnectionString. Если число символов, доступное для возврата, больше или
равно BufferLength, завершенная строка подключения в *OutConnectionString будет
обрезана до BufferLength.
DriverCompletion [Input] указывает должен ли Driver Manager
запросить дополнительную информацию для подключения: SQL_DRIVER_PROMPT,
SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED или SQL_DRIVER_NOPROMPT.
Не поддерживается.
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);
4.4.3.2 Параметры
ConnectionHandle [Input] дескриптор подключения.
InfoType [Input] тип информации, описанной в разделе
комментариев.
InfoValuePtr [Output] указатель на буфер, предназначенный чтобы
возвращать информацию. В зависимости от запрошенного InfoType, возвращенная
информация будет одним из следующего: символьная строка с нулевым символом в
конце, значение SQLUSMALLINT, битовая маска SQLUINTEGER, флажок (параметр)
SQLUINTEGER или двоичное значение SQLUINTEGER.
Если параметр InfoType равен SQL_DRIVER_HDESC или SQL_DRIVER_HSTMT, параметр
InfoValuePtr является вводом и выводом.
BufferLength [Input] длина буфера *InfoValuePtr. Если значение в
*InfoValuePtr не является символьной строкой, или InfoValuePtr представляет
собой null, параметр BufferLength игнорируется. Драйвер принимает, что размер
*InfoValuePtr равен SQLUSMALLINT или SQLUINTEGER, исходя из InfoType. Если
*InfoValuePtr является строкой в формате Unicode (при вызове SQLGetInfoW),
параметр BufferLength должен быть четным числом, если это не так, будет
возвращена ошибка SQLSTATE HY090 (Invalid string or buffer length).
StringLengthPtr [Output] указатель на буфер предназначенный для
того, чтобы возвращать общее количество байт (за вычетом хвостовых нулей для
символьных данных), доступных в *InfoValuePtr.
Для символьных данных, если число доступных байтов больше или равно
BufferLength, информация в *InfoValuePtr обрезается до размера BufferLength.
Для всех других типов данных значение BufferLength игнорируется, и драйвер
принимает, что размер *InfoValuePtr равен SQLUSMALLINT или SQLUINTEGER в
зависимости от InfoType.
SQLGetFunctions возвращает информацию относительно того,
поддерживает ли драйвер специфическую функцию ODBC.
4.4.4.1 Синтаксис
SQLRETURN SQLGetFunctions(SQLHDBC ConnectionHandle, SQLUSMALLINT FunctionId,
SQLUSMALLINT* SupportedPtr);
4.4.4.2 Параметры
ConnectionHandle [Input] дескриптор подключения.
FunctionId [Input] SQL_API_ODBC3_ALL_FUNCTIONS или
SQL_API_ALL_FUNCTIONS.
SQL_API_ODBC3_ALL_FUNCTIONS используется прикладными программами ODBC 3.x,
чтобы определить поддержку ODBC 3.x и более ранних функций.
SQL_API_ALL_FUNCTIONS используется прикладными программами ODBC 2.x, чтобы
определить поддержку ODBC 2.x. Прикладная программа может передавать
индивидуальный функциональный идентификатор, чтобы определить поддерживает ли
драйвер функцию или нет.
SupportedPtr [Output] если FunctionId идентифицирует одиночную
функцию ODBC, SupportedPtr указывает на одиночное значение SQLUSMALLINT, которое
является SQL_TRUE, если определенная функция поддержана драйвером, или SQL_FALSE
в противном случае.
Если FunctionId равно SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr указывает на
массив SQLSMALLINT с рядом элементов, равных SQL_API_ODBC3_ALL_FUNCTIONS_SIZE.
Прикладная программа ODBC 3.x может вызывать SQLGetFunctions с
SQL_API_ODBC3_ALL_FUNCTIONS.
Если FunctionId равно SQL_API_ALL_FUNCTIONS, SupportedPtr указывает на массив
SQLSMALLINT ровно из 100 элементов. Элемент равен SQL_TRUE, если он
идентифицирует ODBC 2.x или более раннюю функцию, поддержанную драйвером.
Элемент массива будет равен SQL_FALSE, если он идентифицирует функцию ODBC, не
поддержанную драйвером, или не идентифицирует функцию ODBC вообще.
Массивы, возвращенные в *SupportedPtr используют индексацию, начиная с 0.
SQLGetTypeInfo возвращает информацию относительно типов
данных, поддержанных сервером. Драйвер возвращает информацию в форме набора
результатов SQL. Типы данных предназначены для использования в инструкциях Data
Definition Language (DDL). Прикладные программы должны использовать имена типов,
возвращенные в столбце TYPE_NAME набора результатов SQLGetTypeInfo. Для команд
ALTER TABLE и CREATE TABLE возможен возврат больше, чем одной строки с тем же
самым значением в DATA_TYPE столбце.
4.4.5.1 Синтаксис
SQLRETURN SQLGetTypeInfo(SQLHSTMT StatementHandle, SQLSMALLINT DataType);
4.4.5.2 Параметры
StatementHandle [Input] операторный дескриптор для набора
результатов.
DataType [Input] SQL-тип данных. SQL_ALL_TYPES определяет, что
должна быть возвращена информация относительно всех типов данных.
SQLSetConnectAttr устанавливает атрибуты, которые управляют
аспектами подключений.
4.5.1.1 Синтаксис
SQLRETURN SQLSetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER StringLength);
4.5.1.2 Параметры
ConnectionHandle [Input] дескриптор подключения.
Attribute [Input] атрибут для установки.
ValuePtr [Input] указатель на значение, которое будет связано с
атрибутом. В зависимости от значения атрибута, ValuePtr будет 32-разрядным целым
числом без знака или указателем на строку символов с нулем в конце. Обратите
внимание, что если параметр Attribute представляет собой специфическое для
драйвера значение, то ValuePtr может быть целым числом со знаком.
StringLength [Input] если Attribute определен в ODBC и ValuePtr
указывает на строку или на двоичный буфер, этот параметр должен быть длиной
*ValuePtr. Если Attribute определен в ODBC и ValuePtr является целым числом,
StringLength игнорируется.
- Если ValuePtr является указателем на строку символов, StringLength
определяет длину строки или равно SQL_NTS.
- Если ValuePtr является указателем на двоичный буфер, то прикладная
программа помещает результат макрокоманды SQL_LEN_BINARY_ATTR(length) в
StringLength. Это помещает отрицательное значение в StringLength.
- Если ValuePtr является указателем на иное значение, StringLength имеет
значение SQL_IS_POINTER.
- Если ValuePtr содержит значение фиксированной длины, StringLength является
соответственно SQL_IS_INTEGER или SQL_IS_UINTEGER.
4.5.1.3 Комментарии
Имеется список атрибутов подключения, которые поддержаны драйвером MyODBC
3.51:
| Атрибут |
Содержимое ValuePtr |
| SQL_ATTR_ACCESS_MODE |
Значение SQLUINTEGER, и драйвер не позволяет пользователю
устанавливать этот атрибут во что-либо, кроме SQL_MODE_READ_WRITE. |
| SQL_ATTR_ASYNC_ENABLE |
Значение SQLUINTEGER, которое определяет асинхронное выполнение.
Драйвер не поддерживает асинхронное выполнение, так что это можно
устанавливать только в SQL_ASYNC_ENABLE_OFF. |
| SQL_ATTR_AUTO_IPD |
Значение SQLUINTEGER только для чтения, драйвер возвращает значение по
умолчанию как SQL_FALSE. |
| SQL_ATTR_AUTOCOMMIT |
Значение SQLUINTEGER, которое определяет использовать ли autocommit
или ручной режим:
SQL_AUTOCOMMIT_OFF: драйвер работает в ручном режиме,
и прикладная программа должна явно заверишть или отменить каждую
транзакцию через SQLEndTran.
SQL_AUTOCOMMIT_ON: драйвер работает в
режиме autocommit. Каждая инструкция выполняется сразу после передачи. Это
значение по умолчанию. Любые открытые транзакции на подключении
автоматически закрываются при смене SQL_ATTR_AUTOCOMMIT на
SQL_AUTOCOMMIT_ON. |
| SQL_ATTR_CONNECTION_DEAD |
Значение SQLUINTERGER, которое указывает состояние подключения. Если
это SQL_CD_TRUE, связь прервана. Если это SQL_CD_FALSE, подключение все
еще активно. |
| SQL_ATTR_CONNECTION_TIMEOUT |
Значение SQLUINTEGER, соответствующее числу секунд, которое надо ждать
любой запрос на подключении перед возвратом прикладной программе. Драйвер
должен возвратить SQLSTATE HYT00 (Timeout expired) по окончании тайм-аута.
Если ValuePtr равно 0 (значение по умолчанию), не имеется никакого времени
ожидания. |
| SQL_ATTR_CURRENT_CATALOG |
Символьная строка, содержащая имя каталога, который нужно использовать
как источник данных. Например, в SQL Server каталог является базой данных,
так что драйвер посылает инструкцию USE источнику данных,
где база данных определена в *ValuePtr. |
| SQL_ATTR_LOGIN_TIMEOUT |
Значение SQLUINTEGER, соответствующее числу секунд, которое надлежит
ждать при входе в систему перед возвратом прикладной программе. Значение
по умолчанию зависит от драйвера. Если ValuePtr равно 0, время ожидания
заблокировано, и попытка подключения будет ждать неопределенное время.
Если определенное время ожидания превышает максимальное время ожидания
входа в систему в источнике данных, значение из драйвера имеет приоритет,
при этом драйвер вернет SQLSTATE 01S02 (Option value changed). |
| SQL_ATTR_METADATA_ID |
Значение SQLUINTEGER, которое определяет как обрабатываются строковые
параметры каталожных функций. Драйвер пока поддерживает только
SQL_FALSE. |
| SQL_ATTR_ODBC_CURSORS |
Значение SQLUINTEGER, определяющее, как Driver Manager использует
библиотеку курсоров ODBC. |
| SQL_ATTR_PACKET_SIZE |
Значение SQLUINTEGER, определяющее сетевой размер пакета в
байтах. |
| SQL_ATTR_QUIET_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 возвращает текущую установку некоего
атрибута подключения.
4.5.2.1 Синтаксис
SQLRETURN SQLGetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER BufferLength,
SQLINTEGER* StringLengthPtr);
4.5.2.2 Параметры
ConnectionHandle [Input] дескриптор подключения.
Attribute [Input] интересующий атрибут.
ValuePtr [Input] указатель на память предназначенный, чтобы
возвращать текущее значение атрибута.
BufferLength [Input]Если Attribute представляет собой
ODBC-атрибут и ValuePtr указывает на символьную строку или двоичный буфер, этот
параметр должен быть длиной *ValuePtr. Если же *ValuePtr не указатель, а целое
число, BufferLength игнорируется.
- Если *ValuePtr указатель на символьную строку, BufferLength хранит длину
строки или SQL_NTS.
- Если *ValuePtr указатель на двоичный буфер, то прикладная программа
помещает результат макрокоманды SQL_LEN_BINARY_ATTR(length) в BufferLength.
Это помещает отрицательное значение в BufferLength.
- Если *ValuePtr указатель на иное значение, то BufferLength имеет значение
SQL_IS_POINTER.
- Если *ValuePtr содержит тип данных фиксированной длины, то BufferLength
является соответственно SQL_IS_INTEGER или SQL_IS_UINTEGER.
StringLengthPtr [Output] указатель на буфер предназначенный,
чтобы возвращать общее количество байт, доступных в *ValuePtr (кроме нулевых
символов в конце). Если *ValuePtr равен null, длина не возвращена. Если
значением атрибута является символьная строка, и число байт больше BufferLength,
данные в *ValuePtr обрезаются до BufferLength.
В ODBC 3.x SQLSetConnectAttr заменяет
SQLSetConnectOption.
В ODBC 3.x SQLGetConnectAttr заменяет
SQLGetConnectOption.
SQLSetEnvAttr устанавливает атрибуты, которые управляют
аспектами сред.
4.5.5.1 Синтаксис
SQLRETURN SQLSetEnvAttr(SQLHENV EnvironmentHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER StringLength);
4.5.5.2 Параметры
EnvironmentHandle [Input] дескриптор среды.
Attribute [Input] атрибут для установки.
ValuePtr [Input] указатель на значение, которое будет связано с
Attribute. В зависимости от значения Attribute, ValuePtr будет 32-битным
целочисленным значением или указателем на символьную строку с нулевым символом в
конце.
StringLength [Input]: если ValuePtr указатель на символьную
строку с нулевым символом в конце или на двоичный буфер, здесь хранится длина
*ValuePtr. Если ValuePtr представляет собой целое число, StringLength
игнорируется.
4.5.5.3 Комментарии
Прикладная программа может вызывать SQLSetEnvAttr только, если никакой
дескриптор подключения не распределен в текущей среде. Все атрибуты среды
устанавливаются прикладной программой до обращения SQLFreeHandle. Следующая
таблица вносит в список различные атрибуты среды, поддержанные драйвером:
| Атрибут |
Содержимое ValuePtr |
| SQL_ATTR_CONNECTION_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 возвращает текущую установку атрибута среды.
4.5.6.1 Синтаксис
SQLRETURN SQLGetEnvAttr(SQLHENV EnvironmentHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER BufferLength,
SQLINTEGER* StringLengthPtr);
4.5.6.2 Параметры
EnvironmentHandle [Input] дескриптор среды.
Attribute [Input] атрибут, значение которого нужно получить.
ValuePtr [Output] указатель на буфер нужный, чтобы возвращать
текущее значение атрибута, определенного Attribute.
BufferLength [Input] если ValuePtr указывает на символьную
строку, этот параметр должен быть длиной *ValuePtr. Если *ValuePtr целое число,
BufferLength игнорируется. Если значение атрибута не строка, BufferLength не
применяется.
StringLength [Output] указатель на буфер предназначенный, чтобы
возвращать общее количество байт, доступных в *ValuePtr (кроме нулевых символов
в конце). Если *ValuePtr равен null, длина не возвращена. Если значением
атрибута является символьная строка, и число байт больше BufferLength, данные в
*ValuePtr обрезаются до BufferLength.
SQLSetStmtAttr устанавливает атрибуты, связанные с
инструкцией.
4.5.7.1 Синтаксис
SQLRETURN SQLSetStmtAttr(SQLHSTMT StatementHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER StringLength);
4.5.7.2 Параметры
StatementHandle [Input] дескриптор инструкции.
Attribute [Input] атрибут для установки.
ValuePtr
[Input] указатель на значение, которое будет связано с Attribute,
ValuePtr может быть 32-битным целым числом числа без знака или указателем на
символьную строку с нулевым символом в конце, двоичный буфер или определенное
драйвером значение. Если параметр Attribute представляет собой специфическое для
драйвера значение, ValuePtr может быть целым числом со знаком.
StringLength [Input] если Attribute определен в ODBC и ValuePtr
указывает на строку или двоичный буфер, это длина *ValuePtr. Если Attribute
определен в ODBC и ValuePtr целое число, StringLength игнорируется. Если
Attribute определен драйвером, прикладная программа указывает характер атрибута
Driver Manager: устанавливая аргумент StringLength. StringLength может иметь
следующие значения:
- Если ValuePtr указатель на символьную строку, то StringLength длина строки
или SQL_NTS.
- Если ValuePtr указатель на двоичный буфер, то прикладная программа
помещает результат макроса SQL_LEN_BINARY_ATTR(length) в StringLength.
- Если ValuePtr указатель на что-то иное, чем символьная или двоичная
строка, StringLength имеет значение SQL_IS_POINTER.
- Если ValuePtr хранит значение фиксированной длины, StringLength равен
соответственно SQL_IS_INTEGER или SQL_IS_UINTEGER.
4.5.7.3 Комментарии
Операторные атрибуты для инструкции остаются в силе, пока они не изменены
другим обращением SQLSetStmtAttr.
| Атрибут |
Значение ValuePtr |
| SQL_ATTR_APP_PARAM_DESC |
Не поддерживается |
| SQL_ATTR_APP_ROW_DESC |
Не поддерживается |
| SQL_ATTR_ASYNC_ENABLE |
Значение SQLUINTEGER, которое определяет выполнена ли функция
асинхронно: SQL_ASYNC_ENABLE_OFF=Off (значение по умолчанию),
SQL_ASYNC_ENABLE_ON=On. Драйвер не поддерживает асинхронное
выполнение, так что прикладная программа может устанавливать это только в
значение по умолчанию. |
| SQL_ATTR_CONCURRENCY |
Значение SQLUINTEGER, которое определяет параллелизм
курсора:
SQL_CONCUR_READ_ONLY: курсор только для чтения.
Никакие модификации не позволяются.
SQL_CONCUR_LOCK:
курсор использует самый низкий уровень блокировки, достаточный, чтобы
гарантировать, что строка может
модифицироваться.
SQL_CONCUR_ROWVER: курсор использует
оптимистическое управление
параллелизма.
SQL_CONCUR_VALUES: курсор использует
оптимистическое управление параллелизма, сравнивая значения.
Значение
по умолчанию для SQL_ATTR_CONCURRENCY равно
SQL_CONCUR_READ_ONLY. Драйвер в настоящее время поддерживает
только SQL_CONCUR_ROWVER. |
| SQL_ATTR_CURSOR_SCROLLABLE |
Значение SQLUINTEGER, которое определяет уровень поддержки, который
прикладная программа требует. Установка этого атрибута воздействует на
последующие обращения к SQLExecDirect и SQLExecute.
SQL_NONSCROLLABLE: скроллируемые курсоры не требуются на
операторном дескрипторе. Если из прикладной программы вызван
SQLFetchScroll на этом дескрипторе, единственное имеющее силу значение
FetchOrientation: SQL_FETCH_NEXT. Это значение по умолчанию.
SQL_SCROLLABLE: скроллируемые курсоры требуются на
операторном дескрипторе. При вызове SQLFetchScroll прикладная программа
может определять любое имеющее силу значение FetchOrientation, достигая
позиционирования курсора в любом режиме. |
| SQL_ATTR_CURSOR_SENSITIVITY |
Значение SQLUINTEGER, которое определяет делают ли курсоры на
операторном дескрипторе видимыми изменения, сделанные другим курсором.
Установка этого атрибута воздействует на последующие обращения к
SQLExecDirect и SQLExecute. Прикладная программа может читать значение
этого атрибута, чтобы получить информацию статуса.
SQL_UNSPECIFIED: не определено, чем является тип курсора, и
делают ли курсоры на операторном дескрипторе видимыми изменения, сделанные
другим курсором. Курсоры на операторном дескрипторе могут делать видимыми
изменения полностью или частично. Это значение по умолчанию.
SQL_INSENSITIVE: все курсоры на операторном дескрипторе
показывают набор результатов без того, чтобы отразить любые изменения,
сделанные любым другим курсором. Нечувствительные курсоры только для
чтения. Это соответствует статическому курсору, который имеет параллелизм
и нужен только для чтения. SQL_SENSITIVE: все курсоры на
операторном дескрипторе делают видимыми все изменения, сделанные другим
курсором. Сейчас драйвер поддерживает только SQL_SENSITIVE и
SQL_INSENSITIVE. |
| SQL_ATTR_CURSOR_TYPE |
Значение SQLUINTEGER, которое определяет тип курсора:
SQL_CURSOR_FORWARD_ONLY: курсор прокручивается только вперед.
SQL_CURSOR_STATIC: данные в наборе результатов статические.
SQL_CURSOR_KEYSET_DRIVEN: драйвер сохраняет и использует
ключи для числа строк, определенных в инструкции
SQL_ATTR_KEYSET_SIZE. SQL_CURSOR_DYNAMIC:
драйвер сохраняет и использует только ключи для строк в rowset. Значение
по умолчанию: SQL_CURSOR_FORWARD_ONLY. Этот атрибут не может
быть определен после того, как инструкция SQL была подготовлена. Драйвер
сейчас поддерживает только статический и "только вперед" типы
курсора. |
| SQL_ATTR_KEYSET_SIZE |
Значение SQLUINTEGER, который определяет число строк в ключе для
управляемого ключом курсора. Поскольку драйвер не поддерживает управляемые
ключами курсоры, этот атрибут игнорируется. |
| SQL_ATTR_MAX_LENGTH |
Значение SQLUINTEGER, которое определяет максимальное количество
данных, которое драйвер возвращает из символьного или двоичного столбца.
Если ValuePtr меньше, чем длина доступных данных, SQLFetch или SQLGetData
усекает данные и возвращает SQL_SUCCESS. Если ValuePtr равно 0 (значение
по умолчанию), драйвер пытается возвращать все доступные данные. |
| SQL_ATTR_MAX_ROWS |
Значение SQLUINTEGER, соответствующее максимальному числу строк,
которое вернется прикладной программе для инструкции SELECT. Если
*ValuePtr равно 0 (значение по умолчанию), драйвер возвращает все
строки. |
| SQL_ATTR_METADATA_ID |
Значение SQLUINTEGER, которое определяет как обрабатываются строчные
параметры каталожной функции. Если SQL_TRUE, строчный
параметр каталожной функции обрабатывается как идентификаторы. Регистр не
важен. В случае SQL_FALSE параметр не обрабатывается как
идентификатор. Регистр важен. Значение по умолчанию SQL_FALSE, и драйвер
поддерживает только значение по умолчанию. |
| SQL_ATTR_NOSCAN |
Значение SQLUINTEGER, которое указывает должен ли драйвер просмотреть
строки SQL на предмет наличия в них управляющих последовательностей.
SQL_NOSCAN_OFF: драйвер просматривает строки SQL (значение по
умолчанию). SQL_NOSCAN_ON: драйвер не просматривает строки
SQL. Вместо этого драйвер посылает инструкцию непосредственно источнику
данных. |
| SQL_ATTR_PARAM_BIND_OFFSET_PTR |
Значение SQLUINTEGER*, которое указывает на смещение, добавленное к
указателям, чтобы изменить связывание динамических параметров. Не
поддерживается драйвером. |
| SQL_ATTR_PARAM_BIND_TYPE |
Значение SQLUINTEGER, которое указывает ориентацию связывания, которую
нужно использовать для динамических параметров. Это поле установлено в
SQL_PARAM_BIND_BY_COLUMN (значение по умолчанию), чтобы
выбрать поколоночное связывание. Чтобы выбрать строчное связывание, это
поле должно быть установлено в длину структуры или в образец буфера,
который будет привязан к набору динамических параметров. Эта длина должна
включать место для всех связанных параметров и любого дополнения структуры
или буфера, чтобы гарантировать, что, когда адрес связанного параметра
будет увеличен на определенную длину, результат укажет на начало того же
самого параметра в следующем наборе параметров. |
| SQL_ATTR_PARAM_OPERATION_PTR |
Значение SQLUSMALLINT*, которое указывает на массив значений
SQLUSMALLINT используемых, чтобы игнорировать параметр в течение
выполнения инструкции SQL. Каждое значение установлено в
SQL_PARAM_PROCEED (для параметра, который будет выполнен) или
в SQL_PARAM_IGNORE (для параметра, который нужно
игнорировать). Набор параметров может игнорироваться в течение обработки,
устанавливая значение состояния в массиве, на который указывает
SQL_DESC_ARRAY_STATUS_PTR в SQL_PARAM_IGNORE.
Набор параметров обработан, если значение состояния установлено в
SQL_PARAM_PROCEED или если никакие элементы в массиве не
установлены. Этот операторный атрибут может быть установлен в null, тогда
драйвер не возвращает значения состояния параметра. Этот атрибут может
быть установлен в любое время, но новое значение не используется до
следующего взоыва SQLExecDirect или SQLExecute. |
| SQL_ATTR_PARAM_STATUS_PTR |
Значение SQLUSMALLINT*, которое указывает на массив значений
SQLUSMALLINT содержащих информацию состояния для каждой строки значений
параметра после обращения к SQLExecute или к SQLExecDirect. Это поле
требуется только если PARAMSET_SIZE больше 1. Значения
состояния могут содержать следующие значения:
SQL_PARAM_SUCCESS: инструкция SQL была успешно выполнена для
этого набора параметров. SQL_PARAM_SUCCESS_WITH_INFO:
инструкция SQL была успешно выполнена для этого набора параметров, однако,
в структуре данных диагностики доступно предупреждение.
SQL_PARAM_ERROR: имелась ошибка в обработке этого набора
параметров. Дополнительная информация об ошибке доступна в структуре
данных диагностики. SQL_PARAM_UNUSED: набор параметров не
пригодился, возможно, вследствие того, что некоторый предыдущий набор
параметров вызвал ошибку, которая прервала обработку, или потому, что
SQL_PARAM_IGNORE был установлен для этого набор параметров в
массиве, определенном SQL_ATTR_PARAM_OPERATION_PTR.
SQL_PARAM_DIAG_UNAVAILABLE: драйвер обрабатывает массивы
параметров как монолитный модуль и не генерирует этот уровень информации
ошибки. Этот операторный атрибут может быть установлен в null, тогда
драйвер не возвращает значения состояния параметра. Этот атрибут может
быть установлен в любое время, но новое значение не используется до
очередного вызова SQLExecute или SQLExecDirect. Обратите внимание, что
этот атрибут может воздействовать на поведение выходного параметра,
выполненное драйвером. |
| SQL_ATTR_PARAMS_PROCESSED_PTR |
Значение SQLUINTEGER*, которое указывает на буфер нужный, чтобы
возвратить число наборов параметров, которые были обработаны, включая
наборы ошибок. Ничего не будет возвращено, если здесь задан null. |
| SQL_ATTR_PARAMSET_SIZE |
Значение SQLUINTEGER, которое определяет число значений для каждого
параметра. |
| SQL_ATTR_QUERY_TIMEOUT |
Значение SQLUINTEGER, соответствующее числу секунд, которое надо ждать
инструкцию SQL перед возвратом прикладной программе. Если ValuePtr равен 0
(значению по умолчанию), не имеется никакого времени ожидания. |
| SQL_ATTR_RETRIEVE_DATA |
Значение SQLUINTEGER: SQL_RD_ON: SQLFetchScroll и, в ODBC
3.x, SQLFetch получают данные после того, как устанавливают курсор в
определенное расположение. Это значение по умолчанию.
SQL_RD_OFF: SQLFetchScroll и, в ODBC 3.x, SQLFetch не
получают данные после того, как устанавливают курсор. Драйвер поддерживает
только значение по умолчанию. |
| SQL_ATTR_ROW_ARRAY_SIZE |
Значение SQLUINTEGER, которое определяет число строк, возвращенных
каждым обращением к SQLFetch или к SQLFetchScroll. Это также задает число
строк в массиве закладок, используемом в оптовой операции закладки в
SQLBulkOperations. Значение по умолчанию 1. |
| SQL_ATTR_ROW_BIND_OFFSET_PTR |
Значение SQLUINTEGER*, которое указывает на смещение, добавленное к
указателям, чтобы изменить связывание данных столбца. |
| SQL_ATTR_ROW_BIND_TYPE |
Значение SQLUINTEGER, которое устанавливает ориентацию связывания,
которую нужно использовать, когда SQLFetch или SQLFetchScroll обращаются к
связанной инструкции. Поколоночное связывание выбрано, устанавливая
значение в SQL_BIND_BY_COLUMN. Построчное связывание будет
выбрано, устанавливая значение в длину структуры или в образец буфера, с
которым столбцы результата будут связаны. |
| SQL_ATTR_ROW_NUMBER |
Значение SQLUINTEGER, которое является номером текущей строки во всем
наборе результатов. Если номер текущей строки не может быть определен или
не имеется никакой текущей строки, драйвер возвращает 0. Этот атрибут
может быть проверен обращением к SQLGetStmtAttr, но не может быть
установлен через вызов SQLSetStmtAttr. |
| SQL_ATTR_ROW_OPERATION_PTR |
Значение SQLUSMALLINT*, которое указывает на массив значений
SQLUSMALLINT используемых, чтобы игнорировать строку в течение оптовой
операции, использующей SQLSetPos. Каждое значение установлено в
SQL_ROW_PROCEED (для строки, которая будет включена в оптовую
операцию) или в SQL_ROW_IGNORE (для строки, которая будет
исключена из оптовой операции). Строки не могут игнорироваться, используя
этот массив в течение обращений к SQLBulkOperations. Этот операторный
атрибут может быть установлен в null, когда драйвер не возвращает значения
состояния строки. Этот атрибут может быть установлен в любое время, но
новое значение не используется до очередного вызова SQLSetPos. |
| SQL_ATTR_ROW_STATUS_PTR |
Значение SQLUSMALLINT*, которое указывает на массив значений
SQLUSMALLINT, содержащих значения состояния строки после обращения к
SQLFetch или SQLFetchScroll. Массив имеет так много элементов, сколько
есть строк в rowset. Этот операторный атрибут может быть установлен в
null, когда драйвер не возвращает значения состояния строки. Этот атрибут
может быть установлен в любое время, но новое значение не используется до
очередного вызова SQLBulkOperations, SQLFetch, SQLFetchScroll или
SQLSetPos. |
| SQL_ATTR_ROWS_FETCHED_PTR |
Значение SQLUINTEGER*, которое указывает на буфер нужный, чтобы
возвратить число строк, выбранных после обращения к SQLFetch или
SQLFetchScroll, число строк, на которые воздействует оптовая операция,
выполняемая обращением к SQLSetPos с параметром Operation выставленным в
SQL_REFRESH, или число строк, на которые воздействует оптовая
операция, выполняемая SQLBulkOperations. |
| SQL_ATTR_SIMULATE_CURSOR |
Значение SQLUINTEGER, которое определяет драйверы, которые моделируют
позиционные модификации и удаления и гарантируют, что такие инструкции
воздействуют только на одну строку. SQL_SC_NON_UNIQUE:
драйвер не гарантирует, что моделируемая инструкция будет воздействовать
только на одну строку. SQL_SC_TRY_UNIQUE: драйвер пытается
гарантировать, что моделируемая инструкция будет воздействовать только на
одну строку. SQL_SC_UNIQUE: драйвер гарантирует, что
моделируемая инструкция будет воздействовать только на одну строку. |
| SQL_ATTR_USE_BOOKMARKS |
Закладки не поддерживаются. |
SQLGetStmtAttr возвращает текущую установку операторного
атрибута.
4.5.8.1 Синтаксис
SQLRETURN SQLGetStmtAttr(SQLHSTMT StatementHandle, SQLINTEGER Attribute,
SQLPOINTER ValuePtr, SQLINTEGER BufferLength,
SQLINTEGER* StringLengthPtr);
4.5.8.2 Параметры
StatementHandle [Input] операторный дескриптор.
Attribute [Input] интересующий атрибут.
ValuePtr [Output] указатель на буфер, в который будет возвращено
значение атрибута, определенного в Attribute.
BufferLength [Input] если Attribute определен в ODBC и ValuePtr
указывает на символьную строку или двоичный буфер, этот параметр должен быть
длиной *ValuePtr. Если Attribute определен в ODBC и *ValuePtr целое число,
BufferLength игнорируется. BufferLength может иметь значения:
- Если *ValuePtr указатель на символьную строку, то BufferLength длина этой
строки или SQL_NTS.
- Если *ValuePtr указатель на двоичный буфер, то прикладная программа
помещает результат макроса SQL_LEN_BINARY_ATTR(length) в BufferLength.
- Если *ValuePtr указатель на другой тип значения, BufferLength имеет
значение SQL_IS_POINTER.
- Если *ValuePtr хранит тип данных фиксированной длины, то BufferLength
SQL_IS_INTEGER или SQL_IS_UINTEGER, как получится.
StringLength [Output] указатель на буфер, куда будет записано
общее количество байт (кроме хвостового нуля), доступное в *ValuePtr. Если
ValuePtr равно null, никакая длина не возвращена. Если значение атрибута
символьная строка, и число доступных байт больше BufferLength, данные в
*ValuePtr автоматически урезаются до размеров BufferLength.
В ODBC 3.x SQLSetStmtAttr заменяет
SQLStmtOption.
В ODBC 3.x SQLGetStmtAttr заменяет
SQLCetStmtOption.
SQLAllocStmt распределяет память для операторного
дескриптора.
4.6.1.1 Синтаксис
SQLRETURN SQLAllocStmt(HDBC ConnectionHandle, HSTMT* StatementHandle);
4.6.1.2 Комментарии
В ODBC 3.x SQLAllocHandle заменяет функцию ODBC 2.x SQLAllocStmt.
SQLPrepare готовит команду SQL к выполнению.
4.6.2.1 Синтаксис
SQLRETURN SQLPrepare(SQLHSTMT StatementHandle, SQLCHAR* StatementText,
SQLINTEGER TextLength);
4.6.2.2 Параметры
StatementHandle [Input] операторный дескриптор.
StatementText [Input] строка SQL-команды.
TextLength [Input] длина *StatementText.
SQLBindParameter привязывает буфер к маркеру параметра в
инструкции SQL. SQLBindParameter поддерживает связывание к Unicode-C типу
данных, даже если основной драйвер не поддерживает Unicode-данные.
4.6.3.1 Синтаксис
SQLRETURN SQLBindParameter(SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT InputOutputType,
SQLSMALLINT ValueType, SQLSMALLINT ParameterType,
SQLUINTEGER ColumnSize, SQLSMALLINT DecimalDigits,
SQLPOINTER ParameterValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER* StrLen_or_IndPtr);
4.6.3.2 Параметры
StatementHandle [Input] операторный дескриптор.
ParameterNumber [Input] номер параметра, упорядоченный
последовательно в увеличивающемся порядке, начинающемся с 1.
InputOutputType [Input] тип параметра.
ValueType [Input] тип данных C для параметра.
ParameterType [Input] SQL-тип параметра.
ColumnSize [Input] размер столбца или выражения,
соответствующего маркеру параметра.
DecimalDigits [Input] десятичные цифры столбца или выражения
соответствующего маркеру параметра.
ParameterValuePtr [Deferred Input] указатель на буфер для данных
параметра.
BufferLength [Input/Output] длина буфера ParameterValuePtr в
байтах.
StrLen_or_IndPtr [Deferred Input] указатель на буфер для длины
параметра.
SQLGetCursorName возвращает имя курсора, связанного с
определенной инструкцией.
4.6.4.1 Синтаксис
SQLRETURN SQLGetCursorName(SQLHSTMT StatementHandle, SQLCHAR* CursorName,
SQLSMALLINT BufferLength,
SQLSMALLINT* NameLengthPtr);
4.6.4.2 Параметры
StatementHandle [Input] дескриптор подключения.
CursorName [Output] указатель на буфер для имени курсора.
BufferLength [Input] длина *CursorName в байтах.
NameLengthPtr [Output] указатель на память, куда будет записано
возвращаемое значение. Если значение больше, чем BufferLength, *CursorName
урезается до BufferLength за вычетом хвостового нуля.
SQLSetCursorName сопоставляет имя курсора с активной
инструкцией. Если прикладная программа не вызывает SQLSetCursorName, драйвер
генерирует имена курсора так, как необходимо для обработки инструкции SQL.
4.6.5.1 Синтаксис
SQLRETURN SQLSetCursorName(SQLHSTMT StatementHandle, SQLCHAR* CursorName,
SQLSMALLINT NameLength);
4.6.5.2 Параметры
StatementHandle [Input] операторный дескриптор.
CursorName [Input] имя курсора. Для эффективной обработки имя
курсора не должно включить никаких пробелов, а если имя курсора включает
разграниченный идентификатор, разделитель должен быть установлен как первый
символ в имени курсора.
NameLength [Input] длина *CursorName.
В ODBC 3.x SQLSetSetScrollOptions заменен обращением к 4.5.7
SQLSetStmtAttr и 4.4.3
SQLGetInfo.
SQLExecute выполняет подготовленную инструкцию, используя
текущие (актуальные) значения переменных маркера параметра, если маркеры
параметров существуют в инструкции.
4.7.1.1 Синтаксис
SQLRETURN SQLExecute(SQLHSTMT StatementHandle);
4.7.1.2 Параметры
StatementHandle [Input] операторный дескриптор.
4.7.1.3 Комментарии
SQLExecute выполняет инструкцию, подготовленную SQLPrepare.
SQLExecDirect выполняет инструкцию, используя текущие
(актуальные) значения переменных маркера параметра, если параметры существуют в
инструкции. SQLExecDirect представляет собой самый быстрый способ представить
серверу на рассмотрение инструкцию SQL для одного выполнения.
4.7.2.1 Синтаксис
SQLRETURN SQLExecDirect(SQLHSTMT StatementHandle, SQLCHAR* StatementText,
SQLINTEGER TextLength);
4.7.2.2 Параметры
StatementHandle [Input] операторный дескриптор.
StatementText [Input] SQL-инструкция, которая будет выполнена.
TextLength [Input] длина *StatementText.
4.7.2.3 Комментарии
Прикладные программы вызывают SQLExecDirect, чтобы послать инструкцию SQL на
сервер MySQL.
SQLNativeSql возвращает строку SQL, обработанную драйвером.
SQLNativeSql не выполняет инструкцию SQL.
4.7.3.1 Синтаксис
SQLRETURN SQLNativeSql(SQLHDBC ConnectionHandle, SQLCHAR* InStatementText,
SQLINTEGER TextLength1, SQLCHAR* OutStatementText,
SQLINTEGER BufferLength, SQLINTEGER* TextLength2Ptr);
4.7.3.2 Параметры
ConnectionHandle [Input] дескриптор подключения.
InStatementText [Input] текст инструкции SQL.
TextLength1 [Input] длина строки *InStatementText.
OutStatementText [Output] указатель на буфер распределенный,
чтобы возвращать строку SQL.
BufferLength [Input] длина буфера *OutStatementText.
TextLength2Ptr [Output] указатель на буфер выделенный, чтобы
возвращать общее количество байт, доступное в *OutStatementText. Если число
доступных байт больше BufferLength, *OutStatementText урезается.
SQLDescribeParam возвращает описание маркера параметра,
связанного с подготовленной инструкцией SQL.
4.7.4.1 Синтаксис
SQLRETURN SQLDescribeParam(SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT* DataTypePtr,
SQLUINTEGER* ParameterSizePtr,
SQLSMALLINT* DecimalDigitsPtr,
SQLSMALLINT* NullablePtr);
4.7.4.2 Параметры
StatementHandle [Input] операторный дескриптор.
ParameterNumber [Input] номер маркера, начиная с 1.
DataTypePtr [Output] указатель на буфер выделенный, чтобы
возвращать SQL-тип данных параметра. В ODBC 3.x SQL_TYPE_DATE, SQL_TYPE_TIME,
или SQL_TYPE_TIMESTAMP будут возвращен в *DataTypePtr для типов date, time или
timestamp соответственно. В ODBC 2.x возвращаются SQL_DATE, SQL_TIME или
SQL_TIMESTAMP.
ParameterSizePtr [Output] указатель на буфер для возврата
размера столбца или выражения соответствующего маркера параметра.
DecimalDigitsPtr [Output] указатель на буфер для возврата
количества десятичных цифр столбца или выражения соответствующего параметра как
определено сервером.
NullablePtr [Output] указатель на буфер, куда будет возвращено
значение, которое указывает позволяет ли параметр значения NULL. Это значение
читается из поля SQL_DESC_NULLABLE в IPD. Один из следующего:
SQL_NO_NULLS: параметр не позволяет значения NULL (это
значение по умолчанию).
SQL_NULLABLE: параметр позволяет значения NULL.
SQL_NULLABLE_UNKNOWN: драйвер не может определить, позволяет
ли параметр значения NULL.
SQLNumParams возвращает число параметров в инструкции
SQL.
4.7.5.1 Синтаксис
SQLRETURN SQLNumParams(SQLHSTMT StatementHandle,
SQLSMALLINT* ParameterCountPtr);
4.7.5.2 Параметры
StatementHandle [Input] операторный дескриптор.
ParameterCountPtr [Output] указатель на буфер распределенный,
чтобы возвращать число параметров в инструкции.
SQLParamData используется вместе с SQLPutData, чтобы
обеспечить данные для параметров во время выполнения.
4.7.6.1 Синтаксис
SQLRETURN SQLParamData(SQLHSTMT StatementHandle, SQLPOINTER* ValuePtrPtr);
4.7.6.2 Параметры
StatementHandle [Input] операторный дескриптор.
ValuePtrPtr [Output] указатель на буфер выделенный, чтобы
возвращать адрес буфера ParameterValuePtr, определенного в SQLBindParameter (для
данных параметра) или адрес буфера TargetValuePtr, определенного в SQLBindCol
(для данных столбца), как указано в поле SQL_DESC_DATA_PTR записи операторного
дескриптора.
SQLPutData позволяет прикладной программе посылать данные
для параметра или столбца драйверу во время выполнения. Эта функция может
использоваться, чтобы послать символьные или двоичные значения данных частями к
столбцу со специфическим типом данных (например, параметры типов
SQL_LONGVARBINARY или SQL_LONGVARCHAR). SQLPutData поддерживает связывание с
Unicode C-типом данных, даже если основной драйвер не поддерживает Unicode.
4.7.7.1 Синтаксис
SQLRETURN SQLPutData(SQLHSTMT StatementHandle, SQLPOINTER DataPtr,
SQLINTEGER StrLen_or_Ind);
4.7.7.2 Параметры
StatementHandle [Input] операторный дескриптор.
DataPtr [Input] указатель на буфер с актуальными данными для для
параметра или столбца. Данные должны быть в C-типе данных, определенном в
параметре ValueType функции SQLBindParameter (для данных параметра) или в
параметре TargetType функции SQLBindCol (для данных столбца).
StrLen_or_Ind [Input] длина *DataPtr. Определяет количество
данных, переданное в вызове SQLPutData. Количество данных может измениться для
каждого вызова. StrLen_or_Ind игнорируется, если не выполняется одно из
следующих условий:
- StrLen_or_Ind равно SQL_NTS, SQL_NULL_DATA или SQL_DEFAULT_PARAM.
- C-тип данных указан в SQLBindParameter, или SQLBindCol равно SQL_C_CHAR
или SQL_C_BINARY.
- C-тип данных SQL_C_DEFAULT, и C-тип данных по умолчанию для определенного
SQL-типа данных равен SQL_C_CHAR или SQL_C_BINARY. Для всех других C-типов
данных, если StrLen_or_Ind не равен SQL_NULL_DATA или SQL_DEFAULT_PARAM,
драйвер принимает, что размер буфера *DataPtr равен размеру C-типа данных,
определенного в ValueType или TargetType и посылает все значения.
SQLRowCount возвращает число строк, на которые воздействует
инструкция UPDATE, INSERT или DELETE.
4.8.1.1 Синтаксис
SQLRETURN SQLRowCount(SQLHSTMT StatementHandle, SQLINTEGER* RowCountPtr);
4.8.1.2 Параметры
StatementHandle [Input] дескриптор подключения.
RowCountPtr [Output] указывает на буфер для возврата числа
строк. Для UPDATE, INSERT и DELETE, операций SQL_ADD в SQLBulkOperations и
SQL_UPDATE или SQL_DELETE в SQLSetPos значение, возвращенное в *RowCountPtr,
является числом строк, на которые воздействует запрос, или -1, если число строк
не доступно.
При вызове SQLExecute, SQLExecDirect, SQLBulkOperations, SQLSetPos или
SQLMoreResults поле SQL_DIAG_ROW_COUNT диагностической структуры данных
установлено в число строк, которое кэшируется зависимым от реализации способом.
SQLRowCount возвращает кэшируемое значение числа строк. Оно имеет силу, пока
операторный дескриптор не перераспределен, не выполнена снова инструкция или не
вызван SQLCloseCursor. Обратите внимание, что, если функция была вызвана, поле
SQL_DIAG_ROW_COUNT было установлено, и значение, возвращенное SQLRowCount, может
отличаться от значения в SQL_DIAG_ROW_COUNT, поскольку поле SQL_DIAG_ROW_COUNT
сброшено в 0 любым обращением к функции.
Для других инструкций и функций, драйвер может определять значение,
возвращенное в *RowCountPtr. Например, некоторые источники данных могут
возвратить число строк, возвращенных инструкцией SELECT или функцией каталога
перед выборкой строк.
Обратите внимание, что много источников данных не могут
возвращать число строк в наборе результатов перед их выборкой.
SQLNumResultCols возвращает число столбцов в наборе
результатов.
4.8.2.1 Синтаксис
SQLRETURN SQLNumResultCols(SQLHSTMT StatementHandle,
SQLSMALLINT* ColumnCountPtr);
4.8.2.2 Параметры
StatementHandle [Input] операторный дескриптор.
ColumnCountPtr [Output] указатель на буфер, в который будет
записано число столбцов в наборе результатов.
SQLDescribeCol возвращает имя дескрипторного столбца
результата, тип, размер столбца, десятичные цифры и возможность принимать
значение null для одного столбца в наборе результатов. Эта информация также
доступна в полях IRD.
4.8.3.1 Синтаксис
SQLRETURN SQLDescribeCol(SQLHSTMT StatementHandle, SQLSMALLINT ColumnNumber,
SQLCHAR* ColumnName, SQLSMALLINT BufferLength,
SQLSMALLINT* NameLengthPtr,
SQLSMALLINT* DataTypePtr,
SQLUINTEGER* ColumnSizePtr,
SQLSMALLINT* DecimalDigitsPtr,
SQLSMALLINT* NullablePtr);
4.8.3.2 Параметры
StatementHandle [Input] операторный дескриптор.
ColumnNumber [Input] номер столбца данных результата,
упорядоченных последовательно в увеличивающемся порядке, начиная с 1. Параметр
ColumnNumber может быть также установлен в 0, чтобы описать столбец
закладки.
ColumnName [Output] указатель на буфер, в который надо вернуть
имя столбца. Это значение читается из поля SQL_DESC_NAME в IRD. Если столбец не
назван, или имя столбца не может быть определено, драйвер возвращает пустую
строку.
BufferLength [Input] длина буфера *ColumnName в символах.
NameLengthPtr [Output] указатель на буфер, куда надо записать
общее количество байт, доступных для возврата в *ColumnName. Хвостовые нули не
учитываются. Если значение в *ColumnName больше BufferLength, оно усекается до
BufferLength.
DataTypePtr [Output] указатель на буфер, в который надо вернуть
SQL-тип данных столбца. Это значение читается из поля SQL_DESC_CONCISE_TYPE в
IRD. Если тип данных не может быть определен, драйвер возвращает
SQL_UNKNOWN_TYPE.
- В 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. Driver
Manager выполняет требуемые отображения, когда прикладная программа ODBC 2.x
работает с драйвером ODBC 3.x.
- Когда ColumnNumber равен 0 (для столбца закладки), SQL_BINARY возвращен в
*DataTypePtr для закладок переменной длины. SQL_INTEGER возвращен, если
закладки используются прикладной программой ODBC 3.x, работающей с драйвером
ODBC 2.x.
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-разрядное дескрипторно-зависимое значение или
целочисленное значение.
4.8.4.1 Синтаксис
SQLRETURN SQLColAttribute(SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLUSMALLINT FieldIdentifier,
SQLPOINTER CharacterAttributePtr,
SQLSMALLINT BufferLength,
SQLSMALLINT* StringLengthPtr,
SQLPOINTER NumericAttributePtr);
4.8.4.2 Параметры
StatementHandle [Input] операторный дескриптор.
ColumnNumber [Input] номер записи в IRD, из которой должно быть
получено значение поля. Этот параметр соответствует номеру столбца данных
результата, упорядоченных последовательно в увеличивающемся порядке, начиная с
1. Столбцы могут быть описаны в любом порядке. Столбец 0 может быть определен в
этом параметре, но все параметры, за исключением SQL_DESC_TYPE и
SQL_DESC_OCTET_LENGTH, возвратят неопределенные значения.
FieldIdentifier [Input] поле в строке ColumnNumber в IRD,
которое должно быть возвращено.
CharacterAttributePtr [Output] указатель на буфер выделенный,
чтобы возвращать значение в поле FieldIdentifier из строки ColumnNumber в IRD,
если поле представляет собой символьную строку. Иначе поле не используется.
BufferLength [Input] если FieldIdentifier определен в ODBC и
CharacterAttributePtr указывает на символьную строку или двоичный буфер, этот
параметр должен быть длиной *CharacterAttributePtr. Если FieldIdentifier
определен в ODBC и *CharacterAttributePtr целое число, это поле игнорируется.
Если *CharacterAttributePtr является строкой в Unicode (при вызове
SQLColAttributeW), параметр BufferLength должен быть четным числом.
Если FieldIdentifier определен в драйвере, прикладная программа указывает
характер поля для Driver Manager, устанавливая параметр BufferLength. Он может
иметь следующие значения:
- Если CharacterAttributePtr указатель на указатель, BufferLength должен
иметь значение SQL_IS_POINTER.
- Если CharacterAttributePtr указатель на символьную строку, BufferLength
определяет длину буфера.
- Если CharacterAttributePtr указатель на двоичный буфер, прикладная
программа помещает результат макроса SQL_LEN_BINARY_ATTR(length) в
BufferLength. Это помещает отрицательное значение в BufferLength.
- Если CharacterAttributePtr указатель на тип данных фиксированной длины,
BufferLength должен быть одним из следующего: SQL_IS_INTEGER,
SQL_IS_UNINTEGER, SQL_SMALLINT или SQLUSMALLINT.
StringLengthPtr [Output] указатель на буфер нужный, чтобы
возвращать общее количество байт, доступное в *CharacterAttributePtr, кроме
хвостовых нулей.
Для символьных данных если число доступных байт больше BufferLength,
информация дескриптора в *CharacterAttributePtr урезается до BufferLength.
Для всех других типов данных значение BufferLength игнорируется, и драйвер
принимает, что размер *CharacterAttributePtr равен 32 битам.
NumericAttributePtr [Output] указатель на целочисленный буфер
нужный, чтобы возвращать значение в поле FieldIdentifier строки ColumnNumber из
IRD, если поле числовой дескрипторный тип, например, SQL_DESC_COLUMN_LENGTH.
Иначе поле не используется.
В ODBC 3.x SQLColAttributes заменена
SQLColAttribute.
SQLBindCol привязывает буферы данных прикладных программ к
столбцам в наборе результатов.
4.8.6.1 Синтаксис
SQLRETURN SQLBindCol(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber,
SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr,
SQLINTEGER BufferLength, SQLLEN* StrLen_or_Ind);
4.8.6.2 Параметры
StatementHandle [Input] операторный дескриптор.
ColumnNumber [Input] номер столбца в наборе результатов, с
которым надо связать буфер. Столбцы пронумерованы в увеличивающемся порядке,
начиная с 0, где столбец с номером 0 является закладкой. Если закладки не
используются, то есть атрибут инструкции SQL_ATTR_USE_BOOKMARKS установлен в
SQL_UB_OFF, столбцы нумеруются, начиная с 1.
TargetType [Input] идентификатор C-типа данных буфера
*TargetValuePtr. При получении данных из источника данных с помощью SQLFetch,
SQLFetchScroll, SQLBulkOperations или SQLSetPos, драйвер преобразовывает данные
к этому типу, а при посылке данных источнику данных с помощью SQLBulkOperations
или SQLSetPos, драйвер преобразовывает данные из этого типа.
TargetValuePtr [Deferred Input/Output] указатель на буфер для
связи со столбцом. SQLFetch и SQLFetchScroll возвращают данные в этом буфере.
SQLBulkOperations получает данные из этого буфера, когда Operation равен
SQL_ADD. SQLSetPos возвращает данные в этом буфере, когда Operation равен
SQL_REFRESH и получает данные из этого буфера, когда Operation равен
SQL_UPDATE.
Если TargetValuePtr равен null, драйвер отвязывает буфер данных от столбца.
Прикладная программа может отвязать все столбцы, вызывая SQLFreeStmt с опцией
SQL_UNBIND. Прикладная программа может отвязать буфер данных от столбца, но все
еще иметь буфер длин связанный со столбцом, если параметр TargetValuePtr в
вызове SQLBindCol равен null, но аргумент StrLen_or_IndPtr представляет собой
имеющее силу значение.
BufferLength [Input] длина в бвйтах *TargetValuePtr. Драйвер
использует BufferLength, чтобы не перезаписать хвост буфера *TargetValuePtr при
возврате данных переменной длины, типа символьных или двоичных данных. Обратите
внимание, что драйвер учитывает хвостовой нулевой символ при возврате символьных
данных в *TargetValuePtr. *TargetValuePtr, следовательно, должен содержать место
для этого символа, или драйвер усечет данные.
Когда данные фиксированной длины, типа целого числа или структуры даты,
драйвер игнорирует BufferLength и принимают, что буфер достаточно большой, чтобы
сохранить данные. Следовательно, для прикладной программы важно распределить
достаточно большой буфер для данных фиксированной длины во избежание проблем с
переполнением.
SQLBindCol возвращает ошибку SQLSTATE HY090 (Invalid string or buffer
length), когда BufferLength меньше 0, но не когда BufferLength равен 0. Однако,
если TargetType определяет символьный тип, прикладная программа не должна
устанавливать BufferLength в 0, поскольку драйверы ISO CLI в этом случае
возвращают SQLSTATE HY090 (Invalid string or buffer length).
StrLen_or_IndPtr [Deferred Input/Output] указатель на буфер длин
для свяхи со столбцом. SQLFetch и SQLFetchScroll возвращают значение в этом
буфере. SQLBulkOperations получает значение из этого буфера, когда параметр
Operation равен SQL_ADD. SQLSetPos возвращает значение в этом буфере, когда
Operation равен SQL_REFRESH и получает значение из этого буфера, когда Operation
равен SQL_UPDATE. SQLFetch, SQLFetchScroll, SQLBulkOperations и SQLSetPos могут
возвращать следующие значения в буфере длин:
- Длина данных, доступных для возврата,
- SQL_NO_TOTAL,
- SQL_NULL_DATA.
Прикладная программа может помещать следующие значения в буфер длин для
использования с SQLBulkOperations или с SQLSetPos:
- Длина данных, доступных для передачи,
- SQL_NTS,
- SQL_NULL_DATA,
- SQL_DATA_AT_EXEC,
- Результат выполнения макроса SQL_LEN_DATA_AT_EXEC,
- SQL_COLUMN_IGNORE (это не поддержано MyODBC и применимо только в MyODBC
3.51).
Если буфер индикаторов и буфер длин разделены, буфер индикаторов может
возвращать только SQL_NULL_DATA, в то время как буфер длин может возвращать все
остальные значения. Если StrLen_or_IndPtr равно null, значения длины или
индикаторов не применяются.
SQLFetch выбирает следующий rowset данных из набора
результатов и возвращает данные для всех связанных столбцов.
4.8.7.1 Синтаксис
SQLRETURN SQLFetch(SQLHSTMT StatementHandle);
4.8.7.2 Параметры
StatementHandle [Input] операторный дескриптор.
4.8.7.3 Комментарии
SQLFetch возвращает следующий rowset в наборе результатов. Это может быть
вызвано только в то время, когда набор результатов существует, то есть после
обращения, которое создает набор результатов и прежде, чем курсор будет закрыт.
Если любые столбцы связаны с данными, этот вызов возвращает данные в этих
столбцах. Если прикладная программа определила указатель на массив состояния или
на буфер нужный, чтобы возвращать число выбранных строк, SQLFetch возвращает
также и эту информацию. Обращение к SQLFetch может быть смешано с обращениями к
SQLFetchScroll, но не может быть смешано с обращениями к SQLExtendedFetch.
SQLFetchScroll выбирает определенный rowset данных из набора
результатов и возвращает данные для всех связанных столбцов. Rowset может быть
определен в абсолютной или относительной позиции или закладкой. При работе с
драйвером ODBC 2.x Driver Manager отображает эту функцию на
SQLExtendedFetch.
4.8.8.1 Синтаксис
SQLRETURN SQLFetchScroll(SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLINTEGER FetchOffset);
4.8.8.2 Параметры
StatementHandle [Input] операторный дескриптор.
FetchOrientation [Input] тип выборки:
- SQL_FETCH_NEXT,
- SQL_FETCH_PRIOR,
- SQL_FETCH_FIRST,
- SQL_FETCH_LAST,
- SQL_FETCH_ABSOLUTE,
- SQL_FETCH_RELATIVE,
- SQL_FETCH_BOOKMARK
FetchOffset [Input] номер строки для выборки. Интерпретация
этого параметра зависит от значения параметра FetchOrientation.
4.8.8.3 Комментарии
Когда набор результатов создан, курсор установлен перед началом набора
результатов. SQLFetchScroll устанавливает блочный курсор, исходя из значений
параметров FetchOrientation и FetchOffset как показано в следующей таблице.
| FetchOritentation |
Смысл |
SQL_FETCH_NEXT |
Вернет следующий rowset. Это эквивалентно вызову SQLFetch.
SQLFetchScroll игнорирует значение FetchOffset. |
SQL_FETCH_PRIOR |
Вернет предшествующий rowset. SQLFetchScroll игнорирует значение
FetchOffset. |
SQL_FETCH_RELATIVE |
Вернет FetchOffset от начала текущего (актуального) rowset. |
SQL_FETCH_ABSOLUTE |
Вернет rowset, начинающийся в строке FetchOffset. |
SQL_FETCH_FIRST |
Вернет первый rowset в наборе результатов. SQLFetchScroll игнорирует
значение FetchOffset. |
SQL_FETCH_LAST |
Вернет последний полный rowset в наборе результатов. SQLFetchScroll
игнорирует значение FetchOffset. |
SQLExtendedFetch выбирает определенный rowset данных из
набора результатов и возвращает данные для всех связанных столбцов. Rowset может
быть определен в абсолютной или относительной позиции.
Обратите внимание в ODBC 3.x SQLExtendedFetch заменен на
SQLFetchScroll. Прикладные программы ODBC 3.x не должны вызвать
SQLExtendedFetch: взамен они должны вызвать SQLFetchScroll.
4.8.9.1 Синтаксис
SQLRETURN SQLExtendedFetch(SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLINTEGER FetchOffset, SQLUINTEGER* RowCountPtr,
SQLUSMALLINT* RowStatusArray);
4.8.9.2 Параметры
StatementHandle [Input] операторный дескриптор.
FetchOrientation [Input] тип выборки. Это аналогично
FetchOrientation в SQLFetchScroll.
FetchOffset [Input] номер столбца для выборки. Аналогично
FetchOffset в SQLFetchScroll.
RowCountPtr [Output] указатель на буфер, куда надо записать
число фактически выбранных строк. Этот буфер используется тем же самым способом,
что и буфер, определенный атрибутом инструкции SQL_ATTR_ROWS_FETCHED_PTR. Этот
буфер используется только SQLExtendedFetch. Это не используется SQLFetch или
SQLFetchScroll.
RowStatusArray [Output] указатель на буфер, куда надо записать
состояние каждой строки. Этот массив используется тем же самым способом, что и
массив, определенный атрибутом инструкции SQL_ATTR_ROW_STATUS_PTR.
Однако, адрес этого массива не сохранен в поле SQL_DESC_STATUS_ARRAY_PTR в
IRD. Кроме того, этот массив используется только SQLExtendedFetch,
SQLBulkOperations при параметре Operation равном SQL_ADD или SQLSetPos, когда
это вызвано после SQLExtendedFetch. SQLFetch или SQLFetchScroll не используют
это вообще, а SQLBulkOperations или SQLSetPos не используют, когда они вызваны
после SQLFetch или SQLFetchScroll. Это также не используется, когда
SQLBulkOperations с параметром Operation равным SQL_ADD вызван прежде, чем
выполнена любая функция выборки. Прикладные программы должны обеспечить имеющий
силу указатель в параметре RowStatusArray. Если это не так, последствия будут
непредсказуемыми.
4.8.9.3 Комментарии
Логика работы SQLExtendedFetch идентична SQLFetchScroll, но:
- SQLExtendedFetch и SQLFetchScroll используют различные методы для возврата
числа выбранных строк. SQLExtendedFetch возвращает число выбранных строк в
*RowCountPtr, а SQLFetchScroll возвращает число выбранных строк
непосредственно в буфер, указанный в SQL_ATTR_ROWS_FETCHED_PTR.
- SQLExtendedFetch и SQLFetchScroll возвращают состояние каждой строки в
различных массивах.
- SQLExtendedFetch не поддерживает закладки переменной длины или выбор
rowset при смещении. отличном от 0.
- SQLExtendedFetch и SQLFetchScroll используют различные размеры rowset.
SQLExtendedFetch использует значение атрибута инструкции SQL_ROWSET_SIZE, а
SQLFetchScroll использует значение атрибута инструкции
SQL_ATTR_ROW_ARRAY_SIZE.
- SQLExtendedFetch имеет немного иную семантику обработки ошибок, чем
SQLFetchScroll.
- SQLExtendedFetch не поддерживает смещения связи (атрибут инструкции
SQL_ATTR_ROW_BIND_OFFSET_PTR.
- Вызов SQLExtendedFetch не может быть смешан с обращениями к SQLFetch или к
SQLFetchScroll, и если SQLBulkOperations вызван прежде, чем отработана любая
функция выборки, то SQLExtendedFetch не может быть вызван, пока курсор не
закрыт и вновь открыт.
SQLGetData получает данные для одиночного столбца в наборе
результатов. Это может быть вызвано неоднократно, чтобы получить данные
переменной длины по частям.
4.8.10.1 Синтаксис
SQLRETURN SQLGetData(SQLHSTMT StatementHandle, SQLUSMALLINT ColumnNumber,
SQLSMALLINT TargetType, SQLPOINTER TargetValuePtr,
SQLINTEGER BufferLength, SQLINTEGER* StrLen_or_IndPtr);
4.8.10.2 Параметры
StatementHandle [Input] операторный дескриптор.
ColumnNumber [Input] номер столбца для возврата данных. Все
столбцы в наборе результатов пронумерованы в увеличивающемся порядке, начиная с
1. Столбец закладки имеет номер столбца, равный 0, это может быть определено
только, если закладки допускаются.
TargetType [Input] идентификатор C-типа данных буфера
*TargetValuePtr. Если это равно SQL_C_DEFAULT, драйвер выбирает заданный по
умолчанию C-тип данных, основываясь на SQL-типе данных источника.
TargetValuePtr [Input] указатель на буфер для приема данных.
BufferLength [Input] длина буфера *TargetValuePtr в байтах.
Драйвер использует BufferLength, чтобы избежать столкновения с *TargetValuePtr
при возврате данных переменной длины, типа символьных или двоичных данных.
Обратите внимание, что драйвер считает хвостовой нуль.
Когда данные имеют фиксированную длину, типа целого числа или структуры даты,
драйвер игнорирует BufferLength и принимает, что буфер достаточно большой, чтобы
сохранить в нем данные.
SQLGetData вернет SQLSTATE HY090 (Invalid string or buffer length), когда
BufferLength меньше 0, но не когда BufferLength равен 0. Если TargetValuePtr
равен null, BufferLength игнорируется драйвером.
StrLen_or_IndPtr [Deferred Input/Output] указатель на буфер
нужный, чтобы возвращать длину или значение индикатора. Если это null, не будет
возвращено ничего. Это возвращает ошибку, когда выбираемые данные NULL.
SQLGetData может возвращать следующие значения в буфере длин/индикатора:
- Длина доступных данных,
- SQL_NO_TOTAL,
- SQL_NULL_DATA.
SQLSetPos устанавливает позицию курсора в rowset и позволяет
прикладной программе обновить данные в rowset, модифицировать или удалять данные
в наборе результатов.
4.8.11.1 Синтаксис
SQLRETURN SQLSetPos(SQLHSTMT StatementHandle, SQLUSMALLINT RowNumber,
SQLUSMALLINT Operation, SQLUSMALLINT LockType);
4.8.11.2 Параметры
StatementHandle [Input]] операторный дескриптор.
RowNumber [Input] позиция строки в rowset над которой надо
выполнить операцию, определенную параметром Operation. Если RowNumber равен 0,
операция применяется к каждой строке в rowset.
Operation [Input] операция для выполнения:
- SQL_POSITION,
- SQL_REFRESH,
- SQL_UPDATE,
- SQL_DELETE.
LockType [Input] определяет, как блокировать строку после
выполнения операции, определенной в параметре Operation:
- SQL_LOCK_NO_CHANGE,
- SQL_LOCK_EXCLUSIVE,
- SQL_LOCK_UNLOCK.
4.8.11.3 Комментарии
Row Number: параметр RowNumber определяет номер строки в
rowset, с которой надо работать. Если RowNumber равен 0, операция применяется к
каждой строке в rowset. RowNumber должен быть значением от 0 до максимального
количества строк в rowset. Обратите внимание, что в языке C массивы
отсчитываются от 0, RowNumber реально отсчитывается от 1. Например, чтобы
модифицировать пятую строку rowset, прикладная программа изменяет буфер rowset в
массиве с индексом 4, но определяет RowNumber=5! Все операции устанавливают
курсор в строку, определенную RowNumber. Следующие операции требуют
позиционирования курсора:
- Позиционное удаление и обновление.
- Вызов SQLGetData.
- Вызов SQLSetPos с опциями SQL_DELETE, SQL_REFRESH и SQL_UPDATE.
Например, если 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 и выборку по закладке.
4.8.12.1 Синтаксис
SQLRETURN SQLBulkOperations(SQLHSTMT StatementHandle,
SQLUSMALLINT Operation);
4.8.12.2 Параметры
StatementHandle [Input] операторный дескриптор.
Operation [Input] операция для выполнения: SQL_ADD.
Обратите внимание: сейчас никакие операции с закладками драйвером не
поддерживаются.
4.8.12.3 Комментарии
Выполнение оптовых вставок:
Чтобы вставлять данные с помощью SQLBulkOperations, прикладная программа
выполняет следующую последовательность шагов:
- Выполняет запрос, который возвращает набор результатов.
- Устанавливает атрибут инструкции SQL_ATTR_ROW_ARRAY_SIZE в число строк,
которые требуется вставить.
- Вызывает
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), чтобы выполнить вставку.
- Если прикладная программа установила атрибут инструкции
SQL_ATTR_ROW_STATUS_PTR, она может осматривать этот массив, чтобы увидеть
результат операции.
SQLError возвращает информацию состояния или ошибку.
Прикладная программа обычно вызывает SQLError, когда предыдущая функция ODBC
возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO. В ODBC 3.x SQLGetDiagRec
заменила функцию ODBC 2.0 SQLError.
SQLGetDiagField возвращает текущее (актуальное) значение
поля записи диагностической структуры данных (связанной с определенным
дескриптором), которое содержит ошибку, предупреждение и информацию состояния.
4.9.2.1 Синтаксис
SQLRETURN SQLGetDiagField(SQLSMALLINT HandleType, SQLHANDLE Handle,
SQLSMALLINT RecNumber, SQLSMALLINT DiagIdentifier,
SQLPOINTER DiagInfoPtr, SQLSMALLINT BufferLength,
SQLSMALLINT* StringLengthPtr);
4.9.2.2 Параметры
HandleType [Input] идентификатор типа дескриптора, который
описывает тип дескриптора для которого требуется диагностика. Должен быть одним
из следующего: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT или
SQL_HANDLE_DESC (не поддерживается).
Handle [Input] дескриптор для диагностической структуры данных.
Тип обозначен в HandleType.
RecNumber [Input] указывает запись состояния, из которой
прикладная программа ищет информацию. Записи состояния пронумерованы, начиная с
1. Если параметр DiagIdentifier указывает, любое поле диагностического
заголовка, RecNumber игнорируется. В противном случае это должно быть больше
0.
DiagIdentifier [Input] указывает поле диагностики, чье значение
должно быть возвращено.
DiagInfoPtr [Output] указатель на буфер выделенный, чтобы
возвращать диагностическую информацию. Тип данных зависит от значения
DiagIdentifier.
BufferLength [Input] если DiagIdentifier определен в ODBC и
DiagInfoPtr указывает на строку или двоичный буфер, этот параметр должен быть
длиной *DiagInfoPtr. Если DiagIdentifier определен в ODBC и *DiagInfoPtr
является целым числом, BufferLength игнорируется. BufferLength может иметь
следующие значения:
- Если *ValuePtr указатель на символьную строку, то BufferLength задает
длину строки или SQL_NTS.
- Если *ValuePtr указатель на двоичный буфер, то прикладная программа
помещает результат макроса SQL_LEN_BINARY_ATTR(length) в BufferLength.
- Если *ValuePtr указатель на другое значение, то BufferLength имеет
значение SQL_IS_POINTER.
- Если *ValuePtr содержит тип данных фиксированной длины, то BufferLength
равен SQL_IS_INTEGER, SQL_IS_UINTEGER, SQL_IS_SMALLINT или SQL_IS_USMALLINT.
StringLengthPtr [Output] указатель на буфер распределенный,
чтобы возвращать общее количество байт, доступных в *DiagInfoPtr (только для
символьных данных, хвостовые нули не считаются).
4.9.2.3 Комментарии
SQLGetDiagField не регистрирует диагностические записи для
себя. Это использует следующие значения возврата, чтобы сообщить результат
собственного выполнения:
- SQL_SUCCESS: функция успешно вернула диагностическую информацию.
- SQL_SUCCESS_WITH_INFO: *DiagInfoPtr был слишком маленький, чтобы вместить
запрошенное диагностическое поле, так что данные в диагностическом поле были
усечены. Чтобы определить, что усечение произошло, прикладная программа должна
сравнить BufferLength с фактическом числом доступных байт, которое записано в
*StringLengthPtr.
- SQL_INVALID_HANDLE: дескриптор, обозначенный HandleType и Handle, не был
имеющим силу дескриптором.
- SQL_ERROR: одно из следующего произошло:
- Параметр DiagIdentifier не был одним из имеющих силу значений.
- Параметр DiagIdentifier был SQL_DIAG_CURSOR_ROW_COUNT,
SQL_DIAG_DYNAMIC_FUNCTION, SQL_DIAG_DYNAMIC_FUNCTION_CODE или
SQL_DIAG_ROW_COUNT, но дескриптор не был операторным. Driver Manager
возвращает эту диагностику.
- Параметр RecNumber был отрицательным или 0, когда DiagIdentifier указал
поле из диагностической записи. RecNumber игнорируется для полей заголовка.
Запрошенное значение было символьной строкой, а BufferLength меньше нуля.
- SQL_NO_DATA: RecNumber больше, чем число диагностических записей для
дескриптора, определенного в Handle. Функция также возвращает SQL_NO_DATA для
любого положительного RecNumber, если не имеется никаких диагностических
записей для дескриптора.
Прикладная программа обычно вызывает SQLGetDiagField, чтобы выполнить одну из
трех целей:
- Получить специфическую информацию об ошибке или предупреждение, когда
обращение к функции возвратило SQL_ERROR или SQL_SUCCESS_WITH_INFO.
- Чтобы выяснить число строк в источнике данных, на которые воздействовали
операции insert, delete или update при вызове SQLExecute, SQLExecDirect,
SQLBulkOperations или SQLSetPos (из поля SQL_DIAG_ROW_COUNT заголовка), или
выяснить число строк, открытом курсоре, если драйвер способен обеспечить эту
информацию (из поля SQL_DIAG_CURSOR_ROW_COUNT заголовка).
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, местный код ошибки и диагностический
текст сообщения.
4.9.3.1 Синтаксис
SQLRETURN SQLGetDiagRec(SQLSMALLINT HandleType, SQLHANDLE Handle,
SQLSMALLINT RecNumber, SQLCHAR* Sqlstate,
SQLINTEGER* NativeErrorPtr, SQLCHAR* MessageText,
SQLSMALLINT BufferLength, SQLSMALLINT* TextLengthPtr);
4.9.3.2 Параметры
HandleType [Input] идентификатор типа дескриптора, который
описывает тип дескриптора, для которого диагностика требуется. Должен быть одним
из следующего: SQL_HANDLE_ENV, SQL_HANDLE_DBC,
SQL_HANDLE_STMT или SQL_HANDLE_DESC (не
поддерживается).
Handle [Input] дескриптор для диагностической структуры данных.
Тип задан в HandleType.
RecNumber [Input] указывает запись состояния, из которой
прикладная программа получает информацию. Записи состояния пронумерованы с 1.
SQLState [Output] указатель на буфер нужный, чтобы возвращать
код пятисимвольного SQLSTATE, имеющий отношение к диагностической записи
RecNumber.
NativeErrorPtr [Output] указатель на буфер выделенный, чтобы
возвращать местный код ошибки, специфический для источника данных. Эта
информация содержится в диагностическом поле SQL_DIAG_NATIVE.
MessageText [Output] указатель на буфер выделенный, чтобы
возвращать диагностический текст сообщения. Эта информация содержится в
диагностическом поле SQL_DIAG_MESSAGE_TEXT.
BufferLength [Input] длина буфера *MessageText в символах. Не
имеется никакой максимальной длины диагностического текста сообщения.
TextLengthPtr [Output] указатель на буфер для возврата общего
количество байтов, доступных в *MessageText (кроме хвостовых нулей).
4.9.3.3 Комментарии
Прикладная программа обычно вызывает SQLGetDiagRec, когда предыдущее
обращение к функции ODBC возвратило SQL_SUCCESS или SQL_SUCCESS_WITH_INFO.
Однако, поскольку любая функция ODBC может регистрировать ноль или большее
количество диагностических записей каждый вызов, прикладная программа может
вызывать SQLGetDiagRec после любого обращения к функции ODBC.
SQLColumnPrivileges возвращает список столбцов и связанных
привилегий для определенной таблицы. Драйвер возвращает информацию как набор
результатов на определенном StatementHandle.
4.10.1.1 Синтаксис
SQLRETURN SQLColumnPrivileges(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLCHAR* ColumnName,
SQLSMALLINT NameLength4);
4.10.1.2 Параметры
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют
имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть null.
TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
ColumnName [Input] образец поиска строки с именем столбца.
NameLength4 [Input] длина *ColumnName.
SQLColumns возвращает список имен столбцов в определенных
таблицах. Драйвер возвращает эту информацию в наборе результатов на определенном
StatementHandle.
4.10.2.1 Синтаксис
SQLRETURN SQLColumns(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLCHAR* ColumnName,
SQLSMALLINT NameLength4);
4.10.2.2 Параметры
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют
имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть null.
TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
ColumnName [Input] образец поиска строки с именем столбца.
NameLength4 [Input] длина *ColumnName.
SQLForeignKeys может вернуть:
- Список внешних ключей в определенной таблице (столбцы в определенной
таблице, которые обращаются к первичным ключам в других таблицах).
- Список внешних ключей в других таблицах, которые обращаются к первичному
ключу в определенной таблице.
Драйвер возвращает каждый список в наборе результатов на определенной
инструкции.
4.10.3.1 Синтаксис
SQLRETURN SQLForeignKeys(SQLHSTMT StatementHandle, SQLCHAR* PKCatalogName,
SQLSMALLINT NameLength1, SQLCHAR* PKSchemaName,
SQLSMALLINT NameLength2, SQLCHAR* PKTableName,
SQLSMALLINT NameLength3, SQLCHAR* FKCatalogName,
SQLSMALLINT NameLength4, SQLCHAR* FKSchemaName,
SQLSMALLINT NameLength5, SQLCHAR* FKTableName,
SQLSMALLINT NameLength6);
4.10.3.2 Параметры
StatementHandle [Input] операторный дескриптор.
PKCatalogName [Input] имя каталога первичного ключа таблицы.
Если драйвер поддерживает имена для некоторых каталогов, но не для всех
(например, при одновременной работе с разными СУБД), пустая строка обозначает те
каталоги, которые не имеют имен. CatalogName не может содержать образец поиска
строки!
NameLength1 [Input] длина *PKCatalogName в байтах.
PKSchemaName [Input] имя схемы первичного ключа таблицы. Если
драйвер поддерживает схемы для некоторых каталогов, но не для всех (например,
при одновременной работе с разными СУБД), пустая строка обозначает те схемы,
которые не имеют имен. SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *PKSchemaName в байтах.
PKTableName [Input] имя таблицы с первичным ключом. Этот
параметр не может быть null. TableName не может содержать образец поиска
строки.
NameLength3 [Input] длина *PKTableName в байтах.
PKCatalogName [Input] имя каталога внешнего ключа таблицы. Если
драйвер поддерживает имена для некоторых каталогов, но не для всех (например,
при одновременной работе с разными СУБД), пустая строка обозначает те каталоги,
которые не имеют имен. CatalogName не может содержать образец поиска строки!
NameLength4 [Input] длина *FKCatalogName в байтах.
PKSchemaName [Input] имя схемы внешнего ключа таблицы. Если
драйвер поддерживает схемы для некоторых каталогов, но не для всех (например,
при одновременной работе с разными СУБД), пустая строка обозначает те схемы,
которые не имеют имен. SchemaName не может содержать образец поиска строки!
NameLength5 [Input] длина *FKSchemaName в байтах.
FKTableName [Input] имя таблицы с внешним ключом. Этот параметр
не может быть null. TableName не может содержать образец поиска строки.
NameLength6 [Input] длина *FKTableName в байтах.
SQLPrimaryKeys возвращает имена столбцов, которые составляют
первичный ключ для таблицы. Драйвер возвращает информацию в наборе результатов.
Эта функция не поддерживает первичные ключи из нескольких таблиц сразу в одном
обращении.
4.10.4.1 Синтаксис
SQLRETURN SQLPrimaryKeys(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3);
4.10.4.2 Параметры
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют
имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть null.
TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
SQLSpecialColumns возвращает следующую информацию
относительно столбцов внутри определенной таблицы:
- Оптимальный набор столбцов, который уникально идентифицирует строку в
таблице.
- Столбцы, которые автоматически модифицируются, когда любое значение в
строка модифицируется транзакцией.
4.10.5.1 Синтаксис
SQLRETURN SQLSpecialColumns(SQLHSTMT StatementHandle,
SQLSMALLINT IdentifierType, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLSMALLINT Scope,
SQLSMALLINT Nullable);
4.10.5.2 Параметры
StatementHandle [Input] операторный дескриптор.
IdentifierType [Input] тип столбца для возврата. Должен быть
одним из следующих значений:
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 возвращает статистику относительно одной
таблицы и индексов, связанных с этой таблицей. Драйвер возвращает информацию в
наборе результатов.
4.10.6.1 Синтаксис
SQLRETURN SQLStatistics(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLUSMALLINT Unique,
SQLUSMALLINT Reserved);
4.10.6.2 Параметры
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют
имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть null.
TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
Unique [Input] тип индекса: SQL_INDEX_UNIQUE или
SQL_INDEX_ALL.
Reserved [Input] указывает важность CARDINALITY в столбце PAGES
набора результатов. Следующие параметры воздействуют на возврат только столбцов
CARDINALITY и PAGES (индексная информация возвращена, даже если CARDINALITY и
PAGES не возвращены):
SQL_ENSURE требует, чтобы драйвер безоговорочно получил
статистику. Драйверы, которые согласовываются только со стандартом X/Open и не
поддерживают ODBC-расширения, не способны поддерживать SQL_ENSURE.
SQL_QUICK требует, чтобы драйвер получил CARDINALITY и PAGES
только если они легко доступны с сервера. В этом случае драйвер не
гарантирует, что значения актуальны. Прикладные программы, которые написаны в
стандарте X/Open, будут всегда получать SQL_QUICK из драйверов ODBC
3.x.
SQLTablePrivileges возвращает список таблиц и привилегий,
связанных с каждой таблицей. Драйвер возвращает информацию в наборе результатов
на определенной инструкции.
4.10.7.1 Синтаксис
SQLRETURN SQLTablePrivileges(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3);
4.10.7.2 Параметры
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют
имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть null.
TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
SQLTables возвращает список имен таблиц, каталогов, схем и
типов таблиц, сохраненных в специфическом источнике данных. Драйвер возвращает
информацию в наборе результатов.
4.10.8.1 Синтаксис
SQLRETURN SQLTables(SQLHSTMT StatementHandle, SQLCHAR* CatalogName,
SQLSMALLINT NameLength1, SQLCHAR* SchemaName,
SQLSMALLINT NameLength2, SQLCHAR* TableName,
SQLSMALLINT NameLength3, SQLCHAR* TableType,
SQLSMALLINT NameLength4);
4.10.8.2 Параметры
StatementHandle [Input] операторный дескриптор.
CatalogName [Input] имя каталога. Если драйвер поддерживает
имена для некоторых каталогов, но не для всех (например, при одновременной
работе с разными СУБД), пустая строка обозначает те каталоги, которые не имеют
имен. CatalogName не может содержать образец поиска строки!
NameLength1 [Input] длина *CatalogName.
SchemaName [Input] имя схемы. Если драйвер поддерживает схемы
для некоторых каталогов, но не для всех (например, при одновременной работе с
разными СУБД), пустая строка обозначает те схемы, которые не имеют имен.
SchemaName не может содержать образец поиска строки!
NameLength2 [Input] длина *SchemaName.
TableName [Input] имя таблицы. Этот параметр не может быть null.
TableName не может содержать образец поиска строки.
NameLength3 [Input] длина *TableName.
Table Type [Input] список типов таблиц.
NameLength4 [Input] длина *TableType.
SQLTransact запрашивает завершение или отмену для всех
активных операций на всех инструкциях, связанных с подключением. SQLTransact
может также запрашивать это для всех подключений, связанных со средой. В ODBC
3.x SQLEndTran заменил функцию ODBC 2.x SQLTransact.
SQLEndTran запрашивает завершение или отмену для всех
активных операций на всех инструкциях, связанных с подключением. SQLEndTran
может также запрашивать это для всех подключений, связанных со средой.
4.11.2.1 Синтаксис
SQLRETURN SQLEndTran(SQLSMALLINT HandleType, SQLHANDLE Handle,
SQLSMALLINT CompletionType);
4.11.2.2 Параметры
HandleType [Input] идентификатор типа дескриптора. Содержит
SQL_HANDLE_ENV (если Handle дескриптор среды) или SQL_HANDLE_DBC (если Handle
представляет собой дескриптор подключения).
Handle [Input] дескриптор, тип коего задан в HandleType,
указывает контекст транзакции.
CompletionType [Input] одно из следующтх двух значений:
SQL_COMMIT или
SQL_ROLLBACK.
SQLFreeStmt останавливает обработку, связанную со
специфической инструкцией, закрывает любые открытые курсоры, связанные с этой
инструкцией, отбрасывает ждущие обработки результаты и, факультативно,
освобождает все ресурсы, связанные с операторным дескриптором.
4.12.1.1 Синтаксис
SQLRETURN SQLFreeStmt(SQLHSTMT StatementHandle, SQLUSMALLINT Option);
4.12.1.2 Параметры
StatementHandle [Input] операторный дескриптор.
Option [Input] одни из следующих параметров:
| Опция |
Действие |
SQL_CLOSE |
Закрывает курсор, связанный с StatementHandle (если он был определен)
и отбрасывает все ждущие обработки результаты. Прикладная программа может
вновь открыть этот курсор позже, выполняя инструкцию SELECT с теми же
самыми или иными значениями параметра. Если никакой курсор не открыт, эта
опция не имеет никакого эффекта для прикладной программы. SQLCloseCursor
может также быть вызван, чтобы закрыть курсор. |
SQL_DROP |
Освобождает операторный дескриптор: освобождает все ресурсы, связанных
с ним, отбрасывает все ждущие обработки операции и закрывает курсор.
Операторный дескриптор должен быть перераспределен для повторного
использования. Эта опция устарела в MyODBC 3.51. Вызов SQLFreeStmt с
параметром Option равным SQL_DROP отображается на вызов
SQLFreeHandle. |
SQL_UNBIND |
Освобождает все буферы столбцов, связанные SQLBindCol для данного
операторного дескриптора. |
SQL_RESET_PARAMS |
Освобождает весь набор буферов параметров SQLBindParameter для данного
операторного дескриптора. |
SQLCloseCursor закрывает курсор, который был открыт на
инструкции и отбрасывает ждущие обработки результаты.
4.12.2.1 Синтаксис
SQLRETURN SQLCloseCursor(SQLHSTMT StatementHandle);
4.12.2.2 Параметры
StatementHandle [Input] операторный дескриптор.
SQLCancel отменяет обработку инструкции.
4.12.3.1 Синтаксис
SQLRETURN SQLCancel(SQLHSTMT StatementHandle);
4.12.3.2 Параметры
StatementHandle [Input] операторный дескриптор.
4.12.3.3 Комментарии
SQLCancel может отменять следующие типы обработки инструкции:
- Функция, которая нуждается в данных.
- Функция из другого потгока.
- Функция выполняется асинхронно, и драйвер не поддерживает асинхронное
выполнение.
В ODBC 2.x, если из прикладной программы вызвана SQLCancel, когда обработка
не делается на инструкции, SQLCancel имеют тот же самый эффект, что и
SQLFreeStmt с опцией SQL_CLOSE. Это поведение определено только для
законченности реализации, и прикладные программы должны вызвать SQLFreeStmt или
SQLCloseCursor, чтобы закрыть курсоры.
SQLDisconnect закрывает подключение, связанное со
специфическим дескриптором подключения.
4.12.4.1 Синтаксис
SQLRETURN SQLDisconnect(SQLHDBC ConnectionHandle);
4.12.4.2 Параметры
ConnectionHandle [Input] дескриптор подключения.
4.12.4.3 Комментарии
Если из прикладной программы вызвана SQLDisconnect, в то время как имеется
незавершенная транзакция, связанная с дескриптором подключения, драйвер
возвращает SQLSTATE 25000 (Invalid transaction state) указывая, что транзакция
является неизменяемой, и подключение открыто. Незавершенной транзакцией является
такая, которая не была ни завершена, ни отменена с помощью вызова
SQLEndTran.
Если из прикладной программы вызвана SQLDisconnect прежде, чем были
освобождены все инструкции, связанные с подключением, драйвер после того, как
успешно завершит отсоединение от сервера, освобождает те инструкции и все
дескрипторы, которые были явно распределены на подключении.
SQLFreeHandle освобождает ресурсы, связанные со
специфической средой, подключением, инструкцией или дескриптором.
Обратите внимание, что это универсальная функция для
освобождения дескрипторов. Это заменяет функции ODBC 2.0 SQLFreeConnect (для
освобождения дескриптора подключения) и SQLFreeEnv (для освобождения дескриптора
среды). SQLFreeConnect и SQLFreeEnv устарели в ODBC 3.x. SQLFreeHandle также
заменяет функцию ODBC 2.0 SQLFreeStmt (с Option равным SQL_DROP) для
освобождения операторного дескриптора.
4.12.5.1 Синтаксис
SQLRETURN SQLFreeHandle(SQLSMALLINT HandleType, SQLHANDLE Handle);
4.12.5.2 Параметры
HandleType [Input] тип дескриптора, который будет освобожден
SQLFreeHandle. Должен быть одним из следующих значений:
SQL_HANDLE_ENV,
SQL_HANDLE_DBC,
SQL_HANDLE_STMT или
SQL_HANDLE_DESC (не поддерживается)
Если HandleType не одно из этих значений, SQLFreeHandle возвращает
SQL_INVALID_HANDLE.
Handle [Input] дескриптор, который будет освобожден.
4.12.5.3 Комментарии
Освобождение дескриптора среды:
До вызова SQLFreeHandle с
HandleType равным SQL_HANDLE_ENV прикладная программа должна вызвать
SQLFreeHandle с HandleType равным SQL_HANDLE_DBC для всех подключений,
распределенных средой. Иначе обращение к SQLFreeHandle возвращает SQL_ERROR, а
среда и любое активное подключение остаются прежними.
Освобождение дескриптора подключения:
До вызова
SQLFreeHandle с HandleType равным SQL_HANDLE_DBC прикладная программа должна
вызвать SQLDisconnect для подключения, если имеется подключение на этом
дескрипторе. Иначе обращение к SQLFreeHandle возвращает SQL_ERROR, а подключение
остается прежним.
Освобождение операторного дескриптора:
Обращение к
SQLFreeHandle с HandleType равным SQL_HANDLE_STMT освобождает все ресурсы,
которые были распределены обращением SQLAllocHandle с HandleType равным
SQL_HANDLE_STMT. Когда из прикладной программы вызывается SQLFreeHandle, чтобы
освободить инструкцию, которая имеет ждущие обработки результаты, они будут
автоматически удалены. Обратите внимание, что SQLDisconnect автоматически
уничтожает любые инструкции и дескрипторы, открытые на подключении.
SQLFreeConnect освобождает дескриптор подключения и всю
память, связанную с этим дескриптором. В ODBC 3.x SQLFreeHandle заменил собой
функцию ODBC 2.0 SQLFreeConnect.
SQLFreeEnv освобождает дескриптор среды и всю память,
связанную с дескриптором среды. В ODBC 3.x SQLFreeHandle заменил собой функцию
ODBC 2.0 SQLFreeEnv.
содержание назад вперед
Виртуальные VPS серверы в РФ и ЕС
🔥 VPS до 5.7 ГГц под любые задачи с AntiDDoS в 7 локациях
