ironwork cobolwork GitHub

ironwork · Features

What ironwork runs today, and how it matches z/OS.

Each run on this page is ironwork 0.7.0, and its program is kept with this site, so every output can be reproduced.

Compiler options

IBM’s options, and what each does in ironwork

The options that change what a program computes are honoured as IBM’s compiler honours them.

CBL and PROCESS cards set them. The spellings and abbreviations come from IBM’s own table of 85 options, which ironwork shares with cobolwork, and the defaults are IBM’s. Every option in the table is accepted by name; the ones below change what a program does.

OptionDefaultEffectSupport
ARITH(COMPAT|EXTEND)COMPATPICTUREs and literals up to 18 or 31 digits; fixed-point intermediates of 30 or 31 digits; floating-point intermediates in long or extended hexadecimal floating pointimplemented
TRUNC(STD|OPT|BIN)STDBinary stores: STD cuts to the PICTURE, BIN keeps what the field holds, and OPT keeps the binary value and reports each store where decimal and binary truncation disagree, since IBM leaves that result to the generated codeimplemented
NUMPROC(NOPFD|PFD)NOPFDHow the signs of zoned and packed data are handled. NUMPROC(MIG), removed in V5, is refusedimplemented
CODEPAGE(ccsid)1140The EBCDIC code page of storage and literals: any of the 21 single-byte pages, and any other is refusedimplemented
SSRANGENOSSRANGESubscripts, reference modification and OCCURS DEPENDING ON counts checked at run timeimplemented
DYNAMNODYNAMA CALL of a literal loads the program at run time, as a CALL of an identifier doesimplemented
FASTSRTNOFASTSRTDFSORT does the I/O of a SORT’s USING and GIVING files where IBM’s rules allow, and each file whose FILE STATUS it leaves alone is reportedimplemented
ADVADVA print file’s control character is a byte before each record, or under NOADV the record’s first byteimplemented
THREAD, DLL, RENT, DBCSNOTHREAD, NODLL, RENT, DBCSChecked for object-oriented programs, which IBM compiles with THREAD and DLL; a missing one is a warningimplemented
COMPILE, NOCOMPILE(W|E|S)NOCOMPILE(S)The severity at which a compile stops short of running the programimplemented
NUMCHECK, ZONECHECK, PARMCHECK, INITCHECKoffChecks of numeric data, CALL arguments and uninitialised items. NUMCHECK and ZONECHECK test each sender a statement reads: MSG warns, and ABD ends the run with U4038. PARMCHECK fills a buffer after WORKING-STORAGE before each CALL and checks it after. INITCHECK warns at compile time of items that may be used before a value is set. ZON(LAX) tolerates the redefinitions IBM’s examples show, and data no statement changes is reported at compile timeimplemented
ZONEDATA, INVDATA, ZWBIBM’sHow invalid zoned and packed data is treated, and whether a sign is ignored when zoned data is compared with alphanumericimplemented
OPTIMIZE(0|1|2)0At 1 and 2, under NOINVDATA, an unsigned zoned integer compared with zero or with one of its own length is compared by its bytes, as IBM’s example shows. --optimize=N gives the compiler invocation’s level, and a card outranks itimplemented
APOST/QUOTE, CURRENCY, NSYMBOLIBM’sWhat the figurative constant QUOTE is, the default currency symbol, and whether N literals are national or DBCS. NSYMBOL(DBCS) makes N literals and PICTURE N items DBCS, and they run, with PICTURE G and USAGE DISPLAY-1, under the eleven mixed CCSIDsimplemented
DISPSIGN, INTDATE, QUALIFYIBM’sHow DISPLAY shows a sign, how the date functions number days, and how far qualification extendsimplemented
INITIAL, VLRoff, IBM’sPrograms in their initial state on every CALL, and variable-length record checksimplemented
VSAMOPENFS(COMPAT|SUCC)COMPATThe file status of an OPEN that verifies an indexed or relative data set a run left open for output, as only an abend under TRAP(OFF) leaves one: 97 under COMPAT, 00 under SUCCimplemented

