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 commandsopen in new window 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 z/OS UNIX System Services.

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 z/OS UNIX System Services 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/OSMFopen in new window 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

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 z/OS UNIX System Services 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.

Searching for files on UNIX System Services by content or file name

With RSE API Plug-in for Zowe CLI, you can search for files in UNIX System Services by file name or content. There are two types of outputs depending on whether content is included in the search query or not:

If content is not included, you will see a list of file paths that match the criteria passed in with the number of matches.

$ zowe rse search uss /u/user "*.txt"

Found 3 results for search:
  - /u/user/example.txt
  - /u/user/test/example2.txt
  - /u/user/test/example3.txt

If content is included in the query and matches are found in the referenced file, you will see a list of file paths and its matched lines from the file's content.

$ zowe rse search uss /u/user "*.txt" --t "hello world!"

Found 2 results for search:

/u/user/test/examples/example.txt -- 2 matches:

1) "hello world! ..."
   Line: 1 -- Start Offset: 1 -- end Offset: 17

1) ".. hello world!"
   Line: 5 -- Start Offset: 23 -- end Offset: 40

/u/user/test/examples/example.txt -- 1 match:

1) "hello world! ..."
   Line: 13 -- Start Offset: 12 -- end Offset: 30

To try this yourself, run the following command:

zowe rse search uss <uss-path> <file/pattern>

There are also options that can be passed to this command such as:

--text | -t (string) The text pattern to be searched for in the provided file. Example: hello
--regex-file-name | --rfn (boolean) Regex for filename. If Regex pattern is not used, wildcard patterns are used
--regex-content | --rc (boolean) Regex for content. If Regex pattern is not used, wildcard patterns are used.
--case-sensitive-file-name | --csfn (boolean) Case-sensitive for filename
--case-sensitive-content | --csc (boolean) Case-sensitive for content
--path-results-only | --pro (boolean) Reduce the response to only the path results

When text is not passed in as an option by default the CLI command will act as if --pathResultsOnly is set to true, since there will be no matches to show, which provides a cleaner output (see example above).

Editing files in the terminal

The edit command enables you to edit the contents of a data set or UNIX file using the terminal and the default editor. To edit a data set, provide the full name, such as HLQ.DATASET for a sequential or HLQ.DATASET(MEMBER) for a partitioned data set member. To edit a UNIX file, specify the complete path, such as /u/user/test.txt, as shown in the syntax.

Edit a Data Set

zowe rse-api-for-zowe-cli edit data-set <dataset-name> [options]

Edit a UNIX System Services File

zowe rse-api-for-zowe-cli edit uss-file <file-path> [options]

When run without any additional options, the command launches the default editor of the operating system and opens the contents of the specified data set or UNIX file for editing. You can also specify a different editor using --editor option, such as --editor vim / --editor nano. Make the necessary changes in the editor, then save and close it. After that, the terminal prompts you to confirm the upload:

Overwrite remote with local edits? (Answer after editing) y/n.

y → Uploads changes to the mainframe successfully
n → Exits without uploading; temporary file remains for further editing.

Options to Edit File

--extension | --ext Set the file extension of the file for editing to leverage an editor's file-type-specific formatting, that is, "--extension jcl".
--editor | --ed Override the default editor for the specified file type. Set the option to the editor's executable file path or program name, that is, "--editor vim".
--binary | -b Transfer the file content in binary mode.
--encoding | --ec Transfer the file content using encoding mode and ensure that data conversion occurs based on the specified file encoding.

Comparing files in the terminal

The compare command enables you to compare the contents of two data sets, UNIX files, or spool files, as well as compare local files to a data set, UNIX file, or spool file using the terminal and the default browser. To compare data sets, provide the full name, such as HLQ.DATASET for a sequential or HLQ.DATASET(MEMBER) for a partitioned data set member. To compare UNIX files, specify the complete path, such as /u/user/test.txt, as shown in the syntax. To compare spool files, specify the spool description in the format of jobName1:jobId1:spoolId1, as shown in the syntax.

Compare data sets

zowe rse-api-for-zowe-cli compare data-set <dataSetName1> <dataSetName2> [options]

Compare a local file with a data set

zowe rse-api-for-zowe-cli compare local-file-data-set <localFilePath> <dataSetName> [options]

Compare a local file with a spool file

