Dovetailed Technologies

3. General Dataset Pipes Examples

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 E.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 -ssh option. 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

3.1 Copy an MVS dataset to a zFS file

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

3.2 Copy a zFS file to an MVS dataset

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.

3.3 Copy an MVS dataset (PDS member) to a zFS 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 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.

3.4 Copy a zFS file to a PDS member

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.

3.5 Specifying dataset names

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 -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.

3.6 Copy an ASCII zFS file to an EBCDIC MVS dataset

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

  • 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 E.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.

3.7 Copy to an MVS dataset, overriding target DCB attributes

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 E.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).

3.8 Copy to an MVS dataset, truncating long lines

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.

3.9 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 E.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.

3.10 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.

3.11 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.

3.12 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).

3.13 Translate a file to the ISO8859-1 codepage from the default z/OS process codepage

fromfile -t ISO8859-1 myfile.txt > myfile_win.txt

  • The -t option may be used to specify the target codepage.

3.14 Copy a zFS file to a new location, creating any missing path components

tofile -p /home/user/newdir/myfile < myfile

  • The -p option make the path components to filename if they don't exist (ala mkdir -p).

3.15 Copy 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.

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