The remaining options govern listings, object code, debugging aids and the compile environment, such as LIST, MAP, ARCH and TEST, and do not change what a program computes. ironwork’s own flags, -silent, -strict-sort-keys, -warnings-block, -debug, --dialect and --compliance, are under Run.

Abends

Abend where z/OS would abend

Bad data stops the run where it would stop on z/OS, with the same completion code.

Spaces moved over a zoned field leave X'40' in every byte, and a 4 is no valid sign. The ADD that follows is a data exception on the machine, and in ironwork.

payadd.cbl
       01  WS-AMOUNT   PIC S9(5)     VALUE ZERO.
       01  WS-RAW      REDEFINES WS-AMOUNT PIC X(5).
       PROCEDURE DIVISION.
           MOVE SPACES TO WS-RAW
           ADD 1 TO WS-AMOUNT
$ ironwork run payadd.cbl; echo $?
payadd.cbl:9:21: ABEND S0C7: Data exception
240
  • 0–238the program’s RETURN-CODE, when the run ends normally
  • 239a RETURN-CODE outside 0–238, or of 239, which standard error gives
  • 240an abend: a system or user completion code, a CICS abend code, the file status of an unhandled I/O failure, or SQL and SQLR
  • 241no program to run: compile errors, including a construct not supported yet
  • 242code generation refused a construct, under --vm
  • 243the VM stopped at a construct it does not run yet
  • 244a construct ironwork does not run: an IRONWORK, EXEC or JAVA abend
  • 245the source, JCL or load module cannot be read
  • 246usage
  • 255an internal error: ironwork panicked

run, cics and job keep 239 and above for the ends ironwork gives a run, and --exit-code gives cobolwork’s verdicts instead: 0 for RETURN-CODE 0, 1 for another, 2 for usage or an input that cannot be read, 3 for an abend, 4 refused, 5 stopped and 70 internal. check and compile exit with the compile’s return code.

Completion codes

Abends carry the codes z/OS gives.

  • S0C7: a data exception.
  • S0C4: a LINKAGE item with no address.
  • S806: a program CALL cannot find.
  • CEE3ABD: a user completion code, U0999 for abend code 999.
  • U4038: a Language Environment condition nothing handles.

ironwork’s own

Where ironwork cannot do what z/OS would, the run ends and says why.

  • EXEC: an EXEC statement with nothing to run it, such as EXEC SQL with no database, or EXEC DLI.
  • JAVA: a Java class reached.
  • SQL: a database session that fails, or an answer with no Db2 SQLCODE.
  • SQLR: a call the SQL recording does not hold.
  • IRONWORK: the rest, among them EXEC CICS outside a CICS task, an object reference used after it was freed, a service called with fewer arguments than it takes, and sort control statements in DD IGZSRTCD.

Subscripts

An overrun stays inside the run unit.

SSRANGE is honoured, including for OCCURS DEPENDING ON counts. Without it a subscript can reach anywhere in the run unit’s storage, as on z/OS, but never outside it.

What runs today

Subset the interpreter runs

Batch COBOL runs today; a construct outside the subset is refused at compile time or, where only the run can find it, ends the run.

SORT and MERGE, Report Writer, EXEC SQL and CICS have sections of their own below.

tools/census.py runs ironwork check over a sample of a COBOL corpus and tallies why programs are refused, which is how the next gaps are chosen.

Source

Fixed-format source compiles as written, copybooks included.

  • Sequence numbers, continuation and *> comments.
  • CBL and PROCESS cards.
  • COPY with REPLACING: whole words, pseudo-text, ==:TAG:== inside words, LEADING and TRAILING, nested.

Limit: free-format source is refused.

Data

