IMS DL/I slice 1: CALL 'CBLTDLI' through a DB PCB on both runtimes; CardDemo PAUDBUNL proven (Part of #4893)

docs/language_status/cobolrt_rules.json

@@ -34,6 +34,15 @@
   },
   "carddemo-cobdatft": {
    "title": "CardDemo app/asm/COBDATFT.asm -- the estate's own assembler routine (no IBM manual applies; the source is the reference)"
+  },
+  "ims-apis": {
+   "title": "IBM IMS Application Programming APIs (DL/I calls, SSAs, relational operators)"
+  },
+  "ims-ap": {
+   "title": "IBM IMS Application Programming (DB PCB masks, current position in the database)"
+  },
+  "ims-codes": {
+   "title": "IBM IMS Messages and Codes, Volume 4: IMS Component Codes (DL/I status codes)"
   }
  },
  "options": {
@@ -156,7 +165,8 @@
    "prefix": "FUNC",
    "title": "intrinsic functions",
    "files": [
-    "Funcs.java"
+    "Funcs.java",
+    "Accept.java"
    ],
    "done": true,
    "about": "The intrinsic functions the translator calls.",
@@ -214,6 +224,32 @@
    "about": "The date / time services and COBDATFT, as the harness's C models do them.",
    "plumbing": []
   },
+  {
+   "id": "DLI",
+   "prefix": "DLI",
+   "title": "IMS DL/I database calls",
+   "files": [
+    "dli/DetDli.java"
+   ],
+   "done": true,
+   "about": "A batch DL/I program's CALL 'CBLTDLI' through a DB PCB on a stated database: the twin of the harness's ggdli.c (register family I).",
+   "plumbing": [
+    "refuse",
+    "dir",
+    "name8",
+    "findSeg",
+    "findFld",
+    "keyCmp",
+    "keyAt",
+    "fullword",
+    "text",
+    "dbFirst",
+    "descends",
+    "descendsType",
+    "lastInSubtree",
+    "ancestorOfType"
+   ]
+  },
   {
    "id": "DATA",
    "prefix": "DATA",
@@ -1869,6 +1905,22 @@
    "status": "MATCHED",
    "calibration": "uncalibrated"
   },
+  {
+   "id": "RT-FUNC-ACCEPT-DATE",
+   "family": "FUNC",
+   "title": "ACCEPT FROM DATE / DATE YYYYMMDD / DAY / DAY YYYYDDD / TIME: the run's clock as the unsigned integer item IBM describes, moved as that item",
+   "methods": [
+    "from"
+   ],
+   "ibm": {
+    "doc": "cobol-lr",
+    "section": "ACCEPT statement: Format 2 (system date and time)"
+   },
+   "options": [],
+   "register": [],
+   "status": "MATCHED",
+   "calibration": "uncalibrated"
+  },
   {
    "id": "RT-CICS-POINTER-IN-COMMAREA",
    "family": "CICS",
@@ -2851,6 +2903,188 @@
    "status": "MATCHED",
    "calibration": "uncalibrated"
   },
