Setting property groups

Property groups are required to define how the COBOL, PL/I, HLASM, and REXX editors search for copybooks and/or includes when you edit a program. Without loading these the language servers used by Z Open Editor will not be able to parse the programs correctly and show many syntax errors that are due to the missing definitions contained in these files. Property Groups can also be used to specify language-specific compiler options.

To define a property group in your ZAPP file, you can use the VS Code snippets provided by Z Open Editor and then fill in the details. Specify if the file is a syslib include file or part of a library, then provide an array of potential local or remote locations to search in. These locations can be absolute, relative, or GLOB file patterns for a local directory path or MVS data set names to be searched on your z/OS system.

Here is an example for a COBOL property group from a ZAPP file that defines a local search path for copybooks as well as remote and local location for library files. All these location will be search in oder top-down:

propertyGroups:
  - name: cobol-copybooks
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "**/COPYBOOK"
          - "projectA/copy"
      - name: MYLIB
        type: mvs
        locations:
          - IBMUSER.SAMPLE.COPYLIB
      - name: MYLIB
        type: local
        locations:
          - "**/COPYLIB"

Z Open Editor watches all the folders that match to locations of the type "local" on your development machine. If files in these folders are changed, added, or deleted, Z Open Editor will re-evaluate based on that change. For example, if the editor has an opened program that finds an included COBOL copybook in the local folder that matches the "projectA/copy" location in the snippet above and finds that copybook was deleted, then the editor will try searching for this copybook in other locations immediately. The editor will do this again in the given order top-down. It might then find the copybook in the "mvs" location "IBMUSER.SAMPLE.COPYLIB" and load and use that version of the copybook instead.

This next example defines a property group for PL/I with a typical compiler option to be used to map the EBCDIC NOT symbol, which does not exist in ASCII, to a common character usable in VS Code:

- name: pl1-includes
  language: pl1
  compilerOptions: "not(!),margins(2,100)"
  libraries:
    - name: syslib
      type: local
      locations:
        - "**/INCLUDES"

As you can see in the examples above, you need to specify a unique name for each property group, which is the only mandatory property. The name can help with troubleshooting as the VS Code output view shows information about which property groups are being searched and in what order.

The sections below explain in-depth how to fully leverage certain properties within a property group object.

Language scoping

You can optionally define a property group scoped to a specific enterprise language in case you have applications that utilize multiple languages. Use Ctrl+Space (Windows and Mac) in the VS Code editor to see the list of valid language values, which currently includes cobol, pl1, hlasm, rexx, and jcl.

When you specify a language, you can also define compiler options that impact the editor. For example, you can specify PL/I codepage options of mapping special characters to operators, such as a ! character to the NOT operator, as seen in the example above. Another use case would be to specify the margins to be used for your PL/I programs. As shown in the property group example pl1-includes above, multiple options should be listed in one string separated by commas. If you have more than one property group for a language, the compilerOptions strings will be concatenated. Note that the options apply globally to all files that open in that language within the scope of your workspace. Therefore, it is valid to add a property group specifically for defining global compiler options, which could consist simply of the name, language, and compilerOptions properties. For more details, see Setting compiler options page.

Syslib and libraries

Syslib

Use the name syslib for a libraries item in a ZAPP property group to resolve the following types of statements:

• COPY <COPYBOOK_NAME> (COBOL and HLASM)
• %INCLUDE <INCLUDE_NAME> (PL/I)
• /*%INCLUDE <INCLUDE_NAME> */ (REXX)

For the value of locations, provide an array of directory path names (for local property groups) or data set names (for mvs property groups) for IBM Z Open Editor to find includes. You can provide multiple paths to resolve includes in different folders. For local libraries items, you can specify a path relative to the workspace in which the ZAPP file is located or an absolute path on your development machine.

Libraries

Use a custom name for a libraries item setting to resolve the following types of statements (substitute <LIBRARY_NAME> with the name you specify for te item):

• COPY <COPYBOOK_NAME> IN <LIBRARY_NAME> (COBOL)
• %INCLUDE <LIBRARY_NAME> (<INCLUDE_NAME>) (PL/I)
• /*%INCLUDE <LIBRARY_NAME>(<INCLUDE_NAME>) */ (REXX)

You can provide multiple library items within the libraries array of a property group. Each library item in the libraries array consists of the following properties:

• The name property must match the library name used in the program. For example, to resolve the library reference in the COBOL statement COPY COPYFILE IN MYLIB, the value of name must be "MYLIB".
• The type property can be either local or mvs specifying if the locations provided are local search path entires or MVS data sets.
• The locations property is an array of either directory or data set names for the associated library name.

MVS property groups using Zowe profiles

