RPGLE Opcode Reference

An opcode, or operation code, is the word that names what an RPG statement does, such as CHAIN, IF or EVAL. This page is an index: find the operation by task, see how it is written in free-form RPGLE, and see which fixed-format opcodes it replaced when you meet them in older code.

It does not teach file input and output or program logic. For the syntax and behaviour of if, select, the loops, leave, iter, return and monitor, see the RPGLE Control-Flow Opcodes Reference. For how calculation specifications and logic blocks work, read RPGLE Calculation Specs and Logic Blocks. If you are new to the language, start with RPGLE for Beginners. For functions that start with a percent sign, use the RPGLE Built-in Functions Reference.

How to read this page

Free-form statements end with a semicolon. A free-form operation is written as the opcode name followed by its operands, with no column rules. Where an operation has an extender such as (e) for error handling, it is written in parentheses after the opcode.

Assignment and arithmetic

Control flow

dcl-s i int(10);
dcl-s sum int(10);

for i = 1 to 5;
  sum += i;
endfor;                       // sum is 15

File input and output

After an I/O operation, test the result with %found or %eof instead of a result indicator. The operations that can fail on a missing record accept the (e) extender, then you test %error. The RPGLE File I/O Opcodes Reference gives the syntax of each file operation, and the RPGLE File and Error BIFs Reference explains what %found, %eof and %error report. Positioning, reading and changing records have their own pages: the RPGLE SETLL and SETGT Opcode Reference, the RPGLE READ, READE and READP Opcode Reference and the RPGLE UPDATE, WRITE and DELETE Opcode Reference. File behaviour is covered by lessons in the RPGLE series, not here.

Calls and procedures

Strings, dates and arrays

Many string, date and array opcodes were replaced by built-in functions.

Details are in the RPGLE String BIFs Reference and the RPGLE Date and Time BIFs Reference.

Operation extenders

An extender in parentheses after the opcode changes how the operation behaves. The most common ones are below.

chain(e) custKey custFile;
if %error();
  // the read failed for a reason other than "not found"
elseif not %found(custFile);
  // no record with that key
endif;

Choosing between DOW and DOU

dow tests before the first pass, so the loop body may never run. dou tests after each pass, so the body always runs at least once.

dcl-s attempts int(10) inz(0);
dcl-s ok ind inz(*off);

dou ok or attempts >= 3;
  attempts += 1;
  ok = tryOnce();          // tryOnce is a procedure that returns an indicator
enddo;

Output and diagnostics

Choosing a file-read opcode

The file operations look alike but answer different questions. Pick by what you know about the record you want.

• Use chain when you have a full key and want one record. It positions and reads in one step, and %found tells you whether the record exists. The RPGLE CHAIN Opcode Reference covers its key forms and locks.
• Use setll then reade when you want every record that has a given key. setll positions the file at the first record with that key, and reade reads the next record only while the key still matches.
• Use read to process a file from the current position to the end, testing %eof after each read.
• Use setgt when you want to start after the last record for a key, for example to find the next key value.

setll custKey orderFile;
reade custKey orderFile;
dow not %eof(orderFile);
  // process one order for this customer
  reade custKey orderFile;
enddo;

This pattern reads each record once and ends cleanly when the key changes or the file ends. Lessons in the RPGLE series cover file behaviour in more depth.

How free-form statements differ

In fixed format, an operation is placed in fixed columns: the opcode in one column range, the operands in others, and a result field and indicators in more. In free-form, an operation reads like a sentence: the opcode, then its operands, then a semicolon.

Three practical differences matter when you convert code. First, many opcodes disappear because an expression does the same job, so ADD, SUB, MULT and DIV become +, -, * and /. Second, result indicators give way to functions such as %found, %eof and %error, which say what happened by name. Third, a few opcodes keep their names and only change layout, such as CHAIN, READ, WRITE and SETLL.

When you read old code, translate it one operation at a time and keep the logic the same. The Fixed-Format to Free-Format Opcode Mapping shows each fixed-format line next to its free-form replacement. Do not combine operations while converting. Combine them afterwards, once the program passes its tests.

Common mistakes

• Converting MOVEL to = without checking field lengths.
• Using a result indicator when %found, %eof or %error would say what happened.
• Choosing DOW when the loop must run at least once. Use DOU.
• Looking for a function with a percent sign in this table. Those are in the BIF references.

FAQ

What is an opcode in RPGLE?

The keyword that names an operation, such as CHAIN, IF or EVAL. In fixed format it sits in a fixed column. In free format it is the first word of the statement.

Do the old fixed-format opcodes still work?

Yes. They still compile. In free-form code, use the expression or BIF form instead.

Which opcodes should I stop using?

MOVE, MOVEL, Z-ADD, Z-SUB and the arithmetic opcodes have clearer free-form forms. Replace them when you change the code around them.

Summary

• Learn how calculation specifications and logic blocks fit together in RPGLE Calculation Specs and Logic Blocks.
• Use the RPGLE Built-in Functions Reference for the functions that replaced many opcodes.
• Read RPGLE Fixed, Free and Fully Free Specifications to see why free-form is the default for new code.