Using command line to interact with z/OS

You can use the Terminal window in VS Code to run command-line operations on your client. For example, you can use the terminal to perform file-based operations and execute any kind of Git commands on your local files right from this terminal.

In addition, you can interact with z/OS® by using commands that are provided by IBM® RSE API plug-in for Zowe™ CLI (RSE CLI plug-in), Zowe CLI, or both in the Terminal window. These commands provide various capabilities for interacting with z/OS resources that include MVS™, jobs, and USS.

To open the Terminal window, click Terminal > New Terminal or press Ctrl+`. It is opened at the bottom below the editor and inside the working directory that contains all the files that are shown in the Files view.

Comparison between Zowe CLI and RSE CLI plug-in

Both of Zowe CLI and RSE CLI plug-in provide the commands, with slight differences in command names and options, to let you perform the following tasks:

• List, create, rename, delete USS files and directories and MVS data sets and members
• Run JCL jobs
• Browse job spool files

Though the capabilities of Zowe CLI and RSE CLI plug-in are similar, the installation and configuration requirements are different:

• To use the commands provided by Zowe CLI to interact with z/OS, you must configure z/OSMF before you install Zowe CLI.

• RSE CLI plug-in extends Zowe CLI to let you interact with z/OS resources by using IBM Remote System Explorer API (RSE API) as an alternative to using z/OSMF. The RSE API is a collection of REST APIs that allow a client to work with various components on the z/OS host system, including MVS data sets, z/OS UNIX files and commands, JES jobs, and more. The overall solution results in a complete set of operations that allows you to do everything as you could do with z/OSMF. Therefore, RSE CLI plug-in is a great alternative if you have used the Remote System Explorer API with other IBM offerings such as IBM Developer for z/OS or IBM Explorer for z/OS.

For more information about the commands provided by Zowe CLI and RSE CLI plug-in, see the command mapping table.

Using RSE CLI plug-in commands

Prerequisites: Installing RSE CLI plug-in

To install RSE CLI plug-in, see the Installing IBM RSE API Plug-in for Zowe CLI section in topic Setting up integrations.

Creating an RSE profile

Zowe v2 Team Configuration file

1. Issue the command zowe config init --global-config and you will be prompted for information. After responding to the prompts, the zowe.config.json file will be added to your ~/.zowe directory. If you respond to the prompts to enter a username and password for a mainframe service, your credentials are stored securely on your computer by default.
2. Edit the zowe.config.json file in any text editor that supports JSON files to update the host and port values and other information needed in the profiles listed within the config file.
3. If the user and password were entered in step 1, you can use your profiles to access Data Sets, USS files and directories, and Jobs. If those fields were entered and accepted during the init command, you will be prompted the first time you run CLI commands. If ‘autoStore:true’ is in the config file, the credentials will be stored securely on your computer.

More information on Using global profile configuration

Zowe v1 Profiles

Note If a Team Configuration file is in place, v1 profile creation and use will not be available.

To avoid typing connection details on every command, you can create a user profile. You can create multiple profiles and switch between them if necessary. To create a profile via command line, issue the following command in the terminal:

zowe profiles create rse rseCLI --host host.company.com --port 6800 --user user --password password --base-path rseapi --reject-unauthorized false --protocol https --encoding IBM-1047

Notes:

• rseCLI: The name of the RSE profile. You can use any name that you want.
• --protocol: To override the default value with HTTP, specify --protocol http. The default value is https.

WARNING

When setting up your profile, you must specify the protocol to be used by the RSE RESTful API. Make sure your administrator configured the z/OS Explorer RSE to use https for enhanced security. For additional safety, set rejectUnauthorized: true to reject self-signed certificates, which should not be trusted in production environments.

• --reject-unauthorized: To reject self-signed certificates, specify true. The default value is false.
• --port: The port on which RSE API is running on the host. The default value is 6800. If you do not know the port number, check with your system administrator.
• --base-path: The base path of the API for the REST API operations. The default value is rseapi.
• --encoding: The default host encoding for the profile. The default value is IBM-1047.

After the RSE profile is created, you can test if the connection with the IBM Remote System Explorer API is working by typing the command to list data sets, for example, zowe rse list data-set HLQ where HLQ is a high-level qualifier or user ID that is accessible by the user ID in the profile that is created to view data sets.

Running RSE CLI plug-in commands

After installing RSE CLI plug-in, you can use it in a command-line window on your development machine. You can issue commands to perform the following tasks:

• List, create, download, upload, and delete MVS data sets and members as well as USS files and directories.
• Submit jobs, list jobs and spool files, download or view spool content, view job status, cancel a job, and delete a job.

For example, after you created your RSE profile for the user USER1 and a data set with your COBOL programs called USER1.SAMPLE.COBOL, you can work on your MVS data sets with the following commands:

• List your data sets and members:

  zowe rse ls ds USER1
  zowe rse ls all-members USER1.SAMPLE.COBOL
  

• Download members:

  zowe rse download ds "USER1.SAMPLE.COBOL(SAM1)"
  

  You will see that new folders appear on the left with the names based on your data set that contains the file SAM1. You can rename it by adding a .cbl extension to edit it in the COBOL editor, and then upload it later using drag-and-drop or via the command line.

• Check the status of your jobs:

  zowe rse ls js | grep ACTIVE
  

  The command above shows an example of how RSE CLI plug-in commands can be used in combination with other Linux® commands and scripts. This example returns the complete list of jobs and pipes that list into the Linux grep command to filter it down to show only the active jobs. This kind of capability enables you to define all kinds of batch jobs and automation for remotely interacting with z/OS.

For the full list of available commands, see IBM RSE API Plug-in for Zowe CLI commands.

Debugging CLI commands via logs

RSE CLI plugin will write logs to Zowe CLI's log file located in ~/.zowe/zowe/zowe.log. The default log level for Zowe CLI's logging is WARN. To change the log level, set the environment variable ZOWE_APP_LOG_LEVEL to the preferred level.

For more information about Zowe CLI's logging, see Setting CLI log levels.

Getting help about commands and options

To learn about a command and all options for the command, add --help after the command. For instance, by specifying zowe rse list --help, you can see all the different items that can be listed and a help response like this in the terminal:

DESCRIPTION
 -----------

   List uss file and folders, data sets and data set members, or jobs and spool
   files. Optionally, you can list their details and attributes.

 USAGE
 -----

   zowe rse-api-for-zowe-cli list <command>

   Where <command> is one of the following:

 COMMANDS
 --------

   all-members | am            List all members of a pds
   data-set | ds               List data sets
   jobs | js                   List z/OS jobs on JES spool/queues
   spool-files-by-jobid | sfbj List spool files of a z/OS job
   uss-files | uss             List USS files

GLOBAL OPTIONS
 --------------

   --response-format-json  | --rfj (boolean)

      Produce JSON formatted data from a command

   --help  | -h (boolean)

      Display help text

   --help-examples  (boolean)

      Display examples for all the commands in a the group

   --help-web  | --hw (boolean)

      Display HTML help in browser

If you want to view the help response in a web browser, enter --help-web, for example, zowe rse list --help-web.

Single sign-on support for RSE profiles

Once an RSE profile has been created users can use Single sign-on (SSO) support for connecting to the RSE API host component. JWTs are stored securely in the profile's file. For RSE profiles connecting directly to the RSE API follow the steps below:

Login to Authentication Service

1. In the terminal, enter the command zowe rse auth login.
2. Enter credentials for z/OS connection when prompted.
3. Recieve a message with information about the JWT; including the JWT's expiration date and time as well as the creation date and time.

Logout from Authentication Service

1. In the terminal, enter the command zowe rse auth logout.
2. Recieve the message JWT Token has been retired..

If obtaining authentication tokens from the API Mediation layer, see Connecting profiles to API Mediation Layer. For an example team configuration file with RSE profile authenticating with API Mediation Layer see Single sign-on support for IBM RSE CLI plugin

Run interactive TSO commands

zowe rse issue cmd "TSO EX 'HLQ.REXX.EXEC(ASKNAME)'" --shell-id myshell

The system prompts for a response:

What is your name?

Enter your response:

zowe rse issue cmd "BABE RUTH" --shell-id myshell

The system again responds:

Your name is:  BABE RUTH

The example above shows how RSE CLI plug-in commands can be used to execute interactive TSO commands using the --shell-id option. This example executes a REXX exec that prompts the user for a name. It also demonstrates how to respond and allow the interactive command to continue to completion.

Using Zowe CLI z/OSMF commands

Prerequisites: Installing Zowe CLI

To install Zowe CLI, see the Installing Zowe CLI section in topic Setting up integrations.

Creating a Zowe CLI z/OSMF profile

To interact with z/OS using a z/OSMF connection, a zosmf profile will need to be created using Zowe CLI. To learn more about the different types of profiles and creating zosmf profiles, see the Zowe CLI documentation on Using profiles.

Running Zowe CLI commands

For example, after you created your Zowe CLI z/OSMF profile for the user USER1 and a data set with your COBOL programs called USER1.SAMPLE.COBOL, you can work on your MVS data sets with the following commands:

• List your data sets and members:

  zowe files ls ds USER1
  zowe files ls all-members USER1.SAMPLE.COBOL
  

• Download members:

  zowe files download ds "USER1.SAMPLE.COBOL(SAM1)"
  

  You will see that new folders appear on the left with the names based on your data set that contains the file SAM1. You can rename it by adding a .cbl extension to edit it in the COBOL editor, and then upload it later using drag-and-drop or via the command line.

• Check the status of your jobs:

  zowe jobs ls js | grep ACTIVE
  

  The command above shows an example of how Zowe CLI commands can be used in combination with other Linux commands and scripts. This example returns the complete list of jobs and pipes that list into the Linux grep command to filter it down to show only the active jobs. This kind of capability enables you to define all kinds of batch jobs and automation for remotely interacting with z/OS.

For an overview of available Zowe CLI commands, type zowe --help.

To learn about all capabilities of Zowe CLI, see Zowe CLI Online Documentation.