企业官网建设流程全解析

1. ADOQUERY 查询报 E_FAIL 到底卡在哪

如果你在用 Delphi/C++Builder 的 ADO 组件做数据库查询，某天突然蹦出一句「数据提供程序或其他服务返回 E_FAIL 状态」，而且代码逻辑没改、数据库也没动，那大概率不是你的 SQL 写错了，而是游标位置（CursorLocation）和提供程序之间的配合出了问题。ADOQUERY 这个组件本身只是 TADOQuery 的封装，它把 SQL 语句、连接、游标模式揉在一起，一旦 cursorLocation 设成 clUseClient，而底层驱动又不支持客户端游标，查询就会在 Open/ExecSQL 阶段直接抛 E_FAIL。

E_FAIL 是一个很「泛」的 HRESULT，它不像语法错误那样给你行号，也不像连接超时那样给你明确提示，所以很多人第一反应是去查 SQL、查权限、查网络，结果绕了一大圈才发现是游标模式的问题。我试过在一个老项目里，同样的 SQL 在 SSMS 里跑得好好的，放到 ADOQUERY 里就报 E_FAIL，最后把 cursorLocation 从 clUseClient 改成 clUseServer 就通了。这不是玄学，而是客户端游标需要本地游标库（Client Cursor Engine）参与，而某些 OLE DB 提供程序（尤其是老版本或第三方驱动）并不完整支持这套机制。

这篇内容适合正在用 ADO/ADOQUERY 做数据访问、被 E_FAIL 卡住的开发者，尤其是那些连接串里混用了 Provider、Extended Properties，又手动设了 cursorLocation 的场景。我会从游标位置和服务端游标的组合切入，给你可复制的连接配置片段、最小复现步骤，以及一套排查路径，帮你判断到底是游标模式的问题，还是服务端游标本身没被正确启用。

2. 先把 TaoToken 的接入前置准备好

在讲具体配置之前，先说一下如果你需要调用大模型来做 SQL 审查、报错日志分析或者生成排查脚本，可以先把 TaoToken 的接入信息准备好。TaoToken 是一个面向开发者的模型调用平台，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。它本身不解决 ADOQUERY 的 E_FAIL，但可以帮你把报错信息、连接串片段、游标配置丢给模型做一轮快速归因，省去反复翻文档的时间。

你需要先拿到 API Key，入口在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。拿到之后，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有不同语言的调用示例。如果你只是想先验证模型能不能理解你的报错，可以直接用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 贴一段 E_FAIL 的上下文试试。

这里要强调一点：TaoToken 是模型调用入口，不是数据库中间件，也不是 ADO 的替代品。你的 ADOQUERY 该连什么数据库还是连什么数据库，TaoToken 只负责在你排查过程中提供模型侧的辅助分析。把这两件事分清楚，后面配置才不会乱。

3. cursorLocation 与 clUseServer 的可复制配置骨架

3.1 连接串里最容易踩的 Provider 与游标组合

ADOQUERY 的 E_FAIL 很多时候不是单独由 cursorLocation 引起的，而是连接串里的 Provider 和 cursorLocation 组合不匹配。下面是一个典型的 SQL Server 连接串配置，你可以直接替换服务器和库名：

// Delphi 中设置 ADOConnection 的连接串 ADOConnection1.ConnectionString := 'Provider=SQLOLEDB.1;' + 'Persist Security Info=False;' + 'User ID=your_user;' + 'Password=your_password;' + 'Initial Catalog=YourDB;' + 'Data Source=192.168.1.100;' + 'Use Procedure for Prepare=1;' + 'Auto Translate=True;' + 'Packet Size=4096;' + 'Use Encryption for Data=False;' + 'Tag with column collation when possible=False';

这段连接串本身没有指定游标位置，游标位置由 ADOQuery 的 CursorLocation 属性决定。关键点在于：SQLOLEDB.1 这个提供程序对客户端游标的支持是有限的，如果你把 ADOQuery1.CursorLocation 设成 clUseClient，再执行一个带 JOIN 或 ORDER BY 的查询，就可能触发 E_FAIL。

