Setting file associations

For local files, IBM Z Open Editor identifies the language of a file opened in the editor based on file extensions in both the default and customized files.associations user settings. This also applies to the include files by using a different user setting; zopeneditor.<language-id>.includeFileExtensions.

For remote files, as MVS data sets do not have file extensions, IBM Z Open Editor uses zopeneditor.datasets.<language-id>Datasets user settings to configure the editor for MVS data sets.

Local file associations

Adding more file associations

IBM Z Open Editor registers itself in VS Code with support for several languages. For each language, it also defines a set of file extensions that by default will be mapped to the registered languages as shown in the table below.

Language	VS Code Language ID	Default File Extensions
Enterprise COBOL	cobol	.cbl .cpy .cob .copy .copybook .cobol .cobcopy
Enterprise PL/I	pl1	.pli .pl1 .pc .pci .plinc .pcx .inc .include
Z High Level Assembler	hlasm	.s .assemble .asm .hla .hlasm
REXX	rexx	.rexx .rex
JCL	jcl	.jcl .cntl .proc

Table 1. IBM Z Open Editor default mapping of languages and file extensions

When you open a file with one of these file extensions in Z Open Editor, then VS Code displays the mapped language in the language selector on the lower-right of the status bar. If you want to temporarily switch the opened editor to any other language available in VS Code, click this bar and enter the wanted language.

If you want to use a file extension in addition to the defaults for any of these languages, you must define them yourself in the user or workspace settings by using either of the following approaches.

Option 1: Using the VS Code Preferences UI
1. Click File > Preference > Settings and switch to either User or Workspace settings.
  Tip: Switch to Workspace settings if you want to define the mappings locally to the current project and store it in SCM with your programs.
2. In the Search bar at the top type associations. It brings up the VS Code Files: Associations setting, which contains a list of the current non-default file associations defined.
  Note: The default associations that are shown in Table 1 are not listed here because they cannot be changed.
3. Click the Add Item button to add another entry. It prompts for a Key, which is the file extension starting with the symbols *. such as *.cp1 and a Value entry that is the language identifier as listed in Table 1.
Option 2: Editing the settings.json file
As an alternative to using the VS Code Preferences UI, you can also edit the JSON file of the user or workspace settings. The format is:
```
"files.associations": {
    "*.cp1": "cobol"
}
```
1
2
3
You can enter a full glob pattern as keys. With such flexible glob patterns, you can map files to a language by using file extensions and arbitrary substring mappings.

Removing file associations

If you remove some of the entries there that were added by IBM Z Open Editor at startup, such as "*.COBOL*": "cobol",, and save, they might reappear afterward. To prevent that see the details below on managing remote file associations that cause this behavior.

Before you be able to remove any of the mappings from the files.associations, you must remove them first from the Datasets settings and Include File Extensions settings first. The reason is that IBM Z Open Editor tries to automatically add these two settings into files.associations to support its features.

Defining include file associations

The include files can be on the local file system or located in remote MVS data sets. After you define property groups to tell IBM Z Open Editor where to look for include files such as COBOL copybooks, for the include files that are stored locally, you must define the default file extensions to identify a valid include file for each language. Without a valid file extension, IBM Z Open Editor cannot find include files and cannot open them correctly for editing.

You can customize your own file extensions by using either of the following approaches.

Option 1: Using the VS Code Preferences UI
1. Click File > Preference > Settings and switch to either User or Workspace settings.
  Tip: Switch to Workspace settings if you want to define the mappings locally to the current project and store it in SCM with your programs.
2. On the left of Settings editor expand the Extensions group and select the entry IBM Z Open Editor.
3. Scroll on the right to see all the different Z Open Editor settings available. There are three settings available for configuring include file extensions:
  - Cobol: Include File Extensions
  - Hlasm: Include File Extensions
  - Pl1: Include File Extensions
  - Rexx: Include File Extensions
  Each shows a list of the currently registered file extensions populated with a set of defaults.
4. Click the Add Item button and enter the extension with a leading dot-character such as .cp1.
5. Click the OK button to save it. You will see that your new extension has also been added automatically to the files.associations setting, which is discussed in file associations.
6. If you remove an extension from the list, IBM Z Open Editor will not currently remove it from the files.associations however. You need to remove it there yourself.
Option 2: Editing the settings.json file
As an alternative to using the VS Code Preferences UI, you can also edit the following properties in the JSON file of the user or workspace settings.
- zopeneditor.cobol.includeFileExtensions
- zopeneditor.hlasm.includeFileExtensions
- zopeneditor.pl1.includeFileExtensions
- zopeneditor.rexx.includeFileExtensions
An example could be the following that adds .mac and .cpysrc to the default set of HLASM include file extensions:
```
"zopeneditor.hlasm.includeFileExtensions": [
  ".s",
  ".assemble",
  ".asm",
  ".hlasm",
  ".hla",
  ".mac",
  ".cpysrc"
]
```
1
2
3
4
5
6
7
8
9

