This chapter contains common examples for using Dataset Pipes, specifically from a remote system. These examples assume that you have installed and configured the Co:Z Toolkit for z/OS on your z/OS systems, the Co:Z Target System Toolkits on non-z/OS systems, and completed the section called “Configuring the Dataset Pipes subsystem” on the target z/OS server.
For a complete set of Dataset Pipes commands that can be executed from a remote system, see Appendix A, Command Reference - Dataset Pipes .
fromdsn -ssh user@zos.myco.com 'hlq.input.dataset' > /tmp/data
Downloads a MVS dataset over a SSH connection.
cat /tmp/data | todsn -ssh -p 2222 user@zos.myco.com 'hlq.input.dataset'
Uploads a MVS dataset over a SSH connection.
fromdsn -k -l rdw //mvs1.input.dataset |
todsn -ssh user@zos2.myco.com -l rdw //mvs2.output.dataset
fromdsn is run locally to create a stream of RDW-delimited records that is piped into the todsn command.
The todsn
-sshoption creates a SSH client connection over which it runs a remote todsn command on the target system.The
-sshoption requires that z/OS OpenSSH is available and configured.This example assumes that you have configured SSH authentication keys, since the todsn command does not allow for password prompting.
cozcontrol start -ssh user@zos.myco.com
fromdsn 'hlq.dsn' > /home/user/mydata/data1.txt
cat /home/user/mydata/data2.txt | todsn 'hlq.dsn'
cozclient wto "message to console"
cozcontrol stop
The cozcontrol start command establishes a SSH connection from unix to the z/OS server.
The fromdsn command downloads a dataset to the unix server
The todsn command uploads a file to a dataset.
The cozclient command write a message to the console.
Finally, the cozcontrol stop command ends the durable SSH connection.
cozcontrol start -ssh user@zos.myco.com
cozclient pax -wzvf "//'HLQ.DATA.ARCHIVE'" /home/user/datadir
fromdsn -b 'hlq.data.archive' > /home/user/mydata/data.archive.pax
cozclient tso delete 'data.archive'
cozclient wto "archive complete"
cozcontrol stop
The cozcontrol start command establishes a SSH connection to the z/OS server.
The cozclient command executes a pax on z/OS to back up a directory to a dataset. Note: pax archives to a dataset only to show a tso delete command in the example.
The fromdsn command copies the dataset backup to the remore system in binary mode.
The cozclient command deletes the dataset backup.
The cozclient command write a message to the console indicating that the archive is complete.
Finally, the cozcontrol stop command ends the durable SSH connection.
cozcontrol start -t -ssh user@zos.myco.com
fromdsn 'hlq.dsn' > /home/user/mydata/data1.txt
cat /home/user/mydata/data2.txt | todsn 'hlq.dsn'
cozclient wto "message to console"
cozcontrol stop
The cozcontrol start command specifies the
-toption setting up a SSH control master with local port forwarding.Subsequent todsn, fromdsn, and cozclient commands are forwarded over this SSH connection.
#! /bin/bash
# Sample script: z/OS Remote Services Example
#
# This script expects user@host as a parameter. Using this parameter,
# 1. establishes a cozcontrol control session.
# 2. retrieves a dataset using the socket established on start,
# 3. runs a command on the z/OS server,
# 4. stops the cozcontrol session.
#
# ENVIRONMENT VARIABLE:
# COZ_LOG
# COZ_CONTROL_SESSION
#
# SCRIPT VARIABLES:
# USER_HOST - initialized with input parameter value
# SSH_LOG_FILE
#
export COZ_LOG=I
#SSH_LOG_FILE="-E /tmp/ssh.log"
if [ "$1" = "" ]
then
echo "Usage: user@host required."
exit
fi
USER_HOST=$1
# Start a cozcontrol session
./cozcontrol start -ssh $SSH_LOG_FILE $USER_HOST
rc=$?
if [ "$rc" -ne "0" ]; then { echo "cozcontrol start failed. rc=$rc" ; exit 1; } fi
# Retrieve a dataset from the server.
COZ_CONTROL_SESSION=$USER_HOST ./fromdsn 'hlq.dsn' > /tmp/data.txt
rc=$?
if [ "$rc" -ne "0" ]; then { echo "fromdsn failed. rc=$rc" ; exit 1; } fi
./cozclient wto "MESSAGE TO CONSOLE"
# Stop the cozcontrol session
COZ_CONTROL_SESSION=$USER_HOST ./cozcontrol stop
rc=$?
if [ "$rc" -ne "0" ]; then { echo "cozcontrol stop failed. rc=$rc" ; exit 1; } fi
A zero return code from cozcontrol start means that the SSH connection to the server has been established. If the ssh connection is not successful, SSH logging can be enabled by adding
-vvvto the cozcontrol start command and reviewing the log captured by setting the script variableSSH_LOG_FILE.Setting the environment variable
COZ_CONTROL_SESSIONto the user@host parameter on each DatasetPipes command allows multiple copies of the script to be run concurrently by the same user to different target hosts.
