ssh-sft-stage

ssh-sft-stage — stage and destage MVS data sets and HFS files

Synopsis

ssh-sft-stage [-i, --input-file=FILE] [-s, --stage-file=FILE] [-o, --output-file=FILE] [-I, --input-file-ccs=CCS] [-S, --stage-file-ccs=CCS] [-O, --output-file-ccs=CCS] [-f, --stage-format=FORMAT] [-p, --profile] [-b, --buffer-size=BUFFER_SIZE] [-d|-D, --debug=STRING] [-v] [-V] [-h]

Description

ssh-sft-stage stages a file or data set, that is, converts it into transfer format, or destages a stage file, that is, converts it into a file or data set. File transfer advice strings and profiles can be used to control staging.

The Secure File Transfer Protocol (SFTP), and the way in which it is used in common Secure Shell implementations, requires that a file to be transferred is an octet sequence, that the file size is known, and that it is possible to seek to any position in the file. Staging transforms structured MVS data sets into such a format. On z/OS Unix such files are known as Hierarchical File System (HFS) files.

There are three transfer formats:

Line format is character-based and uses the newline character as a record delimiter.
Record format includes record length fields in the stored or transferred data.
Stream format stores records end-to-end and does not include any structural information.

Input files and output files may be HFS files or MVS data sets. Output MVS data sets must be pre-allocated with complete DCB parameters.

ssh-sft-stage performs coded character set (CCS) conversion when a CCS option is specified for both the stage file and the MVS data set. All the character sets known by the iconv() function are available. To see a list of the available character sets, run

> iconv -l

in the environment where you intend to run ssh-sft-stage.

The Tectia Server for IBM z/OS server program, sshd2, uses temporary memory files as stage files. This mechanism can be verified with ssh-sft-stage by omitting the -s option and using -i only or both the -i and -o options.

Options

ssh-sft-stage has both a long and short form for the options. Both are shown below – use either of the forms.

-i, --input-file=FILE: Specifes the name of the input file to be staged.
-s, --stage-file=FILE: Specifies the stage file name.
-o, --output-file=FILE: Specifies the file name resulting from destaging the stage file.
-I, --input-file-ccs=CCS: Specifies the CCS of the input file.
-S, --stage-file-ccs=CCS: Specifies the CCS of the stage file.
-O, --output-file-ccs=CCS: Specifies the CCS of the output file.
-f, --stage-format=FORMAT: Specifies the format of the stage file: stream, line, or record.
-b, --buffer-size=BUFFER_SIZE: Specifies the size of file buffer (in bytes).
-p, --profile: Enables file transfer advice profiles.
-d|-D, --debug=STRING: Enables debugging.
-v, --verbose: Generates verbose output.
-V, --version: Displays program version and exits.
-h, --help: Displays a short summary of command-line options and exits.

Files

Data Set Names

Write MVS data set names with leading slashes, e.g. //HANDY.PROGRAM.

HFS file names must include at least one slash, but not two at the start of the name.

Use single quotes for data set names that should not be prefixed with the user's prefix: "//'SYS3.HANDY.PROGRAM'"

Input and output files may also be members in PDS and PDSE libraries. Write the member name in parentheses. Use quoting to prevent the shell from trying to interpret the parentheses: "//'SYS3.CODE(HANDY)'"

Output Data Sets

MVS output data sets must be pre-allocated. Any content will be overwritten.

When destaging, overrunning the data set record length (or block size for the U data set organization) will cause the run to fail. Overrun can be caused by excessive record lengths when the stage file format is record or missing or improperly placed newline characters when the stage file format is line.

For the line format, the stage file must be encoded in EBCDIC or must be converted to EBCDIC with CCS options. The newline character must be NL (0x15 in hexadecimal and 025 in octal).

When the stage file format is line, fixed length records are padded with blanks. When the stage file format is record, fixed length records are padded with binary zeros. For the stream format, the last record may be padded with binary zeros.

Environment Variables

You must set these environment variables:

_BPXK_AUTOCVT=ON
_CEE_RUNOPTS='FILETAG(AUTOCVT,NOAUTOTAG)'

When verifying the use of a temporary memory file as the staging file, add a TRAP option to the _CEE_RUNOPTS variable. Specify TRAP(ON) to use a hiperspace memory file and TRAP(OFF) to use a normal memory file that uses memory in same the address space where ssh-sft-stage runs.

See the IBM z/OS C/C++ Run-Time Library Reference manual for these two variables, which influence how ssh-sft-stage performs character set conversions:

_ICONV_UCS2
_ICONV_UCS2_PREFIX