Привязка и передача данных возвращающих табличное значение параметров и значений столбцов
Возвращающие табличное значение параметры, как и другие параметры, нуждаются в привязке до их передачи на сервер. Приложение выполняет привязку возвращающих табличное значение параметров точно так же, как и любых других параметров: для этого используется функция SQLBindParameter или эквивалентные этому вызовы функций SQLSetDescField или SQLSetDescRec. Типом данных на сервере для параметра, возвращающего табличное значение, является SQL_SS_TABLE. Тип C может иметь значение SQL_C_DEFAULT или SQL_C_BINARY.
В SQL Server 2008 и более поздних версиях возвращающие табличное значение параметры поддерживаются только как входные. Поэтому любая попытка установить для SQL_DESC_PARAMETER_TYPE значение, отличное от SQL_PARAM_INPUT, приведет к возникновению ошибки SQL_ERROR с SQLSTATE = HY105 и появлению сообщения «Недопустимый тип параметра».
Можно назначать значение по умолчанию для целых столбцов возвращающих табличное значение параметров с помощью атрибута SQL_CA_SS_COL_HAS_DEFAULT_VALUE. Однако нельзя назначить значения по умолчанию для отдельных столбцов возвращающих табличное значение параметров, передав функции SQLBindParameter в параметре StrLen_or_IndPtr значение SQL_DEFAULT_PARAM. Для возвращающих табличное значение параметров в целом нельзя назначить значение по умолчанию с помощью значения SQL_DEFAULT_PARAM параметра StrLen_or_IndPtr функции SQLBindParameter Если эти правила нарушены, вызов функций SQLExecute и SQLExecDirect вернет значение SQL_ERROR. Будет создана диагностическая запись с параметром SQLSTATE=07S01 и сообщением «Недопустимое использование параметра по умолчанию для параметра <p>», где <p> — порядковый номер возвращающего табличное значение параметра в инструкции запроса.
После привязки возвращающего табличное значение параметра приложение должно выполнить привязку каждого столбца параметров, возвращающих табличное значение. Для привязки столбцов сначала вызывается метод SQLSetStmtAttr, присваивающий параметру SQL_SOPT_SS_PARAM_FOCUS порядковый номер возвращающего табличное значение параметра. Затем приложение выполняет привязку столбцов возвращающих табличные значения параметров с помощью вызова следующих процедур. SQLBindParameter, SQLSetDescRec и SQLSetDescField. Присвоение атрибуту SQL_SOPT_SS_PARAM_FOCUS значения 0 восстанавливает обычное воздействие функций SQLBindParameter, SQLSetDescRec и SQLSetDescField на параметры верхнего уровня.
Для самого возвращающего табличное значение параметра никакие данные не передаются и не принимаются. Передаются и принимаются данные для каждого из столбцов, составляющих этот параметр. Поскольку возвращающий табличное значение параметр представляет собой псевдостолбец, параметры функции 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 должен содержать либо строковую длину имени, умноженную на sizeof(WCHAR), либо значение SQL_NTS. |
BufferLength |
SQL_DESC_OCTET_LENGTH в APD. |
Длина имени типа возвращающего табличное значение параметра в байтах. Значение может быть равно SQL_NTS, если имя типа представляет собой строку, завершающуюся нулем, или 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 (хотя столбцы, составляющие параметр с табличным значением, могут быть обнуляемыми). Если этому параметру присвоено недопустимое значение, функции SQLExecute и SQLExecDirect возвращают значение SQL_ERROR, будет создана диагностическая запись с параметром SQLSTATE=HY090 и сообщением «Недопустимая длина строки или буфера для параметра <p>», где p — порядковый номер параметра.
Вызывает SQLExecute или SQLExecDirect.
Значения столбцов входного возвращающего табличное значение параметра можно передавать по частям, если для атрибута StrLen_or_IndPtr этого столбца задано значение SQL_LEN_DATA_AT_EXEC(length) или SQL_DATA_AT_EXEC. Это похоже на передачу значений по частям при использовании массивов параметров. Как и для всех прочих параметров с данными времени выполнения, функция SQLParamData не указывает, для какой строки массива драйвер запрашивает данные; об этом должно заботиться приложение. Приложение не может делать никаких предположений о порядке, в котором драйвер будет запрашивать данные.
Переменная привязка строк возвращающего табличное значение параметра
Строки при использовании переменной привязки передаются пакетами во время выполнения, и приложение передает их драйверу по требованию. Это похоже на данные времени выполнения для отдельных значений параметров. Для переменной привязки строк приложение выполняет следующие действия.
Привязывает параметры и столбцы возвращающих табличное значение параметров, как описано в шагах с 1 по 3 предыдущего раздела «Фиксированная привязка строк возвращающего табличное значение параметра».
Устанавливает для атрибута StrLen_or_IndPtr или SQL_DESC_OCTET_LENGTH_PTR значение SQL_DATA_AT_EXEC для всех возвращающих табличное значение параметров, передаваемых во время выполнения. Если ни один из указанных атрибутов не установлен, параметр будет обрабатываться, как описано в предыдущем разделе.
Вызывает SQLExecute или SQLExecDirect. При наличии любых параметров типа SQL_PARAM_INPUT или SQL_PARAM_INPUT_OUTPUT, которые должны быть обработаны как параметры с данными времени выполнения, этот вызов функции вернет значение SQL_NEED_DATA. В этом случае приложение выполняет следующие действия.
- Вызывает 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, после чего переходит к шагу 3а, описанному выше.
Снова вызывает SQLParamData. Если среди столбцов возвращающего табличное значение параметра присутствуют параметры с данными времени выполнения, они будут опознаны по значению ValuePtrPtr, возвращаемому функцией SQLParamData. Когда все значения столбцов будут доступны, вызов функции SQLParamData снова вернет значение ParameterValuePtr для возвращающего табличное значение параметра, и приложение начнет весь процесс заново.