Chapter 6 - Transferring Files
Advanced 3270/SNA allows you to transfer files between your VINES network and your SNA host. The host must be running one of these three applications:
CICS (Customer Information Control System) VM/CMS (Virtual Machine/Conversational Monitor System) MVS/TSO (Multiple Virtual Systems/Time Sharing Option)
This chapter discusses transferring files between an Advanced 3270/SNA workstation and an SNA host running any of these applications.
Requirements for Transferring Files
Before you can transfer files between the SNA host and your workstation, you must have at least one display LU configured on your workstation.
To transfer files, you must use the programs SNA_SND and SNA_RCV. These programs are run after you use the Hotkey to return to DOS from the Advanced 3270/SNA emulator.
SNA_SND and SNA_RCV have many command line switches. The switches vary according to the application running on the host. The switches for each host operating system are explained in detail later in this chapter.
Procedure for Transferring Files
To transfer a file between an Advanced 3270/SNA workstation and the host, follow these steps:
1. Obtain the name of the file transfer program that is running on the host. Advanced 3270/SNA expects the program name for the host portion of file transfer to be IND$FILE.
If the program has a different name, you must notify the file transfer software using the DOS SET command. You can enter the SET command at the keyboard before you run SNA_SND or SNA_RCV, or include it in a DOS batch file. The format for the command is:
SET IND$FILE = NEWNAME
When you enter either the SNA_SND or SNA_RCV command at the PC, Advanced 3270/SNA starts the IND$FILE program on the host.
2. Run the emulator software. (See the section in Chapter 2 entitled "Running Advanced 3270/SNA Software" for complete details.)
3. Log on to the host.
4. Press the Hotkey to go to DOS.
5. Run SNA_SND or SNA_RCV using the command syntax indicated in the next section.
In the command lines below, trailing parameters in square brackets [ ] are optional; those without brackets are mandatory.
To send files to a CICS host, use the following command format:
SNA_SND [/MT=n] [/SM] [/DS] [/SW] [/SN=a] [/TI=n] pcfile hostfile [(options] [)comments]
Receiving Files From a CICS Host
To receive files from a CICS host, use the following command format:
SNA_RCV [/MT=n] [/SM] [/DS] [/SW] [/SN=a] [/TI=n] pcfile hostfile [(options] [)comments]
Sending Files to a VM/CMS Host
To send files to a VM/CMS host, use the following command format:
SNA_SND [/MT=n] [/SM] [/DS] [/SW] [/SN=a] [/TI=n] pcfile hostfile type [(options]
Receiving Files From a VM/CMS Host
To receive files from a VM/CMS host, use the following command format:
SNA_RCV [/MT=n] [/SM] [/DS] [/SW] [/SN=a] [/TI=n] pcfile hostfile type [mode] [(options]
Sending Files to an MVS/TSO Host
To send files to an MVS/TSO host, use the following command format:
SNA_SND [/TI= n] [/MT= n] [/SM] [/DS] [/SW] [/SN=a] pcfile datasetname [(membername)] [/password] [options]
Receiving Files from an MVS/TSO Host
To receive files from an MVS/TSO host, use the following command format:
SNA_RCV [/TI=n] [/MT=/n] [/SM] [/DS] [/SW] [/SN=a] pcfile datasetname [(membername)] [/password] [options]
The command line parameters, switches, and options for all of these applications are described in the next several sections.
Required File Transfer Command Parameters
The SNA_SND and SNA_RCV commands have many trailing parameters. Some are optional. Some are mandatory. This section discusses command line parameters that are required by SNA_SND and SNA_RCV.
Required Command Parameters for CICS
The following command lines show the required parameters for file transfers between Advanced 3270/SNA and a host running CICS.
SNA_SND pcfile hostfile
SNA_RCV pcfile hostfile
pcfile - The file name must conform to the standard DOS file naming convention in the format drive:\path\filename.ext.
hostfile - The host file name must follow the CICS naming conventions. Refer to your CICS documentation for more information.
Required Command Parameters for VM/CMS
The following command lines show the required parameters for file transfers between Advanced 3270/SNA and a host running VM/CMS.
SNA_SND pcfile hostfile type
SNA_RCV pcfile hostfile type
pcfile - The file name must conform to the standard DOS file naming convention in the format drive:\path\filename.ext.
type - Specifies the type of VM/CMS file. For more information, refer to the appropriate IBM documentation.
Required Command Parameters for MVS/TSO
The following command lines show the required parameters for file transfers between Advanced 3270/SNA and a host running MVS/TSO.
SNA_SND pcfile datasetname
SNA_RCV pcfile datasetname
pcfile - The file name must conform to the standard DOS file naming convention in the format drive:\path\filename.ext.
datasetname - The datasetname must follow MVS/TSO naming conventions. For more information refer to the appropriate MVS/TSO documentation.
The following switches are optional. These should be placed after the required parameters discussed in the previous section.
These switches apply to all three host applications unless it is stated otherwise below. These switches always apply to both the SNA_SND and SNA_RCV programs.
)comments - Comments must always appear at the end of the SNA_SND or SNA_RCV command line for CICS applications. See the section entitled "Examples of CICS File Transfers" later in this chapter.
Comments apply only to file transfers between Advanced 3270/SNA and CICS.
/DS - Display Statistics. When this switch is specified, Advanced 3270/SNA displays information concerning the file transfer, such as the number of characters and bytes transferred. If you do not specify this switch, statistics are not displayed.
(membername) - The name of a single member in an existing partitioned MVS/TSO data set. The membername parameter is always enclosed in parentheses.
This parameter applies only to file transfers between Advanced 3270/SNA and MVS/TSO.
mode - VM/CMS file mode. If you do not specify a mode, Advanced 3270/SNA uses a default of A1.
This parameter applies only to file transfers between Advanced 3270/SNA and VM/CMS. For a complete list of VM/CMS file modes, refer to your VM/CMS documentation.
/MT=n - Message Type. Message Type is the prefix on file transfer messages. Assign n the value 0 or 1 to set the prefix of local messages.
If n equals 0, SNA_SND assigns local messages the prefix PDINS to distinguish them from host messages.
If n equals 1, SNA_SND assigns local messages the same prefix as host messages, TRANS.
/password - A file access password. This is required if the MVS/TSO data set is password protected.
/SM - Suppress Message. This parameter suppresses all messages from the file transfer software and the host. It also suppresses error messages from a failed file transfer attempt. Display Messages is the default.
/SN=a - Session Short Names. By default, Session Short Names are assigned by the Advanced 3270/SNA emulator to each host session running concurrently in the PC. The Short Name values are E through I, and are assigned in the order in which they appear when you flip through the sessions or bring up windows. Thus, the first host session has the Short Name E, the next session has the Short Name F, and so on.
You can specify through which host session the file transfer occurs by assigning a the value E through I. If no Short Name is defined, Advanced 3270/SNA uses the host session from which you transferred using the HotKey.
/SW - Suppress Warning. Warning messages describe conditions in which files were transferred, but with unpredictable results. For example, a warning may state that the file was transferred, but certain sectors on the destination disk may be damaged. In this case, check the file to see if the data is intact. If you use the /SW switch, these warnings are suppressed.
/TI=n - Timeout value. The timeout value supplies the number of seconds that Advanced 3270/SNA waits for a response from the host before it terminates the file transfer or issues an error message. Maximum value is 32767 seconds. 60 seconds is the default value. Use this parameter to change the timeout value.
Note: If you set the timeout value to 0, the workstation keyboard will lock when an error occurs during file transfer. The TI=0 switch sets an infinite timeout, so the Advanced 3270/SNA software waits forever on the host.
Command line options are delimited by an open parenthesis character. They appear after the command line switches on the SNA_SND or SNA_RCV command line.
The options below apply to file transfers with all three host applications, unless stated otherwise. These options also apply to both SNA_SND and SNA_RCV unless stated otherwise.
ASCII - Identifies the PC file as a file consisting of ASCII character codes. The host converts the ASCII file into EBCDIC code for storage and use on the host.
ASCII and BINARY are mutually exclusive. Always use ASCII and CRLF when sending files to the host.
APPEND - Attaches the PC file to the end of the named host file. APPEND prevents the PC file from overwriting the host file. APPEND overrides the LRECL and RECFM options.
This option applies only to file transfers between Advanced 3270/SNA and hosts running either VM/CMS or MVS/TSO.
BINARY - Identifies the PC file as a file containing encrypted data, load modules, or other binary data. Data is transferred as is, without conversion.
BINARY and ASCII are mutually exclusive.
BLKSIZE(n) - Specifies the block size of the host data set, where n equals the number of bytes in a data block.
This option applies only to file transfers between Advanced 3270/SNA and hosts running MVS/TSO.
CRLF - Directs the host to delete the Carriage Return (CR) and Line Feed (LF) characters that separate logical records in the PC file. The host stores the data in a temporary storage queue.
CRLF and NOCRLF are mutually exclusive. Always use ASCII and CRLF when sending files to the host.
LRECL(n) - Specifies the logical record length for the host file, where n equals the number of characters in each record. If you are sending variable length records, n equals the maximum length the host accepts or the length of the longest record actually sent.
If you do not specify a length, the host uses a default record length of 80 characters. If you are replacing a file, the default value equals the maximum record length of the existing file. Do not use LRECL with APPEND. APPEND overrides LRECL.
This option applies only to file transfers between Advanced 3270/SNA and hosts running either VM/CMS or MVS/TSO.
NOCRLF - Indicates that the PC file does not separate logical records with CR and LF characters. NOCRLF directs the host to place each uploaded record in its temporary storage queue as a separate item.
NOCRLF and CRLF are mutually exclusive.
RECFM x - Specifies the record format, where x is F, V or U. Specify records as either fixed length (F) or variable length (V) when you are transferring files between Advanced 3270/SNA and either VM/CMS or MVS/TSO. You can specify records of an undefined length (U) only if you are transferring files between Advanced 3270/SNA and MVS/TSO.
If you use SNA_SND to send a new file and omit RECFM, the host assumes the records are of fixed length, unless you specify CRLF. With CRLF, the host assumes the records are of variable length. Do not use RECFM with APPEND. APPEND overrides RECFM.
The following command line is an example of how to send a file with fixed length records:
SNA_SND A:CLIENTS.BAS SOEAST BASIC A1 (ASCII CRLF RECFM F
SNA_SND transfers a copy of the PC file CLIENTS.BAS on drive A to the host file SOEAST. SOEAST is of the type BASIC and mode A1. ASCII directs the host to convert the file to EBCDIC. CRLF deletes the CR (carriage return) and LF (line feed) characters that mark the end of the file's logical records. RECFM F identifies the records as fixed length.
RECFM applies only to file transfers between Advanced 3270/SNA and hosts running either VM/CMS or MVS/TSO.
SPACE(quantity[,increment]) x - specifies the amount of space to be allocated on the host for the new data set. First specify the quantity and increment values, then the storage unit: AVBLOCK(n), TRACKS, or CYLINDERS. If you do not specify a space option, SNA_SND uses the value of BLKSIZE as the default data set size. (If BLKSIZE is not specified, SNA_SND uses the LRECL value.)
The x represents one of three arguments:
AVBLOCK(n) where n is the Average Block Length, in bytes, to allocate on the host. This parameter is used primarily for transfers where the record format parameter (RECFM) is specified as undefined (U). TRACKS is the number of tracks to allocate on the host hard disk. CYLINDERS is the number of cylinders to allocate on the host hard disk.
SPACE applies only to the SNA_SND command. It is used only for files sent to MVS/TSO.
Examples of the SPACE Parameter
The following examples show how the SPACE parameter looks when it is entered on a command line. Note that the rest of the command line is omitted for the sake of simplicity.
SPACE(20,10) tracks
This trailing parameter would allocate 20 tracks on the host, in increments of 10.
SPACE(30,5) cylinders
This trailing parameters would allocate 30 cylinders in increments of 5.
SPACE(20) avblock(10)
This trailing parameter would allocate a total of 20 blocks. The average length of these blocks would be 10 bytes.
This section gives guidelines and examples about using the Advanced 3270/SNA file transfer software with a host running IBM CICS (Customer Information Control System) file transfer software.
When you transfer files between Advanced 3270/SNA and CICS, you should keep the following points in mind:
The host stores files you send it in a temporary storage queue. Each item in the queue represents a logical record. Items in the queue need not be of the same length. The maximum allowable length of a record is 32,767 bytes. If you send the host a file that exceeds the size of the storage queue or is longer than 32,767 bytes, the file transfer might fail.
Null (empty) records in a PC file are represented by two consecutive pairs of CR (carriage return) and LF (line feed) characters. CICS file transfer represents null records as a pair of blanks in the temporary storage queue on the host.
If you transfer files with the ASCII option, the host translates the file into EBCDIC and inserts EBCDIC blanks (hexadecimal 40) in the file to represent any null records. If you transfer files with the BINARY option, translation is unnecessary. The host inserts ASCII blanks (hexadecimal 20) to represent any null records.
In a host file, blank characters that pad fixed-length records represent null characters. If you transfer files with the ASCII option, the host strips out the EBCDIC blanks (hexadecimal 40) before sending. If you transfer files with the BINARY option, the host strips out ASCII blanks (hexadecimal 20).
There are four command options for use with CICS systems:
ASCII BINARY CRLF NOCRLF
The default values are ASCII and CRLF. Advanced 3270/SNA uses ASCII and CRLF together even if you specify only one. Likewise, Advanced 3270/SNA uses BINARY and NOCRLF together even if you specify only one.
Examples of CICS File Transfers
This section shows four examples of CICS file transfers.
1. The SHOWS.BAT file in the SCHEDULES directory on drive E is transferred to a host file named TSHOWS. The command includes the ASCII option and a comment.
SNA_SND E:\schedules\shows.bat tshows (ascii)schedule
2. The LABELS.EXE file on drive C is transferred to the host file MLABELS. The command includes the BINARY option and a comment.
SNA_SND C:labels.exe mlables (binary)address labels
3. The host transfers the file ECNA711 to a PC file named ENGCHNGE.BAT on the default drive. Advanced 3270/SNA sends the file to the PC as an ASCII text file.
SNA_RCV engchnge.bat ecna711 (ascii
4. The SNA_RCV program transfers the file TIMEMGT to a PC file named CALENDAR.EXE in the SCHEDULES directory on drive D. Advanced 3270/SNA sends the file to the PC as a BINARY file.
SNA_RCV d:\schedules\calendar.exe timemgt (binary
This section describes how to use the Advanced 3270/SNA File Transfer software with a host running IBM VM/CMS (Virtual Machine/Conversational Monitor System) file transfer software.
There are eight command options for use with VM/CMS:
APPEND use only with SNA_RCV ASCII BINARY CRLF LRECL (n) use only with SNA_SND NOCRLF RECFM F use only with SNA_RCV RECFM V use only with SNA_RCV
Advanced 3270/SNA file transfer uses the defaults of BINARY and NOCRLF unless you override them with ASCII and CRLF. You cannot enter BINARY and NOCRLF directly in an SNA_SND command. They are in use unless you override them.
Examples of VM/CMS File Transfers
This section shows two examples of VM/CMS file transfers.
1. In this example, SNA_SND transfers a copy of the PC file SALES.BAS on drive C to the host file NOWEST. NOWEST is of the type BASIC and mode A1. ASCII directs the host to convert the file to EBCDIC. CRLF deletes the CR (carriage return) and LF (line feed) characters that mark the end of the file's logical records. RECFM V identifies the records as variable length.
SNA_SND C:Sales.bas Nowest basic a1 (ascii crlf recfm v
2. In the next example, the SNA_RCV program transfers a copy of the host file MAIL (of type BASIC and mode A1) to a PC file named MAILIST.BAS on drive B. The ASCII option converts the host file to ASCII code, and the CRLF option inserts CR and LF characters at the end of each line.
SNA_RCV b:mailist.bas mail basic a1 (ascii crlf
This section gives some guidelines and examples for transferring files between VINES and IBM MVS/TSO (Multiple Virtual Systems/Time Sharing Option).
Use the Hotkey to return to emulation after Advanced 3270/SNA transfers the file.
There are eleven command options for use with MVS/TSO:
APPEND use only with SNA_SND ASCII BINARY BLKSIZE use only with SNA_SND CRLF LRECL use only with SNA_SND NOCRLF RECFM F use only with SNA_SND RECFM V use only with SNA_SND RECFM U use only with SNA_SND SPACE use only with SNA_SND
Banyan recommends that you always use the ASCII and CRLF options when sending text files to the host.
See the section entitled "Command Line Options" for more information.
Examples of MVS/TSO File Transfers
This section shows four examples of MVS/TSO file transfers.
1. SNA_SND transfers a copy of the PC file PAYROLL.BAS on drive D to the host data set PAY.BASIC. /PROTECTS is a password. LRECL sets the logical record length at 132 to override the default value of 80. RECFM f specifies a fixed length record format. SPACE allocates a total of 20 tracks in increments of ten for the new data set.
SNA_SND d:payroll.bas pay.basic /protects lrecl(132) recfm(f) space (20,10) tracks
2. File PAYROLL.BAS on drive D is transferred to the host data set PAY.BASIC. This command includes a member name (RATE85) and specifies a block size of 128 bytes.
SNA_SND d:payroll.bas pay.basic (rate85) blksize(128)
3. SNA_RCV transfers a copy of the data set SALES.BASIC to the PC file SALES.BAS on drive D. /PROTECT is a password. (The file is not password protected on the PC.)
SNA_RCV b:sales.bas sales.basic /protects
4. SNA_RCV transfers a copy of the data set FINSTAT85 to the PC file REPORTS.TXT on drive C. /ADMIN is a password. The command uses ASCII and CRLF options because it is transferring text files.
SNA_RCV c:reports.txt finstat85 /admin ascii crlf
To interrupt file transfer, press the <CTRL> and <BREAK> keys at the same time. Either or both of the following messages are displayed:
TRANS53 Break requested, please wait
^C
The TRANS53 message indicates the Advanced 3270/SNA will terminate the file transfer programs on both the PC and the host.
The ^C message indicates that DOS terminated file transfer.
Switch over to the host system and check to see if the host file transfer program is still active. If the host program is still active, terminate it by pressing the <PF2> key.