Records are laid out byte for byte from their descriptions.

  • Sections: WORKING-STORAGE, LOCAL-STORAGE, FILE SECTION and LINKAGE SECTION.
  • Usages: DISPLAY, BINARY, COMP-5, PACKED-DECIMAL, COMP-1, COMP-2, NATIONAL, POINTER and INDEX.
  • Clauses: numeric-edited and alphanumeric-edited PICTUREs; VALUE, REDEFINES, OCCURS with KEY, INDEXED BY and DEPENDING ON, SIGN, and level-88 conditions with THRU ranges.

Under ARITH(EXTEND) a zoned item of up to 31 digits is packed in parts where one PACK cannot take it. A group that holds its own OCCURS DEPENDING ON object receives data at its maximum length, as IBM lists for MOVE, READ INTO and the rest.

Collating sequences

Comparisons and lookups follow the alphabet the program names.

SPECIAL-NAMES ALPHABET (EBCDIC, NATIVE, STANDARD-1, STANDARD-2, or literals with THROUGH and ALSO) and PROGRAM COLLATING SEQUENCE, which a contained program shares. The sequence orders alphanumeric comparisons, condition names, EVALUATE, SEARCH ALL, MAX and MIN, and gives HIGH-VALUE, LOW-VALUE, CHAR and ORD.

Limit: national and numeric comparisons keep their own order.

Procedure

Control flow, data movement, arithmetic and string handling run.

  • Control: sections and paragraphs, IF, EVALUATE, PERFORM with THRU, TIMES, UNTIL, VARYING or inline, EXIT PARAGRAPH, SECTION and PERFORM, NEXT SENTENCE, GO TO, GOBACK and STOP RUN.
  • Data: MOVE with editing and de-editing, INITIALIZE, SET, STRING, UNSTRING, and INSPECT with TALLYING, REPLACING or CONVERTING.
  • Arithmetic: COMPUTE, ADD, SUBTRACT, MULTIPLY and DIVIDE.
  • Other: SEARCH, DISPLAY and ACCEPT; subscripts, reference modification, LENGTH OF, ADDRESS OF, and 82 intrinsic functions, SQRT, NUMVAL-C and INTEGER-OF-DATE among them.

SEARCH ALL

A table lookup misses what IBM’s would miss.

SEARCH ALL is a binary search on the table’s keys, as IBM’s is, so a table that is not in key order misses entries a serial SEARCH would find. Its keys compare in the program collating sequence.

Subprograms

A run unit of many programs shares memory as it does on z/OS.

  • Several and nested programs per source.
  • Static and dynamic CALL USING BY REFERENCE, BY CONTENT, BY VALUE and OMITTED, with RETURNING and ON EXCEPTION.
  • CANCEL; IS INITIAL and IS RECURSIVE; RETURN-CODE.

Every program in a run shares one memory, and LOCAL-STORAGE starts afresh on every CALL.

Files

Sequential and VSAM files return the file status codes programs test.

  • Organisations: sequential, line-sequential, indexed (VSAM KSDS) and relative (RRDS), with ACCESS SEQUENTIAL, RANDOM and DYNAMIC.
  • Keys: RECORD KEY, ALTERNATE RECORD KEY WITH DUPLICATES and RELATIVE KEY.
  • Statements: OPEN INPUT, OUTPUT, EXTEND and I-O; READ NEXT and PREVIOUS, KEY IS, WRITE, REWRITE, DELETE and START with INVALID KEY; OPTIONAL files.
  • Areas: SAME RECORD AREA, and SAME AREA for VSAM files.

Print files

Print output carries the control characters a printer expects.

A sequential file that WRITE … ADVANCING names, that has LINAGE in its FD, or that holds a report carries a printer control character on each record: ASA when every WRITE … ADVANCING of the file says AFTER, a machine code when one says BEFORE.

Under ADV, the default, it is a byte before the record, so the DD’s records are a byte longer than the FD’s; NOADV makes it the record’s first byte.

Language Environment services

Programs that call Language Environment for dates, times, messages and storage run.

A CALL that finds no program of the name reaches the service:

  • CEE3ABD.
  • CEEDAYS, CEEDATE, CEEDATM, CEESECS and CEEDYWK, for dates and times by picture string.
  • CEELOCT, CEEGMT, CEEUTC and CEEGMTO, which read --clock.
  • CEEMOUT, CEE3DMP, CEEGTST and CEEFRST.

Each returns its 12-byte feedback code, and COPY CEEIGZCT names the 723 symbolic feedback codes when no library holds it.

Limit: a service outside this list abends S806, naming it.

Object-oriented COBOL

Classes written in COBOL run in the run unit.

As Enterprise COBOL has them for Java interoperability: CLASS-ID with INHERITS, FACTORY and OBJECT data, methods, and INVOKE with NEW, SELF and SUPER. Object references are the JNI’s local and global references, and using a freed one abends, naming where it was made and where it was freed.

Limit: Java classes are checked, not run: reaching one ends the run with ABEND JAVA. As IBM requires, a CBL or PROCESS card gives such a program THREAD and DLL, or it is refused.

Coming soonrefused

A construct ironwork does not run yet is refused at compile time where it can be.

Refused in 0.7.0:

  • ALLOCATE.
  • PICTURE U and DYNAMIC LENGTH, by name.
  • The Report Writer precompiler’s extensions, by name.
  • Free-format source, which --compliance extended reads with a warning.

EXEC DLI is checked when compiled, and a run that reaches it ends ABEND EXEC. A Language Environment service outside the list above abends S806, naming it.

Sort and merge

DFSORT key order

Sorted output comes out in the order DFSORT gives.

A SORT or MERGE compares zoned and packed keys as DFSORT compares ZD and PD fields, so no bytes in a key are a data exception, and a key of spaces sorts as zero. -strict-sort-keys reads each key as the program would instead, and the same record abends S0C7 at its RELEASE.

sortkey.cbl
       SD  SORT-FILE.
       01  SORT-REC.
           05  SR-QTY      PIC S9(3).
           05  SR-RAW      REDEFINES SR-QTY PIC X(3).
           05  SR-ITEM     PIC X(5).
       PROCEDURE DIVISION.
           SORT SORT-FILE ON ASCENDING KEY SR-QTY
               INPUT PROCEDURE IS FEED
               OUTPUT PROCEDURE IS SHOW-ALL
           GOBACK.
       FEED.
           MOVE 200 TO SR-QTY MOVE 'BOLTS' TO SR-ITEM
           RELEASE SORT-REC
           MOVE SPACES TO SR-RAW MOVE 'NUTS' TO SR-ITEM
           RELEASE SORT-REC
           MOVE 100 TO SR-QTY MOVE 'PINS' TO SR-ITEM
           RELEASE SORT-REC.
$ ironwork run sortkey.cbl
NUTS
PINS
BOLTS
$ ironwork run sortkey.cbl -strict-sort-keys; echo $?
sortkey.cbl:25:12: ABEND S0C7: Data exception
240

SORT and MERGE

Programs that sort run with no sort product installed.

  • SD files, and ascending and descending keys anywhere in the record.
  • WITH DUPLICATES IN ORDER.
  • USING and GIVING files, or INPUT and OUTPUT PROCEDURE with RELEASE and RETURN.
  • SORT of a table by its keys.
  • SORT-RETURN and the other sort special registers.

Records are sorted in memory, and records with equal keys keep their input order.

Key order

Keys compare in the sequence the program names.

Alphanumeric keys follow the COLLATING SEQUENCE phrase, else, for a file, the program collating sequence, else EBCDIC. Zoned and packed keys compare as DFSORT compares them, other numeric keys by value.

FASTSRT

