HCL z Tools

HCL z Tools is a set of utilities that extend the functionality of Zowe Explorer.

The extension includes the following:

• Run REXX execs
• Submit jobs by specifying data set name or from in an open editor
• Terse PACK or UNPACK data sets or members
• Transmit or receive data sets ready for easy archiving
• Receive XMIT files from Desktop
• List active z/OS address spaces
• List APF authorized data sets
• Get z/OS capacity information
• Check the status of HCL Licenses
• Get IPL information
• View the current linked list set
• View the LPA data sets
• View the system name token values
• View the system page data sets
• View the system SMF data sets
• View static system symbols
• View 31 or 64 bit storage information
• View the subsystems defined on the system
• List the System SVC List
• List System variables
• View the virtual storage map
• Run console commands
• Run TSO commands
• Deploy the HCL z Tools backend to mainframe
• Add or View Metadata in program objects

Note: The Zowe Explorer is powered by Zowe CLI.

Contents

• Software Requirements
• Create a Zowe CLI z/OSMF profile
• Installation
• Installation Verification
• Advanced Configuration
• Sample Use Cases
• Manual backend Deployment

Software Requirements

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

• Installed Node.js v8.0 or later.
• Configured TSO/E address space services, z/OS data set and file REST interface, and z/OS jobs REST interface. For more information, see z/OS Requirements.
• Zowe CLI zosmf profile.

Notes:

• You can use your existing Zowe CLI zosmf profiles that are created with the Zowe CLI v2.0.0 or later.
• Zowe CLI zosmf profiles that are created in Zowe Explorer can be interchangeably used in the Zowe CLI.

Create a Zowe CLI z/OSMF profile

See the Zowe Explorer documentation for profile creation details.

Installation

The HCL z Tools requires a backend application to be installed to use the included commands. The installation can be done with the following steps:

Step 1: Install the HCL z Tools Extension

Step 2: Deploy the HCL z Tools backend exec

• Open the Command Palette, and type "Deploy HCL z Tools backend REXX exec", and select the command to run it
• Choose the Mainframe profile to deploy the REXX exec to
• Specify the name of the data set that will hold the "HCLREXX" backend exec; this data set will be created if it does not exist. This value will be used whenever the HCL z Tools backend is invoked.
• If the HCLREXX member exists, choose "yes" to overwrite the old member.

Step 3: Deploy the HCL z Tools backend Program

• Open the Command Palette, and type "Deploy HCL Tool backend Program", select the command to run it
• Choose the Mainframe profile to deploy the backend program to
• Specify a temporary data set to hold the backend program XMIT file; you will be asked to re-allocate this data set if it already exists.
• Specify a data set to hold the HCL z Tools backend program.
• The backend program will be uploaded to the mainframe and installed to the specified location.

Installation Verification

• After deploying the HCL z Tools backend, installation can be verified by running the Display HCL z Tools backend Version command. Installation is successful if the backend version is displaysed.

Advanced Configuration

You can modify HCL z Tools preferences in the extension Settings in the following ways:

• Default TSO Region Size M You can specify the region size in MB to use when running HCL z Tools TSO commands. A region size of 400 M is recommended. Region sizes of 48M to 2000M are allowed, however very small region sizes may result in 'out of memory' errors. If these occur, try a larger region size.

• Dummy Output Class You can specify which output class should be used when running HCL z Tools backend utilities. By default, class 'Z' is used a dummy class.

• Enable Telemetry High level anonymous usage information is gathered for quality improvement purposes. This telemetry can be turned off if desired.

• HCL backend Exec Data Set Name The data set where the HCL z Tools REXX backend will be located. If this does not exist it will be created for you. A PDSE with Fixed Block 80 byte or larger records is required.

• HCL backend Program Library data set Name The PDSE data set where the HCL Program object will reside. This data set will be created by the backend deployment command.

• Log Level The extension log level can be changed if required. If you encounter a problem when using HCL z Tools please set the log level to "all" prior to reproducing the problem.

• Console Commands Config New commands can be added, or the default commands customized by editing the "label" value of commands.

• Tso Commands Config New commands can be added, or the default commands customized by editing the "label" value of commands.

Sample use cases

Review the following use cases to understand how to use HCL z Tools.

• Data Sets
• Command Palette
• Extras

---

Data Sets

You can use the following functionalities when interacting with the Zowe Explorer data set tree:

• Display HCL z Tools backend Version: You can check which version of the HCL z Tools backend is installed on your mainframe.
• Open the HCL z Tools GUI: You can open the HCL z Tools interface to run many system utilities
• Copy data set Name and Copy Member Name: You can easily copy the label of a data set or member to system clipboard.
• Run as exec: You can run REXX execs from data set or members and see exec output.
• Terse Pack data sets and or members: You can use AMATERSE to PACK data sets or membrs for simplied file transfers of binary or test files.
• Terse Unpack: You can use AMATERSE to UNPACK Terse data sets.

