Skip to content

Pre-discovery workflow

Complete this workflow before you run Discover Code or Discover Metrics. It helps you validate the incoming source package, normalize files, confirm language-specific prerequisites, and decide which Discovery settings need to change before the first upload.


Source intake and inventory

Start with the source package itself. Discovery works best when the delivery method, folder layout, and expected content are documented before you import anything into Eclipse.

  1. Obtain the complete source archive and record how it was delivered, for example, SFTP, a zip archive, or a repository clone.

  2. Understand how the source is organized. Confirm whether development, test, and production artifacts share one tree or are split across separate repositories or folders.

  3. Capture a source inventory that lists expected languages, module types, approximate counts, and known shared libraries.

  4. Record source control and framework context, including proprietary build frameworks, shared utility libraries, scheduler definitions, or generated artifacts.

  5. Document missing components before discovery starts, for example, missing copybooks, JCL procedures, DDL files, or schema definitions.

Warning

Discovery results can only be as complete as the source package that you receive. If the archive and the expected inventory do not match, resolve the gap before the first discovery run.


Identify languages and technologies

Compile the full list of languages and technologies present in the source package. This list drives your configuration, search-order, and pre-discovery decisions.

Language or technology Typical extensions Verify before discovery
COBOL .cbl, .cob, .cpy Copybooks are present, margins are known, and IMS usage is identified.
CICS Embedded in COBOL EXEC CICS usage is identified and supporting maps or copybooks are included when they are part of the source package.
PL/I .pli, .pl1 Margin boundaries and custom OR or NOT symbols are known.
Natural .nsp, .nsl, .nsa Files were extracted in SYSTRANS format and locale settings are known.
JCL .jcl, .job, .proc Jobs, procedures, and in-stream data are split into separate files.
Java .java Package roots are clear and multi-project dependencies are mapped.
C and C++ .c, .h, .cpp, .hpp Shared headers and platform-specific dependencies are accounted for.
C# .cs, .csproj, .sln Solution layout and .NET-specific source dependencies are identified.
SQL and DDL .sql, .ddl Auto-margin detection and DB schema import requirements are understood.
Assembler .asm, .s Threshold-based language detection is reviewed if token noise is expected.

Validate and sanitize source files

Normalize the files before you upload them. This reduces misclassification, parse failures, and noisy undiscovered-entities results.

Validate UTF-8 encoding

  • Confirm that the source files are stored in proper UTF-8 encoding before upload.
  • Use your editor, repository tooling, or a validation script to identify files that still use a legacy encoding.
  • Resolve failed encoding checks with the source provider before you start Discovery.
  • Re-run the validation after any bulk conversion.

Split concatenated files

Split bundled files into the individual artifacts that Discovery expects to analyze.

Scenario Action
One file contains multiple JCL jobs or procedures Split the file into one JCL or procedure artifact per file.
One file contains multiple COBOL programs Split the file into one .cbl program per file.
One file contains multiple copybooks Split the file into one .cpy copybook per file.

Verify file extensions

  • Use consistent extensions for each language and artifact type.
  • Correct obvious mismatches, for example, a copybook saved with a program extension.
  • Review the extension guidance in Code Discovery before the first run.
  • If the source uses ambiguous or custom naming, decide whether to preserve original extensions or normalize them through the Discovery configuration.

Organize files and folders

  • Keep major file types in separate folders whenever possible.
  • Do not mix jobs, programs, copybooks, includes, and schema files in the same source folder.
  • Decide up front how shared libraries or shared components are organized across projects.
  • If a language is definitely not present in the source package, plan to disable it in Discovery_Config.xml before Discover Code.

Review configuration inputs

Before you upload any Discovery configuration, confirm which settings you need to change based on the source inventory.

Decision area Review before upload Detailed reference
Language enablement and parser limits Disable unused languages, confirm timeouts, and decide whether to preserve original extensions. Discovery configuration
COBOL, PL/I, and SQL margin handling Verify standard and non-standard source columns before the first run. Discovery_Config.xml
IMS, shared utilities, and folder retention Decide whether to enable IMS handling, utility handling, and retained directory structure. Other settings
Ambiguous dependencies Decide whether discovery-search-order.xml is required for Java, copybooks, procedures, or shared schemas. discovery-search-order.xml
Utility modules Decide whether you need utilities.xml and exclude_utility for project-specific utilities. Discovery configuration

