RPGLE Data Structures Explained

Once you can declare individual variables, the next question is how to describe several values that belong to one logical concept. A customer identifier, a name, and a balance can appear together in an RPGLE data structure, with each value remaining a separately named, typed subfield.

This reference explains RPGLE data structure basics through small modern declarations. You will learn how to read the declaration, access its fields, reuse its shape, and recognize the keywords that change the way it works. The examples use one deliberately simple customer group so that the language mechanics remain visible.

The starting point is RPGLE Variables and Storage Types. Here, the focus moves from standalone values to grouped declarations. Choosing the best business-field boundaries across a larger application is a later design lesson.

Quick Summary

• A data structure, usually shortened to DS, groups named subfields. Its declaration tells you what those subfields are.
• An explicit modern declaration starts with DCL-DS and closes its subfield block with END-DS.1
• QUALIFIED makes access explicit through the owning structure’s name, such as Customer.name.4
• LIKEDS derives a structure definition from another DS. It implies qualified access; it does not mean “copy the current customer.”5
• Nesting adds another level to an access path. A nested DS is automatically qualified and requires a qualified containing structure.3

Use the keyword table when reading unfamiliar declarations, then return to the focused example for the feature you need. Treat the design-choice table as practical guidance, not a compiler requirement.

What a Data Structure Is

Consider three familiar standalone declarations, taken from basic-data-structure.rpgle:

dcl-s customerId char(10);
dcl-s customerName varchar(60);
dcl-s customerStatus char(1);

The repeated customer prefix makes their intended relationship visible to a reader. A structure gives a related set an explicit declaration boundary. Its individual fields are called subfields.2 The examples below use identifier, name, and balance for that group; the standalone status remains a separate value.

That change is useful to understand even before making any design decision. When you encounter Customer.balance, you can look for the declaration of Customer and then locate balance inside it. The code tells you both the immediate field and its containing group.

Do not attach extra promises to the word “structure.” A declaration does not create a database table or save a customer to disk. It also does not turn the group into a class with methods. In this lesson, think in terms of declarations and field access. File operations, procedure interfaces, and persistence each need their own explanation.

For practice, keep the business meaning deliberately modest: the sample contains enough information to recognize a customer-like group, not enough to define a production customer model. Deciding whether balance, status, contact details, and other information should share a boundary belongs to the later field-grouping lesson.

Reader Prerequisites

You should be comfortable reading DCL-S, recognizing an assignment, and distinguishing a variable’s type from its scope and lifetime. Revisit RPGLE Variables and Storage Types if those distinctions are unfamiliar.

You also need the scalar foundation in RPGLE Data Types, Lengths, and Precision. This article uses CHAR, VARCHAR, and PACKED without repeating their complete parameter rules. A subfield does not make careful type selection less important.

No array processing, database access, or procedure-parameter knowledge is assumed. Read the examples as separate small programs; their repeated Customer declarations are alternatives, not blocks to combine into a single source member.

Learning Outcomes

After working through the examples, you should be able to:

1. Mark the beginning and end of an explicit DS declaration.
2. Identify the structure name, keywords, and typed subfields.
3. Follow a qualified reference back to its declaration.
4. Explain what a LIKEDS-based declaration takes from its source.
5. Read a two-level nested field path without treating the inner group as a standalone variable.
6. Recognize when a keyword leads beyond ordinary declaration mechanics.

A useful self-check is to explain an example aloud before running it: which name identifies a structure, which names identify values, and which statements assign those values? That separates declaration reading from assumptions about output.

DCL-DS Anatomy

Here is the central declaration from basic-data-structure.rpgle:

dcl-ds Customer qualified;
   id char(10);
   name varchar(60);
   balance packed(11:2);
end-ds;

Read the first line from left to right: DCL-DS introduces the declaration, Customer names it, and QUALIFIED controls how its subfields are referenced. The following lines declare the subfields. The final END-DS closes this explicit block.1

Each type clause belongs to the subfield on its own line. There is no instruction here that says all customer fields must have the same type. That is why a compact declaration can place character information and a decimal value in one group without obscuring either choice.

As a reading habit, locate the complete boundary before studying an individual line. This is particularly helpful when another DS is nested inside the first. Indentation helps your eye, but the declaration statements establish the boundaries.

Do not turn this block into a rule that every DS declaration has five lines or always needs a separately written terminator. IBM distinguishes structures with explicit subfields from structures defined through LIKEDS or LIKEREC: those derived forms have no separately declared subfields and no END-DS statement.1 The LIKEDS example below shows the difference directly.

