[ новости /+++ | форум | теги | ]

Каталог документации / Раздел "Базы данных, SQL" / Оглавление документа

4 Функции в MyODBC API

Эта глава руководства описывает каждую функцию (синтаксис, параметры и использование). Каждая функция определена как функция языка программирования 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 как код возврата при поставке длинных данных порциями.

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

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

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

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

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

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

4.3.1 SQLAllocHandle

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

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

4.3.1.1 Синтаксис

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

4.3.1.2 Параметры

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

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

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

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

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

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

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

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

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

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

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

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

4.3.2 SQLAllocEnv

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

4.3.2.1 Синтаксис

SQLRETURN SQLAllocEnv(HENV* EnvironmentHandle);

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

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

4.3.3 SQLAllocConnect

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

4.3.3.1 Синтаксис

SQLRETURN SQLAllocConnect(HENV EnvironmentHandle, HDBC* ConnectionHandle);

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

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

4.3.4 SQLConnect

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

4.3.4.1 Синтаксис

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

4.3.4.2 Параметры

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

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

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

UserName[Input] User id.

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

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

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

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

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

4.3.5 SQLDriverConnect

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

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

• Устанавливает подключение, использующее строку подключения, которая содержит имя источника данных, идентификатор пользователя, пароль и другую информацию, требуемую сервером.
• Устанавливает подключение, используя частичную строку подключения. В этом случае 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.

4.3.6 SQLBrowseConnect

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

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

4.4.1 SQLDataSources

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

4.4.2 SQLDrivers

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

4.4.3 SQLGetInfo

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

4.4.3.1 Синтаксис

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

4.4.3.2 Параметры

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

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

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

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

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

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

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

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

4.4.4 SQLGetFunctions

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

4.4.4.1 Синтаксис

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

4.4.4.2 Параметры

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

FunctionId [Input] SQL_API_ODBC3_ALL_FUNCTIONS или SQL_API_ALL_FUNCTIONS.

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

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

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

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

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

4.4.5 SQLGetTypeInfo

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

4.4.5.1 Синтаксис

SQLRETURN SQLGetTypeInfo(SQLHSTMT StatementHandle, SQLSMALLINT DataType);

4.4.5.2 Параметры

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

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

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

4.5.1 SQLSetConnectAttr

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

4.5.1.1 Синтаксис

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

4.5.1.2 Параметры

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

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

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

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

• Если 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:

4.5.2 SQLGetConnectAttr

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

4.5.2.1 Синтаксис

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

4.5.2.2 Параметры

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

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

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

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

• Если *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.

4.5.3 SQLSetConnectOption

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

4.5.4 SQLGetConnectOption

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

4.5.5 SQLSetEnvAttr

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

4.5.5.1 Синтаксис

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

4.5.5.2 Параметры

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

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

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

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

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

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

4.5.6 SQLGetEnvAttr

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

4.5.6.1 Синтаксис

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

4.5.6.2 Параметры

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

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

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

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

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

4.5.7 SQLSetStmtAttr

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

4.5.7.1 Синтаксис

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

4.5.7.2 Параметры

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

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

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.

4.5.8 SQLGetStmtAttr

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

4.5.8.1 Синтаксис

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

4.5.8.2 Параметры

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

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

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

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

• Если *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.

4.5.9 SQLSetStmtOption

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

4.5.10 SQLGetStmtOption

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

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

4.6.1 SQLAllocStmt

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

4.6.1.1 Синтаксис

SQLRETURN SQLAllocStmt(HDBC ConnectionHandle, HSTMT* StatementHandle);

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

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

4.6.2 SQLPrepare

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

4.6.2.1 Синтаксис

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

4.6.2.2 Параметры

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

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

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

4.6.3 SQLBindParameter

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

4.6.3.1 Синтаксис

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

4.6.3.2 Параметры

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

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

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

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

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

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

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

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

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

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

4.6.4 SQLGetCursorName

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

4.6.4.1 Синтаксис

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

4.6.4.2 Параметры

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

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

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

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

4.6.5 SQLSetCursorName

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

4.6.5.1 Синтаксис

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

4.6.5.2 Параметры

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

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

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

4.6.6 SQLSetScrollOptions

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

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

4.7.1 SQLExecute

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

4.7.1.1 Синтаксис

SQLRETURN SQLExecute(SQLHSTMT StatementHandle);

4.7.1.2 Параметры

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

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

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

4.7.2 SQLExecDirect

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

