det: EXEC CICS READ GTEQ / GENERIC (#4270)

[squid-protocol]

Part of #4270.

The last translation gap for GenApp LGICVS01: EXEC CICS READ ... GTEQ, plus READ GENERIC GTEQ (LGIPVS01).

Spec entry (gitgalaxy/standards/cics/commands/files.py, READ)

• Options now honoured: GTEQ, GENERIC (with KEYLENGTH). IBM, EXEC CICS READ (https://www.ibm.com/docs/en/cics-ts/6.x?topic=summary-read):
  • GENERIC: "the search key is a generic key whose length is specified in the KEYLENGTH option".
  • GTEQ: "if the search for a record that has the same key (complete or generic) ... is unsuccessful, the first record that has a greater key is retrieved".
• Option rules: EQUAL | GTEQ (at most one); GENERIC requires KEYLENGTH.
• Outcomes: NOTFND RESP2 80 for the search ("An attempt to retrieve a record based on the search argument provided is unsuccessful"). The full-key READ still records 0 until spec PR 6.
• Runtime refusal: a GENERIC KEYLENGTH that is not shorter than the key (INVREQ 25) or not above zero (42; zero is undocumented). Registered as X22 in oracle_assumptions.md (summary row and section).

Translator and both runtimes

• det/cics.py: Cics._search emits CicsTask.readSearch over DetCics.Store.search. The search takes the first record in key order whose key, or its first KEYLENGTH bytes, equals RIDFLD's or (with GTEQ) is greater. READ UPDATE holds the record it found. RIDFLD is not updated, because IBM documents that only for READNEXT / READPREV.
• Refused by name:
  • GTEQ together with EQUAL
  • GENERIC without KEYLENGTH
  • a GENERIC KEYLENGTH that is ≥ the key or ≤ 0
  • a KEYLENGTH that is not a constant
  • a partial KEYLENGTH without GENERIC (as before)
  • a RIDFLD shorter than the bytes searched (X6)
  • READ GTEQ on a file named only at run time ("not a known file", ZECS)
• The stub ggcics.c GGCREAD runs the same search (GG-FLAGS GTEQ / GENERIC, read_search) and gives NOTFND RESP2 80. equivalence_cics.py passes the flags and applies the same option rules.
• Runtime tests on both sides with the same expected lines, traced from IBM's text (test_the_stub_read_gteq_and_generic_search_as_ibm_documents, test_cics_task_read_search_answers_as_the_stub_does).

Found on the way (needed to prove LGICVS01)

• Port bug: SEND TEXT FROM(x) LENGTH(n) with n past FROM's end cut the text at FROM's end. CICS sends n bytes starting at FROM (LGICVS01: FROM(WRITE-MSG-H) X(14) LENGTH(24)). The port now uses DetCics.withinRecord, which takes the bytes that follow FROM inside its record. Past the record it refuses with equivalence: WRITEQ TS events on both sides, judge tasks up to X6 (Fixes #4607, #4270) #4634's X6 mechanism (DetCics.PastFrom). A LENGTH that fits within FROM translates exactly as before.
• Equivalence harness: a case or scenario can now state "startcode" (X19), "terminal" (input to an unformatted RECEIVE) and "ts" (the TS queues the task starts with) on both sides, as the cics-crucible runner does. READQ-TS and RECEIVE events are now compared on both sides, next to equivalence: WRITEQ TS events on both sides, judge tasks up to X6 (Fixes #4607, #4270) #4634's WRITEQ-TS events, and their queue, item, resp and data are compared the same way.

Proof: tests/equivalence/genapp-lgicvs01 (new, LGCF terminal task, GENACNTL seeded as LGSETUP leaves it)

scenario	READ GTEQ	result
gteq-key-on-file	key 3 is on file	PROVED 7/7
gteq-next-key	key 11 is missing, next is 0001000005	PROVED 7/7
gteq-past-the-end	no key ≥ 0002000000 (NOTFND)	PROVED 7/7
gteq-random-in-range	RANDOM(EIBTASKN) key in 1..10	PROVED 7/7

det_port.py run genapp-lgicvs01: 51/51 translated, PROVED. Coverage is 1/1 paragraphs and 6/12 branches. Not covered: an empty GENACNTL (it reaches the X6 WRITEQ LENGTH past FROM) and the COMMAREA path, which no GenApp program takes.

det_port.py check: no other port's translated code moved. Only DetCics.java changed for them, and those changes are additive methods. As a sample I re-proved genapp-lgucvs01, carddemo-cardview and cbsa-inqacc: all PROVED.

Numbers (baseline ab94c6c -> after survey)

• blockers --baseline before: READ GTEQ was the only gap for 1 burned program and touched 3; READ GENERIC GTEQ was the only gap for 1.
• usage READ: GTEQ in 4 programs (all burned: lgicvs01, lgipvs01, ZECS000, ZECS003), GENERIC in 1 (lgipvs01).
• translated whole 76 -> 78 (non-burned 14 -> 14); lgicvs01 50/51 -> 51/51, lgipvs01 30/31 -> 31/31; holes naming READ 6 -> 4.
• Left refused: ZECS000 / ZECS003 READ FILE(ZF-FCT) GTEQ. The file is named only at run time, so its key length is unknown ("not a known file").

Crucible companion

None. The cics-crucible runner has no file control yet (the files.cfg it writes is empty), so a hand-traced READ case first needs a runner slice. Follow-up.

Rebase (onto main 6b9720a: #4634, #4633, #4603, #4638)

• Conflicts were resolved keeping both sides:
  • equivalence_cics.py: equivalence: WRITEQ TS events on both sides, judge tasks up to X6 (Fixes #4607, #4270) #4634's WRITEQ-TS events and X6 judged-to handling, plus my READQ-TS / RECEIVE events and the startcode / terminal / ts facts. _cobol_read uses equivalence: WRITEQ TS events on both sides, judge tasks up to X6 (Fixes #4607, #4270) #4634's RESP_NAMES.
  • DetCics.java: equivalence: WRITEQ TS events on both sides, judge tasks up to X6 (Fixes #4607, #4270) #4634's within / PastFrom, plus my Store.search and withinRecord, which now throws PastFrom.
  • test_equivalence_cics.py: both sets of tests.
• The evidence report was re-rendered with evidence_report.py --refresh, and --check passes.
• Re-proved after the rebase: genapp-lgicvs01, plus the 5 GenApp Db2 cases equivalence: WRITEQ TS events on both sides, judge tasks up to X6 (Fixes #4607, #4270) #4634 changed (lgacdb01, lgacdb02, lgdpdb01, lgipdb01, lgucdb01). All PROVED.
• spec: generated CicsSpec.java + ggcics_spec.h, drift test (#4270, spec PR 4) #4608 (spec PR 4) is still open. If it lands first, this PR rebases and runs python -m gitgalaxy.standards.cics regen.

Gates (local)

pr_gates.py --fast 5/5 pass and pr_gates.py --ratchets 6/6 pass, both re-run after the rebase; targeted tests pass (det translate, equivalence_cics, spec, spec equality, spec status, runtimes).

🤖 Generated with Claude Code

[github-actions]

🐦‍⬛ Muninn Security Scan

✅ No security issues found.

🐦‍⬛ Powered by Muninn · Skald Lab