大网数据广告活动
数据库与应用安全

绑定及数据传输的表值参数和列值

· 52CE 我爱测

与其他参数类似,表值参数在传递到服务器之前必须进行绑定。 应用程序绑定表值参数绑定其他参数的相同方式: 通过使用 SQLBindParameter 或 SQLSetDescField 或 SQLSetDescRec 等效调用。 表值参数的服务器数据类型为 SQL_SS_TABLE。 C 类型可以指定为 SQL_C_DEFAULT 或 SQL_C_BINARY。

适用对象:yesSQL ServeryesAzure SQL 数据库yesAzure SQL 数据仓库yes并行数据仓库

与其他参数类似,表值参数在传递到服务器之前必须进行绑定。 应用程序绑定表值参数绑定其他参数的相同方式: 通过使用 SQLBindParameter 或 SQLSetDescField 或 SQLSetDescRec 等效调用。 表值参数的服务器数据类型为 SQL_SS_TABLE。 C 类型可以指定为 SQL_C_DEFAULT 或 SQL_C_BINARY。

在 SQL Server 2008 或更高版本中,只支持输入表值参数。 因此,任何将 SQL_DESC_PARAMETER_TYPE 设置为 SQL_PARAM_INPUT 之外的值的尝试,都将返回具有 SQLSTATE = HY105 和消息“参数类型无效”的 SQL_ERROR。

可使用属性 SQL_CA_SS_COL_HAS_DEFAULT_VALUE 为整个表值参数列分配默认值。 单个表值参数列的值,但是,不能分配默认值通过使用在 SQL_DEFAULT_PARAM StrLen_or_IndPtr SQLBindParameter 使用。 通过使用 SQL_DEFAULT_PARAM 中的,不能作为一个整体的表值参数设置为默认值StrLen_or_IndPtr SQLBindParameter 使用。 如果未遵循这些规则,SQLExecute 或 SQLExecDirect 将返回 SQL_ERROR。 诊断记录将生成具有 SQLSTATE = 07S01 和消息"的默认参数的参数使用无效",其中\ 为 TVP 在查询语句中的序号。

绑定表值参数之后,应用程序随后必须绑定每个表值参数列。 若要执行此操作,该应用程序首先调用 SQLSetStmtAttr 将 SQL_SOPT_SS_PARAM_FOCUS 设置为表值参数的序号。 然后该应用程序将通过调用以下例程绑定表值参数的列: SQLBindParameter、 SQLSetDescRec 和 SQLSetDescField。 将 SQL_SOPT_SS_PARAM_FOCUS 设置为 0 可还原的常见效果 SQLBindParameter、 SQLSetDescRec 和 SQLSetDescField 对常规顶级参数中。

注意: 对于 unixODBC 2.3.1 到 2.3.4,设置通过 SQLSetDescField SQL_CA_SS_TYPE_NAME 描述符字段的 TVP 名称时使用 Linux 和 Mac ODBC 驱动程序,unixODBC 不会自动转换 ANSI 和 Unicode 之间具体取决于确切的字符串调用的函数 (SQLSetDescFieldA / SQLSetDescFieldW)。 很有必要为始终使用 SQLBindParameter 或 SQLSetDescFieldW 使用 Unicode (utf-16) 字符串设置 TVP 名称。

对于表值参数本身而言,并未发送或接收实际数据,但对于表值参数的每个构成列而言,发送和接收了数据。 由于表值参数是伪列,因此将使用 SQLBindParameter 的参数,如下所示为不同的属性比其他数据类型,请参阅:

参数 非表值参数类型的相关属性,包括列 表值参数的相关属性
InputOutputType IPD 中的 SQL_DESC_PARAMETER_TYPE。 对于表值参数列,此属性设置必须与表值参数自身的设置相同。 IPD 中的 SQL_DESC_PARAMETER_TYPE。 此属性必须为 SQL_PARAM_INPUT。
ValueType APD 中的 SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE。 APD 中的 SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE。 此属性必须为 SQL_C_DEFAULT 或 SQL_C_BINARY。
ParameterType IPD 中的 SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE。 IPD 中的 SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE。 此属性必须为 SQL_SS_TABLE。
ColumnSize IPD 中的 SQL_DESC_LENGTH 或 SQL_DESC_PRECISION。 这取决于值ParameterType。 SQL_DESC_ARRAY_SIZE 当参数焦点设置为表值参数时,也可以使用 SQL_ATTR_PARAM_SET_SIZE 进行设置。 对于表值参数,此属性为表值参数列缓冲区内的行数。
DecimalDigits IPD 中的 SQL_DESC_PRECISION 或 SQL_DESC_SCALE。 未使用。 此属性必须为 0。 如果此参数为不 0,SQLBindParameter 将返回 SQL_ERROR,并且诊断记录将生成具有 SQLSTATE = HY104 和消息"无效的精度或小数位数"。
ParameterValuePtr APD 中的 SQL_DESC_DATA_PTR。 SQL_CA_SS_TYPE_NAME。 此属性对于存储过程调用为可选的,并且如果不需要可以指定为 NULL。 对于非过程调用的 SQL 语句,必须指定此属性。 在使用可变行绑定时,此参数还可作为应用程序用于标识该表值参数的唯一值。 有关详细信息,请参阅本主题后面的“可变表值参数行绑定”部分。 当在 SQLBindParameter 调用指定表值参数类型名称时,它必须指定为 Unicode 值,即使在作为 ANSI 应用程序生成的应用程序。 用于参数的值StrLen_or_IndPtr应为 SQL_NTS 或乘以 sizeof (wchar) 的名称的字符串长度。
BufferLength APD 中的 SQL_DESC_OCTET_LENGTH。 表值参数类型名称的长度(以字节为单位)。 如果类型名称为以 NULL 值结束,则它可以是 SQL_NTS;如果不需要表值参数类型名称,则为 0。
StrLen_or_IndPtr APD 中的 SQL_DESC_OCTET_LENGTH_PTR。 APD 中的 SQL_DESC_OCTET_LENGTH_PTR。 对于表值参数,此属性为行计数,而非数据长度。

表值参数支持两种数据传输模式:固定行绑定和可变行绑定。

固定表值参数行绑定

在固定行绑定模式中,应用程序会分配足以容纳所有可能的输入列值的缓冲区(或缓冲区数组)。 应用程序执行以下操作:

  1. 通过使用 SQLBindParameter、 SQLSetDescRec 或 SQLSetDescField 调用绑定所有参数。

    1. 将 SQL_DESC_ARRAY_SIZE 设置为每个表值参数所能传输的最大行数。 这可以在 SQLBindParameter 调用中。
  2. 调用 SQLSetStmtAttr 将 SQL_SOPT_SS_PARAM_FOCUS 设置为每个表值参数的序号。

    1. 每个表值参数,通过使用 SQLBindParameter、 SQLSetDescRec 或 SQLSetDescField 调用绑定表值参数列。

    2. 对于具有默认值是每个表值参数列,都会调用 SQLSetDescField 将 sql_ca_ss_col_has_default_value 设置为 1。

  3. 调用 SQLSetStmtAttr 将 SQL_SOPT_SS_PARAM_FOCUS 设置为 0。 SQLExecute 之前必须进行此类也称为 SQLExecDirect。 否则,将返回 SQL_ERROR,且生成具有 SQLSTATE=HY024 和消息“属性值 SQL_SOPT_SS_PARAM_FOCUS 无效(执行时必须为零)”的诊断记录。

  4. 集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 (尽管表值参数构成列可以为 null)。 如果此值设置为无效值,SQLExecute 或 SQLExecDirect 返回 SQL_ERROR,并诊断记录生成具有 SQLSTATE = HY090 和消息"参数的字符串或缓冲区长度无效",其中 p 是参数数目。

  5. 调用 SQLExecute 或 SQLExecDirect。

输入表值参数列值可以分块传递,是否StrLen_or_IndPtr设置为 SQL_LEN_DATA_AT_EXEC (长度) 或 sql_data_at_exec,那么列。 这类似于使用参数数组时的分块传递值。 因为所有执行时数据参数,使用 SQLParamData 不指示数组的哪一行驱动程序正在请求数据;这必须处理应用程序。 应用程序不能对驱动程序将请求值的顺序做出任何假设。

可变表值参数行绑定

在可变行绑定模式中,行在执行时进行批量传输,且应用程序根据需要将行传递给驱动程序。 这类似于单个参数值的执行时数据。 对于可变行绑定,应用程序执行以下操作:

  1. 按照上一部分“固定表值参数行绑定”中的步骤 1 到 3 所述,绑定参数和表值参数列。

  2. 集StrLen_or_IndPtr或 SQL_DESC_OCTET_LENGTH_PTR 所要在执行时传递给 SQL_DATA_AT_EXEC 的任何表值参数。 如果未设置这两个参数,则将按照上一部分中所述步骤处理参数。

  3. 调用 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 中,可被视作用于唯一地标识为其值是必需的参数的令牌。 此“标记”在绑定时从应用程序传递给驱动程序,在执行时传递回应用程序。
  4. 若要发送 null 表值参数的表值参数行数据,如果表值参数不的任何行,应用程序调用使用 SQLPutData StrLen_or_Ind设置为 SQL_DEFAULT_PARAM。

    对于非 Null TVP,应用程序会:

    • 集Str_Len_or_Ind为适当的值的所有表值参数列,并填充表值参数列不是执行时数据参数的数据缓冲区。 可以采用类似于将普通参数分块传递给驱动程序的方式,使用表值参数列的执行时数据。

    • 调用与 SQLPutData Str_Len_or_Ind设置为行数,以发送到服务器。 范围 0 到 SQL_DESC_ARRAY_SIZE 或 SQL_DEFAULT_PARAM 以外的任何值都将生成错误,并将返回 SQLSTATE HY090 和消息“字符串或缓冲区长度无效”。 0 表示已发送所有行,已不存在任何表值参数数据(如本列表的第二个项目符号项中所述)。 只有在驱动程序第一次请求表值参数数据时,才能使用 SQL_DEFAULT_PARAM(如本列表的第二个项目符号项中所述)。

  5. 在发送所有行后,使用表值参数调用 SQLPutData Str_Len_or_Ind值为 0,然后继续执行上述步骤 3a。

  6. 会再次调用 SQLParamData。 如果表值参数列之间的任何执行时数据参数,这些将能识别的值ValuePtrPtr SQLParamData 返回。 所有列的值可用时,将再次返回 SQLParamData ParameterValuePtr表值参数和应用程序的值将重新开始。

请参阅

表值参数(ODBC)

历史资料。此文对应 2018-11-30 的中文文档快照,适用产品版本和命令行为以原文为准。

来源与署名:Microsoft 和文档贡献者(原始作者元数据 MightyPen)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站展开固定版本仓库内的引用内容,将 Markdown 转为 HTML,规范化链接,移除外部媒体、发布器占位标签和导航标记。

资料来源与适用范围

资料来源
Microsoft / SQL Server 中文文档历史快照
适用范围
历史中文快照 2018-11-30;详见原文产品版本;文档日期 04/04/2017
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0(文档)/ MIT(示例代码)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。