Сценарии использования возвращающих табличное значение параметров ODBC
В данном разделе обсуждаются основные пользовательские сценарии для использования возвращающих табличное значение параметров ODBC.
Возвращающий табличное значение параметр с многострочными буферами с полной привязкой (отправка данных в виде возвращающего табличное значение параметра со всеми значениями в памяти)
Возвращающий табличное значение параметр с поддержкой потоковой работы со строками (отправка данных в виде возвращающего табличное значение параметра с использованием данных времени выполнения).
Получение метаданных возвращающих табличное значение параметров из системного каталога.
Получение метаданных возвращающих табличное значение параметров для подготовленной инструкции.
Возвращающий табличное значение параметр с многострочными буферами с полной привязкой (отправка данных в виде возвращающего табличное значение параметра со всеми значениями в памяти)
При использовании с многострочными буферами с полной привязкой все значения параметров доступны в памяти. Например, это характерно для транзакции OLTP, в которой возвращающие табличное значение параметры могут быть упакованы в одну хранимую процедуру. Без возвращающих табличное значение параметров для этого потребовалось бы динамическое создание сложного пакета с несколькими инструкциями или несколько обращений к серверу.
Возвращающий табличное значение параметр сам по себе привязан путем использования функции SQLBindParameter наряду с другими параметрами. После того как все параметры были привязаны, приложение устанавливает атрибут фокуса параметра, SQL_SOPT_SS_PARAM_FOCUS, на каждый возвращающий табличное значение параметр и вызывает функцию SQLBindParameter для столбцов каждого возвращающего табличное значение параметра.
Тип сервера для возвращающего табличное значение параметра является новым типом SQL Server, SQL_SS_TABLE. Типом привязки C для типа SQL_SS_TABLE должен быть всегда SQL_C_DEFAULT. Никакие данные для параметра, привязанного к возвращающему табличное значение параметру, не передаются; они используются, чтобы передавать метаданные таблицы и управлять передачей данных в столбцах, составляющих возвращающий табличное значение параметр.
Длина возвращающего табличное значение параметра устанавливается в значение количества строк, отправленных серверу. Параметр ColumnSize функции SQLBindParameter для возвращающего табличное значение параметра указывает максимальное количество строк, которое можно отправить. Это размер массива буфера столбцов. ParameterValuePtr является буфером параметров для возвращающего табличное значение параметра в функции SQLBindParameter. ParameterValuePtr и связанный с ним BufferLength при необходимости используются для передачи имени типа возвращающего табличное значение параметра. Имя типа не требуется для вызова хранимой процедуры, но требуется для инструкций SQL.
Если во время вызова SQLBindParameter указано имя типа возвращающего табличное значение параметра, то следует всегда использовать значение в Юникоде, даже в тех приложениях, которые рассчитаны на работу с кодировкой ANSI. При указании имени типа возвращающего табличное значение параметра при помощи функции SQLSetDescField можно использовать литерал, который соответствует способу построения приложения. Диспетчер драйвера ODBC выполнит все необходимые преобразования данных в Юникод.
Метаданными для возвращающих табличное значение параметров и столбцов возвращающих табличное значение параметров можно управлять отдельно и явно при помощи функций SQLGetDescRec, SQLSetDescRec, SQLGetDescField и SQLSetDescField. Однако перегрузка функции SQLBindParameter обычно удобнее и в большинстве случаев не требует явного доступа к дескриптору. Этот подход согласован с определением функции SQLBindParameter для других типов данных, за исключением этого, для возвращающего табличное значение параметра затронутые поля дескриптора немного отличаются.
Иногда приложение использует возвращающий табличное значение параметр с динамическими инструкциями SQL, при этом имя типа возвращающего табличное значение параметра должно быть указано. В этом случае, если возвращающий табличное значение параметр не определен для соединения в текущей схеме по умолчанию, для SQL_CA_SS_TYPE_CATALOG_NAME и SQL_CA_SS_TYPE_SCHEMA_NAME при помощи функции SQLSetDescField должны быть установлены значения. Так как определения табличного типа и возвращающие табличное значение параметры должны находиться в одной базе данных, значение SQL_CA_SS_TYPE_CATALOG_NAME не должно быть установлено, если приложение использует возвращающие табличное значение параметры. В противном случае функция SQLSetDescField вернет ошибку.
Образец кода для данного сценария содержится в процедуре demo_fixed_TVP_binding в Использование возвращающих табличные значения параметров (ODBC).
Возвращающий табличное значение параметр с поддержкой потоковой работы со строками (отправка данных в виде возвращающего табличное значение параметра с использованием данных времени выполнения).
В данном сценарии приложение передает строки драйверу, когда он их запрашивает, и они передаются потоком на сервер. Это помогает избежать буферизации всех строк в памяти. Это типично для массовой вставки или обновления сценариев. Возвращающие табличное значение параметры обеспечивают показатель производительности где-то между массивами параметров и массовым копированием. То есть возвращающие табличное значение параметры почти так же легко программировать, как и массивы параметров, но они дают большую гибкость на сервере.
Возвращающий табличное значение параметр и его столбцы привязаны, как описано в предыдущем разделе «Возвращающий табличное значение параметр с многострочными буферами с полной привязкой», но признак длины возвращающего табличное значение параметра установлен в значение SQL_DATA_AT_EXEC. Драйвер реагирует на функцию SQLExecute или SQLExecuteDirect способом, обычным для параметров с данными времени выполнения то есть возвращая значение SQL_NEED_DATA. Когда драйвер готов принять данные для возвращающего табличное значение параметра, функция SQLParamData возвращает значение ParameterValuePtr в функцию SQLBindParameter.
Приложение использует функцию SQLPutData для возвращающего табличное значение параметра, чтобы показать доступность данных для столбцов, составляющих возвращающий табличное значение параметр. При вызове функции SQLPutData для возвращающего табличное значение параметра значение DataPtr всегда должно быть NULL, а значение StrLen_or_Ind должно быть либо 0, либо меньше или равно размеру массива, указанному для буферов возвращающих табличное значение параметров (параметр ColumnSize функции SQLBindParameter). 0 обозначает, что в возвращающем табличное значение параметре больше нет строк и драйвер продолжит обработку со следующего фактического параметра процедуры. Если значение StrLen_or_Ind не равно 0, драйвер будет обрабатывать столбцы, составляющие возвращающий табличное значение параметр, таким же образом, как параметры, привязанные к не возвращающим табличное значение параметрам. Каждый столбец возвращающего табличное значение параметра может определять свою фактическую длину данных, SQL_NULL_DATA, или может определять данные при выполнении посредством своего буфера длины или признака. Значения столбцов возвращающего табличное значение параметра могут передаваться через повторяющиеся вызовы функции SQLPutData, что обычно происходит, когда символьное или двоичное значение должно быть передано по частям.
После того как все столбцы возвращающего табличное значение параметра были обработаны, драйвер снова обращается к возвращающему табличное значение параметру для обработки следующих строк данных возвращающего табличное значение параметра. Поэтому для возвращающих табличное значение параметров с данными времени выполнения драйвер не выполняет обычный последовательный просмотр привязанных параметров. Привязанный возвращающий табличное значение параметр будет опрашиваться до тех пор, пока не будет вызвана функция SQLPutData с параметром StrLen_Or_IndPtr, равным 0; в этот момент драйвер пропустит столбцы возвращающего табличное значение параметра и продвинется к следующему фактическому параметру хранимой процедуры. Когда функция SQLPutData передает значение признака, большее или равное 1, драйвер последовательно обрабатывает столбцы и строки возвращающего табличное значение параметра для всех привязанных строк и столбцов. Затем драйвер возвращается к возвращающему табличное значение параметру. Между получением токена для возвращающего табличное значение параметра из функции SQLParamData и вызовом функции SQLPutData(hstmt, NULL, n) для возвращающего табличное значение параметра приложение должно установить данные столбцов, содержащихся в возвращающем табличное значение параметре, и содержимое буфера индикатора для следующей строки или строк, которые будут переданы на сервер.
Образец кода для этого сценария приведен в подпрограмме demo_variable_TVP_binding в разделе Использование возвращающих табличные значения параметров (ODBC).
Получение метаданных возвращающих табличное значение параметров из системного каталога
Когда приложение вызывает функцию SQLProcedureColumns для процедуры, параметры которой возвращают табличное значение, DATA_TYPE возвращается как тип SQL_SS_TABLE, а TYPE_NAME является именем табличного типа для возвращающего табличное значение параметра. Два дополнительных столбца добавляются к результирующему набору, который возвращается функцией SQLProcedureColumns. SS_TYPE_CATALOG_NAME возвращает имя каталога, в котором определен табличный тип возвращающего табличное значение параметра, а SS_TYPE_SCHEMA_NAME возвращает имя схемы, в которой определен табличный тип возвращающего табличное значение параметра. В соответствии со спецификацией ODBC SS_TYPE_CATALOG_NAME и SS_TYPE_SCHEMA_NAME применяются до всех столбцов драйвера, которые были добавлены в предыдущих версиях SQL Server, и после всех столбцов, применяемых ODBC.
Новые столбцы будут заполнены не только для возвращающих табличное значение параметров, но и для параметров определенного пользователем типа данных CLR. Существующие схема и столбцы каталога параметров определяемого пользователем типа будут все равно заполнены, но наличие общих схемы и столбцов каталога для типов данных, для которых они требуются, упростит разработку приложения в будущем. (Следует отметить, что коллекции схем XML несколько отличаются и не включаются в это изменение).
Приложение использует функцию SQLTables, чтобы определить имена табличных типов таким же образом, как и для хранимых таблиц, системных таблиц и представлений. Новый табличный тип TABLE TYPE вводится, чтобы приложение могло определить табличный тип, связанный с возвращающими табличное значение параметрами. Табличные типы и обычные таблицы используют различные пространства имен. Это значит, что можно использовать одно и то же имя как для табличного типа, так и для существующей таблицы. Для обработки этой ситуации был введен новый атрибут инструкции SQL_SOPT_SS_NAME_SCOPE. Этот атрибут указывает, следует ли функции SQLTables и другим функциям работы с каталогами, которые принимают имя таблицы в качестве параметра, рассматривать имя таблицы как имя существующей таблицы или как имя табличного типа.
Приложение использует функцию SQLColumns, чтобы определить столбцы для табличного типа таким же образом, как и для хранимых таблиц, но до этого оно должно выставить SQL_SOPT_SS_NAME_SCOPE, чтобы указать на то, что оно работает с табличными типами, а не с существующими таблицами. Функцию SQLPrimaryKeys можно также использовать с табличными типами, опять же с помощью SQL_SOPT_SS_NAME_SCOPE.
Образец кода для этого сценария приведен в подпрограмме demo_metadata_from_catalog_APIs в разделе Использование возвращающих табличные значения параметров (ODBC).
Получение метаданных возвращающих табличное значение параметров для подготовленной инструкции
В этом сценарии приложение использует функции SQLNumParameters и SQLDescribeParam, чтобы получить метаданные для возвращающих табличное значение параметров.
IPD-поле атрибута SQL_CA_SS_TYPE_NAME используется для получения имени типа для возвращающего табличное значение параметра. IPD-поля атрибутов SQL_CA_SS_TYPE_SCHEMA_NAME и SQL_CA_SS_TYPE_CATALOG_NAME используются соответственно для получения каталога и схемы этого параметра.
Определения табличных типов и возвращающие табличное значение параметры должны находиться в одной базе данных. Функция SQLSetDescField сообщит об ошибке, если задан атрибут SQL_CA_SS_TYPE_CATALOG_NAME при использовании возвращающих табличное значение параметров.
Атрибуты SQL_CA_SS_TYPE_CATALOG_NAME и SQL_CA_SS_TYPE_SCHEMA_NAME могут также использоваться для получения каталога и схемы, связанных с параметрами определяемых пользователем типов данных CLR. Атрибуты SQL_CA_SS_TYPE_CATALOG_NAME и SQL_CA_SS_TYPE_SCHEMA_NAME представляют собой альтернативу существующим атрибутам типов в схеме каталогов для определяемых пользователем типов данных CLR.
Приложение также использует функцию SQLColumns для получения метаданных столбца возвращающего табличное значение параметра, так как функция SQLDescribeParam не возвращает метаданные столбцов для столбца возвращающего табличное значение параметра.
Образец кода для данного случая содержится в подпрограмме demo_metadata_from_prepared_statement в Использование возвращающих табличные значения параметров (ODBC).