Pli Migration Analyzer

PL/I Migration Analyzer

Analyzes legacy PL/I programs and generates Java migration strategies. Extracts business logic, data structures, procedures, and dependencies to produce actionable migration plans.

Workflow

1. Discover PL/I Programs

Find PL/I source files in the workspace:

find . -name "*.pli" -o -name "*.PLI" -o -name "*.pl1"

2. Analyze Program Structure

For each PL/I program, extract:

• Entry points: PROCEDURE OPTIONS(MAIN)
• Declarations: DCL statements (FIXED DECIMAL, FIXED BINARY, CHARACTER, BIT, structures)
• Procedures: Nested procedures and functions
• File operations: OPEN, READ, WRITE, CLOSE statements
• Exception handling: ON conditions (ENDFILE, ERROR, etc.)
• Dependencies: CALL statements, %INCLUDE directives

Use scripts for automation:

• extract-structure.py <source_file> - Extract structural information
• analyze-dependencies.sh <directory> - Generate dependency graph
• estimate-complexity.py <source_file> - Estimate migration effort

3. Map to Java Design

Convert PL/I elements to Java:

• Structures → POJOs with appropriate types
• Procedures → Service methods
• File operations → Java I/O or database operations
• ON conditions → try-catch exception handling
• Arrays → Lists or arrays (adjust 1-based to 0-based indexing)

Critical Type Mapping:

• FIXED DECIMAL(n,m) → BigDecimal (NEVER float/double)
• FIXED BINARY(n) → int, long
• CHARACTER(n) → String
• BIT(1) → boolean

4. Generate Java Implementation

Create Java classes using:

• generate-java-classes.py <data_structure_file> - Generate POJOs from structures

Ensure:

• BigDecimal for all financial calculations
• Proper exception handling (no GO TO)
• Array bounds adjustment (1-based → 0-based)
• String operations adjustment (SUBSTR is 1-based, substring is 0-based)

5. Produce Migration Report

Generate comprehensive report with:

1. Program Overview: Purpose, entry points, complexity estimate 2. Dependencies: Called procedures, included files, external references 3. Data Structures: Tables with PL/I types and Java equivalents 4. Business Logic Summary: Key algorithms and rules 5. Java Design: Proposed classes, methods, packages 6. Migration Estimate: Effort in person-days, risk assessment 7. Action Items: Prioritized tasks with owners

Use template: assets/migration-report-template.md

Quick Reference

Common Conversions

Procedure to Method:

CALC_TOTAL: PROCEDURE(qty, price) RETURNS(FIXED DECIMAL(15,2));
    result = qty * price;
    RETURN(result);
END CALC_TOTAL;

→

public BigDecimal calcTotal(BigDecimal qty, BigDecimal price) {
    return qty.multiply(price);
}

File I/O to Streams:

DO WHILE(¬eof);
    READ FILE(infile) INTO(rec);
    CALL process_record(rec);
END;

→

try (BufferedReader reader = Files.newBufferedReader(path)) {
    reader.lines().forEach(this::processRecord);
}

Critical Rules

1. Use BigDecimal for FIXED DECIMAL - Float/double lose precision 2. Arrays are 1-based in PL/I, 0-based in Java - Adjust loops and indices 3. Refactor GO TO statements - Use structured control flow 4. ON conditions map to try-catch - Exception handling strategy required 5. SUBSTR is 1-based - Java substring is 0-based and end-exclusive

Detailed References

For comprehensive information:

• Type mapping & patterns: pli-reference.md - Complete data type conversions, code patterns, migration checklist, common pitfalls
• Pseudocode translation: pseudocode-pli-rules.md - Rules for converting PL/I to pseudocode
• Transaction handling: transaction-handling.md - Database transaction patterns
• Performance: performance-patterns.md - Optimization strategies
• Messaging: messaging-integration.md - Event-driven patterns
• Testing: testing-strategy.md - Test approach and validation

Output Format

Structure migration reports with these sections:

# [Program Name] Migration Analysis

## Executive Summary
High-level overview and recommendations

## Program Overview
Purpose, functionality, complexity metrics

## Dependencies
Procedure calls, file dependencies, external references

## Data Structures
Tables mapping PL/I structures to Java classes

## Business Logic Analysis
Key algorithms, rules, calculations

## Java Design Proposal
Package structure, class design, API interfaces

## Migration Estimate
Effort (person-days), risk level, timeline

## Action Items
Prioritized tasks with acceptance criteria

PL/I Program Migration Report

Program: {{PROGRAM_NAME}} Migration Date: {{MIGRATION_DATE}} Analyst: {{ANALYST_NAME}} Status: {{STATUS}}

---

1. Executive Summary

Program Overview

• Purpose: {{PROGRAM_PURPOSE}}
• Type: {{PROGRAM_TYPE}} (Batch/Online/Utility)
• Lines of Code: {{LOC}}
• Complexity: {{COMPLEXITY_LEVEL}}
• Estimated Effort: {{EFFORT_DAYS}} person-days

Migration Recommendation

{{RECOMMENDATION}}

---

2. Source Analysis

Program Structure

Main Components

• Entry Point: PROCEDURE OPTIONS(MAIN) at Line {{MAIN_PROC_LINE}}
• Total Procedures: {{PROCEDURE_COUNT}}
• Total Declarations: {{DECLARATION_COUNT}}
• File Definitions: {{FILE_DEF_COUNT}}

Key Data Structures

{{DATA_STRUCTURES_TABLE}}

Include Files Used

{{INCLUDE_FILES_TABLE}}

Business Logic Summary

{{BUSINESS_LOGIC_SUMMARY}}

Control Flow

{{CONTROL_FLOW_DESCRIPTION}}

---

3. Dependencies

Program Calls

{{PROGRAM_CALLS_TABLE}}

File Operations

{{FILE_OPERATIONS_TABLE}}

Database Operations

{{DATABASE_OPERATIONS_TABLE}}

Dependency Graph

{{DEPENDENCY_GRAPH}}

---

4. Java Design

Proposed Architecture

Package Structure

{{PACKAGE_STRUCTURE}}

Class Design

{{CLASS_DESIGN_TABLE}}

Method Signatures

{{METHOD_SIGNATURES}}

Data Model

{{DATA_MODEL_DESCRIPTION}}

Service Layer

{{SERVICE_LAYER_DESCRIPTION}}

---

5. Complexity Assessment

Metrics

• Cyclomatic Complexity: {{CYCLOMATIC_COMPLEXITY}}
• Number of Procedures: {{PROCEDURE_COUNT}}
• External Dependencies: {{DEPENDENCY_COUNT}}
• File Operations: {{FILE_OP_COUNT}}
• Database Operations: {{DB_OP_COUNT}}
• Complexity Score: {{COMPLEXITY_SCORE}}

Risk Factors

{{RISK_FACTORS_LIST}}

Technical Challenges

1. {{CHALLENGE_1}} 2. {{CHALLENGE_2}} 3. {{CHALLENGE_3}}

---

6. Migration Strategy

Approach

{{MIGRATION_APPROACH}}

Phase 1: Preparation ({{PHASE1_DAYS}} days)

• [ ] {{PREP_TASK_1}}
• [ ] {{PREP_TASK_2}}
• [ ] {{PREP_TASK_3}}

Phase 2: Implementation ({{PHASE2_DAYS}} days)

• [ ] {{IMPL_TASK_1}}
• [ ] {{IMPL_TASK_2}}
• [ ] {{IMPL_TASK_3}}

Phase 3: Testing ({{PHASE3_DAYS}} days)

• [ ] {{TEST_TASK_1}}
• [ ] {{TEST_TASK_2}}
• [ ] {{TEST_TASK_3}}

Phase 4: Deployment ({{PHASE4_DAYS}} days)

• [ ] {{DEPLOY_TASK_1}}
• [ ] {{DEPLOY_TASK_2}}
• [ ] {{DEPLOY_TASK_3}}

---

7. Testing Plan

Unit Testing

{{UNIT_TEST_PLAN}}

Integration Testing

{{INTEGRATION_TEST_PLAN}}

Parallel Run Testing

{{PARALLEL_RUN_PLAN}}

Performance Testing

{{PERFORMANCE_TEST_PLAN}}

---

8. Data Migration

Data Structures to Migrate

{{DATA_MIGRATION_STRUCTURES}}

Migration Scripts Required

• [ ] {{MIGRATION_SCRIPT_1}}
• [ ] {{MIGRATION_SCRIPT_2}}
• [ ] {{MIGRATION_SCRIPT_3}}

Validation Approach

{{VALIDATION_APPROACH}}

---

9. Implementation Notes

Special Considerations

{{SPECIAL_CONSIDERATIONS}}

Code Patterns

{{CODE_PATTERNS}}

Performance Optimization

{{PERFORMANCE_NOTES}}

---

10. Timeline and Resources

Schedule

Resource Requirements

