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

  • Статья

Применимо к: SQL Server Azure SQL DatabaseУправляемый экземпляр SQL AzureAzure Synapse AnalyticsAnalytics 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Использование Table-Valued параметров (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Использование параметров Table-Valued (ODBC).

Получение метаданных возвращающих табличное значение параметров из системного каталога

Когда приложение вызывает SQLProcedureColumns для процедуры с возвращающими табличное значение параметрами, DATA_TYPE возвращается в виде SQL_SS_TABLE а TYPE_NAME — имя типа таблицы для возвращающего табличное значение параметра. В результирующий набор, возвращаемый SQLProcedureColumns, добавляются два дополнительных столбца: SS_TYPE_CATALOG_NAME возвращает имя каталога, в котором определен тип таблицы параметра table-value, и SS_TYPE_SCHEMA_NAME возвращает имя схемы, в которой определен тип таблицы параметра table-value. В соответствии со спецификацией ODBC SS_TYPE_CATALOG_NAME и SS_TYPE_SCHEMA_NAME отображаться перед всеми столбцами драйвера, добавленными в предыдущих версиях SQL Server, и после всех столбцов, обязательных для самого ODBC.

Новые столбцы будут заполнены не только для возвращающих табличное значение параметров, но и для параметров определенного пользователем типа данных CLR. Существующие схема и столбцы каталога параметров определяемого пользователем типа будут все равно заполнены, но наличие общих схемы и столбцов каталога для типов данных, для которых они требуются, упростит разработку приложения в будущем. (Следует отметить, что коллекции схем XML несколько отличаются и не включаются в это изменение).

Приложение использует SQLTable для определения имен типов таблиц так же, как и для постоянных таблиц, системных таблиц и представлений. Новый табличный тип 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Использование параметров Table-Valued (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в разделе Использование параметров Table-Valued (ODBC).

См. также:

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