Checked mode reports each FILE STATUS that FASTSRT leaves alone.

FASTSRT and NOFASTSRT, the default, on a CBL or PROCESS card choose who does the I/O of USING and GIVING files, as on z/OS. Under FASTSRT, each file IBM’s rules keep from DFSORT is reported with the reason.

$ ironwork run fastsrt.cbl --dd INDD=fastsrt.txt:text --dd OUTDD=sorted.txt:text
ironwork: 22:12: SORT SORT-FILE: FASTSRT: DFSORT does the I/O of USING IN-FILE, so its FILE STATUS IN-FS is not updated by the SORT (-silent stops these reports)
ironwork: 22:12: SORT SORT-FILE: FASTSRT: DFSORT does the I/O of GIVING OUT-FILE, so its FILE STATUS OUT-FS is not updated by the SORT (-silent stops these reports)
IN-FS XX OUT-FS XX

fastsrt.cbl sets both FILE STATUS fields to XX, then sorts one file into another under CBL FASTSRT. Without the card the SORT sets both to 00, and ironwork reports that under FASTSRT DFSORT would do each file’s I/O and leave its FILE STATUS alone. Assumptions S1 to S17 hold what the manuals leave open.

Report Writer

Reports as IBM’s precompiler would print them

Report Writer programs run without IBM’s precompiler.

Enterprise COBOL takes a REPORT SECTION only through IBM’s COBOL Report Writer Precompiler, so ironwork runs a report as the precompiler’s output would run. Each line is a WRITE AFTER ADVANCING to the report’s file, and its record carries an ASA control character.

rwsales.cbl
       RD  SALES CONTROLS ARE FINAL WS-BRANCH PAGE LIMIT 60.
       01  TYPE PAGE HEADING LINE 1.
           05  COLUMN 1  PIC X(6)  VALUE 'BRANCH'.
           05  COLUMN 12 PIC X(6)  VALUE 'AMOUNT'.
       01  SALE-LINE TYPE DETAIL LINE PLUS 1.
           05  COLUMN 1  PIC X(6)  SOURCE WS-BRANCH
                                   GROUP INDICATE.
           05  S-AMT COLUMN 10 PIC ZZ,ZZ9.99 SOURCE WS-AMOUNT.
       01  TYPE CONTROL FOOTING WS-BRANCH LINE PLUS 1.
           05  COLUMN 1  PIC X(5)  VALUE 'TOTAL'.
           05  B-TOT COLUMN 10 PIC ZZ,ZZ9.99 SUM S-AMT.
       01  TYPE CONTROL FOOTING FINAL LINE PLUS 2.
           05  COLUMN 1  PIC X(3)  VALUE 'ALL'.
           05  COLUMN 9  PIC ZZZ,ZZ9.99 SUM B-TOT.
$ ironwork run rwsales.cbl --dd REPORTDD=sales.txt:text && cat -v sales.txt
^LBRANCH     AMOUNT
NORTH       120.50
             75.25
TOTAL       195.75
SOUTH     1,300.00
TOTAL     1,300.00

ALL       1,495.75

The program GENERATEs SALE-LINE twice for NORTH and once for SOUTH. The file’s records begin with ASA characters, 1 for the page eject, a space for single spacing and 0 for the double space before ALL, which a :text DD shows as a form feed and line spacing.

Report description

Report descriptions compile as written.

  • FD REPORT IS.
  • RD with CONTROLS, FINAL included, PAGE LIMIT, HEADING, FIRST DETAIL, LAST DETAIL, FOOTING, LINE LIMIT and a literal CODE.
  • Report groups of every TYPE with LINE, NEXT GROUP, COLUMN, PICTURE with editing, SOURCE, VALUE, SUM with UPON and RESET ON, GROUP INDICATE, BLANK WHEN ZERO, JUSTIFIED and SIGN.

INITIATE, GENERATE, TERMINATE