4.7.2.1 Синтаксис

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

4.7.2.2 Параметры

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

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

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

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

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

4.7.3 SQLNativeSql

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

4.7.3.1 Синтаксис

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

4.7.3.2 Параметры

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

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

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

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

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

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

4.7.4 SQLDescribeParam

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

4.7.4.1 Синтаксис

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

4.7.4.2 Параметры

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

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

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

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

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

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

• SQL_NO_NULLS: параметр не позволяет значения NULL (это значение по умолчанию).
• SQL_NULLABLE: параметр позволяет значения NULL.
• SQL_NULLABLE_UNKNOWN: драйвер не может определить, позволяет ли параметр значения NULL.

4.7.5 SQLNumParams

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

4.7.5.1 Синтаксис

SQLRETURN SQLNumParams(SQLHSTMT StatementHandle,
                       SQLSMALLINT* ParameterCountPtr);

4.7.5.2 Параметры

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

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

4.7.6 SQLParamData

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

4.7.6.1 Синтаксис

SQLRETURN SQLParamData(SQLHSTMT StatementHandle, SQLPOINTER* ValuePtrPtr);

4.7.6.2 Параметры

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

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

4.7.7 SQLPutData

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

4.7.7.1 Синтаксис

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

4.7.7.2 Параметры

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

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

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

• 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 и посылает все значения.

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

4.8.1 SQLRowCount

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

4.8.1.1 Синтаксис

SQLRETURN SQLRowCount(SQLHSTMT StatementHandle, SQLINTEGER* RowCountPtr);

4.8.1.2 Параметры

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

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

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

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

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

4.8.2 SQLNumResultCols

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

4.8.2.1 Синтаксис

SQLRETURN SQLNumResultCols(SQLHSTMT StatementHandle,
                           SQLSMALLINT* ColumnCountPtr);

4.8.2.2 Параметры

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

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

4.8.3 SQLDescribeCol

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

4.8.3.1 Синтаксис

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

4.8.3.2 Параметры

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

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

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

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

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

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

• В 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.

4.8.4 SQLColAttribute

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

4.8.4.1 Синтаксис

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

4.8.4.2 Параметры

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

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

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

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

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

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

• Если 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. Иначе поле не используется.

4.8.5 SQLColAttributes

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

4.8.6 SQLBindCol

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

4.8.6.1 Синтаксис

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

4.8.6.2 Параметры

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

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

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

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

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

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

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

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

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

• Длина данных, доступных для возврата,
• 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, значения длины или индикаторов не применяются.

4.8.7 SQLFetch

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

4.8.7.1 Синтаксис

SQLRETURN SQLFetch(SQLHSTMT StatementHandle);

4.8.7.2 Параметры

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

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

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

4.8.8 SQLFetchScroll

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

4.8.8.1 Синтаксис

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

4.8.8.2 Параметры

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

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

• 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 как показано в следующей таблице.

4.8.9 SQLExtendedFetch

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

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

4.8.9.1 Синтаксис

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

4.8.9.2 Параметры

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

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

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

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

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

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

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

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

• 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 не может быть вызван, пока курсор не закрыт и вновь открыт.

4.8.10 SQLGetData

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

4.8.10.1 Синтаксис

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

4.8.10.2 Параметры

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

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

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

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

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

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

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

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

• Длина доступных данных,
• SQL_NO_TOTAL,
• SQL_NULL_DATA.

4.8.11 SQLSetPos

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

4.8.11.1 Синтаксис

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

4.8.11.2 Параметры

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

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

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

• 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.

4.8.12 SQLBulkOperations

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

4.8.12.1 Синтаксис

SQLRETURN SQLBulkOperations(SQLHSTMT StatementHandle,
                            SQLUSMALLINT Operation);

4.8.12.2 Параметры

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

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

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

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

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

1. Выполняет запрос, который возвращает набор результатов.
2. Устанавливает атрибут инструкции SQL_ATTR_ROW_ARRAY_SIZE в число строк, которые требуется вставить.
3. Вызывает SQLBindCol, чтобы привязать данные, которые требуется вставлять. Данные будут привязаны к массиву с размером, равным значению SQL_ATTR_ROW_ARRAY_SIZE. Обратите внимание, что размер массива, указанного атрибутом инструкции SQL_ATTR_ROW_STATUS_PTR должен быть равен SQL_ATTR_ROW_ARRAY_SIZE, или SQL_ATTR_ROW_STATUS_PTR должен быть null.
4. Вызывает SQLBulkOperations(StatementHandle, SQL_ADD), чтобы выполнить вставку.
5. Если прикладная программа установила атрибут инструкции SQL_ATTR_ROW_STATUS_PTR, она может осматривать этот массив, чтобы увидеть результат операции.

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

