> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metaphi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Drive a CICS transaction

> Start a transaction from its PCT, type screens one attention key at a time, check what the program sent, and hand a live screen to a person.

An online program runs as CICS tasks. A person types a transaction ID, the program sends a map, and each key they press starts the next task with the COMMAREA the last one returned. In Harwell, the region is declared in `run.json` and the person's keys are its `screens`. No JCL is needed. Needs `harwell:runs:write`.

## 1. The map

BMS macro source goes in `BMS/`. Harwell assembles it on every run into the physical map and the symbolic map copybook, named after the mapset, so `COPY GRTSET` finds it. Do not write the symbolic map copybook yourself.

`BMS/GRTSET.bms`:

```text theme={"dark"}
GRTSET   DFHMSD TYPE=&SYSPARM,MODE=INOUT,LANG=COBOL,TIOAPFX=YES
GRTMAP   DFHMDI SIZE=(24,80)
         DFHMDF POS=(1,1),LENGTH=8,ATTRB=(ASKIP,BRT),INITIAL='GREETING'
NAME     DFHMDF POS=(3,1),LENGTH=10,ATTRB=(UNPROT,IC)
MSG      DFHMDF POS=(5,1),LENGTH=30,ATTRB=(ASKIP,NORM)
         DFHMSD TYPE=FINAL
         END
```

## 2. The program

A pseudo-conversational program: the first task sends the map and returns with `TRANSID`, and the next key starts it again with a COMMAREA.

`Progs/GREET.cbl`:

```cobol theme={"dark"}
       IDENTIFICATION DIVISION.
       PROGRAM-ID. GREET.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY GRTSET.
       01  WS-STATE  PIC X VALUE 'Y'.
       PROCEDURE DIVISION.
           IF EIBCALEN = 0
               MOVE LOW-VALUES TO GRTMAPO
               MOVE 'ENTER YOUR NAME' TO MSGO
               EXEC CICS SEND MAP('GRTMAP') MAPSET('GRTSET')
                    FROM(GRTMAPO) ERASE END-EXEC
               EXEC CICS RETURN TRANSID('GR01')
                    COMMAREA(WS-STATE) LENGTH(1) END-EXEC
           END-IF
           EXEC CICS RECEIVE MAP('GRTMAP') MAPSET('GRTSET')
                INTO(GRTMAPI) END-EXEC
           MOVE SPACES TO MSGO
           STRING 'HELLO ' NAMEI DELIMITED BY SPACE INTO MSGO
           EXEC CICS SEND MAP('GRTMAP') MAPSET('GRTSET')
                FROM(GRTMAPO) END-EXEC
           EXEC CICS RETURN END-EXEC.
```

## 3. The region and the screens

`run.json`:

```json theme={"dark"}
{
  "cics": {
    "transactions": {"GR01": "GREET"},
    "screens": [
      {"transid": "GR01", "aid": "DFHENTER"},
      {"transid": "GR01", "aid": "DFHENTER", "map": "GRTMAP", "mapset": "GRTSET",
       "fields": {"NAME": "ADA"}}
    ]
  }
}
```

| Key | Description |
| - | - |
| `transactions` | The PCT: transaction ID to program. `RETURN TRANSID` resolves through it. The first screen's transaction is the one the person starts |
| `screens` | One entry per attention key, in order. Each starts one task |
| `screens[].aid` | The key pressed: `DFHENTER`, `DFHPF1` to `DFHPF24`, `DFHPA1` to `DFHPA3`, `DFHCLEAR` |
| `screens[].fields` | What the person typed, by field name in the map. Or `typed`: `[{"at": [row, col], "value": ...}]` by cursor position |
| `screens[].erased` | Fields the person erased |
| `screens[].commarea` | On the first screen: enter the conversation part way through |
| `fct` | The FCT: each CICS file's data set and cluster geometry. A program that uses only `EXEC SQL` needs none |
| `assign` | What `EXEC CICS ASSIGN` returns |

The first screen has no fields because the program sends its map before it receives one. Every program in the unit is in the PPT, so `LINK` and `XCTL` reach any of them.

## 4. Run it

```json theme={"dark"}
run_unit {"unit_zip_b64": "<greet, zipped and base64-encoded>"}
```

The result shows each map the tasks sent as the terminal shows it, 24 rows of 80 characters, after the task log. The second screen's row 5 reads `HELLO ADA`. The structured result carries the same under `cics`: the maps sent, each field's value and attribute, the cursor, and the COMMAREA each task returned.

## 5. Check the screens

`ORACLE/screens.json` states the maps you expect, one entry per map sent, in order. `null` skips one.

```json theme={"dark"}
{"screens": [null, {"map": "GRTMAP", "fields": {"MSG": "HELLO ADA"}}]}
```

The last line of the text reads `oracle: passed`, or names the field that differs.

## Files and SQL

A program reads and writes VSAM files declared in `fct`, seeded from `CATALOG/` like any data set. `EXEC SQL` in an online program runs as in batch; seed tables in `DB/seed.sql`. A task's writes are committed when it ends or at `SYNCPOINT`, and backed out by `SYNCPOINT ROLLBACK` or an abend.

A condition the program does not handle abends the task with CICS's code: `AEIM` for `NOTFND`, `AEI9` for `MAPFAIL`, `AEI0` for `PGMIDERR`. See [Errors](https://docs.metaphi.ai/harwell/errors.md#cics-abends).

## Hand it to a person

`open_terminal` opens a browser page where a person sits at the screen and drives the transaction by hand.

```json theme={"dark"}
open_terminal {"unit_zip_b64": "<greet>"}
```

```json theme={"dark"}
{"status": "ok", "terminal": "...", "url": "https://...", "expires_in_s": 28800, ...}
```

Give the person `url`. The link is the only credential: anyone holding it can use the screen until it expires. By default the unit's own `screens` replay first, so the person continues from where they end. Pass `replay: false` to open on an empty screen.

Each key the person presses is one task. They mark each turn right or wrong, add notes, and close. Then read what they did (needs `harwell:runs:read`):

```json theme={"dark"}
read_terminal {"terminal": "..."}
```

| Field | Description |
| - | - |
| `screens` | Every key pressed, ready to write into `run.json` `cics.screens` |
| `oracle` | The turns marked right, ready to write as `ORACLE/screens.json` |
| `findings` | Their verdict and note on each turn |
| `status` | `closed` once they are done |

Write `screens` and `oracle` back into the unit, and the next `run_unit` replays and checks what the person did.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.