SuperBOL File Viewer Premium

SuperBOL File Viewer is a tool for viewing COBOL data files. It supports the following organization types:

  • SEQUENTIAL and LINE SEQUENTIAL;
  • INDEXED;
  • RELATIVE.

These files typically have extensions like .dat, .seq or .idx.

Important

SuperBOL File Viewer is a Premium feature. A free version allows you to view files containing at most 100 records. Beyond that, a license key is required (see Adding a SuperBOL License). Contact superbol@ocamlpro.com for commercial offers.

Prerequisites

COBOL data files cannot be interpreted on their own: their structure is defined by the COBOL program that uses them. To open a data file, you therefore need:

  • a COBOL program (.cob or .cbl file) containing the file declaration in the FILE-CONTROL section as well as the record descriptions in the DATA DIVISION;
  • optionally, copybooks referenced by this program to describe the field structure. Copybooks are recognized from the extensions listed in the cobol.copyexts setting (for example .cpy).

You only need to first identify either the COBOL program that defines the data file you wish to view, or the copybook that describes its records: in the latter case, the matching program is searched for automatically in the workspace.

Opening a File

Step 1: Open the Data File

There are two methods to open a data file in VSCode:

  • Via the file menu: go to File > Open File... and select your data file directly.
  • Via the file explorer: open the folder containing your files with File > Open Folder..., then double-click the desired data file (for example, a file with a .dat extension) in the explorer panel on the left.

Once the file is open, a schema selection window appears in the center of the screen.

Step 2: Select a COBOL Program or a Copybook

Opening the file requires associating a COBOL program, or a copybook, that describes its format.

Selection window for the COBOL program or copybook describing the opened data file.

Selection window for the COBOL program or copybook describing the opened data file.

Click on Select a COBOL File or Copybook... and select the corresponding file on your computer. The accepted extensions are listed below the buttons. This file can be located in the open project or anywhere else on your disk. The association is saved for subsequent openings of that data file, for the current workspace.

When the data file has already been associated with a COBOL program or a copybook, two buttons Reuse layout from copybook <copybook> and Reuse layout from <program>, naming the last copybook and the last program used, are shown above, allowing you to reuse the previous association directly.

Selecting a Copybook

When a copybook is selected, the workspace is searched for the COBOL programs that include it with a COPY statement and whose record layout can be extracted:

  • if a single program is found, it is used automatically, without any further action on your part;
  • if several programs are found, a Multiple programs found window asks you to choose the one to use from a list (see Selection Lists). The Select a COBOL File or Copybook... button also lets you select another file manually;
  • if no program is found, you are invited to select a COBOL program manually.

It is also possible to view the raw file without a COBOL program by clicking on View as Raw Data.

Tip

If you do not have access to the corresponding COBOL program, you can still open the file by clicking on View as Raw Data to inspect its raw content.

Step 3: Disambiguation (if necessary)

Note

This step only appears if the selected COBOL program declares multiple files in its FILE-CONTROL section and none of them can be identified automatically. The file opens directly if only one file is declared, or if the ASSIGN clause of one of the declarations matches the name of the data file.

The same COBOL program can declare multiple files in its FILE-CONTROL section. When no declaration that corresponds to the opened file can be automatically determined, a Multiple file declarations found disambiguation window is displayed, asking you to choose it.

Disambiguation window for file declarations (when multiple data files are declared by the same COBOL program).

Disambiguation window for file declarations (when multiple data files are declared by the same COBOL program).

Select the appropriate declaration from the list, then click Confirm to validate.

Selection Lists

The disambiguation windows, whether for choosing a file declaration or a program including a copybook, display the possible choices in a scrollable list:

  • the entries are sorted alphabetically;
  • double-clicking an entry selects it and validates the choice directly, without going through the Confirm button;
  • the last entry chosen for this data file is pinned at the top of the list and pre-selected;
  • when the list holds more than ten entries, a Filter... search bar placed above it allows you to filter its contents instantly.

Viewer Interface

Once the file is opened with the associated COBOL program, the viewer displays the structured data in a table format, with one row per record and one column per field (columns can be grouped to represent COBOL data groups).

Main interface of the file viewer.

Main interface of the file viewer.

From top to bottom, the interface is divided into three main parts where several interactions are possible:

  • the header, giving the organization of the file and its total number of records, together with a control panel;

  • the data table, where the columns can be moved freely, except for the No column of record numbers, which stays pinned to the left, and a field cannot be taken out of the group it belongs to;

  • the navigation panel.

The first row of the table is pinned below the column names and gives the PICTURE and USAGE clauses of each field. Hovering over one of its cells displays additional information about the field, such as whether it is signed and how it is stored.

Data Visualization

The record details window. Each field features labels for its PICTURE and USAGE clauses, and the associated value on the right-hand side.

The record details window. Each field features labels for its PICTURE and USAGE clauses, and the associated value on the right-hand side.

By double-clicking a row in the table, the record details window, titled Record #n where n is the record number, opens to display the details of the associated record. The record structure presents the data in a tree format to visually distinguish the different groups. The groups are collapsed when the window opens: clicking on a group name expands it, and clicking it again collapses it.

At the top of the window are formatting buttons:

  • a Show PIC and USAGE button allows you to show or hide labels, which helps visually lighten the interface;

  • a Raw view button allows you to display the values as they are stored on disk, with their non-significant characters: for text values, leading and trailing spaces are shown as middle dots (·), and for numeric values the leading zeros are dimmed. Signs are also displayed at the position where they are stored, at the beginning or at the end of the value. Fields cannot be edited in this mode.

