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
cat /home/user/myfile | todsn //MVS1.OUTPUT.DATASET
This command can be entered from any z/OS Unix shell (see Section H.2, “Using the z/OS Unix Shell”).
The HFS file is copied to
stdout, which is piped ('|') to
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
Lines longer than allowed by the dataset will be wrapped onto multiple records.
cat /home/user/myfile | todsn -o 'recfm=fb,lrecl=80' //MVS1.DATASET1
-o option is used to provide additional options to the
fopen() API. (see Section H.3, “The z/OS C library fopen() routine”), which is used by
todsn to open the output dataset. The base
options used by todsn to open output datasets is
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
cat /home/user/myfile | todsn -w trunc //MVS1.DATASET1
-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.
trunc to cause long lines to be truncated, or
to cause the command to fail if a long line is encountered.
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.
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.
-roption 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
-roption may still be used to indicate that the userid should be added as a prefix.
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-dwhich signals an end-of-file.
-aoption changes the base
"ab,type=record,noseek", which opens the file in append (aka "mod") mode. This option can of course be used with pipes as well.
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.
fromdsn -x shr //mvs1.input.dataset > /home/user/mydata
The default allocation status used by
in "read" mode is DISP=OLD. The -
x option can be used to specify
BPXWDYN allocation keywords (see Section H.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.
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.
fromdsn //mvs1.input.dataset | todsn -x 'new like(mvs1.input.dataset)' //mvs1.output.dataset
-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.
fromdsn -k -l rdw //mvs1.input.dataset | todsn -l rdw -x 'new like(mvs1.input.dataset)' //mvs1.output.dataset
-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
option specifies that pad characters should not be trimmed from the end of records (trimming
is the default for fixed-length records).
cat /home/user/ascii.txt | todsn -s iso8859-1 -r //my.dataset
-soption names the source codepage(charset) used to convert the data.
-toption may be used to specify the target codepage.
-tis omitted, they default to the current codepage for the process's locale, which is commonly "IBM-1047" (EBCDIC, Latin).
The arguments to
>-tmay 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 H.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
fromdsn -k -l rdw //mvs1.input.dataset | todsn -ssh firstname.lastname@example.org -l rdw //mvs2.output.dataset
fromdsn is run locally to create a stream of RDW-delimited records that is piped into the todsn command.
-sshoption creates an SSH client connection over which it runs a remote todsn command on the target system.
-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.
fromdsn -ssh email@example.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
-sshoption 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
The linemode option
crlffor 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.4, “Windows Target System Installation” for more information
copy c:\upload.txt con: | todsn -ssh firstname.lastname@example.org '//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
-sshoptions requires that the PuTTY plink command be installed and available on the
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.4, “Windows Target System Installation” for more information