Understanding your Data Lineage Project

A Data Lineage project lets you explore a legacy IBM application—COBOL, RPG, PL/I, and related batch programs—using a read-only view created from your ingested source code. Zengines parses these sources to build a unified UI for all supported languages. The same tabs, layouts, and lineage workflows apply across COBOL, RPG, and other legacy code.

Who does what

You do not edit source code inside Data Lineage; you discover and trace how the system works.

Deterministic vs AI content

Deterministic (Explore) — Everything in the six Explore tabs comes from parsing: grids, counts, SQL text, variable trees, job steps, file and data set links. The same project always shows the same facts until the underlying ingestion is refreshed.

AI (Dashboard and Summary actions) — Ask a Lineage Question lives on the dashboard only. Summary and Tell Me More appear on module, variable, and job detail views. AI-generated text may differ when you run it again; links inside AI answers still point to deterministic Explore items.

Recently asked questions — Under the Ask a Lineage Question box on the dashboard, Recently asked questions lists prompts you asked in this browser. That history is local to your browser, not shared across users or devices.

What to supply for a strong project

Zengines parses legacy program source (COBOL, RPG, PL/I, and related), embedded SQL, job languages (JCL on z/OS; CL, CLLE, and related on IBM i—especially for AS/400-based applications), copybooks and shared layouts, and Db2-style schema metadata. Customer Success coordinates what your project ingests.

During source code ingestion, Zengines runs automated checks to detect and fix bad characters and non-conforming code where possible, so parsing and lineage are more reliable. Customer Success can advise on sources that need attention before upload.

The layout below is a typical structure Customer Success uses when preparing a COBOL-oriented codebase; IBM i and mixed-language projects follow the same general pattern with language-appropriate folders.

Folder and file layout

Db2 schema metadata (SYSCOLUMNS.csv)

SYSCOLUMNS.csv is ingested separately from program source—it is not stored in your source tree or at a project root folder. It tells Zengines about Db2 tables and columns (IBM SYSCOLUMNS-style export).

• Customer Success uploads schema metadata as part of project setup
• One header row, then one row per column; no blank lines between rows
• COLUMN_COMMENT should carry short business meanings (helpful for architects and analysts tracing field semantics)

Zengines provides queries against the Db2 SYSCOLUMNS catalog to extract everything required for this file. Customer Success can provide those queries if your team needs to generate the export.

Required header columns:

TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, ORDINAL_POSITION, COLUMN_DEFAULT, IS_NULLABLE, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, CHARACTER_OCTET_LENGTH, NUMERIC_PRECISION, NUMERIC_SCALE, DATETIME_PRECISION, CHARACTER_SET_NAME, COLLATION_NAME, COLUMN_CONSTRAINT_TYPE, COLUMN_CONSTRAINT_NAME, COLUMN_CONSTRAINT_EXPRESSION, COLUMN_CONSTRAINT_TABLE_REFERENCE, COLUMN_CONSTRAINT_COLUMN_REFERENCE, COLUMN_CONSTRAINT_COLUMN_REFERENCE_CONSTRAINT_NAME, EXTRA, PRIVILEGES, COLUMN_COMMENT

File extensions (COBOL deliverables)

All COBOL-related artifacts use the .cbl extension: programs, DCLGEN, and copybooks. Do not use .cpy or .dcl in deliverables prepared for this pipeline unless Customer Success specifies otherwise for your project.

COBOL format expectations

Programs should use fixed-format, 80-column COBOL so parsing is reliable:

• Column 7: * for comments, space for source, - for continuation
• Columns 73–80: leave blank unless your shop requires sequence numbers

Customer Success can advise on formatting existing sources before ingestion.

Job languages and file lineage

Job languages are the batch control scripts that tell the system which programs run and which files or data sets they use—for example JCL on z/OS and CL / CLLE on IBM i (common on AS/400-based applications).

Jobs are not strictly required to create a project, but including job language sources gives the best results:

• Files tab and file sections on modules populate when job definitions link programs to files and data sets
• Jobs tab shows steps, modules, and connections into variables that represent file records

In COBOL, SELECT / ASSIGN should align with DD names in JCL where applicable so program → file → job relationships resolve in Explore.

SQL and copybooks

Embedded EXEC SQL in COBOL drives Tables and Fields lineage. DCLGEN and copybooks define structures that appear under Variables and in AI summaries (for example, which copybook defines a group item).

You can open and use a project without job language sources, but table-to-file research is limited until jobs and file names are ingested. Plan to include JCL, CL, or related job definitions when you care about batch flows, extracts, and file in/out on modules.