Release Notes

Topaz Workbench 19.04

June 6, 2019

What’s New in Release 19.04

Topaz Workbench provides an Eclipse-based IDE to streamline mainframe application development with System z software. Its intuitive and easy-to-use interface provides the essentials of modern mainframe application development, testing, and maintenance powered by Compuware Abend-AID, File-AID, Hiperstation, Xpediter, and Strobe.

The Topaz Workbench media is composed of Topaz Workbench, a branded Eclipse Rich Client Platform application that includes the Compuware z/OS Product Plug-ins. Topaz Workbench plug-ins are also made available on the Topaz Workbench media for installation into Eclipse and IBM RDz/IDz environments.

Release 19.04 includes the following enhancements:
April 1, 2019
Topaz Workbench

  z/OS Unix support improvements:

-- file/folder creation, deletion and rename

-- set permissions

  Release 19.04.01 introduces the Topaz 3270 Emulator:

-- An embedded emulator accommodates one-off 3270 interactions without leaving Topaz. For example, you can run REXX/CLIST utilities within ISPF or access CICS or IMS transactions to initiate debugging sessions.

  Topaz SDK API additions:

-- allocate PDS or sequential dataset

-- create and delete members in a PDS

-- write to a sequential dataset or a member in a PDS

  Continuous improvement:

-- SlickEdit preferences now including in team sharing via Team Profiles

-- Improved drag/drop processing for mainframe projects; improved copy to clipboard

-- Added ability to add datasets/PDS members to projects from Project Explorer via right click Add

-- Improved icons in the Team Profile dialogs

-- Added encryption to our Jenkins Host Connection capabilities

-- Improved performance in Xpediter/Eclipse with large programs.

-- Announced intention to remove Xpediter TSO Debug Session from our Launch Configurations. This capability has been superseded by Xpediter Batch Debug Sessions.

Topaz for Program Analysis

  Internal 3270 emulator provided as part of Topaz for Program Analysis licensing.

Topaz for Enterprise Data

  Installation and licensing changes:

-- The Topaz Enterprise Data feature selected during install now includes functionality which was previously installed by the File-AID/Eclipse, File-AID/EX, File-AID Data Privacy, and Topaz for Enterprise Data features.

-- A Topaz for Enterprise Data (TED) license is required to use some of the capabilities within Topaz Enterprise Data, including File-AID/EX functionality.

-- All functionality from File-AID/EX is now available from within Topaz Workbench. Installation of the Topaz Enterprise Data feature within Topaz Workbench includes the File-AID/EX client, Communications Manager, and a local Execution Server. The File-AID/EX standalone client components which were previously installed from the File-AID/EX tab on the Topaz for Enterprise Data media are now part of Topaz Workbench.

-- Since File-AID/EX functionality is now installed with Topaz Enterprise Data, it can only be started from within Topaz Workbench; there is no longer an option to start File-AID/EX from the Windows Start Menu.

-- Execution of File-AID/EX batch jobs and access to z/OS datasets through File-Aid Enterprise Edition both require a standalone Execution Server be installed.

  Additional functionality in Topaz Enterprise Data:

-- Related Extract now includes an option to generate Delete statements for each row included in the extract. A file is generated containing the Delete statements; this file can then be processed as SQL to delete the identified rows.

-- Execution Servers are now defined as preferences for Topaz for Enterprise Data. An option is available to add current Execution Server definitions stored in the repository to TED Preferences. Execution Server Preferences includes Execution Hosts to identify hosts for mainframe execution.

-- Disabled entries within Data Privacy can now be displayed and edited.

Topaz for Total Test

  Additional support for CICS commands

  Support for Combined REWRITE stub

  Support for CICS integrated translator

  Added redefine for DB2 stub host variables

  Support for IMS CEETDLI interfaces

  For functional testing, replaced the use of FTP with HCI

  One combined test scenario - first integration between unit and functional tests

-- Allowing execution of unit and functional test cases from the same test scenario with one user flow.

