Part 10 — Migration and Compatibility Guide¶
10.1 Migration Overview¶
10.1.1 Supported Source Dialect¶
- IBM Enterprise PL/I for z/OS source compatibility
- Fixed-form source format (columns 1–72)
- Preprocessor macros and include files
10.1.2 Migration Workflow¶
1. Analyze PL/I source programs
2. Configure compiler options (--sql, --cics, --strategy, etc.)
3. Set up Helper JSON for edge cases
4. Compile PL/I sources to Java
5. Configure runtime environment (DD names, JDBC, MQ)
6. Test transpiled programs
7. Deploy to target platform
10.2 Compiler Compatibility¶
10.2.1 Supported PL/I Features¶
The Heirloom PL/I compiler provides comprehensive support for IBM Enterprise PL/I for z/OS V5R1 features.
Coverage Summary¶
| Metric | Value | Details |
|---|---|---|
| Total Features | 575 | Including core PL/I, SQL, and CICS |
| Full Support | 407 (70.8%) | Complete implementation with evidence |
| Partial Support | 66 (11.5%) | Implemented with known limitations |
| Not Implemented | 102 (17.7%) | Not yet supported |
| Test Coverage | 48.3% | 240 features with automated tests |
| SQL/CICS Coverage | 91% | Production-ready confidence |
Key Strengths¶
Enterprise Features: - ✅ BASED variables - Full pointer-based memory management - ✅ DEFINED attribute - Memory overlays and aliases - ✅ LIKE attribute - Structure inheritance - ✅ CONTROLLED storage - Explicit ALLOCATE/FREE lifecycle - ✅ REFER attribute - Self-defining structures
CICS Support: - ✅ 100% CICS command coverage - All 78 EXEC CICS handlers implemented - ✅ Terminal I/O, File operations, Program control, Queue management - ✅ Container services, System services
SQL Support: - ✅ Core DML - SELECT, INSERT, UPDATE, DELETE fully supported - ✅ Cursor operations - DECLARE, OPEN, FETCH, CLOSE - ✅ Dynamic SQL - PREPARE, EXECUTE, DESCRIBE - ⚠️ Advanced DDL - Some limitations (use database scripts)
Statements & Control Flow: - ✅ All standard statements: IF, DO, SELECT, CALL, RETURN, GOTO, LEAVE, ITERATE - ✅ 140+ built-in functions - ✅ File I/O: READ, WRITE, REWRITE, DELETE, OPEN, CLOSE - ✅ Stream I/O: GET, PUT (LIST, EDIT, DATA)
Validation¶
The compiler has been validated against 203 BMW customer programs, including: - Largest program: 40,976 lines of PL/I - CICS online applications (BMWCICSWave-1) - Batch processing systems (bmw-batch-improvement) - Production-scale enterprise patterns
Coverage by Category¶
| Category | Features | Full | Partial | None |
|---|---|---|---|---|
| Statements & Procedures | 93 | 85% | 10% | 5% |
| Declarations & Attributes | 112 | 75% | 12% | 13% |
| Built-in Functions | 187 | 68% | 8% | 24% |
| I/O Operations | 45 | 72% | 15% | 13% |
| Conditions & Error Handling | 32 | 65% | 20% | 15% |
| SQL (EXEC SQL) | 52 | 90% | 8% | 2% |
| CICS (EXEC CICS) | 78 | 100% | 0% | 0% |
Known Limitations¶
Not Implemented (typically not needed): - Multithreading (ATTACH, DETACH, WAIT) - Not used in BMW programs - Some mathematical built-ins - Not used in customer code - Advanced preprocessor directives - Basic %INCLUDE works
Partial Implementation: - Some I/O operations - Core file I/O fully functional - Dynamic SQL edge cases - Core PREPARE/EXECUTE works
See also: - Compiler Reference: 2.2 Supported Features for feature details - Language Reference: Part 3 for PL/I syntax reference - Runtime Reference: Part 4 for implementation details
10.2.2 Known Limitations and Differences¶
- Features with partial or modified support
- Mainframe-specific features requiring adaptation
- Known behavioral differences from z/OS PL/I
10.2.3 Helper System for Edge Cases¶
Using the Helper JSON system to resolve compilation edge cases without source modification.
10.3 Runtime Compatibility¶
10.3.1 Data Type Fidelity¶
- FIXED DECIMAL precision and scale preservation
- PICTURE formatting accuracy
- Bit string operations
- Pointer semantics on JVM
10.3.2 Character Encoding¶
- EBCDIC to ASCII/UTF-8 mapping
- MEMCONVERT and REPATTERN for encoding conversion
- Collation sequence differences
10.3.3 I/O Compatibility¶
- DD name to file path mapping
- Sequential and ISAM/VSAM file emulation
- Print file formatting
10.4 CICS Migration¶
10.4.1 CICS Transaction Mapping¶
- BMS map conversion
- COMMAREA handling
- Channel/container migration
- Transaction routing configuration
10.4.2 CICS Resource Configuration¶
- File definitions (FCT equivalent)
- Transaction definitions (PCT equivalent)
- Program definitions (PPT equivalent)
10.5 DB2/SQL Migration¶
10.5.1 Database Connectivity¶
- JDBC driver configuration
- Connection pool setup
- DB2 to target RDBMS considerations
10.5.2 SQL Dialect Differences¶
- DB2-specific SQL functions mapping
- Date/time format configuration
- SQLCA behavior
10.6 MQ Migration¶
10.6.1 MQ Configuration¶
- Queue manager connection setup
- Queue definition mapping
- Channel configuration
10.6.2 MQ Runtime Environment¶
- Connection factory configuration
- Message encoding (EBCDIC/ASCII)