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 eachlibraries
item there can be manylocations
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 namesyslib
in any local sub-folder that matches the folder nameINCLUDES
. Second, it will search in the one local folderTOOLS
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 andIBMUSER.TOOLS.PLI.PLINC
second. The same kind of search applies to the librariesMYLIB
andMYFILES
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 calledapplication
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 our User Documentation for the IBM Z and Cloud Modernization Stack.