Display HCL z Tools backend Version

1. Navigate to the Zowe Explorer tree.
2. Open the DATA SETS Bar.
3. Select the profile that you want to see the backend version of
4. Right Click and choose Display HCL z Tools backend Version The backend version is displayed as a Information Message in the Noficiation Area.

Open the HCL z Tools GUI

1. Navigate to the Zowe Explorer tree.
2. Open the DATA SETS Bar.
3. Select the profile that you want use
4. Right Click and choose Open the HCL z Tools GUI The HCL z Tools dashboard opens.

Copy data set or member Name

1. Navigate to the Zowe Explorer tree.
2. Open the DATA SETS Bar.
3. Select a profile which is displaying a data set search pattern.
4. Select the desired data set or member.
5. Right Click and choose Copy data set name or Copy member name. The resource name is placed on the system clipboard.

Run as exec

1. Navigate to the Zowe Explorer tree.
2. Open the DATA SETS Bar.
3. Select a profile which is displaying a data set search pattern.
4. Select the desired EXEC data set or member.
5. Right Click and choose Run as exec
6. If needed specify an argument string for the exec, or press enter to run with no arguments The exec is run, and the output is displayed.

Terse Pack data sets and or members

1. Navigate to the Zowe Explorer tree.
2. Open the DATA SETS Bar.
3. Select a profile which is displaying a data set search pattern.
4. Select the desired data set or member
5. Right Click and choose Terse: Pack select data set
6. Specify the output terse file name The selected file is packed, and the output is displayed.

Terse Unpack

1. Navigate to the Zowe Explorer tree.
2. Open the DATA SETS Bar.
3. Select a profile which is displaying a data set search pattern.
4. Select the desired data set or member
5. Right Click and choose Terse: unpack select data set The selected file is unpacked, and the output is displayed.

---

Command Palette

You can use the following functionalities from the vscode command palette or the HCL z Tools GUI

• List active z/OS address spaces: You can list the active address spaces, including system , started tasks, jobs and TSO users
• List APF authorized data sets: You see the current list of APF authorized data sets and check if any no longer exist
• Get z/OS capacity information: You can find out about the capacity of the current z/OS system including MSUs and numbers of CPUs
• Check the status of HCL Licenses: You can verify that your HCL licensed software has current licenses
• Get IPL information: You can find out about when the system was last IPLed and which parmlib data sets are in use
• View the current linked list set: You can see which datasets are in link list
• View the LPA data sets: You can view the datasets that are in LPA
• View the system name token values: You can see the values of all the system name tokens on the current system
• View the system page data sets: You can see the names and usage of the system page data sets
• View the system SMF data sets: You can see which datasets are recordining SMF information
• View static system symbols: You can list the current system symbols and their values
• View 31 or 64 bit storage information: You can view storage information for a user or all 64 bit tasks on the system
• List SVCs: You can see the system SVC list including the numbers, addresses and names of both standard and ESR SVC entries.
• List System Variables: You can see the current values of many system (REXX) variables, including Operating System and Hardware information
• View the subsystems defined on the system: You can see which subsystems are defined on the system and which vendor subsystems are active
• View the virtual storage map: You can view the storage ranges of virtual storage
• Edit metadata in Program Objects: You can add metadata to existing program objects
• View metadata in Program Objects: You can view metadata from existing progrma objects

Invoking commands using the Command Palette

1. In VSCode choose View, Command Palette... to open the Command Palette.
2. Type 'HCL z Tools' into the command palette to see all the possible commands.
3. Select a command with the keyboard arrow keys and press enter or use the mouse to click on the desired option.
4. In most cases you will be first asked to choose a profile to use with the command, then specify an required inputs for the command
5. The command runs and output is displayed; in many cases the output will appear in the 'HCL z Tools GUI'

Invoking commands using the HCL z Tools GUI

1. Navigate to the Zowe Explorer tree.
2. Open the DATA SETS Bar.
3. Select a profile, right click and choose Display Hcl Z Tools GUI
4. The dashbaord allows you to run any of the supported command from the menu on the left side of the toolbar on the HCL z Tools GUI

---

Extras

• Show all available Commands: You can get an overview of all the commands included in HCL z Tools; including the situations when the commands can be invoked.

• Submit a Batch Job: You can submit a batch job by specifying the full data set name. The job appears in the Zowe Explorer Jobs tree.

