Zowe and Zowe CLI
Zowe is an open source project for the IBM Z platform. It provides new user interfaces for users to interact with z/OS. It also provides a set of APIs on which users can easily build their applications on z/OS. Zowe's modern interface allows you to use z/OS to develop and extend your applications in a way similar to what you experience on a cloud platform today. It not only lowered the learning curve of IBM mainframe and made IBM z/OS easy to work with, but also is the product of IBM mainframe embracing open source and entering the cloud era.
Zowe CLI is an important part of Zowe. It is a command-line interface that you can use on any platform (Windows, MacOS, Linux). It is easy to integrate with common development build tools such as integrated development environments (IDEs), shell commands, bash scripts, build tools, and so on. It can easily interact with the host, obtain z/OS resources, execute and control z/OS jobs, issue system commands and TSO commands. But Zowe CLI relies on z/OSMF for these powerful features. Users need to install z/OSMF on the system they are interacting with. This brings some trouble to those users who do not have z/OSMF. So, without z/OSMF, wouldn't we be able to experience the fun of Zowe CLI? Of course not, today's z/OS FTP plug-in for Zowe CLI is a good choice!
z/OS FTP Plug-in for Zowe CLI
z/OS FTP plug-in for Zowe CLI (zftp) uses the zos-node-accessor package and z/OS FTP service to interact with z/OS. So there is no need for z/OSMF as the back-end support. It is as consistent as possible with the Zowe CLI core in terms of the command syntax and response so that you don't have to learn any additional syntax knowledge when using it. Now Zowe 1.9.0 has officially released the z/OS FTP plug-in. The following will show you how to install and use it.
Prerequisites
1. Enable FTP or FTPS(FTP over SSL) services on z/OS. The secure FTPS is recommended and ensure the value of FTP setting, JESINTERFACELEVEL , is 2.
2. Install Node.JS v8 or above version(v10/v12) on your workstation.
Tips: you can run command rstat in z/OSMF FTP client to check the value of JESINTERFACELEVEL.
Installation
1. Install Zowe CLI
Run the following commands to install Zowe CLI and Secure Credential Store.
npm install -g @zowe/cli@zowe-v1-lts
zowe plugins install @zowe/secure-credential-store-for-zowe-cli@zowe-v1-lts
2. Install z/OS FTP Plug-in for Zowe CLI
zowe plugins install @zowe/zos-ftp-for-zowe-cli@zowe-v1-lts
W
hen you finished the installation, the following message will show up: ‘This plugin was successfully validated. Enjoy the plugin.’
3. Create User Profile
Using the following command to create a user profile：
zowe profiles create zftp profilename -u username -p password -H hostname --secure-ftp true/false
Change the red parts to fit your system. If FTPS (FTP over SSL) enabled, set --secure-ftp to be true. Otherwise, set it false. Example:
zowe profiles create zftp p21 -u ibmuser -p xxxxxxxx -H 9.12.34.56 --secure-ftp false
4. Verify
You can run a simple zowe zftp command to verify this plugin. Example:
zowe zftp list ds “SYS1.**”
Now you can follow me to go through the simple but useful commands to learn more about zowe zftp plugin.
Datasets
The most data on z/OS are stored in dataset, like the sequential dataset and partition dataset. z/OS FTP plug-in for Zowe CLI allows you to list datasets, view their contents, download, upload or delete them from command line easily.
First, you can list dataset with“list data-set” command:
$ zowe zos-ftp list data-set "SYS1.**.*EXEC"
SYS1.SAXREXEC
SYS1.SBPXEXEC
Then, you can view the dataset contents with “view data-set” command, as you do from ISPF. Reminder: Only text data is supported to view.
$ zowe zos-ftp view data-set "TNZSYS.ZFTP.TEST(HELLO)"
//HELLO JOB ,NOTIFY=&SYSUID,CLASS=A,MSGCLASS=H,MSGLEVEL=1
//STEP0001 EXEC PGM=IEBGENER
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD *
Hello World
/*
//SYSUT2 DD SYSOUT=*
You can also download the text dataset to the local machine with “download data-set” command:
$ zowe zos-ftp download data-set "TNZSYS.ZFTP.TEST(HELLO)"
Data set downloaded successfully.
Destination: tnzsys/zftp/test/hello
Or download the dataset in binary mode by adding “--binary”:
$ zowe zos-ftp download data-set "TNZSYS.ZFTP.TEST(HELLO)" --binary
Data set downloaded successfully.
Destination: tnzsys/zftp/test/hello
There are two ways to upload the local changes to the dataset on z/OS.
1) You do some changes in the local file and then upload it to z/OS with “upload file-to-data-set” command:
$ zowe zos-ftp upload file-to-data-set hello "TNZSYS.ZFTP.TEST.HELLO"
Uploaded from local file 'hello' to TNZSYS.ZFTP.TEST.HELLO
The target dataset will be allocated, if it does not exist, or overwritten if existent. In the former case, the target dataset is allocated with the default allocation configuration. You can specify the allocation configuration with the dataset control block option, --dcb. Please note the configuration parameters are separated by space character, requiring double quotes enclosing them usually. For example:
$ zowe zos-ftp upload file-to-data-set hello "TNZSYS.ZFTP.TEST.HELLO.DCB" --dcb "RECFM=VB LRECL=326 BLKSIZE=23472"
Uploaded from local file 'hello' to TNZSYS.ZFTP.TEST.HELLO.DCB
Also if you want to upload a file to dataset in binary mode just add “--binary” option.
2) z/OS FTP Plug-in also supports to upload dataset from stdin with “upload stdin-to-data-set” command. You just need write your contents in a new line and when you finished the contents using “Control + D” to end the command. The message like “Uploaded from stdin to TNZSYS.ZFTP.TEST(HELLO1)” indicates the success.
$ zowe zos-ftp upload stdin-to-data-set "TNZSYS.ZFTP.TEST(HELLO1)"
//HELLO JOB ,NOTIFY=&SYSUID,CLASS=A,MSGCLASS=H,MSGLEVEL=1
//STEP0001 EXEC PGM=IEBGENER
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD *
Hello World
/*
//SYSUT2 DD SYSOUT=*
^D
Uploaded from stdin to TNZSYS.ZFTP.TEST(HELLO1)
Finally, you can rename the dataset with “rename data-set” command.
$ zowe zos-ftp rename data-set "TNZSYS.ZFTP.TEST.HELLO" "TNZSYS.ZFTP.TEST.HELLO.NEW"
Successfully renamed data set from 'TNZSYS.ZFTP.TEST.HELLO' to 'TNZSYS.ZFTP.TEST.HELLO.NEW'
And delete the dataset or the member of partition dataset with “delete data-set” command. Don’t forget to add “--force” option to confirm that action.
$ zowe zos-ftp delete data-set "TNZSYS.ZFTP.TEST.HELLO.DCB" --force
Successfully deleted data set file TNZSYS.ZFTP.TEST.HELLO.DCB
USS File/Directory
z/OS FTP plug-in for Zowe CLI also allows to operate another set of data in z/OS, USS file and directory. You can do the same things from command line, like list USS files under one directory, view file contents, download, upload or delete them.
First, you can use “list uss-files” to list USS files in a directory:
$ zowe zos-ftp list uss-files "/u/tnzsys/test"
mytest 8192 TNZSYS TESTER drwxr-xr-x
syscmd.txt 224 TNZSYS TESTER -rw-r-----
test.txt 21 TNZSYS TESTER -rw-r--r--
test2 21 TNZSYS TESTER -rwx------
testfile 224 TNZSYS TESTER -rw-r-----
Have a quick view of the USS file contents with “view uss-file” command:
$ zowe zos-ftp view uss-file "/u/tnzsys/test/test.txt"
this is a test file.
Download the USS file with “download uss-file” command:
$ zowe zos-ftp download uss-file "/u/tnzsys/testfile.txt"
Successfully downloaded USS file '/u/tnzsys/testfile.txt' to local file 'testfile.txt'
You can also upload the local file to the USS file by using “upload file-to-uss-file” command:
$ zowe zos-ftp upload file-to-uss-file hello "/u/tnzsys/test/hello.txt"
Uploaded from local file 'hello' to /u/tnzsys/test/hello.txt
Like dataset, you can upload a USS file from stdin as well, using “upload stdin-to-uss-file” command:
$ zowe zos-ftp upload stdin-to-uss-file "/u/tnzsys/test/hello1.txt"
//HELLO JOB ,NOTIFY=&SYSUID,CLASS=A,MSGCLASS=H,MSGLEVEL=1
//STEP0001 EXEC PGM=IEBGENER
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD *
Hello World
/*
//SYSUT2 DD SYSOUT=*
^D
Uploaded from stdin to /u/tnzsys/test/hello1.txt
Finally, you rename the USS file or directory with “rename uss-file”.
$ zowe zos-ftp rename uss-file "/u/tnzsys/test/hello1.txt" "/u/tnzsys/test/hello2.txt"
Successfully renamed USS file or directory from '/u/tnzsys/test/hello1.txt' to '/u/tnzsys/test/hello2.txt'
And delete the USS file with “delete uss-file” command. The option “--force” is required to confirm this action.
$ zowe zos-ftp delete uss-file "/u/tnzsys/test/hello2.txt" --force
Successfully deleted USS file /u/tnzsys/test/hello2.txt
If you want to delete whole directory the option “--recursive” is required.
$ zowe zftp delete uss "/u/tnzsys/test" --force --recursive
Deleted /u/tnzsys/test/hello.txt
Deleted /u/tnzsys/test/mytest
Deleted /u/tnzsys/test/syscmd.txt
Deleted /u/tnzsys/test/test.txt
Deleted /u/tnzsys/test/test2
Deleted /u/tnzsys/test/testfile
Deleted /u/tnzsys/test
Successfully deleted USS file /u/tnzsys/test
Jobs
In z/OS system, job is a common way to perform tasks. You can use z/OS FTP Plug-in to submit job, list job, query job status, view job spool output and delete job easily.
First, you can submit job with the JCL stored on dataset by using “submit data-set” command:
$ zowe zos-ftp submit data-set "TNZSYS.ZFTP.TEST(HELLO)"
jobid: JOB16841
jobname: HELLO
owner: TNZSYS
status: OUTPUT
The job can also be submit with the JCL from the local file by using “submit local-file” command:
$ zowe zos-ftp submit local-file hello
jobid: JOB16842
jobname: HELLO
owner: TNZSYS
status: OUTPUT
Or the JCL from stdin by using “submit stdin” command:
$ zowe zos-ftp submit stdin
//HELLO JOB ,NOTIFY=&SYSUID,CLASS=A,MSGCLASS=H,MSGLEVEL=1
//STEP0001 EXEC PGM=IEBGENER
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD *
Hello World
/*
//SYSUT2 DD SYSOUT=*
^D
jobid: JOB16843
jobname: HELLO
owner: TNZSYS
status: OUTPUT
You can use “list jobs” command to list the jobs with the specified prefix. By default, you can only list jobs which owned by yourself.
$ zowe zos-ftp list jobs --prefix "sys*"
SYSTES2 JOB16798 TNZSYS
SYSTES1 JOB16797 TNZSYS
SYSTEST JOB16796 TNZSYS
If you want to list jobs owned by others the option “--owner” is supported.
$ zowe zftp list jobs --prefix "sys*" --owner "*"
SYSTES2 JOB16798 TNZSYS
SYSTES1 JOB16797 TNZSYS
SYSTEST JOB16796 TNZSYS
SYSLOG STC16646
After submitting job, you can query for the job status with the specified job ID, using “view job-status-by-jobid” command. The “rc: 0” means the job completes successfully. If the job is running the status will show “ACTIVE” in the second example.
$ zowe zos-ftp view job-status-by-jobid JOB16843
jobname: HELLO
jobid: JOB16843
owner: TNZSYS
status: OUTPUT
rc: 0
$ zowe zos-ftp view job-status-by-jobid STC16646
jobname: SYSLOG
jobid: STC16646
owner: +MASTER+
status: ACTIVE
If you need more job information, there are some commands related to JES spool to help you view details about the job.
You can list spool files with the specified job ID by using “list spool-files-by-jobid” command:
$ zowe zos-ftp list spool-files-by-jobid JOB16843
1 JESMSGLG N/A JES2
2 JESJCL N/A JES2
3 JESYSMSG N/A JES2
4 SYSPRINT N/A STEP0001
5 SYSUT2 N/A STEP0001
You can also view the specified spool file by using “view spool-file-by-id” command with jobid and spool file id. The spool file id is the first number in the above output.
$ zowe zos-ftp view spool-file-by-id JOB16843 5
Hello World
You can view all spool files by using “view all-spool-by-jobid” command:（Some of the output has been omitted in the following example）
$ zowe zos-ftp view all-spool-by-jobid JOB16843
1 J E S 2 J O B L O G -- S Y S T E M P 2 1 -- N O D E P K P A T 2 1
0
01.19.47 JOB16843 ---- SATURDAY, 04 APR 2020 ----
01.19.47 JOB16843 IRR010I USERID TNZSYS IS ASSIGNED TO THIS JOB.
…… ……
1 //HELLO JOB ,NOTIFY=&SYSUID,CLASS=A,MSGCLASS=H,MSGLEVEL=1 JOB16843
IEFC653I SUBSTITUTION JCL - ,NOTIFY=TNZSYS,CLASS=A,MSGCLASS=H,MSGLEVEL=1
2 //STEP0001 EXEC PGM=IEBGENER
PROCESSING ENDED AT EOD
Hello World
Or download them by using “download all-spool-by-jobid” command:
$ zowe zos-ftp download all-spool-by-jobid JOB16843
Successfully downloaded 5 spool files to ./output/
If you want to delete the job in the spool you can use “delete job” command:
$ zowe zos-ftp delete job JOB16843
Successfully deleted job JOB16843
The above examples are commonly used and you can find the cheetsheet at the end of this article. Or use “zowe zftp --help” command to get more help and instructions.
Before we finish it, let’s have a look at a complete example.
Complete Example
This script defines allocFun function which does the following things:
First, updates the JCL which is downloaded from z/OS and saved to the local file, ALLOCDS.JCL.
Then, submits ALLOCDS.JCL. and checks the job status every 3 seconds until the job finishes.
Lastly, get the job return code to confim it finishes successfully.
At the end of this script, invoke allocFun function two times to allocate dataset IBMUSER.ZFTP.DS1 and IBMUSER.ZFTP.DS2.
Script:
#!/bin/bash
# download JCL from z/OS system
zowe zos-ftp download data-set "TNZSYS.ZFTP.TEST(ALLOCDS)" -f ./ALLOCDS
# allocFun function
allocFun()
{
echo "allocate dataset $1"
# update JCL
sed "s/DSN=.*,/DSN=$1,/" ALLOCDS>ALLOCDS.JCL
# submit job
jobid=$(zowe zos-ftp submit local-file ALLOCDS.JCL --rff jobid --rft string)
echo "Submitted job ALLOCDS, JOB ID is $jobid"
# check job status every three seconds
status="UNKNOWN"
while [[ "$status" != "OUTPUT" ]]; do
echo "Checking status of job $jobid"
status=$(zowe zos-ftp view job-status-by-jobid "$jobid" --rff status --rft string)
echo "Current job status is $status"
sleep 3s
done;
# check return code
rc=$(zowe zos-ftp view job-status-by-jobid "$jobid" --rff rc --rft string)
echo "$jobid is return $rc"
}
# invoke allocFun to allocate dataset
allocFun IBMUSER.ZFTP.DS1
allocFun IBMUSER.ZFTP.DS2
echo "all datasets are allocated successfully!"
The option “--rff” is stand for “--response-format-filter”. Filter (include) fields in the response. In the example, the filter field is jobid. Accepts an array of field/property names to include in the output response. You can filter JSON objects properties OR table columns/fields.
The option “--rft” is stand for “--response-format-type”. Specified the command response output format type. The allowed value are table,list,object and string.
You can use these two options to reduce the output of a command to a single field/property or a list of a single field/property.
JCL:
//ALLOCDS JOB MSGLEVEL=(1,1),NOTIFY=&SYSUID,MSGCLASS=A
//CRT01 EXEC PGM=IEFBR14
//STEP10 EXEC PGM=IEFBR14
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//SYSDUMP DD SYSOUT=*
//DD1 DD DSN=IBMUSER.ZFTP.DS0,
// DISP=(NEW,CATLG,DELETE),
// SPACE=(TRK,(1,1),RLSE),
// UNIT=SYSDA,
// DCB=(DSORG=PS,RECFM=FB,LRECL=23,BLKSIZE=230)
The above script and JCL are for reference only. Please change the name according to your system condition.
Hope you can go through above introduction and enjoy using it to help you on your daily work. If you encounter any problems in use it, please contact us or present your ideas and requirements. Thank you very much!
Contact: tiantn@cn.ibm.com, liangqi@cn.ibm.com
At the end of the article list some common used commands and useful links that you can reference. Enjoy it!
Commands
profile related commands:
zowe profiles create zftp-profile myprofile -u ibmuser -p ibmp4ss -H sys123
zowe profiles delete zftp-profile profilename
zowe profiles list zftp-profiles --sc
zowe profiles delete zftp-profile profilename
zowe profiles update zftp-profile profilename
delete commands:
zowe zos-ftp delete data-set "ibmuser.cntl" --force
zowe zos-ftp delete job j123
zowe zos-ftp delete uss-file "/u/ibmuser/myfile.txt" --force
download commands:
zowe zos-ftp download all-spool-by-jobid j123
zowe zos-ftp download data-set "ibmuser.loadlib(main)"
zowe zos-ftp download uss-file "/u/users/ibmuser/main.obj"
list commands:
zowe zos-ftp list data-set "ibmuser.**.cntl"
zowe zos-ftp list jobs --prefix "ibmu*"
zowe zos-ftp list spool-files-by-jobid job00123
zowe zos-ftp list uss-files "/u/users/ibmuser"
rename commands：
zowe zos-ftp rename data-set ibmuser.jcl ibmuser.cntl
zowe zos-ftp rename uss-file "/u/users/ibmuser/hello.txt" "/u/users/ibmuser/hello2.txt"
submit commands：
zowe zos-ftp submit data-set "ibmuser.cntl(iefbr14)"
zowe zos-ftp submit local-file "my_build_jcl.txt"
zowe zos-ftp submit stdin
upload commands：
zowe zos-ftp upload file-to-data-set iefbr14.txt "ibmuser.cntl(iefbr14)"
zowe zos-ftp upload file-to-uss-file iefbr14.txt "/u/users/ibmuser/iefbr14.txt"
owe zos-ftp upload stdin-to-data-set "ibmuser.cntl(iefbr14)"
zowe zos-ftp upload stdin-to-uss-file "/u/users/ibmuser/iefbr14.txt"
view commands：
zowe zos-ftp view all-spool-by-jobid j123
zowe zos-ftp view data-set "ibmuser.cntl(iefbr14)"
zowe zos-ftp view job-status-by-jobid j123
zowe zos-ftp view spool-file-by-id JOB00123 4
zowe zos-ftp view uss-file "/u/users/ibmuser/myfile.txt"
Reference link:
https://docs.zowe.org/stable/Zowe_Documentation.pdf
https://github.com/zowe/zowe-cli-ftp-plugin
https://github.com/IBM/zos-node-accessor