zowe rse-api-for-zowe-cli compare local-file-spool-dd <localFilePath> <spoolDescription> [options]

Compare a local file with a z/OS UNIX file

zowe rse-api-for-zowe-cli compare local-file-uss-file <localFilePath> <ussFilePath> [options]

Compare spool files

zowe rse-api-for-zowe-cli compare spool-dd <spoolDescription1> <spoolDescription2> [options]

Compare a z/OS UNIX File

zowe rse-api-for-zowe-cli compare uss-files <ussFilePath1> <ussFilePath2> [options]

When run without any additional options, the command launches in the terminal and shows the contents of the specified files with the differences between them highlighted. Pass the --browser-view option to open the files and display the highlighted differences in the default browser.

Options to Compare File

--encoding | --ec Transfer the content of the first data set using encoding mode, which performs data conversion based on the specified file encoding . If encoding mode is set and the encoding2 flag is not set, both data sets are transferred using encoding mode.
encoding2 | --ec2 Transfer the content of the second data set with its own encoding mode.
context-lines | --cl The number of context lines that display before and after detected non-matching lines. By default, all matching lines are displayed. If you want to limit the amount of data returned to only lines with differences, use the context lines option to reduce the matching lines to only those before and after non-matching lines. Using a value of 0 removes all matching lines.
browser-view | --bv Opens the differences between two given files in the browser.
seqnum | --sn If you compare two files that contain sequence numbers, this option controls whether the sequence numbers are removed from the end of each string. By default, sequence numbers are preserved. Use the --no-seqnum option to exclude them.

Working with z/OS UNIX Archive Files

The archive commands enable you to interact with files and directories inside archive files such as .zip or .tar located in the z/OS UNIX System Services. You can list archive contents, retrieve file data, update files using local content, or delete files within an archive.

List Files in an Archive

Lists the files and directories inside a z/OS UNIX System Services archive. You can specify a relative path to narrow down the listing. This enables quick inspection of the archive contents without file extraction and is ideal for archive structure verification before you perform further operations.

# Usage:
zowe rse-api-for-zowe-cli archive list-files <archivePath> [relativePath]

# List root directory in the archive
zowe rse-api-for-zowe-cli archive list-files "/u/ibmuser/archive.zip"

# List contents of a specific folder within the archive
zowe rse-api-for-zowe-cli archive list-files "/u/ibmuser/archive.zip" "test/"

Aliases: lf

Get File Content from an Archive

Retrieves the content of a file within a z/OS UNIX System Services archive. You can view the content directly or download it locally with encoding support. This command is useful to inspect or save specific files from the archive and supports flexible options to handle different file types and encodings.

# Usage:
zowe rse-api-for-zowe-cli archive get-content <archivePath> <relativePath> [options]

# Retrieve the content of a file from archive
zowe rse-api-for-zowe-cli archive get-content "/u/ibmuser/archive.zip" "test/tst.txt"

# Download file from archive and save locally
zowe rse-api-for-zowe-cli archive get-content "/u/ibmuser/archive.zip" "test/tst.txt" -f "./local-output.txt"

# Use additional encoding options when required
zowe rse-api-for-zowe-cli archive get-content "/u/ibmuser/archive.zip" "test/tst.txt" -f "./local-output.txt" --encoding IBM-1047 --local-encoding utf-8

Aliases: gc

Update File Content in an Archive

Updates the content of a file inside a z/OS UNIX System Services archive using a local file. This enables you to modify and create new files within the archive without full extraction and also supports binary and encoding options as follows. It provides a convenient way to keep archive contents up to date.

# Usage:
zowe rse-api-for-zowe-cli archive update-content <archivePath> <relativePath> -f <localFilePath> [options]

# Update archive file using content from a local file
zowe rse-api-for-zowe-cli archive update-content "/u/ibmuser/archive.zip" "test/tst.txt" -f "./updated.txt"

# Include encoding when required
zowe rse-api-for-zowe-cli archive update-content "/u/ibmuser/archive.zip" "test/tst.txt" -f "./updated.txt" --encoding IBM-1047 --local-encoding utf-8

Aliases: uc

Delete a File from an Archive

Deletes a file or directory from within a z/OS UNIX System Services archive. This command enables you to clean up archive contents remotely without unpacking the archive. It safely removes unwanted items directly on the server.