-- Uses the repository from functional testing to keep runtime data about programs to be unit tested.

-- At execution time, generates the runner JCL removing the need for users to manually create and administrate runner JCL files.

-- This is the first initial integration between unit and functional testing and shows how the integration of the approaches will be done. Improvements will be made for each coming release based on customer interactions and feedback.

ISPW Eclipse

  Ability to check out a previous “historical” version and add it to a Task

  A new Promotion Analysis column has been added the to Active Assignment view which will warn of potential overlay conflicts; this is the information found in the “Version Audit” report in the TSO interface

  Active Assignment View: you will now be able to select the columns you wish to see

  Eclipse Project support has:

-- Added the ability to Drag and Drop items from the Repository Explorer to the Active Assignment

-- Added the ability for JCL components to Submit or Debug

  New REST API provides a list of Assignment, Release, and Sets

  New REST API provides a list of information in the ISPW Worklist

  Updated Deploy REST API allows for multiple deployment environments with individual date/time to be specified

  New API for deployment requests has been added to allow for modification of deployment date/time

  Provide for a Browse of a Task when someone else has it checked out

  Support for secure CT connections

  Update Replace Version added to Task View and Active Assignment View

Release 19.03 enhancements January 3, 2019
Topaz Workbench

  Introduced Team Profile to allow for users to quickly and easily share configurations, projects, preferences and working sets either to Compuware Enterprise Services or to a local file.

  Improved the ability to control the logical layout of mainframe projects, allowing cut/copy/paste of mainframe assets (files, tables, members, launch configurations) across folders and across mainframe projects.

  Enhanced the Add ... project capability to allow the user to specify the project folder location and to use search to determine files / members to be added.

  Introduced JES Explorer job limit as a preference.

Xpediter/Eclipse

  Changed the default work file specification so users can now debug both pre-COBOL 5 and COBOL 5/6 programs without having to change any settings.

  Added the default work file specification to preferences to allow a site to globally override this setting.

  Introduced the Common tab to the Launch Configuration dialog. This tab replaces the Comments tab and allows the user to save the configuration within a project (besides the ability to add comments).

Topaz for Enterprise Data

  Extracts can now be created in Topaz for Enterprise Data for File-AID/RDX. Extract is available for z/OS Db2 tables and includes the ability to discover related tables based on RI defined in Db2, specify selection criteria, define extract options and apply Data Privacy rules. The extract can be saved to a repository and executed by File-AID/RDX; execution reports will be returned to Topaz for Enterprise Data.

  Metadata Extensions are used by Data Privacy Rules to process COBOL layouts which contain REDEFINES. The Metadata Extension defines which definition or REDEFINES is to be used to process the data. Metadata Extensions have been redesigned to allow reuse of the definition and improve usability. Previously, the use of a Metadata Extension was limited to the dataset and member specified during definition. Metadata Identifiers have been introduced to provide additional locations where the same layout resides. The same Metadata Extension definition will then be applied to each layout identified by the Metadata Identifiers.

  The ability to disable Source Data Identifiers (SDIs) in the Data Privacy Global Project is no longer available. Any existing SDIs within the Global Project will be enabled during repository conversion. SDIs imported from the Global Project must be disabled within the Project which uses the SDIs if they are to be omitted during processing.

Topaz for Total Test

  XaTester by Compuware included in Topaz for Total Test and renamed to functional testing.

  Unit test creation for CICS programs with recording and stubbing of CICS APIs. Run a generated CICS unit test without the need for a CICS environment.

ISPW Eclipse

  Eclipse Project support has been added.

-- This adds the new Active Assignment View where you can do most of your work.

-- Leverages Eclipse functionalities which work off projects.

  Fallback API now can specify a specific Assignment, Release, or Task.

  New API to Transfer Task to another Assignment or Release.

  Several existing views have become default views. For an existing workspace, reset the perspective to automatically see the new default views.

Release 19.02 enhancements October 1, 2018
Host Explorer

  JES Explorer now by default lists the referenced DDs based on the DSID, the same order as SDSF.

  Online Projects enhancements:

