RPGLE LEAVE, ITER, and Loop Control

LEAVE and ITER answer two different questions inside an RPGLE loop. LEAVE says, “this loop is finished now.” ITER says, “this pass is finished; apply the loop’s normal continuation logic.” The distinction is small in syntax and large in effect: one transfers control beyond the loop, while the other transfers control to its ENDDO continuation point.12

This reference concentrates on those control transfers. It does not re-teach how counted DO, post-test DOU, or pre-test DOW groups establish repetition.

Use the opening table when you only need the answer, then jump to the matching statement section for syntax, a trace, and failure modes. The examples stay deliberately small: one search exits early, one counted loop skips selected positions, and one condition-controlled loop puts both operations side by side. Readability recommendations are labeled separately from IBM-defined behavior.

Quick Reference

Two rules prevent most mistakes:

1. Choose LEAVE when no later iteration is wanted.
2. Choose ITER when only the rest of the current pass should be skipped.

In nested loops, both operations apply to the innermost loop that contains them.12 They are not procedure exits: LEAVE does not behave like RETURN, and ITER does not restart the procedure.

Where LEAVE and ITER Fit

The loop operation and the loop-control operation have separate jobs. A DO, DOU, or DOW group establishes repetition and defines its ordinary continuation rule. LEAVE and ITER can alter the path while the body is running:

• LEAVE bypasses the remainder of the current body and the loop’s later passes.
• ITER bypasses only the remainder of the current body, then transfers control to ENDDO so the loop continues in its normal way.12

That final qualification matters. ITER does not promise that the body will execute again. At the continuation point, a counted loop can reach its limit, a DOW condition can be false, or a DOU condition can be true. In any of those cases, normal loop behavior ends the group instead of starting another body pass.

The RPGLE DOW Loops Explained reference provides the pre-test condition model used by two examples below. This article changes flow inside that model; it does not change when DOW evaluates its condition.

LEAVE

LEAVE purpose and syntax

LEAVE immediately transfers control out of the innermost loop containing it. Processing resumes with the first statement following that loop’s ENDDO.1

if targetFound;
  leave;
endif;

The surrounding IF supplies the reason for the exit. LEAVE itself has no condition operand in this fully free-form example.

Stop when a target is found

leave-when-target-found.rpgle searches a deliberately small numeric range so the control behavior remains visible:

dow candidateNumber <= finalCandidate;
  if candidateNumber = targetNumber;
    targetFound = *on;
    leave;
  endif;

  candidateNumber += 1;
enddo;

dsply ('Target found: ' + %char(targetFound));

When candidateNumber reaches the target, LEAVE skips the increment below it, ends the DOW group, and transfers control to the DSPLY after ENDDO. No later candidate is examined.

Use this shape when finding the target fully satisfies the loop’s purpose. If later iterations still have useful work, exiting would be the wrong choice.

LEAVE readability check

The semantics are simple, but placement can make them hard to see. A LEAVE near the top of a short loop, immediately under a named condition, makes the early-exit reason obvious. Several exits scattered through a long body force the reader to hunt for every path that can terminate the loop. That is maintainability guidance, not an RPG requirement.

ITER

ITER purpose and syntax

ITER transfers control from its position in the loop body to the ENDDO of the innermost containing loop. Statements between ITER and that ENDDO are not executed during the current iteration.2

if skipCurrentItem;
  iter;
endif;

At ENDDO, the loop performs its normal continuation behavior. This is why “skip the rest of this pass” is more exact than “jump to the next pass.”

Skip the current item

iter-skip-current-item.rpgle uses a counted loop and treats positions 2 and 5 as irrelevant:

do 1 to 6 itemNumber;
  if itemNumber = 2 or itemNumber = 5;
    iter;
  endif;

  processedCount += 1;
  dsply ('Processed item ' + %char(itemNumber));
enddo;

On positions 2 and 5, ITER prevents the count increment and display below it. The DO group still applies its own end-of-iteration behavior, so processing can continue with the next position until the counted range is complete.

The intended final processedCount is 4. That value is a trace derived from the initialized data and IBM-documented flow, not captured IBM i runtime output.

ITER state-update hazard

In a condition-controlled loop, an ITER can skip a statement that the loop needs in order to make progress. Consider a DOW driven by workItemNumber. If ITER occurs before that number advances, the same item can be tested repeatedly forever. Update the state needed for the next continuation decision before executing ITER, or restructure the body so progress cannot be bypassed.

This is a practical consequence of documented ITER transfer, not a special compiler restriction. RPG transfers control exactly as requested; the program author remains responsible for state that allows the loop to finish.

LEAVE vs ITER

