Setting property groups

Property groups are required to define how the COBOL, PL/I, HLASM, REXX, and JCL editors search for copybooks or includes when you edit a program. Without property groups, the language servers used by Z Open Editor cannot parse the programs correctly and show 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 searches in order 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 re-evaluates 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 try's to search for this copybook in other locations immediately. The editor does 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"

For JCL, include files you can specify property groups with jcllib instead of syslib, as well as leave out the locations list if you want the editor to use the location specified in the JCL file itself. For example, consider a JCL file with the following lines:

//    SET HLQ='IBMUSER'
//    SET LIB='SAMPLE.JCL'
// JCLLIB ORDER=&HLQ..&LIB
// INCLUDE MEMBER=COMPSET

The following property group can support a typical developer scenario in which a developer maintains a local version of the COMPSET JCL file in a local folder while working on modification. If the developer intends to hardcode the final location of the included JCL within the main JCL file as shown in the preceding JCL example, this setup ensures the file is ready for deployment to z/OS. The property group defines the search order for Z Open Editor when resolving JCL include files. It first searches the local folder JCLLIB. If the file is not found there, it checks the location specified by the including JCL file, as expressed by the second entry in the property group, which omits the locations list. If the file is still not found, the editor then attempts to locate it in the third location on MVS, as specified. This search order enables the developer to work with a local copy of COMPSET, and also enables other team members to locate the include file in IBMUSER.SAMPLE.JCL in case they do not have a local copy. With the search order defined in the ZAPP file, the team can specify multiple search locations to support various development setups and configurations.

- name: jcl-includes
  language: jcl
  libraries:
    - name: jcllib
      type: local
      locations:
        - "JCLLIB"
    - name: jcllib
      type: mvs
    - name: jcllib
      type: mvs
      locations:
        - "SYS1.PROCLIB"

As shown in the preceding examples, you must specify a unique name for each property group. This is the only required property. The name can help with troubleshooting, as the VS Code output view displays information about which property groups are searched and in what order.

The following sections explain 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 affect the editor. For example, define PL/I codepage options that map special characters to operators, such as a mapping the ! character to the NOT operator, as shown in the preceding pl1-includes example. Another use case is to specify the margins to be used for the PL/I programs. As demonstrated in the same property group example, list multiple options in a single string, separated by commas. If you define more than one property group for a language, the compilerOptions strings are concatenated. These options apply globally to all files in that language within the scope of your workspace. To define global compiler options, create a property group that includes only the name, language, and compilerOptions properties. For more details, see the 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, specify an array of directory path names (for local property groups) or data set names (for MVS property groups) for IBM Z Open Editor uses to locate include files. Specify multiple paths to resolve includes across 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 the 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 must be set to either local or mvs to indicate whether the values in locations refer to local search path entries or MVS data sets.
• The locations property is an array of either directory or data set names for the associated library name.

Note that libraries do not yet support JCL property groups.

Maclibs

When advanced capabilities are enabled, you can use the name maclib for a libraries item in a ZAPP property group to resolve custom macros in HLASM programs. See Custom Macros for HLASM for details. An example of a ZAPP property group with both a local and remote maclib entry:

propertyGroups:
  - name: hlasm-maclibs
    language: hlasm
    libraries:
      - name: maclib
        type: local
        locations:
          - "**/ASMMAC"
      - name: maclib
        type: mvs
        locations:
          - "IBMUSER.ASM.MACLIB"

Note that macros contained in maclib libraries are not available for fetching with COPY statements. See Syslib for more information on setting up your ZAPP file for COPY statements.

Proclibs

You can use the name proclib for a libraries item in a ZAPP property group to resolve custom procedures in JCL programs. An example of a ZAPP property group with both a local and remote proclib entry:

propertyGroups:
  - name: jcl-proclibs
    language: jcl
    libraries:
      - name: proclib
        type: local
        locations:
          - "**/PROCLIB"
      - name: proclib
        type: mvs
      - name: proclib
        type: mvs
        locations:
          - "SYS1.PROCLIB"

If the locations field is omitted for a libraries item that is named proclib, the procedure is resolved by using the datasets specified in the JCL file itself.

MVS property groups using Zowe profiles

If Zowe™ CLI or Zowe Explorer is configured on the development machine, libraries items of type mvs attempt to resolve copybooks referenced in COBOL programs by using Zowe RSE or z/OSMF service profiles. For details on defining these profiles, refer to Setting up integrations to interact with z/OS.

