Dovetailed Technologies

Name

todsn — read a stream of data from stdin and write records to a z/OS dataset

Synopsis

todsn [OPTION...] dataset-name
todsn -sock [OPTION...] dataset-name
todsn -ssh [ssh-opt...] user@host [OPTION...] dataset-name
todsn -local [OPTION...] dataset-name
todsn -v
todsn -h
    

Description

The todsn command writes records to dataset-name using a stream of data read from stdin. Dataset records are created from the input stream based on the options provided.

The todsn command runs in one of three environments:

  • locally (default on z/OS sytems)

  • remotely, from a client-initiated ssh connection: -ssh option

  • remotely, from a client which was started by Co:Z launcher: -sock (default option on non-z/OS systems)

The user has wide flexibility in choosing:

  • How dataset-name is to be allocated/opened for writing

  • How records are to be created from the incoming source lines

  • What character set (codepage) translations are to be performed

dataset-name is automatically converted to upper case, and is assumed to be fully qualified unless otherwise specified (see the -r option below). If dataset-name starts with 'DD:', then it refers to an existing DDNAME.

If dataset-name is //INTRDR, then the system internal reader is automatically allocated with a default RECFM=F and LRECL=80. In this case, the pseudo BPXWDYN option symlist() may be specified in order to pass one, or more JES system symbols to the internal reader. See this example.

Options

-sock

Specifies a remote invocation of todsn from a client environment running under a Co:Z Agent. This is the default for non-z/OS environments. If specified, this must be the first command option.

-ssh [ssh-options...] user@host

Specifies a remote invocation of todsn using a client-initiated ssh connection to the given z/OS user@host. If specified, this must be the first command option.

-local

Specifies the use of local z/OS I/O, even if run via CoZLauncher. If specified, this must be the first command option.

-a

open dataset-name in append/mod mode. This option changes the base fopen() options to ab,type=record,noseek.

-b

binary flow mode, same as -l none -p 0x00 -w flow.

-f

begin writing data to dataset-name immediately (disable buffering). This is the default if used with a tunneled socket or if dataset-name refers to a SYSOUT data set.

-h

display help and exit.

-k

keep trailing pad characters in record. The default is to trim if dataset-name has fixed length records.

-K

always trim trailing pad characters.

-l line-separator

flexible | cr | lf | crlf | nl | crnl

source lines are separated by combination of linefeed and/or carriage return characters. The default is 'flexible' which allows for any of the other patterns above. These characters are taken from the source codepage.

rdw

source lines are preceeded with a four byte IBM-style RDW, consisting of a two byte network order (big endian) length followed by two bytes of zeros.

mfrdw

Source data is preceeded by a 128 byte MicroFocus standard header. Source lines are preceeded with a network order (big endian) length. If the maximum record length is < 4095 bytes, the length field is 2 bytes. If the maximum record length is >= 4095 bytes, the length field is 4 bytes. Each record must be padded with zeros to the nearest 4 byte boundary.

0xbb[bb..]

source lines are followed with a hex character sequence. The sequence must be between 1 and 8 bytes long.

none

source lines do not have separators; source lines are determined by the maximum output record length.

-L logging-options

A comma-separated list of options to control logging and tracing:

M | A | C | E | W | N | I | D | T | F

Logging threshhold: eMergency, Alert, Critical, Error, Warning, Notice, Info (default), Debug, Trace, Fine.

t

Prefix log messages with a system timestamp

e

Include consumed cpu time in log messages

s

Messages are logged to SYSLOG facility instead of stderr

logname=M|A|C|E|W|N|I|D|T|F

Set a specific log name to the given threshold

-o fopen-options

additional mode arguments to the z/OS C library fopen() routine. The base mode options used by todsn to open dataset-name are "wb,type=record,noseek". See "z/OS C++ Programming Guide" for details.

-p 0xbb

pad character. The default is the source codepage space character.

-q technique-str

Codepage conversion technique string. Used to override the default Unicode Services value of LMREC. For more information, see IBM's Unicode Services User's Guide and Reference (SA22-7649).

-r

dataset-name will be prefixed with the current z/OS userid.

-s source-codepage

