Dovetailed Technologies

Name

tofile — read a stream of data from stdin and write to a z/OS POSIX file

Synopsis

tofile [OPTION...] filename
tofile -ssh [ssh-opt...] [user]@host [OPTION...] filename
tofile -local [OPTION...] filename
tofile -v
tofile -h
    

Description

The tofile command writes a stream of bytes to filename using a stream of data read from stdin. Codepage translation is performed and custom source line terminators are respected depending on the options provided.

The tofile 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: -ssh option

filename is a path to the z/OS POSIX file to write. It may be either an absolute path or relative path.

Options

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

Specifies a remote invocation of tofile 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. Applicable when the source and target are both z/OS. If specified, this must be the first command option.

-a

open filename in append mode.

-b

binary mode. Bytes are streamed as-is from stdin to the POSIX file.

-f

begin writing data to filename immediately (disable buffering). This is the default if used with a tunneled socket.

-h

display help and exit.

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

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.

-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 (default), Info, Debug, Trace, Fine.

t

Prefix log messages with a system timestamp

e

Include consumed cpu time in log messages

f=filename

Messages are logged to filename on the server instead of stderr. If not fully qualified, the file is written to the user's home directory on the server.

s

Messages are logged to SYSLOG facility instead of stderr

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

Set the logging threshold for a specific component. Specify only at the request of product support personnel.

-m file_access_mode

the file access mode (as an octal number) to apply to filename.

-n

do not replace filename if it exists.

-p

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

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

-s source-codepage

the codepage name or numeric CCSID id of the data read from stdin. If not specified and invoked from a remote client, the default client codepage is used.

-t target-codepage

the codepage name or numeric CCSID id of the output filename. If not specified, 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.

-u umask

the umask (as an octal number) to apply to filename.

-v

display the current version and exit.

-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 filename if the input stream is empty.

Examples

Local z/OS Examples

tofile -t ISO8859-1 /home/user/myfile.iso8859 < myfile

Creates a copy of an HFS or zFS file locally, translating the default z/OS process codepage to ISO8859-1.

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

Copies an HFS or zFS file to a new location, creating any missing path components (e.g. newdir).

Remote Client SSH Connection Examples

tofile -ssh user@myzos2.com /home/user/mydata < /tmp/data

Uploads a remote file over an SSH connection (Unix). Codepage translation is performed from the remote unix codepage to the current z/OS process codepage.

copy c:ata.txt con: | tofile -ssh user@myzos2.com myfile.txt

Uploads a remote file over an SSH connection (Windows). The target filename is relative to the current user's $HOME directory. Codepage translation is performed from the remote Windows codepage to the current z/OS process codepage.

tofile -ssh user@myzos2.com -b /home/user/data.bin < /tmp/data.bin

Uploads a remote file over an SSH connection as-is (no codepage translation is performed).

cat /tmp/myscript.sh | tofile -ssh -p 2222 user@myzos2.com -m 0777 /home/user/myscript.sh

Uploads a remote file with additional ssh options. The target file will be given a file access mask of 0777 (rwxrwxrwx), but is subject to the user's existing umask.

See Also

fromfile(1)

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