rpg-migration-analyzer

What this skill does

# RPG Migration Analyzer

Analyzes legacy RPG programs (RPG III/IV/ILE) from AS/400 and IBM i systems for migration to modern Java applications, extracting business logic, data structures, file operations, and generating actionable migration strategies.

## Overview

This skill provides comprehensive analysis and migration planning for RPG (Report Program Generator) applications. It extracts program specifications, converts RPG data types to Java equivalents, maps file operations to modern database access patterns, and generates implementation-ready Java code structures.

**Key Migration Focus**: RPG to Java with proper handling of packed decimals (BigDecimal), data structures (POJOs), file operations (JPA/JDBC), indicators (boolean variables), and business logic preservation.

## When to Use This Skill

Use this skill when:

- Analyzing RPG source files (.rpg, .rpgle, .RPGLE) for modernization
- Planning migration from AS/400 or IBM i systems to Java
- Converting RPG data structures (D-specs) to Java classes
- Mapping RPG file operations (F-specs) to database access patterns
- Understanding RPG program dependencies and call chains
- Generating Java code equivalents from RPG business logic
- Estimating complexity and effort for RPG migration projects
- Creating migration documentation and strategy reports
- Modernizing legacy mainframe applications to microservices
- User mentions: RPG analysis, AS/400 migration, IBM i modernization, Report Program Generator, packed decimal conversion

## Core Capabilities

### 1. Program Analysis

Extract and analyze RPG program components:

- **Specification types**: H-spec (header/control), F-spec (file definitions), D-spec (data definitions), C-spec (calculation/logic), P-spec (procedures)
- **Data structures**: D-specs with nested structures, arrays (DIM), external references (EXTNAME), qualifiers (LIKEDS, QUALIFIED)
- **File definitions**: Physical files, logical files, display files (WORKSTN), printer files
- **Business logic**: Calculation specifications, control structures (IF/ELSE/DO/FOR), expressions (EVAL)
- **Indicators**: Legacy indicators (*IN01-*IN99), built-in indicators (*INLR,*INOF)
- **Built-in functions**: String functions (%SUBST, %TRIM, %SCAN), date functions (%DATE, %DAYS), math functions (%DEC, %INT), file status (%EOF, %FOUND, %ERROR)
- **Error handling**: %ERROR, %STATUS, ON-ERROR blocks

### 2. Data Structure Mapping

Convert RPG data definitions to Java equivalents:

- **D-spec conversion**: Data structure definitions to Java classes (POJOs)
- **Data type mapping**:
  - Packed decimal (P) → `BigDecimal` (preserve precision)
  - Zoned decimal (S) → `BigDecimal` (decimal with sign)
  - Character (A) → `String`
  - Date (D) → `LocalDate`
  - Time (T) → `LocalTime`
  - Timestamp (Z) → `LocalDateTime`
  - Indicator (N) → `boolean`
  - Binary integer (I) → `int` or `long`
- **Arrays (DIM)**: Convert to Java `List<T>` or arrays `T[]`
- **Nested data structures**: Convert LIKEDS to nested Java classes
- **External data structures (EXTNAME)**: Generate JPA entities from database table definitions
- **Initialization (INZ)**: Map to Java field initializers or constructors

### 3. File Operations

Parse and convert RPG file I/O to modern database access:

- **File types**: Physical files (DISK), logical files (keyed access), display files (WORKSTN), printer files (PRINTER)
- **Access methods**: Sequential (full read), keyed (direct access by key), arrival sequence
- **I/O operations**:
  - READ/READE → JPA query methods, JDBC ResultSet iteration
  - WRITE → JPA persist(), JDBC INSERT
  - UPDATE → JPA merge(), JDBC UPDATE
  - DELETE → JPA remove(), JDBC DELETE
  - CHAIN → JPA findById(), Optional pattern
  - SETLL/READE loop → JPA findBy...() queries with ordering
- **File status**: %EOF (end of file), %FOUND (record found), %ERROR (I/O error) → Java exceptions or Optional
- **Transaction boundaries**: Identify commit boundaries (COMMIT operation code)

### 4. Java Migration Strategy

Generate modern Java implementation patterns:

