Explorer for ChangeMan ZMF

Explorer for ChangeMan ZMF® provides the ability to manage and edit ZMF components within a ZMF system. Components may be browsed from Baseline libraries and checked out to a Package on the mainframe where they may then be retrieved to the local desktop computer, edited and subsequently uploaded back into the package for subsequent ZMF processing. After checking the component back into the package, a build of the component may then be issued. As many components make use of copybook files, these may optionally be retrieved to allow a more seamless experience when editing the source component locally.
Depending upon the language editor of choice within VSCode, the source code may be COBOL, HLASM, PL/1 plus support for JCL.

Contents

• Prerequisites
• Installing
• User Guide
• Accessing the ChangeMan ZMF tree view
• Technical Assistance and support for Explorer for ChangeMan ZMF

Prerequisites

Prior to using Explorer for ChangeMan ZMF, please ensure that you have the following prerequisites in place:

• Note that older style individual profiles as used in zowe 1 are no longer supported.
• A zowe 2 profile is required to run the ZMF Explorer V2. The zowe 2 profile will typically exist in homedir/.zowe in the file zowe.config.json which would usually be supplied by an admin and distributed to team members. This will be the case if the user is also a ChangeMan ZMF plugin for zowe cli user.
• It is possible to have a profile located in the VSCode workspace where it can be used in preference to or in conjunction with the 'Teams profile' mentioned above. This may be more useful for those users who are predominantly ZMF Explorer users and may not have a 'Teams profile'.
• A new parameter has been added to the ChangeMan ZMF Explorer Settings allowing the user to specify whether to combine any Worskpace profile with the Teams profile or optionally only use the Workspace based profile. Regardless of the setting, if no Worksapce profile exists then the Teams profile located in homedir/.zowe will be attempted.
• Access to Mainframe with valid userid(s)
• Access to ChangeMan ZMF® subsytems
  • Version 8.2 Patch 7 or higher release with one of the following hotfixews:
    • ZMF 8.2 Patch 7 - ZMF8.2.7.018
    • ZMF 8.3 - ZMF8.3.0.019
• Your chosen language editor. e.g. IBM z/Open Editor
• It is recommended that you install a File Icon Theme extension - Material Icon Theme. You can install this from the Extension menu. The theme provides customization options to allow you to set your preferred icon colors in the treeview.

Installing

Explorer for ChangeMan ZMF availability is documented in the ChangeMan ZMF Community pages and installed as a VSCode extension. For more information on updated versions of the ZMF Explorer, please visit the ChangeMan ZMF Community page ChangeMan ZMF Explorer is installed via the VSCode Extensions Marketplace.

Configuration

After completing the installation of the Explorer for ChangeMan ZMF, edit the Extension settings for the ChangeMan ZMF Explorer within VSCode. it is recommended that you use the "User" location. Here you should set the defaults that you wish to apply and set up JCL job cards etc. The logging level is set to "Info" by default. You should only change that on request.

For information on zowe 2 profiles, please visit the zowe documentation. An introduction to zowe 2 profiles can be found here Zowe CLI — Getting Started, Made Easy! Also some example profiles can be found in the ChangeMan ZMF Community site zowe 2 Profiles and how to use them with the ChangeMan ZMF plugin for zowe CLI

Ensure that you enter a valid folder location, This location will be used to place local files downloaded from ZMF until such time as they are either deleted or checked back into a ChangeMan ZMF package on the mainframe. If the folder location does not exist, it will be created when the ZMF Explorer extension is run. At any time, you may cleanup files within that folder for example, if you copied a component down from a package to your local machine that you then no longer required and do not wish to check back into the ZMF package. You should also set the defaults that you wish to apply and set up JCL job cards etc. The logging level is set to "Info" by default. You should only change that on request.

Ensure that you have the correct file associations set within VSCode depending upon the language editor you are using. If you are using IBM z/Open Editor for example, this is done in the Settings as "Include File Extensions'. Using IBM z/Open Editor, you should ensure the following are specified depending in the languages you wish to use.
Refer to the documentation of the language editor that you are using for further information.

    "files.associations": {
        "*.CBL*": "cobol",
        "*.CPY*": "cobol",
        "*.PLI*": "pl1",
        "*.INC*": "pl1",
        "*.ASM*": "hlasm",
        "*.HLASM*": "hlasm",
        "*.JCL*": "jcl",
        "*.REXX*":"rexx",
        "*.REXXC*":"rexx",
    },

