Staging

The current Secure Shell protocol, as implemented in third-party products and current Tectia versions, is designed for Unix files which are byte streams. While MVS data sets are record-based, they must be staged before sending or destaged after they have been received. Staging copies a data set 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.
Tectia client tools for z/OS support native MVS data set 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. For more information, see ssh-sft-stage(1).
Online staging places the byte stream in virtual storage when the file is transferred. The Tectia Server for IBM z/OS (server program) will use online staging automatically if a data set 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 disabled. You can also control staging in the server configuration. When staging is disabled, all clients are required to send the data in the correct order (as consecutive blocks from beginning to end) or else the file transfer fails. In case 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 enable 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:YES
```
Use the file transfer advice string in the put command:
```
sftp> put over2gigfile.txt /ftadv:S=YES///'target'
```

	Note
	If the file transfer client uses the SFTP protocol for transferring the files, and does not access the files or data sets in the correct order, staging must be enabled. If the client accesses file data in random offsets, or uses checksums, staging is necessary.

	Note
	When staging is used, do not set the `_CEE_RUNOPTS` environment variable's `TRAP` option to `OFF`. If you do, sftpg3 fails to start. The `TRAP` option is `ON` by default.

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 data set has to be staged offline.

Table 9.1. Staging summary

Client version	Server version	File size <2GB	File size >2GB
Tectia z/OS 5.2-	Any Unix/Windows	Native	Native
Tectia Unix/Win 5.2-	Tectia z/OS 5.2-	Native	Native
OpenSSH SFTP Client	Tectia z/OS 6.1-	Native	Native
Tectia z/OS 5.2-	Tectia z/OS 5.2-	Online	Offline
Tectia (all) 4.x-5.1	Tectia z/OS 5.2-	Online	Offline
3rd-party Unix/Win	Tectia z/OS 5.2-6.0	Online	Offline

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

//STAGE   EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT
//STDPARM  DD  *
PGM /opt/tectia/sbin/ssh-sft-stage -v
  -i /FTADV:F=LINE,D=IBM-1047,C=ISO8859-1///DD:PROGLI
  -s /tmp/stage.tmp
//STDENV   DD  DSN=&SYSUID..SSZ.WORK(SSHENV),DISP=SHR
//STDOUT   DD  SYSOUT=*
//STDERR   DD  SYSOUT=*
//STDIN    DD  DUMMY
//PROGLI   DD  DSN=&SYSUID..TEST.C.LIST,DISP=SHR
//