leave-vs-iter-control-flow.rpgle puts both decisions in one DOW body. Item 2 is skipped after advancing the loop state; item 5 ends the loop. Items 1, 3, and 4 reach the processing statement.

The sequence is worth tracing:

1. A skip condition means “not this item,” so advance the condition state and use ITER.
2. A stop condition means “no more items,” so use LEAVE.
3. Otherwise perform the ordinary work and advance normally.

This ordering makes the two decisions mutually understandable without turning the middle of the loop into a maze.

Practical Loop-Control Patterns

Stop after success

Use LEAVE after a search or attempt has completely achieved the loop’s purpose. Set any result state the code after the loop needs before leaving. A named result such as targetFound lets later code distinguish success from ordinary exhaustion.

Skip invalid or irrelevant work

Use ITER when the current item should not reach the main processing block but later items remain meaningful. Put the rejection test early, then keep the valid-item path unindented below it. This guard-style iteration can reduce nesting:

if itemIsNotRelevant;
  iter;
endif;

// Main work for a relevant item

The shape is readability guidance. The language guarantee is only the transfer to ENDDO.2

Keep state changes visible

Before either operation, ask which values code after the transfer expects. Before LEAVE, preserve the result or reason for exit. Before ITER, perform any state update that must happen on every pass. Do not rely on a statement below the transfer; by definition, that statement will not run on that path.

Common Mistakes

Using LEAVE when only one item is unwanted. The entire innermost loop ends, so all later items are lost. Use ITER when later passes are still useful.

Using ITER when the task is complete. The loop reaches its continuation point and might start another pass. Use LEAVE when the loop has no remaining purpose.

Describing ITER as an unconditional next pass. It first transfers to ENDDO. The loop’s normal condition or range still determines whether another pass begins.2

Skipping the progress update. An early ITER in a condition-controlled loop can bypass the state change needed to terminate. Trace every ITER path separately.

Putting essential work after a transfer. Statements below an executed LEAVE or ITER are skipped. Move required state changes before the operation or redesign the flow.

Forgetting nested-loop scope. Both statements act on the innermost containing loop.12 They do not automatically exit or advance an outer loop.

Adding too many control jumps. A loop with many LEAVE and ITER sites may be technically valid but expensive to reason about. Consolidate related checks when doing so makes the path clearer.

Readability Guidance

The following recommendations are maintainability guidance, not language semantics:

• Keep the condition immediately above its LEAVE or ITER when practical.
• Use names that explain the reason, such as targetFound or skipCurrentItem.
• Reserve LEAVE for a condition that genuinely completes the loop’s purpose.
• Place early ITER guards before the main work so the ordinary path remains visually straight.
• In a condition-controlled loop, audit every ITER path for guaranteed progress.
• When loops are nested, consider whether a small procedure would express a multi-level outcome more clearly than several inner-loop transfers.

Key Takeaways

• LEAVE ends the innermost containing loop and resumes after its ENDDO.
• ITER skips the rest of the current body and transfers control to that loop’s ENDDO.
• ITER does not guarantee another body pass; the loop’s normal continuation rule still applies.
• Preserve required result state before LEAVE, and preserve required progress state before ITER.
• Treat clear naming, early guard placement, and a limited number of transfer sites as maintainability guidance rather than compiler rules.

Related Learning Path

1. Pillar: RPGLE for Beginners: A Practical IBM i Learning Path (ARTICLE-046)
2. Counted repetition: RPGLE DO Loops Explained (ARTICLE-068)
3. Post-test repetition: RPGLE DOU Loops Explained (ARTICLE-069)
4. Pre-test repetition: RPGLE DOW Loops Explained (ARTICLE-070)
5. Current reference: RPGLE LEAVE, ITER, and Loop Control (ARTICLE-071)
6. Recommended next: RPGLE Arrays and Tables (ARTICLE-072)

ARTICLE-072 is named from the canonical registry but remains unlinked until a publishable repository route exists.

IBM Evidence Used

IBM i 7.5 documentation for LEAVE is the authority for immediate transfer to the statement following the ENDDO of the innermost containing loop.1 The IBM i 7.5 ITER reference supports transfer to that loop’s ENDDO, which skips the remaining body statements while leaving ordinary continuation behavior in control.2

The corresponding IBM i 7.4 topics were selected as compatibility cross-checks.34 Direct retrieval of all four IBM Docs routes returned HTTP 403 in this workspace on 2026-09-15. The URLs and narrow operation semantics follow the repository’s established IBM-reference pattern and require fresh origin confirmation during human technical review. No IBM Docs publication dates are claimed.

Examples and traces are documentation-reviewed; not compiled or run on IBM i in this workspace. Recommendations about naming, guard-style iteration, placement, and limiting control transfers are editorial guidance rather than IBM language rules.

References