SQLPrepare 函数
一致性
引入的版本:ODBC 1.0 标准符合性:ISO 92
摘要
SQLPrepare 准备要执行的 SQL 字符串。
语法
SQLRETURN SQLPrepare(
SQLHSTMT StatementHandle,
SQLCHAR * StatementText,
SQLINTEGER TextLength);
参数
StatementHandle
[输入]语句句柄。
StatementText
[输入]SQL 文本字符串。
TextLength
[输入]*StatementText 的长度(以字符为单位)。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLPrepare 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值,该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT, 句柄 为 StatementHandle。 下表列出了 SQLPrepare 通常返回的 SQLSTATE 值,并说明了此函数上下文中的每个值:表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR,除非另有说明。
SQLSTATE | 错误 | 说明 |
---|---|---|
01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
01S02 | 选项值已更改 | 由于实现工作条件,指定的语句属性无效,因此暂时替换了类似的值。 (可以调用 SQLGetStmtAttr 来确定临时替换的值是什么。) 在关闭游标之前,替换值对 StatementHandle 有效。 可以更改的语句属性为:SQL_ATTR_CONCURRENCY SQL_ATTR_CURSOR_TYPE SQL_ATTR_KEYSET_SIZE SQL_ATTR_MAX_LENGTH SQL_ATTR_MAX_ROWS SQL_ATTR_QUERY_TIMEOUT SQL_ATTR_SIMULATE_CURSOR (函数返回 SQL_SUCCESS_WITH_INFO.) |
08S01 | 通信链接失败 | 在函数完成处理之前,驱动程序与驱动程序连接到的数据源之间的通信链接失败。 |
21S01 | 插入值列表与列列表不匹配 | *StatementText 包含 INSERT 语句,要插入的值数与派生表的度数不匹配。 |
21S02 | 派生表的程度与列列表不匹配 | *StatementText 包含 CREATE VIEW 语句,并且指定的名称数与查询规范定义的派生表不同。 |
22018 | 强制转换规范的字符值无效 | *StatementText 包含包含文本或参数的 SQL 语句,并且该值与关联的表列的数据类型不兼容。 |
22019 | 转义字符无效 | 参数 StatementText 在 WHERE 子句中包含一个带有 ESCAPE 的 LIKE 谓词,而 ESCAPE 后面的转义字符的长度不等于 1。 |
22025 | 转义序列无效 | 参数 StatementText 在 WHERE 子句中包含“LIKE模式值ESCAPE转义字符”,并且模式值中转义字符后面的字符既不是“%”也不是“_”。 |
24000 | 游标状态无效 | (DM) StatementHandle 上打开了游标,并且调用了 SQLFetch 或 SQLFetchScroll 。 在 StatementHandle 上打开了游标,但尚未调用 SQLFetch 或 SQLFetchScroll。 |
34000 | 游标名称无效 | *StatementText 包含定位的 DELETE 或定位的 UPDATE,并且正在准备的语句引用的游标未打开。 |
3D000 | 目录名称无效 | StatementText 中指定的目录名称无效。 |
3F000 | 架构名称无效 | StatementText 中指定的架构名称无效。 |
42000 | 语法错误或访问冲突 | *StatementText 包含不可准备的 SQL 语句或包含语法错误。 *StatementText 包含用户没有所需权限的语句。 |
42S01 | 基表或视图已存在 | *StatementText 包含 CREATE TABLE 或 CREATE VIEW 语句,并且指定的表名或视图名称已存在。 |
42S02 | 找不到基表或视图 | *StatementText 包含 DROP TABLE 或 DROP VIEW 语句,并且指定的表名或视图名称不存在。 *StatementText 包含 ALTER TABLE 语句,并且指定的表名称不存在。 *StatementText 包含 CREATE VIEW 语句,并且查询规范定义的表名或视图名称不存在。 *StatementText 包含 CREATE INDEX 语句,并且指定的表名称不存在。 *StatementText 包含 GRANT 或 REVOKE 语句,并且指定的表名或视图名称不存在。 *StatementText 包含 SELECT 语句,并且指定的表名或视图名称不存在。 *StatementText 包含 DELETE、 INSERT 或 UPDATE 语句,并且指定的表名称不存在。 *StatementText 包含 CREATE TABLE 语句,并在约束中指定的表 (引用所创建的表) 不存在。 |
42S11 | 索引已存在 | *StatementText 包含 CREATE INDEX 语句,并且指定的索引名称已存在。 |
42S12 | 找不到索引 | *StatementText 包含 DROP INDEX 语句,并且指定的索引名称不存在。 |
42S21 | 列已存在 | *StatementText 包含 ALTER TABLE 语句, ADD 子句中指定的列不唯一或标识基表中的现有列。 |
42S22 | 找不到列 | *StatementText 包含 CREATE INDEX 语句,列列表中指定的一个或多个列名称不存在。 *StatementText 包含 GRANT 或 REVOKE 语句,并且指定的列名不存在。 *StatementText 包含 SELECT、 DELETE、 INSERT 或 UPDATE 语句,并且指定的列名不存在。 *StatementText 包含 CREATE TABLE 语句,并在约束中指定的列 (引用所创建的表) 不存在。 |
HY000 | 常规错误 | 发生错误,其中没有特定的 SQLSTATE,并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。 |
HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
HY008 | 操作已取消 | 已为 StatementHandle 启用异步处理。 调用了函数,在它完成执行之前,在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle,然后在 StatementHandle 上再次调用该函数。 函数已调用,在它完成执行之前, SQLCancel 或 SQLCancelHandle 是从多线程应用程序中的不同线程在 StatementHandle 上调用的。 |
HY009 | null 指针的使用无效 | (DM) StatementText 是空指针。 |
HY010 | 函数序列错误 | (DM) 为 与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLPrepare 函数时,此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。 (DM) 为 StatementHandle 调用了异步执行的函数 (不是此函数) ,并且调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行时参数或列发送数据之前调用了此函数。 |
HY013 | 内存管理错误 | 无法处理函数调用,因为无法访问基础内存对象,可能是因为内存不足。 |
HY090 | 无效的字符串或缓冲区长度 | (DM) 参数 TextLength 小于或等于 0 但不等于 SQL_NTS。 |
HY117 | 由于未知的事务状态,连接已挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息,请参阅 SQLEndTran 函数。 |
HYC00 | 未实现可选功能 | 并发设置对于定义的游标类型无效。 SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_VARIABLE,SQL_ATTR_CURSOR_TYPE 语句属性设置为驱动程序不支持书签的游标类型。 |
HYT00 | 超时时间已到 | 在数据源返回结果集之前,超时期限已过期。 超时期限是通过 SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT设置的。 |
HYT01 | 超过连接超时时间 | 在数据源响应请求之前,连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。 |
IM001 | 驱动程序不支持此函数 | (DM) 与 StatementHandle 关联的驱动程序不支持 函数。 |
IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时,轮询都将被禁用。 |
IM018 | 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 | 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式,则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。 |
注释
应用程序调用 SQLPrepare 将 SQL 语句发送到数据源进行准备。 有关准备好的执行的详细信息,请参阅 准备的执行。 应用程序可以在 SQL 语句中包含一个或多个参数标记。 若要包含参数标记,应用程序会将问号 (?) 嵌入 SQL 字符串中的相应位置。 有关参数的信息,请参阅 语句参数。
注意
如果应用程序使用 SQLPrepare 来准备和 SQLExecute 提交 COMMIT 或 ROLLBACK 语句,则它将无法在 DBMS 产品之间互操作。 若要提交或回滚事务,请调用 SQLEndTran。
驱动程序可以修改 语句以使用数据源使用的 SQL 格式,然后将其提交到数据源进行准备。 具体而言,驱动程序修改用于为某些功能定义 SQL 语法的转义序列。 (有关 SQL 语句语法的说明,请参阅 ODBC 中的转义序列 和 附录 C:SQL Grammar.) 对于驱动程序,语句句柄类似于嵌入式 SQL 代码中的语句标识符。 如果数据源支持语句标识符,驱动程序可以将语句标识符和参数值发送到数据源。
准备语句后,应用程序在以后的函数调用中使用 语句句柄来引用语句。 可以通过调用 SQLExecute 来重新执行与语句句柄关联的已准备语句,直到应用程序使用 SQL_DROP 选项调用 SQLFreeStmt 释放语句,或者直到在调用 SQLPrepare、 SQLExecDirect 或 (SQLColumns、 SQLTables 等) 的某个目录函数中使用语句句柄。 应用程序准备语句后,可以请求有关结果集格式的信息。 对于某些实现,在 SQLPrepare 之后调用 SQLDescribeCol 或 SQLDescribeParam 可能不如在 SQLExecute 或 SQLExecDirect 之后调用函数的效率。
当应用程序调用 SQLPrepare 时,某些驱动程序无法返回语法错误或访问冲突。 驱动程序可以处理语法错误和访问冲突、仅语法错误或语法错误和访问冲突。 因此,在调用后续相关函数(例如 SQLNumResultCols、 SQLDescribeCol、 SQLColAttribute 和 SQLExecute)时,应用程序必须能够处理这些条件。
根据驱动程序和数据源的功能,在准备语句时,可能会检查参数 (信息(如数据类型) ) ((如果所有参数都已绑定) )或执行 ((如果尚未绑定所有参数) )。 为了最大程度地实现互操作性,应用程序应取消绑定应用于旧 SQL 语句的所有参数,然后再在同一语句上准备新的 SQL 语句。 这可以防止由于将旧参数信息应用于新语句而导致的错误。
重要
通过显式调用 SQLEndTran 或在自动提交模式下提交事务,都可能导致数据源删除连接上所有语句的访问计划。 有关详细信息,请参阅 SQLGetInfo 中的SQL_CURSOR_COMMIT_BEHAVIOR和SQL_CURSOR_ROLLBACK_BEHAVIOR信息类型以及 事务对游标和已准备语句的影响。
代码示例
请参阅 SQLBindParameter、 SQLPutData 和 SQLSetPos。
相关函数
有关以下方面的信息 | 请参阅 |
---|---|
分配语句句柄 | SQLAllocHandle 函数 |
将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
将缓冲区绑定到参数 | SQLBindParameter 函数 |
取消语句处理 | SQLCancel 函数 |
执行提交或回滚操作 | SQLEndTran 函数 |
执行 SQL 语句 | SQLExecDirect 函数 |
执行准备好的 SQL 语句 | SQLExecute 函数 |
返回受 语句影响的行数 | SQLRowCount Function(SQLRowCount 函数) |
设置游标名称 | SQLSetCursorName 函数 |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