符合性
版本引入了: 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,关联的 SQLSTATE 值可以通过调用来获取SQLGetDiagRec与HandleType的 SQL_HANDLE_STMT 和一个处理的StatementHandle。 下表列出了通常返回的 SQLSTATE 值SQLPrepare ,并解释了此函数; 每个上下文中的表示法"(数据挖掘)"之前 SQLSTATEs 返回由驱动程序管理器的说明。 与每个 SQLSTATE 值关联的返回代码是 SQL_ERROR,除非另有说明。
| SQLSTATE | 错误 | Description |
|---|---|---|
| 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包含插入语句和要插入的值的数目不匹配的派生表的程度。 |
| 21S02 | 派生表等级与列列表不匹配 | *StatementText包含CREATE VIEW语句,并指定名称的数量不是作为查询规范所定义的派生表的相同程度。 |
| 22018 | 转换指定的字符值无效 | **StatementText*包含 SQL 语句包含的文字或参数,而与关联的表的列的数据类型不兼容的值。 |
| 22019 | 无效的转义字符 | 自变量StatementText包含等谓词以及转义中其中子句和转义符的长度之后的字符转义不是等于 1。 |
| 22025 | 无效的转义序列 | 自变量StatementText包含"等模式值转义转义符"中其中子句和后面的模式值中的转义字符的字符是"%"既不"_"。 |
| 24000 | 游标状态无效 | (DM) 上打开了游标StatementHandle,并SQLFetch或SQLFetchScroll已调用一样。 在打开游标的StatementHandle,但SQLFetch或SQLFetchScroll尚未调用。 |
| 34000 | 无效的游标名称 | *StatementText包含定位删除或定位更新,且正在准备的语句所引用的游标未打开。 |
| 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包含授予或撤消语句指定的表名或视图名称不存在。 *StatementText包含选择语句指定的表名或视图名称不存在。 *StatementText包含删除,插入,或更新语句,并指定的表名不存在。 *StatementText包含CREATE TABLE语句,并指定约束 (引用表而不正在创建) 中的表不存在。 |
| 42S11 | 索引已存在 | *StatementText包含CREATE INDEX语句,并指定的索引名称已存在。 |
| 42S12 | 找不到索引 | *StatementText包含DROP INDEX语句,并指定的索引名称不存在。 |
| 42S21 | 已存在的列 | *StatementText包含ALTER TABLE语句,并在指定的列添加子句标识基表中的现有列,或不是唯一的。 |
| 42S22 | 找不到列 | *StatementText包含CREATE INDEX语句,以及一个或多列列表中指定的名称不存在的列。 *StatementText包含授予或撤消语句,并指定的列名称不存在。 *StatementText包含选择,删除,插入,或更新语句,并指定的列名称不存在。 *StatementText包含CREATE TABLE语句,并指定约束 (引用表而不正在创建) 中的列不存在。 |
| HY000 | 常规错误 | 有关其中没有任何特定的 SQLSTATE 和为其定义任何特定于实现的 SQLSTATE 出错。 返回的错误消息SQLGetDiagRec中 *MessageText缓冲区描述错误以及其原因。 |
| HY001 | 内存分配错误 | 该驱动程序无法分配支持执行或完成该函数所需的内存。 |
| HY008 | 操作已取消 | 异步处理的已启用StatementHandle。 调用该函数,和之前执行完毕SQLCancel或SQLCancelHandle上调用了StatementHandle,然后调用该函数是在上再次StatementHandle。 调用该函数,和之前执行完毕SQLCancel或SQLCancelHandle上调用了StatementHandle来自不同线程中多线程应用程序。 |
| HY009 | 使用空指针无效 | (数据挖掘) StatementText是空指针。 |
| HY010 | 函数序列错误 | (DM) 为与之关联的连接句柄调用以异步方式执行的函数StatementHandle。 此异步函数仍在执行时SQLPrepare调用函数。 (数据挖掘) SQLExecute, SQLExecDirect,或SQLMoreResults曾为StatementHandle和返回 SQL_PARAM_DATA_可用。 数据已检索到的所有经过流处理参数之前调用此函数。 (DM) 的调用以异步方式执行的函数 (不是此类似) StatementHandle和仍在执行时调用此函数。 (数据挖掘) 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 字符串。 有关参数的信息,请参阅语句参数。
Note:
如果应用程序使用SQLPrepare准备并SQLExecute提交提交或回滚语句,它不是DBMS 产品之间互操作。 若要提交或回滚事务,调用SQLEndTran。
该驱动程序可以修改该语句使用的 SQL 数据源使用的窗体,然后将它提交到准备的数据源。 具体而言,该驱动程序将修改用于定义某些功能的 SQL 语法的转义序列。 (有关 SQL 语句语法的说明,请参阅ODBC 中的转义序列并附录 c: SQL 语法。)驱动程序语句句柄是类似于语句标识符中的嵌入式 SQL 代码。 如果数据源支持语句标识符,该驱动程序可以向数据源发送语句标识符和参数值。
语句已准备就绪后,应用程序使用的语句句柄来指代中更高版本的函数调用的语句。 可以通过调用重新执行已准备的语句与语句句柄相关联SQLExecute直到应用程序释放通过调用语句SQLFreeStmt SQL_DROP 选项或直到调用中使用的语句句柄SQLPrepare, SQLExecDirect,或一个目录函数 (SQLColumns, SQLTables,依此类推)。 一旦应用程序准备某个语句,它可以请求结果集的格式的信息。 对于某些实现,调用SQLDescribeCol或SQLDescribeParam后SQLPrepare可能不如之后调用该函数SQLExecute或SQLExecDirect。
某些驱动程序不能返回语法错误或访问冲突,当应用程序调用SQLPrepare。 驱动程序可以处理语法错误和访问冲突,仅语法错误或语法错误既不访问冲突。 因此,应用程序必须能够处理这些情况,当调用后续相关函数如SQLNumResultCols, SQLDescribeCol, SQLColAttribute,并SQLExecute。
具体取决于驱动程序和数据源的功能,如果 (如果所有参数都已都绑定) 准备的语句,参数信息 (如数据类型) 可能会处于选中状态,或者 (如果尚未都绑定所有参数) 的执行时。 最大互操作性,应用程序应取消绑定应用于旧 SQL 语句前准备新的 SQL 语句在同一个语句上的所有参数。 这可以防止由于旧应用到新的语句的参数信息的错误。
Important:
提交事务,通过显式调用SQLEndTran或通过在自动提交模式下工作,就可能导致要删除的连接上的所有语句访问计划的数据源。 有关详细信息,请参阅中的 SQL_CURSOR_COMMIT_BEHAVIOR 和 SQL_CURSOR_ROLLBACK_BEHAVIOR 信息类型SQLGetInfo并对游标和准备的语句影响的事务。
代码示例
请参阅SQLBindParameter, SQLPutData,并SQLSetPos。
相关函数
| 有关信息 | 请参阅 |
|---|---|
| 分配语句句柄 | SQLAllocHandle 函数 |
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 绑定到参数的缓冲区 | SQLBindParameter 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 执行提交或回滚操作 | SQLEndTran 函数 |
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行已准备的 SQL 语句 | SQLExecute 函数 |
| 返回语句所影响的行的数 | SQLRowCount 函数 |
| 设置游标名称 | SQLSetCursorName 函数 |
请参阅
历史资料。此文对应 2018-11-30 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 MightyPen)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
