SQLExecDirect 函数

一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92

摘要
如果语句中存在任何参数，SQLExecDirect 使用参数标记变量的当前值执行可准备语句。 SQLExecDirect 是提交 SQL 语句以进行一次性执行的最快方法。

语法

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

参数

StatementHandle
[输入]语句句柄。

StatementText
[输入]要执行的 SQL 语句。

TextLength
[输入]*StatementText 的长度（以字符为单位）。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_NEED_DATA、SQL_STILL_EXECUTING、SQL_ERROR、SQL_NO_DATA、SQL_INVALID_HANDLE或SQL_PARAM_DATA_AVAILABLE。

诊断

当 SQLExecDirect 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType 为 SQL_HANDLE_STMT 和 Handle ofStatementHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLExecDirect 通常返回的 SQLSTATE 值，并对此函数的上下文中的每个值进行了说明：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE	错误	说明
01000	常规警告	特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01001	游标操作冲突	*StatementText 包含定位的更新或删除语句，并且没有更新或删除任何行或多行。 (有关多行更新的详细信息，请参阅 SQLSetStmtAttr.) 中SQL_ATTR_SIMULATE_CURSOR属性的说明 (函数返回 SQL_SUCCESS_WITH_INFO.)
01003	set 函数中消除的 NULL 值	参数 StatementText 包含一个集函数 (如 AVG、 MAX、 MIN 等) ，但不包含 COUNT 集函数，并且 NULL 参数值在应用函数之前已被消除。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01004	字符串数据，右截断	为输入/输出或输出参数返回的字符串或二进制数据导致截断非空字符或非 NULL 二进制数据。 如果它是字符串值，则它被右截断。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01006	未撤销权限	*StatementText 包含 REVOKE 语句，并且用户没有指定的权限。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01007	未授予权限	*StatementText 是 GRANT 语句，无法向用户授予指定的权限。
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.)
01S07	小数截断	为输入/输出或输出参数返回的数据被截断，以便数字数据类型的小数部分被截断，或者时间、时间戳或间隔数据类型的时间分量的小数部分被截断。 (函数返回 SQL_SUCCESS_WITH_INFO.)
07002	COUNT 字段不正确	SQLBindParameter 中指定的参数数小于 *StatementText 中包含的 SQL 语句中的参数数。 调用 SQLBindParameter 时 ，ParameterValuePtr 设置为 null 指针， StrLen_or_IndPtr 未设置为 SQL_NULL_DATA 或 SQL_DATA_AT_EXEC， InputOutputType 未设置为 SQL_PARAM_OUTPUT，因此 SQLBindParameter 中指定的参数数大于 *StatementText 中包含的 SQL 语句中的参数数。
07006	受限数据类型属性冲突	无法将绑定参数的 SQLBindParameter 中的 ValueType 参数标识的数据值转换为由 SQLBindParameter 中的 ParameterType 参数标识的数据类型。 无法将绑定为 SQL_PARAM_INPUT_OUTPUT 或 SQL_PARAM_OUTPUT 的参数返回的数据值转换为由 SQLBindParameter 中的 ValueType 参数标识的数据类型。 (如果无法转换一行或多行的数据值，但成功返回一行或多行，此函数将返回SQL_SUCCESS_WITH_INFO.)
07007	受限参数值冲突	参数类型 SQL_PARAM_INPUT_OUTPUT_STREAM 仅用于在部件中发送和接收数据的参数。 此参数类型不允许输入绑定缓冲区。 当参数类型为 SQL_PARAM_INPUT_OUTPUT，SQLBindParameter 中指定的 *StrLen_or_IndPtr 不等于 SQL_NULL_DATA、SQL_DEFAULT_PARAM、SQL_LEN_DATA_AT_EXEC (len) 或 SQL_DATA_AT_EXEC 时，将发生此错误。
07S01	默认参数的使用无效	使用 SQLBindParameter 设置的参数值SQL_DEFAULT_PARAM，并且相应的参数没有默认值。
08S01	通信链接失败	在函数完成处理之前，驱动程序与所连接的数据源之间的通信链接失败。
21S01	插入值列表与列列表不匹配	*StatementText 包含 INSERT 语句，要插入的值数与派生表的度数不匹配。
21S02	派生表的度与列列表不匹配	*StatementText 包含 CREATE VIEW 语句，非限定列列表 (SQL 语句的 列标识符 参数中为视图指定的列数) 包含的名称多于由 SQL 语句的 查询规范 参数定义的派生表中的列数。
22001	字符串数据，右截断	将字符或二进制值分配给列会导致截断非空字符数据或非 null 二进制数据。
22002	需要指示器变量，但未提供	NULL 数据绑定到由 SQLBindParameter 设置的StrLen_or_IndPtr为 null 指针的输出参数。
22003	数值范围外	*StatementText 包含一个包含绑定数值参数或文本的 SQL 语句，值导致整个 (（而不是) 部分数字在分配给关联的表列时被截断）。 为一个或多个输入/输出或输出参数返回数值 (为数值或字符串) 会导致整个 (而不是数字的) 部分被截断。
22007	日期/时间格式无效	*StatementText 包含一个 SQL 语句，该语句包含日期、时间或时间戳结构作为绑定参数，该参数分别是无效的日期、时间或时间戳。 输入/输出或输出参数绑定到日期、时间或时间戳 C 结构，返回的参数中的值分别为无效的日期、时间或时间戳。 (函数返回 SQL_SUCCESS_WITH_INFO.)
22008	日期时间字段溢出	*StatementText 包含一个 SQL 语句，该语句包含一个日期/时间表达式，在计算时，该表达式会导致日期、时间或时间戳结构无效。 为输入/输出或输出参数计算的日期/时间表达式导致日期、时间或时间戳 C 结构无效。
22012	被零除	*StatementText 包含一个 SQL 语句，该语句包含导致除以零的算术表达式。 为输入/输出或输出参数计算的算术表达式导致除以零。
22015	间隔字段溢出	*StatementText 包含确切的数字或间隔参数，当转换为间隔 SQL 数据类型时，该参数会导致有效数字丢失。 *StatementText 包含一个包含多个字段的 interval 参数，这些字段在转换为列中的数值数据类型时，在数值数据类型中没有表示形式。 *StatementText 包含分配给间隔 SQL 类型的参数数据，并且间隔 SQL 类型中没有 C 类型的值表示形式。 将作为精确数字或间隔 SQL 类型的输入/输出或输出参数分配给间隔 C 类型会导致有效位数丢失。 将输入/输出或输出参数分配给间隔 C 结构时，间隔数据结构中没有数据表示形式。
22018	强制转换规范的字符值无效	*StatementText 包含 C 类型，该类型为精确或近似数值、日期时间或间隔数据类型;列的 SQL 类型是字符数据类型;列中的值不是绑定 C 类型的有效文本。 返回输入/输出或输出参数时，SQL 类型为精确或近似数值、日期时间或间隔数据类型;C 类型SQL_C_CHAR;列中的值不是绑定 SQL 类型的有效文本。
22019	转义字符无效	*StatementText 包含一个 SQL 语句，该语句包含 WHERE 子句中具有 ESCAPE 的 LIKE 谓词，而 ESCAPE 后面的转义字符的长度不等于 1。
22025	转义序列无效	*StatementText 包含一个 SQL 语句，该语句在 WHERE 子句中包含“LIKE模式值ESCAPE转义字符”，并且模式值中转义字符后面的字符不是“%”或“_”之一。
23000	完整性约束冲突	*StatementText 包含包含参数或文本的 SQL 语句。 对于在关联的表列中定义为 NOT NULL 的列，参数值为 NULL，为约束为仅包含唯一值的列提供了重复值，或者违反了其他一些完整性约束。
24000	游标状态无效	游标由 SQLFetch 或SQLFetchScroll 定位在 StatementHandle 上。 如果 SQLFetch 或 SQLFetchScroll 未返回SQL_NO_DATA，则驱动程序管理器将返回此错误;如果 SQLFetch 或 SQLFetchScroll 已返回SQL_NO_DATA，则驱动程序会返回此错误。 游标已打开，但未定位在 StatementHandle 上。 *StatementText 包含定位的 update 或 delete 语句，游标位于结果集开始之前或结果集末尾之后。
34000	游标名称无效	*StatementText 包含定位的更新或删除语句，并且正在执行的语句引用的游标未打开。
3D000	目录名称无效	StatementText 中指定的目录名称无效。
3F000	架构名称无效	StatementText 中指定的架构名称无效。
40001	序列化失败	由于与另一个事务发生资源死锁，事务已回滚。
40003	语句完成未知	在执行此函数期间，关联的连接失败，并且无法确定事务的状态。
42000	语法错误或访问冲突	*StatementText 包含不可准备的 SQL 语句或包含语法错误。 用户无权执行 *StatementText 中包含的 SQL 语句。
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 语句，并在约束中指定的表 (引用所创建的表) 不存在。 *StatementText 包含 CREATE SCHEMA 语句，指定的表名或视图名称不存在。
42S11	索引已存在	*StatementText 包含 CREATE INDEX 语句，并且指定的索引名称已存在。 *StatementText 包含 CREATE SCHEMA 语句，并且指定的索引名称已存在。
42S12	找不到索引	*StatementText 包含 DROP INDEX 语句，并且指定的索引名称不存在。
42S21	列已存在	*StatementText 包含 ALTER TABLE 语句， ADD 子句中指定的列不唯一，或者标识基表中的现有列。
42S22	找不到列	*StatementText 包含 CREATE INDEX 语句，列列表中指定的一个或多个列名称不存在。 *StatementText 包含 GRANT 或 REVOKE 语句，并且指定的列名称不存在。 *StatementText 包含 SELECT、 DELETE、 INSERT 或 UPDATE 语句，并且指定的列名称不存在。 *StatementText 包含 CREATE TABLE 语句，并在约束中指定的列 (引用正在创建的表) 不存在。 *StatementText 包含 CREATE SCHEMA 语句，并且指定的列名称不存在。
44000	WITH CHECK OPTION 冲突	参数 StatementText 包含对查看表执行的 INSERT 语句，或派生自通过指定 WITH CHECK OPTION 创建的查看表的表，这样，受 INSERT 语句影响的一行或多行将不再存在于查看的表中。 参数 StatementText 包含对查看表执行的 UPDATE 语句或派生自通过指定 WITH CHECK OPTION 创建的查看表的表，这样，受 UPDATE 语句影响的一个或多个行将不再存在于查看的表中。
HY000	常规错误	发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001	内存分配错误	驱动程序无法分配支持执行或完成函数所需的内存。
HY008	操作已取消	已为 StatementHandle 启用异步处理。 调用了函数，在它完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用函数。 函数已调用，在它完成执行之前，在 StatementHandle 上从多线程应用程序中的不同线程调用 SQLCancel 或 SQLCancelHandle。
HY009	null 指针的使用无效	(DM) *StatementText 为 null 指针。
HY010	函数序列错误	(DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLExecDirect 函数时，此异步函数仍在执行。 (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。 使用 SQLBindParameter 设置的参数值是空指针，参数长度值不是 0、SQL_NULL_DATA、SQL_DATA_AT_EXEC、SQL_DEFAULT_PARAM或小于或等于 SQL_LEN_DATA_AT_EXEC_OFFSET。 使用 SQLBindParameter 设置的参数值不是 null 指针;C 数据类型SQL_C_BINARY或SQL_C_CHAR;参数长度值小于 0，但未SQL_NTS、SQL_NULL_DATA、SQL_DATA_AT_EXEC、SQL_DEFAULT_PARAM或小于或等于 SQL_LEN_DATA_AT_EXEC_OFFSET。 SQLBindParameter 绑定的参数长度值已设置为 SQL_DATA_AT_EXEC;SQL 类型为SQL_LONGVARCHAR、SQL_LONGVARBINARY或特定于数据源的长数据类型;SQLGetInfo 中的SQL_NEED_LONG_DATA_LEN信息类型为“Y”。
HY105	参数类型无效	为 SQLBindParameter 中的参数 InputOutputType 指定的值SQL_PARAM_OUTPUT，参数为输入参数。
HY109	游标位置无效	*StatementText 包含定位的更新或删除语句，并且游标由 SQLSetPos 或 SQLFetchScroll) 定位在已删除或无法提取的行上 (。
HY117	由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。	(DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYC00	未实现可选功能	驱动程序或数据源不支持SQL_ATTR_CONCURRENCY和 SQL_ATTR_CURSOR_TYPE 语句属性的当前设置组合。 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 以执行后期处理并完成操作。

注释

应用程序调用 SQLExecDirect 以将 SQL 语句发送到数据源。 有关直接执行的详细信息，请参阅 直接执行。 驱动程序将 语句修改为使用数据源使用的 SQL 格式，然后将其提交到数据源。 具体而言，驱动程序修改用于在 SQL 中定义某些功能的转义序列。 有关转义序列的语法，请参阅 ODBC 中的转义序列。

应用程序可以在 SQL 语句中包含一个或多个参数标记。 若要包含参数标记，应用程序会将问号 (？) 嵌入 SQL 语句的相应位置。 有关参数的信息，请参阅 语句参数。

如果 SQL 语句是 SELECT 语句，并且应用程序调用 SQLSetCursorName 将游标与语句相关联，则驱动程序将使用指定的游标。 否则，驱动程序将生成游标名称。

如果数据源处于手动提交模式， (需要显式事务启动) 并且尚未启动事务，则驱动程序会在发送 SQL 语句之前启动事务。 有关详细信息，请参阅 手动提交模式。

如果应用程序使用 SQLExecDirect 提交 COMMIT 或 ROLLBACK 语句，则它将无法在 DBMS 产品之间互操作。 若要提交或回滚事务，应用程序会调用 SQLEndTran。

如果 SQLExecDirect 遇到执行时数据参数，则返回SQL_NEED_DATA。 应用程序使用 SQLParamData 和 SQLPutData 发送 数据。 请参阅 SQLBindParameter、 SQLParamData、 SQLPutData 和 发送长数据。

如果 SQLExecDirect 执行不影响数据源中任何行的搜索更新、插入或删除语句，则对 SQLExecDirect 的调用将返回SQL_NO_DATA。

如果 SQL_ATTR_PARAMSET_SIZE 语句属性的值大于 1 并且 SQL 语句包含至少一个参数标记，则 SQLExecDirect 将对调用 SQLBindParameter 中 ParameterValuePointer 参数指向的数组中的每组参数值执行一次 SQL 语句。 有关详细信息，请参阅 参数值的数组。

如果书签处于打开状态，并且执行了不支持书签的查询，则驱动程序应尝试通过更改属性值并返回 SQLSTATE 01S02 (选项值更改) ，将环境强制设置为支持书签的环境。 如果无法更改属性，驱动程序应返回 SQLSTATE HY024 (无效的属性值) 。

注意

使用连接池时，应用程序不得执行更改数据库或数据库上下文的 SQL 语句，例如SQL Server中的 USEdatabase 语句，这会更改数据源使用的目录。

代码示例

请参阅 SQLBindCol、 SQLGetData 和 示例 ODBC 程序。

相关函数

有关以下方面的信息	请参阅
将缓冲区绑定到结果集中的列	SQLBindCol 函数
取消语句处理	SQLCancel 函数
执行提交或回滚操作	SQLEndTran 函数
执行准备好的 SQL 语句	SQLExecute 函数
提取多行数据	SQLFetch 函数
提取数据块或滚动浏览结果集	SQLFetchScroll Function（SQLFetchScroll 函数）
返回游标名称	SQLGetCursorName 函数
提取部分或全部数据列	SQLGetData 函数
返回要为其发送数据的下一个参数	SQLParamData 函数
准备要执行的语句	SQLPrepare 函数
在执行时发送参数数据	SQLPutData 函数
设置游标名称	SQLSetCursorName 函数
设置语句属性	SQLSetStmtAttr 函数

另请参阅

ODBC API 参考
ODBC 头文件