<transfer service>

──┬─ NFT ──────────┬───────────────────────────────────────────────────┤
  ├─ HOSTSERVICES ─┤
  ├─ HS ───────────┤
  ├─ FTP ──────────┤
  └─ SFTP ─────────┘

Explanation

The process of copying files between hosts is called a file transfer, and the software used to copy the files between hosts is called a transfer service. When you initiate a file transfer, distributed systems services determines which transfer service can be used for the hosts involved in the transfer. Since distributed systems services selects the most suitable transfer service, you do not have to specify the transfer service in the COPY statement. You should specify the transfer service only when you want to override the automatically selected transfer service.

Available File Transfer Services

The file transfer services that distributed systems services selects or that you specify in the COPY statement include the following:

Principles of Selection

The system selects the file transfer service based on the following conditions:

Order of Selection

The selection proceeds as follows:

Additional Considerations

If the COPY statement contains a copy request with multiple hosts, the appropriate service for each pair of source and destination hosts is selected. Therefore, it is possible for more than one transfer service to be used to transfer the files specified in a COPY statement. If a host is offline or does not exist, distributed systems services displays a message and disregards the copy request to that host. However, copy requests between other hosts, if valid, are still performed.

If a file is transferred between two remote hosts through the initiating host (rather than directly between the two remote hosts), all three hosts must use the same transfer service.

More About the File Transfer Services

Each of the file transfer services has certain features that you should know about and certain restrictions that you must observe. These features and restrictions are explained under “NFT File Transfers,” “Host Services File Transfers,” and “FTP File Transfers” found later in this section.

For more extensive information about transferring files between hosts on BNA or OSI networks, or about using NFT or Host Services File Transfer, refer to the Distributed Systems Services Operations Guide. For information about using FTP to transfer files between hosts on TCP/IP networks, refer to the TCP/IP Distributed Systems Services Operations Guide.

NFT File Transfers

<NFT copy or add statement>

──┬─ COPY ─┬─┬─────────────────────────────────────┬───────────────────►
  └─ ADD ──┘ │ ┌◄────────────────────────────────┐ │
             └─┴─┬─ AND ─┬─┬─ /1\ ── CATALOG ──┬─┴─┘
                 └─ & ───┘ └─ /1\ ─┬─ COMPARE ─┤
                                   └─ VERIFY ──┘
►─┬────────────────────────────────────┬───────────────────────────────►
  │     ┌◄────────── , ──────────┐     │
  └─ [ ─┴─┬─ /1\ ── FROMSTART ─┬─┴─ ] ─┘
          └─ /1\ ── NFT ───────┘
  ┌◄──────── , ────────┐
►─┴─<NFT copy request>─┴─┬─────────────────────────────┬───────────────►
                         └─ [ ──<task identifier>── ] ─┘
►─┬───────────────────────────┬────────────────────────────────────────┤
  └─<copy task equation list>─┘

<NFT copy request>

  ┌◄────────────────── , ──────────────────┐
──┴─<NFT file>─┬─────────────────────────┬─┴───────────────────────────►
               └─ FROM ──<source volume>─┘
    ┌◄──────────────── , ────────────────┐
►─┬─┴─ /47\ ── TO ──<destination volume>─┴─┬───────────────────────────┤
  └────────────────────────────────────────┘

<NFT file>

──┬─<long file name>─┬──────────┬─┬────────────────────────┬───────────┤
  │                  └─<origin>─┘ └─ AS ──<long file name>─┤
  ├─<long dir name>─┬──────────┬─┬─────────────────────────┤
  │                 └─<origin>─┘ └─ AS ──<long dir name>───┤
  └─<tape file number>──┬──────────────────────────────────┤
                        └─ AS ──<long file name>───────────┘

The following section describes NFT file transfers to disk.

Transferring Files to Disk

When you transfer a file to disk by using NFT, the FILENAME and FILEKIND attributes of the destination file are set aside temporarily while the file is being transferred. The FILENAME attribute is set to NFTTEMP/<file name>, and the FILEKIND attribute is set to FTAUDIT. These attributes are set to their original values following the successful transfer of the entire file.

