IBM RPG and Java: Data Type Comparison – Precise Mappings, Real Migration Risks and Best Practices for IBM i

1. Summary: The Critical Difference

RPG data types are deeply tied to classical business data processing, Db2 for i, externally described files, DDS, and fixed field definitions.
Java data types live in an object-oriented, JVM-based world. There we distinguish between primitive types such as int, long, or double and object types such as String, BigDecimal, LocalDate, Instant, or custom records.

The highest-risk mistakes in real projects fall into four classic categories: mapping Packed Decimal to double, adopting timestamps without timezone awareness, discovering CCSID conversion issues only in production, and stripping leading zeros from alphanumeric IDs.
Every one of these errors is technically trivial to explain — and extremely expensive in practice.

2. Why Data Types Matter So Much on IBM i

On IBM i, data types rarely live only in local variables. They are part of physical files, SQL tables, DDS descriptions, externally described data structures, RPG programs, CL flows, SQL procedures, and interfaces.
A field is never just “a number” — it might be inventory quantity, a customer key, a monetary amount, or a historic alphanumeric field whose leading zeros have been part of business processes for years.

When you put Java services in front of existing IBM i data, you must separate two perspectives: what is technically possible and what is semantically correct.
Technically you can read a numeric key as a long. Semantically that can still be dangerous if the same key appears in documents, EDI messages, or external APIs with leading zeros preserved.

3. RPG and Java Side-by-Side

The following comparison table is deliberately practical. It does not show absolute memory truth for Java objects. Instead it answers the more important question:
Which Java type best preserves the business meaning of the RPG field?

4. Numbers: Integer, Packed, Zoned, Float

With numeric fields the first question must always be: what kind of number are we dealing with — an exact decimal value, a technical integer, a business key, or an approximation?
This distinction matters more than raw field length.

Integer: Technical Whole Numbers

RPG offers integer variants of different sizes. Java provides the primitive types byte, short, int, and long.
In modern Java business logic, int is commonly used for ordinary counters and long for large values.

Float and Double: Technically Possible, Often Semantically Risky

Floating-point numbers are fast and appropriate for measurements, simulations, or technical approximations. For monetary and commercial values they are usually the wrong choice.

double sum = 0.1 + 0.2;
System.out.println(sum); // usually not exactly 0.3

BigDecimal price = new BigDecimal("0.10");
BigDecimal tax   = new BigDecimal("0.20");
System.out.println(price.add(tax)); // exactly 0.30

5. Packed Decimal and BigDecimal

Packed Decimal is a very common choice in RPG for monetary and commercial values. Java has no primitive equivalent.
The primary counterpart is java.math.BigDecimal.

**free

dcl-s price packed(9:2) inz(1299.95);
dcl-s quantity packed(5:0) inz(3);
dcl-s total packed(11:2);

total = price * quantity;

import java.math.BigDecimal;
import java.math.RoundingMode;

BigDecimal price = new BigDecimal("1299.95");
BigDecimal quantity = new BigDecimal("3");

BigDecimal total = price.multiply(quantity)
                        .setScale(2, RoundingMode.HALF_UP);

The tests below are intentionally small. They are meant to validate typical migration assumptions around scale, leading zeros, time semantics, and Unicode behavior — not to cover an entire domain model.

import static org.junit.jupiter.api.Assertions.assertEquals;
import java.math.BigDecimal;
import org.junit.jupiter.api.Test;

class DecimalMappingTest {

    @Test
    void keepsScaleForPackedAmount() {
        BigDecimal amount = new BigDecimal("9999999.99").setScale(2);

        assertEquals(new BigDecimal("9999999.99"), amount);
        assertEquals(2, amount.scale());
    }
}

6. Date, Time, and Timestamps

RPG has dedicated data types for date, time, and timestamp. Since Java 8 the java.time package provides a modern, rich API.
The key point: LocalDate, LocalTime, LocalDateTime, Instant, and OffsetDateTime answer different questions.

import java.time.Instant;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.OffsetDateTime;

LocalDate invoiceDate = LocalDate.of(2026, 6, 9);
LocalDateTime localBookingTime = LocalDateTime.of(2026, 6, 9, 14, 30);
Instant technicalEventTime = Instant.now();
OffsetDateTime apiTimestamp = OffsetDateTime.now();