• Java Developers: {{JAVA_DEV_COUNT}}
• PL/I Analysts: {{PLI_ANALYST_COUNT}}
• QA Engineers: {{QA_COUNT}}
• DevOps: {{DEVOPS_COUNT}}

Dependencies

• [ ] {{EXTERNAL_DEPENDENCY_1}}
• [ ] {{EXTERNAL_DEPENDENCY_2}}
• [ ] {{EXTERNAL_DEPENDENCY_3}}

---

11. Success Criteria

Functional

• [ ] All business logic correctly migrated
• [ ] 100% test coverage for critical paths
• [ ] Parallel run matches PL/I output (99.9%+)

Non-Functional

• [ ] Performance meets or exceeds PL/I
• [ ] Response time < {{RESPONSE_TIME_TARGET}}ms
• [ ] Throughput >= {{THROUGHPUT_TARGET}} TPS

Quality

• [ ] Code review completed
• [ ] Documentation complete
• [ ] Knowledge transfer completed

---

12. Appendices

A. PL/I Source Reference

{{PLI_SOURCE_EXCERPTS}}

B. Generated Java Code Samples

{{JAVA_CODE_SAMPLES}}

C. Test Cases

{{TEST_CASES}}

D. References

• PL/I Program: {{PLI_FILE_PATH}}
• Design Document: {{DESIGN_DOC_PATH}}
• Test Data: {{TEST_DATA_PATH}}

---

Report Generated: {{REPORT_DATE}} Tool: PL/I Migration Analyzer Agent Skill v1.0.0

Messaging Integration Patterns

Guide for migrating mainframe messaging patterns (MQ, CICS transient data) to modern Java messaging.

Overview

Mainframe systems use IBM MQ, CICS queues, and transient data for asynchronous communication. This guide shows how to migrate these patterns to modern Java messaging frameworks.

Common Mainframe Patterns

1. IBM MQ Messages

PL/I Example:

/* Write to temporary storage queue */
EXEC CICS WRITEQ TS
    QUEUE('ORDERQ')
    FROM(order_message)
    LENGTH(order_length);

/* Read from temporary storage queue */
EXEC CICS READQ TS
    QUEUE('ORDERQ')
    INTO(order_message)
    LENGTH(order_length);

2. CICS Transient Data

/* Write to transient data queue */
EXEC CICS WRITEQ TD
    QUEUE('LOGG')
    FROM(log_message)
    LENGTH(log_length);

Java Messaging Patterns

Pattern 1: Spring JMS with ActiveMQ

Configuration:

@Configuration
@EnableJms
public class JmsConfig {
    
    @Bean
    public ConnectionFactory connectionFactory() {
        return new ActiveMQConnectionFactory("tcp://localhost:61616");
    }
    
    @Bean
    public JmsTemplate jmsTemplate(ConnectionFactory connectionFactory) {
        JmsTemplate template = new JmsTemplate(connectionFactory);
        template.setDefaultDestinationName("order.queue");
        return template;
    }
}

Sender (equivalent to WRITEQ):

@Service
public class OrderMessageSender {
    
    @Autowired
    private JmsTemplate jmsTemplate;
    
    public void sendOrder(Order order) {
        jmsTemplate.convertAndSend("order.queue", order, message -> {
            message.setStringProperty("orderType", order.getType());
            message.setStringProperty("priority", order.getPriority());
            return message;
        });
    }
}

Receiver (equivalent to READQ):

@Service
public class OrderMessageReceiver {
    
    @JmsListener(destination = "order.queue")
    public void receiveOrder(Order order) {
        log.info("Received order: {}", order.getId());
        processOrder(order);
    }
    
    // Manual receive (blocking)
    public Order receiveOrderManually() {
        return (Order) jmsTemplate.receiveAndConvert("order.queue");
    }
}

Pattern 2: Spring AMQP with RabbitMQ

Configuration:

@Configuration
public class RabbitConfig {
    
    @Bean
    public Queue orderQueue() {
        return new Queue("order.queue", true); // durable
    }
    
    @Bean
    public Exchange orderExchange() {
        return new TopicExchange("order.exchange");
    }
    
    @Bean
    public Binding binding(Queue queue, Exchange exchange) {
        return BindingBuilder
            .bind(queue)
            .to(exchange)
            .with("order.#")
            .noargs();
    }
    
    @Bean
    public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory) {
        RabbitTemplate template = new RabbitTemplate(connectionFactory);
        template.setMessageConverter(new Jackson2JsonMessageConverter());
        return template;
    }
}

Sender:

@Service
public class RabbitOrderSender {
    
    @Autowired
    private RabbitTemplate rabbitTemplate;
    
    public void sendOrder(Order order) {
        rabbitTemplate.convertAndSend(
            "order.exchange",
            "order.new",
            order
        );
    }
}

Receiver:

@Service
public class RabbitOrderReceiver {
    
    @RabbitListener(queues = "order.queue")
    public void handleOrder(Order order) {
        processOrder(order);
    }
}

Pattern 3: Spring Kafka

Configuration:

@Configuration
public class KafkaConfig {
    
    @Bean
    public ProducerFactory<String, Order> producerFactory() {
        Map<String, Object> config = new HashMap<>();
        config.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        config.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        config.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, JsonSerializer.class);
        return new DefaultKafkaProducerFactory<>(config);
    }
    
    @Bean
    public KafkaTemplate<String, Order> kafkaTemplate() {
        return new KafkaTemplate<>(producerFactory());
    }
    
    @Bean
    public ConsumerFactory<String, Order> consumerFactory() {
        Map<String, Object> config = new HashMap<>();
        config.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
        config.put(ConsumerConfig.GROUP_ID_CONFIG, "order-processor");
        config.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
        config.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, JsonDeserializer.class);
        config.put(JsonDeserializer.TRUSTED_PACKAGES, "*");
        return new DefaultKafkaConsumerFactory<>(config);
    }
}

Producer:

@Service
public class KafkaOrderProducer {
    
    @Autowired
    private KafkaTemplate<String, Order> kafkaTemplate;
    
    public void sendOrder(Order order) {
        kafkaTemplate.send("order-topic", order.getId(), order)
            .addCallback(
                success -> log.info("Order sent: {}", order.getId()),
                failure -> log.error("Failed to send order", failure)
            );
    }
}

Consumer:

@Service
public class KafkaOrderConsumer {
    
    @KafkaListener(topics = "order-topic", groupId = "order-processor")
    public void consume(Order order) {
        log.info("Consumed order: {}", order.getId());
        processOrder(order);
    }
}

Migration Patterns

Pattern 1: Request-Reply

PL/I/MQ:

/* Send request with reply queue */
MQMD.REPLYTOQ = 'TEMP_REPLY_Q';
CALL MQPUT(hconn, hobj, mqmd, mqpmo, buffer_length, buffer, compcode, reason);

/* Wait for reply */
CALL MQGET(hconn, hobj, mqmd, mqgmo, buffer_length, buffer, data_length, compcode, reason);

Java/JMS:

@Service
public class RequestReplyService {
    
    @Autowired
    private JmsTemplate jmsTemplate;
    
    public Response sendRequest(Request request) {
        return (Response) jmsTemplate.convertSendAndReceive(
            "request.queue",
            request,
            message -> {
                message.setJMSReplyTo(
                    new ActiveMQQueue("reply.queue")
                );
                return message;
            }
        );
    }
}

Pattern 2: Dead Letter Queue

Configuration:

@Bean
public ReplyingKafkaTemplate<String, Order, OrderResult> replyingKafkaTemplate(
        ProducerFactory<String, Order> pf,
        KafkaMessageListenerContainer<String, OrderResult> container) {
    return new ReplyingKafkaTemplate<>(pf, container);
}

@Bean
public DeadLetterPublishingRecoverer deadLetterPublishingRecoverer(
        KafkaTemplate<String, Order> template) {
    return new DeadLetterPublishingRecoverer(template);
}

Usage:

@KafkaListener(topics = "order-topic")
public void processOrder(Order order) {
    try {
        validateAndProcess(order);
    } catch (ValidationException e) {
        // Will be sent to DLQ automatically
        throw new RuntimeException("Invalid order", e);
    }
}

Pattern 3: Message Retry

Configuration:

@Configuration
public class RetryConfig {
    
    @Bean
    public ErrorHandler errorHandler(KafkaTemplate<String, Order> template) {
        // Retry 3 times with exponential backoff
        DefaultErrorHandler handler = new DefaultErrorHandler(
            new DeadLetterPublishingRecoverer(template),
            new FixedBackOff(1000L, 3L)
        );
        
        handler.addNotRetryableExceptions(ValidationException.class);
        return handler;
    }
}

Message Format Conversion

PL/I Fixed-Length to JSON

PL/I Message:

DCL 1 ORDER_MESSAGE,
      2 ORDER_ID CHAR(10),
      2 CUSTOMER_ID CHAR(10),
      2 AMOUNT FIXED DECIMAL(9,2),
      2 ORDER_DATE CHAR(8);