4.9.1 SQLError

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

4.9.2 SQLGetDiagField

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

4.9.2.1 Синтаксис

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

4.9.2.2 Параметры

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

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

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

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

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

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

• Если *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, чтобы выполнить одну из трех целей:

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

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

DiagIdentifier	Тип возврата	Возвращаемое значение
SQL_DIAG_CURSOR_ROW_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 возвращаются.

4.9.3 SQLGetDiagRec

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

4.9.3.1 Синтаксис

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

4.9.3.2 Параметры

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

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

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

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

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

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

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

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

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

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

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

4.10.1 SQLColumnPrivileges

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

4.10.1.1 Синтаксис

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

4.10.1.2 Параметры

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

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

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

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

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

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

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

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

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

4.10.2 SQLColumns

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

4.10.2.1 Синтаксис

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

4.10.2.2 Параметры

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

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

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

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

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

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

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

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

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

4.10.3 SQLForeignKeys

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

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

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

4.10.3.1 Синтаксис

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

4.10.3.2 Параметры

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

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

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

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

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

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

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

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

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

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

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

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

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

4.10.4 SQLPrimaryKeys

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

4.10.4.1 Синтаксис

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

4.10.4.2 Параметры

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

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

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

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

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

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

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

4.10.5 SQLSpecialColumns

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

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

4.10.5.1 Синтаксис

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

4.10.5.2 Параметры

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

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

• 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.

4.10.6 SQLStatistics

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

4.10.6.1 Синтаксис

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

4.10.6.2 Параметры

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

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

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

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

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

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

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

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

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

• SQL_ENSURE требует, чтобы драйвер безоговорочно получил статистику. Драйверы, которые согласовываются только со стандартом X/Open и не поддерживают ODBC-расширения, не способны поддерживать SQL_ENSURE.
• SQL_QUICK требует, чтобы драйвер получил CARDINALITY и PAGES только если они легко доступны с сервера. В этом случае драйвер не гарантирует, что значения актуальны. Прикладные программы, которые написаны в стандарте X/Open, будут всегда получать SQL_QUICK из драйверов ODBC 3.x.

4.10.7 SQLTablePrivileges

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

4.10.7.1 Синтаксис

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

4.10.7.2 Параметры

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

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

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

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

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

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

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

4.10.8 SQLTables

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

4.10.8.1 Синтаксис

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

4.10.8.2 Параметры

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

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

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

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

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

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

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

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

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

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

4.11.1 SQLTransact

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

4.11.2 SQLEndTran

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

4.11.2.1 Синтаксис

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

4.11.2.2 Параметры

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

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

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

• SQL_COMMIT или
• SQL_ROLLBACK.

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

4.12.1 SQLFreeStmt

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

4.12.1.1 Синтаксис

SQLRETURN SQLFreeStmt(SQLHSTMT StatementHandle, SQLUSMALLINT Option);

4.12.1.2 Параметры

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

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

4.12.2 SQLCloseCursor

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

4.12.2.1 Синтаксис

SQLRETURN SQLCloseCursor(SQLHSTMT StatementHandle);

4.12.2.2 Параметры

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

4.12.3 SQLCancel

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

4.12.3.1 Синтаксис

SQLRETURN SQLCancel(SQLHSTMT StatementHandle);

4.12.3.2 Параметры

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

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

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

• Функция, которая нуждается в данных.
• Функция из другого потгока.
• Функция выполняется асинхронно, и драйвер не поддерживает асинхронное выполнение.

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

4.12.4 SQLDisconnect

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

4.12.4.1 Синтаксис

SQLRETURN SQLDisconnect(SQLHDBC ConnectionHandle);

4.12.4.2 Параметры

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

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

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

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

4.12.5 SQLFreeHandle

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

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

4.12.5.1 Синтаксис

SQLRETURN SQLFreeHandle(SQLSMALLINT HandleType, SQLHANDLE Handle);

4.12.5.2 Параметры

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

• 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 автоматически уничтожает любые инструкции и дескрипторы, открытые на подключении.

4.12.6 SQLFreeConnect

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

4.12.7 SQLFreeEnv

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

Партнёры:

Хостинг: