Lesson 1 · July 2026 RPG Enhancements

RPG ASSERT-T and ASSERT-F: Defensive Programming on IBM i

Learn how to use RPG ASSERT-T and ASSERT-F to document and check assumptions in your code with short, practical examples.

ASSERT-T and ASSERT-F give RPG developers a clear way to document and check assumptions in code.

RPG continues to evolve, and the new assertion operations are a good example of practical language modernization.

They are not meant to replace normal validation or business error handling.

They are meant to help developers say:

This condition should be true here.

or:

This condition should be false here.

That may sound small, but it can make RPG code easier to understand, easier to test, and safer to change.

What changed?

RPG now includes two assertion operation codes:

ASSERT-T condition %MSG('message');
ASSERT-F condition %MSG('message');

Use ASSERT-T when the condition should be true.

Use ASSERT-F when the condition should be false.

A failed assertion means the program reached a condition that the developer did not expect.

Why should you care?

Assertions make assumptions visible.

Without assertions, assumptions often live only in a developer’s head.

For example:

• Customer number should not be zero.
• Quantity should be greater than zero.
• Divisor should not be zero.
• Array index should be within range.
• Procedure output should be valid before returning.

Assertions let you write those assumptions directly into the code.

Example 1: quantity must be greater than zero

**free
ctl-opt dftactgrp(*no) assert(*excp);

dcl-s qty packed(9:0);

qty = 5;

assert-t qty > 0 %msg('Quantity must be greater than zero');

*inlr = *on;
return;

This says:

At this point in the program, qty > 0 should be true.

If qty is zero or negative, the assertion fails.

Example 2: customer ID must not be zero

**free
ctl-opt dftactgrp(*no) assert(*excp);

dcl-s customerId int(10);

customerId = 0;

assert-f customerId = 0 %msg('Customer ID cannot be zero');

*inlr = *on;
return;

This says:

At this point in the program, customerId = 0 should be false.

I like this example because it shows the difference between ASSERT-T and ASSERT-F.

These two lines express the same idea in different ways:

assert-t customerId <> 0 %msg('Customer ID cannot be zero');

assert-f customerId = 0 %msg('Customer ID cannot be zero');

Use the version that makes the code easiest to read.

Example 3: protect a calculation

A common defensive programming example is preventing divide-by-zero.

**free
ctl-opt dftactgrp(*no) assert(*excp);

dcl-s total packed(11:2);
dcl-s count packed(9:0);
dcl-s average packed(11:2);

total = 1250.00;
count = 0;

assert-f count = 0 %msg('Count cannot be zero before calculating average');

average = total / count;

*inlr = *on;
return;

The assertion documents an assumption before the calculation happens.

The point is not only to catch the issue.

The point is to make the rule clear to the next developer reading the program.

Example 4: checking procedure assumptions

Assertions are useful at the beginning of a procedure to check preconditions.

dcl-proc calculateDiscount;

  dcl-pi *n packed(7:2);
    orderAmount packed(11:2) const;
  end-pi;

  assert-t orderAmount >= 0 %msg('Order amount cannot be negative');

  if orderAmount >= 1000;
    return 10.00;
  endif;

  return 0.00;

end-proc;

This says:

This procedure expects orderAmount to be zero or greater.

That is different from normal business validation.

It is documenting what the procedure expects from its caller.

ASSERT modes

The behavior of assertion statements is controlled by the ASSERT control keyword.

For development, a useful mode is:

ctl-opt assert(*excp);

In this mode, a failed assertion raises an exception.

That is useful during development because the problem is caught immediately.

Other modes can be used depending on how you want assertion failures handled.

The important idea is this:

Decide how assertions should behave before using them widely.

When to use ASSERT-T and ASSERT-F

Use assertions for developer assumptions and internal correctness checks.

Good places include:

• Procedure preconditions
• Procedure postconditions
• Defensive checks before calculations
• Internal state checks
• Conditions that should never happen if the code is correct
• Test-focused development

When not to use assertions

Do not use assertions as a replacement for normal business validation.

For example, these should usually be handled with normal validation and error messages:

• Missing customer number entered by a user
• Invalid order data from an external system
• Business rule failures
• Expected data quality issues
• Recoverable user input problems

Assertions are better for conditions where failure means:

The program logic or assumptions are wrong.

PTF / release note

At the time of writing, IBM’s RPG Cafe lists the PTF information for the July 2026 RPG enhancements and should be checked before using these features in real development or production environments.

Final takeaway

ASSERT-T and ASSERT-F are small additions, but they encourage a better style of RPG programming.

They help you write code that explains its assumptions clearly.

Use them when your RPG program needs to say:

This should always be true here.

or:

This should always be false here.

That is defensive programming.

And it is a good step toward more intentional modern RPG.