Привязка и передача данных возвращающих табличное значение параметров и значений столбцов
Применимо к:
SQL Server Azure SQL DatabaseУправляемый экземпляр SQL AzureAzure Synapse AnalyticsAnalytics Platform System (PDW)
Возвращаемые табличное значение параметры (TVP), как и другие параметры, должны быть привязаны перед их передачей на сервер. Приложение привязывает возвращающие табличное значение параметры так же, как и другие параметры: с помощью SQLBindParameter или эквивалентных вызовов SQLSetDescField или SQLSetDescRec. Типом данных на сервере для параметра, возвращающего табличное значение, является SQL_SS_TABLE. Тип C может иметь значение SQL_C_DEFAULT или SQL_C_BINARY.
В SQL Server 2008 (10.0.x) или более поздних версиях поддерживаются только входные параметры с табличным значением. Поэтому любая попытка задать для SQL_DESC_PARAMETER_TYPE значение, отличное от SQL_PARAM_INPUT, возвращает SQL_ERROR с SQLSTATE = HY105 и сообщением "Недопустимый тип параметра".
Можно назначать значение по умолчанию для целых столбцов возвращающих табличное значение параметров с помощью атрибута SQL_CA_SS_COL_HAS_DEFAULT_VALUE. Однако отдельным значениям столбцов возвращающего табличное значение параметра нельзя назначить значения по умолчанию с помощью SQL_DEFAULT_PARAM в StrLen_or_IndPtr с SQLBindParameter. Параметры с табличным значением в целом нельзя задать значение по умолчанию с помощью SQL_DEFAULT_PARAM в StrLen_or_IndPtr с SQLBindParameter. Если эти правила не соблюдались, SQLExecute или SQLExecDirect возвращает SQL_ERROR. Создается диагностическая запись с sqlSTATE=07S01 и сообщением "Недопустимое использование параметра по умолчанию для параметра <p>", где <p> — порядковый номер TVP в инструкции запроса.
Примечание
Возвращающие табличное значение параметры не имеют значения по умолчанию, которые можно задать, так как SQL_DEFAULT_PARAM не указывает на отсутствие строк. Таким образом, если строк нет, столбцы для привязки отсутствуют.
После привязки возвращающего табличное значение параметра приложение должно выполнить привязку каждого столбца параметров, возвращающих табличное значение. Для этого приложение сначала вызывает SQLSetStmtAttr, чтобы задать SQL_SOPT_SS_PARAM_FOCUS порядковый номер возвращающего табличное значение параметра. Приложение привязывает столбцы возвращающего табличное значение параметра, вызывая следующие подпрограммы: SQLBindParameter, SQLSetDescRec и SQLSetDescField. При установке SQL_SOPT_SS_PARAM_FOCUS значения 0 восстанавливается обычное действие SQLBindParameter, SQLSetDescRec и SQLSetDescField в работе с обычными параметрами верхнего уровня.
Примечание
Для драйверов ODBC для Linux и Mac с unixODBC 2.3.1–2.3.4 при задании имени TVP с помощью SQLSetDescField с полем дескриптора SQL_CA_SS_TYPE_NAME unixODBC не выполняет автоматическое преобразование между строками ANSI и Юникода в зависимости от точной функции (SQLSetDescFieldA /SQLSetDescFieldW). Для задания имени TVP необходимо всегда использовать SQLBindParameter или SQLSetDescFieldW со строкой Юникода (UTF-16).
Для самого возвращающего табличное значение параметра никакие данные не передаются и не принимаются. Передаются и принимаются данные для каждого из столбцов, составляющих этот параметр. Так как возвращающий табличное значение параметр является псевдостолбец, параметры sqlBindParameter ссылаются на атрибуты, отличные от других типов данных, следующим образом:
| Параметр | Связанный атрибут для типов параметров без табличного значения, включая столбцы | Связанные атрибуты для возвращающих табличное значение параметров |
|---|---|---|
| InputOutputType | SQL_DESC_PARAMETER_TYPE в IPD. Для столбцов, возвращающих табличное значение параметров, этот атрибут должен совпадать с настройкой для самого возвращающего табличное значение параметра. |
SQL_DESC_PARAMETER_TYPE в IPD. Это должен быть атрибут SQL_PARAM_INPUT. |
| ValueType | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE в APD. | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE в APD. Это должен быть атрибут SQL_C_DEFAULT или SQL_C_BINARY. |
| ParameterType | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE в IPD. | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE в IPD. Это должен быть атрибут SQL_SS_TABLE. |
| ColumnSize | SQL_DESC_LENGTH или SQL_DESC_PRECISION в IPD. Это зависит от значения ParameterType. |
SQL_DESC_ARRAY_SIZE Значение этого атрибута можно задать также с помощью атрибута SQL_ATTR_PARAM_SET_SIZE, когда фокус параметра установлен на возвращающий табличное значение параметр. Для возвращающего табличное значение параметра эта величина равна количеству строк в буферах столбцов данного параметра. |
| DecimalDigits | SQL_DESC_PRECISION или SQL_DESC_SCALE в IPD. | Не используется. Атрибут должен иметь значение 0. Если этот параметр не равен 0, SQLBindParameter возвращает SQL_ERROR и создается диагностическая запись с sqlSTATE= HY104 и сообщением "Недопустимая точность или масштаб". |
| ParameterValuePtr | SQL_DESC_DATA_PTR в APD. | SQL_CA_SS_TYPE_NAME. Это необязательно для вызовов хранимых процедур. Если это не требуется, можно указать значение NULL. Его необходимо указать для инструкций SQL, которые не являются вызовами процедур. Этот параметр также служит уникальным значением, по которому приложение может узнать конкретный возвращающий табличное значение параметр при использовании переменной строковой привязки. Дополнительные сведения см. в подразделе «Переменная строковая привязка возвращающих табличное значение параметров» далее в этом разделе. Если имя типа возвращающего табличное значение параметра указано при вызове SQLBindParameter, оно должно быть указано в виде значения Юникода, даже в приложениях, созданных как приложения ANSI. Значение, используемое для параметра StrLen_or_IndPtr , должно быть либо SQL_NTS, либо длина строки имени, умноженная на размер (WCHAR). |
| BufferLength | SQL_DESC_OCTET_LENGTH в APD. | Длина имени типа возвращающего табличное значение параметра в байтах. Это может быть SQL_NTS, если имя типа заканчивается null, или 0, если имя типа возвращающего табличное значение параметра не является обязательным. |
| StrLen_or_IndPtr | SQL_DESC_OCTET_LENGTH_PTR в APD. | SQL_DESC_OCTET_LENGTH_PTR в APD. Для возвращающих табличное значение параметров этот атрибут хранит не длину данных, а количество строк. |
Для возвращающих табличное значение параметров поддерживаются два режима передачи данных: фиксированная и переменная привязка строк.
Фиксированная привязка строк возвращающего табличное значение параметра
Для фиксированной привязки строк приложение выделяет буферы (или буферные массивы), достаточно большие для всех возможных значений входных столбцов. Приложение выполняет следующие действия.
Привязывает все параметры с помощью вызовов SQLBindParameter, SQLSetDescRec или SQLSetDescField.
- Присваивает атрибуту SQL_DESC_ARRAY_SIZE значение максимально возможного числа рядов, которые можно передать для каждого возвращающего табличное значение параметра. Это можно сделать в вызове SQLBindParameter.
Вызывает SQLSetStmtAttr, чтобы задать SQL_SOPT_SS_PARAM_FOCUS порядковый номер каждого возвращающего табличное значение параметра.
Для каждого возвращающего табличное значение параметра привязывает столбцы возвращающих табличное значение параметров с помощью вызовов SQLBindParameter, SQLSetDescRec или SQLSetDescField.
Для каждого столбца параметров с табличным значением, который должен иметь значения по умолчанию, вызывает SQLSetDescField, чтобы задать для SQL_CA_SS_COL_HAS_DEFAULT_VALUE значение 1.
Вызывает SQLSetStmtAttr, чтобы задать для SQL_SOPT_SS_PARAM_FOCUS значение 0. Это необходимо сделать перед вызовом SQLExecute или SQLExecDirect. В противном случае возвращается SQL_ERROR и создается диагностическая запись с sqlSTATE=HY024 и сообщением "Недопустимое значение атрибута, SQL_SOPT_SS_PARAM_FOCUS (должно быть равно нулю во время выполнения)".
Задает StrLen_or_IndPtr или SQL_DESC_OCTET_LENGTH_PTR для SQL_DEFAULT_PARAM для возвращающего табличное значение параметра без строк или количества строк, передаваемых при следующем вызове SQLExecute или SQLExecDirect, если возвращающий табличное значение параметр содержит строки. StrLen_or_IndPtr или SQL_DESC_OCTET_LENGTH_PTR нельзя задать значение SQL_NULL_DATA для возвращающего табличное значение параметра, так как возвращаемые табличное значение параметры не могут иметь значение NULL (хотя составные столбцы возвращающего табличное значение параметра могут иметь значение NULL). Если для этого параметра задано недопустимое значение, SQLExecute или SQLExecDirect возвращает SQL_ERROR и создается диагностическая запись с sqlSTATE=HY090 и сообщением "Недопустимая длина строки или буфера для параметра <p>", где p — номер параметра.
Вызывает SQLExecute или SQLExecDirect.
Входные значения столбцов с табличным значением параметров можно передавать по частям, если для столбца StrLen_or_IndPtr задано значение SQL_LEN_DATA_AT_EXEC(длина) или SQL_DATA_AT_EXEC. Это похоже на передачу значений по частям при использовании массивов параметров. Как и в случае со всеми параметрами данных при выполнении, SQLParamData не указывает, в какой строке массива драйвер запрашивает данные; приложение должно позаботиться об этом. Приложение не может делать никаких предположений о порядке, в котором драйвер запрашивает значения.
Переменная привязка строк возвращающего табличное значение параметра
Для привязки строк переменных строки передаются пакетами во время выполнения, и приложение передает строки драйверу по запросу. Это похоже на данные времени выполнения для отдельных значений параметров. Для переменной привязки строк приложение выполняет следующие действия.
Привязывает параметры и столбцы возвращающих табличное значение параметров, как описано в шагах 1–3 предыдущего раздела "Привязка строк Table-Valued параметров".
Задает StrLen_or_IndPtr или SQL_DESC_OCTET_LENGTH_PTR для любых возвращаемых табличным значением параметров, передаваемых во время выполнения в SQL_DATA_AT_EXEC. Если ни то, ни иное не задано, параметр обрабатывается, как описано в предыдущем разделе.
Вызывает SQLExecute или SQLExecDirect. При этом возвращается SQL_NEED_DATA, если есть какие-либо параметры SQL_PARAM_INPUT или SQL_PARAM_INPUT_OUTPUT для обработки в качестве параметров данных при выполнении. В этом случае приложение выполняет следующие действия.
- Вызывает SQLParamData. Возвращает значение ParameterValuePtr для параметра data-at-execution и код возврата SQL_NEED_DATA. После передачи всех данных параметров в драйвер SQLParamData возвращает SQL_SUCCESS, SQL_SUCCESS_WITH_INFO или SQL_ERROR. Для параметров при выполнении параметр ParameterValuePtr, который совпадает с полем дескриптора SQL_DESC_DATA_PTR, можно рассматривать как маркер для идентификации параметра, для которого требуется уникальное значение. Этот токен передается приложением драйверу во время привязки, а затем передается обратно приложению во время выполнения.
Чтобы отправить данные строки возвращающего табличное значение параметра для возвращающих табличное значение значений null параметров, если возвращающий табличное значение параметр не содержит строк, приложение вызывает SQLPutData с StrLen_or_Ind значением SQL_DEFAULT_PARAM.
Для возвращающих табличное значение параметров, отличных от NULL, приложение выполняет следующие действия.
Задает Str_Len_or_Ind для всех столбцов параметров, возвращающих табличное значение, соответствующими значениям, и заполняет буферы данных для столбцов возвращающих табличное значение параметров, которые не должны быть параметрами данных при выполнении. Данные времени выполнения можно использовать для столбцов возвращающих табличное значение параметров, подобно тому, как обычные параметры могут передаваться драйверу по частям.
Вызывает SQLPutData с Str_Len_or_Ind задано количество строк, отправляемых на сервер. Любое значение за пределами диапазона от 0 до SQL_DESC_ARRAY_SIZE или SQL_DEFAULT_PARAM является ошибкой и возвращает SQLSTATE HY090 с сообщением "Недопустимая длина строки или буфера". 0 указывает, что все строки отправлены, и больше нет данных для возвращающего табличное значение параметра (как указано во втором маркированном элементе в этом списке). SQL_DEFAULT_PARAM можно использовать только в случае, если драйвер запрашивает данные возвращающего табличное значение параметра впервые (как описано в первом пункте данного списка).
После отправки всех строк вызывает SQLPutData для возвращающего табличное значение параметра со значением Str_Len_or_Ind 0, а затем переходите к шагу 3a выше.
Снова вызывает SQLParamData. Если в столбцах возвращаемых табличное значение параметров есть какие-либо параметры, связанные с данными при выполнении, они определяются значением ValuePtrPtr, возвращенным SQLParamData. Когда доступны все значения столбцов, SQLParamData возвращает значение ParameterValuePtr для возвращающего табличное значение параметра, и приложение запускается снова.
Дальнейшие действия
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по