Java DTO:

@Data
public class OrderMessage {
    private String orderId;
    private String customerId;
    private BigDecimal amount;
    private LocalDate orderDate;
    
    // Converter from PL/I format
    public static OrderMessage fromPliBytes(byte[] bytes) {
        // Parse fixed-length format
        String orderId = new String(bytes, 0, 10).trim();
        String customerId = new String(bytes, 10, 10).trim();
        BigDecimal amount = PliConverter.fromPackedDecimal(bytes, 20, 5);
        LocalDate orderDate = PliConverter.fromPliDate(bytes, 25, 8);
        
        return new OrderMessage(orderId, customerId, amount, orderDate);
    }
}

Transaction Management

XA Transactions with Messaging

@Configuration
@EnableTransactionManagement
public class XAMessagingConfig {
    
    @Bean
    public JmsTransactionManager transactionManager(
            ConnectionFactory connectionFactory) {
        return new JmsTransactionManager(connectionFactory);
    }
}

@Service
public class TransactionalMessagingService {
    
    @Transactional
    public void processWithTransaction(Order order) {
        // Save to database
        orderRepository.save(order);
        
        // Send message (part of same transaction)
        jmsTemplate.convertAndSend("order.processed", order);
        
        // Both commit or rollback together
    }
}

Monitoring and Error Handling

Message Metrics

@Component
public class MessagingMetrics {
    
    private final Counter messagesReceived;
    private final Counter messagesFailed;
    private final Timer processingTime;
    
    public MessagingMetrics(MeterRegistry registry) {
        this.messagesReceived = registry.counter("messages.received");
        this.messagesFailed = registry.counter("messages.failed");
        this.processingTime = registry.timer("messages.processing.time");
    }
    
    @Around("@annotation(JmsListener)")
    public Object monitorMessageProcessing(ProceedingJoinPoint pjp) throws Throwable {
        messagesReceived.increment();
        Timer.Sample sample = Timer.start();
        
        try {
            Object result = pjp.proceed();
            sample.stop(processingTime);
            return result;
        } catch (Exception e) {
            messagesFailed.increment();
            throw e;
        }
    }
}

Error Handling

@Service
public class MessagingErrorHandler {
    
    @JmsListener(destination = "order.queue")
    public void handleOrder(Order order, @Header("JMSRedelivered") boolean redelivered) {
        try {
            processOrder(order);
        } catch (Exception e) {
            if (redelivered) {
                // Already retried, send to DLQ
                sendToDeadLetterQueue(order, e);
            } else {
                // First failure, throw to trigger redelivery
                throw new RuntimeException("Processing failed", e);
            }
        }
    }
}

Migration Checklist

• [ ] Identify all MQ queue usages
• [ ] Map CICS transient data queues
• [ ] Choose appropriate messaging technology (JMS/AMQP/Kafka)
• [ ] Design message formats (JSON vs. binary)
• [ ] Implement message converters
• [ ] Configure error handling and DLQ
• [ ] Set up monitoring and alerting
• [ ] Test message ordering guarantees
• [ ] Verify transaction behavior
• [ ] Performance test under load
• [ ] Document migration patterns

Performance Patterns for Migrated Code

This document provides guidance on optimizing Java code migrated from COBOL, addressing common performance challenges.

Overview

COBOL programs often process large volumes of data efficiently using mainframe-optimized patterns. When migrating to Java, it's important to maintain or improve performance while adapting to modern architectures.

Common Performance Patterns

1. Batch Processing with Streams

COBOL Pattern: Sequential file processing Java Solution: Use Java Streams for efficient batch processing

// Instead of loading all records into memory
List<Record> records = loadAllRecords(); // DON'T

// Use streaming
try (Stream<String> lines = Files.lines(path)) {
    lines.map(this::parseRecord)
         .filter(this::isValid)
         .forEach(this::processRecord);
}

2. Database Batch Operations

COBOL Pattern: Cursor processing with commits every N records Java Solution: JDBC batch updates

try (PreparedStatement pstmt = conn.prepareStatement(sql)) {
    for (Record record : records) {
        pstmt.setString(1, record.getId());
        pstmt.setString(2, record.getName());
        pstmt.addBatch();
        
        if (++count % 1000 == 0) {
            pstmt.executeBatch();
            conn.commit();
        }
    }
    pstmt.executeBatch();
    conn.commit();
}

3. Memory Management

Challenge: COBOL's fixed memory model vs. Java's heap Solution: Process in chunks, use pagination

public void processLargeFile(Path file) {
    int batchSize = 1000;
    List<Record> batch = new ArrayList<>(batchSize);
    
    try (Stream<String> lines = Files.lines(file)) {
        lines.forEach(line -> {
            batch.add(parseRecord(line));
            if (batch.size() >= batchSize) {
                processBatch(new ArrayList<>(batch));
                batch.clear();
            }
        });
        if (!batch.isEmpty()) {
            processBatch(batch);
        }
    }
}

4. Parallel Processing

COBOL Pattern: Single-threaded sequential processing Java Solution: Parallel streams for CPU-bound operations

// For independent record processing
records.parallelStream()
       .map(this::transform)
       .forEach(this::save);

// Control parallelism
ForkJoinPool customPool = new ForkJoinPool(4);
customPool.submit(() ->
    records.parallelStream()
           .forEach(this::process)
).get();

5. String Operations

COBOL Pattern: Fixed-length strings with spaces Java Solution: Efficient string handling

// Avoid creating many temporary strings
StringBuilder sb = new StringBuilder();
for (Record r : records) {
    sb.append(r.getId()).append('|')
      .append(r.getName()).append('\n');
}
String output = sb.toString();

// For fixed-length COBOL fields
String padded = String.format("%-20s", value); // Left-padded
String numeric = String.format("%010d", number); // Zero-padded

6. Caching Lookup Tables

COBOL Pattern: In-memory tables loaded at startup Java Solution: Use efficient caching

// Simple cache
private final Map<String, RateEntry> rateCache = new HashMap<>();

// Caffeine cache with eviction
LoadingCache<String, RateEntry> cache = Caffeine.newBuilder()
    .maximumSize(10_000)
    .expireAfterWrite(1, TimeUnit.HOURS)
    .build(key -> loadRate(key));

7. File I/O Optimization

COBOL Pattern: Blocked records for efficient I/O Java Solution: Buffered I/O with appropriate buffer sizes

// Reading
try (BufferedReader reader = new BufferedReader(
        new FileReader(file), 8192 * 4)) { // 32KB buffer
    String line;
    while ((line = reader.readLine()) != null) {
        processLine(line);
    }
}

// Writing
try (BufferedWriter writer = new BufferedWriter(
        new FileWriter(file), 8192 * 4)) {
    for (Record r : records) {
        writer.write(r.toLine());
        writer.newLine();
    }
}

Performance Testing

Benchmark Template

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
@State(Scope.Thread)
public class MigrationBenchmark {
    
    @Param({"1000", "10000", "100000"})
    private int recordCount;
    
    @Setup
    public void setup() {
        // Initialize test data
    }
    
    @Benchmark
    public void testProcessing() {
        // Your processing logic
    }
}

Best Practices

1. Profile Before Optimizing: Use JProfiler, YourKit, or JFR 2. Set Realistic Goals: Match or exceed COBOL performance 3. Test with Production Volumes: Use representative data sizes 4. Monitor JVM Metrics: Heap, GC, thread pools 5. Use Appropriate Data Structures: ArrayList vs. LinkedList, HashMap vs. TreeMap 6. Minimize Object Creation: Reuse objects in tight loops 7. Consider Parallel Processing: But measure - not always faster 8. Optimize Database Access: Use connection pooling, prepared statements

Common Pitfalls

❌ DON'T: Load entire files into memory ✅ DO: Stream and process incrementally

❌ DON'T: Use + for string concatenation in loops ✅ DO: Use StringBuilder or StringJoiner

❌ DON'T: Create new SimpleDateFormat in loops (not thread-safe) ✅ DO: Use DateTimeFormatter (thread-safe) or ThreadLocal

❌ DON'T: Ignore connection pooling ✅ DO: Use HikariCP or similar

❌ DON'T: Assume parallel is always faster ✅ DO: Benchmark and measure

Monitoring Migration Performance

// Add metrics
public class ProcessingService {
    private final Timer processingTimer;
    private final Counter recordCounter;
    
    public void processRecords(List<Record> records) {
        Timer.Sample sample = Timer.start();
        try {
            records.forEach(this::process);
            recordCounter.increment(records.size());
        } finally {
            sample.stop(processingTimer);
        }
    }
}

PL/I to Java Migration Reference

Complete reference for analyzing PL/I programs and migrating to Java.

Table of Contents

• Data Type Mapping
• Code Pattern Conversions
• Key Transformation Rules
• Migration Checklist
• Common Pitfalls

