Привязка и передача данных возвращающих табличное значение параметров и значений столбцов
Применимо: 
SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure azure Synapse Analytics Analytics 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 в работе с обычными параметрами верхнего уровня.
Примечание.
Для драйверов Linux и Mac ODBC с 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 предыдущего раздела "Фиксированная привязка строк параметров с табличным значением".
Задает 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 для параметра выполнения данных и возвращаемого кода SQL_NEED_DATA. Когда все данные параметров передаются драйверу, SQLParamData возвращает SQL_SUCCESS, SQL_SUCCESS_WITH_INFO или SQL_ERROR. Для параметров выполнения параметр ParameterValuePtr, который совпадает с полем дескриптора SQL_DESC_DATA_PTR, можно рассматривать как токен для идентификации параметра, для которого требуется уникальное значение. Этот токен передается приложением драйверу во время привязки, а затем передается обратно приложению во время выполнения.
Чтобы отправить табличное значение данные строки параметров для параметров с табличным значением, если параметр табличного значения не имеет строк, приложение вызывает 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 для табличного параметра, а приложение начинается снова.