Zowe Explorer for IBM CICS Transaction Server

The Zowe® Explorer for IBM® CICS® Transaction Server extension (formerly IBM CICS for Zowe Explorer) adds additional functionality to the popular VS Code extension, Zowe Explorer. This extension allows interactions with CICS regions and resources, and the ability to run commands against them.

Contents

• Zowe Explorer for IBM CICS Transaction Server
  • Contents
  • Software requirements
  • Features
  • Getting started
    • Connecting using a CICS profile
      • Creating or updating a CICS profile
      • Additional details for making the connection
    • Hiding CICS profiles
    • Deleting CICS profiles
    • Using CMCI's client allowlist
  • CICS resources
    • Show logs for a region
    • Show and filter resources in a region
    • Show and filter resources in a plex
    • Show and filter resources in an 'All' resource tree
    • Inspect CICS resources
    • Show attributes
    • Enable and disable
    • New Copy and Phase In
    • Open and Close Local Files
    • Purge Task
    • Inquire functionality
    • View data sets under libraries
  • Untrusted TLS certificates
  • Usage tips
  • Providing feedback or help contributing
    • Checking the source of an error
    • Filing an issue

Software requirements

Ensure that you meet the following prerequisites before you use the extension:

• Install VS Code
• Install Zowe Explorer v3

Tip: See Troubleshooting guide for solutions to common problems.

Features

• Load profiles directly from a locally installed Zowe instance.
• Create new CICS profiles and connect to them.
• Work with a tree structure of resources including programs, local transactions, and local files within CICSplexes and CICS regions.
• Perform actions such as Enable, Disable, New Copy, and Phase In directly from the UI.
• Perform additional actions on local files including Open and Close directly from the UI.
• Perform a Purge on tasks with the option to select from a Purge or Force Purge.
• View and search attributes of resources and regions by right-clicking and using the dynamic filtering feature.
• Apply multiple filters to regions, programs, local transactions local files, and/or tasks.

To install CICS Extension for Zowe Explorer see Installation.

Getting started

Connecting using a CICS profile

CICS profiles are stored with other Zowe profiles in team configuration JSON files. These are used for both Zowe CLI and VS Code extension connections and documented as part of Zowe CLI.

CICS profiles inherit properties from base profiles in the same way as Zowe profiles. Secure storage for credentials also uses the Zowe profile mechanism with secure arrays and autoStore.

The profile defines a connection which must point to a CICS region's CICS Management Client Interface (CMCI) TCP/IP host name and port number. CMCI could be hosted by a WUI in a CICSplex or by a stand-alone System Management Single Server (SMSS) region.

This extension supports the following forms of authentication, configured in a Zowe profile in your team configuration file:

• Basic (user ID and password).
• Multi-factor (MFA) by using the CMCI JVM server.
• SSL certificates.

Creating or updating a CICS profile

1. In Zowe Explorer, select the + button in the CICS tree.

2. Pick an existing CICS profile to add to your tree or select Create a New Team Configuration File or Edit Team Configuration File to create a new CICS profile.

3. Within the profile section in a team configuration file (zowe.config.json), add a new cics profile type.

4. Select the + button in the CICS tree and click the newly created profile to load it into view.

   4.1. The following example shows a CICS profile stored in a configuration file. The host, port, and protocol in a CICS profile must point to a valid CMCI connection:

   {
     "$schema": "./zowe.schema.json",
     "profiles": {
       // this string will be the name of your CICS connection in the tree
       "cics-connection-name": {
         "type": "cics",
         "properties": {
           // replace the host, port, and protocol with your CMCI connection details
           "host": "cics.example.com",
           "port": 1490,
           "protocol": "https",
           // reject self-signed server certificates if using https?
           "rejectUnauthorized": true,
         },
       },
     },
   }
   

   4.2. The following example shows a CICS profile stored in a configuration file. The host, port, and protocol in a CICS profile must point to a valid CMCI connection, additionally, we need to add certFile and certKeyFile fields which point to your certificate PEM and Key file::

     {
       "$schema": "./zowe.schema.json",
       "profiles": {
         // this string will be the name of your CICS connection in the tree
         "cics-ssl-connection-name": {
           "type": "cics",
           "properties": {
             // replace the host, port, and protocol with your CMCI connection details
             "host": "cics.example.com",
             "port": 1490,
             "protocol": "https",
             // reject self-signed server certificates if using https?
             "rejectUnauthorized": false,
             "certFile": "/path/to/cert.pem",
             "certKeyFile": "/path/to/key.pem"
           },
         },
       },
     }
   

