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.
-
Obtain the complete source archive and record how it was delivered, for example, SFTP, a zip archive, or a repository clone.
-
Understand how the source is organized. Confirm whether development, test, and production artifacts share one tree or are split across separate repositories or folders.
-
Capture a source inventory that lists expected languages, module types, approximate counts, and known shared libraries.
-
Record source control and framework context, including proprietary build frameworks, shared utility libraries, scheduler definitions, or generated artifacts.
-
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.xmlbefore 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_dependenciestotruebefore Discover Code. - Configure
discovery-search-order.xmlwhen copybooks or IMS assets are spread across multiple libraries or repositories. - Decide whether
COBOL_PGM_ID_AS_NAMEshould use thePROGRAM-IDvalue instead of the file name.
CICS¶
- Identify which COBOL programs contain
EXEC CICSstatements 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_NAMEwhen 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.xmlas required when Java dependencies span multiple project roots. - Use
INCLUDE_PACKAGESandEXCLUDE_PACKAGESto limit or expand dependency resolution. - Document any shared components that must be copied or referenced across project boundaries.
PL/I¶
- Confirm
PL1_PARSER_MARGIN_STARTandPL1_PARSER_MARGIN_END. - Review
PL1_PARSER_OR_SYMBOLandPL1_PARSER_NOT_SYMBOLwhen the source uses non-default operators. - Check
PL1_PARSER_ANSif the source contains printer-control characters.
Natural¶
- Confirm that the source was extracted in
SYSTRANSformat. - Set
DECIMAL_CHARACTERandINPUT_DELIMITERfor the project locale. - Review
LANGUAGE_CODESwhen language-specific Natural objects must resolve correctly.
Assembler¶
- Review
UNKNOWN_TOKEN_THRESHOLDif Assembler files are likely to contain token noise or hybrid source patterns.
SQL and DDL¶
- Enable
ENABLE_AUTO_MARGIN_DETECTIONbefore you import SQL or DDL with inconsistent margins. - Set
AUTO_MARGIN_SOURCE_SAMPLE_SIZEto a representative sample of the source set, typically three to five files. - Set
AUTO_MARGIN_THRESHOLDto 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 indiscovery-search-order.xmlto 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.