3.2 把 cursorLocation 改成 clUseServer 的最小改动

最直接的修复方式就是在打开查询之前，把游标位置设为服务端游标：

ADOQuery1.Close; ADOQuery1.CursorLocation := clUseServer; // 关键：使用服务端游标 ADOQuery1.SQL.Clear; ADOQuery1.SQL.Add('SELECT * FROM Orders WHERE OrderDate >= :StartDate'); ADOQuery1.Parameters.ParamByName('StartDate').Value := '2024-01-01'; ADOQuery1.Open;

如果你用的是 C++Builder，写法类似：

ADOQuery1->Close(); ADOQuery1->CursorLocation = clUseServer; ADOQuery1->SQL->Clear(); ADOQuery1->SQL->Add("SELECT * FROM Orders WHERE OrderDate >= :StartDate"); ADOQuery1->Parameters->ParamByName("StartDate")->Value = "2024-01-01"; ADOQuery1->Open();

注意，CursorLocation 的设置必须在查询打开之前完成。文档里写得很清楚：该属性设置仅对属性已经设置后才建立的连接有影响，更改 CursorLocation 不会影响现有的连接。也就是说，如果你先 Open 了连接，再改 CursorLocation，是不生效的。

3.3 连接级别与查询级别的游标继承关系

ADO 的游标位置有一个继承链：Connection 对象的 CursorLocation 会被 Recordset 继承，而 ADOQuery 作为 Recordset 的封装，也会从它关联的 ADOConnection 继承。所以你有两种设法：

第一种，在 ADOConnection 上统一设：

ADOConnection1.CursorLocation := clUseServer; ADOConnection1.Connected := True;

第二种，在 ADOQuery 上单独设：

ADOQuery1.CursorLocation := clUseServer; ADOQuery1.Open;

两种都可以，但如果你有多个 ADOQuery 共用同一个 ADOConnection，建议在 Connection 上统一设成 clUseServer，避免某个 Query 忘了设而报 E_FAIL。下面这张表可以帮你快速对照两种游标位置的差异：

3.4 什么时候不该无脑改成 clUseServer

虽然改成 clUseServer 能解决大部分 E_FAIL，但它不是万能药。服务端游标对数据源的变化更敏感，如果你需要断开连接后继续操作记录集，或者需要客户端游标提供的某些批量更新能力，clUseServer 反而会让这些功能不可用。所以正确的做法是先判断 E_FAIL 是不是由游标模式引起的，再决定改不改。

4. 验证请求与成功结果的最小复现步骤

4.1 构造一个能稳定复现 E_FAIL 的最小工程

要确认问题出在游标模式，最好的办法是做一个最小复现。新建一个 VCL Forms Application，放一个 ADOConnection、一个 ADOQuery、一个 Button 和一个 Memo。连接串用上一节的 SQLOLEDB.1 配置，然后写这样的代码：

procedure TForm1.Button1Click(Sender: TObject); begin try ADOQuery1.Close; ADOQuery1.CursorLocation := clUseClient; // 故意用客户端游标 ADOQuery1.SQL.Text := 'SELECT TOP 10 * FROM Orders ORDER BY OrderID DESC'; ADOQuery1.Open; Memo1.Lines.Add('查询成功，记录数：' + IntToStr(ADOQuery1.RecordCount)); except on E: Exception do Memo1.Lines.Add('报错：' + E.Message); end; end;

如果你的环境里客户端游标不被支持，这段代码就会在 Open 处抛出 E_FAIL。然后把 clUseClient 改成 clUseServer，再跑一次：

ADOQuery1.CursorLocation := clUseServer;

如果这次查询成功，Memo 里会显示记录数，那就基本可以确认 E_FAIL 是游标位置引起的。

4.2 用 TaoToken 模型对话辅助分析报错上下文