If you have Zowe CLI or Zowe Explorer configured on your development machine, libraries items of type mvs will try to resolve copybooks referenced in COBOL programs using your Zowe RSE or z/OSMF service profiles. We cover the details for how to define such profiles in Setting up integrations to interact with z/OS.

Once you have created such a profile that has direct access to the MVS data sets listed in the property groups, the COBOL editor will try to look for copybooks in the syslib and library locations provided. During MVS remote file resolving, IBM Z Open Editor employs an MVS connection test that validates the authentication method being used (Figure 1). If a JWT is not located in the service profile or base profile, then basic authentication with username and password will be attempted.

• If the username and password are not saved in the profile, IBM Z Open Editor will prompt you for credentials.
• In the event that a 401: Not Authorized error message is returned from the MVS connection test, IBM Z Open Editor prompts you with an option to update your credentials for the remainder of your IDE session. Cancelling the credential update will turn off MVS remote file resolving for the duration of your IDE session or until you refresh the profile status via the command palette option IBM Z Open Editor: Reload Zowe Profiles. If you choose to update your credentials, you will also have the option to save them to the profile's local file for future use.

Figure 1: MVS connection test flow chart

If you have defined multiple Zowe profiles of the types zosmf or rse, then the editor will use so-called default profiles to determine which of your profiles to use. If you want the editor to pick a different profile instead, you can specify the profile in the User Settings.

IBM Z Open Editor will by default follow these precedence rules to identify which Zowe profile to use:

1. Use the profile specified by the zopeneditor.zowe user setting.
2. If the profile above is not defined, then use the default RSE profile if available.
3. If the default RSE profile is not available, then use the default z/OSMF profile if available. If the default z/OSMF profile is not defined, errors are shown.

The format of the zopeneditor.zowe user setting is as follows:

"zopeneditor.zowe": {
  "defaultCliProfile": "mySandbox.rseapi",
  "defaultSshCliProfile": "mySandbox.ssh",
  "listBeforeDownload": false,
  "maximumParallelFileDownloads": 5,
  "defaultRseConversionMappingsFile": "~/wazi-sample/zapp.yaml"
}

These settings can also be edited using this table in the graphical Settings editor:

The value of defaultCliProfile is the name of the Zowe RSE or z/OSMF profile that you want to use. In the preceding example, it is mySandbox.rseapi. If you cannot remember the names, you can run the following commands to get the list of all your profiles and your default profile:

• List RSE profiles: zowe profiles list rse
• List z/OSMF profiles: zowe profiles list zosmf

You can check the profile that was specified. If no specified profile, the Zowe CLI default profile is used by Z Open Editor in the VS Code status bar. You can find the name and type of the currently active Zowe CLI profile in the lower right of the editor window.

In the previous example, you can also see the following settings:

• The setting defaultRseConversionMappingsFile is discussed in detail in the MVS EBCDIC code pages and mappings files help section.
• The boolean setting listBeforeDownload modifies Z Open Editor's behavior when requesting a file from MVS:
  • When the setting is set to true, the editor will first try to confirm that whether the requested file actually exists by performing a list operation for that file. If the requested file exists, the editor will send another request to download it. If the requested file does not exist, the editor will move on to test the next location listed in the property group.
  • When the setting is set to false, the editor will directly try to download the file from MVS without checking whether it actually exists. If the response from z/OS is a Not Found error, the editor will move on to the next location listed in the property group. In some cases when using z/OSMF as the protocol, this Not Found error will cause entries in z/OS log files, which you can avoid by specifying the value of the setting to true. However, this extra round-trip to the server to check the existence will have performance impact. Because the logging is not an issue when using the RSE API protocol and because of the performance advantage, the default value for this setting is false.
• The integer setting maximumParallelFileDownloads can be used to specify how many parallel downloads Z Open Editor should perform when requesting include files from MVS. Downloading several files in parallel can significantly improve performance, especially when you edit programs with many include files. The downside is that some protocols such as z/OSMF will allocate more address spaces for the parallel requests, which causes more resources being used and more logging on the z/OS side. The RSE API protocol does not have that problem because it achieves scalability in other ways that are documented in the RSE documentation. The default value for this setting is 5, and the maximum value is 10. Set it to 1 to disable parallel downloads requesting one include file at the time.

Setting IBM Z Open Editor property groups using glob patterns, relative path, and absolute path (Local files only)

IBM Z Open Editor supports glob patterns, relative path patterns, and absolute path patterns for local files in order to provide locations items. Below are some examples about adding property groups using glob patterns, relative path, and absolute path for local files. Note, that currently there is no wildcard support for MVS data set names. These have to match exactly.

Glob patterns

Glob patterns can have the following syntax:

• ? to match on one character in a path segment
• * to match one or more characters in a path segment
• ** to match any number of path segments.

Refer to minimatch glob patterns documentation for more information.

An example using basic glob patterns for Windows and Mac:

propertyGroups:
- name: cobol-copybooks
  language: cobol
  libraries:
    - name: syslib
      type: local
      locations:
        - "zopeneditor-sample/**",
        - "zopeneditor-sample/**/COPYFILES"
    - name: MYFILE
      type: local
      locations:
        - "zopeneditor-sample/**/COPY*",
        - "zopeneditor-sample/**/INCLUD?LIB"

Some things to note:

• Windows: Only use forward slashes (/) in glob expressions. Though windows uses either / or \ as its path separator, only / characters are used by this glob implementation. You must use only forward slashes in glob expressions. Backslashes will always be interpreted as escape characters, not path separators.
• Performance warning: Using glob expressions can have an impact on the time it takes for Z Open Editor to find included files if it has to search through hundreds of local file directories. Revise the search pattern to match the lowest number of folders as possible in order to increase performance for finding copybooks and included files.

Relative path patterns

IBM Z Open Editor property group locations can be path patterns relative to the root of the workspace. You want to avoid patterns that point outside of the workspace as these might be different for every developer that you are sharing your ZAPP file with. This is also important for multi-root workspaces: you do not want to reference files from another workspace. Instead, each workspace can have its own ZAPP file and the property groups of all workspaces get concatenated in the order in which the workspaces have been listed in the multi-root's .code-workspace file.

Absolute path patterns

IBM Z Open Editor supports absolute path patterns for locations items.

Windows:

propertyGroups:
- name: cobol-copybooks
  language: cobol
  libraries:
    - name: syslib
      type: local
      locations:
        - "C:\\Users\\<username>\\Desktop\\zopeneditor-sample\\COPYBOOK",
        - "C:/Users/<username>/Desktop/zopeneditor-sample/INCLUDES"
    - name: MYFILE
      type: local
      locations:
        - "C:/Users/<username>/Desktop/zopeneditor-sample/COPYLIB",
        - "C:\\Users\\<username>\\Deskto\\zopeneditor-sample\\INCLUDELIB"

Mac:

propertyGroups:
- name: cobol-copybooks
  language: cobol
  libraries:
    - name: syslib
      type: local
      locations:
        - "/Users/<username>/Desktop/zopeneditor-sample/COPYBOOK",
        - "/Users/<username>/Desktop/zopeneditor-sample/INCLUDES"
    - name: MYFILE
      type: local
      locations:
        - "/Users/<username>/Desktop/zopeneditor-sample/COPYLIB",
        - "/Users/<username>/Desktop/zopeneditor-sample/INCLUDELIB"

Enforcing case-sensitive file name matching

Starting from IBM Z Open Editor 1.2.0, file names to be matched via local libraries items are case-insensitive by default. For example, if you have a local copybook file named book1.cpy in a workspace folder specified by a local property group, then the COBOL statement COPY BOOK1. would still resolve the file, even on a case-sensitive operating system such as Linux or Macs using a case-sensitive disk format. In earlier versions of Z Open Editor, this was strictly case-sensitive on case-sensitive operating systems.

Although this new behavior provides more flexibility for users who create copybooks and include files in lowercase, it could lead to problems in a team where members use different operating systems or switch from VS Code to Eclipse Che. For example, on a case-sensitive operating system files could be created in the same folder that are only different in their casing, such as Book1 and BOOK1, but this would cause problems on case-insensitive file systems such as Windows. Therefore, to enforce exact case matching, you can enable the user setting "zopeneditor.enforceCaseSensitiveIncludeFileNames", which by default is false. Setting it to true means that even on Windows the exact same casing of the file name as specified in the program's code is required. This applies to COBOL, PL/I, and HLASM.

Note: This behavior also applies to the path names specified in property groups, which are case-insensitive by default, but can be made case-sensitive with this setting. However, this currently only works on Windows and Mac. On Linux and therefore Eclipse Che the property group path names are always cases-sensitive. Only the file names on the file system are matched case-insensitive when configured that way on Linux.

SQLCA and SQLDA includes/copybooks

A COBOL or PL/I program can be written to use the SQL communication area (SQLCA) and SQL descriptor area (SQLDA) to check return status for embedded SQL statements, or the program can use the SQL diagnostics area to check return status.

SQLCA and SQLDA includes are usually in-built and not added in the zopeneditor property groups. In IBM Z Open Editor, SQLCA and SQLDA copybooks are excluded from the searches because they do not exist, or because they are not of interest for development. It will not find these copybooks from the mentioned syslib or libraries in the property groups.