SQLDescribeParam

  • 项目

适用于：SQL ServerAzure SQL 数据库Azure SQL 托管实例Azure Synapse AnalyticsAnalytics Platform System (PDW)

为了描述任何 SQL 语句的参数，SQL Server Native Client ODBC 驱动程序在准备好的 ODBC 语句句柄上调用 SQLDescribeParam 时生成和执行 Transact-SQL 标准版LECT 语句。 结果集的元数据确定预定义语句中的参数的特征。 SQLDescribeParam 可以返回 SQLExecute 或 SQLExecDirect 可能返回的任何错误代码。

从 SQL Server 2012 （11.x） 开始，数据库引擎的改进使 SQLDescribeParam 能够获取预期结果的更准确说明。 这些更准确的结果可能与 SQL Server 早期版本中 SQLDescribeParam 返回的值不同。 有关详细信息，请参阅元数据发现。

在 SQL Server 2012（11.x）中，ParameterSizePtr 现在还返回一个值，该值与 ODBC 规范中定义的相应参数标记的列或表达式的大小（以字符为单位）对齐。 在早期版本的 SQL Server Native Client 中，ParameterSizePtr 可以是类型SQL_DESC_OCTET_LENGTH的对应值，也可以是提供给某个类型的 SQLBindParameter 的无关列大小值，应忽略其值（例如SQL_INTEGER）。

在以下情况下，驱动程序不支持调用 SQLDescribeParam：

  • 对于包含 FROM 子句的任何 Transact-SQL UPDATE 或 DELETE 语句，在 SQLExecDirect 之后。

  • 对于包含 HAVING 子句中的参数的任何 ODBC 或 Transact-SQL 语句，或与 SUM 函数的结果进行比较。

  • 对于任何 ODBC 或 Transact-SQL 语句，具体取决于包含参数的子查询。

  • 对于在比较和类似表达式中包含参数标记或包含限定谓词的 ODBC SQL 语句。

  • 对于其参数之一为函数参数的任何查询。

  • 当 Transact-SQL 命令中有注释 （/* */） 时。

在处理一批 Transact-SQL 语句时，驱动程序也不支持在批处理中的第一个语句之后对语句中的参数标记调用 SQLDescribeParam。

描述已准备存储过程的参数时，SQLDescribeParam 使用系统存储过程 sp_sproc_columns 来检索参数特征。 sp_sproc_columns可以报告当前用户数据库中存储过程的数据。 准备完全限定的存储过程名称允许 SQLDescribeParam 跨数据库执行。 例如，可以在任何数据库中准备和执行系统存储过程 sp_who ，如下所示：

SQLPrepare(hstmt, "{call sp_who(?)}", SQL_NTS);

成功准备后执行 SQLDescribeParam，在连接到任何数据库（但 master）时返回空行集。 按照如下所示准备的同一调用会导致 SQLDescribeParam 成功，而不考虑当前的用户数据库：

SQLPrepare(hstmt, "{call master..sp_who(?)}", SQL_NTS);

对于大型值数据类型，DataTypePtr 中返回的值SQL_VARCHAR、SQL_VARBINARY或SQL_NVARCHAR。 若要指示大型值数据类型参数的大小为“无限制”，SQL Server Native Client ODBC 驱动程序将 ParameterSizePtr 设置为 0。 标准 varchar 参数返回实际大小值。

注意

对于 SQL_VARCHAR、SQL_VARBINARY 或 SQL_WVARCHAR 参数，如果参数绑定有最大大小，则返回该参数的绑定大小，而非“无限制”。

若要绑定大小“无限制”的输入参数，必须使用执行时数据。 无法绑定“无限制”大小的输出参数（没有从输出参数流式处理数据的方法，如 SQLGetData 对结果集所做的）。

对于输出参数，必须绑定一个缓冲区，如果值过大，则填充此缓冲区，并返回 SQL_SUCCESS_WITH_INFO 消息和“字符串数据；右端被截断”的警告。 随后将放弃截断的数据。

SQLDescribeParam 和表值函数

应用程序可以使用 SQLDescribeParam 检索已准备语句的表值参数信息。 有关详细信息，请参阅 已准备语句的表值参数元数据。

有关表值参数的详细信息，请参阅表值参数（ODBC）。

SQLDescribeParam 对日期和时间增强功能的支持

日期/时间类型返回以下值：

Attribute DataTypePtr ParameterSizePtr DecimalDigitsPtr
datetime SQL_TYPE_TIMESTAMP 23 3
smalldatetime SQL_TYPE_TIMESTAMP 16 0
date SQL_TYPE_DATE 10 0
time SQL_SS_TIME2 8, 10..16 0..7
datetime2 SQL_TYPE_TIMESTAMP 19、21..27 0..7
datetimeoffset SQL_SS_TIMESTAMPOFFSET 26、28..34 0..7

有关详细信息，请参阅日期和时间改进（ODBC）。

SQLDescribeParam 对大型 CLR UDT 的支持

SQLDescribeParam 支持大型 CLR 用户定义类型（UDT）。 有关详细信息，请参阅大型 CLR 用户定义的类型（ODBC）。

另请参阅

SQLDescribeParam 函数
ODBC API 实现细节