7. Dataset Pipes Examples

This chapter contains common examples for using Dataset Pipes. These examples assume that you have installed and configured the Co:Z toolkit on your z/OS and target systems, and have properly configured the dspipes sshd subsystem.

For questions or to suggest new examples for this chapter, please visit the Dovetailed Technologies z/OS Forum

7.1 Copy an HFS or zFS file to an MVS dataset

cat /home/user/myfile | todsn //MVS1.OUTPUT.DATASET

This command can be entered from any z/OS Unix shell (see Section F.2, “Using the z/OS Unix Shell”). The HFS file is copied to stdout, which is piped ('|') to stdin for the todsn command which converts the data to records written to the MVS dataset. The default options for todsn are in effect:

Input lines will be broken on CR, LF, or CRLF.
If the dataset is new, then its default attributes will be "recfm=VB,lrecl=1028".
Lines longer than allowed by the dataset will be wrapped onto multiple records.

7.2 Copy to an MVS dataset, overriding target DCB attributes

cat /home/user/myfile | todsn -o 'recfm=fb,lrecl=80' //MVS1.DATASET1

The -o option is used to provide additional options to the fopen() API. (see Section F.3, “The z/OS C library fopen() routine”), which is used by todsn to open the output dataset. The base fopen() options used by todsn to open output datasets is "rb,type=record,noseek" Since fixed length records are called for in this example, todsn will pad any short records with spaces. (The pad character can be overridden using the -p option).

7.3 Copy to an MVS dataset, truncating long lines

cat /home/user/myfile | todsn -w trunc //MVS1.DATASET1

The -w option is used specify how to handle lines longer than the maximum record length of the target dataset. The default is to wrap long lines to a new record. Specify trunc to cause long lines to be truncated, or error to cause the command to fail if a long line is encountered.

7.4 Copy to a PDS member

cat /home/user/myfile | todsn '//MVS1.MYLIB.DATA(MEMBER1)'

The single quotes are required so that the parentheses will not be interpreted as shell meta-characters.

7.5 Specifying dataset names

cat /home/user/myfile | todsn //userid.test.data
cat /home/user/myfile | todsn -r //test.data

By default, dataset names are assumed to be fully-qualified.
The -r option can be used to automatically add a prefix of the current userid. Assuming that the current userid is "userid", the to above commands use the same dataset.
Dataset names are always upper case, but upper or lower case names may be given.
Dataset names that include PDS member names should be enclosed in single quotes, so that the parentheses will not be interpreted as shell meta characters. Quoting the dataset name does not imply anything more; the -r option may still be used to indicate that the userid should be added as a prefix.

7.6 Copying user input to the end of an exiting dataset

todsn -a //userid.test.data

Since the todsn command gets its input from stdin, entering the command without a pipe will cause it to read from the terminal. The user can type input lines, ending it ctrl-d which signals an end-of-file.
The -a option changes the base fopen() options to "ab,type=record,noseek", which opens the file in append (aka "mod") mode. This option can of course be used with pipes as well.

7.7 Copy an MVS dataset (PDS member) to an HFS file

fromdsn '//mvs1.my.lib(member1)' > /home/user/member1

The fromdsn command reads an MVS dataset and converts it to a stream of bytes written to stdout. The above command redirects ('>') this output to an HFS file. With the default options for fromdsn:

Trailing pad characters (default is spaces) will be removed from the dataset records
Linefeeds (EBCDIC "newline") characters will be added to the end of each record
The single quotes are required to prevent the Unix shell from interpreting the parentheses as meta characters.

7.8 Copy an MVS dataset using DISP=SHR

fromdsn -x shr //mvs1.input.dataset > /home/user/mydata

The default allocation status used by fopen() in "read" mode is DISP=OLD. The - x option can be used to specify BPXWDYN allocation keywords (see Section F.4, “The z/OS BPXWDYN dynamic allocation service”). In this example, the keyword shr is used to specify a allocation status of "share", which allows for multiple jobs to read the same dataset simultaneously.

7.9 Copy one MVS dataset to another

fromdsn //mvs1.input.dataset | todsn //mvs1.output.dataset

The fromdsn reads the input dataset and converts it to a stream of bytes which is piped into the todsn command which converts that stream of bytes to the output dataset. If the output dataset is new, then the default attributes of "recfm=vb,lrecl=1028". Existing DCB attributes are used if the output dataset already exists. Default line-termination and wrap rules apply, which fine for text data.

7.10 Copy one MVS dataset to another using the same attributes

fromdsn //mvs1.input.dataset | 
  todsn -x 'new like(mvs1.input.dataset)' //mvs1.output.dataset

The -x option is used to specify the "new" and "like" BPXWDYN allocation keyword, which copies attributes (DCB, SPACE, etc) from a model dataset to allocate the new output dataset. Newline characters are, by default, used as record delimiters, so this command is only appropriate for text datasets.

7.11 Copy one MVS non-text dataset to another

fromdsn -k -l rdw //mvs1.input.dataset | 
  todsn -l rdw -x 'new like(mvs1.input.dataset)' //mvs1.output.dataset

The -l rdw option is used on both the fromdsn and todsn commands to indicate that four byte record-descriptor-words (RDW) should be used in the piped stream to indicate record boundaries. The fromdsn -k option specifies that pad characters should not be trimmed from the end of records (trimming is the default for fixed-length records).

7.12 Copy an ASCII HFS file to an EBCDIC MVS dataset

cat /home/user/ascii.txt | todsn -s iso8859-1 -r //my.dataset

The -s option names the source codepage(charset) used to convert the data.
The -t option may be used to specify the target codepage.
If either -s or -t is omitted, they default to the current codepage for the process's locale, which is commonly "IBM-1047" (EBCDIC, Latin).
The arguments to -s and >-t may also be numeric CCSIDs.
If the same effective CCSID is specified as both the source and target, then no translation is performed.
The IBM z/OS Unicode Translation service (see Section F.5, “The z/OS Unicode Translation Services”), is used for all codepage conversions. Starting with z/OS 1.6, this service is configured and enabled by default, but your environment may need to be customized to include specific codepage that you wish to use. If the requested codepage conversions are not available, then Dataset Pipes will try to fall back and use the iconv() C-library routine.

7.13 Copy an MVS dataset from one z/OS system to another over an 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 an SSH client connection over which it runs a remote todsn command on the target system.
The -ssh option requires that the "IBM Ported Tools for z/OS (SSH)" product be installed and configured.
This example assumes that you have configured SSH authentication keys, since the todsn command does not allow for password prompting.

7.14 From a workstation, download a MVS dataset over an SSH connection

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

fromdsn.exe is a Windows program that creates an 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.
See Section 2.2, “Windows Target System Installation” for more information

7.15 From a workstation, upload an MVS dataset (PDS member) over an 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 an 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.
See Section 2.2, “Windows Target System Installation” for more information

Prev		Next
6. Running Dataset Pipes	Contents	8. Problem Determination

Prev		Next
6. Running Dataset Pipes	Home	8. Problem Determination

Co:Z Launcher and Dataset Pipes V 2.0.0