Setting property groups

Property groups are required to define how the COBOL, PL/I, and HLASM editors look for copybooks and/or includes when you edit a program. They can also be used to specify language-specific compiler options. To define a property group, you can use the following JSON snippet as a starting point, and copy-paste it into the existing JSON settings file for your VS Code Workspace or User Settings. For includes resolving, replace the paths for the syslib and/or libraries properties with the actual relative or absolute location of your VS Code workspace directory that holds your includes.

The sections below provide additional guidance on defining property groups using VS Code settings. Alternatively, if you prefer a YAML-based approach, you can define property groups in a ZAPP file instead, as documented in Configure your applications with ZAPP files.

Example JSON snippet for defining IBM Z Open Editor property groups in VS Code's settings file:

   "zopeneditor.propertygroups": [
    {
      "name": "local-cobol-files",
      "type": "local",
      "language": "cobol",
      "syslib": [
          "COPYBOOK",
          "INCLUDES"
      ],
      "libraries": [
       {
         "name": "MYFILE",
         "locations": [
           "COPYLIB"
          ]
       }
      ]
    },
    {
      "name": "local-pl1-files",
      "type": "local",
      "language": "pl1",
      "compilerOptions": "not(!),margins(2,100)",
      "syslib": [
          "INCLUDES"
      ],
    },
    {
      "name": "mvs-members",
      "type": "mvs",
      "syslib": [
        "TSOUSER.SAMPLE.COBCOPY",
        "TSOUSER.SAMPLE.PLINC",
        "TSOUSER.SAMPLE.ASMCOPY"
      ],
      "libraries": [
        {
          "name": "MYLIB",
          "locations": [
            "TSOUSER.SAMPLE.COPYLIB",
            "TSOUSER.SAMPLE.INCLLIB",
            "TSOUSER.SAMPLE.ASMCPYLB"
          ]
        }
      ]
    }
 ]

As you can see in the example above, you need to specify a unique name for each property group, which is the only mandatory property, and will help with troubleshooting. If you are using VS Code settings to define property groups, some additional general tips include:

  • We generally recommend defining property groups in your VS Code workspace settings, as workspace settings override user settings, and can be shared with your team members in an SCM system such as Git.
  • Ensure that you specify property groups correctly as an array of objects with the matching brackets and curly braces as shown above. When you type in these objects correctly, VS Code will give you code completion support, as well as show help information on hover.

The sections below explain in-depth how to fully leverage certain properties within a property group object. For a full breakdown of all the different properties you can specify within a property group, see the Property groups reference page.

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, 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. Another use case would be to specify the margins to be used for your PL/I programs. As shown in the property group example local-pl1-files above, multiple options should be listed in one string separated by commas. If you have more than one property group for a language, the 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 syslib property 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 syslib, 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 property groups, you can specify a path relative to your IDE workspace (only one workspace folder is supported for now) or an absolute path on your development machine.

Libraries

Use the libraries setting to resolve the following types of statements:

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

You can provide multiple libraries within the libraries array of a property group. Each library object in the libraries array consists of two properties:

  • The name property within the libraries setting must match the library name used in the progam. For example, to resolve the library reference in the COBOL statement COPY COPYFILE IN MYLIB, the value of name must be "MYLIB".
  • The locations property is an array of folder paths you provide for the associated library name. The setting looks into the folder paths to resolve the copybook or include.

MVS property groups using Zowe profiles

If you have Zowe CLI or Zowe Explorer configured on your development machine, property groups of type MVS will try to resolve copybooks referenced in COBOL programs using your Zowe default RSE or z/OSMF service profile. In this documentation, we cover the details of 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 libraries locations provided. The profile must be set up to use one of the following authentication methods:

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.

Fig.1: MVS connection test flow chart

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": "rseCLI",
    "defaultRseConversionMappingsFile": "~/.zowe/profiles/rse/conversion-mappings.json"
},

The value of defaultCliProfile is the name of the Zowe RSE or z/OSMF profile that you want to use. (In the example above, it is "rseCLI".) If you cannot remember the names, then you can run the commands below 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

Tip: If you cannot see that your copybooks resolve after you configured a valid defaultCliProfile and corresponding MVS property groups, it might be because the changes are not picked up by IBM Z Open Editor yet. This happens if you made changes to your Zowe profile during the same IDE session you are currently using. To refresh the MVS resource resolution, follow these steps:

  1. Open the command palette with Ctrl+Shift+P (Windows) or Cmd+Shift+P (Mac).
  2. Search for "Reload Zowe Profiles", and select the command IBM Z Open Editor: Reload Zowe Profiles.