Working with Subfields

The basic asset assigns values and then reads two subfields into standalone variables:

Customer.id = 'C000000001';
Customer.name = 'Asha Rao';
Customer.balance = 125.50;
customerId = Customer.id;
customerName = Customer.name;
customerStatus = 'A';
entryId = 'E000000001';

Follow the first assignment by finding id inside the declaration of Customer. Then follow the assignment to customerId: the right side reads that subfield, while the left side names the standalone variable introduced earlier. These are different declarations, even though the example deliberately uses related names.

This is a small reading exercise rather than a recommendation to maintain duplicate representations of customer information. The standalone variables let you see where a value is read from the grouped declaration. The separate entryId comes from the unqualified example in the next section.

IBM permits a free-form subfield declaration to begin with its name or with DCL-SUBF followed by the name. Where a data-type keyword is used, it is the first keyword. Certain names that are also free-form calculation operation codes require DCL-SUBF to remove the ambiguity.3 The ordinary names in our central example do not need that extra operation code.

When a field assignment looks suspicious, inspect the field’s type rather than treating the containing group as a conversion rule. Keep the detailed type reference nearby; the DS declaration is the place where you find the field, not a substitute for understanding its attributes.

QUALIFIED Data Structures

With explicit qualification, IBM requires the DS name, a period, and the subfield name. That is the role of Customer.name in the examples. A qualified structure must be named. Its subfields may use names that are also used elsewhere in the program, because the qualified reference identifies their owner.4

Practical guidance: explicit access is a useful default for these teaching examples. It keeps the connection between declaration and use visible when you read one line in isolation. That preference is not a statement that all RPG structures must be qualified.

The basic asset also includes an ordinary unqualified declaration:

dcl-ds Entry;
   entryId char(10);
end-ds;

Its assignment uses entryId, as shown above. Compare the two access styles while reading the whole declaration, not just the final field name. Existing programs may use either style; understanding the source is more useful than assuming that every declaration follows your preferred convention.

There are also cases where qualification is implicit. A DS declared with LIKEDS is qualified automatically, even if its source DS is unqualified.5 Consequently, absence of the literal word QUALIFIED is not enough to determine access style. Check how the structure was defined.

For a quick maintenance review, write down the exact reference you are investigating, locate its declaration, and note any derivation keyword. This small habit prevents a common mistake: applying the rules of the nearby explicit DS to a derived declaration that behaves differently.

Reusing Layouts with LIKEDS

Once a useful shape exists, another declaration can use it without spelling out the same subfield list again. In likeds-data-structure.rpgle, the same explicit Customer declaration is followed by:

dcl-ds NextCustomer likeds(Customer);

NextCustomer takes its subfield definitions from Customer. There is no new subfield block beneath that line, and no END-DS for it.5 1

The asset assigns ordinary values separately:

Customer.id = 'C000000001';
Customer.name = 'Asha Rao';
Customer.balance = 125.50;
NextCustomer.id = 'C000000002';
NextCustomer.name = 'Mira Shah';
NextCustomer.balance = 80.00;
Customer.name = 'Asha Patel';

The intended observation is that the last statement changes the first customer’s name. There is no assignment there to NextCustomer.name. In a documented IBM i run, inspect both names: the example is intended to leave them as Asha Patel and Mira Shah. These are expected observations, not a claim that the sample was executed in this workspace.

Do not read LIKEDS as “inherit every setting.” IBM documents specific inheritance rules. In particular, the parent’s DS-level DIM and INZ attributes are not automatically inherited; INZ(*LIKEDS) is the mechanism for adopting its specified initializations.5 This example avoids that additional topic by assigning every field it later uses.

Where TEMPLATE fits

Sometimes a source definition exists only to describe other declarations. TEMPLATE makes that intention explicit. IBM explains that a template definition is not an ordinary program variable. It has no associated runtime storage.7 This is a documented property of TEMPLATE. It does not describe the lifetime of every DS.

The IBM i 7.5 rules permit a DS template as the basis of LIKEDS. They also specify the other allowed uses of template names and subfields.6 Do not treat the template itself as a customer value to assign in calculations.

TEMPLATE is not required for the preceding example: its source Customer is intentionally used as ordinary data. If your source is only a reusable definition, consult the TEMPLATE rules and make that role clear. The distinction matters more here than surveying every template-related feature. The reuse diagram therefore uses the ordinary source actually present in the code asset.

