Функция SQLParamData
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLParamData используется вместе с SQLPutData для предоставления данных параметров во время выполнения инструкции и с sqlGetData для получения потоковой выходных данных параметров.
Синтаксис
SQLRETURN SQLParamData(
SQLHSTMT StatementHandle,
SQLPOINTER * ValuePtrPtr);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
ValuePtrPtr
[Выходные данные] Указатель на буфер, в котором возвращается адрес буфера ParameterValuePtr, указанного в SQLBindParameter (для данных параметров) или адрес буфера TargetValuePtr, указанного в SQLBindCol (для данных столбцов), как указано в поле записи дескриптора SQL_DESC_DATA_PTR.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA SQL_STILL_EXECUTING, SQL_ERROR, SQL_INVALID_HANDLE или SQL_PARAM_DATA_AVAILABLE.
Диагностика
Когда SQLParamData возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLParamData и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07006 | Нарушение атрибута ограниченного типа данных | Значение данных, определяемое аргументом ValueType в SQLBindParameter для связанного параметра, не может быть преобразовано в тип данных, определенный аргументом ParameterType в SQLBindParameter. Значение данных, возвращаемое для параметра, привязанного к SQL_PARAM_INPUT_OUTPUT или SQL_PARAM_OUTPUT, не может быть преобразовано в тип данных, определенный аргументом ValueType в SQLBindParameter. (Если значения данных для одной или нескольких строк не удалось преобразовать, но одна или несколько строк были успешно возвращены, эта функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 22026 | Строковые данные, несовпадение длины | Тип сведений SQL_NEED_LONG_DATA_LEN в SQLGetInfo был "Y", и меньше данных было отправлено для длинного параметра (тип данных был SQL_LONGVARCHAR, SQL_LONGVARBINARY или длинный тип данных для конкретного источника данных), чем был указан с аргументом StrLen_or_IndPtr в SQLBindParameter. Тип сведений SQL_NEED_LONG_DATA_LEN в SQLGetInfo был "Y", и меньше данных было отправлено для длинного столбца (тип данных был SQL_LONGVARCHAR, SQL_LONGVARBINARY или длинный тип данных для конкретного источника данных), чем был указан в буфере длины, соответствующего столбцу в строке данных, которые были добавлены или обновлены с помощью SQLBulkOperations или обновлены с помощью SQLSetPos. |
| 40001 | Сбой сериализации | Транзакция была откатена из-за взаимоблокировки ресурсов с другой транзакцией. |
| 40003 | Неизвестное завершение инструкции | Связанное соединение завершилось сбоем во время выполнения этой функции, и состояние транзакции невозможно определить. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана в ОператорHandle. Затем функция была вызвана на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Предыдущий вызов функции не был вызовом SQLExecDirect, SQLExecute, SQLBulkOperations или SQLSetPos, где код возврата был SQL_NEED_DATA, или предыдущий вызов функции был вызовом SQLPutData. Предыдущий вызов функции был вызовом SQLParamData. (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLParamData . (DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. SQLCancel был вызван до отправки данных для всех параметров или столбцов во время выполнения. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, соответствующий ОператорHandle , не поддерживает функцию. |
| IM017 | Опрос отключен в асинхронном режиме уведомлений | При использовании модели уведомлений опрос отключается. |
| IM018 | SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. | Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Если SQLParamData вызывается при отправке данных для параметра в инструкции SQL, он может возвращать любой SQLSTATE, который может быть возвращен функцией, вызываемой для выполнения инструкции (SQLExecute или SQLExecDirect). Если он вызывается при отправке данных для столбца, обновляемого или добавляемого с помощью SQLBulkOperations или обновляемого с помощью SQLSetPos, он может возвращать любой SQLSTATE, который может быть возвращен SQLBulkOperations или SQLSetPos.
Комментарии
SQLParamData можно вызвать для предоставления данных во время выполнения данных для двух используемых: данных параметров, которые будут использоваться в вызове SQLExecute или SQLExecDirect, или данных столбцов, которые будут использоваться при обновлении строки или добавлении вызова SQLBulkOperations или обновления вызовом SQLSetPos. Во время выполнения SQLParamData возвращается в приложение индикатором того, какие данные требует драйвер.
Когда приложение вызывает SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos, драйвер возвращает SQL_NEED_DATA, если он нуждается в данных при выполнении. Затем приложение вызывает SQLParamData , чтобы определить, какие данные нужно отправлять. Если драйверу требуются данные параметров, драйвер возвращает в выходном буфере *ValuePtrPtr значение, которое приложение помещает в буфер набора строк. Приложение может использовать это значение для определения данных параметров, запрашивающих драйвер. Если драйверу требуются данные столбца, драйвер возвращает в буфере *ValuePtrPtr адрес, к которому изначально привязан столбец, как показано ниже.
Смещение привязки привязанных адресов + + ((номер строки — 1) x размер элемента)
где переменные определены, как указано в следующей таблице.
| «Переменная» | Description |
|---|---|
| Привязанный адрес | Адрес, указанный с аргументом TargetValuePtr в SQLBindCol. |
| Смещение привязки | Значение, хранящееся по адресу, указанному атрибутом инструкции SQL_ATTR_ROW_BIND_OFFSET_PTR. |
| Номер строки | 1-е число строки в наборе строк. Для однострочных выборок, которые являются значениями по умолчанию, это значение равно 1. |
| Размер элемента | Значение атрибута оператора SQL_ATTR_ROW_BIND_TYPE для буферов данных и длины или индикатора. |
Он также возвращает SQL_NEED_DATA, который является индикатором для приложения, которое должно вызывать SQLPutData для отправки данных.
Приложение вызывает SQLPutData столько раз, сколько необходимо для отправки данных во время выполнения для столбца или параметра. После отправки всех данных для столбца или параметра приложение снова вызывает SQLParamData . Если SQLParamData снова возвращает SQL_NEED_DATA, данные должны отправляться для другого параметра или столбца. Поэтому приложение снова вызывает SQLPutData. Если все данные выполнения отправляются для всех параметров или столбцов, SQLParamData возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, значение в *ValuePtrPtrPtr не определено, и можно выполнить инструкцию SQL Или вызов SQLBulkOperations или SQLSetPos .
Если SQLParamData предоставляет данные параметров для инструкции поиска или удаления, которая не влияет на строки в источнике данных, вызов SQLParamData возвращает SQL_NO_DATA.
Дополнительные сведения о передаче данных параметра во время выполнения инструкции см. в разделе "Передача значений параметров" в SQLBindParameter и отправке длинных данных. Дополнительные сведения о том, как данные столбца при выполнении обновляются или добавляются, см. в разделе "Использование SQLSetPos" в SQLSetPos, "Выполнение массовых обновлений с помощью закладок" в SQLBulkOperations, а также long Data и SQLSetPos и SQLBulkOperations.
SQLParamData можно вызвать для получения потоковых выходных параметров. Когда SQLMoreResults, SQLExecute, SQLGetData или SQLExecDirect возвращает SQL_PARAM_DATA_AVAILABLE, вызовите SQLParamData, чтобы определить, какой параметр имеет доступное значение. Дополнительные сведения о SQL_PARAM_DATA_AVAILABLE и потоковых выходных параметрах см. в разделе "Получение выходных параметров с помощью SQLGetData".
Пример кода
См. раздел SQLPutData.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Привязка буфера к параметру | Функция SQLBindParameter |
| Отмена обработки инструкций | Функция SQLCancel |
| Возврат сведений о параметре в инструкции | Функция SQLDescribeParam |
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Отправка данных параметров во время выполнения | Функция SQLPutData |
См. также
Справочник по API ODBC
Файлы заголовков ODBC
Получение выходных параметров с помощью метода SQLGetData