The daily edition.

Scope and Architectural Overview

This article covers copybook search order, filename extension matching, and compilation optimization in Rocket Enterprise Developer / Enterprise Server 12.0 for Linux/UNIX.

In enterprise COBOL codebases—especially those migrated from IBM mainframe z/OS environments—programs rarely hardcode explicit file extensions or directory paths in their COPY statements (e.g., coding COPY CUSTREC. rather than COPY "/path/to/CUSTREC.CPY."). During compilation, the Rocket COBOL compiler must dynamically locate and expand each referenced copybook.

This resolution mechanism is governed by two complementary components: the directory traversal sequence described in Copybook search order and the extension candidate list configured via the COPYEXT directive.

Directory Resolution Precedence and COBCPY

When a COPY statement specifies an unqualified filename lacking a path, the compiler traverses candidate directories in a strict four-stage order:

1. COPY library-name Directory: If the COPY statement includes a library-name phrase (or specifies a qualified path), only that directory is searched.
2. Main Source Directory: The directory containing the top-level COBOL source file currently being compiled.
3. IDE Project Dependency Paths: Any project build paths or referenced copybook projects configured in Eclipse project properties under Build Path > Dependency Paths.
4. The COBCPY Environment Variable: The directories enumerated in the COBCPY environment variable, evaluated in the exact order listed.

As documented in UNIX Environment Variables, multiple paths in COBCPY are delimited by colons (:). A null path entry (such as a leading colon, trailing colon, or consecutive colons ::) represents the current working directory:

export COBCPY="/home/team/sharedcpy:.:/opt/app/common/cpy"

In this example, the compiler checks /home/team/sharedcpy, then the current directory (.), and finally /opt/app/common/cpy.

Extension Resolution Mechanics with COPYEXT

At each directory evaluated during the search, the compiler tests candidate file extensions defined by the COPYEXT compiler directive.

Syntax:

COPYEXT"extension[,extension...]"

Key operational rules include:

• Default Behavior: The default configuration is COPYEXT",cbl,cpy". A leading comma denotes a null extension (an extension of spaces), causing the compiler to look first for a file with no extension, followed by .cbl, and then .cpy. (Note that DIALECT"RM" alters this default to COPYEXT",cbl,CBL").
• List Limits: Up to 25 extensions can be specified, with each extension being up to 10 characters long.
• Null Extension Positioning: Null extensions can appear anywhere in the list. For example, COPYEXT"cpy,cbl,cob,abc," checks .cpy, .cbl, .cob, and .abc before checking for an extensionless file.
• Sequential Evaluation: For each directory, the compiler checks the extensions in turn. If a matching file is found, it is opened and expanded; if no match is found across all extensions, the compiler advances to the next directory in the search sequence.

Linux/UNIX Case Sensitivity and Mainframe Migration

On Linux/UNIX environments, filesystem lookups are strictly case-sensitive. On mainframe PDS libraries, member names and datasets are case-insensitive uppercase, and migrated repositories often store copybooks with uppercase extensions (.CPY or .CBL) or mixed-case filenames.

If COPYEXT is left at its default lowercase setting (",cbl,cpy"), the compiler will fail to find CUSTREC.CPY, generating syntax errors despite the copybook residing in the specified directory. When migrating mainframe workloads to Linux/UNIX, COPYEXT must explicitly list uppercase extensions alongside lowercase variants:

cob -C "COPYEXT',CPY,cpy,CBL,cbl'" myprogram.cbl

Accelerating Builds with LIMITED-SEARCH

In large enterprise repositories containing thousands of source modules and deep copybook trees, evaluating up to 25 extensions across 10+ directories produces massive filesystem stat overhead, drastically slowing compilation and CI pipeline throughput.

Two optimizations dramatically reduce this overhead:

1. Pruning COPYEXT: If an organization standardizes all copybooks on .cpy, setting COPYEXT"cpy" restricts the search to a single file check per directory, avoiding wasted lookups for .cbl or extensionless files.
2. The LIMITED-SEARCH Directive: As documented in LIMITED-SEARCH, LS, setting LIMITED-SEARCH (or LS) limits copybook searches strictly to the directories defined in COBCPY, omitting the directory where the source program is located. Furthermore, the extension specified by OSEXT is excluded from the copybook search (preserving only COPYEXT values).

By combining LIMITED-SEARCH with a tuned COBCPY and a concise COPYEXT list, large batch compilation suites avoid thousands of redundant directory scans.

Documentation Takeaway

In Rocket Enterprise Developer 12.0 for Linux/UNIX, copybooks without explicit extensions or paths follow a four-tier directory search (library-name, source directory, IDE dependency paths, and COBCPY) evaluated against up to 25 extensions in COPYEXT; on Linux/UNIX, uppercase extensions must be explicitly included to account for filesystem case sensitivity, and compilation throughput can be substantially improved by pruning COPYEXT and activating LIMITED-SEARCH.