Setting HLASM Parser preferences

Use the HLASM Parser preference page to specify options for editing High Level Assembler files in the z Systems LPEX Editor.

To set the HLASM parser preferences:

1. In the Preferences window, navigate to LPEX Editor > z Systems LPEX Editor > HLASM Parser.
2. In the Initial LPEX Commands section:
   1. Type the editor command that you want to run each time the HLASM parser opens a file. For example, if you define a custom color instruction file that you want all files to use, you can add a command called setCustomColoring on to the list of editor commands that are run each time the parser opens a file.
      Commands are run when a file is opened in the HLASM parser.
   2. Click Add to add the command to the list of editor commands.
   3. Optional. To edit a command in the list of editor commands, do the following actions:
      1. From the list of editor commands, select the command that you want to edit, and then click Edit Command to open the Edit Command dialog box.
      2. Modify the selected editor command, and then click OK to save your changes and close the dialog box. The modified command appears in the list of editor commands.
   4. Optional. To remove a command from the list of editor commands, select the command that you want to remove and click Remove. The selected command is removed from the list of editor commands.
   5. To change the order of the commands in the editor command list, select a command that you want to move, and then click Move Up or Move Down to change its position within the list of commands.
      The commands are run in the order that they appear in the editor command list.

      Note: For files in a z/OS® UNIX subproject, commands that are specified in the HLASM Parser preference page are run first, followed by any applicable commands set within the HLASM tab of the Editor Options preference page.
3. In the User Macro F1 Help Files section, specify a list of the user macro help files that store the help mapping for user macros:
   1. Click Add to open the Add Help File Location dialog box.
   2. Do one of the following actions:
      • Click the Use a manually created mapping file radio button. In the Mapping file field, type the name of the local or remote user macro help file that you want to use. You must specify the name using a fully qualified drive letter or UNC path. For example, \\HOSTNAME\MyFolder\my_macro_help.hlp. You can also specify the name of this file using environment variables. Enclose variable names using the % symbol. To browse for the location of the user macro help file that you want to use, click Browse.
      • Click the Generate index from an existing help table of contents radio button. In the Plug-in name field, type the name of the plug-in that contains your custom help. In the TOC file name field, type the name of the toc.xml file that you created for your custom macros.
        Note: The label attribute for each topic in the toc.xml file is used as the macro name and the href attribute is used as the associated help page. If a topic in the toc.xml file has a label attribute, but no href attribute, it is ignored. If there are spaces in the label attribute, it is also ignored and is not indexed. It is recommended that you specify labels in upper case since macro names are converted to upper case before any comparisons are made.
      • Click OK to close the dialog box.

      The location of the help file appears in the list of user macro help files.
   3. Repeat this procedure for each additional user macro help file that you want to add to the list of user macro help files.
      Tip: This list of files is cumulative; each help file contained in this list is searched when looking for a macro name. If more than one file contains the same macro name, the macro name in the first file is used. For example, if there are two help files in the list, and each file contains a mapping between the macro name MYMAC and an associated help page, the association contained in the first help file is used. If there are multiple instances of a macro name within the same help file, the last occurrence of the macro name in that file is used. For example, if a single help file contains multiple instances of the macro name MYMAC, the last occurrence of MYMAC in that file is used.
   Note: User macro help files can have any file name extension.

   If you modify the user macro help file and want to reload the file to reflect the changes, do one of the following actions:

   • Type the following command in any open editor using the modified macro file:

      reloadUserHelpFile

   • Right-click to open the pop-up menu, and then select Reload User Macro F1 Help Files.
   Note: For files in a z/OS UNIX subproject, if user macro helps files are already specified in the HLASM tab of the Editor Options preference page, those settings override any user macro helps files settings specified in the HLASM Parser preference page.
