Tectia

Staging

The current Secure Shell protocol, as implemented in third-party products and current SSH Tectia versions, is designed for Unix files which are byte streams. While MVS datasets are record-based, they must be staged before sending or destaged after they have been received. Staging copies a dataset into byte stream format and may also convert the character set. Destaging transforms a byte stream into a file format and may also convert the character set. HFS files that do not need character set conversion, do not need to be staged.

There are two modes of staging:

  • Offline staging stores the byte stream as an HFS file. Offline staging incurs the overhead of writing the byte stream to disk and reading it.

    The SSH Tectia client tools for z/OS support native MVS dataset reading and writing and generally do not require staging. Offline staging is still needed if a file is transferred to an MVS server and the size of the file is larger than 2 GB.

    To use offline staging, you must run the ssh-sft-stage utility as a separate step.

  • Online staging places the byte stream in virtual storage when the file is transferred. The SSH Tectia Server for IBM z/OS (server program) will use online staging automatically if a dataset cannot be transferred directly.

    Online staging is more convenient and, for small files, more efficient. Online staging, for large files, will page out most of the byte stream and will page it in again. Online staging does not support files that are larger than 2 GB.

By default, staging is enabled on the server program of SSH Tectia Server for IBM z/OS, but on the clients, staging is disabled by default. The server program of SSH Tectia Server for IBM z/OS uses staging automatically when necessary.

However, you can disable staging also in the server configuration, but in that case all clients are required to send the data in correct order (as consecutive blocks from beginning to end) or else the file transfer fails. In case SSH Tectia Server for IBM z/OS detects changes in the order of the blocks, it stops the transfer and reports an error about non-serialized transfer.

To disable staging, use either one of the following methods:

  • Add the staging setting for sft-server-g3 into the sshd2_config configuration:

    subsystem-sftp /opt/tectia/libexec/sft-server-g3 --attribute=staging:NO
  • Use the file transfer advice string in command put:

    sftp> put over2gigfile.txt /ftadv:S=NO///'target'
[Note]Note

If the file transfer client uses SFTP protocol for transferring the files, and accesses the files or datasets in correct order, staging can be disabled. However, if the client accesses file data in random offsets, or uses checksums, staging will be necessary.

A summary of situations when staging is needed is shown in the following table. In the table, Native indicates that staging is not required, Online indicates that online staging is automatically used, and Offline indicates that the dataset has to be staged offline.

Table 9.1. Staging summary

Client versionServer versionFile size <2GBFile size >2GB
SSH Tectia z/OS 5.2-Any Unix/WindowsNativeNative
SSH Tectia Unix/Win 5.2-SSH Tectia z/OS 5.2-NativeNative
OpenSSH SFTP ClientSSH Tectia z/OS 6.1-NativeNative
SSH Tectia z/OS 5.2-SSH Tectia z/OS 5.2-OnlineOffline
SSH Tectia (all) 4.x-5.1SSH Tectia z/OS 5.2-OnlineOffline
3rd-party Unix/WinSSH Tectia z/OS 5.2-6.0OnlineOffline

SSH Tectia client tools for z/OS include a utility program, ssh-sft-stage, for offline staging and destaging. STAGE is a sample of JCL for running the staging utility located in SAMPLIB:

//STAGE   EXEC PGM=IKJEFT1A,
//             DYNAMNBR=75,
//             TIME=1440,
//             REGION=6M
//SYSPRINT DD  SYSOUT=*
//SYSTSPRT DD  SYSOUT=*
//SYSTERM  DD  DUMMY
//STDOUT   DD  PATH='/tmp/&SYSUID.-STAGE.out',
//             PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//             PATHMODE=(SIRUSR,SIWUSR)
//STDERR   DD  PATH='/tmp/&SYSUID.-STAGE.err',
//             PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
//             PATHMODE=(SIRUSR,SIWUSR)
//STDENV   DD  DSN=&SYSUID..SSZ.SRVR61.PARMLIB(SSHENV),
//             DISP=SHR
//PROGLI   DD  DSN=&SYSUID..TEST.C.LIST,
//             DISP=SHR
//SYSTSIN  DD  *
  BPXBATSL PGM /opt/tectia/sbin/ssh-sft-stage +
               -v +
               -i /FTADV:F=LINE,D=IBM-1047,C=ISO8859-1/+
                  //DD:PROGLI +
               -s /tmp/stage.tmp
  ALLOCATE FILE(PROUT1) DA(*) LRECL(252) RECFM(V,B) REUSE
  ALLOCATE FILE(PRERR1) DA(*) LRECL(252) RECFM(V,B) REUSE
  OCOPY INDD(STDOUT) OUTDD(PROUT1) TEXT PATHOPTS(OVERRIDE)
  OCOPY INDD(STDERR) OUTDD(PRERR1) TEXT PATHOPTS(OVERRIDE)
/*