todsn — read a stream of data from stdin and write records to a z/OS dataset
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 which was started by Co:Z launcher.
remotely, from a client that started a durable session to the server using the cozcontrol command.
remotely, from a client-initiated ssh connection:
The user has wide flexibility in choosing:
dataset-nameis 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
-r option below). If
starts with 'DD:', then it refers to an existing DDNAME.
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.
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.
Specifies the use of local z/OS I/O, even if run via CoZLauncher. Applicable when the source and target are both z/OS. If specified, this must be the first command option.
dataset-namein append/mod mode. This option changes the base fopen() options to
binary flow mode, same as
begin writing data to
dataset-nameimmediately (disable buffering). This is the default if used with a tunneled socket or if
dataset-namerefers to a SYSOUT data set.
display help and exit.
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.
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.
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.
source lines are followed with a hex character sequence. The sequence must be between 1 and 8 bytes long.
source lines do not have separators; source lines are determined by the maximum output record length.
A comma-separated list of options to control logging and tracing.
Logging threshhold: eMergency, Alert, Critical, Error, Warning, Notice (default), Info, Debug, Trace, Fine.
Prefix log messages with a system timestamp
Include consumed cpu time in log messages
Messages are logged to
filenameon the server instead of stderr. If not fully qualified, the file is written to the user's home directory on the server.
Messages are logged to SYSLOG facility instead of stderr
Set the logging threshold for a specific component. Specify only at the request of product support personnel.
additional mode arguments to the z/OS C library fopen() routine. The base mode options used by todsn to open
dataset-nameare "wb,type=record,noseek". Example: "-o recfm=vb,lrecl=1028". See "z/OS C++ Programming Guide" for details.
pad character. The default is the source codepage space character.
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).
dataset-namewill be prefixed with the current z/OS userid.
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.
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.
-TSTANDARD | translate_table_dsname
Specifies the translate table to use for text mode transfers. This option overrides the
-s -t -qoptions 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.
display the current version and exit.
an error is returned if the source line is longer than the maximum record length.
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.
source lines longer than the maximum record length are truncated
source lines longer than the maximum record length are broken into multiple records. The default is 'wrap'.
can be specified to provide more precise control over dataset allocation than the fopen-options. These allocation options allow
dataset-nameto be created with specific space and disposition parameters, or allow
dataset-nameto be created like an already existing dataset. If
dataset-nameis '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". Note: DCB options such as RECFM, LRECL, and BLKSIZE must be specified on the -o option.
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.
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).
Local z/OS Examples
todsn //MVS1.DATASET1 < 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
symlistis 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 email@example.com -r //my.dataset </tmp/myfile
Uploads a file to an MVS Dataset over an SSH connection (Unix).
todsn -ssh firstname.lastname@example.org -r '//my.pds(mem1)' <myfile
Uploads a file to an MVS PDS Member over an SSH connection (Unix).
cat /tmp/data | todsn -ssh -p 2222 email@example.com -r '//my.pds(mem1)'
Uploads a file to an MVS Dataset with additional ssh options.