【转】AdoQuery 报 E_FAIL？从 CursorLocation 到 TaoToken 配置的排查清单

1. AdoQuery 移动游标就报 E_FAIL问题到底出在哪如果你在 Delphi 或 CBuilder 里用TAdoQuery代码里只要出现AdoQuery1.RecordCount、AdoQuery1.Next、AdoQuery1.Last这类移动游标或读取记录数的动作程序立刻抛出“数据提供程序或其他服务返回 E_FAIL 状态”英文是Data provider or other service returned an E_FAIL status那这篇就是写给你的。这个报错的迷惑性在于它看起来像数据库连不上但你的Open明明成功了SELECT也能返回数据偏偏一碰游标就炸。很多人第一反应是去查连接串、换驱动、重装数据库客户端折腾半天没结果。实际上绝大多数情况下问题出在CursorLocation这个属性上——默认的客户端游标clUseClient在某些提供程序下不支持向后滚动或取记录数于是提供程序直接返回 E_FAIL。这篇排查清单面向三类人正在被这个报错卡住的 Delphi/CBuilder 开发者、需要把本地数据访问和远程模型调用统一配置的工程团队、以及想把 API Key 和接入通道集中管理的人。我会从CursorLocationclUseServer这个关键设置讲起给出可复制的config.toml骨架和 TaoToken 统一 Key/API 通道配置示例再附上最小复现步骤和逐项验证动作帮你判断到底是数据提供程序的问题还是配置层的问题。2. 先理解 CursorLocation为什么移动游标会触发 E_FAIL2.1 客户端游标和服务端游标的区别ADO 的游标有两种位置clUseClient客户端游标和clUseServer服务端游标。默认值通常是clUseClient。客户端游标的逻辑是提供程序把整个结果集一次性拉到本地内存之后Next、RecordCount这些操作都在本地完成。听起来很方便但问题在于——不是所有提供程序都完整实现了这套本地游标能力。当提供程序不支持某些游标操作时它不会优雅降级而是直接抛E_FAIL。服务端游标的逻辑是游标留在数据库服务端Next、RecordCount由服务端执行。只要数据库本身支持这类操作就稳定得多。2.2 为什么 RecordCount 和 Next 最容易触发RecordCount需要提供程序知道结果集的总行数。客户端游标下如果提供程序没有预先拉取全部数据就无法给出准确值某些实现会直接报错。Next涉及游标向前移动如果游标类型是只进forward-only而代码又要求可滚动也会触发同样的错误。所以你会看到那个典型现象Open成功一移动游标就 E_FAIL。这不是连接问题是游标能力协商失败。2.3 最小修复设置 clUseServer最直接的修复就是在打开查询之前设置AdoQuery1.CursorLocation : clUseServer; AdoQuery1.SQL.Text : SELECT * FROM Orders WHERE Status :Status; AdoQuery1.Parameters.ParamByName(Status).Value : Open; AdoQuery1.Open;CBuilder 写法AdoQuery1-CursorLocation clUseServer; AdoQuery1-SQL-Text SELECT * FROM Orders WHERE Status :Status; AdoQuery1-Parameters-ParamByName(Status)-Value Open; AdoQuery1-Open();注意顺序CursorLocation必须在Open之前设置。如果你在Open之后才改游标已经建立改属性不会生效甚至可能引发新的异常。3. TaoToken 前置把 Key 和接入通道统一管起来3.1 为什么数据访问项目也需要统一配置很多团队的数据访问层和模型调用层是分开配置的数据库连接串写在一个 ini 里模型 API Key 散落在各个开发者的环境变量里。一旦要换 Key、加通道、做审计就非常痛苦。TaoToken 提供的是统一的 Key 管理和 API 通道官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。它的价值在于你不需要在每个项目里硬编码不同的 Key而是通过一个统一的 API 通道去调用模型能力。对于 Delphi/CBuilder 这种需要同时处理本地数据访问和远程模型调用的场景把配置集中到一份config.toml里维护成本会低很多。3.2 获取 Key 和配置通道先到控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建好之后把 Key 填进下面的配置文件。如果你需要长期做编码或 Agent 类任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先验证模型是否通用模型对话页面https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。4. 可复制配置config.toml 骨架与 AdoQuery 参数对照4.1 config.toml 骨架下面这份配置把数据库访问和 TaoToken 通道放在一起你可以直接改成自己的值# config.toml [app] name delphi-ado-demo env dev [database] provider SQLOLEDB server 127.0.0.1 database TestDB trusted_connection true # 关键服务端游标避免 E_FAIL cursor_location clUseServer command_timeout 30 [taotoken] base_url https://taotoken.net/api api_key sk-your-key-here default_model claude-sonnet timeout_seconds 60 [taotoken.retry] max_attempts 3 backoff_ms 5004.2 连接串与 CursorLocation 对照表配置项推荐值作用不设置的后果ProviderSQLOLEDB / MSOLEDBSQL指定数据提供程序版本不匹配可能直接连不上CursorLocationclUseServer游标留在服务端移动游标报 E_FAILCommandTimeout30命令超时秒数长查询被误判为失败LockTypeltReadOnly只读锁减少冲突并发时可能锁表CacheSize50每次取的行数大批量时内存压力大4.3 在代码里读取配置并应用uses System.IniFiles, Data.DB, Data.Win.ADODB; procedure TForm1.SetupQuery; var Cfg: TIniFile; begin Cfg : TIniFile.Create(config.ini); try AdoQuery1.Connection : AdoConnection1; // 关键先设游标位置再打开 AdoQuery1.CursorLocation : clUseServer; AdoQuery1.CacheSize : Cfg.ReadInteger(database, CacheSize, 50); AdoQuery1.SQL.Text : SELECT TOP 100 * FROM Orders; AdoQuery1.Open; finally Cfg.Free; end; end;如果你用的是 TOML 解析库把上面的config.toml读进来把cursor_location映射到clUseServer即可。核心原则不变游标位置在Open之前确定。5. 验证请求最小复现步骤与成功结果5.1 最小复现步骤先故意用默认的clUseClient复现一次确认你遇到的就是这个问题AdoQuery1.CursorLocation : clUseClient; // 故意用客户端游标 AdoQuery1.SQL.Text : SELECT * FROM Orders; AdoQuery1.Open; ShowMessage(IntToStr(AdoQuery1.RecordCount)); // 这里大概率抛 E_FAIL如果这一步报错把clUseClient改成clUseServer重新编译运行AdoQuery1.CursorLocation : clUseServer; AdoQuery1.SQL.Text : SELECT * FROM Orders; AdoQuery1.Open; ShowMessage(IntToStr(AdoQuery1.RecordCount)); // 正常返回行数 AdoQuery1.Next; // 正常移动5.2 验证 TaoToken 通道是否通配置好 Key 之后用一条最小请求验证通道curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-your-key-here \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping}] }返回里能看到正常的choices结构说明 Key 和通道都没问题。如果返回 401检查 Key 是否复制完整返回 404检查base_url是否写成了https://taotoken.net/api。5.3 成功结果长什么样AdoQuery 这边RecordCount返回真实行数Next能连续移动到最后一行Last能跳到末尾不再抛 E_FAIL。TaoToken 这边请求返回 200响应体里有模型输出。两边都通说明数据访问层和模型调用层都配置正确。6. 本篇常见错排查清单6.1 E_FAIL 相关错误设置 clUseServer 后仍报 E_FAIL。检查提供程序版本。SQLOLEDB较老某些新数据库建议换MSOLEDBSQL。连接串里的Provider和实际安装的驱动要匹配。错误CursorLocation 设置了但没生效。确认设置顺序在Open之前。如果查询已经打开先Close改属性再Open。错误RecordCount 返回 -1。某些游标类型不支持记录数。改用clUseServer加ltReadOnly或者用SELECT COUNT(*)单独取总数。6.2 配置层相关错误TaoToken 请求 401。Key 没填对或者Bearer后面多了空格。到 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新复制一次。错误请求超时。把timeout_seconds调大或者检查网络出口是否稳定。重试配置里的max_attempts可以适当增加。错误模型名不存在。到模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认可用模型名别凭记忆写。6.3 判断是提供程序还是配置层一个简单的判断方法如果Open就失败多半是连接串或提供程序问题如果Open成功但移动游标失败基本就是CursorLocation配置问题如果本地 AdoQuery 正常但 TaoToken 请求失败那是 Key 或通道配置问题。把这三层分开验证定位会快很多。7. 把配置固定下来别每次重踩排查完这一轮建议你把CursorLocation : clUseServer写进项目的基础查询封装里而不是每个TAdoQuery单独设。新建查询时统一走一个工厂方法游标位置、超时、缓存大小都从config.toml读这样下次换数据库或换提供程序时只改配置不改代码。TaoToken 这边同理Key 和base_url集中在一处别散落在各个单元里。需要长期跑编码或 Agent 任务的话Coding Plan 的通道更稳https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入过程中遇到报错先翻文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 大部分错误码都有对应说明。控制台里可以随时看 Key 的使用情况https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。