如果你手头的报错信息比较长，或者涉及多个组件的交互，可以把关键片段整理一下，贴到模型对话里做一轮分析。比如把连接串（去掉密码）、cursorLocation 的设置、完整的报错消息、以及你用的 Provider 版本一起发过去，让模型帮你判断是游标模式问题还是驱动兼容性问题。入口还是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，这个场景下它就是一个帮你快速梳理排查方向的工具。

4.3 成功结果的判断标准

一次成功的验证应该满足三个条件：第一，Open 不抛异常；第二，RecordCount 能返回正确数量（注意服务端游标下 RecordCount 可能返回 -1，这是正常的，可以用 EOF 循环来遍历）；第三，关闭再打开连接后，同样的查询仍然能执行。如果第三条失败，说明问题可能不在游标位置，而在连接池或事务状态。

5. 本篇常见错排查

5.1 改了 cursorLocation 还是报 E_FAIL

这种情况通常有两个原因。一是你改的位置不对，比如在 ADOQuery 已经 Open 之后才改 CursorLocation，这时候属性是只读的，改了也不生效。二是连接串里的 Provider 本身就不支持服务端游标，比如某些 ODBC 桥接的 OLE DB 提供程序。这时候可以换一个 Provider 试试，比如把 SQLOLEDB.1 换成 MSOLEDBSQL，或者反过来。

5.2 报错信息里出现「客户端游标不支持」

如果报错明确提到客户端游标，那就不要犹豫，直接把 CursorLocation 设成 clUseServer。但要注意，有些第三方组件会在内部强制设置 clUseClient，比如某些数据感知控件或报表组件。这种情况下你需要在组件打开查询之前，用代码显式覆盖它的设置。

5.3 连接串里 Extended Properties 的干扰

有些连接串会带 Extended Properties，比如Extended Properties="CursorLocation=3"，这里的 3 对应 adUseClient。如果你在代码里又设了 clUseServer，两者会冲突，最终以连接串里的为准。排查时先把 Extended Properties 去掉，用纯代码控制游标位置，确认没问题后再决定要不要加回去。

5.4 多线程下 ADOQUERY 的游标状态串扰

如果你的 ADOQuery 在多线程里使用，每个线程应该有自己的 ADOConnection 和 ADOQuery 实例，不要共享。共享连接时，一个线程改了 CursorLocation，另一个线程可能读到中间状态，导致偶发的 E_FAIL。这种问题最难查，因为不是每次都复现。建议用连接池或者每个线程独立连接来隔离。

5.5 用日志把 CursorLocation 的实际值打出来

有时候你代码里设了 clUseServer，但运行时实际值不是。可以在 Open 之前加一行日志：

Memo1.Lines.Add('当前 CursorLocation = ' + IntToStr(Ord(ADOQuery1.CursorLocation)));

clUseServer 的值是 3，clUseClient 是 2。如果打出来是 2，说明你的设置被覆盖了，往上找是谁改的。

6. 接入与排障的下一步

如果你已经把 cursorLocation 改成 clUseServer 并且验证通过，那这篇的核心问题就解决了。接下来如果你想把这类排查过程沉淀成可复用的脚本，或者需要模型帮你批量分析历史报错日志，可以走 API 接入的方式。API Key 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 Python、Node.js、curl 的示例，你可以把 E_FAIL 的上下文整理成 prompt，让模型输出排查建议。

如果你是在做长期的编码辅助或者 Agent 类工具，需要频繁调用模型来做代码审查、报错归因，可以看一下 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，它更适合这种持续性的开发场景。控制台入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，可以管理你的调用记录和额度。

最后再提醒一个实操细节：改完 CursorLocation 之后，记得把 ADOConnection 的 Connected 设为 False 再重新连接，确保新的游标设置从连接建立时就生效。很多人改完属性直接 Open，结果因为连接还是旧的，游标位置没变，误以为 clUseServer 没用。这个坑我踩过，希望你能绕过去。