Nested / Grouped Structures

The nesting asset introduces just one extra level:

dcl-ds Customer qualified;
   id char(10);
   dcl-ds contact;
      name varchar(60);
      city varchar(30);
   end-ds contact;
end-ds Customer;

The containing DS is qualified; the inner contact structure is automatically qualified. Both declarations use free-form syntax. These requirements come from IBM’s nested-subfield rules, not from indentation or a naming convention.3

Read the access path one level at a time:

Customer.id = 'C000000001';
Customer.contact.name = 'Asha Rao';
Customer.contact.city = 'Pune';

Start at Customer, enter its contact subfield, then select city. Named END-DS statements make the two closing boundaries especially easy to follow here. The earlier flat example shows that the name after END-DS is optional for a named explicit structure.1

As an exercise, locate each assignment’s destination in the declaration before reading the value on the right. This keeps attention on the skill nesting introduces: following a path through declared groups. You do not need an array or a large domain model to practice it.

Whether contact information deserves its own group in a real application is a separate design question. This example assumes that choice has already been made. It demonstrates the mechanics of expressing and accessing the result, leaving larger grouping decisions to ARTICLE-074.

Selected DS Keywords: Reference Table

The table separates ordinary declaration mechanics from recognition-only features. Patterns are fragments, not additional complete programs. Use the cited IBM page for restrictions before extending a fragment.

Read keywords in the context of their declaration. A list of individually valid keywords does not establish that an arbitrary combination is valid. For this reference, use the three small assets as the starting points; consult the specific keyword rules before adding array, external-description, or storage-related features.

Data Structure vs Standalone Variables

Editorial guidance: keep a simple independent value standalone when grouping would add little meaning. Consider a structure when a known set represents one logical concept and naming that concept helps readers follow the code. Neither recommendation is an IBM requirement.

These patterns overlap: a reused layout can also be qualified, and a qualified DS can contain a nested DS.

The access mechanics are supported by IBM’s qualification, LIKEDS, and subfield references.4 5 2 The “best suited for” column is practical advice.

Stop this decision at an introductory level. Comparing candidate business records, restructuring a collection of existing variables, and evaluating cohesion or maintainability across alternative groupings are the purpose of the planned RPGLE Data Structures for Related Fields lesson, ARTICLE-074.

Legacy / Existing-Code Recognition

Traditional definition specifications

Existing members may express structures through fixed-format definition specifications instead of DCL-DS blocks. IBM describes traditional subfields as definitions following the structure definition, with blank definition-type entries; another definition type or specification type ends that subfield sequence.2

For recognition, locate the parent definition, identify its following subfields, and find their uses. Avoid “converting” a sample by simply removing spaces: fixed-format positions carry meaning. This lesson provides no fixed-column conversion recipe or assertion that every old declaration maps mechanically to the central example.

DIM: recognize repeated structures

DIM on a DS indicates an array of structures, with the element count specified by the keyword. IBM requires a qualified DS and qualified subfield access in this case.8 Seeing it should prompt an array-specific reading of the declaration, not a guess that a field’s character length changed.

This is the recognition boundary. Indexing, loops, array operations, and varying dimensions belong to the planned array lessons, ARTICLE-072 and ARTICLE-073. None of the three accompanying examples requires those topics.

OVERLAY and positional subfields

An overlay is different from ordinary layout reuse: it describes overlapping storage. In a free-form definition, OVERLAY positions one subfield within another previously defined subfield. Its target name is unqualified even within a qualified DS. With no explicit starting position, it starts at position one; the overlay must fit inside its target.9

For recognition, a short character subfield using OVERLAY(id) asks you to inspect the earlier id definition and the overlay’s size. Do not read it as another independent customer identifier. POS, by contrast, specifies a starting position within the containing DS.3 Stop and consult the relevant rules before changing either form. Byte-layout calculations, alignment workarounds, and advanced overlay techniques are outside this introduction.

Externally described structures

EXTNAME identifies a file whose field descriptions supply the DS subfields. In free-form source, its file-name argument is a character literal or a suitable named constant.10 That helps explain why a declaration can have fields that are not individually spelled out beneath it.

Read it as a dependency on an external description. Do not assume the declaration alone has retrieved a database row. Checking the external format, understanding I/O usage, and managing database changes require more than this recognition note; they are deliberately excluded from the self-contained examples.

Common Mistakes

Reading only the final name. When investigating a value, keep its entire qualified path in view. Find the owning declaration before changing the field or its access expression.