Tip: Create a profile without the user and password properties and expand the profile after loading it into the CICS view. The CICS extension will then prompt you for the user and password fields to be stored in the secure array.

To show more than one CICS profile in the tree, select the + button and choose from the list of profiles. Only profiles not already included in the CICS tree will be shown.

Additional details for making the connection

If you are connecting to a CICSplex, you can optionally specify the cicsPlex or regionName properties to scope the set of CICSplexes or CICS regions shown in the CICS tree. Instead of a region name, you can also enter a CICS System Group.

Configuring a CICS region for CMCI is a system programmer task and more details can be found in Setting up CMCI with CICSPlex SM or Setting up CMCI in a stand-alone CICS region. If your CMCI connection is configured to use a self-signed certificate that your PC's trust store does not recognize, see Untrusted TLS certificates.

You can also view your Zowe profiles using Zowe CLI by using the command zowe profiles list cics from a terminal.

Hiding CICS profiles

Right-click a CICS profile and select Manage Profile to show profile options. Choose Hide Profile to hide it from the CICS view. To add it back, click the + button and select the profile from the quick pick list.

Deleting CICS profiles

1. Right-click a CICS profile and select Manage Profile to show profile options.

2. Choose Delete Profile to open the configuration file that contains the profile you want to delete.

3. Edit the config file to remove the CICS profile entry.

Using CMCI's client allowlist

If your CICS CMCI JVM server is configured with a client allowlist, the User-Agent header included in the CMCI requests must be included in this list. To check the User-Agent header that will be sent on each request, issue the Zowe Explorer for IBM CICS TS: Copy User Agent Header command from the command palette. This will copy the header to your clipboard.

The header uses the format:

zowe.cics-extension-for-zowe/<CICS extension version number> zowe.vscode-extension-for-zowe/<Zowe Explorer version number>

Resulting in a header looking something like:

User-Agent: zowe.cics-extension-for-zowe/3.11.0 zowe.vscode-extension-for-zowe/3.3.0

CICS resources

Expand a CICS profile to explore any CICSplexes and CICS regions that are available. CICS regions are nested within the CICSplex they are part of. CICS resources are available both within an individual CICS region and across the CICSplex. Regions that are not active - defined to a CICSplex but without a running job - are shown with a no entry sign.

Show logs for a region

Right-click a CICS region and select the Show Region Logs option to reveal the CICS region's logs in the Zowe Explorer Jobs tree.

You must have a connection configured in Zowe Explorer with access to the CICS region's logs.

Tip: A good way to associate CICS and z/OSMF profiles for the same host is to nest them under the same parent profile, using Zowe CLI nested profiles.

Show and filter resources in a region

The resource types supported by the CICS extension are Programs, Transactions, Local Files, Tasks, Libraries, Pipelines, TCP/IP services, URI maps, and Web services, JVM servers and Bundles.

Expand a CICS region to show folders containing each resource type. The number of resources in a resource tree appear in square brackets next to the tree name.

The list of resources are pre-filtered to exclude many of the IBM-supplied items; these default filters are configured in the settings for the CICS extension.

Use the Filter icon against a resource type to apply a filter. This can be an exact resource name or can include wildcards. The filter history is saved so you can recall previous filters.

To reset the filter to its initial criteria, use the Clear Filter icon against the resource type. If you want to see all resources in a region (including IBM supplied ones) you can use \* as a filter.

Tip: To apply multiple filters, separate entries with a comma. You can append any filter with an \*, which indicates wildcard filtering.

Show and filter resources in a plex

In the same way as filtering resources in a region, you can apply a filter on resources in a plex. Use the Filter and Clear Filter buttons against the Regions tree element to manage filters across the whole set of regions and resources.

Show and filter resources in an 'All' resource tree

