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 和 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 值 argument StatementText 包含一个集函数, (如 AVGMAXMIN 等) ,但未消除 COUNT 集函数,并在应用函数之前消除 NULL 参数值。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01004 字符串数据,右截断 为输入/输出或输出参数返回的字符串或二进制数据导致非布兰克字符或非 NULL 二进制数据截断。 如果它是字符串值,则将其右截断。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01006 未撤销的权限 *StatementText 包含 REVOKE 语句,并且用户没有指定的权限。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01007 未授予特权 *StatementTextGRANT 语句,用户无法授予指定权限。
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 指针调用 SQLBindParameterStrLen_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绑定的参数返回的数据值转换为 SQLBindParameterValueType 参数标识的数据类型。

(如果无法转换一个或多个行的数据值,但成功返回了一个或多个行,此函数将返回 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为空指针。
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 包含一个 SQL 语句,该语句包含 WHERE 子句中的“LIKE模式值ESCAPE 转义字符”,并且模式值中的转义字符后面的字符不是“%”或“_”。
23000 完整性约束冲突 *StatementText 包含包含参数或文本的 SQL 语句。 参数值是关联表列中定义为 NOT NULL 的列的 NULL,为约束仅包含唯一值的列提供重复值,或者违反了其他一些完整性约束。
24000 游标状态无效 游标位于 SqlFetchSQLFetchScrollStatementHandle 上。 如果 SQLFetch 或 SQLFetchScroll 未返回SQL_NO_DATA,并且如果 SQLFetchSQLFetchScroll 返回了SQL_NO_DATA,驱动程序将返回此错误。

光标处于打开状态,但未定位在 StatementHandle 上。

*StatementText 包含定位的更新或删除语句,游标位于结果集的开头或结果集末尾之前。
34000 无效的游标名称 *StatementText 包含定位的更新或删除语句,所执行的语句引用的游标未打开。
3D000 目录名称无效 StatementText 中指定的目录名称无效。
3F000 无效的架构名称 StatementText 中指定的架构名称无效。
40001 序列化失败 由于与另一个事务发生资源死锁,事务已回滚。
40003 语句完成未知 执行此函数期间关联的连接失败,无法确定事务的状态。
42000 语法错误或访问冲突 *StatementText 包含不可预分析或包含语法错误的 SQL 语句。

用户无权执行 *StatementText 中包含的 SQL 语句。
42S01 基表或视图已存在 *StatementText 包含 CREATE TABLECREATE VIEW 语句,并且指定的表名或视图名称已存在。
42S02 找不到基表或视图 *StatementText 包含 DROP TABLEDROP VIEW 语句,指定的表名或视图名称不存在。

*StatementText 包含 ALTER TABLE 语句,指定的表名不存在。

*StatementText 包含 CREATE VIEW 语句,查询规范定义的表名或视图名称不存在。

*StatementText 包含 CREATE INDEX 语句,指定的表名不存在。

*StatementText 包含 GRANTREVOKE 语句,指定的表名或视图名称不存在。

*StatementText 包含 SELECT 语句,并且不存在指定的表名或视图名称。

*StatementText 包含 DELETEINSERTUPDATE 语句,指定的表名不存在。

*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 包含 GRANTREVOKE 语句,并且不存在指定的列名。

*StatementText 包含 SELECTDELETEINSERTUPDATE 语句,并且不存在指定的列名。

*StatementText 包含 CREATE TABLE 语句,而约束中指定的列 (引用创建表以外的表) 不存在。

*StatementText 包含 CREATE SCHEMA 语句,并且不存在指定的列名。
44000 WITH CHECK OPTION 冲突 参数 StatementText 包含对视图表或派生自通过指定 WITH CHECK OPTION 创建的已查看表的表执行的 INSERT 语句,使受 INSERT 语句影响的一行或多行不再存在于视图表中。

参数 StatementText 包含对视图表或派生自通过指定 WITH CHECK OPTION 创建的已查看表的表执行的 UPDATE 语句,使受 UPDATE 语句影响的一行或多行不再存在于视图表中。
HY000 常规错误 发生错误,其中没有特定的 SQLSTATE,未定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY008 操作已取消 StatementHandle 启用了异步处理。 调用函数,并在完成执行之前,SQLCancel 或 SQLCancelHandleStatementHandle 上调用。 然后,在 StatementHandle 上再次调用该函数。

调用函数,并在完成执行之前,SQLCancel 或 SQLCancelHandle 从多线程应用程序中的不同线程调用 StatementHandle
HY009 无效使用 null 指针 (DM) *StatementText 是空指针。
HY010 函数序列错误 (DM) 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLExecDirect 函数时,此异步函数仍在执行。

(DM) SQLExecute、SQLExecDirectSQLMoreResults 已针对 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。

(DM) 异步执行的函数 (不是为 StatementHandle 调用此函数) ,并且调用此函数时仍在执行。

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos 已针对 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 包含定位更新或删除语句,游标由 SQLSetPosSQLFetchScroll) 定位在已删除或无法提取的行上 (。
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 提交 COMMITROLLBACK 语句,则 DBMS 产品之间不会互操作。 若要提交或回滚事务,应用程序调用 SQLEndTran

如果 SQLExecDirect 遇到执行时的数据参数,它将返回SQL_NEED_DATA。 应用程序使用 SQLParamDataSQLPutData 发送数据。 请参阅 SQLBindParameterSQLParamDataSQLPutData发送长数据

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

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

如果打开书签并且执行不支持书签的查询,驱动程序应尝试通过更改属性值并返回 SQLSTATE 01S02 (选项值更改) 将环境强制转换为支持书签的环境。 如果无法更改该属性,驱动程序应返回 SQLSTATE HY024 (属性值无效) 。

注意

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

代码示例

请参阅 SQLBindColSQLGetData示例 ODBC 程序

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

另请参阅

ODBC API 参考
ODBC 头文件