# Usage:
zowe rse-api-for-zowe-cli archive delete <archivePath> <relativePath>

# Delete a file from the archive
zowe rse-api-for-zowe-cli archive delete "/u/ibmuser/archive.zip" "test/tst.txt"

Aliases: d

Options

The following are the common options supported by applicable archive commands for get-content and update-content:

--file <path> | -f
Specifies the local file path used to upload content to or download content from an archive. When used with get-content, this path serves as the destination where the archive file content is saved. When used with update-content, it serves as the source of the local file that is uploaded into the archive. If not specified with get-content, the content is displayed in the terminal or returned inline.
--binary | -b
Indicates whether the transfer is treated as binary. By default, this is true. If set to false, the transfer occurs in text mode to enable character encoding conversions.
--encoding <hostEncoding> | --ec
The character encoding used by the file on the z/OS UNIX host. When you retrieve or upload a text file, this option ensures accurate translation between the host and local environments. For example: --encoding IBM-1047.
--local-encoding <encoding> | --lc
The encoding used on your local system for the file you upload or save. Use this when the local file uses a specific character set different from the host. For example: --local-encoding utf-8.

Command Summary

Command	Description	Alias
`list-files`	List contents of a z/OS UNIX archive	`lf`
`get-content`	Get file content from an archive	`gc`
`update-content`	Update a file inside an archive using a local file	`uc`
`delete`	Delete a file or folder from an archive	`d`

Working with VSAM data sets

RSE API v1.2.3 introduces VSAM support for allocateLike and delete actions.

Allocate Like VSAM:

Create another VSAM data set with identical attributes:

zowe rse create ds HLQ.SAMPLE.ALL --like HLQ.SAMPLE.VSAM

Delete VSAM:

zowe rse delete ds HLQ.SAMPLE.VSAM

Running 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 preceding example shows how RSE CLI plug-in commands can be used to execute interactive TSO commands by 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.

Getting help about commands and options

To learn about a command and all options for the command, add --help after the command. For example, 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 z/OS UNIX System Services 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 z/OS UNIX System Services 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.

Online Help rendered as a web page

Debugging CLI commands via logs

RSE CLI plug-in 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 levelsopen in new window.

Using Zowe CLI z/OSMF commands

Prerequisites

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)"
```
1
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
```
1
The preceding command 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 the capabilities of Zowe CLI, see Zowe CLI Online Documentationopen in new window.

# Using command line to interact with z/OS

# Comparison between Zowe CLI and RSE CLI plug-in

# Using RSE CLI plug-in commands

# Prerequisites

# Running RSE CLI plug-in commands

# Searching for files on UNIX System Services by content or file name

# Editing files in the terminal

# Edit a Data Set

# Edit a UNIX System Services File

# Options to Edit File

# Comparing files in the terminal

# Compare data sets

# Compare a local file with a data set

# Compare a local file with a spool file

# Compare a local file with a z/OS UNIX file

# Compare spool files

# Compare a z/OS UNIX File

# Options to Compare File

# Working with z/OS UNIX Archive Files

# List Files in an Archive

# Get File Content from an Archive

# Update File Content in an Archive

# Delete a File from an Archive

# Options

# Command Summary

# Working with VSAM data sets

# Running interactive TSO commands

# Getting help about commands and options

# Debugging CLI commands via logs

# Using Zowe CLI z/OSMF commands

# Prerequisites

# Running Zowe CLI commands

Using command line to interact with z/OS

Comparison between Zowe CLI and RSE CLI plug-in

Using RSE CLI plug-in commands

Prerequisites

Running RSE CLI plug-in commands

Searching for files on UNIX System Services by content or file name

Editing files in the terminal

Edit a Data Set

Edit a UNIX System Services File

Options to Edit File

Comparing files in the terminal

Compare data sets

Compare a local file with a data set

Compare a local file with a spool file

Compare a local file with a z/OS UNIX file

Compare spool files

Compare a z/OS UNIX File

Options to Compare File

Working with z/OS UNIX Archive Files

List Files in an Archive

Get File Content from an Archive

Update File Content in an Archive

Delete a File from an Archive

Options

Command Summary

Working with VSAM data sets

Running interactive TSO commands

Getting help about commands and options

Debugging CLI commands via logs

Using Zowe CLI z/OSMF commands

Prerequisites

Running Zowe CLI commands