+  {
+   "id": "RT-DLI-ENTRY",
+   "family": "DLI",
+   "title": "ENTRY 'DLITCBL': each DB PCB of the PSB bound to the area IMS passes, its mask filled (DBD name, level 00, blank status, PROCOPT, sensitive segments, key feedback zero)",
+   "methods": [
+    "enter"
+   ],
+   "ibm": {
+    "doc": "ims-ap",
+    "section": "Specifying the DB PCB mask"
+   },
+   "options": [],
+   "register": [
+    "I4"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-STATE",
+   "family": "DLI",
+   "title": "The stated database: DBD / PSB configuration and seed loaded in hierarchic sequence (refused when out of order), new twins placed by segment type and sequence field, each database written at the step's end",
+   "methods": [
+    "load",
+    "loadDb",
+    "linkChild",
+    "leave",
+    "dump"
+   ],
+   "ibm": {
+    "doc": "ims-ap",
+    "section": "Hierarchic sequence"
+   },
+   "options": [],
+   "register": [
+    "I1",
+    "I2",
+    "I6"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-SSA",
+   "family": "DLI",
+   "title": "SSAs: segment name, unqualified (blank) or qualified (field, relational operator, value, ')'); AC / AJ / AK as IBM answers them; command codes, boolean qualification and missing levels refused",
+   "methods": [
+    "parseSsas",
+    "chain"
+   ],
+   "ibm": {
+    "doc": "ims-apis",
+    "section": "Segment search arguments (SSAs)"
+   },
+   "options": [],
+   "register": [
+    "I1",
+    "I5"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-QUALIFY",
+   "family": "DLI",
+   "title": "A qualification compares the field's stored bytes (C / X); a P field only where packed and logical comparison agree (both valid, one positive sign)",
+   "methods": [
+    "qualifies",
+    "packedSign",
+    "satisfies"
+   ],
+   "ibm": {
+    "doc": "ims-apis",
+    "section": "SSA relational operators"
+   },
+   "options": [],
+   "register": [
+    "I2"
+   ],
+   "status": "DIFFERS",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-FEEDBACK",
+   "family": "DLI",
+   "title": "The PCB mask after a call: status code, segment level, segment name, concatenated key and its length",
+   "methods": [
+    "feedback",
+    "status"
+   ],
+   "ibm": {
+    "doc": "ims-ap",
+    "section": "Specifying the DB PCB mask"
+   },
+   "options": [],
+   "register": [
+    "I4"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-GET",
+   "family": "DLI",
+   "title": "GU / GN / GNP and their holds: the first segment in hierarchic sequence satisfying the SSAs, from the database's start, from position, or under parentage; GE / GB / GP / GA / GK; position and parentage after the call",
+   "methods": [
+    "get",
+    "firstSatisfying",
+    "deepest",
+    "nextInSeq"
+   ],
+   "ibm": {
+    "doc": "ims-apis",
+    "section": "GU / GHU, GN / GHN, GNP / GHNP calls"
+   },
+   "options": [],
+   "register": [
+    "I1",
+    "I3"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-ISRT",
+   "family": "DLI",
+   "title": "ISRT: the segment under the parent its SSAs (or current position) locate, among its twins by sequence field; II for a key its twins hold, GE for a parent not found",
+   "methods": [
+    "isrt"
+   ],
+   "ibm": {
+    "doc": "ims-apis",
+    "section": "ISRT call"
+   },
+   "options": [],
+   "register": [
+    "I1",
+    "I3"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-CHANGE",
+   "family": "DLI",
+   "title": "REPL / DLET on the segment the previous get-hold call returned; DJ without one, DA when the I/O area changed the sequence field; DLET removes the segment's dependents",
+   "methods": [
+    "change"
+   ],
+   "ibm": {
+    "doc": "ims-apis",
+    "section": "REPL call; DLET call"
+   },
+   "options": [],
+   "register": [
+    "I1",
+    "I3"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
+  {
+   "id": "RT-DLI-CALL",
+   "family": "DLI",
+   "title": "CALL 'CBLTDLI' USING function pcb io-area [ssa ...]: the PCB the program was passed, the function's dispatch (AD for an unknown function, AM for one PROCOPT does not allow), any other DL/I call refused",
+   "methods": [
+    "call",
+    "findPcb",
+    "allows"
+   ],
+   "ibm": {
+    "doc": "ims-codes",
+    "section": "DL/I status codes"
+   },
+   "options": [],
+   "register": [
+    "I1",
+    "I5"
+   ],
+   "status": "ASSUMED",
+   "calibration": "uncalibrated"
+  },
   {
    "id": "RT-DATA-BINARY-SIZE",
    "family": "DATA",

docs/language_status/det_port_design.md

@@ -458,7 +458,9 @@ Only generator output, never a test case:
   The cross-check reads every unit, each paragraph's extent ending with its program. estate-crucible PAYMAIN, refused
   first by its COPY DATEWS collision until #4486, now translates. *Grammar gaps*: `ENTRY 'DLITCBL' USING pcb ...` (IMS DL/I batch)
   is read as a statement (a placeholder CALL, as SORT); as the program's first statement with no PROCEDURE DIVISION
-  USING it is the program's entry, its USING the program's parameters; elsewhere it translates as a hole. A reference
+  USING it is the program's entry, its USING the program's parameters; elsewhere it translates as a hole. Since #4893
+  `ENTRY 'DLITCBL'` as the first statement is the entry even when PROCEDURE DIVISION has a USING of its own (IMS
+  enters a DL/I program there, with that ENTRY's list): see "IMS DL/I" below. A reference
   modification of an intrinsic function (`FUNCTION CURRENT-DATE (1:4)`, `FUNCTION UPPER-CASE(A) (2:3)`) is handed to
   the grammar as an argument list of the same length; expr reads it as the reference modification, and gen takes the
   substring of an alphanumeric function's text (it had dropped the modification). Newly read: CardDemo DBUNLDGS,
@@ -820,6 +822,32 @@ NULL is distinct.
     reads to the end of the caller's record only (`Cobol.commarea`, register X10) and a det caller passes the bytes
     themselves (`CicsTask.link(..., area)`).
 
+## IMS DL/I (batch DL/I calls, #4893)
+
+**Slice 1: CALL 'CBLTDLI' through a DB PCB, proven on a stated database.** A batch DL/I program (IMS enters its
+`ENTRY 'DLITCBL' USING pcb ...`; CMPAT=NO, a DLI region) translates whole. Its CALLs run through the det runtime's
+`cobolrt/dli/DetDli` (det/dli.py emits them; RETURN-CODE 0 after each, register I1), and the oracle's through
+`tests/equivalence/ims/ggdli.c`, the same rules and refusals on both sides (register family I, rule family DLI).
+
+- **The database is stated, not connected.** A case's `"ims"` section names its DBD and PSB sources (read by the
+  engine's `core/ims_gen.py`) and a seed: the corpus's own HD unload, or segments the case writes
+  (`tests/tools/equivalence_ims.py`). Both sides start from it, and the database each leaves is compared segment by
+  segment, every field of the segment's layout.
+- **Modelled.** GU, GHU, GN, GHN, GNP, GHNP, ISRT, REPL and DLET; unqualified SSAs and SSAs qualified by one field;
+  the PCB mask's feedback; position and parentage; status blank, GA, GK, GE, GB, GP, II, DJ, DA, AC, AJ, AK, AD and AM.
+- **The level fixture.** `tests/equivalence/ims/fixture` (LVLDBD, LVLPSB, DLILVL, expected.txt) is a three-level
+  database with every modelled call and status. Its expected output was written from IBM's documentation and
+  committed before either runtime ran it (policy: level estates first). On its first run both runtimes printed it line
+  for line (51/51) and left the same database (`tests/cobol_mainframe/test_det_dli.py`, EQUIVALENCE_E2E=1).
+- **Proven.** CardDemo PAUDBUNL (`carddemo-paudbunl`) unloads the corpus's own DBPAUTP0 unload (22 roots, 202
+  children) through GN / GNP into two files. It is proven on 5 runs (the step and four file faults), covering 9/10
+  paragraphs and 20/22 branches. The same work made ACCEPT FROM DATE / DAY / TIME translate (`cobolrt/Accept.java`): the
+  translator had emitted a call to a method the runtime did not have.
+- **Refused (register I5).** EXEC DLI; BMP / MPP / CICS DL/I programs and the I/O PCB (IMS TM); GSAM; DL/I calls
+  other than the nine; command codes and boolean SSAs; AIBTDLI / CEETDLI; HDAM order; secondary indexes; logical
+  relationships; load mode. CardDemo's other DL/I programs stop at one of these: PAUDBLOD (CMPAT=YES, an I/O PCB),
+  DBUNLDGS (GSAM PCBs), and CBPAUP0C, COPAUA0C, COPAUS0C, COPAUS1C (EXEC DLI).
+
 ## In port_runner
 
 The combined method runs in the porting loop like any other backend, and every event lands in

docs/language_status/register/I1.md

@@ -0,0 +1,35 @@
+---
+id: "I1"
+family: "I"
+status: "ASSUMED"
+title: "DL/I database calls through a DB PCB — the stated database model"
+area: "IMS"
+summary: "CBLTDLI GU GHU GN GHN GNP GHNP ISRT REPL DLET on a stated hierarchy (DBD / PSB sources, a seed), status codes from IBM's table, RETURN-CODE 0 after each call"
+reached: "yes (CardDemo PAUDBUNL, carddemo-paudbunl, #4893)"
+---
+- **What is modelled** (#4893). A batch DL/I program: IMS enters it at ENTRY 'DLITCBL' with the PSB's DB PCBs (CMPAT=NO,
+  a DLI region), and it issues `CALL 'CBLTDLI' USING function pcb io-area [ssa ...]`. The COBOL side runs against
+  `tests/equivalence/ims/ggdli.c`, the det port against `cobolrt/dli/DetDli.java`: one rule set, one set of refusals.
+  The calls are GU, GHU, GN, GHN, GNP, GHNP, ISRT, REPL and DLET (IBM IMS Application Programming APIs, "DL/I calls
+  for database management").
+- **The database is stated, not connected.** The case names its DBD and PSB sources, which the engine's own macro
+  reader parses (`gitgalaxy/core/ims_gen.py`), and a seed: the corpus's own HD unload (I6), or segments the case writes.
+  Both sides read the same `dbd.cfg` / `psb.cfg` / `seed.<DBD>`, and each writes the database it ended with. The
+  harness compares those segment by segment, every field of the segment's copybook layout (`equivalence_ims.diff_db`).
+  The database is a hierarchy in hierarchic sequence: each parent's children by segment type in DBD order, and twins in
+  sequence-field order (I2). HIDAM, PHIDAM, HISAM and SHISAM are read alike. The HIDAM index is not a database here:
+  it only orders the roots by key, which the hierarchy already does.
+- **Status codes** (IMS Messages and Codes, Volume 4, "DL/I status codes"):
+  - blank: success.
+  - GA: an unqualified GN / GNP moved up a level. GK: it returned a segment of another type at the same level.
+  - GE: segment not found, or ISRT's parent not found. GB: GN reached the end of the database.
+  - GP: GNP with no parentage. II: ISRT of a segment whose key its twins already hold.
+  - DJ: REPL / DLET without a get-hold call just before. DA: REPL / DLET whose I/O area changed the sequence field.
+  - AC: SSA naming a segment the DBD lacks, or SSAs out of hierarchic order. AJ: invalid SSA (qualification start,
+    operator, end). AK: invalid field name. AD: invalid function. AM: function the PCB's PROCOPT does not allow.
+
+  Any other condition is refused (I5).
+- **RETURN-CODE after the call.** Each call returns 0: the C model returns 0 (GnuCOBOL stores it in RETURN-CODE), and
+  the det port stores 0. IBM does not document what the DL/I language interface leaves in register 15 for a COBOL
+  CALL. A program that reads RETURN-CODE after a DL/I call, or ends without setting it, relies on this assumption:
+  PAUDBUNL ends RETURN-CODE 0 after its last GN (GB).

docs/language_status/register/I2.md

@@ -0,0 +1,23 @@
+---
+id: "I2"
+family: "I"
+status: "DIFFERS"
+title: "Sequence-field order and SSA comparison — the stored bytes, in the data page"
+area: "IMS"
+summary: "twins and qualifications compare the field's stored bytes; a C / X key's order is the data page's (ASCII on both sides), not EBCDIC's; a P qualification only where packed and logical comparison agree"
+reached: "no (CardDemo's keys are packed and binary bytes, the same in both pages)"
+---
+- **Order.** Twins sit in the order of their sequence field's bytes, compared unsigned, on both sides. That is
+  IMS's own order for the bytes it holds. The corpus is evidence: CardDemo's unload of DBPAUTP0 (HIDAM, ACCNTID TYPE=P)
+  holds a root whose key is EBCDIC spaces (X'404040404040') after every valid packed key, which is a logical
+  comparison, not a packed one. A seed not in that order is refused: the oracle's byte order would not be the
+  estate's.
+- **DIFFERS for text keys.** The harness's data page is ASCII-family (Latin-1), so a C key holding letters and digits
+  sorts in ASCII order on both sides, where z/OS sorts it in EBCDIC order (digits after letters). This is the
+  declared collation difference of indexed files (`COLLATION` in equivalence.py), here for twin order and for the GN /
+  GNP that walks it. No proven case reaches it.
+- **Qualification** (IMS Application Programming APIs, "SSA: relational operators"). The operators are EQ, GT, LT,
+  GE, LE and NE, and their symbolic forms (`=`, `>`, `<`, `>=` / `=>`, `<=` / `=<`, `¬=` / `=¬`, each with a blank to
+  fill two bytes). A C or X field compares bytes. A P field compares arithmetically in IMS; the model compares bytes
+  only when both operands are valid packed numbers with the same positive sign (C or F), where the two comparisons
+  agree, and refuses otherwise by name. Any other field type in a qualification (Z, H, F, ...) is refused.