2026-07: Assertion operations

Content

2026-07: Assertion operations

• Control keyword ASSERT
• Assertion operations ASSERT-F and ASSERT-T
• %MSG can have only one "message-string" parameter when used with an assertion operation

The assertion operations can be used for assertion-based coding. For example, using the assertion statements to ensure that preconditions and postconditions are correct for your procedures. https://en.wikipedia.org/wiki/Assertion_(software_development)

They can also be used for unit testing. https://en.wikipedia.org/wiki/Unit_testing

Details

Assertion modes

There are several modes that control how your assertion operations are handled.

• For assertion-based coding, you use the *EXCP, *WARN, and *NONE modes to control what happens if an assertion fails.
• For unit testing, use use the *CALL mode, where a procedure is called for every assertion operation, with a parameter indicating whether the assertion passed or failed.

Control keyword ASSERT controls the mode for your assertion operations.

• ASSERT(*EXCP): This is the default. If an assertion fails, an exception message is issued to the current procedure

  This is useful during development. It also may be useful in production.

• ASSERT(*WARN): If an assertion fails, a diagnostic message is issued to the current procedure if an assertion fails unless they have the A extender indicating that an exception message should be issued.

  If you don't want your application to fail immediately during production when your code discovers an error, it is useful to have something in the joblog to help with problem determination.

• ASSERT(*NONE): The assertion operations are ignored by the compiler unless they have the A extender indicating they should always cause an exception if the assertion fails.

  You might use this option in production if the messages associated with your assertion operations have internal information that your customers should not see in the joblog.

• ASSERT(*CALL:prototype-name): The program or procedure identified by the prototype-name is called for every assertion operation indicating whether the assertion passed or failed.

  This mode might be useful in a unit test environment where the purpose of the assertion is to check the result of the test.

  The prototype must have between 2 and 4 parameters:

  • Required: Indicator: *ON if the assertion was successful and *OFF if the assertion failed.
  • Required: String. This is the %MSG value for the assertion statement.
  • Optional: UTF-8 string. This is the procedure containing the assertion statement.
  • Optional: 4 or 8 byte unsigned integer. This is the statement number of the assertion statement. (The generated statement number, not the statement number in the source.)

   

Assertion operations

The assertion operations are ASSERT-F and ASSERT-T.

The operands are the condition followed by an optional %MSG.

• ASSERT-F asserts that the condition is false 

  pEnvvar = getenv ('SOME_ENVVAR');
  assert-f pEnvvar = *NULL %msg('SOME_ENVVAR should be set');
  

• ASSERT-T asserts that the condition is true 

  dcl-proc add_employee;
     dcl-pi *n;
        name varchar(50) const;
        type like(EMPLOYEE_TYPES) const;
     end-pi;
  
     // Check the input parameters
     assert-t name <> *blanks %msg('Name cannot be blank');
     assert-t type in EMPLOYEE_TYPES %msg('Invalid type: ' + %char(type));
     ...
  

   

%MSG for assertion operations

For an assertion operation, you can code %MSG with 2 or 3 parameters to send a message ID in a message file, or you can code %MSG with a single "message-string" parameter to send RPG runtime message RNX0461.

The single-parameter form is required if ASSERT(*CALL) is in effect.

Example of ASSERT(*CALL) showing a sample procedure to handle the assertions.

ctl-opt assert(*call : assertFn);
dcl-s num_asserts int(10);
dcl-s num_passed_asserts int(10);

test_format_date ();
return;

dcl-proc test_format_date;
   dcl-s string varchar(100);

   string = format_date (D'2001-02-03' : 'MDYY-');
   assert-t string = '01-02-2001' %MSG(string);

   string = format_date (D'2001-02-03' : 'Words');
   assert-t string = '3 Feb 2001' %MSG (string);
end-proc test_format_date;

dcl-proc assertFn;
   dcl-pi *n;
      ok ind const;
      msg varucs2(1000) const;
   end-pi;

   num_asserts += 1;
   if ok;
      num_passed_asserts += 1;
   else;
      snd-msg *diag 'Assertion failed: ' + msg
              %target(*caller);
   endif;
end-proc;