---

Data Type Mapping

Type Conversion Table

Array Index Conversion

Critical: PL/I arrays are 1-based, Java arrays are 0-based.

DCL arr(10) FIXED DECIMAL(9,2);
arr(1) = 100.00;  /* First element */
arr(10) = 200.00; /* Last element */

BigDecimal[] arr = new BigDecimal[10];
arr[0] = new BigDecimal("100.00");  // First element
arr[9] = new BigDecimal("200.00");  // Last element

---

Code Pattern Conversions

Procedures to Methods

PL/I Procedure:

CALC_TOTAL: PROCEDURE(qty, price) RETURNS(FIXED DECIMAL(15,2));
    DCL qty FIXED DECIMAL(9,2);
    DCL price FIXED DECIMAL(9,2);
    DCL result FIXED DECIMAL(15,2);
    
    result = qty * price;
    IF result > 1000 THEN 
        result = result * 0.90; /* 10% discount */
    RETURN(result);
END CALC_TOTAL;

Java Method:

public BigDecimal calcTotal(BigDecimal qty, BigDecimal price) {
    BigDecimal result = qty.multiply(price);
    
    if (result.compareTo(new BigDecimal("1000")) > 0) {
        result = result.multiply(new BigDecimal("0.90")); // 10% discount
    }
    
    return result;
}

File I/O Operations

PL/I Sequential File Read:

DCL infile FILE INPUT RECORD SEQUENTIAL;
DCL rec CHARACTER(100);
DCL eof BIT(1) INIT('0'B);

ON ENDFILE(infile) eof = '1'B;
OPEN FILE(infile);

DO WHILE(¬eof);
    READ FILE(infile) INTO(rec);
    IF ¬eof THEN CALL process_record(rec);
END;

CLOSE FILE(infile);

Java File Read:

try (BufferedReader reader = Files.newBufferedReader(Paths.get("inputfile"))) {
    reader.lines().forEach(this::processRecord);
} catch (IOException e) {
    logger.error("Error reading file", e);
    throw new RuntimeException("Failed to process input file", e);
}

Structure to Class

PL/I Structure:

DCL 1 EMPLOYEE,
      2 ID CHARACTER(10),
      2 NAME CHARACTER(50),
      2 SALARY FIXED DECIMAL(9,2),
      2 HIRE_DATE CHARACTER(10);

Java Class:

public class Employee {
    private String id;
    private String name;
    private BigDecimal salary;
    private LocalDate hireDate;
    
    // Constructors
    public Employee() {}
    
    public Employee(String id, String name, BigDecimal salary, LocalDate hireDate) {
        this.id = id;
        this.name = name;
        this.salary = salary;
        this.hireDate = hireDate;
    }
    
    // Getters and Setters
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }
    
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    
    public BigDecimal getSalary() { return salary; }
    public void setSalary(BigDecimal salary) { this.salary = salary; }
    
    public LocalDate getHireDate() { return hireDate; }
    public void setHireDate(LocalDate hireDate) { this.hireDate = hireDate; }
}

Loop Conversions

DO WHILE:

DCL i FIXED BINARY(31);
i = 1;
DO WHILE(i <= 10);
    CALL process(i);
    i = i + 1;
END;

int i = 1;
while (i <= 10) {
    process(i);
    i++;
}

DO index = start TO end:

DCL i FIXED BINARY(31);
DO i = 1 TO 10;
    CALL process(i);
END;

for (int i = 1; i <= 10; i++) {
    process(i);
}

DO index = start TO end BY step:

DO i = 1 TO 10 BY 2;
    CALL process(i);
END;

for (int i = 1; i <= 10; i += 2) {
    process(i);
}

String Operations

Example - SUBSTR conversion:

DCL text CHARACTER(100);
DCL part CHARACTER(20);
text = 'The quick brown fox jumps';
part = SUBSTR(text, 5, 5);  /* 'quick' - position 5, length 5 */

String text = "The quick brown fox jumps";
String part = text.substring(4, 9);  // 'quick' - start 4, end 9 (0-based, exclusive end)

SELECT/WHEN to Switch/Case

PL/I SELECT:

SELECT (status);
    WHEN ('A') CALL handle_active();
    WHEN ('I') CALL handle_inactive();
    WHEN ('P') CALL handle_pending();
    OTHERWISE CALL handle_unknown();
END;

Java Switch (traditional):

switch (status) {
    case 'A':
        handleActive();
        break;
    case 'I':
        handleInactive();
        break;
    case 'P':
        handlePending();
        break;
    default:
        handleUnknown();
        break;
}

Java Switch (modern, Java 14+):

switch (status) {
    case 'A' -> handleActive();
    case 'I' -> handleInactive();
    case 'P' -> handlePending();
    default -> handleUnknown();
}

Exception Handling (ON Conditions)

PL/I ON Conditions:

DCL infile FILE INPUT;

ON ENDFILE(infile) GO TO end_processing;
ON ERROR BEGIN;
    PUT SKIP LIST('Error occurred');
    GO TO cleanup;
END;

OPEN FILE(infile);
/* processing */

end_processing:
    CLOSE FILE(infile);

Java Try-Catch:

try (BufferedReader reader = Files.newBufferedReader(path)) {
    // Processing
    String line;
    while ((line = reader.readLine()) != null) {
        processLine(line);
    }
} catch (IOException e) {
    logger.error("Error occurred", e);
    throw new RuntimeException("Failed to process file", e);
} finally {
    // Cleanup if needed
}

---

Key Transformation Rules

1. GO TO Statement Refactoring

Never translate GO TO directly. Refactor to structured control flow.

Anti-pattern (PL/I):

    IF error_flag THEN GO TO error_handler;
    CALL process_data();
    GO TO end_routine;

error_handler:
    CALL handle_error();
    
end_routine:
    RETURN;

Correct Java Pattern:

if (errorFlag) {
    handleError();
} else {
    processData();
}

2. FIXED DECIMAL Precision

Critical: Always preserve decimal precision. Never use float or double for financial calculations.

DCL amount FIXED DECIMAL(15,2);  /* 15 digits total, 2 decimal places */

// Correct
BigDecimal amount = new BigDecimal("0.00");

// WRONG - loses precision
double amount = 0.00;  // Never do this for financial data!

3. Array Bounds

Always adjust loop bounds when converting arrays:

DCL arr(10) FIXED DECIMAL(9,2);
DO i = 1 TO 10;
    PUT SKIP LIST(arr(i));
END;

BigDecimal[] arr = new BigDecimal[10];
for (int i = 0; i < 10; i++) {  // 0 to 9, not 1 to 10
    System.out.println(arr[i]);
}

4. Boolean Operations

---

Migration Checklist

Use this checklist for each PL/I program:

Analysis Phase

• [ ] Identify entry point (PROCEDURE OPTIONS(MAIN))
• [ ] Extract all DCL statements and create data dictionary
• [ ] Map all procedures to methods
• [ ] Identify file operations (READ, WRITE, OPEN, CLOSE)
• [ ] Extract all ON conditions and exception handlers
• [ ] Identify external procedure calls
• [ ] Document all %INCLUDE directives
• [ ] Map all GO TO statements for refactoring

Design Phase

• [ ] Convert structures to Java classes with appropriate types
• [ ] Use BigDecimal for all FIXED DECIMAL types
• [ ] Design exception handling strategy (map ON conditions)
• [ ] Plan file I/O migration (files vs database)
• [ ] Identify transaction boundaries
• [ ] Design API interfaces for procedure conversions
• [ ] Plan test data and validation approach

Implementation Phase

• [ ] Create POJOs for all data structures
• [ ] Implement service methods for procedures
• [ ] Convert file operations to Java I/O or database operations
• [ ] Implement exception handling with try-catch
• [ ] Refactor GO TO statements to structured flow
• [ ] Adjust array indexing (1-based to 0-based)
• [ ] Convert string operations (SUBSTR, INDEX)
• [ ] Add Bean Validation annotations (@NotNull, @Size, etc.)

Validation Phase

• [ ] Create unit tests for each converted procedure
• [ ] Test boundary conditions (arrays, strings)
• [ ] Validate decimal precision (BigDecimal calculations)
• [ ] Test exception handling paths
• [ ] Compare outputs with legacy system
• [ ] Performance testing
• [ ] Code review for Java best practices

---

Common Pitfalls

Pitfall 1: Using float/double for FIXED DECIMAL

Problem:

// WRONG
double salary = 1234.56;
double tax = salary * 0.15;

Solution:

// CORRECT
BigDecimal salary = new BigDecimal("1234.56");
BigDecimal tax = salary.multiply(new BigDecimal("0.15"));

Pitfall 2: Forgetting Array Index Offset

Problem:

// PL/I: arr(1) to arr(10)
// Java array of size 10, but accessing arr[1] to arr[10] causes ArrayIndexOutOfBoundsException

Solution:

// Adjust indices: PL/I arr(i) becomes Java arr[i-1]
// Or adjust loop: FOR i = 1 TO 10 becomes for (int i = 0; i < 10; i++)

Pitfall 3: Direct GO TO Translation

Problem:

// Attempting to use labels and goto (not supported in Java)

Solution:

// Refactor to if-else, loops, or early returns
// Use exceptions for error handling instead of jumping to error labels

Pitfall 4: String SUBSTR Off-by-One Errors

Problem:

// PL/I: SUBSTR(str, 5, 10) starts at position 5 (1-based)
// Java: str.substring(5, 10) starts at index 5 (0-based)

Solution:

// PL/I SUBSTR(str, pos, len) → Java str.substring(pos-1, pos-1+len)
// Example: SUBSTR(str, 5, 10) → str.substring(4, 14)

Pitfall 5: Ignoring File vs Database Migration

Problem:

// Simply converting FILE operations to File I/O without considering database

Solution:

// Evaluate if sequential file processing should become database operations
// Consider transaction management, concurrent access, data integrity

Pitfall 6: Not Handling NULL Values

Problem:

// PL/I has implicit initialization, Java requires explicit null handling

Solution:

// Use Optional<T> or null checks
// Add @NotNull, @Nullable annotations
// Implement proper null validation

---

Additional Resources

For specific topics, see:

• Pseudocode translation: pseudocode-pli-rules.md
• Transaction patterns: transaction-handling.md
• Performance optimization: performance-patterns.md
• Messaging integration: messaging-integration.md
• Testing strategies: testing-strategy.md

Pseudocode Common Rules - All Languages

Naming Conventions

• Variables: camelCase (inputCount, customerName)
• Types/Structures: PascalCase (CustomerRecord, OrderDetail)
• Constants: UPPER_SNAKE_CASE (MAX_RECORDS, TAX_RATE)
• Functions/Procedures: PascalCase with verb (ProcessRecord, CalculateTotal)

Data Types

• INTEGER - whole numbers
• DECIMAL(n,m) - financial precision (n digits, m decimals)
• STRING[n] - text (max n characters)
• BOOLEAN - true/false
• DATE / DATETIME - dates/times
• ARRAY[n] OF TYPE - arrays
• STRUCTURE - composite types

Pseudocode Syntax

Structure Definition

STRUCTURE StructureName:
    field: TYPE[length]    // Description
END STRUCTURE

Constants

CONSTANTS:
    NAME = value
END CONSTANTS

Functions/Procedures

FUNCTION Name(param: TYPE) RETURNS TYPE
BEGIN
    RETURN value
END FUNCTION

PROCEDURE Name(param: TYPE)
BEGIN
    statements
END PROCEDURE

Control Flow

IF condition THEN ... ELSE ... END IF
WHILE condition DO ... END WHILE
FOR i FROM start TO end BY step DO ... END FOR
SWITCH expr: CASE val: ... BREAK; DEFAULT: ... END SWITCH

File Operations

file = OPEN(path) FOR READING|WRITING|APPENDING
record = READ_RECORD(file)
WRITE_RECORD(file, record)
CLOSE(file)
IF END_OF_FILE(file) THEN ...

Error Handling

TRY:
    statements
CATCH ExceptionType:
    handler
FINALLY:
    cleanup
END TRY

Financial Precision Rule

CRITICAL: Always use DECIMAL(n,m) for money. Never use floating point.

amount: DECIMAL(15,2)
result = ROUND(calculation, 2)  // Use HALF_UP rounding

Mermaid Flowchart Template

````mermaid flowchart TD Start([Start]) Process[Process Step] Decision{Condition?} End([End])

Start --> Process Process --> Decision Decision -->|Yes| End Decision -->|No| Process ````

Document Structure Template

# [PROGRAM-NAME] - Description

## Program Overview
- Purpose, Input, Output, Original Source

## Data Structures
[Structures and constants]

## Main Algorithm
[High-level flow]

## Core Processing Logic
[Detailed procedures]

## Flowchart (Mermaid)
[Diagram]

## Decision Logic / Special Cases / Error Handling
[Business rules and edge cases]

## Example Traces / Testing / Integration Points
[Walkthroughs and dependencies]

PL/I Translation Rules

Prerequisites: Read pseudocode-common-rules.md for syntax, naming, and structure.

---

Structure Mapping

Data Types

Statement Mapping

Built-in Functions

Translation Patterns

Procedure → Function

CALC_TOTAL: PROCEDURE(qty, price) RETURNS(FIXED DECIMAL(15,2));
    DCL qty FIXED DECIMAL(7,2);
    DCL price FIXED DECIMAL(9,2);
    RETURN(qty * price);
END CALC_TOTAL;

→

FUNCTION CalcTotal(qty: DECIMAL(7,2), price: DECIMAL(9,2)): DECIMAL(15,2)
BEGIN
    RETURN qty * price
END FUNCTION

ON Condition → TRY-CATCH

ON ENDFILE(infile) EOF = '1'B;
READ FILE(infile) INTO(rec);

→

TRY
    record = READ_RECORD(inFile)
CATCH EndOfFile
    eof = TRUE
END TRY

Structure Declaration

DCL 1 EMPLOYEE,
      2 ID CHAR(10),
      2 NAME CHAR(50),
      2 SALARY FIXED DECIMAL(9,2);

→

STRUCTURE Employee
    id: STRING[10]
    name: STRING[50]
    salary: DECIMAL(9,2)
END STRUCTURE

File Processing Loop

ON ENDFILE(INFILE) EOF = '1'B;
OPEN FILE(INFILE) INPUT;
EOF = '0'B;
DO WHILE(EOF = '0'B);
    READ FILE(INFILE) INTO(RECORD);
    IF EOF = '0'B THEN
        CALL PROCESS_RECORD(RECORD);
END;
CLOSE FILE(INFILE);

→

PROCEDURE ProcessFile(filePath: STRING)
BEGIN
    file = OPEN(filePath) FOR READING
    
    WHILE NOT END_OF_FILE(file) DO
        TRY
            record = READ_RECORD(file)
            CALL ProcessRecord(record)
        CATCH EndOfFile
            BREAK
        END TRY
    END WHILE
    
    CLOSE(file)
END PROCEDURE

DO UNTIL Loop

DO UNTIL(condition);
    statements;
END;

→

REPEAT
    statements
UNTIL condition

SELECT/WHEN → SWITCH/CASE

SELECT;
    WHEN (code = 'A') result = 10;
    WHEN (code = 'B') result = 20;
    WHEN (code = 'C') result = 30;
    OTHERWISE result = 0;
END;

→

SWITCH code
    CASE 'A': result = 10; BREAK
    CASE 'B': result = 20; BREAK
    CASE 'C': result = 30; BREAK
    DEFAULT: result = 0
END SWITCH

Array Operations

DCL TOTALS(12) FIXED DECIMAL(15,2);
DO I = 1 TO 12;
    TOTALS(I) = 0;
END;

→

totals: ARRAY[12] OF DECIMAL(15,2)
FOR i FROM 1 TO 12 DO
    totals[i] = 0
END FOR

String Concatenation

FULL_NAME = TRIM(FIRST_NAME) || ' ' || TRIM(LAST_NAME);

→

fullName = TRIM(firstName) + ' ' + TRIM(lastName)

Nested Structures

DCL 1 ORDER,
      2 ORDER_ID CHAR(10),
      2 CUSTOMER,
        3 CUST_ID CHAR(8),
        3 CUST_NAME CHAR(50),
      2 AMOUNT FIXED DECIMAL(15,2);

→

STRUCTURE Customer
    custId: STRING[8]
    custName: STRING[50]
END STRUCTURE

STRUCTURE Order
    orderId: STRING[10]
    customer: Customer
    amount: DECIMAL(15,2)
END STRUCTURE

Entry Parameters

CALC_TAX: PROCEDURE(amount, rate) RETURNS(FIXED DECIMAL(15,2));
    DCL amount FIXED DECIMAL(15,2);
    DCL rate FIXED DECIMAL(5,4);
    RETURN(amount * rate);
END CALC_TAX;

→

FUNCTION CalcTax(amount: DECIMAL(15,2), rate: DECIMAL(5,4)): DECIMAL(15,2)
BEGIN
    RETURN amount * rate
END FUNCTION

Critical Rules

1. 1-based indexing: PL/I arrays start at 1 (preserve or document) 2. FIXED DECIMAL: MUST map to DECIMAL with exact precision 3. FLOAT: Prohibited for financial calculations - always use DECIMAL 4. ON conditions: Map to TRY-CATCH blocks 5. GO TO: Refactor to structured control flow 6. Bit strings: Convert '1'B/'0'B to TRUE/FALSE8. Substring positions: PL/I uses 1-based indexing (document conversion to 0-based if needed) 7. File buffers: LOCATE allocates buffer - map to appropriate memory management 8. Concatenation: || operator maps to + or CONCAT()

