Making COBOL and PL/I code changes

IBM Z® Open Editor supports COBOL, PL/I, HLASM, and REXX editing. Select a program, copybook, include, or JCL file in the Explorer to open it in the editor. For HLASM specific details, see Making High Level Assembler code changes. For REXX specific details, see Making REXX code changes.

With the syntax highlighting capability, you can quickly distinguish reserved words, comments, constants, and variables of COBOL, PL/I and HLASM programs. With vertical rulers, which mark different areas, you can better determine the correct areas for comments and the boundaries for coding in areas A and B, and so on.

The editor provides the following features and capabilities:

Browsing code by using the Outline view

As you view the source, you can use the Outline view to efficiently explore and navigate the code of the program. By looking through the items in this view, you can get an idea of what the program does at a high level.

How to use it

You can use the Outline view only after you have opened a file or program. If the Outline view is not already expanded, you can open it by clicking View > Open view > Outline.

You can use this view to:

• Expand and collapse sections such as Division Headings, Section Headings, and Variable Group Names in the Outline View.
• Recognize includes, procedures, loops quickly via the icons located by the various items.
• Go to a wanted location in the code by clicking that section header in the view.
• Sort by Position, Name, or Type.
• Search for identifiers within the outline by pressing Ctrl+Shift+O (Windows), or Cmd+Shift+O (Mac) within the Editor window.

When you move your cursor over the program, outline nodes are automatically selected. To toggle this and other features related to the Outline View, hover over the upper right corner of the Outline View. You can see the option ..., where you can click to find multiple options to organize your outline view such as Follow on Cursor, Filter by Type and Sort by Name, Position, and Type.

Code and variable completion suggestion

When you are typing code, code completion suggestion provides you with a matching list from which you can select commands, defined variable and paragraph names, and code snippets.

How to use it

The code completion suggestion is displayed automatically while you are typing or when you press Ctrl+Space (Windows and Mac) depending on your preferences settings.

Hovering for declaration

You can see the working storage definition or DCL definition and the parent group of a variable or paragraph name by moving your mouse cursor over to the variable or paragraph name.

How to use it

The declaration hover is enabled by default.

Previewing copybooks and include files

You can preview the contents of a copybook or include file by moving your mouse cursor over the copybook name in a COPY statement in COBOL and HLASM, or the include file in a %INCLUDE statement in PL/I and REXX, without having to navigate away from the file you are working in. To open the file in a separate editor, press Ctrl+Click (Windows) or Cmd+Click (Mac).

How to use it

You must specify the filepath to the copybooks or include files in your ZAPP file property groups to resolve the references. The location can be a local one, such as another directory in your workspace or it can be an MVS data set on a remote z/OS system using Zowe connectivity to find an load the files.

If no filepath is specified or the copybooks or include files are not found in the provided filepath, an error (red squiggle) is shown. To resolve this, follow the instructions provided and our ZAPP overview and Property Groups pages.

Expanding programs with copybooks

You can preview how the compiler will be expanding copybooks in your COBOL program. The results will be displayed in a new editor tab for a temporary file showing how the copybooks will be inserted into the code and REPLACING statements expanded.

How to use it

• Open a COBOL program that includes copybooks.

• Right-click inside the editor and select Expand source code from the context menu.

  A new editor tab will open appending "expanded_COBOL" to the filename showing the results. You will see copybooks inside the program text with additional comments listing the source location of the included file. Inside the program you find variable names substituted with REPLACING values if specified in the original COPY statement.

Operations on variable and paragraph names

When you double-click a variable or paragraph name to highlight the entire name and then right-click it, you can see the available operations.

How to use it

• Click Change All Occurrences: Ctrl+F2 (Windows) or Cmd+F2 (Mac)

  When you type the new name, all occurrences are changed simultaneously.

  NOTE: In the scroll bar on the right side of the editor, each occurrence is noted with a location bar.

• Click Find All References: Alt+Shift+F12 (Windows) or Option+Shift+F12(Mac)

  A Results References view for the variable or paragraph is displayed on the left side of the screen. Click any result to go to that location in the file.

• Click Peek References: Shift+F12 (Windows and Mac)

  This opens a Results References view in the CodeLens box underneath the variable or paragraph. Click any result to go to that location in the file.

  

• Click Go to Definition: F12 (Windows and Mac)

  Go to the location where the variable or paragraph is defined. It opens the copybook or include file if applicable.

• Click Go to Symbol: Ctrl+Shift+O (Windows) or Cmd+Shift+O (Mac)

  When you enter an object name in the search bar or you scroll through the items to select the object, the cursor is moved to that location.

• Click Peek Definition: Alt+F12 (Windows) or Option+F12 (Mac)

  This opens a CodeLens box that shows where the variable or paragraph was defined in the code. If you use the keyboard shortcut Alt+F12 (Windows) or Option+F12 (Mac), the variable or paragraph name is only clicked once before the keyboard shortcuts are pressed. Double-click any result to go to that location in the file.

  

• Click Rename Symbol: F2 (Windows and Mac)

  Rename the selected symbol, and the changes are done in the whole program and copybook or include if it is attached to that symbol.

Syntax checking

The syntax checking feature underlines unrecognized statements and expressions in red, which helps you to make quick corrections and reduce compile errors.

Syntax checking also works for misspelled COBOL, PL/I reserved words and unknown variable names. For HLASM, there are syntax errors for improper spaces in a continuation line and unresolved copy statements.

