Getting started with the HLASM Editor

Edit online

The HLASM Editor shares common behavior with the other Eclipse language editors, but also provides language-specific enhancements such as syntax highlighting and content assistance. To open a file in the HLASM Editor, right-click and select Open With > HLASM Editor.

To set the HLASM Editor as the default editor for specific file types, open the Preferences window and click General > Editors > File Associations.
To set the HLASM Editor as the default editor for all file types defined in the HLASM Source File content type, do these steps:
  1. Open the Preferences window and click General > Content Types.
  2. Expand Text and then select HLASM Source file.
  3. In the Associated editors list, select HLASM Editor, and then click Default.

When you make this association, you can double-click a file to open it in the HLASM Editor.

If one of the following conditions is true, the file opens in read-only mode:
  • If you open an MVS file that is locked on the MVS Files subsystem, the editor opens it in read-only mode and issues a locked file warning. A file might be locked because it is already open by another user or process.
  • If an MVS file contains characters that cannot be correctly converted from one encoding (code page) to another and then back to the original encoding, the file is opened in read-only mode and the characters that cannot be converted correctly are highlighted.
  • If the Browse action is used to open the file.
Note: Saving an MVS file when some of the line lengths exceed the record length limit opens a file truncation warning. Continuing with the save results in truncated lines.

Supported features

For a complete list of the editing features supported by the HLASM Editor, see Features of language editors. The following is a brief description of supported features. For more information, click the links in this list
Content assist
The content assist feature suggests symbols, instructions, default macros that are defined in SYS1.MACLIB, and local custom macros appropriate to the cursor location in the editor. To open content assist, press Ctrl+Spacebar.
Content assist
Find references
The Find References action in the editor locates occurrences of selected language elements. When you select an element in the code, other instances are displayed in the Search results view and highlighted in the editor.
Find references
Hover help
Hover help is available for symbols, instructions, copy members, default macros that are defined in SYS1.MACLIB, local macros defined in a local property group, and custom macros that are defined in the program.
Hover help
Outline view
When you open a file in the editor, an outline of the file opens in the Outline view. Click an item in the view to locate it in the editor. 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 see the internal routines, and directly navigate to one by selecting it. These elements are included in the outline view: macros, CSECTs, DSECTs, RSECTs, COMs, LOCTRs, branch targets, and symbol names.
Outline view
Open declaration
Opens a link to the source file where a symbol, copy member, or default macro is defined; or to the location where a custom macro in the Assembler program is defined.
Real-time syntax checking
Real-time syntax checking automatically validates the syntax of HLASM code and displays error information in the editor margin. Support for real-time syntax checking is limited. For more information about the limitations, see Real-time syntax checking.
Real-time syntax checking
Syntax coloring
The editor displays different language elements in different colors. Syntax coloring is not configurable.
Syntax coloring in the HLASM Editor

Customizing the editor

To customize the HLASM Editor to suit your preference, see Setting HLASM Editor preferences.

Editing toolbar

You can access several editing tools by using the editing toolbar:

  • Toggle block selection mode Toggle Block Selection Mode enables block selection of text. Enabling block selection changes the editor font to a fixed-width font.
  • Show white-space characters Show Whitespace Characters displays a small dot for white-space characters and a paragraph mark for end-of-line markers.

Shortcut keys

For a list of shortcut keys for the editor, click Help > Show Active Key Bindings or press Ctrl+Shift+L (on Windows) or Mac icon+Shift+L (on macOS).

Status bar

The status bar at the bottom of the workspace provides the following information about files that are open in the editor:
  • The read/write indicator displays Writable or Read-Only.
  • The edit mode indicator displays Insert or "Overwrite".
  • The line:column indicator displays the line and column position of the edit cursor.

Limitations

The following list contains the general limitations of the HLASM Editor. To see limitations specific to individual features, refer to the corresponding HLASM Editor help topic.
  • No support for embedded languages
  • No support for the rename function
  • No support during debug sessions or in code coverage reports
  • If the file you are editing is large or the property group that is associated with it defines a large number of copy libraries, the performance of content assistance and hover help might be affected.
  • The Outline view supports macros that are defined in the Assembler program and local custom macros. Calls to the default SYS1.MACLIB macros are not displayed in the Outline view.
  • Syntax highlighting does not correctly highlight code in these situations:
    • Multiline strings
    • Continuation lines if they do not begin at column 16
    • Noncontinuation lines that begin at column 16
    • Does not recognize continuation lines that begin at column 17 or beyond as comments
  • Reporting of syntax errors is limited. Undeclared variables, for example, do not generate errors.
  • For files that are opened from the Git Repositories view, but not contained in an Eclipse project, the HLASM Editor has these limitations:
    • Syntax errors show in the editor, but the Problems view is not populated.
    • The Outline view is not populated.
  • The syntax error messages are in English, and are not translatable.
  • Although the toolbar includes a Real Time Syntax Checking Real Time Syntax Checking button, it has no function. Use the Disable problems check box on the HLASM Editor preferences page to enable and disable real-time syntax checking.
  • The Open Declaration action can locate symbols that are declared in the current file or in a copy member, but symbols that are declared in macros are not supported.
  • Block commenting is not supported.
  • If you use the Generate ZAPP command for property groups that define macro libraries in either local or remote Assembler files, the macro library definitions are not saved to the ZAPP file.
  • You might receive the error java.io.UncheckedIOException: java.net.BindException: Address already in use: bind in the error log of your workspace. This error is caused by a known LSP4E issue. To work around this issue, kill all java processes and restart the product.
  • If the file you are editing has references to many default macros defined in SYS1.MACLIB, you might experience these issues:
    • Performance problems with the editor.
    • The Outline view might not be displayed.
    • Local macros may not be displayed in the Outline view.
    To resolve these issues, try clearing the Enable resolving macros from SYS1.MACLIB preference and reopening the Assembler file. To locate this preference, open the Preferences window and navigate to HLASM > Editor.
  • If a property group is configured with a local custom macro directory and the macro library is removed from the property group that is associated with an assembler file, the IDz workspace may hang when the assembler file is opened.
    Workaround: Add the macro library to the property group again.
The following functions available for HLASM files in the z Systems LPEX Editor are not supported in the HLASM Editor. This list is not comprehensive.
  • Autosave
  • Block commenting
  • Build errors in the Remote Error List
  • Certain syntax errors, such as unknown instructions, missing labels on branch statements, and tab characters
  • Custom comment handling
  • Remote custom macro support
  • Customized commands for the editor context menu
  • ISPF editor commands
  • JCL Submit command
  • Line break conversions
  • Maintaining column alignment for DBCS editing
  • Nesting display
  • Outline elements from copy members
  • Outline filtering
  • Sequence number support
  • Task tags
  • Templates