-- Online projects have been enhanced to include capabilities currently available within Host Explorer right-click options such as compare, submit, and submit compile.

-- Searching is now allowed at the online project folder level.

-- Context menus have been cleaned up for consistency and to follow standard UI guidelines.

-- Icons have been updated to indicate if an entire PDS/PDSe library was added to a project or a subset of members from that library.

-- The icons have also been updated to indicate if the entry is a link (as to an existing mainframe asset) or is a local file.

Topaz for Enterprise Data

  Data Privacy now includes Encryption Sets which allow users to limit the characters used as replacements during encryption rule actions. A new function was added to Administration to define the Encryption Set.

  File-AID/EX has been changed to eliminate the use of the Windows Registry; existing values will be automatically migrated to configuration files.

Topaz for Program Analysis

Performance for Project Hierarchy has been improved by only analyzing referenced copybook members.

Topaz for Total Test

Ability to edit the DB2 structure length in a stub without recapturing the test case.

ISPW Eclipse

  Ability to copy values to the clipboard from Tasks View and Error Logs View.

  Ability to select a selective deploy environment when using the fast path operations (Promote/Deploy/Fallback/Regress).

Release 19.01 enhancements June 28, 2018
Topaz Workbench

  Topaz Workbench has been updated to be based off Eclipse Neon. Please check the Installation Guide ’s “Task 1.1 Verify System Requirements” section for corequisite software requirements.

  JES Explorer has been updated to have a more intuitive user experience.

-- The view now has three panels, including a collapsible dialog on the left for entering search criteria. The middle panel will show the jobs in the queue, and the right side will show the DDs for the selected job. A filtering capability has been added for the jobs that appear in the middle panel as well as the total number of records for the selected jobs DDs.

-- Additionally, JES Explorer has the ability perform Hold and Release actions on jobs in the queue.

  Online Projects functionality has been significantly enhanced.

-- Online projects now allow the user to easily organize assets into user-defined folders as well as add mainframe data assets (MVS, IMS, and DB2) to the project in addition to source code and JCL.

-- Online projects now support submit/debug and Search via File-AID and Host Explorer search.

-- Additionally, DIFFZilla has been added as a compare option for comparing source code. DIFFZilla allows columns to be ignored in the comparison, which can be useful when source code line numbers are part of columns 0-7 or 72-80.

  Host connections are now specified in the user interface throughout Topaz by the description vs. the host:port.

  The locate functionality in the Host Explorer Content view has been replaced with a Find capability that will filter the members displayed based off members that match the filter.

  Xpediter/Eclipse will now default the showing of the Xpediter log file to off when creating a new Xpediter debug profile.

   '.COPY' has been added to the Dataset Extension Mapping Definitions for the .cpy extension.

  Changed the default browser setting in Eclipse to use the External Browser setting.

Topaz for Enterprise Data

  Data Privacy Rule tree display will now include the names of translate tables and composites used within the rule.

  Search and Replace were added to the right-click menu of the Data Privacy Rule Editor.

  Security improvements were made to File-AID/EX to provide secure socket communication and password encryption. A utility was added to generate key stores and trust stores for securing communication.

  Execution of System Commands from within File-AID/EX specifications will be blocked. A new Execution Server option must be set to permit System Commands to execute.

  The Data View within File-AID/EX Homebase has been dropped; Host Explorer provides the ability to list database tables.

  The File-AID/EX installation instructions and the File-AID Data Privacy Configuration Guide are now part of the Topaz Enterprise Data Installation and Configuration Guide . A section on “Good Practices” for security has been added to this guide.

  File-AID/EX fixes have been applied to the jtds driver installed with the product.

Topaz for Program Analysis

The Program Structure view now persists the setting for the Node Text which controls the text displayed in each node in the chart.

File-AID/Eclipse

  Improved File-AID DB2 editors messaging when no rows are selected.

  Added the Data Source Explorer view to the File-AID Data Editor perspective.

