COBOL to Java Conversion

Overview

Comprehensive guide for converting COBOL mainframe applications to modern Java, preserving business logic while adopting cloud-native architecture patterns. This skill is specifically tailored for the CardDemo application but provides general best practices applicable to any COBOL modernization effort.

When to Use This Skill

• •Converting COBOL online CICS programs to Java Spring Boot REST services
• •Migrating COBOL batch programs to Java scheduled jobs or Spring Batch
• •Translating COBOL copybooks to Java POJOs
• •Migrating VSAM files to SQL databases
• •Modernizing DB2/IMS data access to JPA/JDBC

Prerequisites

Knowledge Required

• •Understanding of COBOL syntax and mainframe concepts (CICS, VSAM, JCL)
• •Java development experience (Spring Boot, JPA, REST APIs)
• •Database knowledge (SQL, transactions, data modeling)

Tools Required

• •AWS Transform (optional but recommended for automated analysis)
• •IDE: IntelliJ IDEA or Eclipse with COBOL plugin
• •Build Tools: Maven or Gradle
• •Database: PostgreSQL, MySQL, or Oracle
• •Testing: JUnit 5, Mockito, Spring Test

Environment Setup

1. •Clone this repository
2. •Review mappings/*.md files for conversion patterns
3. •Install copybook-to-POJO converters (see Tools section)
4. •Set up local database for testing

Conversion Workflow

Phase 1: Analysis & Planning

1.1 Analyze COBOL Program

# Run analysis script
./scripts/analyze-cobol.sh app/cbl/COSGN00C.cbl

Output includes:

• •Program dependencies (COPY statements, CALL statements)
• •File I/O operations (VSAM, DB2)
• •CICS commands (SEND MAP, RECEIVE, LINK, etc.)
• •Complex data structures (REDEFINES, OCCURS)

1.2 Identify Conversion Pattern

Refer to decision tree:

1.3 Review Pre-Conversion Checklist

• • Business logic documented
• • All dependencies identified
• • Test data prepared
• • Conversion pattern selected
• • Target Java architecture designed

See checklists/pre-conversion.md for complete checklist.

Phase 2: Data Structure Conversion

2.1 Convert Copybooks to POJOs

COBOL Copybook Example:

01  CUSTOMER-RECORD.
    05  CUST-ID           PIC 9(10).
    05  CUST-NAME         PIC X(50).
    05  CUST-BALANCE      PIC S9(13)V99 COMP-3.
    05  CUST-STATUS       PIC X(01).

Java POJO (Converted):

@Entity
@Table(name = "CUSTOMER")
public class Customer {
    @Id
    private Long custId;
    
    @Column(length = 50)
    private String custName;
    
    @Column(precision = 15, scale = 2)
    private BigDecimal custBalance;  // Note: BigDecimal for COMP-3
    
    private String custStatus;
    
    // Getters, setters, constructors
}

⚠️ Critical: Data Type Mappings

See mappings/data-types.md for complete table.

Phase 3: Business Logic Conversion

3.1 CICS Transaction → Spring Boot REST Service

COBOL CICS Program Structure:

IDENTIFICATION DIVISION.
PROGRAM-ID. COSGN00C.
*> Signon transaction

WORKING-STORAGE SECTION.
01  WS-USER-ID     PIC X(08).
01  WS-USER-PWD    PIC X(08).

PROCEDURE DIVISION.
    EXEC CICS RECEIVE MAP('COSGN0A')
              MAPSET('COSGN00')
              INTO(WS-MAP-AREA)
    END-EXEC.
    
    *> Validate user credentials
    PERFORM VALIDATE-USER.
    
    *> Read security file
    EXEC CICS READ FILE('USRSEC')
              RIDFLD(WS-USER-ID)
              INTO(WS-USER-RECORD)
    END-EXEC.

Converted Java Spring Boot:

@RestController
@RequestMapping("/api/auth")
public class AuthenticationController {
    
    @Autowired
    private UserSecurityService userSecurityService;
    
    @PostMapping("/signin")
    public ResponseEntity<SigninResponse> signin(
            @RequestBody @Valid SigninRequest request) {
        
        // Validate user credentials (business logic preserved)
        User user = userSecurityService.validateUser(
            request.getUserId(), 
            request.getPassword()
        );
        
        if (user == null) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body(new SigninResponse("Invalid credentials"));
        }
        
        // Generate token (modern approach vs CICS commarea)
        String token = jwtService.generateToken(user);
        
        return ResponseEntity.ok(
            new SigninResponse(token, user)
        );
    }
}

Key Conversion Patterns:

• •CICS RECEIVE MAP → @PostMapping with @RequestBody
• •CICS SEND MAP → ResponseEntity with JSON
• •CICS FILE READ → JPA repository findById()
• •CICS LINK → Service method call or REST client
• •COMMAREA → DTOs passed between methods

See mappings/cics-to-spring.md for complete patterns.

3.2 Batch Program → Spring Batch

COBOL Batch Structure:

PROGRAM-ID. CBTRN02C.
*> Post daily transactions

PROCEDURE DIVISION.
    OPEN INPUT DALYTRAN-FILE
    OPEN I-O TRANSACT-FILE
    
    PERFORM UNTIL EOF
        READ DALYTRAN-FILE
        PERFORM PROCESS-TRANSACTION
        WRITE TRANSACT-FILE FROM WS-TRANSACTION
    END-PERFORM.

Java Spring Batch:

@Configuration
public class TransactionPostingBatchJob {
    
    @Bean
    public Job postTransactionsJob(JobRepository jobRepository,
                                   Step processTransactionStep) {
        return new JobBuilder("postTransactions", jobRepository)
            .start(processTransactionStep)
            .build();
    }
    
    @Bean
    public Step processTransactionStep(
            JobRepository jobRepository,
            PlatformTransactionManager txManager,
            ItemReader<DailyTransaction> reader,
            ItemProcessor<DailyTransaction, Transaction> processor,
            ItemWriter<Transaction> writer) {
        return new StepBuilder("processTransactionStep", jobRepository)
            .<DailyTransaction, Transaction>chunk(100, txManager)
            .reader(reader)    // Read from staging table
            .processor(processor) // Business logic
            .writer(writer)    // Write to main table
            .build();
    }
}

See examples/batch-conversion-example.md for complete example.

Phase 4: Data Migration

4.1 VSAM to SQL

Refer to mappings/vsam-to-sql.md for:

• •Schema design patterns
• •Index strategies (KSDS primary key → SQL PRIMARY KEY, AIX → SQL INDEX)
• •Data extraction scripts
• •Bulk load strategies

4.2 Data Type Transformations

# Use provided script for data migration
python3 scripts/generate-test-data.py \
  --copybook app/cpy/CUSTOMER.cpy \
  --output test-data.json \
  --records 1000

See checklists/data-migration.md for complete process.

Phase 5: Testing & Validation

5.1 Unit Testing

Create equivalent test cases:

@SpringBootTest
class SigninServiceTest {
    
    @Test
    void testValidCredentials_Success() {
        // Given
        String userId = "USER0001";
        String password = "PASSWORD";
        
        // When
        User user = signinService.authenticate(userId, password);
        
        // Then
        assertNotNull(user);
        assertEquals(userId, user.getUserId());
    }
    
    @Test
    void testInvalidPassword_ThrowsException() {
        // Test invalid credentials
        assertThrows(InvalidCredentialsException.class, () -> {
            signinService.authenticate("USER0001", "WRONG");
        });
    }
}

5.2 Integration Testing

Use TestRestTemplate to test full flow:

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class SigninControllerIntegrationTest {
    
    @Autowired
    private TestRestTemplate restTemplate;
    
    @Test
    void testSigninFlow_EndToEnd() {
        SigninRequest request = new SigninRequest("USER0001", "PASSWORD");
        
        ResponseEntity<SigninResponse> response = restTemplate
            .postForEntity("/api/auth/signin", request, SigninResponse.class);
        
        assertEquals(HttpStatus.OK, response.getStatusCode());
        assertNotNull(response.getBody().getToken());
    }
}

5.3 Data Validation

Compare COBOL output vs Java output using provided scripts.

See checklists/post-conversion-validation.md for complete checklist.

Common Pitfalls & Solutions

1. Numeric Precision Loss

❌ Problem:

double balance = 123.45;  // Can cause rounding errors

✅ Solution:

BigDecimal balance = new BigDecimal("123.45");  // Precise decimal

2. JOBOL Anti-Pattern

❌ Problem: Direct line-by-line translation

// Bad: Procedural COBOL-style Java
public class SignonProgram {
    public void main() {
        receiveMap();
        if (eibaid == DFHENTER) {
            processEnterKey();
        }
    }
}

✅ Solution: Object-oriented Java

@RestController
public class AuthenticationController {
    @PostMapping("/signin")
    public ResponseEntity<SigninResponse> signin(@RequestBody SigninRequest req) {
        // Clean, RESTful design
    }
}

3. Ignoring CICS Transaction Context

⚠️ Remember: CICS is pseudo-conversational. Don't try to maintain server-side state.

✅ Solution: Use JWT tokens or session management

4. EBCDIC Encoding Issues

✅ Solution: Always specify encoding when reading mainframe data:

String data = new String(bytes, Charset.forName("IBM037")); // EBCDIC

See references/common-pitfalls.md for complete list.

AWS Transform Integration

Using AWS Transform for Automated Analysis

# Upload COBOL source to S3
aws s3 cp app/cbl/ s3://my-bucket/cobol-source/ --recursive

# Start AWS Transform project
aws transform create-project \
  --name carddemo-modernization \
  --source-location s3://my-bucket/cobol-source/

# Get analysis results
aws transform get-analysis --project-id <project-id>

AWS Transform provides:

• •Dependency graphs
• •Complexity analysis
• •Automated refactoring suggestions
• •Test case generation

See references/aws-transform-guide.md for setup instructions.

Tools & Resources

Recommended Tools

1. •

   Copybook Converters:

   • •cobol2java-copybook-converter (GitHub: manuelscurti/cobol2java-copybook-converter)
   • •JRecord (GitHub: bmTas/JRecord)
   • •cb2java (Dynamic parser)
2. •

   Testing:

   • •JUnit 5
   • •Spring Test
   • •TestContainers (for database testing)
3. •

   AWS Services:

   • •AWS Transform
   • •AWS Mainframe Modernization
   • •AWS Blu Age

Reference Documentation

• •AWS Mainframe Modernization
• •Spring Boot Documentation
• •Spring Batch
• •COBOL Language Reference (IBM)

Verification Checklist

Before marking conversion complete:

• • All business logic tests pass
• • Performance meets or exceeds COBOL baseline
• • Data integrity validated (checksums, record counts)
• • Error handling implemented
• • Logging added for troubleshooting
• • Security reviewed (authentication, authorization)
• • Documentation updated
• • Code review completed
• • Integration tests pass
• • Deployment tested in staging

Examples

See examples/ directory for:

• •Complete CICS-to-Spring conversion
• •Batch program migration
• •Copybook-to-POJO examples

Iterative Approach

Recommended order for CardDemo conversion:

1. •Phase 1: Data structures (copybooks → POJOs)
2. •Phase 2: Simple CICS transactions (COSGN00C signon)
3. •Phase 3: Complex transactions (account updates, transactions)
4. •Phase 4: Batch programs (statement generation)
5. •Phase 5: Optional modules (DB2, IMS, MQ)

Each phase allows testing and validation before proceeding.

Support & Collaboration

• •Review existing sessions for patterns discovered by team
• •Document new patterns in this skill as they emerge
• •Update mappings when edge cases are found
• •Share learnings via pull requests

Maintenance

This skill should be updated as:

• •New COBOL patterns are discovered
• •Java best practices evolve
• •AWS Transform capabilities expand
• •Team identifies additional pitfalls