When a file transfer fails and you reissue the original COPY statement, NFT restarts the interrupted file transfer. The resumption point depends on the kind of destination volume and the characteristics of the files being transferred. For more information on file transfer resumption, refer to the Distributed Systems Services Operations Guide.

Constraints

The following list describes the constraints for NFT file transfers:

Examples

The following examples illustrate the COPY statement syntax when NFT is used to transfer files between host systems.

This statement copies the file A from the family DISK on the local host to a pack named PACK on host HOSTB. For this example, assume that the COPY statement is part of a WFL job that is restarted if the file transfer fails. If the WFL job restarts, file A is completely re-transferred because the FROMSTART option is specified in the COPY statement.

COPY [NFT,FROMSTART] A TO PACK(HOSTNAME=HOSTB);

This statement copies files from the SYMBOL/= directory on the source CD-ROM volume SYMCD at host CENTER. It copies only those files under SYMBOL/= for which there is already a resident version on the SYM disk family:

REPLACE [NFT] SYMBOL/= 
  FROM SYMCD (CD, HOSTNAME=CENTER) 
  TO SYM (PACK); 

This WFL job copies the file A from the family DISK on the local host to a pack named PACK on the host HOSTB, taking advantage of the file transfer resumption feature of NFT:

BEGIN JOB NFT/RECOVERY;
  TASK T;
  RESUME:
  COPY A TO PACK(HOSTNAME=HOSTB)[T];
  IF T(VALUE) NEQ 0 THEN
    BEGIN
    WAIT(30);
    GO RESUME;
    END;
END JOB.

Host Services File Transfer

<HS copy or add statement>

──┬─ COPY ─┬─ [ ─┬─ HOSTSERVICES ─┬─ ] ────────────────────────────────►
  └─ ADD ──┘     └─ HS ───────────┘
  ┌◄──────── , ───────┐
►─┴─<HS copy request>─┴─┬─────────────────────────────┬────────────────►
                        └─ [ ──<task identifier>── ] ─┘
►─┬───────────────────────────┬────────────────────────────────────────┤
  └─<copy task equation list>─┘

<HS copy request>

  ┌◄────────────────── , ─────────────────┐
──┴─<HS file>─┬─────────────────────────┬─┴────────────────────────────►
              └─ FROM ──<source volume>─┘
    ┌◄──────────────── , ────────────────┐
►─┬─┴─ /47\ ── TO ──<destination volume>─┴─┬───────────────────────────┤
  └────────────────────────────────────────┘

<HS file>

──┬─<long file name>─┬────────────────────────┬────────────────────────┤
  │                  └─ AS ──<long file name>─┤
  └─<long dir name>─┬─────────────────────────┤
                    └─ AS ──<long dir name>───┘

When you transfer a file by using Host Services File Transfer, you must observe the following restrictions:

Examples

The following examples illustrate the COPY statement syntax when Host Services File Transfer is used to transfer files.

This statement copies the file X from DISK (at the local host) to DISK at host HOSTB, and names the new file Y. The HOSTSERVICES option is used to designate that Host Services File Transfer should be used to transfer the file.

COPY [HOSTSERVICES] X AS Y FROM DISK TO DISK(HOSTNAME=HOSTB);

This statement copies the file WEEKLY_SUMMARY (from DISK at the local host) to DISK at host HOSTB, and renames the file as WEEKLY/SUMMARY. In this example, HOSTB does not support NFT, so Host Services File Transfer is selected automatically.

COPY WEEKLY_SUMMARY AS WEEKLY/SUMMARY TO DISK(HOSTNAME=HOSTB);

This statement copies the file TIME/SUM from the disk ENGDATA at the host HOSTE as the file ENG/TIME/SUM on the disk ACCTDATA at the host HOSTA. In this example, HOSTE supports NFT but HOSTA does not. Therefore, Host Services File Transfer is automatically selected to copy the files.

COPY TIME/SUM AS ENG/TIME/SUM FROM ENGDATA
	(KIND=DISK,HOSTNAME=HOSTE)
TO ACCTDATA(KIND=DISK,HOSTNAME=HOSTA);

FTP File Transfers

SFTP File Transfers

<FTP copy>

── COPY ── [─┬─ FTP ──┬─ ] ────────────────────────────────────────────►   
             └─ SFTP ─┘
  ┌◄──────── , ────────┐