- **POJOs**: Plain Old Java Objects from D-spec data structures
- **JPA Entities**: @Entity annotations for database tables (from EXTNAME files)
- **Repository pattern**: Spring Data JPA repositories for file operations
- **Service methods**: Business logic from procedures and subroutines
- **Bean Validation**: @NotNull, @Size, @DecimalMin/Max from RPG field validations
- **Exception handling**: Convert %ERROR patterns to try-catch blocks with custom exceptions
- **Collections**: Java Collections API (List, Map, Set) from RPG arrays and data structures
- **DTOs**: Data Transfer Objects for service boundaries
- **Transaction management**: @Transactional annotations for commit boundaries

### 5. Dependency Analysis

Map program relationships and external dependencies:

- **Program calls**: CALLB (bound procedure calls), CALLP (prototyped procedure calls)
- **Service programs**: BNDDIR (binding directories), *SRVPGM objects
- **File dependencies**: All physical/logical files accessed by the program
- **Database tables**: DB2 for i tables referenced (EXTNAME)
- **/COPY members**: Include files, copy source members, prototypes
- **Call chains**: Identify calling programs and called programs
- **Shared data areas**: *DTAARA usage
- **Message queues**: QMHSNDPM (send program message)

## Instructions

Follow these steps to analyze and migrate RPG programs to Java:

### Step 1: Locate RPG Source Files

Find RPG source files (.rpg, .rpgle, .RPGLE extensions for RPG III/IV/ILE free-format).

```bash
find . -name "*.rpg" -o -name "*.rpgle" -o -name "*.RPGLE"
```

### Step 2: Analyze Program Structure

Extract specifications (H, F, D, C, P), data structures, file definitions, procedures, and dependencies.

**Automation**: Run `scripts/extract-structure.py` for automated extraction.

### Step 3: Map Data Types

Convert RPG to Java types - **CRITICAL**: Always use `BigDecimal` for packed/zoned decimals (never float/double).

| RPG Type | Java Type | Key Notes |
|----------|-----------|-----------|
| `nP m` (packed) | `BigDecimal` | **MUST** preserve precision |
| `nS m` (zoned) | `BigDecimal` | Decimal with sign |
| `A` (char) | `String` | Character data |
| `D/T/Z` (date/time) | `LocalDate/LocalTime/LocalDateTime` | Date fields |
| `N` (indicator) | `boolean` | True/False flags |
| `I` (integer) | `int` or `long` | Binary integer |
| `DIM(n)` (array) | `List<T>` or `T[]` | Arrays |

### Step 4: Convert Code Patterns

Transform RPG operations to Java - key conversions:

- **Calculations**: EVAL expressions → BigDecimal arithmetic methods
- **File I/O**: CHAIN → `findById()` with Optional, READ → query methods
- **Arrays**: Adjust 1-based (RPG) to 0-based (Java) indexing
- **Strings**: %SUBST(1-based) → substring(0-based)
- **Indicators**: *IN01 → named boolean variables

See [pseudocode-rpg-rules.md](references/pseudocode-rpg-rules.md) for comprehensive conversion patterns.

### Step 5: Generate Java Implementation

Create:

1. POJOs from D-spec data structures (`scripts/generate-java-classes.py`)
2. JPA entities for database tables
3. Repository interfaces (Spring Data JPA)
4. Service methods for business logic
5. Exception handling and validation

### Step 6: Analyze Dependencies

Map program calls (CALLB/CALLP), file dependencies, /COPY members, service programs.

**Automation**: Run `scripts/analyze-dependencies.sh` or `.ps1`

### Step 7: Create Migration Report

Generate documentation with program overview, dependencies, data mappings, Java design, and complexity estimate.

**Template**: Use `assets/migration-report-template.md`

### Step 8: Validate and Test

Verify: BigDecimal usage, index adjustments, transaction boundaries, error handling, unit tests with AS/400 data samples.

## Quick Reference

### Critical Migration Rules

1. **ALWAYS use BigDecimal** for RPG packed (P) and zoned (S) decimals - never float/double
2. **Adjust indexing**: RPG uses 1-based arrays/strings, Java