Migrating workspaces to a new version

Workspaces from earlier versions of IBM® Developer for z/OS® can be migrated for use in the latest Developer for z/OS version.

Workspaces that are created in an earlier version of Developer for z/OS are compatible with later versions. Workspaces that are created in later versions of Developer for z/OS are not compatible with earlier versions. For example, a workspace that is created with Developer for z/OS version 15.0.x can be opened in version 16.0.x, but after it is used with version 16.0.x it can no longer be used with version 15.0.x. This policy also applies to individual artifacts of a workspace, such as property groups. It is a good practice to make a backup copy of a workspace prior to migrating it to the new version.

Migrating a workspace

  1. Review the Workspace migration notes and take note of any that apply to your workspace.
  2. Create a backup copy of your workspace before migrating it to a new version of Developer for z/OS.
  3. To migrate a workspace that was created in a previous version of Developer for z/OS, open the workspace in the new version of the client. A message similar to the following prompts you to confirm the migration:
    Workspace migration confirmation message
  4. After the workspace opens in the new version, you might need to reset any active perspectives to ensure that the correct views are shown. For each active perspective, right-click the perspective icon and click Reset.
    Reset Perspective action
Following migration, you are likely to see one or more of the following messages:
  • A message that indicates the old workspace layout cannot be restored. This condition is caused by renaming some views and deprecating others.
  • A window that requests a user ID and password for a remote system connection. Before any connection properties are changed to reflect differences in the old and new remote system environments, an attempt to connect is likely to fail.

Workspace migration notes

Client certificate authentication
Developer for z/OS version 16.0.x supports Java 11, which does not include IBMCAC. If you migrate a Windows workspace that uses client certificate authentication and specifies IBMCAC as the JCE provider in the Client Certificates Preferences page, do these steps before migrating the workspace to version 16.0.x:
  1. With the workspace open in the prior version of Developer for z/OS, open the Client Certificates Preferences page and record the value in the hostIdMappings object identifier (OID) field.
    Client certificates preferences page
  2. Migrate the workspace as described in Migrating a workspace.
  3. With the workspace open in the version 16.0.x client, open the Client Certificates Preferences page and click Restore Defaults.
  4. Verify that the value in the hostIdMappings object identifier (OID) field matches the value you recorded when the workspace was open in the prior version of the client.
  5. Click Apply and Close.
Data Studio and the Data perspective
Data Studio and the Data perspective are removed from the product. If you open a workspace created by an earlier release, and the Data perspective is open, the views show error messages similar to the following example: Could not create the view: com.ibm.datatools.project.ui.projectExplorer. Close the Data perspective.
For versions 16.0.6 and 17.0.0, you can export database connection profiles from a version 15.0.x or earlier workspace, and then import them into a version 16.0.6 or 17.0.0 workspace. For instructions, see Importing connection profiles from IBM Data Studio or Eclipse Data Tools.
Db2 for z/OS
  • For versions 16.0.6 and 17.0.0, the Db2 catalog filtering function is expanded to include more catalog table columns. The first time you open an older workspace, any previously defined Name pattern filters are deleted and replaced with a column filter on the Name column. The name pattern is transformed to map to a Starts with, Ends with, Contains, or Equal to operator. If the name pattern has neither a . nor a % character, the Equal to operator is used. If the name pattern starts and ends with a % character, the Contains operator is used and the leading and trailing % characters are from the pattern. If the name pattern starts with a % character, the Ends with operator is used and the leading % character is removed from the pattern. If the name pattern ends with a % character, the Starts with operator is used and the trailing % character is removed from the pattern. If the pattern is the % string, it is migrated since it matches all strings. For more information about creating catalog filters, see Filtering Db2 objects.
  • For version 16.0.3, a new remote file mapping is added to map *.sql files on the workstation to **SQL partitioned data sets on z/OS. This mapping is added to workspace that were created in prior versions when you open the workspace in the version 16.0.3 client.
  • If you use the version 16.0.2 client to open a workspace created by the version 16.0.1 client and the JDBC driver license file is detected in the hidden folder of your home directory, for example, ~/.idzdb2/license/db2jcc_license_cisuz.jar, then the workspace preference for the location of the license file is set to that file. You must restart the client.

    If you use the version 16.0.2 client to open a workspace created by the version 16.0.0 client, no restart is required.

Getting Started view
The Getting Started view is removed from the product, and the task guides are migrated to Eclipse cheat sheets. If you open a workspace created in version 15.0.x or earlier in the version 16.0 client, the Getting Started view redirects you to cheat sheets.
Host Connection Emulator
Replaced with the Remote Connection Emulator. If you use the version 16.0 client to open a workspace that was created in version 15.0.x, and the workspace has an active Host Connection Emulator session, the session opens in the Remote Connection Emulator with a message similar to: No editor descriptor for id com.ibm.etools.host.connect.editors.HostConnectEditor. To access the full functionality of the Remote Connection Emulator, close that session and open a Remote Connection Emulator session.
Remote Connection Emulator
The Remote Connection Emulator can migrate emulator sessions in workspaces that were created by prior versions of the client, but you might notice these differences or limitations:
  • The session profile names might be changed. The Remote Connection Emulator creates profiles with a default name that matches the connection name, but you can rename the profile:
    1. To open the profile, click Edit profile Edit profile.
    2. Expand the Connection information section and update the Profile name field.
    3. Save your changes and close the session.
    4. In the Remote Systems view, right-click the connection name and select Remote Connection Emulator. The new name is displayed in the list of profiles.
  • If session profile includes a key mapping to the paste command, that key mapping is not migrated. Keys can no longer be mapped to the paste command.
  • For workspaces created on a macOS client, the certificate file for secure connection is not migrated. For more information about certificate files for secure connections on macOS, see Preparing a certificate file for secure connections from macOS.

The default session type is telnet 3279. If you use the 16.0.x or 17.0.x client to open a workspace that was created by a 15.0.x client, and that workspace has an active Remote Connection Emulator session, the Session type setting retains the value that was set in the workspace. To change the session type, click Edit profile Edit profile, and expand the Connection information section.

Limitation: Migrating from version 16 to version 17 does not migrate Remote Connection Emulator profiles. You must create Remote Connection emulator profiles for z/OS connections in your version 17 workspace.