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 函数 |