Функции в 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] атрибут для установки.

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.

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: ниже приведен полный список диагностических идентификаторов, поддержанных драйвером.