►─┴─<FTP copy request>─┴─┬─────────────────────────────┬───────────────►
                         └─ [ ──<task identifier>── ] ─┘
►─┬───────────────────────────┬────────────────────────────────────────┤
  └─<copy task equation list>─┘

<FTP copy request>

  ┌◄─────────────────────── , ──────────────────────┐ 
──┴─┬─<FTP file>──────┬─┬─────────────────────────┬─┴──────────────────►
    └─<FTP directory>─┘ └─ FROM ──<source volume>─┘
 ►─┬────────────────────────────────────────┬───────────────────────────┤   
   │ ┌◄──────────────── , ────────────────┐ │
   └─┴─ /47\ ── TO ──<destination volume>─┴─┘

<FTP file>

──┬─<long file name>─┬──────────────────────────────┬──────────────────►
  │                  └─ AS ─┬─<long file name>──────┤
  │                         └─<universal file name>─┤
  └─<universal file name>── AS ──<long file name>───┘
►─┬──────────────────┬─────────────────────────────────────────────────┤
  └─<FTP attributes>─┘

<FTP directory>

──┬─<long directory name>─┬───────────────────────────────────┬────────►
  │                       └─ AS ─┬─<long directory name>──────┤
  │                              └─<universal directory name>─┤
  └─<universal directory name>── AS ──<long directory name>───┘
►─┬──────────────────┬─────────────────────────────────────────────────┤
  └─<FTP attributes>─┘

<FTP attributes>

      ┌◄───────────────────── , ────────────────────┐
── ( ─┴─┬─/1\─ APPEND ─┬─────┬─┬──────────────────┬─┴─ ) ──────────────┤
        │              └─ = ─┘ ├─ TRUE ───────────┤
        │                      └─ FALSE ──────────┤
        ├─/1\─ FTPSITE ── = ──<string expression>─┤
        ├─/1\─ FTPSTRUCTURE ── = ─┬─ FTPFILE ─────┤
        │                         └─ FTPRECORD ───┤
        └─/1\─ FTPTYPE ── = ─┬─ ASCIINONPRINT ────┤
                             ├─ EBCDICNONPRINT ───┤
                             ├─ IMAGE ────────────┤
                             └─ MCPDATA ──────────┘

Explanation

When you transfer a file by using FTP, you should note that FTP does not distinguish between the ADD and COPY statements. A file existing under the name specified in the ADD statement is overwritten on a receiving host.

Any ASCII nonprint and EBCDIC nonprint files copied by using FTP reside on disk as FTPDATA files that are specially formatted. An FTPDATA file is not a standard MCP environment file kind and must be converted before it can be processed, printed, or viewed by MCP environment software. The FTP utility program can convert an FTPDATA file to a conventional MCP environment format with a title and certain other attribute values that you designate. For more information on converting FTPDATA files with the FTP utility, refer to the TCP/IP Distributed Systems Services Operations Guide.

When you transfer a file by using FTP, you must observe the following restrictions:

FTP Transform Attributes for Copying Files

The following FTP transform attributes are used to assign file characteristics to files that are transferred to a remote host through the FTP file transfer service.

APPEND

Appends the contents of the source file to the destination file. The APPEND attribute applies only if the destination is not on an MCP host.

FTPSITE

Specifies any of several options that are described in detail in the TCP/IP Distributed Systems Services Operations Guide.

FTPSTRUCTURE

Identifies the structure of the file that is being transferred.

FTPFILE represents the file structure where there is no internal structure. The file is considered to be a continuous sequence of data bytes. This is the default structure used when transferring a file if FTPSTRUCTURE is not specified.

FTPRECORD represents a record structure where the file is made up of sequential records.

FTPTYPE

Identifies the type of code format (either ASCII, EBCDIC, or image) in which the characters of the file are represented.

ASCIINONPRINT represents the file in ASCII format without vertical format information. Vertical format control characters provide printer instructions such as carriage return (CR), line feed (LF), new line (NL), form feed (FF), and so on. The ASCII format is the default code format type.

EBCDICNONPRINT represents the file in EBCDIC format without vertical format control information.

