SQLPrepare 函数SQLPrepare Function

符合性Conformance
版本引入了:ODBC 1.0 标准符合性:ISO 92Version Introduced: ODBC 1.0 Standards Compliance: ISO 92

摘要Summary
SQLPrepare做好执行 SQL 字符串。SQLPrepare prepares an SQL string for execution.

语法Syntax

  
SQLRETURN SQLPrepare(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     StatementText,  
     SQLINTEGER    TextLength);  

参数Arguments

StatementHandleStatementHandle
[输入]语句句柄。[Input] Statement handle.

StatementTextStatementText
[输入]SQL 文本字符串。[Input] SQL text string.

TextLengthTextLength
[输入]长度 *StatementText以字符为单位。[Input] Length of *StatementText in characters.

返回Returns

SQL_SUCCESS、 SQL_SUCCESS_WITH_INFO、 SQL_STILL_EXECUTING、 SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLPrepare返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO,关联的 SQLSTATE 值可以通过调用来获取SQLGetDiagRecHandleType的 SQL_HANDLE_STMT 和一个处理StatementHandleWhen SQLPrepare returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. 下表列出了通常返回的 SQLSTATE 值SQLPrepare ,并解释了此函数; 每个上下文中的表示法"(数据挖掘)"之前 SQLSTATEs 返回由驱动程序管理器的说明。The following table lists the SQLSTATE values commonly returned by SQLPrepare and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 与每个 SQLSTATE 值关联的返回代码是 SQL_ERROR,除非另有说明。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATESQLSTATE ErrorError 描述Description
0100001000 常规警告General warning 特定于驱动程序的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
01S0201S02 选项值已更改Option value changed 指定的语句属性实现运行情况,由于无效,因此已暂时替换一个相近的值。A specified statement attribute was invalid because of implementation working conditions, so a similar value was temporarily substituted. (SQLGetStmtAttr可以调用以确定暂时被替换的值是什么。)替换值是否为有效StatementHandle直到关闭游标。(SQLGetStmtAttr can be called to determine what the temporarily substituted value is.) The substitute value is valid for the StatementHandle until the cursor is closed. 可以更改的语句属性有: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_CURSORThe statement attributes that can be changed are: 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。)(Function returns SQL_SUCCESS_WITH_INFO.)
08S0108S01 通讯链接失败Communication link failure 该驱动程序和驱动程序已连接到数据源之间的通信链接失败之前函数已完成处理。The communication link between the driver and the data source to which the driver was connected failed before the function completed processing.
21S0121S01 插入值列表与列列表不匹配Insert value list does not match column list *StatementText包含插入语句和要插入的值的数目不匹配的派生表的程度。*StatementText contained an INSERT statement, and the number of values to be inserted did not match the degree of the derived table.
21S0221S02 派生表等级与列列表不匹配Degree of derived table does not match column list *StatementText包含CREATE VIEW语句,并指定名称的数量不是作为查询规范所定义的派生表的相同程度。*StatementText contained a CREATE VIEW statement, and the number of names specified is not the same degree as the derived table defined by the query specification.
2201822018 转换指定的字符值无效Invalid character value for cast specification *StatementText包含 SQL 语句包含的文字或参数,而与关联的表的列的数据类型不兼容的值。*StatementText contained an SQL statement that contained a literal or parameter, and the value was incompatible with the data type of the associated table column.
2201922019 无效的转义字符Invalid escape character 自变量StatementText包含谓词以及转义其中子句和转义符的长度之后的字符转义不是等于 1。The argument StatementText contained a LIKE predicate with an ESCAPE in the WHERE clause, and the length of the escape character following ESCAPE was not equal to 1.
2202522025 无效的转义序列Invalid escape sequence 自变量StatementText包含"模式值转义转义符"中其中子句和后面的模式值中的转义字符的字符是"%"既不""。The argument StatementText contained "LIKE pattern value ESCAPE escape character" in the WHERE clause, and the character following the escape character in the pattern value was neither "%" nor "".
2400024000 游标状态无效Invalid cursor state (DM) 上打开了游标StatementHandle,并SQLFetchSQLFetchScroll已调用一样。(DM) A cursor was open on the StatementHandle, and SQLFetch or SQLFetchScroll had been called.

