Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
В этом разделе рассматриваются сценарии основного пользователя для использования параметров с табличным значением с ODBC:
параметр Table-Valued с полностью привязанными многороувными буферами (отправка данных в виде TVP со всеми значениями в памяти)
параметр Table-Valued с потоковой передачей строк (отправка данных в виде TVP с помощьюAt-Executionданных)
Получение метаданных параметра Table-Valued из системного каталога
Получение метаданных параметра Table-Valued для подготовленной инструкции
параметр Table-Valued с полностью привязанными многороувными буферами (отправка данных в виде TVP со всеми значениями в памяти)
При использовании с полностью привязанными многороувными буферами все значения параметров доступны в памяти. Это обычно, например, транзакции OLTP, в которой табличное значение параметров можно упаковываться в одну хранимую процедуру. Без табличных параметров это приведет к динамическому созданию сложного пакета с несколькими операторами или выполнению нескольких вызовов к серверу.
Сам параметр с табличным значением привязан с помощью SQLBindParameter вместе с другими параметрами. После привязки всех параметров приложение задает атрибут фокуса параметра SQL_SOPT_SS_PARAM_FOCUS для каждого табличного параметра и вызывает SQLBindParameter для столбцов табличного параметра.
Тип сервера для табличного параметра — это новый тип SQL Server, SQL_SS_TABLE. Тип привязки C для SQL_SS_TABLE всегда должен быть SQL_C_DEFAULT. Данные не передаются для привязанного параметра с табличным значением; он используется для передачи метаданных таблицы и управления передачей данных в составных столбцах табличного параметра.
Длина табличного параметра определяется количеством строк, отправляемых на сервер. Параметр ColumnSize sqlBindParameter для табличного параметра указывает максимальное количество строк, которые можно отправить; это размер массива буферов столбцов. ParameterValuePtr — это буфер параметров для табличного параметра в SQLBindParameter. ПараметрValuePtr и связанный с ним 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использования Table-Valued параметров (ODBC).
параметр Table-Valued с потоковой передачей строк (отправка данных в виде TVP с помощьюAt-Executionданных)
В этом сценарии приложение предоставляет строки драйверу по мере их запроса, и они передаются на сервер. Это позволяет избежать необходимости буферизации всех строк в памяти. Это является представителем сценариев массового вставки и обновления. Параметры с табличным значением предоставляют точку производительности где-то между массивами параметров и массовой копией. То есть табличное значение параметров примерно так же легко программировать, как массивы параметров, но обеспечивают большую гибкость на сервере.
Параметр с табличным значением и его столбцы привязаны, как описано в предыдущем разделе, Table-Valued параметр с полностью привязанными буферами multirow, но для индикатора длины самого табличного параметра задано значение 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).
Получение метаданных параметра Table-Valued из системного каталога
Когда приложение вызывает 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использования Table-Valued параметров (ODBC).
Получение метаданных параметра Table-Valued для подготовленной инструкции
В этом сценарии приложение использует 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 в разделе "Использование Table-Valued параметров (ODBC)".