Making High Level Assembler code changes

In addition to COBOL and PL/I, IBM Z® Open Editor supports IBM Z High Level Assembler (HLASM) editing. You can use the following features to program in HLASM effectively.

With the syntax highlighting capability, you can quickly distinguish between labels, operations, operands, and comments in a HLASM program. With vertical rulers, which mark different areas, you can better determine correct areas for symbols, operations, operands, continuation line indicators, and sequence numbers.

The editor provides the following features and capabilities:

Browsing code by using the Outline view

You can use the Outline view to efficiently explore and browse the source code of a program. By looking through the items in this view, you can get an idea of what the program does at a high level and easily go to key instructions, branch labels, and symbols. We purposely chose not to include every symbol, because in large assembler programs, the Outline view often becomes extremely cluttered. For more information, see Customizing the Outline view.

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 expanded, you can open it by clicking View > Open view > Outline.

You can use this view to:

• Recognize the following instructions quickly through the icons:
  • CSECT
  • DSECT
  • RSECT
  • COM
  • LOCTR
  • MACRO
• Identify the following unique icons:
  • All labels used in a branch instruction
  • All labels, if enabled
• Go to a location that you want in the code by clicking that section header in the view.
• Sort by Position, Name, or Type.
• Search for identifiers by pressing Ctrl+Shift+O on Windows or Cmd+Shift+O on Mac in 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. To filter which icons to display in the Outline view, see Customizing the Outline view.

Code completion

When you are typing in an HLASM program, code completion provides you with a list from which you can select operations or labels depending on the current context. Currently, code completion for symbols works for symbols defined in the current file and copied files. Code completion for operations works for default (SYS1.MACLIB) macros, macros defined in the current file, and local custom macros.

When using code completion for instructions that have operands as well as macros with parameters, the HLASM language server will provide a snippet-style completion text that allows the user to use the tab key to modify and complete the operands or parameters as needed. See the following examples of operation and macro code completion.

How to use it

The code completion suggestion is displayed automatically while you are typing in an appropriate context.

Hovering for declaration

You can see hovers for operations and operands by moving your mouse cursor over the operation or operand.

How to use it

Operation and operand hovers are enabled by default. Simply move your mouse over an operation or operand. If the operand or operation is defined, a hover will appear.

Previewing copybooks

To preview the contents of a COPY statement move your mouse cursor over the copybook name. If the copybook cannot be resolved, a red error underline will appear on the copybook name. To open the file in a separate editor, press Ctrl+Click (Windows) or Cmd+Click (Mac).

How to use it

To resolve copybooks, 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 the 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.

Operations on symbols

When you double-click a symbol 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.

  

Remote macros

Macros in SYS1.MACLIB are available for code completion. In addition, if you configured Zowe Explorer to a z/OS MVS system that has a SYS1.MACLIB data set with a valid user z/OSMF or RSE API profile, you can preview remote macros in rich hovers. The tools will follow the same rules as for include file resolution, although no property groups need to be defined.

To enable the automatic lookup with your default Zowe CLI profile, go to Preferences > Settings, expand Extensions > IBM Z Open Editor and check the option Hlasm: Enable Resolving Macros. Additionally, you can adjust the lookup to use the z/OS 2.4, 2.5, or 3.1 version of SYS1.MACLIB using Hlasm: Zos Macros Version. This will ensure proper hover and code completion support for the macro set that you are using. See Setting preferences for more details on managing preferences.

If you do not have any connectivity, we recommend keeping this feature switched off; otherwise the editor will continue trying to resolve the file via your Zowe CLI profile.

If you want to use a different Zowe CLI profile than the default RSE API or z/OSMF profiles, specify the name of a different profile in the "zopeneditor.zowe" user setting. See the details in Setting up and using RSE profiles in IBM Z Open Editor.

Syntax checking

The syntax checking feature underlines unrecognized statements and expressions in red, which helps you to make quick corrections and reduce compile errors. Currently, there are syntax errors for improper spaces in a continuation line, unresolved copy statements, and an invalid number of operands.

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.

• Invalid number of operands

  This syntax error is currently supported for all machine instructions. Assembler instructions and macros are not currently supported.

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).

Commenting and uncommenting HLASM code

You can comment and uncomment HLASM 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 HLASM code:

1. In an HLASM 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 HLASM code:

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

Tracking progress when editing HLASM

The HLASM language server will report progress as it is parsing files. You will see this progress in the bottom toolbar as well as in notifications. If HLASM files are taking a while to load language functionality such as the outline view or hovers, this feature is helpful to see what is causing the slowdown. The stages of processing are:

• File parsing
• Retrieving and parsing copy members
• Retrieving SYS1.MACLIB macros (if enabled)
• Finding and retrieving local macros (with commercial features available)