4. In the Autocomment section, complete the following steps:
   1. Select the Add autocomment to changed lines check box to specify that you want to add an autocomment to each line that you change while editing a file with the z Systems® LPEX Editor.
      When auto comment is invoked, the default language profile is used. The default language profile is set in the autocomment preference page.
   2. In the Base comment field, type the comment that you want to appear on each line that you change while editing a file with the z Systems LPEX Editor. For example, a defect number.
      You can use subproject level substitution variables; file level substitution variables are not supported.
      For example, &N, where the &N user variable represents the name of a z/OS UNIX subproject.
      Tip: If the base comment is set, but the file does not add a comment to changed lines, the base comment might not meet the criteria specified in the profile options. You can use the Autocomment preference page to view or change the autocomment profile options.
   Note: For z/OS UNIX subproject files, if autocomment settings are already specified in the HLASM tab of the Editor Options preference page, those settings override any autocomment settings specified in the HLASM Parser preference page.
5. To specify the macro file that stores the IBM®-supplied macro definitions, in the Base Macro File field, click Browse to navigate to the location of the macro file, or type the fully qualified name of the file by using a drive letter or UNC path. You can use environment variables such as %ENVVARS%\tpfhlasm.dat, where %ENVVARS% points to the location of the file. You can also specify a partitioned data set member or a sequential data set.
   If you modify the macro file and want to reload the file to reflect the changes, type the reloadTPFMacrosFile command in the editor command line or right-click in the editor and select Reload Base Macros File.
6. To specify a user macro file that stores user macro definitions:
   1. Create a user macro file with any file-name extension.
      You can use a user macro file to hide IBM shipped macros defined in the base macro file from the HLASM parser, and to have your own custom macro syntax recognized.
   2. In the User Macro File field, click Browse to navigate to the location of the macro file, or type the fully qualified path of the file, for example, \\HOSTNAME\MyFolder\my_macro_file.dat. You can use environment variables such as %ENVVARS%\tpfhlasm.dat, where %ENVVARS% points to the location of the file. You can also specify a partitioned data set member or a sequential data set.
   If you modify the user macro file and want to reload the file to reflect the changes, type the reloadUserMacrosFile command in the editor command line or right-click in the editor and select Reload User Macros File.

   Note: You can define the location of macro files in two locations: In a remote property group that is associated with a resource or on the HLASM Parser preference page. To define macro files for local assembler resources, you must use the HLASM Parser preference page. Macro file definitions in remote property groups take precedence over the macro definitions on the HLASM Parser preference page. If an Assembler resource has a remote property group associated with it, but the user macro file is not defined in the property group, then no user macro file is used.
7. To specify the custom instruction color file that stores data about how particular instructions must be colored in the HLASM parser, do one of the following actions:
   • In the Custom Instruction Color File field, type the name of the local or remote custom instruction color file that you want to use. You can specify the name of this file using environment variables and the UNC path.
   • Click Browse to browse for the location of the custom instruction color file that you want to use. This file must have a .xml file-name extension.
   Tip: Using the HLASM parser, you can set colors for instructions on an instruction-by-instruction basis. If you want to set colors for instructions based on instruction type (for example, machine instruction), you can use the LPEX Editor Parser Styles preference page. To set your coloring preference by instruction type, in the Preferences window, double-click the LPEX Editor node to open the list of available LPEX Editor preference pages. Double-click Parsers to open the Parsers page, and then click Parser Styles to open the Parser Styles page.

   To use the colors that you define in the Custom Instruction Color file, turn the custom coloring feature on for each file that uses the HLASM parser. You can turn this feature on using the setCustomColoring on command.

   Note: For files in a z/OS UNIX subproject, if a custom instruction color file is already specified in the HLASM tab of the Editor Options preference page, that setting overrides any custom instruction color file specified in the HLASM Parser preference page for files.
8. Click Edit to open the Custom Instruction Colors dialog box.
9. Edit the selected custom color instruction file. See the link below for details on how to edit custom instruction color files.
10. Specify the CICS® level that the parser should use for parsing and content assist on embedded CICS statements.
11. Click Apply to save your selections in the preference page. The preferences that you selected are applied to all files that use the HLASM parser.
    Tip: If you modify your HLASM parser preferences, Editor Options, or Property Group settings or add a file to a z/OS UNIX or MVS™ subproject and the file is already opened in z Systems LPEX Editor, the changes will not appear unless you close and reopen the file or run the updateProfile command to register any changes with the HLASM parser.