Topaz for Total Test

  IMS MPP Program support.

  User-defined Static and Dynamic structure Redefinition.

ISPW Eclipse

  Performance Improvements.

  Improved the Workflow--Fast Path and Advanced.

-- Made a fast path to quickly Generate, Promote, Deploy, Regress, and Fallback.

-- Advanced options for scheduling and modify processing. You can now schedule Regress and Fallback processing.

  New APIs for your DevOps tool chain.

-- Assignment and Release Operations: Cancel, Close.

-- Set Operations: Restart, Terminate and Approve, Deny, Reset.

  Topaz CLI for ISPW now supports downloading of specific Set, Assignment, or Release containers as well as downloading of changes (instead of complete download) on subsequent runs of the downloading process.


Software and Hardware Requirements

The Software and Hardware Requirements can be found in the Topaz Workbench Installation and Configuration Guide.


Technical Notes

Topaz Workbench

The following features need to be installed after Check for Updates upgrade processing of an earlier 19.x release to Topaz 19.4.1 has been performed. Refer to the Topaz Workbench Installation Guide , Appendix C, “Adding and Removing Topaz Workbench Features”.

  Topaz 3270 Emulator -- New feature.

  Topaz Enterprise Data

-- Packaging adjustments require additional plugins. Select either the 64-bit or 32-bit (x86) version.

-- A “drivers” folder must be created in the install directory and required database drivers copied there.

  Use of the ConverterPro Specification Generation Utility requires a full install or reinstall of Topaz Workbench.

Topaz for Total Test

  A 64-bit Java Runtime Environment (JRE) is required for the Topaz for Total Test Command Line Interface (CLI).

  Topaz for Total Test does not support KSDS READ NEXT using alternate key for which duplicates are allowed when there are duplicates and they are not ordered in prime key order.

  Generating Topaz for Total Test unit test cases for very large programs may require increasing the memory allocated to Topaz Workbench. To do this edit the topaz.ini file in your installation directory of Topaz Workbench (by default the path is C:\Program Files\Compuware\Topaz Workbench\eclipse):

Find the entries:

-Xms256m
-Xmx512m

Change them to:

-Xms512m
-Xmx1024m

This change doubles the amount of memory available to the Topaz Workbench and Topaz for Total Test.

Save the topaz.ini file and restart Topaz Workbench.

Topaz Enterprise Data

For Eclipse-based IDE installs:

  If Topaz Workbench Datatools will be used, install only the Compuware DB2 for z/OS using Topaz (base) feature. This plugin is optional and not required if the native Eclipse datatools plugins will be utilized.

  The following update sites must also be included and enabled:

-- For Neon - http://download.eclipse.org/releases/neon and http://download.eclipse.org/eclipse/updates/4.6

-- For Oxygen - http://download.eclipse.org/releases/oxygen and http://download.eclipse.org/eclipse/updates/4.7

  To use Topaz Workbench Datatools after the Compuware DB2 for z/OS using Topaz (base) feature has been installed, a database connection must be established. In IBM IDz 14.1 releases, the New Connection Profile option in the Data Source Explorer view does not open the correct dialog. You must:

-- Click File>New>Other

-- Expand Connection Profiles

-- Select Connection Profile and click Next

-- Select DB2 for z/OS using Topaz .

Supported DB2 and IMS Releases

  DB2:

-- V11 CM, NFM

-- V12 (Refer to File-AID for DB2 for further support details)

  IMS:

-- IMSV12.1

-- IMSV13.1

-- IMSV14.1 (Refer to File-AID for IMS for further support details)

Supported Distributed RDBMS Platforms

  Oracle Database 11g, 12c

  DB2 for LUW V9.5, V9.7, V10.1, V10.5

  Sybase 15

  MS SQL Server 2005, 2008, 2012

Program Analysis

Supported COBOL, PL/I, DB2, and IMS Releases

  IBM Enterprise COBOL for z/OS:

-- V4.2

-- V5.1

-- V5.2

-- V6.1

