COBOL Copybook Toolkit

View the exact byte position of every field in a COBOL copybook, decode and edit fixed-width data files, and restructure copybooks — without doing the column arithmetic by hand.

Works with .cbl, .cpy, .cpb, and .cob files, in both reference (fixed-column) and free format — the format is auto-detected.

Getting started in 30 seconds

1. Open a copybook file (for example sample.cbl).
2. Right-click in the editor → COBOL: Show Copybook Layout.
3. That's it — you'll see every field with its start/end byte position, length, PICTURE, and usage.

All commands are available three ways:

• Right-click in the editor of an open copybook
• Right-click a copybook file in the Explorer sidebar
• Command Palette (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows/Linux) → type "COBOL"

The four commands

1. COBOL: Show Copybook Layout

Shows a searchable table of every field in the copybook:

Click any row to jump to that field in the copybook source. Use the filter box to find a field by name in large copybooks.

Two extras in the toolbar:

• Expand OCCURS — by default the table shows one row per declared field, positioned at its first occurrence. Tick this to expand every OCCURS (nested included) into its own row with absolute Start/End and an Occurrence column (e.g. GACCOUNTS 2/2 ; GTRANSACTIONS 3/3), so you can see exactly where each copy lives in the record.
• Download CSV… — saves the expanded table as name-layout.csv with columns Field, Path, Level, Start, End, Length, PIC, Usage, Occurrence, Redefines, Group. Open it in Excel and build your own parser: with a record's text in a cell, each field's value is simply =MID(record, Start, Length). Filter Group = N for the fields that actually hold data, and use the Redefines column to skip overlays.

2. COBOL: Open Data Editor

Decode a fixed-width data file into an editable form — or create records from scratch.

When you run it, you choose how to start:

• Load a data file — pick a .dat/.txt file; it is split into records using the copybook's record length and every record is decoded into named fields.
• Start from a generated sample record — the extension creates a valid record for you (handy when you don't have data yet).

In the editor you can:

• Edit any field value — just type in the input next to the field name. Numeric fields keep full precision; the PIC and usage are shown next to each field.
• ◀ Prev / Next ▶ — step through the records in the file.
• + Add record — append a new sample record.
• Randomize record — fill the current record with random valid values.
• ⟳ Reload — re-parse the copybook (including unsaved editor changes) and re-read the data file from disk. Use it when you've changed the copybook source or the data file and the editor is showing stale positions/values. It discards unsaved field edits, so it asks for confirmation first.
• Save data file… — re-encode all records to fixed-width bytes and save.

3. COBOL: Edit Copybook Layout

Restructure the copybook itself, with byte positions recomputing live:

• Rename a field — edit the name in the table.
• Change a PIC or usage — edit the PIC cell or pick a usage from the dropdown; lengths and all downstream positions update instantly.
• Change OCCURS — set the occurs count (0 = no OCCURS).
• Delete a field — click Delete on its row.
• Insert a new field — use the "Insert a new field" form: pick an existing field to anchor to, a position (before / after / as first child / as last child), then give the new field a level, name, PIC, usage, and optional OCCURS.

A live copybook preview at the bottom shows the regenerated source. When you're happy, click Write to copybook document — the open copybook document is replaced with the new text (you still review and save it yourself, and undo works normally).

Migrating your data files alongside an edit

If you have existing fixed-width data files (test fixtures, sample records) that match the original layout, the Data migration section of this panel keeps them in sync as you edit:

1. Click Attach data file(s)… and pick one or more .dat/.txt files — they're read against the copybook as it currently stands in the document (the "old" layout).
2. As you rename, retype, insert, or delete fields, a preview table updates live showing the first 20 records of each attached file migrated to your edited layout: values follow field names (a rename carries its value; a delete drops it), and any newly inserted field is highlighted with an input where you type its default value once — that value is applied to every record, in every attached file. A warning count appears when a carried value won't fit its new PIC (e.g. retyping a field narrower); the full detail goes to the "COBOL Migration" output channel.
3. Click Save migrated data file(s)… to migrate the entire file (not just the preview) and write it out as name.migrated.ext next to the original — your source files are never overwritten. If a migrated file already exists you're asked whether to overwrite it.

Attach your data files before clicking "Write to copybook document" — once the document is rewritten, the old and new layouts are identical and there's nothing left to migrate. For large batches of files, see the CLI's cobol migrate command instead (same underlying logic, scriptable for many files at once).

4. COBOL: Migrate Data

Move fixed-width data files between two existing copybook files — for example when a new version of a copybook arrives and your data still matches the old one. (Section 3's migration works while you edit a single copybook; this command works with two separate files and no editing.)

When you run it you're asked for two copybooks:

1. FROM — the copybook your existing data matches (right-clicking a copybook runs the command with that file as FROM).
2. TO — the new layout you want the data to follow.

The panel then walks you through the migration:

• Field comparison — every field is classified as unchanged, changed (same name, different PIC/usage/OCCURS — the exact change is listed), added (only in TO), or removed (only in FROM). Changes that can lose data (narrower PIC, lost sign or decimals, fewer occurrences) are flagged with ⚠ data loss risk.
• Rename mappings — a renamed field looks like one added + one removed field, so the panel suggests likely pairs (same PIC, similar name) and offers an Accept suggested rename mapping(s) button. You can also map any added field to any removed field manually with the dropdown on its row, or unmap it again. A mapped field's values are carried instead of dropped and re-defaulted.
• New field values — each genuinely new field gets an input; the value you type is applied to every migrated record (sensible defaults — zeros/spaces — are prefilled).
• Data files & preview — attach one or more .dat/.txt files. Each is validated against the FROM layout (file length must be a whole number of records, and record 1's numeric fields are sanity-checked — a warning here usually means the wrong copybook was selected). A before/after table shows the first records with old → new for every value that changes, added fields highlighted, removed fields struck through.
• Approve & write migrated file(s) — migrates each attached file in full and writes it as name.migrated.ext next to the original (sources are never overwritten; you're asked before replacing an existing .migrated file). Truncation warnings go to the "COBOL Migration" output channel, and you can save a JSON migration report (mapping used, defaults, warnings per record) as an audit trail.

Step by step

1. Right-click the copybook your data currently matches → COBOL: Migrate Data (that file becomes FROM; from the Command Palette you're asked for it first).
2. In the file dialog, pick the TO copybook (the new layout).
3. In the Field comparison table, check the statuses and any ⚠ data-loss flags.
4. Click Accept suggested rename mapping(s), or map added ↔ removed pairs manually with the "rename of:" dropdown, so renamed fields keep their values.
5. In New field values, type the value every record should get for each added field (zeros/spaces are prefilled).
6. Click Attach data file(s)… and pick the data file(s) — check the validation notes and the before/after preview (old → new per cell).
7. Click Approve & write migrated file(s) — each file is written as name.migrated.ext next to the original. Use Show warnings for truncation details and Save report… for a JSON audit trail.
8. Verify with COBOL: Open Data Editor on the TO copybook, loading the .migrated file.

For scripted or batch use, the CLI mirrors this flow: cobol diff old.cbl new.cbl prints the same comparison with rename suggestions, and cobol migrate old.cbl data.dat --to new.cbl --map map.json --defaults defaults.json performs the migration.

Everywhere else in the editor

• Hover any field name in a copybook to see its position, length, and type inline.
• The Explorer sidebar gains a Copybook Fields tree for the active copybook — click a field to navigate.

What it understands

• Level numbers, group vs. elementary items, FILLER, 88/66 levels.
• PICTURE: 9, X, A, S, V (implied decimal), P, and edited symbols.
• USAGE: DISPLAY, COMP-3/PACKED-DECIMAL, COMP/BINARY/COMP-4, COMP-1, COMP-2.
• OCCURS n TIMES (including nested) and OCCURS DEPENDING ON (fixed max).
• REDEFINES (overlays the same bytes).

Data is treated as ASCII/UTF-8. Byte positions are 1-based and inclusive.

Tips

• Record length is shown at the bottom of the layout view and in the data editor toolbar — if your data file's line length doesn't match, check for trailing newlines or encoding issues.
• The data editor treats the file as fixed-width records back to back; a file shorter than one record is padded with spaces.

License

MIT — see LICENSE.md.