Adding END-DS after LIKEDS. Compare the short derived declaration with the explicit block. They are different declaration forms, not a long and short way to write the same block.

Expecting values to follow a reused definition. Read the assignment statements in the reuse asset separately from its declarations. A customer’s later name change is not an instruction to update the other customer.

Assuming every setting carries across. Initialization and dimension attributes need attention when extending a LIKEDS example. Do not apply a broad “same as the parent” shortcut to every keyword.

Using the template as working data. A definition intended solely as a template is not where the program should store the next customer’s values. Keep that distinction visible when naming and reviewing declarations.

Using grouping to explain lifetime. The presence of subfields answers a different question from how long data remains available. Return to the variables-and-storage lesson instead of deriving duration from the nesting diagram.

Expanding the first example too far. Add one language feature at a time. An example that simultaneously introduces files, arrays, pointers, and parameters makes a simple access error much harder to isolate.

FAQ

How is DCL-DS different from DCL-S?

Use the first example as the contrast: the DCL-S declarations each name a standalone value; Customer contains named subfields. Choose the declaration that expresses the immediate concept, then check its syntax and access rules.

Must every DS use QUALIFIED?

No. The Entry example is deliberately unqualified. Some other forms impose qualification, including LIKEDS-based structures and DS arrays, so inspect the complete declaration before deciding how to reference a field.4 8

Does LIKEDS copy the current values?

It is a declaration mechanism. In the reuse example, read the separate assignments to Customer and NextCustomer; the two names are used for different customer data. Do not substitute a declaration relationship for a value-assignment operation.

Is TEMPLATE needed to use LIKEDS?

No: the accompanying asset derives NextCustomer from an ordinary Customer DS. TEMPLATE is useful when the source is intended only for definitional uses. IBM’s permitted-use rules govern what you may do with a template.6

How do I read a nested field reference?

Follow the declaration path from the outside inward. In the nested asset, Customer contains contact, and contact contains city. Match each part of the access expression to that declaration before investigating the assigned value.

Can different subfields use different types?

Yes; compare id, name, and balance in the central declaration. The type clauses remain attached to individual subfields. Use the scalar type reference for choosing and interpreting those clauses rather than assuming the group supplies one common type.

When should I learn arrays or external descriptions?

When the code you need to understand depends on them. First become comfortable with these self-contained declarations. DIM and EXTNAME are useful signals that additional declaration rules or dependencies need separate study.

Key Takeaways

• Read the complete declaration before interpreting a subfield reference.
• Keep structure names, subfield names, and type clauses distinct.
• Use the explicit, derived, and nested examples as three focused reading patterns.
• Separate definition reuse from assignment, and template intent from ordinary data.
• Treat optional recognition keywords as prompts to consult their own rules.
• Keep practical grouping advice separate from compiler requirements and detailed business design.

Continue Your Learning

1. Foundation: RPGLE Variables and Storage Types
2. Previous: RPGLE Data Types, Lengths, and Precision
3. Current: RPGLE Data Structures Explained
4. Planned next: RPGLE Constants and Literals (ARTICLE-062)
5. Then planned: RPGLE Passing Data by Value and by Reference (ARTICLE-063)
6. Later design practice: RPGLE Data Structures for Related Fields (ARTICLE-074)
7. Learning-path overview: RPGLE for Beginners: A Practical IBM i Learning Path

Upcoming lessons are named without links because their public destinations have not been established for this draft. ARTICLE-074 retains business-field selection, logical-record modeling, restructuring of standalone variables, and the tradeoffs involved in grouping. This article supplies the declaration mechanics needed before that work.

IBM Evidence Used

The technical references are IBM i 7.4/7.5 documentation, plus IBM’s explanation of TEMPLATE’s purpose. The DS-definition page supports the explicit/derived distinction; the subfield pages support field declarations and nesting; the dedicated keyword pages support the qualification, reuse, array, overlay, and external-description cautions.

The examples and both diagrams are original teaching material checked against those rules. Their code files include the complete local examples. They have not been compiled or run on IBM i here; expected observations require an IBM i verification pass. No physical-layout limit or feature-introduction date is asserted.

The code README records source-access details and the claim map. Several IBM Docs direct fetches returned access errors; extended indexed IBM page bodies supplied the relevant rules and examples, while the IBM Support TEMPLATE page was directly retrieved. No IBM publication dates have been inferred. The choice guidance and reading exercises are editorial recommendations.

References