Migrating from Z Open Editor v2 to v3

This page is for users migrating from IBM Z Open Editor versions 1 or 2. Z Open Editor version 3 introduces some breaking changes and the removal and replacement of a few capabilities that require manual migration steps. Review the changes below.

Note: If you do not want to be surprised by a VS Code automatic update for this release and/or need more time to prepare a migration, we strongly recommend that you use the VS Code setting extensions.autoUpdate and switch it to false. If you don't want VS Code to even check for updates, you can set the extensions.autoCheckUpdates setting to false. However, this also prevents updates for other VS Code extensions from being installed.

Features that have been removed/replaced

• Support for Java 8 removed: We compiled all of our language servers with Java 11 for this version of Z Open Editor. You will no longer be able to run the editor with a Java 8 runtime. You must upgrade to a Java 11 or newer runtime. For recommendations, see our updated Getting Started section.
• Property groups will no longer be supported as VS Code settings (zopeneditor.propertygroups): We made the full switch to ZAPP files in this release. You need to move all your property groups from your user settings and/or workspace settings to a ZAPP file. Also see the next section for breaking changes for ZAPP property groups.
• User Build workspace setting will no longer be supported as VS Code settings (zopeneditor.userbuild.workspaceSettings): We also made the switch to ZAPP here. The exception will be the user settings (zopeneditor.userbuild.userSettings). Those will remain.

Breaking feature changes

In addition to moving Property Groups and User Build settings to ZAPP, we also made schema changes that require updates to existing ZAPP files. All of these changes are driven by enhancement requests from the community at https://github.com/IBM/zopeneditor-about, IBM customers, and technical representatives that work with our customers every day. Changes in v3.0.0 represent the first increment of changes and requires breakages and manual migration. Going forward, our plan is to build on these changes in future updates, without requiring more manual migrations.

The following changes require manual updates to your current ZAPP files:

• Renamed properties: We fixed several places in which property names did not follow YAML/JSON naming conventions. We were aware of these issues, but did not update them in order to avoid migration. However, the required migration for version 3.0.0 created the ideal opportunity to fix them. The updated keywords below need to be replaced in your ZAPP files. Note that the first three properties in the table below are currently not used by Z Open Editor capabilities. They are planned to be used in future releases to support multiple ZAPP files and define relationships.

  Old name	New name
  group-id	groupId
  artifact-id	artifactId
  parent-id	parentId
  property-groups	propertyGroups

• Simplified and refactored property groups: Based on suggestions in discussion threads and issues filed in our community GitHub repository, as well as other feedback from users, we refactored the property groups. The goal was to make writing property groups simpler and avoid redundancies, such as specifying compiler options multiple times. In the new structure you can create one property group per language and provide a list to local or remote locations for it. You can still create several property groups for the same language, if you prefer to. We also simplified the nesting of the location arrays to be less complex by eliminating the special property syslib and instead making it one of the possible name values. Here is an example for a PL/I property group using the new schema:

  propertyGroups:
    - name: pl1-includes
      language: pl1
      compilerOptions: not(!)
      libraries:
        - name: syslib
          type: local
          locations:
            - "**/INCLUDES"
            - "TOOLS"
        - name: syslib
          type: mvs
          locations:
            - "IBMUSER.SAMPLE.PLI.PLINC"
            - "IBMUSER.TOOLS.PLI.PLINC"
        - name: MYLIB
          type: mvs
          locations:
            - "IBMUSER.SAMPLE.PLI.INCLLIB"
        - name: MYLIB
          type: local
          locations:
            - "**/INCLUDELIB-MVS"
        - name: MYFILES
          type: local
          locations:
            - "**/INCLUDELIB"
  

  The libraries array defines the search order for include files. Within each libraries item there can be many locations items that are also searched in the order listed. For the example above, Z Open Editor will first look for regular include files using the entries specified under the name syslib in any local sub-folder that matches the folder name INCLUDES. Second, it will search in the one local folder TOOLS that is expected to be at the root of the current VS Code workspace in which the ZAPP file is located. If Z Open Editor does not find an include file in any of these local folders, it will then search in MVS in the data sets listed: IBMUSER.SAMPLE.PLI.PLINC first and IBMUSER.TOOLS.PLI.PLINC second. The same kind of search applies to the libraries MYLIB and MYFILES as defined in the example above. Note, that as in previous releases of Z Open Editor you can use multi-root workspaces with each workspace having its own ZAPP file. The search order will then be determined by the order of workspaces defined in the .code-workspace file.

• Required application setting for User Build: In the 2.1.1 and 2.2.0 releases of Z Open Editor we changed the usage of the --application parameter for user build as a quick fix for an issue with multi-root workspaces. The disadvantage of the solution was that programs stored at the top-level folder of a VS Code workspace would be uploaded to the z/OS UNIX System Services workspace without organizing them into an application-specific subfolder. (See 2.1.1 Release notes.) We have addressed this problem now by introducing a new mandatory setting for DBB ZAPP profiles called application that defines the application name as required by dbb-zappbuild. Users need to add this setting to their profiles. For example:

  profiles:
    - name: dbb-userbuild
      type: dbb
      settings:
        application: SAM
        command: "$DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON"
        buildScriptPath: "${zopeneditor.userbuild.userSettings.dbbWorkspace}/dbb-zappbuild/build.groovy"
        buildScriptArgs:
          - "--userBuild"
          - "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}"
          - "--application ${application}"
          - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
          - "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
          - "--dependencyFile ${dependencyFile}"
        additionalDependencies:
          - application-conf
  

  As you can see in the example, the value of the new application setting can be referenced as a variable ${application} within the profile, such as for the Groovy command argument. Since user build requires IBM Dependency Based Build, the documentation with user build changes and enhancements is only available in IBM Documentation.