Control breaks, page breaks and totals print in IBM’s order.

  • GENERATE of a DETAIL group, or of the report for summary reporting.
  • Control footings minor to major, and headings major to minor.
  • Page footing and heading on each new page; PAGE-COUNTER and LINE-COUNTER.
  • DECLARATIVES hold USE BEFORE REPORTING, with SUPPRESS PRINTING and PRINT-SWITCH.

Refused by name

The precompiler’s extensions are refused by name.

OCCURS, PRESENT WHEN, multiple LINES and COLUMNS, OR PAGE, STYLE, FUNCTION and the rest. Assumptions RW1 to RW13 hold what the manuals leave open.

EXEC SQL

SQL against PostgreSQL, or a recording of a run

Programs with embedded SQL run without Db2: against PostgreSQL, or from a recording with no database.

--sql-db runs EXEC SQL against PostgreSQL. --sql-record writes each call and its answer to a text file a person can read and edit, and --sql-replay answers from that file. custq.cbl selects customers 2 and 9 from a table that holds 1 and 2, and this recording of it was made against PostgreSQL 14.19.

custq.rec
# ironwork sql recording 1
# source: PostgreSQL 14.19 (Debian 14.19-1.pgdg12+1) at 127.0.0.1:55491/ironwork
@ 1 CUSTQ:3:f490308e SELECT
> int:2
< 0 00000 rows=0
= char:"GLOBEX" | dec:-123.45
@ 2 CUSTQ:4:f490308e SELECT
> int:9
< 0 00000 rows=0
@ 3 CUSTQ:0:d0f73cbc COMMIT
< 0 00000 rows=0
$ ironwork run custq.cbl --sql-replay custq.rec
SQLCODE     0 GLOBEX                  -123.45
SQLCODE   100 SQLSTATE 02000

What runs

Single-row statements, cursors and dynamic SQL run, with Db2’s conversions.

  • Single-row statements, cursors WITH HOLD and positioned changes.
  • PREPARE, EXECUTE, EXECUTE IMMEDIATE and cursors declared for a prepared statement, under Db2 13’s rules and SQLCODEs. DESCRIBE, PREPARE … INTO and USING DESCRIPTOR are refused by name until the SQLDA is read.
  • COMMIT, ROLLBACK and CICS SYNCPOINT.
  • Host variables and indicators converted by Db2’s rules.
  • The SQLCA and WHENEVER.

A normal end commits and an abend rolls back, as the recording’s closing COMMIT shows.

Checked when compiled

A host variable that does not resolve fails the compile.

EXEC SQL INCLUDE works as COPY, and SQLCA and SQLDA are built in when no library holds them.

Limit: with neither --sql-db nor --sql-replay, the first SQL statement reached ends the run as ABEND EXEC.

Replay

A recorded run replays with no database.

Strict replay, the default, answers call n from the recording’s call n; --sql-replay-mode keyed answers each call from the first unused recorded call with the same statement and inputs.

Limit: a call the recording does not hold abends SQLR, naming both calls.

TLS and Db2

The main build keeps no dependencies.

TLS to PostgreSQL is a separate build, tls/, on rustls. docs/sql-runtime.md specifies the runtime, with what Db2 12.1 for Linux settled.

CICS and BMS

CICS task, and 3270 terminal for its maps

A CICS transaction runs without a CICS region, with its screens on a 3270 terminal.

ironwork cics runs a program as the first program of a CICS task, with the transaction ID, terminal, user and COMMAREA the command line gives, and the EXEC interface block in IBM’s layout. The task ends with RETURN TRANSID’s COMMAREA written out, so a pseudo-conversation runs one task at a time.

orders.cbl
           MOVE LOW-VALUES TO ORDMAPO
           MOVE 'ENTER AN ORDER' TO MSGO
           EXEC CICS SEND MAP('ORDMAP') MAPSET('ORDSET') ERASE
           END-EXEC
           EXEC CICS RECEIVE MAP('ORDMAP') MAPSET('ORDSET')
               RESP(WS-RESP) END-EXEC
           IF EIBAID = DFHENTER
               MOVE SPACES TO MSGO
               STRING 'ORDER TAKEN FOR ' CUSTI DELIMITED BY SIZE
                   INTO MSGO
               EXEC CICS SEND MAP('ORDMAP') MAPSET('ORDSET')
                   DATAONLY END-EXEC
           END-IF
           EXEC CICS RETURN END-EXEC.
orders.screens
type 3 12 ACME
type 4 12 7
ENTER
$ ironwork cics orders.cbl --transid ORD1 --screens orders.screens
orders.cbl: informational: IGYPS2091-W not given: the program ends with EXEC CICS RETURN, which the CICS translator turns into a CALL; --cics-return-warning=always gives the warning, =never drops this note
--- screen 1 ---
 ORDER ENTRY

 CUSTOMER:
 QUANTITY:

 ENTER AN ORDER
--- screen 2 ---
 ORDER ENTRY

 CUSTOMER: ACME
 QUANTITY: 007

 ORDER TAKEN FOR ACME
ironwork: the task ended

COPY ORDSET reads ORDSET.bms, beside the program, and gives the symbolic map. QUANTITY is a NUM field, so the 7 lands right-justified and zero-filled. Rows 7 to 24 of each screen are blank and left out here.

Program control

Transfers and condition handling work as a transaction expects.

  • RETURN with TRANSID and COMMAREA, LINK, XCTL and ABEND.
  • RESP, RESP2 and NOHANDLE.
  • HANDLE CONDITION with ERROR, IGNORE CONDITION, PUSH and POP HANDLE, and HANDLE ABEND with PROGRAM, LABEL, CANCEL and RESET, one exit per logical level.

Abends

A task fails with the abend code IBM documents.

A condition nothing handles ends the task with the AEIx abend IBM documents for it, AEIL for FILENOTFOUND among them, and a program check is ASRA. CEE3ABD is a transaction abend with its code as the four-digit ABCODE.

Services and queues

Timing, storage, locking and queue services run.

  • ASKTIME, FORMATTIME, ASSIGN, GETMAIN, FREEMAIN, ADDRESS, SYNCPOINT, ENQ, DEQ, DELAY, SEND TEXT and WRITE OPERATOR.
  • Temporary-storage and transient-data queues.

CEEMOUT and CEE3DMP write to transient data queue CESE.

File control

A transaction reads and updates VSAM KSDS and RRDS files.

  • READ with GENERIC, GTEQ and UPDATE.
  • WRITE, REWRITE, DELETE and UNLOCK.
  • Browsing with STARTBR, READNEXT, READPREV, RESETBR and ENDBR.

BMS maps

Maps come from BMS source, with no assembly step.

COPY of a mapset reads NAME.bms (DFHMSD, DFHMDI, DFHMDF) from the copy libraries and gives the symbolic map the BMS assembly would. SEND MAP, RECEIVE MAP, SEND CONTROL and RECEIVE work on a 3270 display that speaks the 3270 data stream.

A terminal to connect to

A tester drives the transaction from a 3270 emulator.

--serve HOST:PORT is a TN3270 server that c3270 or x3270 connects to, running pseudo-conversations task after task. --transaction TRAN=PROGRAM names the program each transaction runs.

Limit: one terminal at a time.

