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 of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLExecDirect 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 01001 | 游标操作冲突 | *StatementText 包含定位更新或删除语句，并且未更新或删除行或多行。 （有关多行更新的详细信息，请参阅SQL_ATTR_SIMULATE_CURSOR的说明SQLSetStmtAttr 中的属性。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 01003 | 在 set 函数中消除 NULL 值 | argument 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 语句中的参数数。 使用 ParameterValuePtr 设置为 null 指针调用 SQLBindParameter，StrLen_or_IndPtr未设置为SQL_NULL_DATA或SQL_DATA_AT_EXEC，并且 InputOutputType 未设置为SQL_PARAM_OUTPUT，以便 SQLBindParameter 中指定的参数数大于 *StatementText 中包含的 SQL 语句中的参数数。 |
| 07006 | 受限数据类型属性冲突 | 无法将绑定参数的 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 包含一个包含多个字段的间隔参数，当转换为列中的数字数据类型时，该参数在数值数据类型中没有表示形式。 *StatementText 包含分配给间隔 SQL 类型的参数数据，并且间隔 SQL 类型中没有 C 类型的值表示形式。 将精确数字或间隔 SQL 类型的输入/输出参数分配给间隔 C 类型会导致有效数字丢失。 将输入/输出或输出参数分配给间隔 C 结构时，间隔数据结构中没有数据的表示形式。 |
| 22018 | 强制转换规范的字符值无效 | *StatementText 包含的 C 类型是精确或近似数字、日期/时间或间隔数据类型;列的 SQL 类型是字符数据类型;列中的值不是绑定 C 类型的有效文本。 返回输入/输出或输出参数时，SQL 类型是精确或近似数字、日期/时间或间隔数据类型;C 类型SQL_C_CHAR;和列中的值不是绑定 SQL 类型的有效文本。 |
| 22019 | 转义字符无效 | *StatementText 包含包含 WHERE 子句中 ESCAPE 的 LIKE 谓词的 SQL 语句，而 ESCAPE 后面的转义字符的长度不等于 1。 |
| 22025 | 无效转义序列 | *StatementText 包含 WHERE 子句中包含“LIKE 模式值 ESCAPE 转义字符”的 SQL 语句，模式值中的转义字符后面的字符不是“%”或“_”。 |
| 23000 | 完整性约束冲突 | *StatementText 包含包含参数或文本的 SQL 语句。 参数值是关联表列中定义为 NOT NULL 的列的 NULL，为约束仅包含唯一值的列提供了重复值，或者违反了其他一些完整性约束。 |
| 24000 | 游标状态无效 | 游标位于 SQLFetch 或 SQLFetchScroll 的 StatementHandle 上。 如果 SQLFetch 或 SQLFetchScroll 未返回SQL_NO_DATA，并且如果 SQLFetch 或 SQLFetchScroll 返回SQL_NO_DATA，驱动程序将返回此错误。 光标已打开，但未放置在 StatementHandle 上。 *StatementText 包含定位的更新或删除语句，光标位于结果集的开头或结果集末尾之后。 |
| 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 包含对已查看表或派生自通过指定 WITH CHECK OPTION 创建的表的 INSERT 语句，这样，受 INSERT 语句影响的一行或多行将不再存在于查看表中。 argument StatementText 包含对已查看表或派生自通过指定 WITH CHECK OPTION 创建的表的 UPDATE 语句，这样，受 UPDATE 语句影响的一行或多行将不再存在于查看表中。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 为 StatementHandle 启用了异步处理。 调用了该函数，在完成执行之前，对 StatementHandle 调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用该函数。 调用了函数，在完成执行之前，SQLCancel 或 SQLCancelHandle 从多线程应用程序中的不同线程调用 StatementHandle。 |
| HY009 | 无效使用 null 指针 | （DM） *StatementText 是空指针。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLExecDirect 函数时，此异步函数仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 为 StatementHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了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 设置的参数值不是空指针;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 中的 USE 数据库 语句，这会更改数据源使用的目录。
代码示例
请参阅 SQLBindCol、 SQLGetData 和 示例 ODBC 程序。
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 执行提交或回滚操作 | SQLEndTran 函数 |
| 执行准备的 SQL 语句 | SQLExecute 函数 |
| 提取多行数据 | SQLFetch 函数 |
| 提取数据块或滚动结果集 | SQLFetchScroll 函数 |
| 返回游标名称 | SQLGetCursorName 函数 |
| 提取部分或全部数据列 | SQLGetData 函数 |
| 返回要为其发送数据的下一个参数 | SQLParamData 函数 |
| 准备语句以供执行 | SQLPrepare 函数 |
| 在执行时发送参数数据 | SQLPutData 函数 |
| 设置游标名称 | SQLSetCursorName 函数 |
| 设置语句属性 | SQLSetStmtAttr 函数 |