CICSplexes contain an All Programs, All Local Transactions, All Local Files, and All Tasks trees which show resources from all regions in the plex.

To view resources under these trees, use the Filter icon inline with the tree and apply a filter.

If the applied filter results in more than 500 records, either change the filter to narrow down the result set, or click the view X more ... item to retrieve 'X' more resources.

Tip: The default 500 count can be modified via the Record Count Increment property in the settings for the CICS extension.

Inspect CICS resources

View resource information without using the CICS tree. Access the command palette and filter for Inspect CICS Resource. You'll be prompted for your Zowe CICS profile, a resource type, and a resource name. The CICS Resource Inspector opens showing the details of the specified resource.

Show attributes

To show the attributes for a CICS resource, right-click on the desired resource and select the Inspect Resource option. The CICS Resource Inspector opens, listing all attributes and their values. The table of attributes has a search box that lets you search for specific attributes.

To show the attributes for a CICS region, right-click on the desired region and select the Show Attributes option. An attribute page opens, listing all attributes and their values. The attributes page has a filter box at the top that lets you search for attributes matching the criteria.

Enable and disable

Right-click against a program, local transaction, local file, JVM server or bundle to open the pop-up menu and select Disable [CICS resource] to disable the resource. When a resource is already disabled the first option becomes Enable [CICS resource] to allow its enablement state to be toggled. A disabled resource is identified by a (Disabled) label next to its name.

New Copy and Phase In

Use New Copy and Phase In actions against a CICS program to refresh the program only if it is not currently in use (New Copy), or to use the new version of the module for all future requests (Phase In). This could be after you have edited a COBOL program source and successfully compiled it into a load library so that you can test your change.

The newcopycnt for a program which is greater than zero is shown next to the program item in the CICS resource tree.

Open and Close Local Files

Right-click against a closed local file and perform the Open Local File menu action to toggle the openstatus attribute to OPEN.

To close a local file, right-click against an open local file and perform the Close Local File menu action. This brings up a prompt on the bottom right corner requesting to choose one of Wait, No Wait, or Force for the file busy condition. Once an option has been selected, the local file name is appended with a (Closed) label upon success.

Purge Task

Right-click against a task and click the Purge Task command. This opens a prompt asking whether to perform a Purge or Force Purge.

Select the appropriate condition to perform the purge.

Inquire functionality

Right-click against a task and perform the Inquire Transaction command. This inquires the associated local transaction (that is, the transaction with the name that matches the tranid attribute of the selected task) under the local transactions folder.

The same can be done on a local transaction to find the associated Program by executing the Inquire Program right-click menu action against a local transaction.

View data sets under libraries

Expand libraries of a region to view specific data sets belonging to a library. Right-click on libraries to Show Attributes to view library attributes. Similarly, right-click on data sets to Show Attributes to view data set attributes.

Untrusted TLS certificates

If the CMCI connection is using a TLS certificate that your PC does not have in its trust store, then by default the connection will be rejected untrusted with the error SELF_SIGNED_CERT_IN_CHAIN - self signed certificate in certificate chain. To override this behavior, use the setting rejectUnauthorized=false on your CICS connection profile.

Usage tips

• Most menu actions available by right-clicking a profile or resource can be applied to multiple items by multi-selecting nodes of the same type before right-clicking.

  • To multi-select, either hold Ctrl/Cmd key while selecting resources, or select the first item in a list of nodes then hold Shift and click both the last item to select a consecutive list of nodes.

• Click the Refresh icon at the top of the CICS view to reload the resources in every region.

Providing feedback or help contributing

Checking the source of an error

Before filing an issue, check if an error is arising from the Zowe Explorer for IBM CICS Transaction Server extension and not the Zowe Explorer extension by expanding the error message and checking if the Source is Zowe Explorer for IBM CICS Transaction Server (Extension).

Error messages arising from the Zowe Explorer extension identify the Source as Zowe Explorer(Extension).

Filing an issue

Before filing an issue, check the Troubleshooting guide first to ensure that the issue has not already been addressed.

To file issues, use the Zowe Explorer for IBM CICS Transaction Server issue list, or chat with use on Slack by indicating the message is for the Zowe Explorer for IBM CICS Transaction Server extension.