import static org.junit.jupiter.api.Assertions.assertEquals;
import java.time.Instant;
import java.time.OffsetDateTime;
import org.junit.jupiter.api.Test;

class TimestampMappingTest {

    @Test
    void apiTimestampKeepsOffsetInformation() {
        OffsetDateTime value = OffsetDateTime.parse("2026-06-09T14:30:00+02:00");
        Instant instant = value.toInstant();

        assertEquals("2026-06-09T12:30:00Z", instant.toString());
    }
}

7. Text, String, Unicode, and CCSID

Text is often more dangerous than numbers in integration projects. RPG and Db2 for i fields can use different CCSIDs, fixed or variable length, padding, and historical EBCDIC contexts.
Java treats String as a Unicode-oriented object type.

String text = "tiny-tool.de 🚀";

int utf16Units = text.length();
int codePoints = text.codePointCount(0, text.length());

System.out.println("UTF-16 code units: " + utf16Units);
System.out.println("Unicode code points: " + codePoints);

import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;

class CustomerNumberTest {

    @Test
    void keepsLeadingZeros() {
        CustomerNumber number = new CustomerNumber("000123");

        assertEquals("000123", number.value());
    }
}

8. Binary Data, Pointers, and References

Binary data should be treated as binary data in Java: byte[], ByteBuffer, InputStream, or appropriate streaming types depending on the framework.
The classic mistake is accidentally sending binary data through a text conversion.

Pointers are a different story. RPG can work with pointers; Java abstracts memory access through references and object models.
A direct mechanical translation is rarely a good goal.

9. Common Migration Pitfalls

The following mistakes appear especially often in RPG-to-Java projects. They typically occur when teams try to “just quickly pass a field through.”

10. Value Objects and Domain Modeling

Java modernization is not only about type mapping. It is also an opportunity to make business rules visible in code.
An amount is not just any BigDecimal. A customer number is not just a String.
Small Value Objects prevent the same validation logic from appearing in ten places — or missing from nine of them.

import java.math.BigDecimal;
import java.math.RoundingMode;

public record Money(BigDecimal amount) {

    public Money {
        if (amount == null) {
            throw new IllegalArgumentException("amount must not be null");
        }
        amount = amount.setScale(2, RoundingMode.HALF_UP);
    }

    public Money add(Money other) {
        return new Money(this.amount.add(other.amount));
    }
}

public record CustomerNumber(String value) {

    public CustomerNumber {
        if (value == null || !value.matches("\\d{6}")) {
            throw new IllegalArgumentException("customer number must have exactly 6 digits");
        }
    }
}

public enum OrderStatus {
    OPEN,
    RELEASED,
    SHIPPED,
    CANCELLED
}

11. Best Practices and Test Ideas

• Clarify business meaning first: Price, quantity, key, status, date, and text are different things — even when they look technically similar.
• Handle decimal values consistently: Prefer BigDecimal for money, prices, and commercial values in Java.
• Document scale explicitly: In packed(9:2) the :2 is business-critical, not decoration.
• Model date and time cleanly: LocalDate for dates, Instant for technical instants, OffsetDateTime for API timestamps that include offset.
• Test CCSID and Unicode thoroughly: Not only with ABC123, but with ÄÖÜ, ß, accents, special characters, and real production examples.
• Do not blindly numericize IDs: When leading zeros, check digits, or external display matter, String or a Value Object is usually the correct choice.
• Avoid primitive obsession: Important business values deserve their own types or records.
• Centralize mapping logic: RPG/Db2-to-Java conversions should not be scattered across controllers, services, and SQL helper classes.
• Build tests with boundary data: Test maximum packed values, negative amounts, 0.00, 0.10, leading zeros, blank-padded text, umlauts, special characters, old status values, invalid data, and timestamps around DST transitions.

import static org.junit.jupiter.api.Assertions.assertEquals;
import java.math.BigDecimal;
import org.junit.jupiter.api.Test;

class MoneyTest {

    @Test
    void normalizesScaleToTwoDecimals() {
        Money money = new Money(new BigDecimal("12.3"));

        assertEquals(new BigDecimal("12.30"), money.amount());
    }

    @Test
    void addsAmountsWithStableScale() {
        Money result = new Money(new BigDecimal("0.10"))
                .add(new Money(new BigDecimal("0.20")));

        assertEquals(new BigDecimal("0.30"), result.amount());
        assertEquals(2, result.amount().scale());
    }
}

Conclusion