Common PL/I Idioms

Initialization Pattern

DCL counter FIXED BIN(31) INIT(0);

→

counter: INTEGER = 0

Null String Check

IF name = '' THEN ...

→

IF name = '' OR name = NULL THEN ...

Numeric Validation

ON CONVERSION SNAP;
value = input_string;
REVERT CONVERSION;

→

TRY
    value = CONVERT_TO_NUMBER(inputString)
CATCH ConversionError
    // Handle invalid input
END TRY

Counter Increment

count = count + 1;

→

count = count + 1  // or INCREMENT(count)

Boolean Toggle

flag = ¬flag;  /* or */ flag = ^flag;

→

flag = NOT flag

Range Check

IF value >= MIN_VALUE & value <= MAX_VALUE THEN ...

→

IF value >= MIN_VALUE AND value <= MAX_VALUE THEN ...

Packed Decimal Precision

DCL price FIXED DECIMAL(9,2);  /* 999999999.99 */

→

price: DECIMAL(9,2)  // CRITICAL: Preserve exact precision!

Translation Workflow

Step-by-Step Process

1. Identify Program Structure

• Locate PROCEDURE OPTIONS(MAIN) → Main entry point
• List all nested procedures → Subroutines
• Map %INCLUDE directives → Dependencies

2. Extract Data Declarations

• Convert all DCL/DECLARE → Data Structures
• ⚠️ CRITICAL: Preserve FIXED DECIMAL(n,m) precision exactly
• Map FILE declarations → File definitions
• Identify constants (INIT values)

3. Translate Control Flow

• Map DO WHILE/DO UNTIL → WHILE/REPEAT loops
• Convert SELECT/WHEN → SWITCH/CASE
• Refactor GO TO → Structured flow
• Preserve loop counters (1-based indexing)

4. Convert Exception Handling

• Map ON ENDFILE → TRY-CATCH EndOfFile
• Convert ON ERROR → General exception handling
• Translate ON CONVERSION, OVERFLOW, etc. → Specific catches
• Document REVERT statements

5. Translate Procedures

• Convert PROCEDURE → FUNCTION (if RETURNS) or PROCEDURE
• Map parameters → Typed parameters
• Preserve return types with exact precision
• Document ENTRY points if multiple

6. Process File I/O

• OPEN FILE → OPEN with mode
• READ/WRITE → Corresponding operations
• Handle LOCATE buffer allocations
• Map CLOSE operations

7. Translate Built-in Functions

• Map all BIFs using table above
• Document 1-based SUBSTR positions
• Preserve rounding behavior

8. Generate Documentation

• Create Program Overview section
• Document all Data Structures
• Write Main Algorithm (high-level)
• Detail Core Processing Logic
• Add Mermaid flowchart
• Include Decision Logic and edge cases

9. Validation Checklist

• ✅ All FIXED DECIMAL preserved (no float!)
• ✅ 1-based indexing documented
• ✅ File operations properly handled
• ✅ Exception handling comprehensive
• ✅ No GO TO statements (refactored)
• ✅ All procedures translated
• ✅ Bit strings converted to boolean
• ✅ Flowchart matches logic

Best Practices

1. Always preserve numeric precision - FIXED DECIMAL(n,m) must map to DECIMAL(n,m) 2. Document indexing - Note 1-based arrays if converting to 0-based 3. Simplify nested structures - Break complex hierarchies into clear types 4. Eliminate GO TO - Use structured programming (loops, functions) 5. Handle all ON conditions - Don't skip exception scenarios 6. Test numeric calculations - Verify precision in edge cases 7. Document assumptions - Note any PL/I-specific behaviors

Reference: IBM Enterprise PL/I for z/OS Language Reference

Testing Strategy for PL/I to Java Migration

Comprehensive testing approach to ensure functional equivalence and quality during migration from PL/I programs to Java.

Testing Pyramid for Migration

                    /\
                   /  \
                  / E2E\
                 /------\
                /  Integ \
               /----------\
              /    Unit    \
             /--------------\

1. Unit Testing

Testing Converted Business Logic

Goal: Verify each Java method matches PL/I procedure behavior

@Test
void testCalculateBonus_seniorEmployee() {
    // Given
    Employee emp = new Employee();
    emp.setYearsOfService(12);
    emp.setSalary(new BigDecimal("50000"));
    
    // When
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    // Then
    assertEquals(new BigDecimal("7500.00"), bonus);
}

@Test
void testCalculateBonus_midLevelEmployee() {
    Employee emp = new Employee();
    emp.setYearsOfService(7);
    emp.setSalary(new BigDecimal("40000"));
    
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    assertEquals(new BigDecimal("4000.00"), bonus);
}

@Test
void testCalculateBonus_juniorEmployee() {
    Employee emp = new Employee();
    emp.setYearsOfService(2);
    emp.setSalary(new BigDecimal("30000"));
    
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    assertEquals(new BigDecimal("1500.00"), bonus);
}

Testing Data Transformations

@Test
void testPliToJavaDataConversion() {
    // PL/I FIXED DECIMAL(7,2)
    String pliPackedDecimal = "0000012345C"; // 123.45
    
    BigDecimal result = converter.fromPackedDecimal(pliPackedDecimal);
    
    assertEquals(new BigDecimal("123.45"), result);
}

@Test
void testDateConversion() {
    // PL/I date format: YYYYMMDD
    String pliDate = "20260113";
    
    LocalDate result = converter.fromPliDate(pliDate);
    
    assertEquals(LocalDate.of(2026, 1, 13), result);
}

Parameterized Tests for Edge Cases

@ParameterizedTest
@CsvSource({
    "0, 0.00",
    "1, 1500.00",
    "5, 2000.00",
    "6, 4000.00",
    "10, 4000.00",
    "11, 7500.00",
    "20, 7500.00"
})
void testBonusCalculation_allRanges(int years, String expectedBonus) {
    Employee emp = new Employee();
    emp.setYearsOfService(years);
    emp.setSalary(new BigDecimal("50000"));
    
    BigDecimal bonus = bonusCalculator.calculate(emp);
    
    assertEquals(new BigDecimal(expectedBonus), bonus);
}

2. Integration Testing

Database Operations

@SpringBootTest
@Transactional
class CustomerRepositoryTest {
    
    @Autowired
    private CustomerRepository customerRepo;
    
    @Test
    void testSaveAndRetrieve() {
        // Given
        Customer customer = new Customer();
        customer.setId("CUST001");
        customer.setName("Test Customer");
        
        // When
        customerRepo.save(customer);
        entityManager.flush();
        entityManager.clear();
        
        // Then
        Optional<Customer> retrieved = customerRepo.findById("CUST001");
        assertTrue(retrieved.isPresent());
        assertEquals("Test Customer", retrieved.get().getName());
    }
}

File Processing

@SpringBootTest
class FileProcessorTest {
    
    @Autowired
    private FileProcessor processor;
    
    @TempDir
    Path tempDir;
    
    @Test
    void testProcessInputFile() throws IOException {
        // Given
        Path inputFile = tempDir.resolve("input.txt");
        Files.write(inputFile, Arrays.asList(
            "CUST001John Doe      00012345",
            "CUST002Jane Smith   00067890"
        ));
        
        // When
        ProcessingResult result = processor.process(inputFile);
        
        // Then
        assertEquals(2, result.getProcessedCount());
        assertEquals(0, result.getErrorCount());
    }
}

3. Parallel Run Testing

Strategy: Run Both Systems in Parallel

Goal: Prove functional equivalence with production data

@Service
public class ParallelRunService {
    
    @Autowired
    private LegacySystemAdapter legacyAdapter;
    
    @Autowired
    private NewJavaService newService;
    
    @Autowired
    private ResultComparator comparator;
    
    public ProcessingResult processWithComparison(InputData input) {
        // Run new system
        Result newResult = newService.process(input);
        
        // Run legacy system (asynchronously)
        CompletableFuture<Result> legacyFuture = 
            CompletableFuture.supplyAsync(() -> legacyAdapter.process(input));
        
        // Compare results
        legacyFuture.thenAccept(legacyResult -> {
            ComparisonResult comparison = comparator.compare(newResult, legacyResult);
            if (!comparison.isMatch()) {
                logDiscrepancy(input, newResult, legacyResult, comparison);
            }
        });
        
        // Return new result (legacy is shadow)
        return newResult;
    }
}

Result Comparison

@Service
public class ResultComparator {
    
    public ComparisonResult compare(Result actual, Result expected) {
        ComparisonResult result = new ComparisonResult();
        
        // Compare numeric fields with tolerance
        if (!compareDecimal(actual.getAmount(), expected.getAmount(), 0.01)) {
            result.addDifference("amount", expected.getAmount(), actual.getAmount());
        }
        
        // Compare strings (trim for PL/I fixed-length CHARACTER spaces)
        if (!actual.getName().trim().equals(expected.getName().trim())) {
            result.addDifference("name", expected.getName(), actual.getName());
        }
        
        // Compare dates
        if (!actual.getDate().equals(expected.getDate())) {
            result.addDifference("date", expected.getDate(), actual.getDate());
        }
        
        return result;
    }
    
