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

• Requirements
• Integration with Zowe Explorer
• Configuring the extension
• Using the extension
• Enabling the AI integration
• Getting help

Requirements

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

• HCL Z Abend Investigator 16.1.0+
• HCL Z Common Components 16.1.0+
  • You must configure and deploy at least one Z Common Components server on the host you intend to use with the extension.

VS Code requirements

• VS Code 1.108.0+
• Zowe Explorer 3.2.0+
  • Assumes the user is familiar with the Zowe Explorer extension before using the HCL Z Abend Investigator.

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.
• HCL Z Data Tools
  • Allows data set hyperlinks in fault reports to open the referenced data sets.

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.

Configuring the extension

Configure the following settings under HCL Z Abend Investigator in VS Code Settings.

Language

The extension supports resources in both English (IBM1047) and Japanese (IBM939).

Use the Language setting to configure the global resource language.

Analysis Options

Use the Analysis Options setting to define data sets and source information used when refreshing Z Abend Investigator fault entries. Use commas (,) to separate multiple data set names.

Available options are IDIOPTS, IDIADATA, IDILC, IDILCOB, IDILCOBO, IDILANGX, IDILPLI, IDILPLIE, and IDISYSDB.

Pinned History Files

The hclzabendinvestigator.pinnedHistoryFiles setting maps Zowe profile names to history files that should always appear in the HCL Z Abend Investigator tree view. This is especially useful when distributing base settings to a group of users.

"hclzabendinvestigator.pinnedHistoryFiles": {
  "profileName": [
    "HISTORY.FILE.ONE",
    "HISTORY.FILE.TWO"
  ]
}

Using the extension

Configuring the Z Common Components connection

Before you begin, all previously listed requirements must be satisfied.

1. Open VS Code.
2. If necessary, create at least one Zowe profile.
3. Switch to the Zowe Explorer tool window.
4. Right-click on the profile that matches the z/OS subsystem where your Z Common Components server runs.
5. From the Z Common Components menu item, select Configure connection.
6. Enter the connection information for the Z Common Components server.

You are now ready to use the HCL 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.

For more information on Z Common Components connections, see the relevant chapter in the HCL Z Common Components extension documentation.

Managing history files

History files can be opened from the HCL Z Abend Investigator tree, the Zowe Explorer Data Sets tree, or the command palette. You can also create new history files from the command palette.

The HCL 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 an HCL Z Abend Investigator tree view, to manage history files. When you associate a Z Common Components connection with a profile, the connection displays in the tree view.

The HCL Z Abend Investigator tree view

Connection nodes display each Z Common Components host and port connection.

History Files nodes contain the history files associated with a connection.

• Pinned history files configured in hclzabendinvestigator.pinnedHistoryFiles appear automatically.
• 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 represent individual history files 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 open, 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 a history file from the Data Sets tree

History files can also be added from the Zowe Explorer Data Sets tree:

1. 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.
2. 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.
3. Right-click the history file and select HCL Z Abend Investigator > Open History File.
4. 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.
5. 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.

Opening a history file from the Data Sets view

Opening a history file from the command palette

Run HCL Z Abend Investigator: Open History File. The wizard suggests the configured default history file, pinned history files, and the 10 most recently used history files. Selected data sets are validated before they are opened.

1. Select a Zowe profile that has an associated Z Common Components connection.
2. Select or enter the history file data set name.

The history file opens in a new tab and is added to the HCL Z Abend Investigator tree.

Opening a history file from the command palette

Creating a history file

Run HCL Z Abend Investigator: Create History File from the command palette and select the Zowe profile on which to create the file. Use this command when the history file does not yet exist on the host.

The wizard lets you configure:

• The data set name and type: Library or Partitioned Data Set (PDS).
• Primary and Secondary space allocation in cylinders.
• The prefix used to generate fault entry IDs.
• The minimum number of entries before automatic space management for a Library, or the maximum number of entries maintained in a PDS.

Working with fault entries

Click a history file in the HCL Z Abend Investigator tree to open its fault entries in a separate view.

In the history file view, use the Refresh button to retrieve the latest fault entries without closing and reopening the view. Use the Columns menu to show or hide columns, drag them into a different order, or reset them.

Right-click a fault entry row to use the following actions:

• Reanalyze the fault entry and open its fault report.
• Copy or Move the fault entry to another history file.
• Delete the fault entry from the history file.

If a copy, move, or delete operation fails because the fault entry is locked, the extension can unlock the entry and retry the operation.

Opening fault reports

Fault reports can be opened from a history file, from the Zowe Explorer Jobs tree, a JESMSGLG editor, or the command palette.

From a history file

Double-click a fault entry row, or right-click the row and select Reanalyze.

Opening a fault report from a history file's fault entry

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 job node

1. Right-click the job that completed with an ABEND.
2. 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 JESMSGLG hyperlinks

1. Expand the tree node for the job that ended with an ABEND.
2. Click on the JES2:JESMSGLG output data set to open it.
3. Hyperlinks display for each ABEND. To open the fault report for an ABEND, hold Ctrl (Cmd on macOS) and click the associated hyperlink.

From the JESMSGLG context menu

1. Expand the tree node for the job that ended with an ABEND.
2. Click on the JES2:JESMSGLG output data set to open it.
3. Open the editor context menu and select Open Fault Report.

From the command palette

Run HCL Z Abend Investigator: Open Fault Report. The wizard shows all entries from the selected history file and the 10 most recently used fault entry IDs.

1. Select a Zowe profile that has an associated Z Common Components connection.
2. Select or enter the history file data set name.
3. Select or enter the fault entry ID.

Opening a fault report from the command palette

Navigating fault reports

The fault report view is a collection of tabs that provide access to the different sections of the report.

• In the Event Details section, you can click event hyperlinks to jump to specific event definitions.
• Data set hyperlinks can be opened with HCL Z Data Tools, if it is installed.
• Source-code hyperlinks open the associated source file at the designated line.

Use the Reanalyze Fault Entry editor action to refresh the active report with the configured analysis options.

Overview of the fault report view

Enabling the AI integration

The extension also provides an experimental integration with the built-in VS Code Chat experience.

The experimental integration is off by default, and can be enabled by setting hclzabendinvestigator.ai.enabled to true and then restarting VS Code. The enabled components include:

• MCP Server: provides tools to allow LLMs to interact with history files, fault entries, and fault reports when prompting in a Chat session.
• Chat Participant: provides a @abend-investigator participant for questions about using the extension.

Using the Chat Participant

In a Chat session, tag the HCL Z Abend Investigator Chat Participant with @abend-investigator to ask questions about how to use the extension. For example, you may want to know how to open a history file, how to find a fault entry, how to navigate a fault report, or how to report unexpected behavior.

The Chat Participant is mostly intended for extension how-to questions at the moment, but it may be expanded to other use cases in the future, such as assisting with host-related questions, or being able to automate specific UI workflows.

For information about history files, fault entries, or fault reports, prompt directly in Chat as described below.

Prompting for history files and fault reports

Tagging @abend-investigator is not necessary to retrieve information from history files, fault entries, or fault reports. The MCP Server makes tools available to the selected chat model, which can use them when appropriate.

For example, ask for entries in HISTORY.FILE.NAME, or for a summary of the report for HISTORY.FILE.NAME(FAULTID).

If you do not specify a Zowe profile, the tools use the only profile with a configured connection, or ask you to select one when several are available.

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.