How to use it

To see all the syntax errors in the open files, open the Problems view through the View menu or by clicking the error and warning icon at the bottom in the status bar. Double-click the list item to directly go to the problem.

Editing double-byte characters

When writing international applications with string constants that contain shift-in/shift-out double-byte characters, Z Open Editor will assist developers in ensuring that the COBOL program lines do not exceed the maximum line length configured for the editor.

It will do that in two ways:

1. Any sets of characters that take up more than one byte will be automatically visualized in the editor with special guillemets (« ») annotations. These annotations only help you to identify the characters. They are not actual characters of the program and will not be stored with it. Also, when you copy and paste the text to another editor, they will not be added to the clipboard.
2. When you start typing such characters, the status bar will automatically start displaying a Byte Count entry that shows you how many bytes you have left before reaching the maximum line length.

Also review EBCDIC code pages and mappings files with examples for converting double-byte characters from EBCDIC to UTF-8 and vice versa when working with files from z/OS MVS and UNIX System Services.

Undoing and redoing

Undo your changes by pressing Ctrl+Z (Windows) or Cmd+Z (Mac). Redo your changes by pressing Ctrl+Shift+Z (Windows) or Cmd+Shift+Z (Mac).

Renumbering and unnumbering sequence numbers

The Renumber/Unnumber function applies only to COBOL and will renumber the lines in the COBOL file. There is an option in preferences to control which columns will have sequence numbers inserted and removed. The user selects either columns 1-6, 73-80, or both. The numbering will start with 100 and increment each line by 100 while preserving non-numeric markers. This function equates to turning on the number mode in ISPF.

The COBOL Unnumber function will remove the line numbering in either columns 1-6, 73-80, or both while preserving non-numeric markers. This function equates to turning off the number mode in ISPF.

How to use it

To configure the preferences in the Z Open Editor Settings for which columns you would like to renumber and unnumber, modify your settings as follows.

1. Open your settings:

   • Windows: File > Preferences > Settings
   • Mac: Code > Preferences > Settings

2. In the left side of the opened Settings interface, expand Extensions from the list of categories, and click IBM Z Open Editor. In the IBM Z Open Editor settings, under COBOL: Sequence Numbers, click the dropdown menu to select a preference.

3. Click the appropriate option to specify the location of sequence numbers that are inserted and removed from a file by the Renumber and Unnumber editor actions. The options are as follows.

   • column-1: The sequence numbering begins at column 1, and will fill columns 1-6.
   • column-73: The sequence numbering begins at column 73, and will fill columns 73-80.
   • column-1-and-73: The sequence numbering begins at column 1 and 73, and will fill columns 1-6 and 73-80.

To number or renumber a COBOL file, right-click in the file in the editor and select the Renumber Sequence Numbers command. To unnumber the COBOL file, right-click in file in the editor and select the Unnumber Sequence Numbers command.

Commenting and uncommenting COBOL code

You can comment and uncomment COBOL code by using the keyboard shortcut. This method works for both single-line comments and multi-line block comments.

How to use it

To comment COBOL code:

1. In a COBOL file, place your cursor where you want to add a single-line comment, or click and select the code or text where you want to comment out a code block.
2. Press Ctrl+/ (Windows) or Cmd+/ (Mac).

To uncomment COBOL code:

1. Select the code that is currently commented out.
2. Press Ctrl+/ (Windows) or Cmd+/ (Mac).

COBOL Code Folding

Code folding is a feature that allows users to show or hide logical sections of the COBOL source code, which makes it easier for users to focus on the code they are working on. Logical sections of COBOL source code include but not limited to DIVISION, SECTION, PARAGRAPH, IF, ELSE, WHEN, DO, DATA-ITEMS, and EXEC SQL/CICS statements.

How to use it

You can fold regions of COBOL source code using the folding icons in the gutter between the line numbers and line start. Move the mouse over the gutter and click to fold and unfold regions. Use Shift + Click on the folding icon to fold or unfold the region and all regions inside. For more detailed information about code folding, refer to the VS Code code folding documentation.

COBOL code folding is enabled by default. To disable it use the setting zopeneditor.cobol.enableCodeFolding.

PL/I Code Folding

Code folding is a feature that allows users to show or hide logical sections of the PL/I source code which makes it easier for users to focus on the code they are working on. Logical sections of PL/I source code include IF, ELSE, DO, SELECT, WHEN, OTHERWISE, PACKAGE, BEGIN, PROCEDURE and ON blocks.

How to use it

You can fold regions of PL/I source code using the folding icons in the gutter between the line numbers and line start. Move the mouse over the gutter and click to fold and unfold regions. Use Shift + Click on the folding icon to fold or unfold the region and all regions inside. For more detailed information about code folding, refer to the VS Code code folding documentation.

Commenting and uncommenting PL/I code

You can comment out one or multiple selected lines of code or a selected section of code by using the toggle comment function.

How to use it

To toggle comment for one or multiple selected lines of code, press Cmd+/ (Mac) or Ctrl+/ (Windows), or go to Edit > Toggle Line Comment.

To toggle comments for a selected section of code, press Option+Shift+A (Mac) or Alt+Shift+A (Windows), or go to Edit > Toggle Block Comment.

See the following example where we first toggle line comment on multiple selected lines, then toggle line comment on a single line, and finally toggle block comment on a selection: