From 7c04148b842c0b279fe19c064bdeb0efc69a59df Mon Sep 17 00:00:00 2001 From: qiuqiuqiu Date: Thu, 25 Jun 2026 00:15:48 +0800 Subject: [PATCH] AGENTS.md: Record Subsystem A FILE STATUS progress (session 2026-06-24) --- AGENTS.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..97dd4c5 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,137 @@ +# AGENTS.md + +## Project + +COBOL 勤怠管理システム for IBM z/OS + DB2. Local dev: GnuCOBOL 3.2.0 + SQLite3 via C bridge (`tools/sqlite_bridge.c` + `tools/convert-sql.mjs`). Japanese only. + +| Subsystem | Prefix | Programs | DB access | +|-----------|--------|----------|-----------| +| A (勤怠休暇) | KIN | KIN01INP, KIN02UPD, KIN03EXP | EXEC SQL (KIN02UPD, KIN03EXP) | +| B (残業統計) | ZAN | ZAN01CHK–ZAN06UPD (6 progs) | EXEC SQL (ZAN06UPD only) | +| C (給与計算) | — | not yet implemented | — | + +Subprograms (5, no EXEC SQL): `SUB01DAT` (date), `SUB02MSG` (msg), `SUB03END` (abend), `SUB04CHK` (validation), `SUB05TIM` (rounding). + +Git remote: `https://gittea.dev/qiuqiuqiu/cobol-tna-system` (user `qiuqiuqiu`). + +## Setup & Prerequisites + +- Working directory **must** be project root (`Q:\202606AI-3\`) +- `gcc`, `cobc`, `node` on PATH +- `C:\mingw64\bin\sqlite3.dll` must exist +- `COB_CONFIG_DIR` must be set (default `C:\mingw64\share\gnucobol\config`) +- `COB_LIBRARY_PATH=bin` for subprogram DLLs + +## Build + +``` +tools\build.bat src\PROG.cbl → bin\PROG.exe (main, -x) +tools\build.bat sub\PROG.cbl → bin\PROG.dll (sub, -m) +``` + +Auto-detects main vs sub by directory. Internal: `gcc sqlite_bridge.c` → `node convert-sql.mjs` → `cobc -I"cpy"`. Preprocessed file → `tmp\*_prep.cbl`. + +## Run + +DD names bound via env vars (prefix = first 5 chars of program ID): +``` +set ZAN01R01=data\OVT-APPLY.DAT +set ZAN01W01=data\OVT-VALID.DAT +bin\ZAN01CHK.exe +``` +PARM via command line: `bin\PROG.exe YEARMONTH=202605`. + +SQLite DBs: `data/OVERTIME.db` (subsystem B), `data/kin.db` (subsystem A). + +## Testing + +``` +powershell -File test\run_subsystem_b.ps1 -Scenario all +``` + +Scenarios: `all`, `zero`, `oneside`, `multi`, `nto1`, `overlap`, `match`, `sql-error`, `branch`. + +Individual program tests: +``` +test\ZAN01\Test-ZAN01CHK.ps1 -TestCase all +``` + +Scripts handle data setup, SORT-emulation (PowerShell Sort-Object), pipeline execution, output verification. + +**Test coverage must cover**: 0件 (empty), 单边0件 (one-side zero), 复数件 (multi), N:1マッチング, 異常値, 境界値, and **all processing possibilities** (every branch, every processing function). Branch-only coverage is insufficient; every processing path must be exercised. + +DB initialization: +``` +node tools\init_db_zan.mjs # OVERTIME.db +node tools\init_db_kin.mjs # kin.db +``` + +## COBOL Conventions + +- **Format**: Fixed — Area A = col 8, Area B = col 12, `*` at col 7. 72-char line limit. +- **ID pattern**: `SSSnnFFF` (ZAN01CHK, SUB01DAT) +- **DD prefix**: first 5 chars (ZAN01R01 for ZAN01CHK) +- **No COBOL SORT** — PowerShell `Sort-Object` replaces JCL `PGM=SORT`. +- **File I/O**: sequential READ/WRITE only. No VSAM, random access, or REWRITE. +- **EXEC SQL**: source kept in DB2 syntax. `tools/convert-sql.mjs` converts to `CALL 'br_exec'`/`CALL 'br_query'`/`CALL 'br_get_col'` for SQLite. +- **Bridge COPY**: `tools/DB-COMMON.cpy` has WS-SQL-STR, SQLCODE, etc. +- **COMP-3 host variables**: declare in `compVars` map in `convert-sql.mjs` (lines 132–136). +- **Subprograms**: use GOBACK, never EXIT PROGRAM or STOP RUN. +- **Output files**: write to `data/` or `tmp/`, never project root. + +## Critical Gotchas + +- **Backup first**: `copy src\PROG.cbl src\PROG-bk-YYYYMMDD-HHmm.cbl` before editing. After session, move `src/*-bk-*` → `src/old/`. +- **INITIALIZE on PIC X** → SPACES, not `'0'`. If 88-level checks `VALUE '0'`, do explicit `MOVE '0'` after INITIALIZE. +- **FILLER length** must match record length. Mismatch shifts reads on 2nd+ iteration. +- **File encoding**: source files are UTF-8 with LF line endings. Fixed-length data files are ASCII. Always use `-Encoding UTF8` in PowerShell for source; never ASCII (corrupts Japanese comments). +- **Column accuracy**: COBOL fixed format is column-sensitive. `*` at col 7, level 01 at col 8, level 03+ at col 12+. Off-by-one causes "PROCEDURE DIVISION header missing". +- **Generated STRING blocks** in ZAN06UPD use `>>SOURCE FORMAT IS FREE`. Hand-editing requires care. +- **Template dead-code**: inherited `*-FLG` variables (WRK-FIRST-FLG, etc.) are initialized but never referenced. Remove them in code review. +- **復元は `bk/` または `production/` から**: safer than fixing corrupted files in `src/`. +- **Edit COBOL via PowerShell**: `edit` tool may mismatch whitespace due to encoding. Prefer `Get-Content -Encoding UTF8` → modify array → `WriteAllLines` UTF8 no BOM. +- **Phase 4で正常コードを「改善」しない**: working variable patterns (e.g., WRK-DIFF-MIN two-step calc) must not be refactored for readability. + +## Development Flow (7 Phases) + +| # | Phase | Exit condition | +|---|-------|---------------| +| 1 | 設計レビュー | Design review sign-off, JCL/Sort-key/COPY-book consistency checked | +| 2 | テストケース設計 | All branch-covering + all processing-path test data ready (CSV → fixed-length via `tools/make-test-data.ps1`) | +| 3 | 実装 | Compile OK | +| 4 | コードレビュー | Bidirectional trace (design↔code), dead code check, JCL/file-layout match | +| 5 | テスト実行 | All scenarios PASS (record count, field values, sort order, over/under) | +| 6 | 文書化 | Resource list & coverage doc updated, design doc reconciled | +| 7 | バックアップ・完了 | Backups moved to `src/old/`, full re-test PASS | + +## Post-Edit Checklist + +1. Move backups `src/` → `src/old/` +2. Update `使用資源一覧/{PGM-ID}_使用資源一覧.md` if COPY/CALL/SELECT/DB tables changed +3. Update `list/プログラムタイプ・ステートメントカバレッジ状況_*.txt` if statement count changed +4. Build + run all test scenarios +5. Verify all PASS +6. If COPY BOOK modified, verify all programs using it +7. Copy changed files only to `production/` (compare size or git diff; no blanket copy) + +--- + +## Progress (Session 2026-06-24) + +### Goal +Complete Subsystem A FILE STATUS consistency fix and KIN07DAI 9999ABDSOR reachability. + +### Done +- FILE STATUS + OPEN error checks added to all 6 KIN programs (KIN01INP/KIN02UPD/KIN03EXP/KIN04CHK/KIN06CLD/KIN07DAI) +- KIN06CLD: added missing 9999ABDSOR section +- All 6 programs build OK +- Subsystem A tests PASS (KIN04CHK/KIN06CLD/KIN07DAI — no tests exist for KIN01INP/KIN02UPD/KIN03EXP) +- `production/` synced (source + exe) +- Git commit + push (`47866d2`, `master → master`) + +### Design Review Note +FILE STATUS is a standard COBOL I/O implementation detail, not design-level business logic. The design documents do not need to reflect FILE STATUS declarations or OPEN STATUS checks. Code and design docs are consistent. + +### Next Session +- Subsystem A テスト拡充（KIN01INP/KIN02UPD/KIN03EXP のテストスクリプト作成） +- Subsystem B の継続（次のタスクを確認）