116 lines
5.7 KiB
Markdown
116 lines
5.7 KiB
Markdown
# 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)
|