Drive a CICS transaction

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:

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:

       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:

{
  "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

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.

{"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.

Hand it to a person

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

open_terminal {"unit_zip_b64": "<greet>"}

{"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):

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.

Get started

Guides

Concepts

Reference

Drive a CICS transaction

1. The map

2. The program

3. The region and the screens

4. Run it

5. Check the screens

Files and SQL

Hand it to a person

​1. The map

​2. The program

​3. The region and the screens

​4. Run it

​5. Check the screens

​Files and SQL

​Hand it to a person

1. The map

2. The program

3. The region and the screens

4. Run it

5. Check the screens

Files and SQL

Hand it to a person