Dovetailed Technologies

4. z/OS Remote Services Examples

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 .

4.1 Download a dataset to a unix server over a SSH connection

fromdsn -ssh user@zos.myco.com 'hlq.input.dataset' > /tmp/data
      

  • Downloads a MVS dataset over a SSH connection.

4.2 Upload a dataset from a unix server 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.

4.3 Copy a MVS dataset from one z/OS system to another 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 -ssh option creates a SSH client connection over which it runs a remote todsn command on the target system.

  • The -ssh option 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.

4.4 Using a durable connection, run simple dspipes commands, end the connection

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.

4.5 Using a durable connection, run a pax command on z/OS, download the archive to unix, end the 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.

4.6 From a remote linux system, start a tunneled durable connection, run dspipes commands, end the 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 -t option setting up a SSH control master with local port forwarding.

  • Subsequent todsn, fromdsn, and cozclient commands are forwarded over this SSH connection.

4.7 Scripted Co:Z Remote Services example

#! /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 -vvv to the cozcontrol start command and reviewing the log captured by setting the script variable SSH_LOG_FILE.

  • Setting the environment variable COZ_CONTROL_SESSION to 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.

4.8 From a Windows workstation, download a MVS dataset over a SSH connection

fromdsn -ssh user@zos2.myco.com //mvs1.input.dataset > c:\mydata\data1.txt

  • fromdsn.exe is a Windows program that creates a SSH connection to a remote z/OS host to remotely run the z/OS fromdsn command.

  • On Windows, the -ssh option requires that the PuTTY plink command be installed and available on the PATH.

  • fromdsn is also available in source for building on POSIX / Unix systems as part of the Co:Z target server toolkit

  • fromdsn.exe has the same arguments and features as the z/OS fromdsn command, with the addition of options for specifying the remote z/OS SSH user@host, and optional arguments to SSH / Putty. See the other examples for features of fromdsn that you may remotely use via fromdsn -ssh.

  • The linemode option -l defaults to crlf for the Windows client, and the by default the source codepage will be the same as the current Windows codepage.

  • The output of the fromdsn command is the converted stream of data, which is redirected ('>') to a PC file.

4.9 From a Windows workstation, upload an MVS dataset (PDS member) over a SSH connection

copy c:\upload.txt con: | 
  todsn -ssh user@zos.myco.com '//userid.lib.data(mem1)'

  • The Windows copy command is used to pipe ('|') the contents of a file into the todsn command.

  • todsn.exe is a Windows executable that creates a SSH connection to a remote z/OS host to remotely run the z/OS todsn command.

  • On Windows, the todsn -ssh options requires that the PuTTY plink command be installed and available on the PATH.

  • todsn.exe has the same arguments and features as the z/OS todsn command, with the addition of options for specifying the remote z/OS SSH user@host, and optional arguments to SSH / PuTTY. See the other recipes in this cookbook for features of todsn that you may use remotely with the Windows SSH client.

Copyright© 2009-2017 Dovetailed Technologies, LLC. All rights reserved.
Co:Z® is a registered trademark of Dovetailed Technologies, LLC.