Be aware that z/Open Editor V3.x introduced breaking changes and the preious zopeneditor.propertygroups is no longer used and should be removed and replaced by a new zapp.yaml file containing the local language properties and placed in a folder that is opened or exists in a VSCode Workspace. IBM have indicated that this may change based on feedback. You should refer to the relevant IBM documention on creating the zapp.yaml file - Configure your applications with ZAPP files

A simple zapp.yaml can be seen here:

name: sample
description: For IBM Z Open Editor 3.0.0 or newer. 
version: 3.0.0
author:
  name: rocketsoftware

propertyGroups:
  - name: local-cobol-files
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "d:/myFolder/**"
      - name: syslib
        type: mvs
        locations:
          - "DJACKSO.TEST.COBOL"
  
  - name: local-pl1-files
    language: pl1
    compilerOptions: not(!)
    libraries:
      - name: syslib
        type: local
        locations:
          - "d:/myFolder/**"
  
  - name: local-asm-files
    language: hlasm
    libraries:
      - name: syslib
        type: local
        locations:
          - "d:/myFolder/**"
      - name: syslib
        type: mvs
        locations:
          - "DJACKSO.TEST.ASM"    

  - name: local-rexx-files
    language: rexx
    libraries:
    - name: syslib
      type: local
      locations:
        - "d:/myFolder/**"

It is also recommended that you change a setting in VSCode so that popup dialogs are more in line with the VSCode theme. To do this, enter VSCode Manage Settings and in the 'Search Settings" option enter "dialog". You are presented with "Windows Dialog Style" set to "Native". Use the drop down list box and change this to "Custom".

User Guide

Create a Profile

With version 2, there is only a single profile file - zowe.config.json and its associated schema file zowe.schema.json If you are an existing zowe cli V2 user, these files will already exist in the homedir/.zowe folder. If you are not an existing zowe cli user, you may find example files in the Community forum that you can adapt to your own requirements.

Explorer for ChangeMan ZMF uses the same Zowe CLI V2 profiles for the ChangeMan ZMF CLI plug-in interface to access ZMF maintained libraries on the mainframe.
As such, if you already have a ChangeMan ZMF plug-in Zowe CLI system definitions in the profile definition file, these will automatically appear in the Explorer for ChangeMan ZMF tree and may be used to access ChangeMan ZMF maintained libraries.

In Zowe V2, userid and password are securely stored in the Operating System's secure credential vault and no longer in plain text.

Not all ZMF Explorer users may be Zowe cli users and as such may not have the zowe.config.json file present and indeed, may not have the homedir/.zowe folder present. This is catered for in the ZMF Explorer. You may create a folder on your machine e.g. d:/ConfigFolder. In this folder, place a zowe.config.json and the zowe.schema.json files that you can obtain from the Community Forum. You can then edit the zowe.config.json to your own particular preferences. This is clarified in the Forum where you will find a blog post and links to other reference material. Do not modify the zowe.schema.json file. Note that the zowe.schema.json file must coexist with the zowe.config.json.

When you start VSCode, open the folder with "File - Open Folder.." and select the D:/ConfigFolder. This folder now becomes your VSCode Workspace folder. Then you may start the ZMF Explorer by clicking the icon. At any time, you may open the zowe.config.json file and modify it and the ZMF Explorer will silently reload using the new file contents. Alternatively, you have a number of config.json files each with different configurations which you can then copy and paste into the zowe.config.json and save whioch will cause the ZMF Explorer to silently reload. The suggestion here is to have a zowe.config.json file into which you can then copy and paste from one of your config.json variations. You sholuld alwasy have a local zowe.config.json that the ZMF Explorer can access.

New settings option for Profile usage

