Navigating in PL/I source files

The z Systems® LPEX Editor, PL/I Editor, and PL/I Compare Editor provide various ways to navigate to and from variable declarations, even when a variable is declared in a different file.

Procedure

To navigate to and from variable declarations:

To navigate in a PL/I program from a variable or method name, perform one of the following actions:
- Position the text cursor on a field or paragraph name and press the F3 key.
- Hover the cursor over a variable or method name, hold down the Ctrl key, and click.
- Right-click the data item reference, and select Open Declaration from the menu.
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.
Hovering the cursor over a variable or procedure causes a hover information window to display details about the highlighted element. Hovering the cursor over this window causes a toolbar to be displayed. The toolbar contains a toolbar button for opening the declaration of the hovered element.
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 PL/I Editor only.
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 for the buttons on the toolbar.
This action is available for the PL/I Editor only.
To jump to the location of the next or previous Package or Procedure, use the Go To Next Element (Ctrl+Shift+Down) and Go To Previous Element (Ctrl+Shift+Up) actions.
This action available for the PL/I 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 visited by these navigation commands, 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 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 include file that is referenced in an Include Statement, use the Open Include File action. The action is available in the editor menu, or as a hyperlink.
To open a procedure that is referenced in a CALL, EXEC CICS® LINK, or EXEC CICS XCTL Statement, use the Open Procedure and Open File actions. The name of the procedure 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 procedure is located within the same compilation unit, you can navigate to the procedure by using the Open Procedure action. Otherwise, you can use the Open File action to search for and open a file. The name of the procedure or file available to be opened is determined statically. The action is available in the editor menu, or as a hyperlink.

Folding code blocks

When code folding is enabled, you can expand and collapse code blocks for IFELSE, IF, ELSE, DO, SELECT, WHEN, OTHERWISE, PACKAGE, BEGIN, and PROCEDURE statements.

Before you begin

Code folding is supported in the PL/I Editor only. It is disabled by default. To enable it:

Open the Preferences window.
Navigate to PL/I > Editor.
Select Enable folding of code blocks.

Limitation: Code folding does not work if a file contains parser errors or if tooling is disabled.

About this task

The following screen capture shows a block of text that is collapsed, marked by +, and one that is expanded, marked by -.

A code block that has only one line of code after the initial line cannot be folded, as in this example:

Using the PL/I Outline view

When you open a file in the editor, an outline of the file opens in the Outline view. The outline view can be updated to contain preprocessor statements after running the Source > Preprocessor Commands action. You can expand or collapse program divisions, show or hide parts of a program, or filter parts of a program by name.

About this task

The divisions in a PL/I program are identified by icons in the Outline view:

Icon	Outline element
	PROCEDURE or PROC
	ON
	REVERT
	LABEL
	DO, SELECT, and BEGIN statements
	Data item

When you open a file, the Outline view provides toolbar items and a menu for filtering the parts of a program. From this view, you can show or hide different parts of the program according to their division, expand and collapse the outline, and show or hide parts of the program according to their name.

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. When you place the cursor on a line in the editor, the outline expands or collapses the corresponding node.

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.
	Hides data items.
	Hides on-units.
	Hides labels.
	Hides includes.
	Hides statement blocks not containing data items.

To hide parts of the program according to their name:
1. Select Filters from the drop-down menu.
  The PL/I 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.

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.

Viewing a PL/I program structure

Use the Open Call Hierarchy action to see a tree-structure view of the procedure and function calls in a PL/I file.

About this task

The Call Hierarchy view is a tree graphic that displays functions and procedures. This view provides a way to navigate a large or complex PL/I file that contains many procedures and assists you with determining the call flow between the procedures. The Call Hierarchy view provides information from both a called and caller perspective.

There are two sections in the Call Hierarchy view,

The left column contains the tree structure of the specified function or procedure
The right column shows the line number for the code. When you click a node in the tree structure, the corresponding line number is displayed.

Restriction:

The Call Hierarchy function has several limitations:

Only static calls to procedures and functions are supported. Variable references to function names and procedure names are not supported.
Multiple labels for a single procedure or function definition are not supported.
Multiple entry points into a procedure are not supported.
Double-clicking a procedure name when the procedure definition is in an expanded macro source results in being taken to the macro call.

Procedure

In the editor, select the element that you want to view.
Right-click and click Open Call Hierarchy from the menu.
The Call Hierarchy view opens.

Navigating the Call Hierarchy view

Procedure

The Call Hierarchy view contains the following toolbar buttons for filtering the contents of the view.

Callee Hierarchy: Displays in the view only the procedures that called the highlighted procedure.
Caller Hierarchy: Displays in the view only the procedures that are called by the highlighted procedure.
View menu: Shows a list of functions to perform in the Call Hierarchy view. In addition to the Caller Hierarchy and Callee Hierarchy view, you can select to hide or show built in functions.