Skip to content

Part 1 — Introduction and Overview

1.1 About Heirloom Enterprise PL/I

Overview of the Heirloom PL/I modernization platform. The system transpiles IBM mainframe PL/I source programs into Java, preserving semantics, and executes them on the Heirloom Runtime — a Java-based runtime that emulates the mainframe execution environment including CICS, DB2, and IBM MQ.

1.1.1 Purpose and Scope

  • Automated migration of PL/I programs from z/OS to Java/cloud platforms
  • Preservation of mainframe PL/I semantics (1-based indexing, fixed-length strings, packed decimal arithmetic, pointer-based storage)
  • Support for CICS, DB2, and IBM MQ integration

1.1.2 Architecture Overview

The Heirloom PL/I Platform consists of four core components working together to modernize mainframe PL/I applications to Java:

  1. PLI Preprocessor (pli-preprocessor) — Macro expansion and include file processing
  2. PLI Compiler (pli_compiler2) — PL/I to Java source transpilation
  3. Manifold Enhancement (heirloom-manifold) — Compile-time code annotation processing
  4. PLI Runtime (pli_runtime2) — Java runtime library providing PL/I semantics

Plus supporting infrastructure:

  1. EBP (Elastic Batch Platform) — Job scheduler for batch workload execution

Complete Platform Architecture

┌──────────────────────────────────────────────────────────────────────────────┐
│                        Heirloom PL/I Platform                                │
└──────────────────────────────────────────────────────────────────────────────┘

   PL/I Source (.pli)
         │
         ▼
   ┌────────────────────────┐
   │  1. PLI Preprocessor   │  %INCLUDE, macro expansion, %REPLACE
   │  (pli-preprocessor)    │  Conditional compilation
   └──────────┬─────────────┘
              ▼
   Preprocessed PL/I
              │
              ▼
   ┌────────────────────────┐
   │  2. PLI Compiler       │  ANTLR-based parser (10 grammar files)
   │  (pli_compiler2)       │  Transpiler (35+ statement handlers)
   │                        │  SQL module (18 handlers)
   │  • Lexer/Parser        │  CICS module (78 handlers)
   │  • Semantic Analysis   │  Built-in functions (90+ implementations)
   │  • Java Transpiler     │
   └──────────┬─────────────┘
              ▼
   Java Source Files (.java)
   + Annotations (@CHAR, @INTEGER, @DECIMAL, etc.)
              │
              ▼
   ┌────────────────────────┐
   │  3. Manifold           │  ◄─── Compile-time processing (javac plugin)
   │  Enhancement           │       Calculates byte offsets
   │  (heirloom-manifold)   │       Generates metadata ($MetadataOffsets)
   │                        │       Creates getter/setter methods
   │  ENTER → ANALYZE →     │       Zero runtime overhead
   │  GENERATE              │
   └──────────┬─────────────┘
              ▼
   Enhanced .class files
   + Runtime metadata
              │
              ▼
   ┌────────────────────────┐
   │  4. PLI Runtime        │  ◄─── Execution (JVM)
   │  (pli_runtime2)        │
   │                        │
   │  ┌──────────────────┐  │  Core Types:
   │  │ Core Runtime     │  │  • Group (structures, 186KB)
   │  │ (81 classes)     │  │  • Array (multi-dimensional, 218KB)
   │  │                  │  │  • PLIString (CHAR/VARCHAR)
   │  │ • Data Types     │  │  • Builtin (200+ functions, 337KB)
   │  │ • Storage Mgmt   │  │  • PLIDecimal, PLIInteger, PLIFloat
   │  │ • Built-ins      │  │  • PLIPointer, PLIArea, PLIFile
   │  └──────────────────┘  │
   │                        │  Subsystems:
   │  ┌──────────────────┐  │  • SQL Package (full DB2 support)
   │  │ CICS Package     │  │  • CICS Package (transaction commands)
   │  │ SQL Package      │  │  • MQ Package (message queues)
   │  │ MQ Package       │  │
   │  └──────────────────┘  │
   └──────────┬─────────────┘
              ▼
        Running Java Application
        • CICS Web Application (Payara/Jakarta EE)
        • Batch Job (via EBP)

┌─────────────────────────────────────────────────────────────────────┐
│  5. EBP — Elastic Batch Platform (Optional for Batch Workloads)    │
│                                                                     │
│  • JCL Parser (ANTLR4-based)        • Web UI (job monitoring)      │
│  • Job Scheduler & Queue            • REST API                     │
│  • Resource Management              • GDG Support                  │
│  • Multi-wave batch execution       • WAR deployment               │
└─────────────────────────────────────────────────────────────────────┘

Data Flow Summary

The complete modernization pipeline:

  1. PL/I Source → Preprocessor → Expanded source with includes/macros resolved
  2. Expanded PL/I → Compiler → Java source + annotations
  3. Java Source → javac + Manifold → Enhanced .class with metadata
  4. Enhanced .class → JVM + Runtime → Running application
  5. Batch Jobs → EBP → Scheduled execution of compiled programs

Each component is essential: - Preprocessor: Resolves %INCLUDE and macros before compilation - Compiler: Converts PL/I semantics to Java semantics - Manifold: Ensures mainframe-compatible memory layout at compile-time - Runtime: Provides PL/I data types and built-in functions at runtime - EBP: Orchestrates batch job execution (for batch workloads only)

1.1.3 Supported PL/I Dialect

  • IBM Enterprise PL/I for z/OS compatibility
  • Fixed-form source format with configurable margins (default columns 1–72)
  • Full preprocessor macro support

1.1.4 System Requirements and Prerequisites

  • Java 11 or later (JDK)
  • Gradle build system
  • Heirloom Runtime library (heirloom-manifold)
  • For CICS: Heirloom ETP (Enterprise Transaction Platform)
  • For DB2: JDBC-compatible database driver
  • For MQ: IBM MQ client libraries or Heirloom MQ emulation

1.1.5 What's New in This Release

  • DIMACROSS semantics (root structure single instance, children as arrays)
  • Boolean return type fixes for INLIST, ALL, ANY
  • Function invocations in SQL WHERE clauses
  • Complex BASED addressing improvements
  • LIKE attribute deep nesting support