CHangeMan ZMF V2 introduces a new parameter setting that allows the user to specify whether to merge a Workspace project level profile with the zowe V2 profile from the homedir/.zowe location - opr alterantively only use a Workspace project level folder location.
The default is to merge any existing Workspace profile with any existing zowe V2 profile from the homedir/.zowe folder. If the option is made to use only the Workspace folder - then if that folder doesn't exist, then an attempt is made to look for the homedir/.zowe folder as a fallback.

Hiding a ZMF system

Having created one or more ZMF system definitions in the zowe.config.json file, you may wish to not have the ZMF system show in the tree. A system may be 'hidden' from view by clicking the relevant icon. Once a profile is hidden, you may retrieve it back into view by clicking the icon and any hidden profile(s) will be presented. Selecting a hidden profile will then reestablish that profile back into the tree.
However, using a Workspace specific profile definition might be a more preferred option in that instance.

Creating and modifying Filters

ChangeMan ZMF systems can comprise of many thousands of components. In order to focus on the items that you wish to work with, you may create a filter for each ChangeMan ZMF system by clicking on the 'Edit Filter' icon against the profile name.

Filter on:

• Application name(s). A valid application filter might be A*, BC*,CDE,FGHI etc. Or clear the filter prompt and press enter for all applications.
• Baseline libraries. A valid Baseline library filter might be CP*,SRC etc. Clear the filter prompt and press enter for all baseline libraries
• Baseline components. Here you may filter on specific components. A wildcard is permitted.
• Package libraries. Like Baseline libraries, you may enter a list of package libraries that you wish to filter on.
• Package components. Here you may filter on specific components. A wildcard is permitted.

Once a filter is created, it will not be automatically activated. A new icon will appear showing the filter status and hovering over the profile name will show the filter criteria. Clicking on the icon will then toggle the filter inactive/active and the tree will be rebuilt based on the filter criteria. It is recommended to contract the tree before toggling the filter status.

Accessing the ChangeMan ZMF tree view

When you click on the ZMF system in the tree view, a list of Applications are displayed. YOu can then select an Application which then displays Baselines and Packages. You may expand the tree further to display components. Selecting a component (left click) will download that component to the local computer. Baselines components can only be viewed. Right click on components offers more options that can be performed. These options are displayed based on the status of the component and the tree is refreshed as actions are taken that may cause the right click options to be refreshed.

Accessing Batch job output

As of V2.0.1 of the ZMF Explorer, you now have the option to view the batch job output of a Packge Component batch compile submission. To make use of this option, it is necessary that you have z/OSMF installed and configured on your Mainframe system. You should check with your System Programmer to determine if that feature is enabled and configured. To make use of this feature, the z/OSMF profile must be defined in the zowe.config.json .If you were supplied a Teams profile, contact your Admin who maintains the file to chekc if z/OSMF is configed in the profile correctly. Each ZMF profile within the zowe.config.json will need to have an additional parameter zosmfProfile present as in this example:

"u820all": {
                "properties": {
                "basePath": "/zmfrest",
                "port": 9992,
                "protocol": "https",
                "zosmfProfile": "zosmf"
                },
                "type": "zmf"
            },

Making use of VSCode File Icon Themes

The ZMF Explorer supports File Icon Themes that may be enabled within VSCode. ZMF Explorer makes use of 2 icons - the Folder icon and a File icon. However the default VSCode File Icon theme "Seti' does not provide an icon for a Folder. so no folder icon will be displayed if using that File Icon Theme. You can check which File Icon theme is in use by clicking 'View' 'Command Palette' and searching on 'File Icon'. Switching for example to the 'Minimal' icon theme will then display icons, in the ZMF tree view, however, a recommended File Icon Theme extension that you may wish to install is the Material Icon Theme. You can install this from the Extension menu. The theme provides customization options to allow you to set your preferred icon colors.

Technical Assistance and support for Explorer for ChangeMan ZMF

The Explorer for ChangeMan ZMF extension is made available to customers in accordance with the terms and conditions contained in the provided End-User License Agreement (EULA).

If you are on active Rocket Software support for ChangeMan ZMF, technical assistance and support is provided via the ChangeMan ZMF Community pages: ChangeMan ZMF Community page

Copyright 2024 Rocket Software