1. PB 游标到底解决什么问题
PowerBuilder 里做数据查询，多数人第一反应是 DataWindow。拖个控件、写条 SQL、Retrieve 一下，界面和数据全有了。但有些场景 DataWindow 并不顺手：比如你要在脚本里逐行处理结果集、要把多行数据塞进数组做二次计算、要在循环里对每一行做条件判断再决定下一步动作。这时候游标（Cursor）就是更直接的工具。
PB 的游标走的是经典四步：DECLARE CURSOR 声明、OPEN 打开、FETCH 逐行取值、CLOSE 释放。它和嵌入式 SQL 配合，把 SELECT 的结果集一行一行交到你手里，你在 DO WHILE 循环里想怎么处理就怎么处理。适合谁？适合已经会写 PB 脚本、但游标用得不够顺、或者想把游标逻辑接进 AI 辅助编码链路的开发者。
这篇聚焦两件事：一是把 DECLARE CURSOR 到 CLOSE 的完整流程讲透，包括宿主变量、SQLCODE 判断、数组暂存这些容易踩坑的细节；二是给出 TaoToken 的 settings.json 配置骨架，让你在写 PB 游标代码时能通过统一 Key/API 通道调用 AI 辅助，减少重复查文档、拼 SQL 的时间。TaoToken 在这里的角色是统一入口，不是替代 PB 本身，PB 的编译和运行还是在你本地环境完成。
2. TaoToken 前置：统一 Key 与 settings.json 骨架
在动手写游标之前，先把 AI 辅助通道配好。TaoToken 提供统一的 API 通道，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。你需要先去控制台拿一个 Key，然后把它写进 settings.json。
拿 Key 的路径：进入控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 创建一个新 Key。创建后复制出来，后面配置要用。
settings.json 的骨架如下，你可以直接复制改：
{ "taotoken": { "api_base": "https://taotoken.net/api", "api_key": "sk-你的Key粘贴在这里", "default_model": "claude-sonnet", "timeout_ms": 60000, "max_retries": 2 }, "workspace": { "pb_project_root": "D:/pb_projects/fare_report", "cursor_snippet_dir": "./snippets/pb_cursor" }, "logging": { "level": "info", "file": "./logs/taotoken_pb.log" } }几个字段说明：api_base 固定指向 https://taotoken.net/api ，不要加 UTM 参数；api_key 填你刚创建的那串；default_model 按你实际可用的模型填；timeout_ms 给 60 秒，PB 项目里 SQL 拼接有时较长，留足时间。workspace 段是给你自己项目用的，pb_project_root 指向你的 PB 工程目录，cursor_snippet_dir 用来放游标代码片段。
注意：settings.json 不要提交到公开仓库，api_key 属于敏感信息。建议在 .gitignore 里加上这个文件，或者用环境变量注入。
配好之后，你可以通过模型对话入口 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 先测一下通道是否通。如果后面你要做长期编码或 Agent 类任务，可以看 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
3. 可复制配置：DECLARE CURSOR 到 CLOSE 完整骨架
现在进入正题。下面这段是 PB 游标的标准骨架，我按你 excerpt 里的思路做了扩展，把声明、打开、循环取值、关闭四步都写全，并加上数组暂存和错误处理。
// 1. 声明游标 DECLARE C1 CURSOR FOR SELECT aln_cd, sum(cargo_aln_fare) as fare_sum FROM fare_daily_view WHERE aln_cd <> '000' AND cargo_aln_fare <> 0 AND act_fare_dt BETWEEN :emstart AND :emend GROUP BY aln_cd; // 2. 打开游标 OPEN C1; // 3. 逐行取值 string ls_aln_cd decimal ld_fare_sum string ls_rec_arr[] decimal ld_sum_arr[] integer li_i = 0 DO WHILE sqlca.SQLCODE = 0 FETCH C1 INTO :ls_aln_cd, :ld_fare_sum; IF sqlca.SQLCODE = 0 THEN li_i += 1 ls_rec_arr[li_i] = ls_aln_cd ld_sum_arr[li_i] = ld_fare_sum END IF LOOP // 4. 关闭游标 CLOSE C1;这段代码有几个关键点。第一，DECLARE CURSOR 里的 SELECT 用了宿主变量 :emstart 和 :emend，这两个变量必须在声明之前就已经赋值，否则游标打开时会报错。第二，FETCH 的 INTO 后面跟的变量类型要和 SELECT 列的类型匹配，aln_cd 是字符型对应 string，sum 结果是数值型对应 decimal。第三，DO WHILE 的判断条件是 sqlca.SQLCODE = 0，FETCH 成功时 SQLCODE 为 0，取完之后变成 100，出错则是负数。第四，循环里先 FETCH 再判断，避免把无效行写进数组。
如果你想把这段逻辑接进 AI 辅助链路，可以在 settings.json 的 cursor_snippet_dir 里放一个模板文件，比如 pb_cursor_template.srf，内容就是上面这段骨架，把表名、字段名、宿主变量名做成占位符。下次写新游标时，让 AI 按你的表结构填充占位符，你只做校验和微调。
提示：PB 的游标名在同一脚本内不能重复声明。如果你在同一个窗口或函数里要用多个游标，用 C1、C2、C3 区分，并且每个都要单独 OPEN 和 CLOSE。
4. 验证请求与成功结果
配好 settings.json 之后，怎么确认通道是通的？最简单的办法是发一个验证请求。你可以用 curl 在命令行测：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "claude-sonnet", "messages": [ {"role": "user", "content": "用一句话说明 PowerBuilder 游标 FETCH 后 SQLCODE 为 100 代表什么"} ] }'如果返回的 JSON 里有 choices 字段，并且 content 里给出了类似「结果集已取完」的回答，说明 Key 和通道都正常。这一步不需要 PB 环境，纯命令行就能验证。
接下来在 PB 里验证游标逻辑。建一个简单的窗口，放一个按钮，在 Clicked 事件里粘贴第 3 节的骨架代码，把表名换成你实际有的表，宿主变量先赋固定值。运行后点按钮，如果数组里能拿到数据，说明游标流程通了。你可以在循环里加一行MessageBox("行号", string(li_i))来观察每次 FETCH 的结果。
实测下来，最容易出问题的是宿主变量作用域。DECLARE CURSOR 里的 :emstart 和 :emend 如果是实例变量，要在声明前确保已赋值；如果是局部变量，声明和赋值要在同一个脚本块里。另外，FETCH 的 INTO 变量个数必须和 SELECT 列数一致，少一个都会报 SQLCODE 负值。
成功的结果长这样：点按钮后弹出若干次 MessageBox，每次显示递增的行号，最后数组长度等于实际行数，CLOSE 之后 sqlca.SQLCODE 回到 0。如果中途 SQLCODE 变成 -1，去 sqlca.SQLErrText 里看具体错误信息。
5. 本篇常见错排查
5.1 DECLARE CURSOR 报「游标已存在」
同一个脚本里重复声明同名游标会报这个错。PB 的游标声明是编译期检查的，不是运行期。解决办法是每个游标用唯一名字，或者把游标声明放在不同的函数/事件里。如果你确实需要在同一作用域复用，先 CLOSE 再重新 DECLARE 是不行的，必须换名字。
5.2 FETCH 后 SQLCODE 一直是 100
说明游标打开后没有取到任何行。先检查 OPEN 之后、FETCH 之前 sqlca.SQLCODE 是否为 0。如果 OPEN 就返回 100，那是 SELECT 条件过滤掉了所有数据，不是 FETCH 的问题。把 WHERE 条件放宽，或者先用 DataWindow 跑一遍同样的 SQL 确认有数据。
5.3 数组越界或数据错位
DO WHILE 循环里如果先写数组再 FETCH，会把上一次的旧值重复写入。正确顺序是 FETCH 之后立刻判断 SQLCODE，为 0 才写数组。另外数组下标从 1 开始，li_i 初始为 0，每次成功 FETCH 后先加 1 再赋值。
5.4 CLOSE 之后还能 FETCH
PB 不会阻止你在 CLOSE 之后继续 FETCH，但结果不可预期。养成习惯：CLOSE 之后不要再碰游标变量。如果你在循环里用 RETURN 或 HALT 提前退出，确保 CLOSE 在退出前执行，否则游标资源不会释放。
5.5 settings.json 里 api_key 不生效
检查三点：Key 是否复制完整（没有多余空格）、api_base 是否写成 https://taotoken.net/api （不要加 UTM）、请求头里 Authorization 格式是否为 Bearer 加空格加 Key。如果还是 401，去控制台重新生成一个 Key 试试。
6. 把游标逻辑接进 AI 辅助链路
游标代码写多了会发现，大部分工作是重复的：声明、打开、循环、关闭，变的是表名、字段、宿主变量。这部分完全可以交给 AI 辅助生成，你只做校验。配置好 settings.json 之后，你可以把第 3 节的骨架作为模板，让 AI 按你的表结构填充，然后你在 PB 里编译运行。
如果你在接入过程中遇到通道问题，优先看 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认 Key 状态，接入文档在 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 发一条消息即可。长期做 PB 编码辅助或 Agent 任务，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 更合适。
最后说一个我踩过的坑：PB 的游标在 DataWindow 的 Retrieve 之后使用，有时会因为事务对象状态不一致导致 OPEN 失败。解决办法是在 OPEN 之前加一句sqlca.of_CheckTransaction()之类的自定义检查，或者干脆把游标逻辑放在 DataWindow 之外独立的事务里。这个细节文档里不常提，但实际项目里遇到一次就记住了。