IMAGE represents the file in 8-bit transfer bytes. Data is sent as contiguous bits and must be stored as contiguous bits by the receiving host. If the receiving host must store the data in a manner such that the file (or record for a record-structured file) necessitates the padding of the file with 0 (zeroes) to some convenient boundary such as byte, word, or block, then the zeroes must be placed at the end of the file or record and the padding bits must be identifiable.

MCPDATA represents the file in EBCDIC format with added MCP attribute information. Embedded MCP attributes allow the file to be stored at the destination with the same attributes as the source file.

Examples

The following examples illustrate the COPY syntax when FTP is used to transfer files across a TCP/IP network.

This statement copies the file PAYROLL/TIMECARDS/061490 from DISK at the local host as the file [PAY735]TC061490.DAT on DISK at the remote host HQSYS1. Log-on information is passed to the remote host HQSYS1 with the USERCODE attribute.

COPY PAYROLL/TIMECARDS/061490 
  AS '[PAY735]TC061490.DAT'
	TO DISK(KIND=PACK, HOSTNAME=HQSYS1, 
  USERCODE=RMPAYR/MONEY/735);

This statement copies the file [PAY735]90AWARDS.DAT from DISK at the remote host HQSYS1 as the file PAYROLL/AWARDS/1990 on DISK at the local host.

COPY '[PAY735]90AWARDS.DAT' 
  AS PAYROLL/AWARDS/1990 
	FROM DISK(KIND=PACK, HOSTNAME=HQSYS1, 
	USERCODE=RMPAYR/MONEY/735) TO DISK;

The following examples show some uses of the FTP transform attributes.

Transfer by IP Address, with FTPTYPE = IMAGE

The following example transfers a file FILE1 as file 1 from a local MCP host to a remote host 125.32.1.1. The usercode is INV, the password is 4367, and the account number is 88315.

COPY FILE AS 'file1' (FTPTYPE = IMAGE) TO DISK(IPADDRESS =
	"125.32.1.1", USERCODE = INV/4367/88315)

Transfer by Domain Name, with FTPSTRUCTURE = FTPRECORD

The following example transfers a file PARTS.LIST as PARTS/LIST from a remote host NIC.DDN.MIL to a local MCP host. The FTPSTRUCTURE is set to FTPRECORD.

COPY "PARTS.LIST" AS PARTS/LIST (FTPTYPE = EBCDICNONPRINT,
  FTPSTRUCTURE = FTPRECORD) FROM DISK(DOMAINNAME = "NIC.DDN.MIL",
  USERCODE = FDR/''/'') TO TCP(PACK)

Transfer Using Secure Socket Layer (SSL) Protocol

The following example transfers FILEX from the MCP host MP156 to the local MCP host using SSL data encryption.

COPY [FTP] FILEX (FTPTYPE=IMAGE)
   FROM DISK (SSLMODE=IMPLICIT, USERCODE=PTF/PTF, HOSTNAME=MP156);

Transfer Using Secure Shell (SSH) Protocol

The following example transfers FILEX from the MCP environment to host MVHOST using SSH data encryption.

COPY [FTP] FILEX (FTPTYPE=ASCIINONPRINT) FROM DISK 
	TO DISK(USERCODE=ABC/ABC, HOSTNAME=MVHOST, AUTHMODE=SSH)

Transfer a Case-sensitive Directory

The following example transfers all files in the Test directory from a remote host to a local MCP host. The interchange name is used to preserve the case of the directory name sent to the remote host.

COPY 'Test'/= AS TEST/= FROM DISK 
	(DOMAINNAME = "rhel5", USERCODE = UC/PW)

Restarting COPY Interrupted File Transfers

When a host or network failure interrupts a COPY statement, the WFL job containing the COPY statement automatically restarts if the failure was caused by a halt/load process or if the job was written to restart after an unsuccessful file transfer.

The results of restarting the COPY statement depend on the type of transfer, as follows:

If some of the files were transferred with NFT, it might not be necessary for all files named in the COPY statement to be retransferred. Those files transferred with NFT may be transferred again according to the rules for the FROMSTART option, listed in the following item.

The resumption point depends on the kind of destination volume and the characteristics of the files being transferred. For more information about resuming a file transfer in NFT, refer to the Distributed Systems Services Operations Guide.