CICS flagWhat it does
--transid TThe transaction that started the task, as EIBTRNID reports it. --termid, --userid, --applid and --sysid give the rest, as EIBTRMID and ASSIGN report them
--commarea path[:text]The COMMAREA the task starts with, in EBCDIC bytes or UTF-8 text. EIBCALEN is its length, and 0 without it
--commarea-out path[:text]Where RETURN’s COMMAREA is written
--file NAME=path,…A CICS file: KSDS,key=OFFSET:LENGTH,len=RECLEN or RRDS,len=RECLEN after the path. Its data set holds the records in key order, as a REPRO unload does, and is written back when the task ends
--td QUEUE=pathA transient-data queue, appended to the file as text lines when the task ends
--screens pathA 24 by 80 3270 terminal played from a script: type ROW COL text, eof ROW COL, cursor ROW COL, and an AID key ending each turn. Every screen the task sends is printed
--serve HOST:PORTA TN3270 server instead of a script, until interrupted. Not with --screens, --commarea, --commarea-out, --sql-db or --sql-replay
--transaction TRAN=PROGRAMWith --serve, the program a transaction runs: one of the source’s, or one found through -L

ironwork cics takes run’s flags too. Assumptions C22 to C27 hold the CICS choices, and C28 to C33 those for BMS and the terminal.

Conformance tests

Predictions to be scored against the real compiler

Every prediction the model makes can be checked against IBM’s compiler, and the machine model against Hercules.

ironwork-oracle writes COBOL programs that pin TRUNC, NUMPROC and ARITH on their CBL card rather than trusting an installation’s defaults, and DISPLAY each case’s storage in hex. The model predicts the same bytes. Generated source uses only EBCDIC-invariant characters, so the transfer code page does not change it.

Goldens come from submitting those jobs to Enterprise COBOL on z/OS under terms of use that permit it, and saving their complete output, one directory per target, because the compiler level, ARCH and OPT all change the generated code.

Limit: no goldens are in the repository yet, so the model’s predictions have not yet been scored against IBM’s compiler.

Hercules 4.9.1 gives the machine a second reading. A bare-metal program runs about two thousand cases of the decimal instructions and the HFP arithmetic, on edge and random operands, and each result, condition code and program interruption is compared with ironwork’s model. Every decimal case agrees. Two HFP instructions disagree, LDXR and MXDR, and in both the Principles of Operation (SA22-7832-14) sides with ironwork.

Limit: Hercules implements the same manual as ironwork’s model.

cargo run -p ironwork-oracle --
generate out/       ORAC01..04 .cbl and .jcl, and expected.tsv
check goldens/     score saved job output against the predictions
smoke /tmp/smoke    compile and run with GnuCOBOL: a syntax check only
hercules /tmp/herc  run the instruction cases under Hercules 4.9.1
Assumptions recorded
302
each naming what settles it: Enterprise COBOL on the pinned target for 284, Db2 for z/OS for 16, Hercules for 2
Chosen
208
stated nowhere; IBM’s documentation leaves them to the generated code
Recalled
23
stated by IBM and written from memory of it, to be checked against the manual
Documented
63
stated in IBM’s documentation and checked against its text
Observed
8
seen on a related system the claim names, such as Db2 12.1.5 for Linux, rather than on the one that settles it

Counted in numeric::assumptions::ASSUMPTIONS in ironwork 0.7.0, which ironwork assumptions lists one per line: M for the machine; C for the compiler, files, CICS and BMS; L for Language Environment; S for sort; RW for Report Writer; J for object-oriented COBOL; SQ for SQL.

Code pages

EBCDIC storage

Data keeps its mainframe bytes; conversion happens only at I/O.

The tables are IBM’s as ICU publishes them, pinned to one ICU data commit, and the build refuses a table that does not map all 256 bytes.

Limit: line feed is X'25' and next line X'15' in these tables, which is right for record-oriented data sets. z/OS UNIX text files swap the two.

  • 037
  • 273
  • 277
  • 278
  • 280
  • 284
  • 285
  • 297
  • 500
  • 871
  • 1047
  • 1140
  • 1141
  • 1142
  • 1143
  • 1144
  • 1145
  • 1146
  • 1147
  • 1148
  • 1149

21 single-byte CCSIDs, from unicode-org/icu-data@8d9eb3e2, under the Unicode License v3.