-- V6.2

  Toleration of all supported GA versions of:

-- IBM Enterprise PL/I for z/OS

-- IBM DB2 for z/OS

-- IBM CICS Transaction Server for z/OS

-- IBM IMS Transaction and Database Servers.

ISPW/Eclipse

For Eclipse-based IDE installs, the following update sites must also be included and enabled:

  For Neon - http://download.eclipse.org/releases/neon and http://download.eclipse.org/eclipse/updates/4.6

  For Oxygen - http://download.eclipse.org/releases/oxygen and http://download.eclipse.org/eclipse/updates/4.7

ISPW Installation in Eclipse or RDz/IDz Environments

For the ISPW plug-in to be fully functional in an Eclipse or IBM RDz/IDz environment, be sure to select Host Explorer and SlickEdit (optional, for copybook support) for installation along with ISPW.

Running Topaz Workbench in 32-bit mode on a 64-bit OS

If you wish to run a new installation of Topaz Workbench as 32-bit in a 64-bit environment, run the Install32on64.bat file, which launches an installer containing an option to install as 32-bit on 64-bit. The batch file is located in the same folder on the Media Browser disk image as the setup.exe file.

File-AID/EX

Starting with release 19.4.1, a 32-bit Java Virtual Machine is no longer packaged with File-AID/EX. The default location for the 64-bit JVM is the C:\Users\<User ID>\Compuware\Topaz\eclipse\jre folder. Windows registry is no longer used, and existing registry entries are automatically moved to configuration files. If you have customized batch files or JVM switches, review them to ensure they remain compatible after the change to a 64-bit JVM.

VIPA Networks

A minimum of HCI 3.0 is required for VIPA networks.

Host Explorer and SlickEdit Licensing

Use of Host Explorer and SlickEdit will require a valid Compuware Mainframe License (any product) on any LPAR serving Host Explorer connections. The HCI hosting these communications must have access to Compuware’s License Manager. If there is any licensed Compuware mainframe product running on an LPAR where HCI is executing, no further effort is necessary.

Xpediter/Eclipse

Compuware Shared Services Enhanced Listings

Xpediter/Eclipse does not support Compuware Shared Services (CSS) enhanced listings. For information on enhanced listings, refer to the Compuware Shared Services documentation.

Xpediter/Eclipse requires a direct connection to an LPAR with a working version of Xpediter/CICS, Xpediter/TSO, and/or Xpediter/IMS on any LPAR where Xpediter debugging sessions are to execute.

Audit Preference

By default, the Enable auditing preference is turned on, and an audit file is created on the mainframe. Be aware that when auditing is enabled, the FORCE option on the Concurrent Update view does not work because it would negate the audit.

Hiperstation/Eclipse

  The Hiperstation/Eclipse feature is not compatible with the Eclipse Oxygen 4.7 release. This will be corrected with later maintenance.

  Security for the Hiperstation for WebSphere MQ product is now checked not only when the product is started, but also whenever a Restart command for a global recording request is issued. If security has changed for the request owner or rules have been changed, requests that ran before may no longer run.

  Only single-byte characters are supported on code page 939.

eGit Compatibility

eGit versions 4.6.1--5.0.1 and 5.04 and above are compatible with Topaz Workbench release 19.01 and above. eGit versions 5.02--5.03, however, exhibit known issues with the eGit UI and are not compatible with Topaz Workbench release 19.01 and above.

Configuring Eclipse Memory Settings

Java OutOfMemory errors may occur when editing a large file or displaying a large JES report. These errors can often be avoided by increasing the maximum size of the JVM memory heap. The initialization files in Topaz Workbench or Eclipse (topaz.ini or eclipse.ini) include an Xmx parameter (default 512m or 1024m) used to specify the maximum heap size. The optimum value for this parameter varies depending on the OS used, memory fragmentation, and other factors.