在打开游标的StatementHandle,但SQLFetchSQLFetchScroll尚未调用。A cursor was open on the StatementHandle, but SQLFetch or SQLFetchScroll had not been called.
3400034000 无效的游标名称Invalid cursor name *StatementText包含定位删除或定位更新,且正在准备的语句所引用的游标未打开。*StatementText contained a positioned DELETE or a positioned UPDATE, and the cursor referenced by the statement being prepared was not open.
3D0003D000 目录名称无效Invalid catalog name 中指定的目录名称StatementText无效。The catalog name specified in StatementText was invalid.
3F0003F000 无效的架构名称Invalid schema name 中指定的架构名称StatementText无效。The schema name specified in StatementText was invalid.
4200042000 语法错误或访问冲突Syntax error or access violation *StatementText包含 SQL 语句不是可准备对象或包含语法错误。*StatementText contained an SQL statement that was not preparable or contained a syntax error.

*StatementText包含用户没有具有所需的权限的语句。*StatementText contained a statement for which the user did not have the required privileges.
42S0142S01 基表或视图已存在Base table or view already exists *StatementText包含CREATE TABLECREATE VIEW语句和表名称或视图指定名称已存在。*StatementText contained a CREATE TABLE or CREATE VIEW statement, and the table name or view name specified already exists.
42S0242S02 基表或视图找不到Base table or view not found *StatementText包含DROP TABLEDROP VIEW语句指定的表名或视图名称不存在。*StatementText contained a DROP TABLE or a DROP VIEW statement, and the specified table name or view name did not exist.

*StatementText包含ALTER TABLE语句,并指定的表名不存在。*StatementText contained an ALTER TABLE statement, and the specified table name did not exist.

*StatementText包含CREATE VIEW语句和表名称或视图不存在查询规范所定义的名称。*StatementText contained a CREATE VIEW statement, and a table name or view name defined by the query specification did not exist.

*StatementText包含CREATE INDEX语句,并指定的表名不存在。*StatementText contained a CREATE INDEX statement, and the specified table name did not exist.

*StatementText包含授予撤消语句指定的表名或视图名称不存在。*StatementText contained a GRANT or REVOKE statement, and the specified table name or view name did not exist.

*StatementText包含选择语句指定的表名或视图名称不存在。*StatementText contained a SELECT statement, and a specified table name or view name did not exist.

*StatementText包含删除插入,或更新语句,并指定的表名不存在。*StatementText contained a DELETE, INSERT, or UPDATE statement, and the specified table name did not exist.

*StatementText包含CREATE TABLE语句,并指定约束 (引用表而不正在创建) 中的表不存在。*StatementText contained a CREATE TABLE statement, and a table specified in a constraint (referencing a table other than the one being created) did not exist.
42S1142S11 索引已存在Index already exists *StatementText包含CREATE INDEX语句,并指定的索引名称已存在。*StatementText contained a CREATE INDEX statement, and the specified index name already existed.
42S1242S12 找不到索引Index not found *StatementText包含DROP INDEX语句,并指定的索引名称不存在。*StatementText contained a DROP INDEX statement, and the specified index name did not exist.
42S2142S21 已存在的列Column already exists *StatementText包含ALTER TABLE语句,并在指定的列添加子句标识基表中的现有列,或不是唯一的。*StatementText contained an ALTER TABLE statement, and the column specified in the ADD clause is not unique or identifies an existing column in the base table.
42S2242S22 找不到列Column not found *StatementText包含CREATE INDEX语句,以及一个或多列列表中指定的名称不存在的列。*StatementText contained a CREATE INDEX statement, and one or more of the column names specified in the column list did not exist.