After you have created a profile that provides direct access to the MVS data sets listed in the property groups, the COBOL editor searches for copybooks in the syslib and library locations specified. During MVS remote file resolving, IBM Z® Open Editor performs an MVS connection test to validate the authentication method in use (Figure 1). If a JWT is not present in the service profile or base profile, the editor attempts basic authentication using a username and password. Z Open Editor does not attempt to resolve remote files until the connection test passes.

• If the username and password are not saved in Zowe the profile, IBM Z Open Editor prompts 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 turns off MVS remote file resolving for the duration of your IDE session or until you refresh the profile status through the command palette option >IBM Z Open Editor: Reload Zowe Profiles.
  • If you choose to update the profile's credentials, your Zowe profile only saves the new credentials if autoStore in your zowe.config.json is set to true.
  • After you update the profile's credentials, Z Open Editor re-attempts the MVS connection test.
• If the MVS connection returns a non-401 error, the error is logged to the Z Open Editor output and remote file to resolve stops for the duration of your IDE session or until you refresh the profile status through the command palette option >IBM Z Open Editor: Reload Zowe Profiles.

Figure 1: MVS connection test flow chart

If you have defined multiple Zowe profiles of the types zosmf or rse, then the editor uses the 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 zopeneditor.zowe User Settings.

Z Open Editor shows a progress notification for programs that involve long-running remote copybook or include file resolution. This notification enables users to cancel ongoing remote file resolution; however, requests already in progress continue to completion. Z Open Editor does not attempt to resolve remote files for a cancelled program until the program is closed and reopened.

Set 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 to define locations items. The following examples show how to add property groups using glob patterns, relative path, and absolute path for local files. Note that wildcard support is not currently available for MVS data set names; these must 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: Use only forward slashes (/) in glob expressions. Although Windows supports both / and \ as path separators, only / characters are used by this glob implementation. You must use only forward slashes in glob expressions. Backslashes are always interpreted as escape characters, not as 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 use path patterns relative to the root of the workspace. Avoid patterns that point outside the workspace, as these might be different for every developer that you are sharing your ZAPP file with. This is especially important for multi-root workspaces: do not reference files from another workspace. Instead, assign a separate ZAPP file to each workspace. The property groups from all workspaces are concatenated in the order in which the workspaces appear in the multi-root .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 through 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. still resolves 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 causes 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 using this setting. However, this option currently works only on Windows and Mac. On Linux, and therefore in Eclipse Che, property group path names are always case-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 does not find these copybooks from the mentioned syslib or libraries in the property groups.

UNC paths and mapped drive letters support on Windows

IBM Z Open Editor supports both UNC network paths and mapped drive letters on Windows in the locations field of a property group on the Windows operating system. This enables teams working in enterprise environments with shared network drives to resolve include files, such as copybooks stored on Windows network shares. When defining property groups, you can specify UNC-style paths, for example, \\\\hostname\\share, or mapped drive paths, such as Z:/folder, in the locations list for local libraries. IBM Z Open Editor validates and resolves these paths, provided they are accessible and properly authenticated within your Windows user session.

UNC path support includes the following considerations:

• IBM Z Open Editor supports UNC paths in the format \\\\hostname\\folder1\\folder2 or //hostname/folder1/folder2. These must be accessible and readable during use.
• If the UNC path is not authenticated, such as when credentials are not cached or Windows Explorer is not used to access it, resolution may fail. In such cases, open the UNC path manually in Windows Explorer to prompt authentication.
• By default VS Code security settings restrict UNC access with the user setting security.restrictUNCAccess set to true. To access your drives when the value is not set to false, the UNC hosts must be listed under the user settingsecurity.allowedUNCHosts. If they are not listed, IBM Z Open Editor skips these locations. Note, that when you change one of these user settings you must stop and restart VS Code for them to take effect.
• Mapped network drives, such as Z:/folder1/folder2, are also supported. IBM Z Open Editor checks internally whether the mapped drive points to a UNC path and applies UNC host restrictions accordingly.
• UNC path wildcards, such as \\\\hostname\\folder\\*, or globbing over a UNC root, for example, //hostname/**/COPYBOOK, are not supported and are ignored to prevent unpredictable results or access issues.

Windows:

propertyGroups:
  - name: cobol-copybooks
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "\\\\hostname\\folder1\\folder2"
          - "Z:/team/copybooks"