On 32-bit Windows, the theoretical heap size is limited to 2GB due to how Windows allocates memory, but this is reduced by many factors. Generally, the stated maximum is 1536m, while a commonly stated max range is 1200m to 1500m. The optimal setting for a particular installation--with no OutOfMemory errors or noticeable garbage collection pauses--can only be determined by experimenting with different values. Compuware recommends increasing the Xmx value to 1200m as a starting point and increasing or decreasing the value in small increments, such as 512m, until an optimum value is found. However, even with a setting of 1536m, large JES output can easily exceed that value. The only practical solution in such situations is to install the products on a 64-bit OS.

On 64-bit Windows operating systems, heap size is limited by your Windows virtual memory specification, minus a small amount of memory used by the OS and other processes. Specifying 4GB or more for the Xmx parameter can be practical depending on the Windows virtual memory size.


Known Issues

Topaz 3270 Emulator

The 3270 Emulator has the following known issues:

  Cut (Ctrl+x) is not supported.

  Intermittent connectivity issues may occur during initialization. If so, press Clear to reset the connection.

ISPW Eclipse 19.03.01

  Sonar Lint Change Analyze Changed Files option is not functional in this release.

  Refreshing a project will close any editors that are open for the project.

  The Team menu for an ISPW project will show Apply Patch and Share Project even though they don’t apply.

Viewing Exported Portable Network Graphics (PNG) Files

When exporting an image from Program Analysis or Visualizer, if the View document after export checkbox is selected, *.png is selected from the Save as type dropdown list, and the default application associated with .png files is Microsoft Paint, the exported image cannot be opened automatically. Browse to the export location and open the file manually.

Overlaid Error and Warning Marks in Overview Ruler

When using Program Analysis, markers for Information items can potentially overlay and obscure Error and Warning markers in the SlickEdit Overview Ruler. The suggested workaround is to deselect the Overview Ruler for Information items, leaving Errors and Warnings displayed without being overlaid.

Potential for Missing Menus and Toolbars

The topaz.ini file sets the osgi.instance.area.default to the @user.home location, which is typically mapped to a local drive or absolute path. If the user has their @user.home set to a UNC network path, the toolbars and menus within Topaz Workbench may not appear. To correct the problem, edit the topaz.ini file (default location is Topaz Workbench installation’s eclipse directory), replacing the @user.home location with a local drive or absolute path. If Topaz Workbench has been installed via p2repo into an Eclipse instance, the edit should be done to the eclipse.ini file instead.

Internet Explorer 11 Security Update for Windows 7 and 8.1 Causes Topaz Workbench Failure After Closing the Welcome Page

Microsoft Internet Explorer cumulative security update KB2977629 can cause failure of Eclipse-based products when closing the Welcome page. To resolve this issue, install Microsoft Internet Explorer cumulative security update KB2987107 or uninstall KB2977629.

File-AID Data Editor

Potential Loss of Precision

The potential exists for loss of precision on FLOAT and DOUBLE data types between the mainframe and the File-AID Data Editor user interface. See “Chapter 9. Floating-Point Overview and Support Instructions” in IBM's z/Architecture Principles of Operation (SA22-7832-09) for more information.

Formatting of COMP and COMP-4 COBOL Fields

Picture clauses for COMP and COMP-4 (binary data) field types are not used when displaying the decimal numeric value of these fields. Any implied decimals (V) or implied scaling (P) in the Picture are ignored and not used to display the numeric value of the field. The value displayed is a positive or negative integer.

Unformatted Mode Ruler and Data Alignment

The ruler at the top of unformatted mode is intended to line up with the data below it, but this may not always happen. Although the same fixed-width font is used for both the ruler and the data, certain characters on code pages 930 and 939 are narrower than others, causing the ruler and the data to fail to line up when those characters appear in the data.

The recommended solution is to substitute the narrow characters with red “periods” as currently done for binary data that cannot be translated to characters. Any modifications to those letters and punctuation must be done in the 3-line Hex display option.

Locked Oracle Table Postpones Timeout Error

When saving data to a locked Oracle table, the timeout error does not return after the set timeout period. It does return after the lock has been released.

Doc. APR2019