RPGLE Control Specifications and Compiler Directives

The first few lines of an RPGLE source member can look like one block of setup, but they do not all serve the same purpose.
The **free line is a compiler directive.
The ctl-opt line is a control-options statement.
They can both appear near the top, yet they tell the compiler different things.

Earlier lessons established the foundation for this topic.
How to Read an RPGLE Program From Top to Bottom gave you a reading order.
RPGLE Naming Conventions and Code Organization showed how clear names improve code.
RPGLE Program Structure Explained explained the main source sections.
This lesson zooms in on the top-of-source controls so you can recognize them without memorizing advanced configuration.

Estimated reading time: 8 to 10 minutes

Quick Summary

• **free is a special compiler directive that identifies fully free-form source.
• Compiler directives guide how the compiler reads or selects source.
• ctl-opt begins a free-form control statement containing program-wide control options.
• Compiler directives and control options are not interchangeable.
• Control options are optional, and programs do not all use the same options.

The beginner mental model starts with two distinct kinds of information in the source:

1. Start with the RPGLE source.
2. Recognize compiler directives associated with source processing.
3. Recognize control options associated with program- or module-level choices.
4. Understand that the compiler processes both according to their different roles.
5. Receive the requested compiled object when compilation succeeds.

Compiler directives guide source processing, while control options supply program- or module-level choices used to create the requested compiled object.

Reader Prerequisites

• You should recognize the major sections of a small RPGLE program.
• You should know that declarations and executable statements have different jobs.
• You do not need to understand activation groups, modules, service programs, or compiler commands.
• You do not need to memorize any list of control options.

Learning Outcomes

By the end of this lesson, you will be able to:

• Recognize **free as a compiler directive.
• Explain that compiler directives affect source processing.
• Recognize ctl-opt as a control-options statement.
• Explain that control options describe program-wide choices.
• Avoid treating **free and ctl-opt as interchangeable.
• Identify advanced options that can safely wait until later.
• Read the top of modern RPGLE source with more confidence.

Why These Top-of-Source Lines Matter

These lines shape how you read everything below them.
If you treat every top line as executable logic, the program will seem harder than it is.

Start by asking two questions:

1. Is this line guiding how the compiler processes source?
2. Is this line declaring a program-wide control choice?

That distinction lets you classify the line before studying its individual keywords.
The rest of the program can then follow in its normal structural order: file declarations, variable declarations, executable logic, and program termination.

Compiler Directives and Control Options Are Different

Compiler directives and control options both participate in compilation, but they operate at different levels.
Directives guide source handling, while control options describe choices for the program or module being compiled.

This table is a recognition guide.
Individual directives and options have their own rules, so do not assume that every item in one column behaves exactly like every other item.

What **free Means

**free is a special directive that tells the compiler the source member uses fully free-form RPG source.^[1]
In this form it appears in column 1 of the first source line, with the rest of that line blank.

**free

For a beginner, the key message is simple: this line establishes the source form.
It is not a ctl-opt keyword, it does not end with a semicolon, and it does not perform business logic.

Do not confuse **free with the older /FREE and /END-FREE directives you may encounter in historical examples.
This lesson uses modern fully free-form source and does not teach the older column-limited pattern.

Other Compiler Directives You May See

You may meet other directives while reading real source:

• /COPY brings source records from another source member or stream file into the compile.^[2]
• /IF, /ELSE, and /ENDIF let the compiler include or exclude source according to compile-time conditions.^[3]
• /EOF tells the compiler to treat the current source file as having reached its end.^[3]

You only need recognition-level knowledge now.
When one of these lines appears, read it as an instruction to the compiler about source handling.
Do not stop to design copybook structures or conditional-compilation strategies during your first pass.

Not every program uses these directives, and not every directive must appear at the beginning of the main source member.
Each directive has placement and syntax rules that belong in a later reference lesson.

What ctl-opt Does

ctl-opt starts a free-form control statement.
It is followed by zero or more control keywords and ends with a semicolon.^[4]
In modern free-form source, RPGLE control specifications use this statement form.

ctl-opt dftactgrp(*no) actgrp(*caller);

The two keywords in this sample are examples of program-wide control choices.
At this stage, read them as setup selected for this compilation; you do not need to learn activation-group behavior.

Control options are optional.
A source member does not need to contain this exact statement, and different programs may choose different options.
Do not assume that every RPGLE source member begins with ctl-opt.

Read a Small RPGLE Example

This is the same subtotal, tax, total, printer-file, and message example used in the preceding lessons:

**free

// Control options
ctl-opt dftactgrp(*no) actgrp(*caller);

// File declaration
dcl-f samplePrint printer(132) extfile('QPRINT');

// Variable declarations
dcl-s subtotal packed(7:2) inz(125.00);
dcl-s taxRate packed(5:4) inz(0.0750);
dcl-s total packed(7:2);
dcl-s message varchar(40);

// Executable logic
total = subtotal + (subtotal * taxRate);
message = 'Total amount: ' + %char(total);
dsply message;

// Program termination
*inlr = *on;
return;

Read only the first two active lines for this lesson.
**free establishes fully free-form source.
The ctl-opt statement supplies program-wide control choices.
The file, variables, calculation, message, and termination statements follow below, but their details are not today’s topic.

Learn Now / Learn Later

Common Beginner Mistakes

• Calling **free a control option.
• Assuming every program needs ctl-opt.
• Treating top-of-source setup as executable business logic.
• Trying to memorize every option before learning its purpose.
• Assuming every compiler directive appears in every source member.
• Expanding /COPY or conditional directives into advanced design topics too early.
• Believing that two nearby lines must belong to the same language construct.

FAQ

What is a compiler directive in RPGLE?

It is an instruction that guides the compiler’s handling of source, such as identifying fully free-form source, including other source, or selecting source records during compilation.

Is **free the same as ctl-opt?

No. **free is a special compiler directive that identifies fully free-form source. ctl-opt begins a control statement containing program-wide options.

Does every RPGLE program need ctl-opt?

No. Control options are optional, and programs can use different combinations according to their requirements.

What does dftactgrp(*no) mean at a beginner level?

For this lesson, treat it as an example of a program-wide control choice. Its activation-group behavior belongs in a later lesson.

What are /COPY and /IF used for?

At recognition level, /COPY includes other source during compilation, while /IF begins a condition that controls which source records the compiler reads.

Should beginners memorize all control options?

No. First learn to recognize ctl-opt, identify its keywords, and look up unfamiliar options when a program uses them.

Can compiler directives appear anywhere in the source?

No. Directives have syntax and placement rules. **free, for example, belongs in column 1 of the first source line. Other directives follow their own documented rules.

What should I study after this lesson?

Continue with RPGLE Input and Output Specifications to learn how later source sections describe input and output work.

Key Takeaways

• **free identifies fully free-form RPGLE source.
• Compiler directives guide how source is processed.
• ctl-opt introduces optional program-wide control choices.
• **free and ctl-opt are different constructs even when they appear close together.
• Recognition and purpose matter more than memorizing advanced keywords.
• The top of a source member becomes easier to read when you classify each line before studying its details.

Continue Your Learning

1. Previous: RPGLE Program Structure Explained
2. Current: RPGLE Control Specifications and Compiler Directives
3. Next: RPGLE Input and Output Specifications
4. Return to: RPGLE for Beginners: A Practical IBM i Learning Path

This lesson follows program structure and prepares you for RPGLE input and output specifications.