The language server protocol will refresh, and you should now see that MVS copybook references resolve.

Quick tips for setting IBM Z Open Editor property groups

Setting IBM Z Open Editor property groups in multi-root workspaces

IBM Z Open Editor supports setting property groups for multi-root workspaces. Multi-root workspaces allow you to work with multiple project folders in Visual Studio Code. This can be very helpful when you are working on several related projects at one time. For more information, see multi-root workspaces documentationopen in new window.

When there are multiple projects opened in one workspace using multi-root workspaces in Visual Studio Code, each project may have its own .vscode directory individually defining settings that should only apply for that project. To avoid collisions, only resource (that is, file or folder) settings are applied while you are working with multi-root workspaces. Settings that affect the entire editor are ignored. For example, two projects cannot set different zoom levels at the same time.

User settings are supported the same way as with single-folder workspaces, but you can also set global workspace settings that will apply to all folders in your multi-root workspace. Global workspace settings will be stored in your .code-workspace file.

For more information about multi-root workspaces settings, see multi-root workspaces settings documentationopen in new window.

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 syslib locations as well as locations of libraries. Below are some examples about adding property groups using glob patterns, relative path, and absolute path for local files.

1. 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 glob patterns documentationopen in new window for more information.

  • An example using basic glob patterns for Windows and Mac:

    Windows and Mac:

    "zopeneditor.propertygroups": [
      {
        "name": "local-files",
        "type": "local",
        "syslib": [
          "zopeneditor-sample/**",
          "zopeneditor-sample/**/COPYFILES"
        ],
        "libraries": [
          {
            "name": "MYFILE",
            "locations": [
              "zopeneditor-sample/**/COPY*",
              "zopeneditor-sample/**/INCLUD?LIB"
            ]
          }
        ]
      }
    ]
    
  • Notes:

    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: For performance reasons, if your specified property groups contain a glob pattern that returns more than 20 directories to search, revise the search pattern to match less in order to increase performance for finding copybooks and include files.

2. Relative path patterns

  • IBM Z Open Editor supports relative path patterns in order to provide syslib locations as well as locations of libraries. Consider the example below for a user who has opened a zopeneditor-sample workspace:

    Windows and Mac:

    "zopeneditor.propertygroups": [
      {
        "name": "local-files",
        "type": "local",
        "syslib": [
          "../zopeneditor-sample/COPYBOOK",
          "../zopeneditor-sample/INCLUDES"
        ],
        "libraries": [
          {
            "name": "MYFILE",
            "locations": [
              "../zopeneditor-sample/COPYLIB",
              "../zopeneditor-sample/INCLUDELIB"
            ]
          }
        ]
      }
    ]
    

3. Absolute path patterns

  • IBM Z Open Editor supports absolute path patterns in order to provide syslib locations as well as locations of libraries.

    Windows:

    "zopeneditor.propertygroups": [
        {
          "name": "local-files",
          "type": "local",
          "syslib": [
            "C:\\Users\\<username>\\Desktop\\zopeneditor-sample\\COPYBOOK",
            "C:/Users/<username>/Desktop/zopeneditor-sample/INCLUDES"
          ],
          "libraries": [
            {
              "name": "MYFILE",
              "locations": [
                "C:/Users/<username>/Desktop/zopeneditor-sample/COPYLIB",
                "C:\\Users\\<username>\\Deskto\\zopeneditor-sample\\INCLUDELIB"
              ]
            }
          ]
        }
      ]
    

    Mac:

    "zopeneditor.propertygroups": [
        {
          "name": "local-files",
          "type": "local",
          "syslib": [
            "/Users/<username>/Desktop/zopeneditor-sample/COPYBOOK",
            "/Users/<username>/Desktop/zopeneditor-sample/INCLUDES"
          ],
          "libraries": [
            {
              "name": "MYFILE",
              "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 Syslib or Libraries entries 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)open in new window and SQL descriptor area (SQLDA)open in new window 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.

Last Updated:
Contributors: Lauren Li, Peter Haumer, Lauren Li, Shi Kun Li, Billie Simmons, Prasang-A-Prajapati, Min Huang, Billie Simmons, Greg Lambert, Eric Subah, PrasangAPrajapati, Bradley Knaysi, kmaselli