Функция SQLBindParameter
Соответствие
Представлена версия: соответствие стандартам ODBC 2.0: ODBC
Сводка
SQLBindParameter привязывает буфер к маркеру параметра в инструкции SQL. SQLBindParameter поддерживает привязку к типу данных ЮникодА C, даже если базовый драйвер не поддерживает данные Юникода.
Примечание.
Эта функция заменяет функцию ODBC 1.0 SQLSetParam. Дополнительные сведения см. в разделе "Комментарии".
Синтаксис
SQLRETURN SQLBindParameter(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT InputOutputType,
SQLSMALLINT ValueType,
SQLSMALLINT ParameterType,
SQLULEN ColumnSize,
SQLSMALLINT DecimalDigits,
SQLPOINTER ParameterValuePtr,
SQLLEN BufferLength,
SQLLEN * StrLen_or_IndPtr);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
ПараметрNumber
[Входные данные] Число параметров, упорядоченное последовательно в увеличении порядка параметров, начиная с 1.
InputOutputType
[Входные данные] Тип параметра. Дополнительные сведения см. в разделе "Аргумент InputOutputType " в разделе "Комментарии".
ValueType
[Входные данные] Тип данных C параметра. Дополнительные сведения см. в разделе "Аргумент ValueType " в разделе "Комментарии".
ParameterType
[Входные данные] Тип данных SQL параметра. Дополнительные сведения см. в разделе "Аргумент ParameterType " в разделе "Комментарии".
ColumnSize
[Входные данные] Размер столбца или выражения соответствующего маркера параметра. Дополнительные сведения см. в разделе "Аргумент ColumnSize " в разделе "Комментарии".
Если приложение будет работать в 64-разрядной операционной системе Windows, ознакомьтесь с 64-разрядной информацией ODBC.
DecimalDigits
[Входные данные] Десятичные цифры столбца или выражения соответствующего маркера параметра. Дополнительные сведения о размере столбца см. в разделе "Размер столбца", "Десятичные цифры", " Длина октета" и "Размер отображения".
ParameterValuePtr
[Отложенные входные данные] Указатель на буфер для данных параметра. Дополнительные сведения см. в разделе "Аргумент ParameterValuePtr " в разделе "Комментарии".
BufferLength
[входные и выходные данные] Длина буфера ParameterValuePtr в байтах. Дополнительные сведения см. в разделе "Аргумент BufferLength " в разделе "Комментарии".
См. сведения о 64-разрядной версии ODBC, если приложение будет работать в 64-разрядной операционной системе.
StrLen_or_IndPtr
[Отложенные входные данные] Указатель на буфер для длины параметра. Дополнительные сведения см. в разделе "Аргумент StrLen_or_IndPtr " в разделе "Комментарии".
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLBindParameter возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLBindParameter и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07006 | Нарушение атрибута ограниченного типа данных | Тип данных, определяемый аргументом ValueType , не может быть преобразован в тип данных, определенный аргументом ParameterType . Обратите внимание, что эта ошибка может быть возвращена SQLExecDirect, SQLExecute или SQLPutData во время выполнения вместо SQLBindParameter. |
| 07009 | Недопустимый индекс дескриптора | (DM) Значение, указанное для аргумента ParameterNumber , было меньше 1. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY003 | Недопустимый тип буфера приложения | Значение, указанное аргументом ValueType , не является допустимым типом данных C или SQL_C_DEFAULT. |
| HY004 | Недопустимый тип данных SQL | Значение, указанное для аргумента ParameterType , не было допустимым идентификатором типа данных ODBC SQL, а также идентификатором типа данных SQL, определенным драйвером. |
| HY009 | Недопустимое значение аргумента | (DM) Аргумент ParameterValuePtr был пустым указателем, аргумент StrLen_or_IndPtr был пустым указателем, а аргумент InputOutputType не был SQL_PARAM_OUTPUT. (DM) SQL_PARAM_OUTPUT, где аргумент ParameterValuePtr был пустым указателем, тип C был char или binary, и BufferLength (cbValueMax) было больше 0. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове SQLBindParameter . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY021 | Несогласованные сведения о дескрипторе | Сведения дескриптора, проверяемые во время проверки согласованности, не согласованы. (См. раздел "Проверки согласованности" в разделеSQLSetDescField.) Значение, указанное для аргумента DecimalDigits , находится вне диапазона значений, поддерживаемых источником данных для столбца типа данных SQL, указанного аргументом ParameterType . |
| HY090 | Недопустимая длина строки или буфера | (DM) Значение в BufferLength было меньше 0. (См. описание поля SQL_DESC_DATA_PTR в SQLSetDescField.) |
| HY104 | Недопустимое значение точности или масштабирования | Значение, указанное для аргумента ColumnSize или DecimalDigits , находится вне диапазона значений, поддерживаемых источником данных для столбца типа данных SQL, указанного аргументом ParameterType . |
| HY105 | Недопустимый тип параметра | (DM) Значение, указанное для аргумента InputOutputType , было недопустимым. (См. комментарии.) |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYC00 | Необязательный компонент не реализован | Драйвер или источник данных не поддерживает преобразование, указанное в сочетании значения, указанного для аргумента ValueType, и значения, указанного для аргумента ParameterType. Значение, указанное для аргумента ParameterType , было допустимым идентификатором типа данных ODBC SQL для версии ODBC, поддерживаемой драйвером или источником данных. Драйвер поддерживает только ODBC 2.x и аргумент ValueType были одним из следующих: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT и все типы данных C, перечисленные в типах данных C в приложении D: Типы данных. Драйвер поддерживает только версии ODBC до 3.50, а аргумент ValueType был SQL_C_GUID. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
Комментарии
Приложение вызывает SQLBindParameter для привязки каждого маркера параметра в инструкции SQL. Привязки остаются в силе, пока приложение не вызовет SQLBindParameter еще раз, вызывает SQLFreeStmt с параметром SQL_RESET_PARAMS или вызывает SQLSetDescField , чтобы задать поле заголовка SQL_DESC_COUNT APD равным 0.
Дополнительные сведения о параметрах см. в разделе "Параметры инструкции". Дополнительные сведения о типах данных параметров и маркерах параметров см. в разделе "Типы данных параметров" и "Маркеры параметров" в приложении C: грамматика SQL.
Аргумент ParameterNumber
Если параметрNumber в вызове SQLBindParameter больше значения SQL_DESC_COUNT, вызывается SQLSetDescField , чтобы увеличить значение SQL_DESC_COUNT до ParameterNumber.
Аргумент InputOutputType
Аргумент InputOutputType указывает тип параметра. Этот аргумент задает поле SQL_DESC_PARAMETER_TYPE IPD. Все параметры в инструкциях SQL, которые не вызывают процедуры, такие как инструкции INSERT , являются входными параметрами. Параметры в вызовах процедур могут быть входным, входным и выходным или выходными параметрами. (Вызовы приложенияSQLProcedureColumns для определения типа параметра в вызове процедуры; параметры, тип которых не может быть определен, предполагается, что это входные параметры.)
Аргумент InputOutputType может иметь одно из следующих значений:
SQL_PARAM_INPUT. Параметр помечает параметр в инструкции SQL, которая не вызывает процедуру, например инструкцию INSERT , или помечает входной параметр в процедуре. Например, параметры в INSERT INTO Employee VALUES (?, ?, ?) являются входными параметрами, в то время как параметры в {call AddEmp(?, ?, ?)} могут быть, но не обязательно являются входными параметрами.
При выполнении инструкции драйвер отправляет данные для параметра в источник данных; Буфер *ParameterValuePtr должен содержать допустимое входное значение, или буфер *StrLen_or_IndPtr должен содержать SQL_NULL_DATA, SQL_DATA_AT_EXEC или результат макроса SQL_LEN_DATA_AT_EXEC.
Если приложение не может определить тип параметра в вызове процедуры, он задает inputOutputType значение SQL_PARAM_INPUT; если источник данных возвращает значение параметра, драйвер удаляет его.
SQL_PARAM_INPUT_OUTPUT. Параметр помечает входной и выходной параметр в процедуре. Например, параметр в {call GetEmpDept(?)} является параметром ввода и вывода, который принимает имя сотрудника и возвращает имя отдела сотрудника.
При выполнении инструкции драйвер отправляет данные для параметра в источник данных; Буфер *ParameterValuePtr должен содержать допустимое входное значение, или буфер *StrLen_or_IndPtr должен содержать SQL_NULL_DATA, SQL_DATA_AT_EXEC или результат макроса SQL_LEN_DATA_AT_EXEC. После выполнения инструкции драйвер возвращает данные для параметра приложению; Если источник данных не возвращает значение для входного и выходного параметра, драйвер задает буфер *StrLen_or_IndPtr значение SQL_NULL_DATA.
Примечание.
Когда приложение ODBC 1.0 вызывает SQLSetParam в драйвере ODBC 2.0, диспетчер драйверов преобразует это в вызов SQLBindParameter , в котором аргумент InputOutputType имеет значение SQL_PARAM_INPUT_OUTPUT.
SQL_PARAM_OUTPUT. Параметр помечает возвращаемое значение процедуры или выходного параметра в процедуре; В любом случае они называются выходными параметрами. Например, параметр в {?=call GetNextEmpID} является выходным параметром, который возвращает следующий идентификатор сотрудника.
После выполнения инструкции драйвер возвращает данные для параметра в приложение, если только аргументы ParameterValuePtr и StrLen_or_IndPtr не являются пустыми указателями, в этом случае драйвер удаляет выходное значение. Если источник данных не возвращает значение для выходного параметра, драйвер задает буфер *StrLen_or_IndPtr значение SQL_NULL_DATA.
SQL_PARAM_INPUT_OUTPUT_STREAM. Указывает, что входной и выходной параметр должен быть потоковым. SQLGetData может считывать значения параметров в частях. BufferLength игнорируется, так как длина буфера будет определена при вызове SQLGetData. Значение буфера StrLen_or_IndPtr должно содержать SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC или результат макроса SQL_LEN_DATA_AT_EXEC. Параметр должен быть привязан как параметр daE для данных при входных данных, если он будет передаваться в выходные данные. ПараметрValuePtr может быть любым значением указателя, не допускающим null, которое будет возвращено SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с параметром ParameterValuePtr для входных и выходных данных. Дополнительные сведения см. в разделе Получение выходных параметров с помощью метода SQLGetData.
SQL_PARAM_OUTPUT_STREAM. То же, что и SQL_PARAM_INPUT_OUTPUT_STREAM, для выходного параметра. * StrLen_or_IndPtr игнорируется при входных данных.
В следующей таблице перечислены различные сочетания InputOutputType и *StrLen_or_IndPtr:
| InputOutputType | *StrLen_or_IndPtr | Результат | Примечание к ParameterValuePtr |
|---|---|---|---|
| SQL_PARAM_INPUT | SQL_LEN_DATA_AT_EXEC(len) или SQL_DATA_AT_EXEC | Входные данные в частях | ПараметрValuePtr может быть любым значением указателя, возвращаемым SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с параметром ParameterValuePtr. |
| SQL_PARAM_INPUT | Не SQL_LEN_DATA_AT_EXEC(len) или SQL_DATA_AT_EXEC | Входной буфер с привязкой | ParameterValuePtr — это адрес входного буфера. |
| SQL_PARAM_OUTPUT | Игнорируется при входных данных. | Буфер с привязкой вывода | ParameterValuePtr — это адрес выходного буфера. |
| SQL_PARAM_OUTPUT_STREAM | Игнорируется при входных данных. | Потоковые выходные данные | ПараметрValuePtr может быть любым значением указателя, которое будет возвращено SQLParamData в качестве определяемого пользователем токена, значение которого было передано с параметром ParameterValuePtr. |
| SQL_PARAM_INPUT_OUTPUT | SQL_LEN_DATA_AT_EXEC(len) или SQL_DATA_AT_EXEC | Входные данные в частях и буфере с привязкой выходных данных | ParameterValuePtr — это адрес выходного буфера, который также будет возвращен SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с параметром ParameterValuePtr. |
| SQL_PARAM_INPUT_OUTPUT | Не SQL_LEN_DATA_AT_EXEC(len) или SQL_DATA_AT_EXEC | Входной буфер и выходной привязанный буфер | ParameterValuePtr — это адрес общего буфера ввода и вывода. |
| SQL_PARAM_INPUT_OUTPUT_STREAM | SQL_LEN_DATA_AT_EXEC(len) или SQL_DATA_AT_EXEC | Входные данные в частях и потоковые выходные данные | ПараметрValuePtr может быть любым значением указателя, не допускающего значение NULL, которое будет возвращено SQLParamData в качестве определяемого пользователем маркера, значение которого было передано с параметром ParameterValuePtr для входных и выходных данных. |
Примечание.
Драйвер должен решить, какие типы SQL разрешены, когда приложение привязывает выходной или входной выходной параметр в виде потоковой передачи. Диспетчер драйверов не создаст ошибку для недопустимого типа SQL.
Аргумент ValueType
Аргумент ValueType указывает тип данных C параметра. Этот аргумент задает поля SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE APD. Это должно быть одно из значений в разделе типов данных C в приложении D: Типы данных.
Если аргумент ValueType является одним из типов данных интервала, SQL_DESC_TYPE поле записи ParameterNumber для APD имеет значение SQL_INTERVAL, SQL_DESC_CONCISE_TYPE поле APD задано для краткого типа данных интервала, а поле SQL_DESC_DATETIME_INTERVAL_CODE записи ParameterNumber имеет подкод для конкретного типа данных интервала. (См. раздел Приложение D. Типы данных.) Для данных используются значения интервала по умолчанию с начальной точностью (2) и интервалом по умолчанию (6), как указано в полях SQL_DESC_DATETIME_INTERVAL_PRECISION и SQL_DESC_PRECISION APD соответственно. Если точность по умолчанию не подходит, приложение должно явно задать поле дескриптора вызовом SQLSetDescField или SQLSetDescRec.
Если аргумент ValueType является одним из типов данных datetime, SQL_DESC_TYPE поле записи ParameterNumber для APD имеет значение SQL_DATETIME, поле SQL_DESC_CONCISE_TYPE записи ПараметраNumber для типа данных APD имеет краткий тип данных datetime C, а поле SQL_DESC_DATETIME_INTERVAL_CODE записи ParameterNumber задано в подкод для конкретного типа данных datetime. (См. раздел Приложение D. Типы данных.)
Если аргумент ValueType является типом данных SQL_C_NUMERIC, точность по умолчанию (определяемая драйвером) и масштаб по умолчанию (0), заданный в SQL_DESC_PRECISION и SQL_DESC_SCALE полях APD, используются для данных. Если точность или масштабирование по умолчанию не подходит, приложение должно явно задать поле дескриптора вызовом SQLSetDescField или SQLSetDescRec.
SQL_C_DEFAULT указывает, что значение параметра передается из типа данных C по умолчанию для типа данных SQL, указанного с параметром ParameterType.
Можно также указать расширенный тип данных C. Дополнительные сведения о типах данных см. в разделе Типы данных C в ODBC.
Дополнительные сведения см. в разделе "Типы данных C" по умолчанию, преобразование данных из C в типы данных SQL и преобразование данных из SQL в типы данных C в приложении D: Типы данных.
Аргумент ParameterType
Это должно быть одно из значений, перечисленных в разделе "Типы данных SQL" в приложении D: Типы данных, или это должно быть значением для конкретного драйвера. Этот аргумент задает поля SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE и SQL_DESC_DATETIME_INTERVAL_CODE IPD.
Если аргумент ParameterType является одним из идентификаторов даты и времени, то для поля SQL_DESC_TYPE IPD задано значение SQL_DATETIME, поле SQL_DESC_CONCISE_TYPE IPD задано в качестве краткого типа данных datetime SQL, а поле SQL_DESC_DATETIME_INTERVAL_CODE задано в соответствующее значение подкода datetime.
Если ПараметрТип является одним из идентификаторов интервала, то для поля SQL_DESC_TYPE IPD задано значение SQL_INTERVAL, поле SQL_DESC_CONCISE_TYPE IPD имеет краткий тип данных интервала SQL, а для поля SQL_DESC_DATETIME_INTERVAL_CODE IPD задан соответствующий подкод интервала. Поле SQL_DESC_DATETIME_INTERVAL_PRECISION IPD имеет значение интервала в качестве начальной точности, а поле SQL_DESC_PRECISION задано для точности интервала в секундах, если применимо. Если значение по умолчанию SQL_DESC_DATETIME_INTERVAL_PRECISION или SQL_DESC_PRECISION не подходит, приложение должно явно задать его путем вызова SQLSetDescField. Дополнительные сведения о любом из этих полей см. в разделе SQLSetDescField.
Если аргумент ValueType является типом данных SQL_NUMERIC, точность по умолчанию (определяемая драйвером) и масштаб по умолчанию (0), заданный в SQL_DESC_PRECISION и SQL_DESC_SCALE полях IPD, используются для данных. Если точность или масштабирование по умолчанию не подходит, приложение должно явно задать поле дескриптора вызовом SQLSetDescField или SQLSetDescRec.
Сведения о преобразовании данных см. в разделе "Преобразование данных из C в типы данных SQL" и преобразование данных из SQL в типы данных C в приложении D: Типы данных.
Аргумент ColumnSize
Аргумент ColumnSize указывает размер столбца или выражения, соответствующего маркеру параметра, длине этих данных или обоим. Этот аргумент задает различные поля IPD в зависимости от типа данных SQL ( аргумент ParameterType ). К этому сопоставлению применяются следующие правила:
Если параметрType имеет значение SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY или один из кратких типов данных даты и интервала SQL, SQL_DESC_LENGTH поле IPD имеет значение ColumnSize. (Дополнительные сведения см. в разделе Размер столбца, десятичные цифры, длина октета и раздел "Размер отображения" в приложении D: Типы данных.)
Если параметрType SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL или SQL_DOUBLE, то для поля SQL_DESC_PRECISION IPD задано значение ColumnSize.
Для других типов данных аргумент ColumnSize игнорируется.
Дополнительные сведения см. в разделе "Передача значений параметров" и SQL_DATA_AT_EXEC в разделе "Аргумент StrLen_or_IndPtr ".
Аргумент DecimalDigits
Если ПараметрТип SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND или SQL_INTERVAL_MINUTE_TO_SECOND, поле SQL_DESC_PRECISION IPD имеет значение DecimalDigits. Если параметрType SQL_NUMERIC или SQL_DECIMAL, поле SQL_DESC_SCALE IPD имеет значение DecimalDigits. Для всех других типов данных аргумент DecimalDigits игнорируется.
Аргумент ParameterValuePtr
Аргумент ParameterValuePtr указывает на буфер, который при вызове SQLExecute или SQLExecDirect содержит фактические данные для параметра. Данные должны находиться в форме, указанной аргументом ValueType . Этот аргумент задает поле SQL_DESC_DATA_PTR APD. Приложение может задать для аргумента ParameterValuePtr значение NULL, если *StrLen_or_IndPtr SQL_NULL_DATA или SQL_DATA_AT_EXEC. (Это относится только к входным или входным или выходным параметрам.)
Если *StrLen_or_IndPtr является результатом макроса SQL_LEN_DATA_AT_EXEC(длина) или SQL_DATA_AT_EXEC, параметрValuePtr — это определяемое приложением значение указателя, связанное с параметром. Он возвращается приложению через SQLParamData. Например, ParameterValuePtr может быть ненулевым маркером, таким как номер параметра, указатель на данные или указатель на структуру, используемую приложением для привязки входных параметров. Однако обратите внимание, что если параметр является входным и выходным параметром, ПараметрValuePtr должен быть указателем на буфер, в котором будет храниться выходное значение. Если значение атрибута инструкции SQL_ATTR_PARAMSET_SIZE больше 1, приложение может использовать значение, указываемое атрибутом оператора SQL_ATTR_PARAMS_PROCESSED_PTR вместе с аргументом ParameterValuePtr . Например, ParameterValuePtr может указывать на массив значений, и приложение может использовать значение, на которое указывает SQL_ATTR_PARAMS_PROCESSED_PTR для получения правильного значения из массива. Дополнительные сведения см. в разделе "Передача значений параметров" далее в этом разделе.
Если аргумент InputOutputType SQL_PARAM_INPUT_OUTPUT или SQL_PARAM_OUTPUT, ПараметрValuePtr указывает на буфер, в котором драйвер возвращает выходное значение. Если процедура возвращает один или несколько результирующих наборов, буфер *ParameterValuePtr не гарантируется, пока не будут обработаны все результирующие наборы или счетчики строк. Если буфер не задан до завершения обработки, выходные параметры и возвращаемые значения недоступны, пока SQLMoreResults не возвращает SQL_NO_DATA. Вызов SQLCloseCursor или SQLFreeStmt с параметром SQL_CLOSE приведет к отмене этих значений.
Если значение атрибута инструкции SQL_ATTR_PARAMSET_SIZE больше 1, ПараметрValuePtr указывает на массив. Одна инструкция SQL обрабатывает полный массив входных значений для входного или выходного параметра и возвращает массив выходных значений для входного или выходного параметра.
Аргумент BufferLength
Для данных символа и двоичного кода C аргумент BufferLength указывает длину буфера *ParameterValuePtr (если это один элемент) или длину элемента в массиве *ParameterValuePtr (если значение в атрибуте оператора SQL_ATTR_PARAMSET_SIZE больше 1). Этот аргумент задает поле записи SQL_DESC_OCTET_LENGTH APD. Если приложение задает несколько значений, bufferLength используется для определения расположения значений в массиве *ParameterValuePtr , как входных, так и выходных данных. Для входных и выходных параметров используется для определения того, следует ли усечь символ и двоичные данные C для выходных данных:
Для символьных данных C, если число байтов, доступных для возврата, больше или равно BufferLength, данные в *ParameterValuePtr усечены в BufferLength меньше длины символа завершения null и прерваны драйвером.
Для двоичных данных C, если число возвращаемых байтов больше, чем BufferLength, данные в *ParameterValuePtr усечены до байтов BufferLength.
Для всех других типов данных C аргумент BufferLength игнорируется. Длина буфера *ParameterValuePtr (если это один элемент) или длина элемента в массиве *ParameterValuePtr (если приложение вызывает SQLSetStmtAttr с аргументом атрибута SQL_ATTR_PARAMSET_SIZE указывать несколько значений для каждого параметра), предполагается, что длина типа данных C.
Для потоковых выходных или потоковых входных и выходных параметров аргумент BufferLength игнорируется, так как длина буфера указана в SQLGetData.
Примечание.
Когда приложение ODBC 1.0 вызывает SQLSetParam в ODBC 3.X Driver Manager преобразует это в вызов SQLBindParameter , в котором аргумент BufferLength всегда SQL_SETPARAM_VALUE_MAX. Так как диспетчер драйверов возвращает ошибку, если ODBC 3.Приложение x задает значение BufferLength для SQL_SETPARAM_VALUE_MAX, ODBC 3.Драйвер x может использовать это для определения того, когда он вызывается приложением ODBC 1.0.
Примечание.
В SQLSetParam способ, в котором приложение указывает длину буфера *ParameterValuePtr , чтобы драйвер может возвращать символьные или двоичные данные, а также способ, в котором приложение отправляет массив значений символов или двоичных параметров драйверу, определяется драйвером.
аргумент StrLen_or_IndPtr
Аргумент StrLen_or_IndPtr указывает на буфер, который, когда вызывается SQLExecute или SQLExecDirect , содержит одно из следующих элементов. (Этот аргумент задает поля SQL_DESC_OCTET_LENGTH_PTR и записи SQL_DESC_INDICATOR_PTR указателей параметров приложения.)
Длина значения параметра, хранящегося в *ParameterValuePtr. Это игнорируется, за исключением символьных или двоичных данных C.
SQL_NTS. Значение параметра — это строка, завершающаяся значением NULL.
SQL_NULL_DATA. Значение параметра равно NULL.
SQL_DEFAULT_PARAM. Процедура — использовать значение по умолчанию параметра, а не значение, полученное из приложения. Это значение допустимо только в процедуре, вызываемой в каноническом синтаксисе ODBC, а затем только в том случае, если аргумент InputOutputType имеет значение SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT или SQL_PARAM_INPUT_OUTPUT_STREAM. Если *StrLen_or_IndPtr SQL_DEFAULT_PARAM, аргументы ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength и ParameterValuePtr игнорируются для входных параметров и используются только для определения значения выходного параметра входных и выходных параметров.
Результат макроса SQL_LEN_DATA_AT_EXEC(длина). Данные для параметра будут отправлены с помощью SQLPutData. Если аргумент ParameterType равен SQL_LONGVARBINARY, SQL_LONGVARCHAR или длинному типу данных для конкретного источника данных, а драйвер возвращает значение "Y" для типа сведений SQL_NEED_LONG_DATA_LEN в SQLGetInfo, длина — это количество байтов данных, отправляемых для параметра; в противном случае длина должна быть ненегрегативной и игнорируется. Дополнительные сведения см. в разделе "Передача значений параметров" далее в этом разделе.
Например, чтобы указать, что 10 000 байт данных будут отправляться с помощью SQLPutData в одном или нескольких вызовах для параметра SQL_LONGVARCHAR, приложение задает *StrLen_or_IndPtr значение SQL_LEN_DATA_AT_EXEC(10000).
SQL_DATA_AT_EXEC. Данные для параметра будут отправлены с помощью SQLPutData. Это значение используется приложениями ODBC 1.0 при вызове ODBC 3.драйверы x . Дополнительные сведения см. в разделе "Передача значений параметров" далее в этом разделе.
Если StrLen_or_IndPtr является указателем NULL, драйвер предполагает, что все входные значения параметров являются не NULL, а двоичные данные символа и двоичные данные завершаются null. Если InputOutputType SQL_PARAM_OUTPUT или SQL_PARAM_OUTPUT_STREAM и ParameterValuePtr и StrLen_or_IndPtr являются указателями NULL, драйвер удаляет выходное значение.
Примечание.
Разработчикам приложений настоятельно не рекомендуется указывать указатель null для StrLen_or_IndPtr , если тип данных параметра SQL_C_BINARY. Чтобы убедиться, что драйвер не неожиданно усечен SQL_C_BINARY данных, StrLen_or_IndPtr должен содержать указатель на допустимое значение длины.
Если аргумент InputOutputType SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM или SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr указывает на буфер, в котором драйвер возвращает SQL_NULL_DATA, число байтов, доступное для возврата в *ParameterValuePtr (за исключением байтов символьного завершения null), или SQL_NO_TOTAL (если число байтов, доступных для возврата, невозможно определить). Если процедура возвращает один или несколько результирующих наборов, буфер *StrLen_or_IndPtr не гарантируется, пока не будут возвращены все результаты.
Если значение в атрибуте инструкции SQL_ATTR_PARAMSET_SIZE больше 1, StrLen_or_IndPtr указывает на массив значений SQLLEN. Они могут быть любым из значений, перечисленных ранее в этом разделе, и обрабатываются с помощью одной инструкции SQL.
Передача значений параметров
Приложение может передать значение параметра в буфере *ParameterValuePtr или с одним или несколькими вызовами SQLPutData. Параметры, данные которых передаются с помощью SQLPutData , называются параметрами данных при выполнении . Обычно они используются для отправки данных для SQL_LONGVARBINARY и SQL_LONGVARCHAR параметров и могут быть смешанными с другими параметрами.
Чтобы передать значения параметров, приложение выполняет следующую последовательность шагов:
Вызывает SQLBindParameter для каждого параметра, чтобы привязать буферы для значения параметра (аргумент ParameterValuePtr ) и длины или индикатора (StrLen_or_IndPtr аргумента). Для параметров выполнения параметр ParameterValuePtr — это определяемое приложением значение указателя, например номер параметра или указатель на данные. Значение будет возвращено позже и может использоваться для идентификации параметра.
Помещает значения для входных и выходных параметров в буферы *ParameterValuePtr и *StrLen_or_IndPtr :
Для обычных параметров приложение помещает значение параметра в буфер *ParameterValuePtr и длину этого значения в буфере *StrLen_or_IndPtr . Дополнительные сведения см. в разделе "Настройка значений параметров".
Для параметров выполнения приложение помещает результат макроса SQL_LEN_DATA_AT_EXEC(длины) (при вызове драйвера ODBC 2.0) в буфер *StrLen_or_IndPtr .
Вызывает SQLExecute или SQLExecDirect для выполнения инструкции SQL.
Если нет параметров выполнения данных, процесс завершается.
Если есть какие-либо параметры выполнения данных, функция возвращает SQL_NEED_DATA.
Вызывает SQLParamData, чтобы получить определяемое приложением значение, указанное в аргументе ParameterValuePtr SQLBindParameter для первого параметра обработки данных при выполнении. SQLParamData возвращает SQL_NEED_DATA.
Примечание.
Хотя параметры во время выполнения похожи на столбцы данных во время выполнения, значение, возвращаемое SQLParamData , отличается для каждого. Параметры выполнения данных — это параметры в инструкции SQL, для которой данные будут отправляться с SQLPutData при выполнении инструкции с помощью SQLExecDirect или SQLExecute. Они привязаны к SQLBindParameter. Значение, возвращаемое SQLParamData, является значением указателя, передаваемым в SQLBindParameter в аргументе ParameterValuePtr. Столбцы данных во время выполнения — это столбцы в наборе строк, для которого данные будут отправляться с ПОМОЩЬЮ SQLPutData при обновлении или добавлении строки с помощью SQLBulkOperations или обновлении с помощью SQLSetPos. Они привязаны к SQLBindCol. Значение, возвращаемое SQLParamData , — это адрес строки в буфере *TargetValuePtr (заданный вызовом SQLBindCol), который обрабатывается.
Вызывает SQLPutData один или несколько раз для отправки данных для параметра. Требуется несколько вызовов, если значение данных больше буфера *ParameterValuePtr , указанного в SQLPutData; несколько вызовов SQLPutData для одного и того же параметра разрешены только при отправке символьных данных C в столбец с символом, двоичным или конкретным типом данных источника данных или при отправке двоичных данных C в столбец с символом, двоичный или конкретный тип данных источника данных.
Вызывает SQLParamData еще раз, чтобы сообщить о том, что все данные отправлены для параметра.
При наличии дополнительных параметров выполнения SQLParamData возвращает SQL_NEED_DATA и определяемое приложением значение для следующего параметра обработки данных при выполнении. Приложение повторяет шаги 4 и 5.
Если нет дополнительных параметров выполнения данных, процесс завершается. Если инструкция была успешно выполнена, SQLParamData возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO; если выполнение завершилось сбоем, возвращается SQL_ERROR. На этом этапе SQLParamData может возвращать любой SQLSTATE, который можно вернуть функцией, которая используется для выполнения инструкции (SQLExecDirect или SQLExecute).
Выходные значения для любых входных и выходных параметров доступны в буферах *ParameterValuePtr и *StrLen_or_IndPtr после получения всех результирующих наборов, созданных инструкцией.
Вызов SQLExecute или SQLExecDirect помещает инструкцию в состояние SQL_NEED_DATA. На этом этапе приложение может вызывать только SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData или SQLPutData с инструкцией или дескриптором подключения, связанным с инструкцией. Если он вызывает любую другую функцию с инструкцией или соединением, связанной с инструкцией, функция возвращает SQLSTATE HY010 (ошибка последовательности функций). Инструкция оставляет состояние SQL_NEED_DATA, когда SQLParamData или SQLPutData возвращает ошибку, SQLParamData возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO или отменяет инструкцию.
Если приложение вызывает SQLCancel , в то время как драйвер по-прежнему нуждается в данных для параметров выполнения, драйвер отменяет выполнение инструкции; приложение может снова вызывать SQLExecute или SQLExecDirect .
Получение потоковых выходных параметров
Когда приложение задает InputOutputType значение SQL_PARAM_INPUT_OUTPUT_STREAM или SQL_PARAM_OUTPUT_STREAM, значение выходного параметра должно быть получено одним или несколькими вызовами SQLGetData. Если драйвер имеет потоковое значение выходного параметра, возвращаемое приложению, оно вернет SQL_PARAM_DATA_AVAILABLE в ответ на вызов следующих функций: SQLMoreResults, SQLExecute и SQLExecDirect. Приложение вызывает SQLParamData , чтобы определить, какое значение параметра доступно.
Дополнительные сведения о SQL_PARAM_DATA_AVAILABLE и потоковых выходных параметрах см. в разделе "Получение выходных параметров с помощью SQLGetData".
Использование массивов параметров
Когда приложение подготавливает инструкцию с маркерами параметров и передает массив параметров, это можно выполнить двумя способами. Один из способов заключается в том, чтобы драйвер опирался на возможности обработки массива внутренней части, в этом случае весь оператор с массивом параметров рассматривается как одна атомарная единица. Oracle — это пример источника данных, поддерживающего возможности обработки массивов. Другой способ реализации этой функции — создать пакет инструкций SQL, одну инструкцию SQL для каждого набора параметров в массиве параметров и выполнить пакет. Массивы параметров нельзя использовать с инструкцией UPDATE WHERE CURRENT OF .
При обработке массива параметров отдельные результирующие наборы или количество строк (по одному для каждого набора параметров) могут быть доступны, или количество результирующих наборов или строк можно свернуть в одну. Параметр SQL_PARAM_ARRAY_ROW_COUNTS в SQLGetInfo указывает, доступны ли счетчики строк для каждого набора параметров (SQL_PARC_BATCH) или доступно только одно число строк (SQL_PARC_NO_BATCH).
Параметр SQL_PARAM_ARRAY_SELECTS в SQLGetInfo указывает, доступен ли результирующий набор для каждого набора параметров (SQL_PAS_BATCH) или доступен только один результирующий набор (SQL_PAS_NO_BATCH). Если драйвер не разрешает выполнение инструкции создания результирующих наборов с массивом параметров, SQL_PARAM_ARRAY_SELECTS возвращает SQL_PAS_NO_SELECT.
Дополнительные сведения см. в разделе "Функция SQLGetInfo".
Для поддержки массивов параметров атрибут инструкции SQL_ATTR_PARAMSET_SIZE задает количество значений для каждого параметра. Если поле больше 1, SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR поля APD должны указывать на массивы. Кратность каждого массива равна значению SQL_ATTR_PARAMSET_SIZE.
Поле SQL_DESC_ROWS_PROCESSED_PTR APD указывает на буфер, содержащий количество наборов обработанных параметров, включая наборы ошибок. По мере обработки каждого набора параметров драйвер сохраняет новое значение в буфере. Число не будет возвращено, если это пустой указатель. Если используются массивы параметров, значение, указываемое полем SQL_DESC_ROWS_PROCESSED_PTR APD, заполняется, даже если SQL_ERROR возвращается функцией параметра. Если возвращается SQL_NEED_DATA, значение, указываемое полем SQL_DESC_ROWS_PROCESSED_PTR APD, устанавливается в набор параметров, обрабатываемых.
Что происходит при привязке массива параметров и выполняется инструкция UPDATE WHERE CURRENT OF , определяется драйвером.
Привязка параметров column-Wise
В привязке со столбцами приложение привязывает отдельные массивы параметров и индикаторов к каждому параметру.
Чтобы использовать привязку со столбцами, приложение сначала задает атрибут инструкции SQL_ATTR_PARAM_BIND_TYPE значение SQL_PARAM_BIND_BY_COLUMN. (Это значение по умолчанию.) Для привязки каждого столбца приложение выполняет следующие действия:
Выделяет массив буфера параметров.
Выделяет массив буферов длины или индикатора.
Примечание.
Если приложение записывает непосредственно в дескрипторы при использовании привязки со столбцами, отдельные массивы можно использовать для данных длины и индикатора.
Вызывает SQLBindParameter со следующими аргументами:
ValueType — это тип C одного элемента в массиве буфера параметров.
ParameterType — это тип SQL параметра.
ParameterValuePtr — это адрес массива буфера параметров.
BufferLength — это размер одного элемента в массиве буфера параметров. Аргумент BufferLength игнорируется, если данные являются данными фиксированной длины.
StrLen_or_IndPtr — это адрес массива длины или индикатора.
Дополнительные сведения об использовании этой информации см. в разделе "Аргумент ParameterValuePtr" в разделе "Комментарии" далее в этом разделе. Дополнительные сведения о привязке параметров со столбцами см. в разделе "Массивы параметров привязки".
Привязка параметров Row-Wise
В привязке по строкам приложение определяет структуру, содержащую буферы параметров и длины или индикатора для привязки каждого параметра.
Чтобы использовать привязку по строкам, приложение выполняет следующие действия.
Определяет структуру для хранения одного набора параметров (включая буферы параметра и длины или индикатора) и выделяет массив этих структур.
Примечание.
Если приложение записывает непосредственно в дескрипторы при использовании привязки по строкам, отдельные поля можно использовать для данных длины и индикатора.
Задает атрибут оператора SQL_ATTR_PARAM_BIND_TYPE размер структуры, содержащей один набор параметров или размер экземпляра буфера, в который будут привязаны параметры. Длина должна содержать пространство для всех привязанных параметров, а также любое заполнение структуры или буфера, чтобы убедиться, что при добавлении адреса привязанного параметра с указанной длиной результат указывает на начало одного и того же параметра в следующей строке. При использовании оператора sizeof в ANSI C это поведение гарантируется.
Вызывает SQLBindParameter со следующими аргументами для привязки каждого параметра:
ValueType — это тип элемента буфера параметров, привязанного к столбцу.
ParameterType — это тип SQL параметра.
ParameterValuePtr — это адрес элемента буфера параметров в первом элементе массива.
BufferLength — это размер элемента буфера параметров.
StrLen_or_IndPtr — это адрес привязанного элемента длины или индикатора.
Дополнительные сведения об использовании этой информации см. в разделе "Аргумент ParameterValuePtr " далее в этом разделе. Дополнительные сведения о строковой привязке параметров см. в массивах привязки параметров.
Сведения об ошибке
Если драйвер не реализует массивы параметров в виде пакетов (параметр SQL_PARAM_ARRAY_ROW_COUNTS равен SQL_PARC_NO_BATCH), то ситуации ошибок обрабатываются так, как если бы выполнялась одна инструкция. Если драйвер реализует массивы параметров в виде пакетов, приложение может использовать поле заголовка SQL_DESC_ARRAY_STATUS_PTR IPD, чтобы определить, какой параметр инструкции SQL или какой параметр в массиве параметров вызвал SQLExecDirect или SQLExecute , чтобы вернуть ошибку. Это поле содержит сведения о состоянии для каждой строки значений параметров. Если поле указывает, что произошла ошибка, поля в структуре диагностических данных будут указывать номер строки и параметра параметра, завершившееся сбоем. Число элементов в массиве определяется полем заголовка SQL_DESC_ARRAY_SIZE в APD, которое можно задать атрибутом инструкции SQL_ATTR_PARAMSET_SIZE.
Примечание.
Поле заголовка SQL_DESC_ARRAY_STATUS_PTR в APD используется для пропуска параметров. Дополнительные сведения об игнорировании параметров см. в следующем разделе "Игнорируние набора параметров".
Когда SQLExecute или SQLExecDirect возвращает SQL_ERROR, элементы массива, на которые указывает поле SQL_DESC_ARRAY_STATUS_PTR в IPD, будет содержать SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED или SQL_PARAM_DIAG_UNAVAILABLE.
Для каждого элемента в этом массиве структура диагностических данных содержит одну или несколько записей состояния. Поле SQL_DIAG_ROW_NUMBER структуры указывает номер строки значений параметров, вызвавших ошибку. Если можно определить конкретный параметр в строке параметров, вызвавших ошибку, номер параметра будет введен в поле SQL_DIAG_COLUMN_NUMBER.
SQL_PARAM_UNUSED вводится, если параметр не использовался, так как ошибка произошла в предыдущем параметре, принудив SQLExecute или SQLExecDirect к прерыванию. Например, если при выполнении набора параметров, вызвавших прерывание SQLExecute или SQLExecDirect , произошла ошибка, SQL_PARAM_UNUSED вводится в массив состояния для параметров 41–50.
SQL_PARAM_DIAG_UNAVAILABLE вводится, когда драйвер обрабатывает массивы параметров как монолитную единицу, поэтому не создает этот отдельный уровень сведений об ошибке.
Некоторые ошибки при обработке одного набора параметров приводят к остановке обработки последующих наборов параметров в массиве. Другие ошибки не влияют на обработку последующих параметров. Какие ошибки прекратят обработку, определяется драйвером. Если обработка не остановлена, все параметры в массиве обрабатываются, SQL_SUCCESS_WITH_INFO возвращается в результате ошибки, а буфер, определенный SQL_ATTR_PARAMS_PROCESSED_PTR, имеет общее количество наборов параметров, обработанных (как определено атрибутом инструкции SQL_ATTR_PARAMSET_SIZE), включающее наборы ошибок.
Внимание
Поведение ODBC при возникновении ошибки в обработке массива параметров отличается в ODBC 3.x , чем это было в ODBC 2.x. В ODBC 2.x, функция вернула SQL_ERROR и перестала обрабатываться. Буфер, на который указывает аргумент pirow SQLParamOptions, содержит число строк ошибки. В ODBC 3.x функция возвращает SQL_SUCCESS_WITH_INFO и обработка может остановить или продолжить. Если он продолжается, буфер, указанный SQL_ATTR_PARAMS_PROCESSED_PTR, будет иметь значение всех обработанных параметров, включая те, которые привели к ошибке. Это изменение может вызвать проблемы для существующих приложений.
Когда SQLExecute или SQLExecDirect возвращается перед завершением обработки всех наборов параметров в массиве параметров, например при возврате SQL_ERROR или SQL_NEED_DATA, массив состояния содержит состояния для этих параметров, которые уже обработаны. Расположение, на которое указывает поле SQL_DESC_ROWS_PROCESSED_PTR в IPD, содержит номер строки в массиве параметров, вызвавшего код ошибки SQL_ERROR или SQL_NEED_DATA. При отправке массива параметров в инструкцию SELECT доступность значений массива состояния определяется драйвером; они могут быть доступны после выполнения инструкции или получения результирующих наборов.
Игнорировать набор параметров
Поле SQL_DESC_ARRAY_STATUS_PTR APD (как задано атрибутом инструкции SQL_ATTR_PARAM_STATUS_PTR) можно использовать для указания, что набор привязанных параметров в инструкции SQL следует игнорировать. Чтобы направить драйвер, чтобы игнорировать один или несколько наборов параметров во время выполнения, приложение должно выполнить следующие действия.
Вызовите SQLSetDescField , чтобы задать поле заголовка SQL_DESC_ARRAY_STATUS_PTR APD, чтобы указать массив значений SQLUSMALLINT, чтобы содержать сведения о состоянии. Это поле также можно задать путем вызова SQLSetStmtAttr с атрибутом SQL_ATTR_PARAM_OPERATION_PTR, что позволяет приложению задать поле без получения дескриптора дескриптора.
Задайте каждому элементу массива, определенному полем SQL_DESC_ARRAY_STATUS_PTR APD, одно из двух значений:
SQL_PARAM_IGNORE, чтобы указать, что строка исключена из выполнения инструкции.
SQL_PARAM_PROCEED, чтобы указать, что строка включена в выполнение инструкции.
Вызовите SQLExecDirect или SQLExecute , чтобы выполнить подготовленную инструкцию.
Следующие правила применяются к массиву, определенному полем SQL_DESC_ARRAY_STATUS_PTR APD:
Указатель по умолчанию имеет значение NULL.
Если указатель имеет значение NULL, используются все наборы параметров, как если бы для всех элементов было задано значение SQL_ROW_PROCEED.
Установка элемента на SQL_PARAM_PROCEED не гарантирует, что операция будет использовать этот конкретный набор параметров.
SQL_PARAM_PROCEED определяется как 0 в файле заголовка.
Приложение может задать поле SQL_DESC_ARRAY_STATUS_PTR в APD, чтобы указать тот же массив, что и поле SQL_DESC_ARRAY_STATUS_PTR в IRD. Это полезно при привязке параметров к данным строк. Затем параметры можно игнорировать в соответствии с состоянием данных строки. Помимо SQL_PARAM_IGNORE, следующие коды вызывают игнорировать параметр в инструкции SQL: SQL_ROW_DELETED, SQL_ROW_UPDATED и SQL_ROW_ERROR. Помимо SQL_PARAM_PROCEED, следующие коды вызывают продолжение инструкции SQL: SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO и SQL_ROW_ADDED.
Повторная привязка параметров
Приложение может выполнить одно из двух операций, чтобы изменить привязку:
Вызовите SQLBindParameter , чтобы указать новую привязку для столбца, который уже привязан. Драйвер перезаписывает старую привязку новым.
Укажите смещение, которое нужно добавить в буферный адрес, который был указан вызовом привязки к SQLBindParameter. Дополнительные сведения см. в следующем разделе "Повторное связывание с смещениями".
Повторная привязка с помощью смещения
Повторная привязка параметров особенно полезна, если приложение имеет конфигурацию буферной области, которая может содержать множество параметров, но вызов SQLExecDirect или SQLExecute использует только несколько параметров. Оставшееся пространство в буферной области можно использовать для следующего набора параметров, изменив существующую привязку смещением.
Поле заголовка SQL_DESC_BIND_OFFSET_PTR в APD указывает на смещение привязки. Если поле не равно NULL, драйвер разыменовывает указатель и, если ни одно из значений в SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR поля является пустым указателем, добавляет деконференцию значения к этим полям в записях дескриптора во время выполнения. Новые значения указателя используются при выполнении инструкций SQL. Смещение остается допустимым после повторной привязки. Так как SQL_DESC_BIND_OFFSET_PTR является указателем на смещение, а не само смещение, приложение может напрямую изменить смещение, не вызывая SQLSetDescField или SQLSetDescRec для изменения поля дескриптора. Указатель по умолчанию имеет значение NULL. Поле SQL_DESC_BIND_OFFSET_PTR ARD можно задать путем вызова SQLSetDescField или вызова SQLSetStmtAttr с помощью fAttribute SQL_ATTR_PARAM_BIND_OFFSET_PTR.
Смещение привязки всегда добавляется непосредственно к значениям в полях SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR и SQL_DESC_OCTET_LENGTH_PTR. Если смещение изменяется на другое значение, новое значение по-прежнему добавляется непосредственно в значение в каждом поле дескриптора. Новое смещение не добавляется к сумме значения поля и любых предыдущих смещениях.
Дескрипторы
Способ привязки параметра определяется полями APD и IPD. Аргументы в SQLBindParameter используются для задания этих полей дескриптора. Поля также можно задать функциями SQLSetDescField , хотя SQLBindParameter эффективнее использовать, так как приложению не нужно получать дескриптор для вызова SQLBindParameter.
Внимание
Вызов SQLBindParameter для одной инструкции может повлиять на другие инструкции. Это происходит при явном выделении ARD, связанном с инструкцией, и также связана с другими операторами. Так как SQLBindParameter изменяет поля APD, изменения применяются ко всем операторам, с которым связан дескриптор. Если это не обязательное поведение, приложение должно отсортировать этот дескриптор от других инструкций, прежде чем вызывать SQLBindParameter.
Концептуально SQLBindParameter выполняет следующие действия в последовательности:
Вызывает SQLGetStmtAttr , чтобы получить дескриптор APD.
Вызывает SQLGetDescField, чтобы получить поле SQL_DESC_COUNT APD, и если значение аргумента ColumnNumber превышает значение SQL_DESC_COUNT, вызывает SQLSetDescField, чтобы увеличить значение SQL_DESC_COUNT в ColumnNumber.
Вызывает SQLSetDescField несколько раз, чтобы назначить значения следующим полям APD:
Задает SQL_DESC_TYPE и SQL_DESC_CONCISE_TYPE значение ValueType, за исключением того, что если ValueType является одним из кратких идентификаторов подтипа даты и времени или интервала, он задает SQL_DESC_TYPE SQL_DATETIME или SQL_INTERVAL соответственно, задает SQL_DESC_CONCISE_TYPE в краткий идентификатор и задает SQL_DESC_DATETIME_INTERVAL_CODE соответствующий подкод даты и интервала.
Задает поле SQL_DESC_OCTET_LENGTH значение BufferLength.
Задает поле SQL_DESC_DATA_PTR значением ParameterValue.
Задает поле SQL_DESC_OCTET_LENGTH_PTR значением StrLen_or_Ind.
Задает поле SQL_DESC_INDICATOR_PTR также значением StrLen_or_Ind.
Параметр StrLen_or_Ind указывает сведения о индикаторе и длину значения параметра.
Вызывает SQLGetStmtAttr для получения дескриптора IPD.
Вызывает SQLGetDescField, чтобы получить поле SQL_DESC_COUNT IPD, и если значение аргумента ColumnNumber превышает значение SQL_DESC_COUNT, вызывает SQLSetDescField, чтобы увеличить значение SQL_DESC_COUNT в ColumnNumber.
Вызывает SQLSetDescField несколько раз, чтобы назначить значения следующим полям IPD:
Задает SQL_DESC_TYPE и SQL_DESC_CONCISE_TYPE значение ParameterType, за исключением того, что если ПараметрТип является одним из кратких идентификаторов подтипа даты и времени или интервала, он задает SQL_DESC_TYPE SQL_DATETIME или SQL_INTERVAL соответственно, задает SQL_DESC_CONCISE_TYPE в краткий идентификатор и задает SQL_DESC_DATETIME_INTERVAL_CODE соответствующий подкод даты и интервала.
Задает один или несколько SQL_DESC_LENGTH, SQL_DESC_PRECISION и SQL_DESC_DATETIME_INTERVAL_PRECISION в соответствии с параметромType.
Задает SQL_DESC_SCALE значение DecimalDigits.
Если вызов SQLBindParameter завершается ошибкой, содержимое полей дескриптора, заданных в APD, не определено, а поле SQL_DESC_COUNT APD не изменяется. Кроме того, поля SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE и SQL_DESC_TYPE соответствующей записи в IPD не определены, а поле SQL_DESC_COUNT IPD не изменяется.
Преобразование вызовов в SQLSetParam и из нее
Когда приложение ODBC 1.0 вызывает SQLSetParam в ODBC 3.x driver, ODBC 3.Диспетчер драйверов x сопоставляет вызов, как показано в следующей таблице.
| Вызов приложения ODBC 1.0 | Вызов ODBC 3.драйвер x |
|---|---|
| SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr); | SQLBindParameter( StatementHandle, ParameterNumber, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, DecimalDigits, ParameterValuePtr, SQL_SETPARAM_VALUE_MAX, StrLen_or_IndPtr); |
Примеры
А. Использование функции SQLBindParameter
В следующем примере приложение подготавливает инструкцию SQL для вставки данных в таблицу ORDERS. Для каждого параметра в инструкции приложение вызывает SQLBindParameter , чтобы указать тип данных ODBC C и тип данных SQL параметра, а также привязать буфер к каждому параметру. Для каждой строки данных приложение назначает значения данных каждому параметру и вызывает SQLExecute для выполнения инструкции.
В следующем примере предполагается, что у вас есть источник данных ODBC на компьютере с именем Northwind, связанный с базой данных Northwind.
Дополнительные примеры кода см. в разделе "Функция SQLBulkOperations", функция SQLProcedures, функция SQLPutData и функция SQLSetPos.
// SQLBindParameter_Function.cpp
// compile with: ODBC32.lib
#include <windows.h>
#include <sqltypes.h>
#include <sqlext.h>
#define EMPLOYEE_ID_LEN 10
SQLHENV henv = NULL;
SQLHDBC hdbc = NULL;
SQLRETURN retcode;
SQLHSTMT hstmt = NULL;
SQLSMALLINT sCustID;
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];
SQL_DATE_STRUCT dsOrderDate;
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;
int main() {
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);
retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);
retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);
retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);
strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");
sCustID = 5;
dsOrderDate.year = 2006;
dsOrderDate.month = 3;
dsOrderDate.day = 17;
retcode = SQLExecute(hstmt);
}
B. Выполнение хранимой процедуры с помощью именованного параметра
В следующем примере приложение выполняет хранимую процедуру SQL Server с помощью именованного параметра.
// SQLBindParameter_Function_2.cpp
// compile with: ODBC32.lib
// sample assumes the following stored procedure:
// use northwind
// DROP PROCEDURE SQLBindParameter
// GO
//
// CREATE PROCEDURE SQLBindParameter @quote int
// AS
// delete from orders where OrderID >= @quote
// GO
#include <windows.h>
#include <sqltypes.h>
#include <sqlext.h>
SQLHDESC hIpd = NULL;
SQLHENV henv = NULL;
SQLHDBC hdbc = NULL;
SQLRETURN retcode;
SQLHSTMT hstmt = NULL;
SQLCHAR szQuote[50] = "100084";
SQLINTEGER cbValue = SQL_NTS;
int main() {
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);
retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);
retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);
retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);
retcode = SQLExecute(hstmt);
}
Связанные функции
| Сведения | Смотрите |
|---|---|
| Возврат сведений о параметре в инструкции | Функция SQLDescribeParam |
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Освобождение буферов параметров в инструкции | Функция SQLFreeStmt |
| Возврат количества параметров инструкции | Функция SQLNumParams |
| Возврат следующего параметра для отправки данных | Функция SQLParamData |
| Указание нескольких значений параметров | Функция SQLParamOptions |
| Отправка данных параметров во время выполнения | Функция SQLPutData |
См. также
Справочник по API ODBC
Файлы заголовков ODBC
Получение выходных параметров с помощью метода SQLGetData