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

Move backups src/ → src/old/
Update 使用資源一覧/{PGM-ID}_使用資源一覧.md if COPY/CALL/SELECT/DB tables changed
Update list/プログラムタイプ・ステートメントカバレッジ状況_*.txt if statement count changed
Build + run all test scenarios
Verify all PASS
If COPY BOOK modified, verify all programs using it
Copy changed files only to production/ (compare size or git diff; no blanket copy)

5.7 KiB Raw Blame History Unescape Escape