HCL Z Abend Investigator
The HCL Z Abend Investigator extension for Microsoft Visual Studio Code works in conjunction
with the Zowe Explorer extension. HCL Z Abend Investigator helps developers
analyze and fix application and system failures.
When applications abnormally end (ABEND), it is crucial to understand the root cause.
HCL Z Abend Investigator can discover ABENDs faster, more confidently, and in less time
by automatically gathering real-time information of the ABEND and the environment at the time of failure.
Table of contents
General requirements
- Assumes knowledge of the HCL Z Abend Investigator product installation
and features.
- The Z Abend Investigator VS Code extension connectivity to the host is similar to using
the Z Common Components (ZCC) server:
- Assumes knowledge of how to install and configure
the Z Common Components server.
- ZCC must use the AT-TLS feature when configuring TLS support.
Host requirements
VS Code requirements
- VS Code
1.101.0+
- Zowe Explorer
3.2.0+
- Assumes the user is familiar with the Zowe Explorer extension before using the HCL Z Abend Investigator.
Integration with Zowe Explorer
The HCL Z Abend Investigator extension builds on the strong foundation provided by Zowe Explorer.
To preserve the familiar Zowe Explorer user experience, it purposefully avoids contributing highly
customized UI elements whenever possible. Instead, it enhances your current workspace by:
- Reusing your Zowe profiles configuration to manage local and remote resources.
- Adding new functionality directly to Zowe Explorer's existing Data Sets and Jobs views.
- Integrating specialized views directly into Zowe Explorer's existing tool windows.
See the Getting help section to report issues related to the Zowe Explorer extension.
Optional VS Code extensions
- IBM Z® Open Editor
- Provides color-coded sources when viewing side files in fault reports.
- Provides color-coded job spool data sets.
Features
The current version of the HCL Z Abend Investigator extension does not support all features available
in the ISPF Z Abend Investigator client.
The following list provides a high-level overview of the features that are supported and unsupported
in the extension.
Supported character sets
The extension supports resources in both English (IBM1047) and Japanese (IBM939).
Use the HCL Z Abend Investigator > Language setting to configure the global resource language.
History files
- Open history files in a separate view.
- Customize visible columns in the history files view.
- Filter visible fault reports using individual column filters.
- Add history files to the Z Abend Investigator tree view:
- From the Zowe Data Sets tree view
- From the Z Abend Investigator tree view
- From the Command Palette
- Remove history files from the Z Abend Investigator tree view.
Fault reports
- Reanalyze and display fault reports in a separate view:
- From the context menu of the history file view, or by clicking a fault entry reference
- From the context menu of a job in the Zowe Jobs tree view
- From a job JESMSGLG editor as hyperlinks, and from the context menu
- From the Command Palette
- Navigate to sections of the report:
- Event Detail hyperlinks to jump to a specific event definition
- Source code hyperlinks to open a source file at a designated line
Z Common Components connections
- Associate a Z Common Components connection with a Zowe profile.
- Remove the association between a Z Common Components connection and a Zowe profile.
Unsupported features
Secure connections
- Trust manager for certificates that are used to connect to the Z Common Components server.
History files
- Add default and recent history files.
- Copy/Rename/Remove fault entries from the history file.
- Choose column ordering.
- View fault entry properties.
Fault reports
- Side files:
- IDITrace logs
- JCL for the job causing the ABEND
- Minidump
- Hyperlinks:
- Lookup view links for viewing ABEND explanations
- Memory links jumping to minidump
- CICS links
Views
- Add view
- Create view
- Display and navigate views
Fault analytics
- Manage and display charts
Getting started
Configuring the Z Common Components connection
Before you begin, all preceding requirements must be satisfied.
- Open VS Code.
- If necessary, create at least one Zowe profile: team configuration profile or v1 profile (deprecated).
- Switch to the Zowe Explorer tool window.
- Right-click on the profile that matches the z/OS subsystem where your Z Common Components server runs.
- From the Z Common Components menu item, select Configure connection.
- Enter the connection information for the Z Common Components server.
You are now ready to use the Z Abend Investigator VS Code extension.
Note: if you access a Z Abend Investigator feature before configuring the ZCC connection,
you are prompted to provide the required connection information. This prompt occurs only during the
first access.
The Z Abend Investigator tree
When the Zowe Explorer tool window is selected in VS Code, the tool window contains three default tree views:
Data Sets, Unix System Services, and Jobs.
The HCL Z Abend Investigator extension adds a tree view, HCL Z Abend Investigator, to manage the addition
of history files. When you associate a ZCC connection with a profile, the connection displays in the
HCL Z Abend Investigator tree view.
Tree structure
Connection nodes
A root node in the tree view displays each ZCC host and port connection.
History Files nodes
These are the parent nodes for the history files associated with the connection.
- Click the Add History File inline button or select the option from the context menu to provide
a data set name. This action opens the new history file and adds it to the tree view.
History File nodes
These nodes represent the history files that are associated with the connection.
- Click the Open History File inline button or select the option from the context menu to open
the history file. If the file is already option, this action puts it into focus.
- Click the Remove History File inline button or select the option from the context menu to remove
the history file from the HCL Z Abend Investigator tree.
Opening history files from the Zowe Explorer Data Sets tree
History files can also be added from the Zowe Explorer Data Sets tree:
- In the Zowe Explorer Data Sets tree view, click the Search Data Sets inline button or select
the option from the context menu item for a specific profile.
- Select an existing filter or create a new filter to display the history file that you want to add to
the HCL Z Abend Investigator tree view.
- Right-click the history file and select HCL Z Abend Investigator > Open History File.
- If a Z Common Components connection is not yet defined for this profile, provide the connection
information when prompted. A new connection is created in the HCL Z Abend Investigator tree view.
- The history file is opened in a new tab and is displayed in the HCL Z Abend Investigator tree view
if it does not already exist.
Viewing fault reports from a history file
To view a history file, click the entry in the HCL Z Abend Investigator tree view.
To open a fault report from a displayed history file, either double-click a fault entry row or,
from the context menu on a fault entry row, select Reanalyze.
Viewing fault reports from the Zowe Explorer Jobs tree
When a job generates one or more ABENDs, you can display the fault report from the Zowe Explorer
Jobs tree view by using any of the following methods:
From the Jobs tree node
Right-click the job that completed with an ABEND.
Select HCL Z Abend Investigator > Open Fault Report.
Note: if a job has more than one ABEND, you are prompted to select the fault report you want to open.
From a job JESMSGLG output data set (hyperlinks)
- Expand the tree node for the job that ended with an ABEND.
- Click on the JES2:JESMSGLG output data set to open it.
- Hyperlinks display for each ABEND. To open the fault report for an ABEND, hold
CTRL and click
the associated hyperlink.
- Expand the tree node for the job that ended with an ABEND.
- Click on the JES2:JESMSGLG output data set to open it.
- Open the editor context menu and select Open Fault Report.
Command Palette commands
The HCL Z Abend Investigator extension adds new commands to the VS Code Command Palette.
Open History File
This command adds a history file to the Z Abend Investigator tree view in the Zowe Explorer tool window.
When you select this command, you are prompted to provide the following information:
- A Zowe profile. If multiple profiles are defined, select a profile that has an associated
Z Common Components connection.
- A data set name. Specify the name of the history file you want to open and add to the Z Abend Investigator
tree view.
Open Fault Report
This command reanalyzes and opens a fault report. When you select this command, you are prompted to
provide the following information:
- A Zowe profile. If multiple profiles are defined, select a profile that has an associated Z Common
Components connection.
- The data set name. Specify the name of the history file that contains the fault entry you want to
reanalyze and open.
- The fault entry ID. Specify the ID of the report you want to reanalyze and open.
Overview of the Fault Report view
The Fault Report view is a collection of tabs that provide access to the different sections of the report.
Some sections contain hyperlinks that you can use to open source files at a specific line number.
In the Event Details section, you can click event hyperlinks to jump to specific event
definitions in another section.
Getting help
To ask questions or report issues related to the installation, configuration,
or use of this extension, contact HCL Support.
Zowe Explorer issues
The HCL Z Abend Investigator extension depends on Zowe Explorer.
Issues might originate from core Zowe Explorer functionality rather than the extension itself.
Examples include:
- Data set and Unix System Services (USS) file browsing
- Job management and submission
- Base Zowe Explorer commands and views
Report issues that are specific to Zowe Explorer to the Zowe Explorer issue tracker.
To determine the source of an issue and the appropriate reporting channel, consider the following:
- Error notifications include the extension name.
- Log entries displayed in the Output view are categorized by extension.