*StatementText包含授予撤消语句,并指定的列名称不存在。*StatementText contained a GRANT or REVOKE statement, and a specified column name did not exist.

*StatementText包含选择删除插入,或更新语句,并指定的列名称不存在。*StatementText contained a SELECT, DELETE, INSERT, or UPDATE statement, and a specified column name did not exist.

*StatementText包含CREATE TABLE语句,并指定约束 (引用表而不正在创建) 中的列不存在。*StatementText contained a CREATE TABLE statement, and a column specified in a constraint (referencing a table other than the one being created) did not exist.
HY000HY000 常规错误General error 有关其中没有任何特定的 SQLSTATE 和为其定义任何特定于实现的 SQLSTATE 出错。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. 返回的错误消息SQLGetDiagRec*MessageText缓冲区描述错误以及其原因。The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001HY001 内存分配错误Memory allocation error 该驱动程序无法分配支持执行或完成该函数所需的内存。The driver was unable to allocate memory required to support execution or completion of the function.
HY008HY008 操作已取消Operation canceled 异步处理的已启用StatementHandleAsynchronous processing was enabled for the StatementHandle. 调用该函数,和之前执行完毕SQLCancelSQLCancelHandle上调用了StatementHandle,然后调用该函数是在上再次StatementHandleThe function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle, and then the function was called again on the StatementHandle.