Language-specific readiness checklists

Use the following checklists to confirm the most common language-specific prerequisites before the first run.

COBOL and IMS

  • Verify whether the source uses standard COBOL columns 1-6, 7, 8-72, and 73-80, or a client-specific layout.
  • Keep programs and copybooks in separate folders.
  • If IMS is present, set cobol_ims_dependencies to true before Discover Code.
  • Configure discovery-search-order.xml when copybooks or IMS assets are spread across multiple libraries or repositories.
  • Decide whether COBOL_PGM_ID_AS_NAME should use the PROGRAM-ID value instead of the file name.

CICS

  • Identify which COBOL programs contain EXEC CICS statements or other CICS-specific entry points before the first run.
  • Include related maps, copybooks, or other delivered CICS assets when they are required to interpret the online transaction flow.
  • Record any missing CICS resources in the source inventory so later result reviews can distinguish missing package content from discovery defects.

JCL

  • Split concatenated jobs and procedures into individual files.
  • Keep JCL and procedure libraries separate from COBOL source and copybooks.
  • Configure STEP_NAME when JCL control cards must be recognized during Discovery.
  • Add search-order rules when JCL procedures resolve from specific procedure libraries.

Java

  • Organize source into clear project and package roots, for example, src/main/java.
  • Treat discovery-search-order.xml as required when Java dependencies span multiple project roots.
  • Use INCLUDE_PACKAGES and EXCLUDE_PACKAGES to limit or expand dependency resolution.
  • Document any shared components that must be copied or referenced across project boundaries.

PL/I

  • Confirm PL1_PARSER_MARGIN_START and PL1_PARSER_MARGIN_END.
  • Review PL1_PARSER_OR_SYMBOL and PL1_PARSER_NOT_SYMBOL when the source uses non-default operators.
  • Check PL1_PARSER_ANS if the source contains printer-control characters.

Natural

  • Confirm that the source was extracted in SYSTRANS format.
  • Set DECIMAL_CHARACTER and INPUT_DELIMITER for the project locale.
  • Review LANGUAGE_CODES when language-specific Natural objects must resolve correctly.

Assembler

  • Review UNKNOWN_TOKEN_THRESHOLD if Assembler files are likely to contain token noise or hybrid source patterns.

SQL and DDL

  • Enable ENABLE_AUTO_MARGIN_DETECTION before you import SQL or DDL with inconsistent margins.
  • Set AUTO_MARGIN_SOURCE_SAMPLE_SIZE to a representative sample of the source set, typically three to five files.
  • Set AUTO_MARGIN_THRESHOLD to match the quality of the source set, typically between 25% and 75%.
  • Import the database schema before discovery when SQL objects must resolve against existing database objects.
  • If multiple schemas contain same-named tables, use <contained-in> rules in discovery-search-order.xml to disambiguate them.

Final pre-discovery validation checklist

Run through this checklist before you trigger Discover Code.

Check Why it matters
All files are UTF-8 encoded Prevents parse failures and incorrect language classification.
Concatenated files have been split Lets Discovery process one artifact per file.
File extensions are correct and consistent Improves identification accuracy.
Files and folders are organized by type Reduces noisy src/maybe and undiscovered-entities results.
Languages are identified and unused languages are disabled Improves speed and reduces false positives.
Margin settings are verified for COBOL, PL/I, and SQL Prevents parser errors on fixed-column source.
Natural files are confirmed in SYSTRANS format Required for accurate Natural discovery.
IMS handling is enabled when IMS is present Preserves COBOL-to-IMS discovery relationships.
Search order is configured for multi-repository or multi-schema source Prevents unresolved or ambiguous dependencies.
utilities.xml is configured when project utilities need special handling Avoids treating utility modules as ordinary missing dependencies.
Missing components are documented and communicated Makes result gaps easier to interpret after the first run.
The latest Discovery configuration is uploaded to the server Ensures the first run uses the intended settings.

Continue with Discovery

After the pre-discovery checks are complete, continue with Code Discovery to upload the configuration, run Discover Code, and review the first discovery results. If the output does not match your source inventory, use Discovery troubleshooting before rerunning the workflow.