• Run Console Commands: You can easily run several console commands by choosing from a list. You can easily change the default commands or add new commands in HCL z Tools Settings, for example, the following could be added to "list OUTCLASS definitions":

"mainframetools.consoleCommandsConfig": [
    ...
        {
            "label": "$D OUTCLASS",
            "description": "List OUTCLASS definitions"
        },
    ...

where "label" is the command to execute and "description" the human readable description of the command.

• Run TSO commands: You can easily run TSO commands by choosing from a list, You can easily change the default commands or add new commands in HCL z Tools Settings.

• Receive an XMIT file from Workstation: You can use this command to upload and receive an XMIT format file from your workstation to the mainframe.

• Create an XMIT format data set: You can use this command to "XMIT" a PDSE or other kind of data set to an XMIT format data set. The resulting file can be downloaded to a workstation or easily sent to another mainframe system.

• Receive an XMIT file on mainframe: You can use this command to "RECEIVE" an XMIT format data set. For example, you might need to do this if you have copied an XMIT file from another mainframe and wish to extract it.

• Edit metadata in Program Objects: You can use this command to add metadata to existing program objects.

• View metadata in Program Objects: You can use this command to view metadata from existing program objects.

Show all available Commands

1. Open the Command Palette
2. Type 'HCL z Tools Show all', select the command to run it A table of all available HCL z Tools commands is displayed including the contexts in which each can be used

Submit a Batch Job

1. Open the Command Palette
2. Type 'HCL z Tools Submit job', select the command to run it
3. Choose the desired profile
4. Specify the name of the data set and member containing the desired job, press enter to submit the job The Job number appears in the Notification area

Run Console Commands

1. Open the Command Palette
2. Type 'HCL z Tools run a console command', select the command to run it
3. Choose the desired profile
4. Select the command you wish to issue, or "custom command" if you wish to run a different command
5. Press Enter to run the command The output from the command appears in the HCL z Tools Output terminal

Receive an XMIT file from Workstation

1. Open the Command Palette
2. Type 'HCL z Tools Upload and receive an XMIT file from workstation', select the command to run it
3. Choose the desired profile
4. Navigate to and select the local XMIT file using the file selection dialog, Click open
5. Specify the remote XMIT data set name and the remote 'receive' data set name, press enter The data set is uploaded to the mainframe ane then Received into the specified data set

Create an XMIT format data set

1. Open the Command Palette
2. Type 'HCL z Tools Create an XMIT format data set', select the command to run it
3. Choose the desired profile
4. Specify the data set to be converted to XMIT format
5. Specify the output data set name The data set is transmitted to the specified output data set and the result displayed

Receive an XMIT file on mainframe

1. Open the Command Palette
2. Type 'HCL z Tools receive xmit', select the command to run it
3. Choose the desired profile
4. Specify the data set to be received
5. Specify the destination data set name The data set is received into the specified destination and the result displayed

Edit metadata in Program Objects

1. Open the Command Palette
2. Type 'Edit metadata in Program Objects', select the command to run it
3. Choose the desired profile
4. In the HCL z Tools GUI, specify the program data set, member name, segment name and metadata text
5. Click Go The result of adding the metadata is displayed.

View metadata in Program Objects

1. Open the Command Palette
2. Type 'View metadata in Program Objects', select the command to run it
3. Choose the desired profile
4. In the HCL z Tools GUI, specify the program data set, member name, segment name
5. Click Go The metadata text and list of text segments found in the program are displayed.

Manual backend Deployment

The HCL z Tools backend can be deployed manually if required.

1. In VS Code open the Command Palette
2. Type 'deploy', select 'Deploy the HCL z Tools backend (using FTP and JCL)
3. The manual deployment README and a terminal is displayed
4. The sample ftp commands can be issued directly in the VS code terminal

• Any file transfer mechanism can be used instead of FTP if preferred, however;
• The 'ZTOOLS.BACKEND.XMIT' file must be transferred with 'binary' mode to a FB80 format Physical Sequential data set
• The 'HCLREXX' and 'INSTALL' files must be transferred with 'ascii' / 'text' mode to a FB80 format PDSE data set

5. The 'INSTALL' JCL can be submitted using FTP or any other batch job submission mechanism
6. Check the Completion code of the 'INSTALL' job using FTP or any other JES interface
7. Update the VS Code Settings for HCL z Tools

• Open the VS Code Command Palette, select 'Preferences: Open Settings (JSON)'
• Add the following to the settings JSON: -- Replace HLQ with your userid:

"mainframeTools.hclBackendExecDataSetName": "HLQ.ZTOOLS.BACKEND.EXEC",
"mainframeTools.hclBackendProgramLibraryDatasetName":  "HLQ.ZTOOLS.BACKEND.LOAD"