RPGLE Input and Output Specifications Explained

Traditional RPGLE input specifications and output specifications can look like mysterious rows of letters and columns when you first meet them.
They become much easier to read once you separate three responsibilities: declaring a file, describing records and fields, and requesting an input or output operation.

This distinction matters most when you maintain older fixed-format or mixed-form RPG applications.
New fully free-form RPGLE normally uses free-form file declarations, external descriptions or explicit data definitions, and calculation statements for the related work.
Traditional I-specifications and O-specifications are therefore recognition knowledge, not the recommended starting style for a new fully free-form program.

This lesson continues from RPGLE Control Specifications and Compiler Directives.
That lesson separated source-processing directives from program-wide control options.
Here, the same reading habit helps you separate record descriptions from executable I/O.

Estimated reading time: 9 to 11 minutes

Quick Summary

• An input specification, often called an I-spec, traditionally describes input records, their fields, and selected RPG handling information.
• An output specification, often called an O-spec, traditionally describes output records, their fields, and conditions associated with producing output.
• I-specifications and O-specifications are fixed-format, position-dependent forms.
• They do not declare the file and they do not perform a READ or WRITE operation.
• Externally described files often make these specifications unnecessary because the compiler retrieves record and field definitions from IBM i.
• Fully free-form RPGLE has no I-specification or O-specification statement forms; it uses other constructs for the same broad responsibilities.

The traditional program-described relationship has two directions:

The diagram is a description model, not a complete runtime model.
The specification explains how data in a record corresponds to fields available to the program.
An executable calculation operation requests the actual read or write.

Reader Prerequisites

• You should recognize the major sections of an RPGLE source member from RPGLE Program Structure Explained.
• You should understand that a file contains records and that a record contains fields.
• You do not need to know DDS, SQL, keyed access, indicators, the RPG program cycle, or printer formatting.
• You do not need to memorize fixed-format column positions.

Learning Outcomes

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

• Explain what traditional input and output specifications describe.
• Distinguish a file declaration from a record description and an I/O operation.
• Recognize I-specifications and O-specifications in older RPG source.
• Distinguish program-described files from externally described files.
• Explain why a modern fully free-form program does not contain traditional I- or O-specification forms.
• Decide which advanced I/O subjects can wait for later.

Build the File, Record, and Field Mental Model

Start with five terms that describe different layers:

1. A program contains declarations and executable logic.
2. A file declaration tells RPG which file the program uses and how it intends to use that file.
3. A file is the resource through which the program receives or sends records.
4. A record format defines the structure and identity of a type of record.
5. A field is one item within that record, such as customer number, customer name, or status.

A record is one instance of a record format.
For example, a customer record could hold the values C00042, Asha Rao, and ACTIVE in three fields.
The record format defines where those values belong and what their attributes are.

Traditional input and output specifications connect record data with fields known to the RPG program.
They are descriptions.
They are not the file object, and they are not executable requests to move data.

Where I-Specifications and O-Specifications Fit

IBM documents the traditional RPG IV main source order as control, file description and definition, input, calculation, and output specifications.1
Each specification type has a distinct purpose, and a type can be absent when the program does not need it.2

That gives you a useful top-to-bottom reading order:

1. Control information establishes program-wide choices.
2. File declarations identify files.
3. Definitions establish program data.
4. Input specifications describe incoming records and fields.
5. Calculations express operations and business logic.
6. Output specifications describe outgoing records and fields.

This is the traditional structural model.
Do not turn it into a rule that every RPG program must contain every section.
A modern fully free-form program can declare files and data and perform program-controlled I/O without any traditional I- or O-specification lines.

What Input Specifications Describe

For a program-described input file, input specifications can describe record types, the fields within a record, field locations, and additional processing information.3
At beginner level, the most important movement is:

File record -> input description -> program fields

When you see an I in the fixed-format specification position, first classify the line as part of an input description.
Then determine whether it identifies a record or describes one of that record’s fields.

The full form can also express record-identifying indicators, control fields, matching information, sequence checking, and field indicators.
Those features belong to later maintenance and RPG-cycle study.
You do not need them to understand the central purpose of an I-specification.

Most importantly, the I-specification does not read the record.
A program-controlled operation such as READ or CHAIN, or the traditional RPG cycle in cycle-driven code, controls when input occurs.8

