This chapter contains common examples for using Dataset Pipes. The commands in this section can be used in three different environments (use cases):
z/OS Unix System Services Integration: from any z/OS Unix shell (see Section D.2, “Using the z/OS Unix Shell”) including Co:Z Batch,
z/OS Hybrid Batch: from a shell process executing on a distributed system by the Co:Z Launcher, or
z/OS Remote Services: from a remote client initiatinig a connection to z/OS using a cozcontrol durable SSH connection. Optionally, these commands can be modified to specify the target system connection information directly on the command by adding the
-sshoption. See Chapter 4, z/OS Remote Services Examples.
These examples assume that you have installed and configured the Co:Z Toolkit for z/OS on your z/OS server, the Co:Z Target System Toolkits on non-z/OS servers, and in the z/OS remote services use case, completed the section called “Configuring the Dataset Pipes subsystem” on the target z/OS server.
For questions or to suggest new examples for this chapter, please visit the Dovetailed Technologies z/OS Forum
fromdsn //MVS1.INPUT.DATASET > /home/user/mydata
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 a zFS 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
todsn //MVS1.OUTPUT.DATASET < /home/user/myfile
The zFS file is redirected to stdin of 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.
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 a zFS 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.
todsn '//MVS1.MYLIB.DATA(MEMBER1)' < /home/user/myfile
The single quotes are required so that the parentheses will not be interpreted as shell meta-characters.
todsn //userid.test.data < /home/user/myfile todsn -r //test.data < /home/user/myfile
By default, dataset names are assumed to be fully-qualified.
The
-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 -s iso8859-1 -r //my.dataset < /home/user/ascii.txt
The
-soption names the source codepage(charset) used to convert the data.The
-toption may be used to specify the target codepage.If either
-sor-tis omitted, they default to the current codepage for the process's locale, which is commonly "IBM-1047" (EBCDIC, Latin).The arguments to
-sand>-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 D.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.
todsn -o 'recfm=fb,lrecl=80' //MVS1.DATASET1 < /home/user/myfile
The -o option is used to provide additional options to the
fopen() API. (see Section D.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).
todsn -w trunc //MVS1.DATASET1 < /home/user/myfile
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.
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 D.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
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.
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).
fromfile -t ISO8859-1 myfile.txt > myfile_win.txt
The
-toption may be used to specify the target codepage.
tofile -p /home/user/newdir/myfile < myfile
The
-poption make the path components to filename if they don't exist (ala mkdir -p).
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 itctrl-dwhich signals an end-of-file.The
-aoption changes the basefopen()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.