调用该函数,和之前执行完毕SQLCancelSQLCancelHandle上调用了StatementHandle来自不同线程中多线程应用程序。The function was called, and before it completed execution, SQLCancel or SQLCancelHandle was called on the StatementHandle from a different thread in a multithread application.
HY009HY009 使用空指针无效Invalid use of null pointer (数据挖掘) StatementText是空指针。(DM) StatementText was a null pointer.
HY010HY010 函数序列错误Function sequence error (DM) 为与之关联的连接句柄调用以异步方式执行的函数StatementHandle(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 此异步函数仍在执行时SQLPrepare调用函数。This asynchronous function was still executing when the SQLPrepare function was called.

(数据挖掘) SQLExecuteSQLExecDirect,或SQLMoreResults曾为StatementHandle和返回 SQL_PARAM_DATA_可用。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the StatementHandle and returned SQL_PARAM_DATA_AVAILABLE. 数据已检索到的所有经过流处理参数之前调用此函数。This function was called before data was retrieved for all streamed parameters.

(DM) 的调用以异步方式执行的函数 (不是此类似) StatementHandle和仍在执行时调用此函数。(DM) An asynchronously executing function (not this one) was called for the StatementHandle and was still executing when this function was called.

(数据挖掘) SQLExecuteSQLExecDirectSQLBulkOperations,或者SQLSetPos曾为StatementHandle和返回 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. 数据已发送的所有执行时数据参数或列之前调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.
HY013HY013 内存管理错误Memory management error 无法处理函数调用,因为基础内存对象无法访问,可能是由于内存不足的情况。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY090HY090 字符串或缓冲区长度无效Invalid string or buffer length (DM) 参数TextLength小于或等于为 0 但不是等于 SQL_NTS。(DM) The argument TextLength was less than or equal to 0 but not equal to SQL_NTS.
HY117HY117 由于未知的事务状态而挂起连接。Connection is suspended due to unknown transaction state. 仅断开连接,并允许使用只读的函数。Only disconnect and read-only functions are allowed. (DM) 有关挂起状态的详细信息,请参阅SQLEndTran 函数(DM) For more information about suspended state, see SQLEndTran Function.
HYC00HYC00 未实现的可选功能Optional feature not implemented 并发设置定义游标类型无效。The concurrency setting was invalid for the type of cursor defined.

SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_VARIABLE,并且 SQL_ATTR_CURSOR_TYPE 语句属性设置为游标类型,该驱动程序不支持书签。The SQL_ATTR_USE_BOOKMARKS statement attribute was set to SQL_UB_VARIABLE, and the SQL_ATTR_CURSOR_TYPE statement attribute was set to a cursor type for which the driver does not support bookmarks.
HYT00HYT00 超时时间已到Timeout expired 超时期限过期之前的数据源返回的结果集。The timeout period expired before the data source returned the result set. 通过设置超时期限SQLSetStmtAttr,SQL_ATTR_QUERY_TIMEOUT。The timeout period is set through SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT.
HYT01HYT01 连接超时时间已到Connection timeout expired 连接超时期限过期之前的数据源响应此请求。The connection timeout period expired before the data source responded to the request. 通过设置连接超时期SQLSetConnectAttr,SQL_ATTR_CONNECTION_TIMEOUT。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此函数Driver does not support this function (DM) 驱动程序与相关联StatementHandle不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.
IM017IM017 轮询异步通知模式中禁用Polling is disabled in asynchronous notification mode 只要使用通知模型,将禁用轮询。Whenever the notification model is used, polling is disabled.
IM018IM018 SQLCompleteAsync尚未调用以完成此句柄上以前的异步操作。SQLCompleteAsync has not been called to complete the previous asynchronous operation on this handle. 如果句柄上的上一个函数调用返回 SQL_STILL_EXECUTING,如果启用通知模式,则SQLCompleteAsync必须要对其进行后期处理并完成该操作的句柄上调用。If the previous function call on the handle returns SQL_STILL_EXECUTING and if notification mode is enabled, SQLCompleteAsync must be called on the handle to do post-processing and complete the operation.

注释Comments

应用程序调用SQLPrepare将 SQL 语句发送到准备的数据源。The application calls SQLPrepare to send an SQL statement to the data source for preparation. 准备好的执行有关的详细信息,请参阅准备好执行For more information about prepared execution, see Prepared Execution. 应用程序可以在 SQL 语句中包含一个或多个参数标记。The application can include one or more parameter markers in the SQL statement. 若要包含的参数标记,该应用程序将嵌入一个问号 (?) 到相应位置处的 SQL 字符串。To include a parameter marker, the application embeds a question mark (?) into the SQL string at the appropriate position. 有关参数的信息,请参阅语句参数For information about parameters, see Statement Parameters.

备注

如果应用程序使用SQLPrepare准备并SQLExecute提交提交回滚语句,它不是DBMS 产品之间互操作。If an application uses SQLPrepare to prepare and SQLExecute to submit a COMMIT or ROLLBACK statement, it will not be interoperable between DBMS products. 若要提交或回滚事务,调用SQLEndTranTo commit or roll back a transaction, call SQLEndTran.

该驱动程序可以修改该语句使用的 SQL 数据源使用的窗体,然后将它提交到准备的数据源。The driver can modify the statement to use the form of SQL used by the data source and then submit it to the data source for preparation. 具体而言,该驱动程序将修改用于定义某些功能的 SQL 语法的转义序列。In particular, the driver modifies the escape sequences used to define SQL syntax for certain features. (有关 SQL 语句语法的说明,请参阅ODBC 中的转义序列附录 c:SQL 语法。)驱动程序语句句柄是类似于语句标识符中的嵌入式 SQL 代码。(For a description of SQL statement grammar, see Escape Sequences in ODBC and Appendix C: SQL Grammar.) For the driver, a statement handle is similar to a statement identifier in embedded SQL code. 如果数据源支持语句标识符,该驱动程序可以向数据源发送语句标识符和参数值。If the data source supports statement identifiers, the driver can send a statement identifier and parameter values to the data source.

语句已准备就绪后,应用程序使用的语句句柄来指代中更高版本的函数调用的语句。After a statement is prepared, the application uses the statement handle to refer to the statement in later function calls. 可以通过调用重新执行已准备的语句与语句句柄相关联SQLExecute直到应用程序释放通过调用语句SQLFreeStmt SQL_DROP 选项或直到调用中使用的语句句柄SQLPrepareSQLExecDirect,或一个目录函数 (SQLColumnsSQLTables,依此类推)。The prepared statement associated with the statement handle can be re-executed by calling SQLExecute until the application frees the statement with a call to SQLFreeStmt with the SQL_DROP option or until the statement handle is used in a call to SQLPrepare, SQLExecDirect, or one of the catalog functions (SQLColumns, SQLTables, and so on). 一旦应用程序准备某个语句,它可以请求结果集的格式的信息。Once the application prepares a statement, it can request information about the format of the result set. 对于某些实现,调用SQLDescribeColSQLDescribeParamSQLPrepare可能不如之后调用该函数SQLExecuteSQLExecDirectFor some implementations, calling SQLDescribeCol or SQLDescribeParam after SQLPrepare might not be as efficient as calling the function after SQLExecute or SQLExecDirect.

某些驱动程序不能返回语法错误或访问冲突,当应用程序调用SQLPrepareSome drivers cannot return syntax errors or access violations when the application calls SQLPrepare. 驱动程序可以处理语法错误和访问冲突,仅语法错误或语法错误既不访问冲突。A driver can handle syntax errors and access violations, only syntax errors, or neither syntax errors nor access violations. 因此,应用程序必须能够处理这些情况,当调用后续相关函数如SQLNumResultColsSQLDescribeColSQLColAttribute,并SQLExecuteTherefore, an application must be able to handle these conditions when calling subsequent related functions such as SQLNumResultCols, SQLDescribeCol, SQLColAttribute, and SQLExecute.

具体取决于驱动程序和数据源的功能,如果 (如果所有参数都已都绑定) 准备的语句,参数信息 (如数据类型) 可能会处于选中状态,或者 (如果尚未都绑定所有参数) 的执行时。Depending on the capabilities of the driver and data source, parameter information (such as data types) might be checked when the statement is prepared (if all parameters have been bound) or when it is executed (if all parameters have not been bound). 最大互操作性,应用程序应取消绑定应用于旧 SQL 语句前准备新的 SQL 语句在同一个语句上的所有参数。For maximum interoperability, an application should unbind all parameters that applied to an old SQL statement before preparing a new SQL statement on the same statement. 这可以防止由于旧应用到新的语句的参数信息的错误。This prevents errors that are due to old parameter information being applied to the new statement.

重要

提交事务,通过显式调用SQLEndTran或通过在自动提交模式下工作,就可能导致要删除的连接上的所有语句访问计划的数据源。Committing a transaction, either by explicitly calling SQLEndTran or by working in autocommit mode, can cause the data source to delete the access plans for all statements on a connection. 有关详细信息,请参阅中的 SQL_CURSOR_COMMIT_BEHAVIOR 和 SQL_CURSOR_ROLLBACK_BEHAVIOR 信息类型SQLGetInfo对游标和准备的语句影响的事务For more information, see the SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR information types in SQLGetInfo and Effect of Transactions on Cursors and Prepared Statements.

代码示例Code Example

请参阅SQLBindParameterSQLPutData,并SQLSetPosSee SQLBindParameter, SQLPutData, and SQLSetPos.

有关信息For information about 请参阅See
分配语句句柄Allocating a statement handle SQLAllocHandle 函数SQLAllocHandle Function
将缓冲区绑定到结果集中的列Binding a buffer to a column in a result set SQLBindCol 函数SQLBindCol Function
绑定到参数的缓冲区Binding a buffer to a parameter SQLBindParameter 函数SQLBindParameter Function
取消语句处理Canceling statement processing SQLCancel 函数SQLCancel Function
执行提交或回滚操作Executing a commit or rollback operation SQLEndTran 函数SQLEndTran Function
执行 SQL 语句Executing an SQL statement SQLExecDirect 函数SQLExecDirect Function
执行已准备的 SQL 语句Executing a prepared SQL statement SQLExecute 函数SQLExecute Function
返回语句所影响的行的数Returning the number of rows affected by a statement SQLRowCount 函数SQLRowCount Function
设置游标名称Setting a cursor name SQLSetCursorName 函数SQLSetCursorName Function

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件ODBC Header Files