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 .copyasm .macasm .bms .mac .dbd .mfs .pcb
REXX	rexx	.rexx
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 for local files 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

Using the Z Open Editor datasets setting

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"
],

Using the VS Code files.associations setting

Alternatively, you can directly specify an array of associations native to VS Code instead of using the "zopeneditor.dataset" property above, which computes the VS Code associations for you.

The format for these mapping has changed since Z Open Editor v5 with Zowe Explorer v3. Data sets opened with Zowe Explorer are now opened in memory using the Zowe Explorer virtual filesystem. This file system has a different path structure for data set members than traditional file references. The path includes the Zowe profile name and begins with a Zowe resource-specific scheme. Additionally, instead of including the member in the filename, the member name is added as a new path segment (ex: zowe-ds:/rse/PDS.NAME/MEMBER).

The patterns in files.associations must be adjusted to account for this new format. **/*{QUALIFIER}*{,/*} will match to any sequential data set or data set member containing the provided qualifier. For example, these patterns match to the same data sets as above:

"files.associations": {
  "**/*COBOL*{,/*}": "cobol",
  "**/*COPY*{,/*}*": "cobol",
  "**/*PLI*{,/*}": "pl1",
  "**/*INCLUDE*{,/*}": "pl1",
  "**/*JCL*{,/*}": "jcl",
  "**/*ASM*{,/*}": "hlasm",
  "**/*REXX*{,/*}": "rexx",
  "**/*REXXINC*{,/*}": "rexx"
}

When you edit and save files opened with Zowe Explorer, the updated contents can be automatically written back to MVS when you save. You need to enable the ability to save back with the setting zopeneditor.zowe.readonlyRemoteIncludeFiles first. See section zopeneditor.zowe settings explained for details. When you quit the editor, Zowe Explorer will delete all temporary files for your source code security.

If you are still on Z Open Editor v4.x and Zowe Explorer v2 then data sets opened with Zowe Explorer will be downloaded to temporary, on-disk storage. For sequential data sets, the downloaded data set's filename will be the name of the dataset. For members, the format of the filename will be PDS.NAME(MEMBER). You can specify a data set qualifier with a leading and trailing asterisk as a glob pattern to match data sets containing that qualifier to a language. For example:

"files.associations": {
  "*.COBOL*": "cobol",
  "*.COPY*": "cobol",
  "*.PL1*": "pl1",
  "*.INCLUDE*": "pl1",
  "*.JCL*": "jcl",
  "*.ASM*": "hlasm",
  "*.REXX*": "rexx",
  "*.REXXINC*": "rexx"
}

# Setting file associations

# Local file associations

# Adding more file associations

# Removing file associations

# Defining include file associations

# Remote file associations

# Using the Z Open Editor datasets setting

# Using the VS Code files.associations setting