Zowe and Zowe CLI
{Core} The Open Mainframe Project’s 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 a significant number of Zowe CLI commands, especially those related to data set and job management, require that z/OSMF be installed and configured before use. This can be potentially limiting on systems where z/OSMF has not been installed and configured for use with Zowe. So, without z/OSMF, wouldn’t we be able to experience the fun of Zowe CLI? This is where the z/OS FTP plug-in for Zowe CLI comes to the rescue, as FTP on z/OS provides access to services for working with datasets, uss and jobs. By using FTP on z/OS (instead of z/OSMF REST APIs) for these z/OS services users can still enjoy the CLI and use it for scriptable orchestration and automation of their mainframe. FTP is not a full replacement for z/OSMF REST API services, because while it covers the core function needed for data sets, USS and JES access, it doesn’t provide the ability to do workflows or provisioning.
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. 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. You can enable the FTP service by referring to the link: https://www.ibm.com/docs/en/zos/2.4.0?topic=applications-transferring-files-using-ftp.
2. Install Node.JS v8 or above version(v10/v12) on your workstation.
Tips: you can run command status to check JESINTERFACELevel from ftp localhost on USS environment.
The following is the sample output for command status
Command:
status
>>> STAT
............
211-JESLRECL is 80
211-JESRECFM is Fixed
211-JESINTERFACELEVEL is 2
211-Server site variable JESTRAILINGBLANKS is set to TRUE
............
211-Server site variable LISTLEVEL is set to 0
211 *** end of status ***
Command:Installation
1. Install Zowe CLI
Run the following commands to install Zowe CLI .
npm install -g @zowe/cli@zowe-v1-lts2. Install Zowe Secure Credential Store(optional)
The Secure Credential Store is an optional plugin and used to store passwords more securely than plain text profiles. To learn more about it please refer to https://docs.zowe.org/stable/user-guide/cli-scsplugin.html#secure-credential-store-plug-in-for-zowe-cli
zowe plugins install @zowe/secure-credential-store-for-zowe-cli@zowe-v1-lts3. Install z/OS FTP Plug-in for Zowe CLI
zowe plugins install @zowe/zos-ftp-for-zowe-cli@zowe-v1-ltsWhen you finished the installation, the following message will show up: ‘This plugin was successfully validated. Enjoy the plugin.’
4. 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/falseChange profilename, username, password and hostname 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 false5. 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.SBPXEXECThen, 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/helloOr 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/helloYou can also allocate sequential or partitioned dataset with “allocate data-set” command:
$ zowe zos-ftp allocate data-set "TNZSYS.ZFTP.DS1" --dcb "RECFM=FB DSORG=PO PRIMARY=10 SECONDARY=20 DIRECTORY=10"
Allocated dataset TNZSYS.ZFTP.DS1 successfully!The “ — dcb” option specify DCB parameters for dataset allocation. It’s space separated like “RECFM=FB LRECL=326 BLKSIZE=23472”.
There are two ways to upload the local changes to the dataset on z/OS.
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.HELLOThe 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.DCBAlso 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.DCBUSS 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.txtLike dataset, you can upload a USS file from stdin as well, using “upload stdin-to-uss-file” command:
You can also make a USS directory using “make uss-directory” command:
$ zowe zos-ftp make uss-directory "/u/tnzsys/newdir"
Make USS directory /u/tnzsys/newdir successfully!Finally, you can rename the USS file or directory with “rename uss-file”.
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.txtIf 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/testJobs
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: OUTPUTThe 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: OUTPUTOr 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: OUTPUTYou 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 TNZSYSIf 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 STC16646After 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 STEP0001You 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 WorldYou 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 JOB168431 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=IEBGENERPROCESSING ENDED AT EODHello 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 JOB16843The 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.DS2echo "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 profilenamedelete 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" --forcedownload 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 stdinupload 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
Finding out more
If you enjoyed this blog checkout more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #Zowe-dev, #Zowe-user or #Zowe-onboarding. If this is your first time using the OMP slack channel register here.
