IBM Z® Open Editor

HLASM editing tutorial

About this tutorial

For the tutorial, you will assume the role of an HLASM developer who has received a requirement to enhance the output from ASAM1 to also write the hexedecimal value of a character string. The current version simply reads in a string from an input file, and writes the record number, column number headings, and the input string to an output file.

Prerequisites

Install IBM Z Open Editor and its prerequisites such as Java as described in Getting Started.

Procedure

  1. To enhance the report, you need to import the source code first.

    1. In VS Code, click Terminal > New Terminal to open a terminal.
    2. In the Terminal window, navigate to the desired directory for the source code by entering, for example, the following command:
      cd /c/Users/Public
    3. To clone the source code from the Git repository, enter the git repository of the sample files:
      git clone https://github.com/IBM/zopeneditor-sample.git
    4. After the clone is completed, click File > Open Folder. Then, in the Open Folder window, select the C:/Users/Public/zopeneditor-sample directory that you cloned, and click Select Folder.

  2. Review the source code.

    The current sample application consists of one HLASM program (ASAM1), one copybook (REGISTRS), two JCL members to set up and run the application (ASMALLOC, RUNASAM1), and the input data file (FILEIN).

    ASAM1 reads in the FILEIN data file record as a character string, and then simply writes out the string to the output file FILEOUT.

  3. (Optional) As you view the source in VS Code, you can use the Outline view to efficiently explore and navigate the code of the program. Note that the Outline view can be used only after you have opened a file or program in VS Code.

    If the Outline view is not already expanded, you can open it by clicking View > Open view > Outline. By looking through the items in this view, you can get an idea of what the program does at a high level.

    Note: ASAM1.asm is a simple program to use in the editing tutorial. To see a more robust Outline view, you can open the IRR@XACS.asm file, an example from SYS1.SAMPLIB. The IRR@XACS.asm file serves as a better example to demonstrate the the Outline view and its capabilities, and you can further explore it as follows:

    • Expand and collapse sections such as Dummy Sections (DSECT) and Control Sections (CSECT), and Macros in the Outline View.
    • Go to a desired location in the code by clicking that section header in the view.
    • Sort by Position, Name, or Type.
    • See Customizing the Outline view to configure what types of symbols to appear in the Outline view.

  4. (Optional) In the ASAM1.asm file, you will see code syntax highlighting in the opened file, which helps you quickly distinguish between HLASM reserved words, comments, constants, and variables.

    To see all the syntax errors in the open files, click View > Problems or click the error and warning icon at the bottom in the status bar. Click the list item to directly go to the problem.

  5. (Optional) Another visual feature of the editor is the grey lines that help with formatting as you code. You will notice the column 72 for the continuation character and the line at column 16 to show where a continued line can begin.

  6. Modify the code in the ASAM1.asm file to also write the hexedecimal value of a character string to the output. When you enter code, the code completion capability provides you with matching lists from which you can select commands, defined variables, and code snippets.

    For example, place your cursor at the end of line 40, and hit the Enter key to begin a new line on line 41. Try typing the command BALR, and as you type, you can select from the lists of code completion suggestions that appear. You will also see a pop-up that displays the name of the command and the format of the command. Delete the new line you just typed on line 41 and continue with the tutorial.

  7. (Optional) The hover feature works on variables and copybooks. You can hover over a variable to see its definition. You can hover over a copybook after configuring your ZAPP file and the editor will resolve it and display it in a pop-up window. After the copybook is opened, you can press Ctrl+Click on Windows or Cmd+Click on Mac to open the copybook in an editor window. Alternatively, you can use F12 or right click the copybook and select Go to Definition. Copybook resolution is based on ZAPP file property groups.

  8. (Optional) The editor can show you all references of a variable or section in your code. When you double-click a variable or section name to highlight the entire name and then right-click it, you can see the following available actions:

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

      A Results References view is displayed 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 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.

  9. Examine your code to analyze the impact of the requirement you received to determine the modifications needed. As you are to modify ASAM1, you need to search for all components that refer to the program.

    To search for components referencing ASAM1, you can use the advanced search capabilities provided by the VS Code editor. Its Search view allows searching for strings and regular expressions across all files or a specific subset of files based on location or name patterns.

    In the Explorer view, right-click in the background of the zopeneditor-sample, not showing any particular file or folder to initiate a search on all files:

    1. Select Find in Folder...

    2. Input the search term ASAM1 and press Enter.

      You can review some of the other search options such as using regular expressions and specifying patterns for files and folders to be excluded or included in the search.

      For example, to perform a regular expression search, select the .* icon and change the search term to ASAM1.* and review the results. Results will appear in the Search panel.

    3. Click on the result to navigate to that location file in the Editor panel.

  10. Open the integrated Git in VS Code, and create an isolated branch called write-hex-value, where no one but yourself can access the source code before you push the changes to the origin repository.

    To create the branch:

    1. In VS Code on the lower left hand corner, click create branch.
    2. Then, from the drop-down menu that is displayed at the top of VS Code, click Create new branch.
    3. Specify a branch name of write-hex-value, and then press enter to confirm. The workspace is switched to the isolated write-hex-value branch now.

  11. Commit your changes into your write-hex-value branch.

    Now that you have performed various code changes and refinements you can commit this file version of the application to the SCM to preserve and share it.

    To commit your changes, click the Source Control icon on the left of VS Code. In the Source Control panel that opens, the changed program is listed in the CHANGES section. In the CHANGES section, hover on the ASAM1.asm program name and click the Stage changes (+) icon to move your changes to the staging area. In the Message text box, enter a comment for the changes such as Implemented Hex Value, and then click the Commit icon to commit your changes.

  12. (Optional) Z Open Editor also supports custom macros for HLASM as an advanced feature. You can hover over a macro after configuring your ZAPP file and the editor will resolve it and display it in a pop-up window. After the macro is opened, you can press Ctrl+Click on Windows or Cmd+Click on Mac to open the macro in an editor window. Alternatively, you can use F12 or right click the macro and select Go to Definition . See Custom Macros for HLASM for more information. To see an example of custom macros working in the zopeneditor-sample repository, follow these steps:

    1. Change your branch to wazi-main.
    2. Open the zapp.yaml in the root of the workspace. There is an entry for a library named maclib.
    3. Open /ASM/MASAM1.asm.
    4. Scroll throughout the program and notice the various custom macros that are used. Key macros to look for: MCLOSE, MOPEN, MPUT, MGET, and REGS.

Congratulations on completing the tutorial. For a more comprehensive list of the available features for code editing, see Making code changes.

Last Updated:
Contributors: Shi Kun Li, Peter Haumer, Peter Haumer, Saile Daimwood, Chun Hong Zheng, Hestia Zhang