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时，可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLParamData 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 07006 | 受限数据类型属性冲突 | 无法将绑定参数的 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 的调用中使用的参数数据，或调用 SQLSetPos 时将使用的行或通过调用 SQLBulkOperations 或更新的列数据。 在执行时， SQLParamData 返回到应用程序，指示驱动程序需要哪些数据。
当应用程序调用 SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 时，如果驱动程序需要执行数据，驱动程序将返回SQL_NEED_DATA。 然后，应用程序调用 SQLParamData 来确定要发送的数据。 如果驱动程序需要参数数据，驱动程序在 *ValuePtrPtr 输出缓冲区中返回应用程序放入行集缓冲区的值。 应用程序可以使用此值来确定驱动程序请求的参数数据。 如果驱动程序需要列数据，驱动程序在 *ValuePtrPtr 缓冲区中返回该列最初绑定到的地址，如下所示：
绑定地址 + 绑定偏移量 + （（行号 - 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 函数 |