What Output Specifications Describe

Output specifications describe records and fields for program-described output and can specify when a record is produced.4
The beginner movement is the reverse of input:

Program fields -> output description -> output record

An O-specification may identify an output record and then describe the fields or constants placed in it.
Older source can also contain conditioned output, detail and total output, or exception output.
Recognize those as extensions of the traditional model, but postpone their exact rules.

An O-specification does not replace the file declaration, and it does not mean that every output device is a printer or display.
It describes output associated with a file.
The operation or cycle processing determines when RPG asks data management to produce that output.

Input Specifications Versus Output Specifications

The safest reading question is not “Is this line about a file?”
Ask, “Is this line declaring a file, describing a record, or requesting an operation?”

Program-Described and Externally Described Files

The location of the record definition changes how much RPG source must describe.

Program-described file

With a program-described file, the RPG program takes responsibility for the record or field layout.
Traditional global source can use input or output specifications for that description.
A modern program-controlled design can instead use a data structure as the record area.

Externally described file

With an externally described file, the compiler retrieves record and field definitions from a file description maintained on IBM i.5
The record format and field attributes therefore do not have to be repeated in the RPG source.

For externally described files, input and output specifications are optional.6
They may still appear when older code adds selected RPG-specific functions.
For example, an input specification can rename a field for the program or associate certain RPG information with an external record or field.7

This nuance prevents two common mistakes:

• An externally described record is not an input specification.
• The presence of an external description does not prove that older source has no I- or O-specifications.

How Fully Free-Form RPGLE Handles the Responsibilities

When the first source line is **free, the source is fully free-form.
IBM lists free-form control, file definition, data definition, calculation, and procedure statements, but not free-form I-specification or O-specification statement forms.9

Modern source answers three separate questions:

The free-form dcl-f statement is therefore not a free-form I-specification.
It declares a file.
Likewise, a READ statement is not an input specification.
It requests an operation.

IBM maps data-management actions such as reading, writing, updating, and deleting to RPG I/O operations.10
Their detailed rules are intentionally outside this lesson.

Read a Small Legacy Recognition Example

The following excerpt is maintenance-reading material.
It shows a record-identification line followed by three program-described input field lines.
The fields occupy positions 1 through 10, 11 through 30, and 31 through 35 of the record.

     ICUSTREC
     I                                  1   10  CUSTNO
     I                                 11   30  CUSTNAME
     I                                 31   35  CUSTSTAT

Do not copy this spacing casually.
Fixed-format source is position-dependent, so column placement carries meaning.
For this lesson, read only the responsibilities:

• CUSTREC identifies the input record description.
• CUSTNO, CUSTNAME, and CUSTSTAT are program fields mapped from positions in that record.
• Nothing in this excerpt requests the actual read.

Compare the Modern Responsibility Map

The reusable sample for this lesson expresses the related responsibilities in fully free-form RPGLE:

**free

dcl-f custIn disk(35) usage(*input);
dcl-f custOut disk(35) usage(*output);

dcl-ds customerRecord qualified len(35);
  customerNumber char(10) pos(1);
  customerName char(20) pos(11);
  customerStatus char(5) pos(31);
end-ds;

The file declarations identify the input and output files.
The data structure explicitly defines a 35-character customer record.
Later calculation statements request one read and, when a record was received, one write.

This is not a mechanical conversion of each I-specification line into one free-form line.
It is a comparison of responsibilities.
The complete teaching source is available at content/code/rpgle/article-055/input-output-responsibilities.rpgle.

Learn Now / Learn Later

Common Beginner Mistakes

• Treating file, record format, and record as synonyms. A file can expose record formats, and a record is one instance of a format.
• Calling every file-related line an I-spec or O-spec. Classify declarations, descriptions, and operations separately.
• Calling dcl-f a free-form I-specification. It is a file declaration.
• Assuming an I-specification performs READ. It describes input; an operation or cycle processing controls input.
• Assuming an O-specification always performs WRITE. It describes output and its conditions within the traditional model.
• Expecting every program to contain both forms. Specification types are optional, and fully free-form source uses other constructs.
• Assuming an external description and an I-spec cannot coexist. Older global source can add selected RPG functions to an external description.
• Reading source order as data direction. Input data moves toward program fields even though output specifications appear later in traditional source order.
• Memorizing columns before understanding purpose. First learn what the line describes; learn exact positions when maintenance work requires them.