The codepage name or numeric CCSID id of the input data. If not specified and invoked from a remote client with a line-separator other than 'none', 'rdw' or 'mfrdw', then the default client codepage is used, otherwise the default z/OS codepage is used.

-t target-codepage

The codepage name or numeric CCSID id of output dataset. If not specified, then the default z/OS process codepage is used. Translation is disabled if source-codepage equals target-code- page.

-T STANDARD | translate_table_dsname

Specifies the translate table to use for text mode transfers. This option overrides the -s -t -q options if also given. If STANDARD, the translate table TCPIP.STANDARD.TCPXLBIN is used. If a dataset name is supplied, it is expected to be in the format produced by the TSO CONVXLAT command. Only single byte translations are supported. Specifically, the dataset DCB must be LRECL=256,RECFM=F and contain two translation table records. The first record is an ASCII-to-EBCDIC mapping; the second record is an EBCDIC-to-ASCII mapping. Additional comment records (starting with * in the first column) are allowed.

-v

display the current version and exit.

-w wrap-options

error

an error is returned if the source line is longer than the maximum record length.

flow

source lines longer than the maximum record length are flowed across subsequent records. For fixed record formats, the pad character is used to complete the final record resulting from the source line.

trunc

source lines longer than the maximum record length are truncated

wrap

source lines longer than the maximum record length are broken into multiple records. The default is 'wrap'.

-x bpxwdyn-alloc-keywords

can be specified to provide more precise control over dataset allocation than the fopen-options. These allocation options allow dataset-name to be created with specific space and disposition parameters, or allow dataset-name to be created like an already existing dataset. If dataset-name is 'DD:name', then this option is ignored. For a complete list of options, see the IBM manual: "Using REXX and z/OS UNIX System Services".

-z

allow for an empty input stream. If not specified, the default is to exit with an error and not open or write to the output dataset if the input stream is empty.

Files

todsn may obtain name matched profile information for a dataset from either a per-user profile or a system-wide profile on the z/OS system. For well known dataset-name patterns, profile options can be used to significantly reduce the specification of individual options on the command line. The file format and profile options are described in dsn_profile(5).

Examples

Local z/OS Examples

todsn //MVS1.DATASET1 %lt; myfile

Copies an HFS or zFS file to an MVS dataset.

todsn -o 'recfm=fb,lrecl=80' //MVS1.DATASET1 < myfile

Copies to an MVS dataset, overriding target DCB attributes.

todsn -w trunc //MVS1.DATASET1 < myfile

Copies to an MVS dataset, truncating long lines

todsn -x shr '//MVS1.MYLIB.DATA(MEMBER1)' < myfile

Copies to a PDS member, allocating with DISP=SHR.

todsn -r //test.data < myfile

Specifies a relative dataset name (HLQ will be added).

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

Copies an ASCII HFS file to an EBCDIC MVS dataset.

cat /home/user/rdw.bin | todsn -l rdw -r //my.dataset

Copies a binary HFS file with RDW-prefixed lines to an MVS dataset.

todsn -x "symlist(*)" //intrdr <myjcl.txt

Submits a file as a job to the internal reader. The pseudo BPXWDYN keyword symlist is used to specify that all JES system symbols are to be passed to the internal reader (requires z/OS 2.1).

Remote Client SSH Connection Examples

todsn -ssh user@myzos2.com -r //my.dataset </tmp/myfile

Uploads a file to an MVS Dataset over an SSH connection (Unix).

copy c:ata.txt con: | todsn -ssh user@myzos2.com -r //my.dataset

Uploads a file to an MVS Dataset over an SSH connection (Windows).

todsn -ssh user@myzos2.com -r '//my.pds(mem1)' <myfile

Uploads a file to an MVS PDS Member over an SSH connection (Unix).

copy c:ata.txt con: | todsn -ssh user@myzos2.com -r '//my.pds(mem1)'

Upload a file to an MVS PDS Member over an SSH connection (Windows).

cat /tmp/data | todsn -ssh -p 2222 user@myzos2.com -r '//my.pds(mem1)'

Uploads a file to an MVS Dataset with additional ssh options.

See Also

fromdsn(1)

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