SQLParamData 函数

  • 项目

一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92

摘要
SQLParamData 与 SQLPutData 一起使用，用于在语句执行时提供参数数据，并与 SQLGetData 一起使用以检索流式输出参数数据。

语法

  
SQLRETURN SQLParamData(  
     SQLHSTMT       StatementHandle,  
     SQLPOINTER *   ValuePtrPtr);

参数

StatementHandle
[输入]语句句柄。

ValuePtrPtr
[输出]指向缓冲区的指针，该缓冲区将返回 SQLBindParameter (中指定的 ParameterValuePtr 缓冲区的地址，该地址用于参数数据) ，或者在 SQLBindCol (中为列数据) 指定的 TargetValuePtr 缓冲区的地址，如SQL_DESC_DATA_PTR描述符记录字段中所示。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_NO_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_INVALID_HANDLE或SQL_PARAM_DATA_AVAILABLE。

诊断

当 SQLParamData 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT， 句柄 为 StatementHandle。 下表列出了通常由 SQLParamData 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
07006 受限数据类型属性冲突 无法将绑定参数的 SQLBindParameter 中的 ValueType 参数标识的数据值转换为 SQLBindParameter 中的 ParameterType 参数标识的数据类型。

为绑定为 SQL_PARAM_INPUT_OUTPUT 或 SQL_PARAM_OUTPUT 的参数返回的数据值无法转换为由 SQLBindParameter 中的 ValueType 参数标识的数据类型。

(如果无法转换一行或多行的数据值，但成功返回一行或多行，此函数将返回SQL_SUCCESS_WITH_INFO.)
08S01 通信链接失败 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。
22026 字符串数据，长度不匹配 SQLGetInfo 中的SQL_NEED_LONG_DATA_LEN信息类型为“Y”， (数据类型SQL_LONGVARCHAR、SQL_LONGVARBINARY或特定于数据源的长数据类型) 比使用 SQLBindParameter 中的 StrLen_or_IndPtr 参数指定的数据更少。

SQLGetInfo 中的SQL_NEED_LONG_DATA_LEN信息类型为“Y”，并且为长列发送的数据较少， (数据类型SQL_LONGVARCHAR、SQL_LONGVARBINARY或特定于长数据源的数据类型) ，而不是使用 SQLBulkOperations 添加或更新或使用 SQLSetPos 更新的数据行中与列对应的长度缓冲区中指定的数据。
40001 序列化失败 由于与另一个事务发生资源死锁，事务已回滚。
40003 语句完成未知 关联的连接在执行此函数期间失败，并且无法确定事务的状态。
HY000 常规错误 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY008 操作已取消 已为 StatementHandle 启用异步处理。 调用了函数，在它完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle; 然后，在 StatementHandle 上再次调用 函数。

函数已调用，在它完成执行之前， SQLCancel 或 SQLCancelHandle 是从多线程应用程序中的不同线程在 StatementHandle 上调用的。
HY010 函数序列错误 (DM) 上一个函数调用不是对 sqlExecDirect、 SQLExecute、 SQLBulkOperations 或 SQLSetPos 的调用，其中返回代码SQL_NEED_DATA，或者上一个函数调用是对 SQLPutData 的调用。

上一个函数调用是对 SQLParamData 的调用。

(DM) 为 与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLParamData 函数时，此异步函数仍在执行。

(DM) 为 StatementHandle 调用了异步执行的函数 (不是此函数) ，并且调用此函数时仍在执行。

已为 StatementHandle 调用 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回SQL_NEED_DATA。 SQLCancel 是在为所有数据执行时参数或列发送数据之前调用的。
HY013 内存管理错误 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。
HY117 由于未知的事务状态，连接已挂起。 仅允许断开连接和只读函数。 (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYT01 超过连接超时时间 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。
IM001 驱动程序不支持此函数 (DM) 对应于 StatementHandle 的 驱动程序不支持 函数。
IM017 在异步通知模式下禁用轮询 每当使用通知模型时，轮询都将被禁用。
IM018 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式，则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。

如果在 SQL 语句中为参数发送数据时调用 SQLParamData，它可以返回可由调用的函数返回的任何 SQLSTATE，以执行 sqlExecute 或 SQLExecDirect) (语句。 如果在为使用 SQLBulkOperations 更新或添加的列发送数据或使用 SQLSetPos 更新时调用它，它可以返回可由 SQLBulkOperations 或 SQLSetPos 返回的任何 SQLSTATE。

注释

可以调用 SQLParamData 来提供用于两种用途的执行数据：将在调用 SQLExecute 或 SQLExecDirect 时使用的参数数据，或者在调用 SQLBulkOperations 或通过调用 SQLSetPos 更新行或添加行时将使用的列数据。 在执行时， SQLParamData 会向应用程序返回驱动程序所需的数据的指示器。

当应用程序调用 SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 时，如果驱动程序需要执行时的数据，则返回SQL_NEED_DATA。 然后，应用程序调用 SQLParamData 来确定要发送的数据。 如果驱动程序需要参数数据，驱动程序将在 *ValuePtrPtrPtr 输出缓冲区中返回应用程序放入行集缓冲区中的值。 应用程序可以使用此值来确定驱动程序请求的参数数据。 如果驱动程序需要列数据，驱动程序将在 *ValuePtrPtrPtr 缓冲区中返回列最初绑定到的地址，如下所示：

绑定地址 + 绑定偏移量 + ( (行号 - 1) x 元素大小)

其中，定义变量，如下表所示。

变量 说明
绑定地址 在 SQLBindCol 中使用 TargetValuePtr 参数指定的地址。
绑定偏移量 存储在使用 SQL_ATTR_ROW_BIND_OFFSET_PTR 语句属性指定的地址处的值。
Row Number 行集中行的从 1 开始的行号。 对于默认的单行提取，这是 1。
元素大小 数据和长度/指示器缓冲区的 SQL_ATTR_ROW_BIND_TYPE 语句属性的值。

它还返回SQL_NEED_DATA，指示应用程序应调用 SQLPutData 来发送数据。

应用程序根据需要多次调用 SQLPutData ，以发送列或参数的执行时数据。 为列或参数发送所有数据后，应用程序将再次调用 SQLParamData 。 如果 SQLParamData 再次返回SQL_NEED_DATA，则必须为另一个参数或列发送数据。 因此，应用程序再次调用 SQLPutData。 如果已为所有参数或列发送所有执行数据，则 SQLParamData 返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO， 则 ValuePtrPtr 中的 值未定义，可以执行 SQL 语句，或者可以处理 SQLBulkOperations 或 SQLSetPos 调用。

如果 SQLParamData 为搜索的更新或删除语句提供参数数据，而该语句不会影响数据源中的任何行，则对 SQLParamData 的调用将返回SQL_NO_DATA。

有关如何在语句执行时传递执行时参数数据的详细信息，请参阅 SQLBindParameter 和 发送长数据中的“传递参数值”。 有关如何更新或添加执行时数据列数据的详细信息，请参阅 SQLSetPos 中的“使用 SQLSetPos”部分、SQLBulkOperations 中的“使用书签执行批量汇报”以及 Long Data 和 SQLSetPos 和 SQLBulkOperations 部分。

可以调用 SQLParamData 来检索流式输出参数。 当 SQLMoreResults、 SQLExecute、 SQLGetData 或 SQLExecDirect 返回SQL_PARAM_DATA_AVAILABLE时，请调用 SQLParamData 以确定哪个参数具有可用的值。 有关SQL_PARAM_DATA_AVAILABLE和流输出参数的详细信息，请参阅 使用 SQLGetData 检索输出参数。

代码示例

请参阅 SQLPutData。

有关以下方面的信息 请参阅
将缓冲区绑定到参数 SQLBindParameter 函数
取消语句处理 SQLCancel 函数
返回语句中有关参数的信息 SQLDescribeParam 函数
执行 SQL 语句 SQLExecDirect 函数
执行准备好的 SQL 语句 SQLExecute 函数
在执行时发送参数数据 SQLPutData 函数

另请参阅

ODBC API 参考
ODBC 头文件
使用 SQLGetData 检索输出参数