Glossary

• Input specification (I-specification): A traditional fixed-format RPG specification that describes input records, fields, and selected input handling.
• Output specification (O-specification): A traditional fixed-format RPG specification that describes output records, fields, and selected output conditions.
• File declaration: The source construct that identifies a file and how the program intends to use it.
• File: A resource through which a program receives, sends, or updates records.
• Record: One structured unit of data transferred through a file.
• Record format: The named definition of a record’s fields and attributes.
• Field: One item within a record.
• Program-described file: A file whose record or field layout is described by the program or a program data structure.
• Externally described file: A file whose record and field definitions are retrieved from an external IBM i description.
• External description: Record- and field-level metadata maintained outside the RPG source and used by the compiler.
• Position-dependent: Syntax whose meaning depends on text appearing in prescribed columns.
• Program-controlled I/O: Input or output requested explicitly by calculation operations in the program.
• I/O operation: An executable request to read, write, update, or delete data.

FAQ

What are input specifications in RPGLE?

Traditional RPGLE input specifications describe input records, their fields, and selected information about how RPG uses those records and fields.
They are fixed-format, position-dependent specifications.

What are output specifications in RPGLE?

Traditional output specifications describe output records, their fields, and conditions associated with producing output.
They are also fixed-format and position-dependent.

What is the difference between an input specification and an output specification?

An input specification maps information from an input record toward program fields.
An output specification maps program fields or constants toward an output record.

Does every RPGLE program need input and output specifications?

No.
Traditional specification types are optional, and modern fully free-form programs use other constructs for file declarations, record definitions, and program-controlled I/O.

Can I code I-specifications or O-specifications in fully free-form RPGLE?

No fully free-form I-specification or O-specification statement form exists.
You may encounter the traditional forms in fixed-format or mixed-form source, but a source member beginning with **free uses fully free-form constructs.

Is dcl-f an input specification?

No.
dcl-f is a free-form file declaration.
It identifies a file and its usage; it does not replace an input record description line by line.

Does an input specification read a record?

No.
It describes input records and fields.
An explicit operation or traditional cycle processing controls when input occurs.

Does an output specification write a record?

An output specification describes the output record and can associate conditions with producing it.
Do not confuse that description with a modern program-controlled WRITE operation.

What is the difference between program-described and externally described files?

A program-described file keeps the record or field layout in the RPG program or a program data structure.
For an externally described file, the compiler retrieves that information from an IBM i file description.

Why do modern RPGLE programs often have no I-specifications or O-specifications?

Fully free-form RPGLE separates the work among free-form file declarations, external descriptions or explicit data definitions, and calculation statements.
Traditional I- and O-specification forms are not part of fully free-form syntax.

What should I learn next?

Continue with calculation specifications and logic blocks.
That lesson explains where executable operations and business logic appear and connects older C-specification recognition with modern free-form statement flow.

Key Takeaways

• Traditional I-specifications and O-specifications describe records and fields; they are not file declarations.
• Input moves conceptually from a file record through its description to program fields.
• Output moves from program fields through its description to an output record.
• Specifications describe data correspondence; operations or cycle processing control when I/O occurs.
• External descriptions can supply record and field definitions, making traditional I- and O-specifications optional.
• Fully free-form RPGLE uses free-form declarations, data definitions, and calculation statements instead of traditional I- and O-specification forms.
• Learn the traditional forms for confident maintenance reading, not as the default style for new programs.

Continue Your Learning

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

Calculation specifications are the correct next step in the traditional source sequence.
They also provide the bridge to modern free-form calculation statements, where program-controlled I/O and business logic are expressed.

IBM Evidence Used

This lesson uses IBM’s ILE RPG documentation as its primary evidence:

• The RPG IV specification overview establishes the traditional specification purposes and source order.1
• The input and output reference topics define what those specification types describe.3 4
• IBM’s file-description guidance distinguishes program-described and externally described files.5
• The free-form statement reference establishes the modern statement categories used in fully free-form source.9
• The file-processing and I/O references distinguish descriptions from executable operations.8 10