When the length of a record does not match the one declared by the record layout, it is marked in the No column of the table as well as in the record details window. The fields located past the end of the record then hold no data, and the record cannot be edited.

Editing a Record

Editing a field: the previous value is recalled above the input.

Editing a field: the previous value is recalled above the input.

Outside of the Raw view mode, the values displayed in the record details window are editable input fields. Numeric values with a decimal part are split into a sign selector (+ / -) for signed fields, an integer part and a decimal part.

As soon as a field is modified, its previous value is recalled above the input (Previous value: ...).

Each input is checked against the PICTURE clause of the field (number of digits, presence of a decimal part, allowed characters, etc.). In case of error, an explanatory message is displayed next to the field and the Update button is disabled until the error is fixed.

Modifications are only saved when clicking Update: the Close button closes the window without saving pending changes. Clicking Update writes only the modified fields to the data file, the other ones keeping their original content. The window stays open and a message lists the modified fields (Saved. Changed fields: ...), while the table of the main window is updated.

Warning

Changes are written directly to the data file. Remember to keep a backup copy if needed.

Formatting

Buttons for formatting record values.

Buttons for formatting record values.

At the top left of the main window are buttons to format the data.

Similarly to the record details window, you can show or hide non-significant characters using the Raw view toggle. The same setting applies in both windows: changing it in one of them changes it in the other. Like the column selection, the state of this toggle and that of Show PIC and USAGE are kept for subsequent openings of the viewer.

With the Show only records with errors toggle, you can also filter the view to keep only records containing errors (notably typing errors, when values do not match the specified PICTURE clause). This makes it easy to spot data that needs fixing. Records containing errors are highlighted in the table at all times, whether this toggle is enabled or not.

Data Navigation

Navigation interface for records at the bottom of the main window.

Navigation interface for records at the bottom of the main window.

At the bottom of the main window is a navigation interface. In order:

  • a Go to record field allowing you to jump to a specific record number. For example, entering 5 and clicking Go will take you directly to the fifth record (which will be highlighted). The Enter key validates the input as well, and a record number outside the range of the file is ignored;

  • a Page Size drop-down list allowing you to choose the number of records displayed per page;

  • an indicator of the currently displayed record numbers relative to the total (1 to 10 of 10 in the screenshot);

  • an indicator of the current page relative to the total number of pages (Page 1 of 1 in the screenshot), surrounded by buttons to go to the next / previous page or to the beginning / end of the file.

Filtering

Column Set Filtering

Column display management panel.

Column display management panel.

At the top right of the main window is a Columns button that opens a floating panel with the list of fields. The list follows the structure of the record: the fields of a group appear indented under its name.

This allows you to select which columns are displayed or hidden by checking or unchecking the corresponding boxes. Checking or unchecking a group applies to all of its fields at once, and the box of a partially displayed group is shown in an intermediate state. Select all and Unselect all buttons are also present to select and deselect all columns at once.

Unchecking an OCCURS group also hides the column displayed when it is folded, so that the group disappears entirely from the table.

The selection is kept for subsequent openings of the viewer, and the number of hidden columns is displayed next to the Columns button.

A search bar at the top of the panel allows you to search for specific columns.

Tip

If you only want to display a small number of specific columns, you can uncheck everything with Unselect all and use the search bar to find and check the columns you need.

A “fullscreen” button at the top right of the floating window also allows for a wider and more comfortable view in case there is a great depth of data.

Column Data Filtering

Floating window for filtering column data.

Floating window for filtering column data.

Each column has a “funnel” icon to the right of its name, allowing you to filter the displayed data according to certain criteria.

Whatever the type of the field, the filters are:

  • Contains to keep only records where the value in the selected column contains the entered text;
  • Starts with when the value starts with the input;
  • Ends with when the value ends with the input;
  • Equals when the value is identical to the input;
  • Blank when the value is empty;
  • Not blank when the value is not empty.

Comparisons are case-sensitive. The filter is applied by clicking Apply, and Clear removes it.

Tables (OCCURS clause)

A group with an OCCURS n clause is displayed as a table of columns called “occurrences”, indexed by an integer.

Folded OCCURS table: a single greyed-out column summarizes the occurrences.

Folded OCCURS table: a single greyed-out column summarizes the occurrences.

When the file is opened, this table is folded and displays a single greyed-out column, titled (n folded occurrences) where n is the number of occurrences. The cells in this column show “...”. Therefore, the table remains readable when a record repeats a large number of fields.

The same OCCURS table unfolded: one column per occurrence.

The same OCCURS table unfolded: one column per occurrence.

Clicking anywhere on the group header unfolds it, and clicking again folds it back. Once unfolded, the group replaces that single column with one column per occurrence.

The headers of these columns repeat the field name followed by its occurrence index. The occurrences remain side by side and in the order of their indices when the columns are moved.

Nested OCCURS tables.

Nested OCCURS tables.

In case of nested OCCURS, each occurrence of the outer group has its own copy of the inner group, which is folded when the file is opened as well. Each copy folds and unfolds independently of the others.

The inner OCCURS table unfolded in the first occurrence of the outer table.

The inner OCCURS table unfolded in the first occurrence of the outer table.

The filter of an occurrence column applies only to that occurrence. On the other hand, the global search, that covers all the columns, applies to every occurrence.

In the record details window, the field names keep their occurrence index.

The record details window: the occurrences keep their index there.

The record details window: the occurrences keep their index there.