Once configured, IBM Z Open Editor can find include files with these new extensions in the locations as specified in property groups. When you open these files, they can be correctly opened in the editor as include files for the assigned language. This also means for COBOL and PL/I the files will be correctly parsed as include files rather than full program files. See here for more details on the specific differences.

Remote file associations

IBM Z Open Editor integrates with and provides advanced capabilities for Zowe Explorer to edit program files from remote z/OS locations. You can, for example, find your COBOL programs in Zowe Explorer's MVS explorer and the open them directly from there for editing in IBM Z Open Editor. However, MVS data sets do not have file extensions, which are essential for VS Code to identify the language of file opened in the editor. Therefore, IBM Z Open Editor uses zopeneditor.datasets settings to configure the editor for MVS.

Within the family of zopeneditor.datasets VS Code settings defined by IBM Z Open Editor, you can specify name patterns for MVS data sets that are expected to contain COBOL, PL/I, or HLASM programs, copybooks, include files, and JCL. After configuration, when you open members of these data sets by using Zowe Explorer in the editor, they are considered the designated type of file. IBM Z Open Editor recognized file types by mapping your customized zopeneditor.datasets settings to VS Code files.associations settings.

You can edit the name patterns for MVS data sets by using either of the following approaches:

Option 1: Using the VS Code Preferences UI
1. Click File > Preference > Settings and switch to either User or Workspace settings.
  Tip: Switch to Workspace settings if you want to define the mappings locally to the current project and store it in SCM with your programs.
2. On the left of Settings editor expand the Extensions group and select the entry IBM Z Open Editor.
3. Scroll on the right to see all the IBM Z Open Editor settings available. There are four settings available for configuring data set names:
  - Datasets: Cobol Datasets
  - Datasets: Hlasm Datasets
  - Datasets: Jcl Datasets
  - Datasets: Pl1 Datasets
  - Datasets: Rexx Datasets
  Each shows a list of the currently registered names populated with a set of defaults.
4. Click the Add Item button to add new name pattern to the list.
  Tip: As you see in the list of defaults, it is a good idea to include dots to make the mappings to MVS data set names less ambiguous.
5. Click the OK button to save it. You will see that your new name has also been added with an additional * wildcard at the end automatically to the files.associations setting, which is discussed in file associations.
6. If you remove an entry from the list, IBM Z Open Editor will not currently remove it from the files.associations however. You need to remove it there yourself afterward.
Option 2: Editing the settings.json file
As an alternative to using the VS Code Preferences UI, you can also edit the family of zopeneditor.dataset properties in the JSON file of the user or workspace settings.

After editing the settings file, when you open any member of IBMUSER.SAMPLE.COBOL in MVS, the content will open in a COBOL editor. The same process applies to PL/I, HLASM, REXX, and JCL files. These are the default values that you can customize in the settings:

"zopeneditor.datasets.cobolDatasets": [
    ".COBOL",
    ".COB",
    ".COBCOPY",
    ".COPYBOOK",
    ".COPY"
],
"zopeneditor.datasets.jclDatasets": [
    ".JCL"
],
"zopeneditor.datasets.pl1Datasets": [
    ".PL1",
    ".PLI",
    ".INC",
    ".INCLUDE"
],
"zopeneditor.datasets.hlasmDatasets": [
    ".ASM",
    ".ASSEMBLE",
    ".HLASM",
    ".HLA",
    ".MACLIB"
],
"zopeneditor.datasets.rexxDatasets": [
    ".EXEC",
    ".REXX",
    ".REXXINC"
],

Alternatively, you can directly specify an array of associations instead of using the "zopeneditor.dataset" property above. For example,

"files.associations": {
  "*.COBOL*": "cobol",
  "*.COB*": "cobol",
  "*.COBCOPY*": "cobol",
  "*.COPYBOOK*": "cobol",
  "*.COPY*": "cobol",
  "*.PL1*": "pl1",
  "*.PLI*": "pl1",
  "*.INC*": "pl1",
  "*.INCLUDE*": "pl1",
  "*.JCL*": "jcl",
  "*.ASM*": "hlasm",
  "*.EXEC*": "rexx",
  "*.REXX*": "rexx",
  "*.REXXINC*": "rexx"
}

Again, if you prefer COPYBOOK data sets be opened as hlasm data sets, you can designate that in this setting.

The resulting behavior for Zowe Explorer is now that using these settings, you can navigate to an MVS data set that matches these patterns and select a member, which is then opened in Z Open Editor in the mapped language. To achieve that Zowe Explorer downloads the file into a temporary directory that contains the mapped data set name pattern as well and opens it in the correct language, because of the files.associations mapping pattern. When you save these local files with changes Zowe Explorer will automatically write them back to MVS. When you quit the editor then Zowe Explorer will delete all temporary files for you source code security.

# Setting file associations

# Local file associations

# Adding more file associations

# Removing file associations