Сценарии использования возвращающих табличное значение параметров ODBC

Применимо: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure azure Synapse Analytics Analytics Platform System (PDW)

В данном разделе обсуждаются основные пользовательские сценарии для использования возвращающих табличное значение параметров 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_SCHEMA_NAME необходимо задать с помощью SQLSetDescField. Так как определения типов таблиц и табличное значение параметров должны находиться в одной базе данных, SQL_CA_SS_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_SCHEMA_NAME и SQL_CA_SS_CATALOG_NAME используются для получения каталога и схемы соответственно.

Определения табличных типов и возвращающие табличное значение параметры должны находиться в одной базе данных. SQLSetDescField сообщает об ошибке, если приложение задает SQL_CA_SS_CATALOG_NAME при использовании параметров с табличным значением.

SQL_CA_SS_CATALOG_NAME и SQL_CA_SS_SCHEMA_NAME также можно использовать для получения каталога и схемы, связанной с параметрами определяемого пользователем типа CLR. SQL_CA_SS_CATALOG_NAME и SQL_CA_SS_SCHEMA_NAME являются альтернативами существующим атрибутам схемы каталога для типов определяемых пользователем типов CLR.

Приложение использует SQLColumns для получения метаданных столбцов для параметра с табличным значением в этом сценарии, так как SQLDescribeParam не возвращает метаданные для столбцов столбца столбца с табличным значением параметра.

Пример кода для этого варианта использования находится в подпрограмме demo_metadata_from_prepared_statement в разделе Use Table-Valued Parameters (ODBC).

См. также

Возвращающие табличные значения параметры (ODBC)