Navigating in COBOL source files

The editors provide various ways to navigate to and from data items.

About this task

Supported Editors:

COBOL Editor
z Systems® LPEX Editor

Procedure

To navigate in a COBOL program from a data item reference in the PROCEDURE division to the data item declaration in the DATA division, do one of the following actions:
- Position the text cursor on the data item reference, and press the F3 key.
- Hold down the Ctrl key, position the text cursor on the data item reference, and click.
- Right-click the data item reference, and select Open Declaration.
In the COBOL Editor, if the declaration is in the same file as the reference, the editor navigates to the declaration in the same editor. If the declaration is in a collapsed region, the region is expanded. If the reference is in another file and the location of the file can be determined, the source file is opened in a new instance of the editor.
To jump to the editor location of your most recent text change, use the Last Edit Location (Ctrl+Q) action.
This action available for the COBOL Editor only.
To jump to the location of the next or previous Division, Section, or Paragraph. use the Go To Next Element (Ctrl+Shift+Down) and Go To Previous Element (Ctrl+Shift+Up) actions.
This action available for the COBOL Editor only.
To list all the occurrences of the selected language element in the Search view, use the Occurrences in Compilation Unit (Ctrl+Shift+U) action. Then, you can use the Next (Ctrl+.) and Previous (Ctrl+,) actions to jump to the location of the next or previous occurrences. To return the focus to the editor, press Enter.
When you use another view, such as the Outline, Search, or Perform Hierarchy views, a navigation history entry is created. To jump to the previous editor locations, use the Backward History (Alt+Left) and Forward History (Alt+Right) actions. You can also use the left arrow () icon to go back to a previous location and the right arrow () icon to move forward. These icons are in the menu bar.
To navigate the annotations in the editor, use the Next Annotation (Ctrl+.) and Previous Annotation (Ctrl+,) actions. The types of annotations visited by these actions can be configured by using the Annotations page. To access this preference click General > Editors > Text Editor > Annotations or use the menu on the toolbar.
This action available for the COBOL Editor only.
To navigate to the declaration of a language element, use the Open Declaration (F3) action. The action is also available in the editor menu, or as a hyperlink.
To open the copybook file that is referenced in a Copy Statement, use the Open Copybook action. The action is available in the editor menu, or as a hyperlink.
To open a program that is referenced in a CALL, EXEC CICS® LINK, or EXEC CICS XCTL Statement, use the Open Program action. The name of the program or file available to be opened is determined statically.
- If the name of the procedure of file cannot be determined statically, then these actions are not available.
- If the program is located within the same compilation unit, you can navigate to the program by using the Open Program action. Otherwise, you can use the Open File action to search for and open a file. The action is available in the editor menu, or as a hyperlink.

Viewing a COBOL program structure

Use the Open Perform Hierarchy action to see the structure of a COBOL program.

About this task

Results from Open Perform Hierarchy are available in the Perform Hierarchy view. The Perform Hierarchy view is a tree graphic that displays paragraph and line numbers for each statement in the hierarchy. By using this view, you can navigate among those statements as shown in the following graphic.

Each paragraph is identified by an icon (). The paragraph icon can contain decorators that provide more information about the paragraph.

: Indicates conditional processing.
: Indicates loop processing, such as self referencing GO TO statements.
: Indicates that an exception occurred.

Limitation: Changes to the control flow made by starting user-defined functions are not represented in this view.

Procedure

In the editor, select the element that you want to view.
Right-click the selection, and select Open Perform Hierarchy.
Click the Perform Hierarchy tab to see the results.
In the Perform Hierarchy view, you can choose these actions from the drop-down menu:
- Show the performer hierarchy or the performee hierarchy.
  
  Performer Hierarchy
  
  Displays all elements that can transfer control to the selection. For example, given the paragraph "Copy-input-to-output," the Performer Hierarchy displays all paragraphs and sections that can transfer control to that paragraph with a statement such as Perform Copy-input-to-output.
  
  Performee Hierarchy
  
  Displays all elements that are referenced from the selection. For example, given the Copy-input-to-output paragraph, the Performee Hierarchy displays a statement that can transfer control outside of the selection paragraph with statements such as Perform Read-next-input-data. Because perform hierarchies can be nested arbitrarily, the Perform Hierarchy is a tree view that you can use to traverse this hierarchy.
- Calculate fall-through. The Calculate Fall Through action provides a possible logic path that is based on potential fall through in paragraphs and sections. You might see false positives in the results.
- Filter the amount of information that is displayed. These filters are available:
  - Hide EXIT Paragraphs
  - Hide CALL statements
  - Hide STOP RUN statements
  - Hide GOBACK statements
  One or more filters can be selected concurrently. The filters work like a toggle switch; when a filter is on, a check mark is displayed next to the name. To clear the filter, click the filter name. The display changes dynamically when the filter is changed.

Examples

Following is an example of COBOL code with the performee highlighted:

* ****************************************************************************
* Utility method for copying input data from the input file to the output file
* ****************************************************************************
  Copy-input-to-output.
* Loop until end of file for input file
     Move "0" to Input-eof
     Perform until
             NOT inputfile-success OR
             NOT outputfile-success
         PERFORM  Read-next-input-data 
         IF inputfile-success
            PERFORM Write-output-data
         End-IF
         End-perform.
      Copy-input-to-output-EXIT.
         EXIT.

* *******************************************
* Utility method for reading from input file
* *******************************************
  Read-input-data.
*    Assume text to be read into Temp-data from IN-INTERNAL-FILE
     Move Spaces to Temp-data.

In the following example from the same COBOL program the performer is highlighted:

 Procedure DIVISION USING PARMS.
* Open the input and/or output files
     PERFORM Open-files.

* Process the user request

     EVALUATE ACTION
         WHEN DO-COPY-DATASET
             PERFORM  Copy-input-to-output. 
         WHEN OTHER
             CONTINUE.
     END-EVALUATE.
     MOVE IN-FILE-STATUS
          TO PARM-IN-FILE-STATUS.
     MOVE OUT-FILE-STATUS
          TO PARM-OUT-FILE-STATUS.
     MOVE IN-VSAM-CODE
          TO PARM-IN-VSAM-CODE.
     MOVE OUT-VSAM-CODE
          TO PARM-OUT-VSAM-CODE.
     PERFORM Close-files.
     goback.

* ***************************************************
* Utility method to open the input and/or output file
* ***************************************************
  Open-files.
* Open the input file
     OPEN I-O IN-INTERNAL-FILE

Using the COBOL Outline view

When you open a file in the editor, an outline of the file opens in the Outline view. In the Outline view, you can expand or collapse program divisions, show or hide parts of a program, or filter parts of a program.

About this task

The divisions in a COBOL program are identified by icons in the Outline view:

Icon	Outline element
	IDENTIFICATION DIVISION
	CONFIGURATION SECTION
	INPUT-OUTPUT SECTION
	DATA DIVISION
	FILE SECTION
	WORKING-STORAGE SECTION
	LOCAL-STORAGE SECTION
	LINKAGE SECTION
	REPORT SECTION
	PROCEDURE DIVISION
	FUNCTION
	DECLARATIVES
	PARENT DATA ELEMENT
	DATA ELEMENT
	SECTION
	PARAGRAPH
	COPY

Procedure

To expand the nodes in the Outline view, select Expand Outline from the drop-down menu. To collapse the outline to the nodes, select Collapse Outline from the menu.

To filter the program divisions in the Outline view, click one of the toolbar buttons at the top of the view. Click a button to activate the filter. Click it again to restore the outline view to its original state.

Option	Description
	Sorts sibling nodes in the outline in ascending order by name.
	Causes the outline view to show only the four divisions (identification division, environment division, data division, and procedure division) in programs. The content of the divisions is not shown.
	Hides nested programs in the outline view.
	Shows the data division contents in the outline view. The other divisions in the program are hidden.
	Shows the contents of the file section of the data division.
	Hides subordinate data items in the outline so that only level 1 data items are shown.
	Shows the contents of the procedure division in the outline, including sections and paragraphs in the procedure division. The identification division, data division, and environment division are hidden.

To hide parts of the program according to their name:
1. Select Filters from the drop-down menu.
  The COBOL Element Filters window opens.
2. Type a name pattern in the field.
  You can use the * and ? wildcard characters in the filter string. Separate multiple filter strings with commas.
3. Click Ignore case to match strings in upper, lower, or mixed case.
4. Click OK.
  The Outline view hides any program elements that match the filter strings entered.
5. To show any of these filtered elements, select Filters again, delete the filter strings from the field, and click OK.
To synchronize the editor with the Outline view, select Link with Editor from the drop-down menu.
When you place the cursor on a line in the editor, the Outline view expands to display the corresponding node. To disable this behavior, clear the Link with Editor option on the menu.
Note: When you select a node in the Outline view, the corresponding line in the editor is always shown. This action affects only the link from the editor to the Outline view. It does not affect the link from the Outline view to the editor.

Navigating a source file with quick outline

Open a quick outline to see the structure of COBOL, JCL, and PL/I files and navigate in files.

About this task

The quick outline opens on top of the COBOL Editor, JCL Editor, and PL/I Editor. It provides a view of the outline of a source file and tools for navigating in the file.

Procedure

To open the quick outline, click Navigate > Quick Outline or press Ctrl+O.
The quick outline opens on top of the editor. It contains a search filter and an outline of the content of the editor.
To filter the content of the quick outline, type the text that you want to show in the filter.
Elements that contain matching text and their ancestors are shown in the outline tree. The first matching element is selected in the outline.
To close the quick outline and navigate to the selected element in the source file, press Enter or double-click the element.