    private boolean compareDecimal(BigDecimal a, BigDecimal b, double tolerance) {
        return a.subtract(b).abs().doubleValue() <= tolerance;
    }
}

4. End-to-End Testing

Full Workflow Testing

@SpringBootTest
@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
class OrderWorkflowE2ETest {
    
    @Test
    @Order(1)
    void test_completeOrderWorkflow() {
        // Step 1: Create order
        OrderRequest request = new OrderRequest();
        request.setCustomerId("CUST001");
        request.addItem("ITEM001", 2);
        
        Order order = orderService.createOrder(request);
        assertNotNull(order.getId());
        
        // Step 2: Process payment
        PaymentResult payment = paymentService.process(order);
        assertEquals(PaymentStatus.APPROVED, payment.getStatus());
        
        // Step 3: Ship order
        ShipmentResult shipment = shippingService.ship(order);
        assertEquals(ShipmentStatus.SHIPPED, shipment.getStatus());
        
        // Step 4: Verify final state
        Order finalOrder = orderService.getOrder(order.getId());
        assertEquals(OrderStatus.COMPLETED, finalOrder.getStatus());
    }
}

5. Performance Testing

Baseline Comparison

@State(Scope.Thread)
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.SECONDS)
public class PerformanceBenchmark {
    
    private List<Record> testData;
    
    @Setup
    public void setup() {
        testData = generateTestData(10000);
    }
    
    @Benchmark
    public void testJavaImplementation() {
        javaService.process(testData);
    }
    
    // Compare with baseline from PL/I system
    // Target: >= 90% of PL/I throughput
}

Load Testing

@SpringBootTest
class LoadTest {
    
    @Test
    void testConcurrentProcessing() throws InterruptedException {
        int threadCount = 10;
        int iterationsPerThread = 100;
        ExecutorService executor = Executors.newFixedThreadPool(threadCount);
        
        List<Future<?>> futures = new ArrayList<>();
        
        for (int i = 0; i < threadCount; i++) {
            futures.add(executor.submit(() -> {
                for (int j = 0; j < iterationsPerThread; j++) {
                    orderService.processOrder(createTestOrder());
                }
            }));
        }
        
        // Wait for completion
        for (Future<?> future : futures) {
            future.get();
        }
        
        executor.shutdown();
        
        // Verify results
        long totalOrders = orderRepository.count();
        assertEquals(threadCount * iterationsPerThread, totalOrders);
    }
}

6. Data Migration Testing

Data Validation

@SpringBootTest
class DataMigrationTest {
    
    @Test
    void validateMigratedCustomers() {
        // Load from legacy system
        List<LegacyCustomer> legacyCustomers = legacyDataSource.getAllCustomers();
        
        // Compare with migrated data
        for (LegacyCustomer legacy : legacyCustomers) {
            Customer migrated = customerRepo.findById(legacy.getId())
                .orElseThrow(() -> new AssertionError("Customer not migrated: " + legacy.getId()));
            
            assertEquals(legacy.getName().trim(), migrated.getName());
            assertEquals(legacy.getBalance(), migrated.getBalance());
            // ... more assertions
        }
    }
    
    @Test
    void verifyDataIntegrity() {
        // Check referential integrity
        List<Order> orders = orderRepo.findAll();
        for (Order order : orders) {
            assertTrue(customerRepo.existsById(order.getCustomerId()),
                "Order references non-existent customer: " + order.getId());
        }
    }
}

7. Regression Testing

Automated Regression Suite

@SpringBootTest
@Tag("regression")
class RegressionTestSuite {
    
    @Nested
    @DisplayName("Customer Management")
    class CustomerTests {
        
        @Test
        void testCreateCustomer() { /* ... */ }
        
        @Test
        void testUpdateCustomer() { /* ... */ }
        
        @Test
        void testDeleteCustomer() { /* ... */ }
    }
    
    @Nested
    @DisplayName("Order Processing")
    class OrderTests {
        // ... order tests
    }
}

Test Data Strategy

Using Production-Like Data

@TestConfiguration
public class TestDataConfig {
    
    @Bean
    public TestDataGenerator testDataGenerator() {
        return TestDataGenerator.builder()
            .withCustomerCount(1000)
            .withOrderCount(5000)
            .withProductCount(100)
            .withRealisticDistribution(true)
            .build();
    }
}

Anonymizing Production Data

public class DataAnonymizer {
    
    public Customer anonymize(Customer customer) {
        Customer anonymized = new Customer();
        anonymized.setId(customer.getId());
        anonymized.setName(generateFakeName());
        anonymized.setEmail(generateFakeEmail());
        anonymized.setBalance(customer.getBalance()); // Keep financial data
        return anonymized;
    }
}

Test Automation

CI/CD Integration

# .github/workflows/test.yml
name: Migration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v2
      
      - name: Set up JDK
        uses: actions/setup-java@v2
        with:
          java-version: '17'
      
      - name: Run Unit Tests
        run: ./mvnw test
      
      - name: Run Integration Tests
        run: ./mvnw verify -P integration-tests
      
      - name: Run E2E Tests
        run: ./mvnw verify -P e2e-tests
      
      - name: Generate Coverage Report
        run: ./mvnw jacoco:report

Coverage Goals

• Unit Test Coverage: ≥ 80% line coverage
• Integration Test Coverage: All APIs and database operations
• E2E Coverage: All critical business workflows
• Parallel Run Coverage: 100% of transactions for 30 days

Test Documentation

Test Case Template

/**
 * Test: Calculate bonus for senior employee
 * 
 * PL/I Reference: PROGRAM_NAME, procedure CALC_BONUS
 * 
 * Business Rule: Employees with >10 years service get 15% bonus
 * 
 * Test Data:
 * - Years of service: 12
 * - Salary: $50,000
 * 
 * Expected Result: $7,500 bonus
 */
@Test
void testCalculateBonus_seniorEmployee() {
    // Test implementation
}

Monitoring Test Results

@ExtendWith(TestResultLogger.class)
class MonitoredTest {
    
    @Test
    void testWithMonitoring() {
        // Test execution metrics logged automatically
    }
}

class TestResultLogger implements TestWatcher {
    
    @Override
    public void testSuccessful(ExtensionContext context) {
        log.info("Test passed: {}", context.getDisplayName());
        metricsService.recordTestSuccess(context);
    }
    
    @Override
    public void testFailed(ExtensionContext context, Throwable cause) {
        log.error("Test failed: {}", context.getDisplayName(), cause);
        metricsService.recordTestFailure(context, cause);
    }
}

Checklist

• [ ] Unit tests for all business logic methods
• [ ] Integration tests for data access
• [ ] E2E tests for critical workflows
• [ ] Performance tests vs. baseline
• [ ] Parallel run for 30 days minimum
• [ ] Data migration validation
• [ ] Regression suite automated
• [ ] Test data anonymized
• [ ] CI/CD pipeline configured
• [ ] Coverage reports generated
• [ ] Test documentation complete

Transaction Handling in Migrated Applications

This document explains how to handle transactions when migrating from CICS/mainframe environments to Java.

Overview

PL/I programs running under CICS or IMS use implicit transaction management. In Java, transactions must be explicitly managed using appropriate frameworks and patterns.

CICS Transaction Concepts

CICS Transaction Model

Key Characteristics:

• Implicit transaction boundaries
• SYNCPOINT for explicit commits
• Automatic rollback on ABEND
• Resource coordination (files, databases, queues)
• Conversational vs. pseudo-conversational

Common CICS Commands

/* PL/I CICS commands */
EXEC CICS SYNCPOINT;
EXEC CICS SYNCPOINT ROLLBACK;
EXEC CICS LINK PROGRAM(name);
EXEC CICS RETURN;

Java Transaction Patterns

1. Programmatic Transactions

For simple cases, use JDBC transactions:

Connection conn = dataSource.getConnection();
try {
    conn.setAutoCommit(false);
    
    // Perform operations
    updateCustomer(conn, customer);
    insertOrder(conn, order);
    
    conn.commit();
} catch (Exception e) {
    conn.rollback();
    throw e;
} finally {
    conn.close();
}

2. Declarative Transactions (Spring)

For most migrations, use Spring's declarative approach:

@Service
@Transactional
public class OrderService {
    
    @Autowired
    private CustomerRepository customerRepo;
    
    @Autowired
    private OrderRepository orderRepo;
    
    @Transactional
    public void processOrder(OrderRequest request) {
        // All operations in one transaction
        Customer customer = customerRepo.findById(request.getCustomerId())
            .orElseThrow(() -> new CustomerNotFoundException());
        
        Order order = new Order();
        order.setCustomer(customer);
        order.setAmount(request.getAmount());
        
        orderRepo.save(order);
        
        // Transaction commits automatically on success
        // Rolls back on unchecked exceptions
    }
    
    @Transactional(readOnly = true)
    public Order getOrder(Long orderId) {
        // Read-only optimization
        return orderRepo.findById(orderId)
            .orElseThrow(() -> new OrderNotFoundException());
    }
}

3. Transaction Propagation

Map CICS patterns to Spring propagation:

// CICS: New transaction (like EXEC CICS LINK SYNCONRETURN)
@Transactional(propagation = Propagation.REQUIRES_NEW)
public void processInNewTransaction() {
    // Runs in separate transaction
}

// CICS: Join existing transaction
@Transactional(propagation = Propagation.REQUIRED)
public void processInCurrentTransaction() {
    // Joins existing or creates new
}

// CICS: No transaction coordination
@Transactional(propagation = Propagation.NOT_SUPPORTED)
public void processWithoutTransaction() {
    // Suspends any existing transaction
}

4. Isolation Levels

Match CICS resource locking to SQL isolation:

// CICS UPDATE (exclusive lock)
@Transactional(isolation = Isolation.SERIALIZABLE)
public void updateWithExclusiveLock() {
    // Prevents concurrent access
}

// CICS READ (shared lock)
@Transactional(isolation = Isolation.REPEATABLE_READ)
public void readWithConsistency() {
    // Consistent reads within transaction
}

Migration Patterns

Pattern 1: Batch SYNCPOINT

PL/I/CICS:

/* Process records with periodic commits */
DCL counter FIXED BINARY(31) INIT(0);

DO WHILE (counter <= 1000);
    CALL PROCESS_RECORD();
    counter = counter + 1;
    
    IF counter = 100 THEN DO;
        EXEC CICS SYNCPOINT;
        counter = 0;
    END;
END;

Java:

@Service
public class BatchProcessor {
    
    @Autowired
    private TransactionTemplate transactionTemplate;
    
    public void processBatch(List<Record> records) {
        int batchSize = 100;
        List<Record> batch = new ArrayList<>();
        
        for (Record record : records) {
            batch.add(record);
            
            if (batch.size() >= batchSize) {
                processBatchInTransaction(new ArrayList<>(batch));
                batch.clear();
            }
        }
        
        if (!batch.isEmpty()) {
            processBatchInTransaction(batch);
        }
    }
    
    private void processBatchInTransaction(List<Record> batch) {
        transactionTemplate.execute(status -> {
            batch.forEach(this::processRecord);
            return null;
        });
    }
}

Pattern 2: Compensating Transactions

Challenge: Multi-system transactions without XA Solution: Saga pattern

@Service
public class OrderSagaService {
    
    public void processOrder(OrderRequest request) {
        String sagaId = UUID.randomUUID().toString();
        
        try {
            // Step 1: Reserve inventory
            String reservationId = inventoryService.reserve(request.getItems());
            
            // Step 2: Charge payment
            String paymentId = paymentService.charge(request.getPayment());
            
            // Step 3: Create order
            Order order = orderService.create(request, reservationId, paymentId);
            
            // Success - commit all
            inventoryService.confirm(reservationId);
            paymentService.confirm(paymentId);
            
        } catch (Exception e) {
            // Compensate in reverse order
            if (paymentId != null) {
                paymentService.refund(paymentId);
            }
            if (reservationId != null) {
                inventoryService.release(reservationId);
            }
            throw new OrderProcessingException("Order failed", e);
        }
    }
}

Pattern 3: Distributed Transactions (XA)

For true 2-phase commit across resources:

@Configuration
public class XAConfig {
    
    @Bean
    public PlatformTransactionManager transactionManager() {
        JtaTransactionManager tm = new JtaTransactionManager();
        tm.setTransactionManager(atomikosTransactionManager());
        return tm;
    }
    
    @Bean
    public DataSource xaDataSource1() {
        AtomikosDataSourceBean ds = new AtomikosDataSourceBean();
        ds.setUniqueResourceName("db1");
        ds.setXaDataSourceClassName("org.postgresql.xa.PGXADataSource");
        // ... configuration
        return ds;
    }
    
    @Bean
    public DataSource xaDataSource2() {
        AtomikosDataSourceBean ds = new AtomikosDataSourceBean();
        ds.setUniqueResourceName("db2");
        // ... configuration
        return ds;
    }
}

@Service
public class DistributedService {
    
    @Transactional
    public void updateBothDatabases() {
        // Both updates in same XA transaction
        db1Repository.update(data1);
        db2Repository.update(data2);
        // Atomikos coordinates 2PC
    }
}

Error Handling

CICS ABEND → Java Exception

PL/I/CICS:

IF error_condition THEN DO;
    EXEC CICS ABEND ABCODE('APPL');
END;

Java:

@Transactional
public void process() {
    if (errorCondition) {
        // Unchecked exception triggers rollback
        throw new ApplicationException("APPL");
    }
}

// For checked exceptions that should rollback
@Transactional(rollbackFor = BusinessException.class)
public void processWithChecked() throws BusinessException {
    if (errorCondition) {
        throw new BusinessException("Error occurred");
    }
}

Testing Strategies

Unit Testing with Transactions

@SpringBootTest
@Transactional
class OrderServiceTest {
    
    @Autowired
    private OrderService orderService;
    
    @Test
    @Rollback  // Default behavior
    void testOrderProcessing() {
        // Test runs in transaction
        // Automatically rolled back after test
        Order order = orderService.processOrder(request);
        assertNotNull(order.getId());
    }
    
    @Test
    @Commit  // Explicitly commit for verification
    void testOrderPersistence() {
        Order order = orderService.processOrder(request);
        // Verify in separate transaction
    }
}

Integration Testing

@SpringBootTest
@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_EACH_TEST_METHOD)
class TransactionIntegrationTest {
    
    @Test
    void testRollbackOnError() {
        assertThrows(BusinessException.class, () -> {
            orderService.processInvalidOrder(invalidRequest);
        });
        
        // Verify rollback
        assertFalse(orderRepository.findById(orderId).isPresent());
    }
}

Configuration Best Practices

Spring Boot Configuration

spring:
  datasource:
    hikari:
      auto-commit: false
      maximum-pool-size: 20
      connection-timeout: 30000
  jpa:
    properties:
      hibernate:
        connection:
          isolation: 2  # READ_COMMITTED
        jdbc:
          batch_size: 50
        order_inserts: true
        order_updates: true

Transaction Manager Tuning

@Configuration
public class TransactionConfig {
    
    @Bean
    public PlatformTransactionManager transactionManager(EntityManagerFactory emf) {
        JpaTransactionManager tm = new JpaTransactionManager(emf);
        tm.setDefaultTimeout(30);  // 30 seconds
        return tm;
    }
}

Monitoring and Debugging

Enable Transaction Logging

logging:
  level:
    org.springframework.transaction: DEBUG
    org.springframework.orm.jpa: DEBUG
    org.hibernate.engine.transaction: DEBUG

Transaction Events

@Component
public class TransactionEventListener {
    
    @TransactionalEventListener(phase = TransactionPhase.BEFORE_COMMIT)
    public void beforeCommit(OrderCreatedEvent event) {
        log.info("About to commit order: {}", event.getOrderId());
    }
    
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMPLETION)
    public void afterCompletion(OrderCreatedEvent event) {
        log.info("Transaction completed for order: {}", event.getOrderId());
    }
}

Common Issues and Solutions

Issue: Lost Updates

Problem: Concurrent modifications Solution: Use optimistic or pessimistic locking

@Entity
public class Account {
    @Id
    private Long id;
    
    @Version  // Optimistic locking
    private Long version;
    
    private BigDecimal balance;
}

// Or pessimistic locking
@Lock(LockModeType.PESSIMISTIC_WRITE)
Account findById(Long id);

Issue: Long-Running Transactions

Problem: Locks held too long Solution: Minimize transaction scope

// Bad: Transaction spans user interaction
@Transactional
public void processOrderBad(OrderRequest request) {
    Order order = createOrder(request);
    sendEmail(order);  // Slow!
    updateInventory(order);
}

// Good: Transaction only for data operations
public void processOrderGood(OrderRequest request) {
    Order order;
    
    // Transaction scope
    order = transactionTemplate.execute(status -> {
        Order o = createOrder(request);
        updateInventory(o);
        return o;
    });
    
    // Outside transaction
    sendEmail(order);
}

Migration Checklist

• [ ] Identify all SYNCPOINT locations
• [ ] Map CICS transaction boundaries
• [ ] Determine isolation requirements
• [ ] Plan for distributed transactions
• [ ] Define compensating actions
• [ ] Implement error handling
• [ ] Add transaction monitoring
• [ ] Test rollback scenarios
• [ ] Performance test with load
• [ ] Document transaction flows