COOL:2E developer on retainer: PGORDCHK Change function type generates FORDMST UF update-mode F-spec locking ORDMST record during ORDENT screen I/O while warehouse ORDPICK waits

COOL:2E 6.0 (Synon/2E) • ARCAD ALM • IBM i 7.4 • ILE RPG generated • DB2 for i record lock • Function Type • retainer billing

Consolidated Wholesale Distributors had been running their warehouse and order management systems on IBM i for twenty-two years. The core applications were built in COOL:2E Version 5, migrated to COOL:2E 6.0, and never converted out of the 4GL model. The original COOL:2E developers were long gone. When the warehouse complained that the order picking system was dying with cryptic “machine check” errors every few hours, the IT manager brought in a COOL:2E retainer consultant who had been working with Synon/2E and its successors since the 1990s.

The symptom: job ORDPICK, running under user profile WHPICK, would terminate abnormally with MCH3601 (object not available) during peak order processing. It happened only when order entry operators were actively processing orders. It never happened during off-hours batch runs. Classic interactive-vs-batch lock contention — but the actual source was buried in how COOL:2E had generated a retrieval-only function with the wrong access mode.

COOL:2E function types and generated F-specs

COOL:2E generates ILE RPG source code from a model. One of the most consequential modeling decisions is the function type. COOL:2E function types include:

• Add — generates WRITE; F-spec with output mode
• Change — generates CHAIN then UPDATE; F-spec with update-full (UF) access mode — acquires exclusive record lock on CHAIN
• Delete — generates CHAIN then DELETE; F-spec with update-full access mode
• Inquire — generates CHAIN; F-spec with input mode (IF) — no lock on CHAIN
• Process — generates READ/CHAIN for retrieval in a batch or validation context; F-spec with input mode — no lock on CHAIN
• Browse — generates SETLL/READ for sequential display; F-spec with input mode

The critical difference: Change and Delete generate UF (update-full) in the F-spec. Any CHAIN on a UF file acquires an exclusive DB2 for i record lock (*EXCLRD). That lock is held until either UPDATE or UNLOCK is executed. If the program returns or branches to a non-update exit without UNLOCK, the lock is held in the calling activation group until that group ends.

The PGORDCHK mismodeled function

PGORDCHK (Order Check) was a validation function called from PGORDENT (Order Entry), the interactive order entry display program. Its design intent was simple: given an order number, retrieve the ORDMST (Order Master) record and check whether the order had already been picked — if so, return a DUPLICATE-ORDER return code to prevent the operator from double-picking it.

The original developer had modeled PGORDCHK as a Change function type, probably because Change was the default when creating functions that accessed ORDMST in other contexts. The COOL:2E model generated this RPG F-spec for PGORDCHK:

FORDMST    UF   A   E           K DISK    WAITRDC(60)
*                ^^^ Update-Full = CHAIN acquires *EXCLRD lock

The generated action diagram logic was:

C     ORDNO         CHAIN     ORDMST               /* *EXCLRD lock acquired */
C                   IF        %FOUND(ORDMST)
C                   IF        ORD_STATUS = 'PICKED'
C                   EVAL      RTNCOD = 'DUPORD'    /* return DUPLICATE-ORDER */
C                   RETURN                         /* exits — *EXCLRD still held */
C                   ENDIF
C                   ENDIF
C                   EVAL      RTNCOD = 'OK'
C                   RETURN

PGORDCHK never contained an UPDATE ORDMST call — it was read-only. But the Change function type caused COOL:2E to generate a UF F-spec regardless. The CHAIN at line 1 acquired a *EXCLRD record lock on the ORDMST record. The RETURN at the DUPLICATE-ORDER exit returned control to PGORDENT — but in an *CALLER activation group, the lock from PGORDCHK stayed open in PGORDENT’s activation group context.

PGORDENT then did an EXFMT (write/read to display file), waiting for the operator to press a key. The *EXCLRD lock on the ORDMST record was held for the entire workstation wait — typically 3 to 8 minutes during peak processing.

WRKOBJLCK diagnosis and the MCH3601 chain

The retainer consultant ran WRKOBJLCK FILE(ORDLIB/ORDMST) MBR(*FIRST) while an order entry operator had the order status check screen displayed. The output showed exactly one *EXCLRD lock held by interactive job ORDENTRY under user ORDMGR — on the ORDMST record for the order number the operator had just looked up. The lock had been held for 6 minutes.

Meanwhile, job ORDPICK under user WHPICK was executing a COOL:2E-generated picking confirmation function (PGORDPCK), which also used a Change function type on ORDMST. PGORDPCK’s CHAIN ORDNO ORDMST hit the same record already locked by ORDENTRY. WAITRDC(60) in the generated F-spec meant ORDPICK waited 60 seconds, then received an MCH3601 exception. The warehouse order picking queue fell behind and the pickers had to re-scan the same items repeatedly when their terminals locked up.

Fix: Change Function Type to Process in COOL:2E model

The fix required one model change and a regeneration cycle:

1. In the COOL:2E model APPMODEL (library SYNLIB), open function PGORDCHK
2. Change Function Type from Change to Process
3. Regenerate PGORDCHK — COOL:2E now generates FORDMST IF E K DISK (IF = input-only, no lock on CHAIN)
4. Compile: CRTRPGMOD PGM(ORDLIB/PGORDCHK) SRCFILE(ORDLIB/QRPGLESRC) then CRTPGM PGM(ORDLIB/PGORDCHK)

After the fix: WRKOBJLCK FILE(ORDLIB/ORDMST) showed zero *EXCLRD locks during order entry screen waits. PGORDPCK no longer timed out. MCH3601 errors: eliminated. The consultant also audited all other COOL:2E Change functions that contained no UPDATE statement in their action diagram — found three more mismodeled as Change when Process was correct — and corrected all of them in the same session.

How HourTab helps COOL:2E retainer consultants

COOL:2E retainer work is inherently episodic: a production lock issue escalates, the consultant diagnoses in 1–2 hours, the fix takes another hour, regression testing takes another hour. The distributor’s IT manager asked how much of the retainer budget this incident consumed. The retainer consultant pulled up their HourTab link — 3.5 hours logged with timestamps — and sent it in a reply. No spreadsheet attachment, no PDF invoice, no follow-up email asking “how many hours do we have left.”

HourTab turns a time-tracker CSV into a public retainer-hours URL your client can bookmark — no login, no portal, no “how many hours do I have left?” emails. Free for one retainer. $9/mo for up to ten.

FAQ: COOL:2E developer retainers

See also: IBM AS/400 / IBM i developer retainer · Db2 developer retainer · JCL developer retainer