This chapter gives details on using the BARR/3270 file transfer program, including features of the file transfer program, performing file transfer between BARR/3270 and common host environments, and description of messages one might see during file transfer.
BARR/3270 supports foreground and background file transfer from both the DOS and 3270 sessions. During foreground file transfer, you can start the file transfer from DOS or a 3270 session and remain in that session until the transfer completes. During background file transfer, you can start the file transfer from DOS or a 3270 session and then switch to another session to perform useful interactive work while the file transfer takes place in the background. In this way, simultaneous file transfers from several sessions can take place in the background while other tasks are done in the interactive session.
Performing file transfer between the PC and an IBM host requires that the IND$FILE program be installed at the host.
For CMS, File Transfer program number 5664-281 is required.
For TSO, File Transfer program number 5665-311 is required.
For CICS/VM, File Transfer program number 5789-DQH is required.
To perform file transfer, BARR/3270 uses the Distributed Data Management (DDM) architecture protocol. In this protocol, the host and the PC communicate using Write Structured Fields (WSF). In 3270, WSFs are supported only in the extended mode. herefore, to perform file transfer using BARR/3270, the session from which file transfer is to take place should be connected to the host using an extended LOGMODE. For examples of an extended LOGMODE used for file transfer, see Appendix D.
BARR/3270 supports inbound data packet size in the range from 1000 to 8000 bytes. Data packet size is host-dependent and is specified by the user in the Installation program. A default data packet size of 4000 bytes is used. When file transfer is taking place, a message indicating the progress of the file transfer is continuously displayed and updated. If no progress is made, the file transfer is cancelled after a one-minute time-out period. You can cancel a file transfer after it has started by pressing CTRL-Break.
Before beginning file transfer from a 3270 session, you should be logged on to the desired host environment (TSO, VM/CMS, or CICS) and be at the READY prompt in TSO or at the command level in VM/CMS or CICS.
PC file names used during file transfer under TSO, VM/CMS, or CICS should follow these conventions.
PC Filename
The name of the file to be sent. It should be a valid DOS file name in the format
[d:][path]filename[.ext]
where
d: is the drive specifier. If not specified, the default drive is assumed.
path is the directory path.
filename is the name of the PC file.
.ext is the file extension.
Host Filename
The Host file name depends on which operating system you are using. See the sections specific to TSO, VM/CMS, or CICS later in this chapter for more information.
You can invoke the file transfer program either by pressing CTRL-F3 or by selecting the File Transfer function from the on-line Help menu. Once the file transfer program is invoked, this screen appears:
Send
Transfers a file from the PC to the host. The Send file parameter screen displays when this option is selected.
Receive
Transfers a file from the host to the PC. The Receive file parameter screen displays when this option is selected.
Escape
Exits the file transfer program and returns you to the 3270 session.
At the TSO Ready prompt, display the file transfer utility and invoke the Send command. This screen appears:
PC Filename
Valid DOS file name. See File Name Conventions in Section 11.
Host Filename
The name of a TSO data set or the name of a member in a partitioned data set. If the host file already exists, it will be overwritten.
Options
Options allow you to specify to the host any changes to be made to the file during transfer. If no options are specified, system defaults are used. The following options are allowed in TSO Send file transfer:
/password
APPEND
ASCII
CRLF
LRECL(n)
BLKSIZE(n)
RECFM(F)
RECFM(V)
RECFM(U)
SPACE(q[,i])
AVBLOCK(value)
TRACKS
CYLINDERS
For example,
If this option is not specified, the default is the BLKSIZE.
Below is a TSO Send file example screen:
Use the up and down arrow keys to move between the input fields. ESC cancels the Send command.
After supplying the required information, press ENTER to start file transfer. You can cancel a file transfer after it has started by pressing CTRL-Break.
At the TSO Ready prompt, display the File Transfer utility and invoke the Receive command. This screen appears:
PC Filename
Valid DOS file name. See File Name Conventions in Section 11.1. If a PC file with the same file name and extension exists, it is overwritten.
Host Filename
The Host Filename is the name of an existing TSO data set or the name of a member in a partitioned data set.
Options
Options allow you to specify to the host any changes to be made to the file during file transfer. If no options are specified, the defaults are used. The following options are allowed in TSO Receive file transfer:
APPEND
ASCII
CRLF
This is a Receive file transfer screen:
Use the up and down arrow keys to move between the input fields. ESC cancels the Receive.
After supplying the required information, press ENTER to start file transfer. You can cancel a file transfer after it has started by pressing CTRL-Break.
At the VM/CMS command level, display the File Transfer utility and invoke the Send command. This screen appears:
PC Filename
Valid DOS file name. See File Name Conventions in Section 11.1.
Host Filename
The host file name is in the format
filename filetype [filemode]
where
filename is the 1-8 character VM/CMS file name.
filetype is the 1-8 character VM/CMS file type.
filemode is the optional file mode. (Default file mode is A1).
Options
Options allow you to specify to the host any changes to be made to the file during transfer. If no options are specified, the defaults are used. For VM/CMS, options must appear in parentheses. The following options are allowed in VM/CMS Send file transfer:
APPEND
ASCII
CRLF
LRECL
n
RECFM
F
RECFM
V
Here is a Send file example:
Use the up and down arrow keys to move between the input fields. ESC cancels the Send.
After supplying the required information, press ENTER to start file transfer. You can cancel a file transfer after it has started by pressing CTRL-Break.
Invoke the Receive command from the File Transfer utility at the CMS command level. This screen appears.
PC Filename
Valid DOS file name. See File Name Conventions in Section 11.1. If a PC file with the same file name and extension exists, it will be overwritten.
Host Filename
The host file name is in the format
filename filetype [filemode]
where
filename is the 1-8 character VM/CMS file name
filetype is the 1-8 character VM/CMS file type
filemode is the optional file mode. (Default file mode is A1).
Options
Options allow you to specify to the host any changes to be made to the file during transfer. If no options are specified, the defaults are used. For VM/CMS, options must appear in parentheses. The following options are allowed in VM/CMS Receive file transfer:
APPEND
ASCII
CRLF
Below is an example of the information to be entered in the Receive file transfer utility fields:
Use the up and down arrow keys to move between the input fields. ESC cancels the Receive.
After supplying the required information, press ENTER to start file transfer. You can cancel a file transfer after it has started by pressing CTRL-Break.
At the MVS/CICS command level, display the File Transfer utility and invoke the Send command. This screen appears:
PC Filename
Valid DOS file name. See File Name Conventions in Section 11.1.
Host Filename
The host file name is the 1 to 8 character name of the CICS file to be created.
Options
Options allow you to specify to the host the changes to be made to the file during transfer. If no options are specified, the defaults are used. For MVS/CICS, options must appear in parentheses. The following options are allowed in MVS/CICS Send file transfer:
ASCII
BINARY
CRLF
NOCRLF
Below is an example of the information to be entered in the Send file transfer utility fields:
Use the up and down arrow keys to move between the input fields. ESC cancels the Send.
After supplying the required information, press ENTER to start file transfer. You can cancel a file transfer after it has started by pressing CTRL-Break.
At the MVS/CICS command level, display the File Transfer utility and invoke the Receive command. This screen appears:
PC Filename
Valid DOS file name. See File Name Conventions in Section 11.1.
Host Filename
The host file name is the 1 to 8 character name of the CICS file to be received. The host file name must match the name in the first record of the CICS file in the CICS TS download queue.
Options
Options allow you to specify to the host the changes to be made to the file during transfer. If no options are specified, the defaults are used. For MVS/CICS, options must appear in parentheses. The following options are allowed in MVS/CICS Receive file transfer:
ASCII
BINARY
CRLF
Below is an example of the information to be entered in the Receive file transfer utility fields:
Use the up and down arrow keys to move between the input fields. ESC cancels the Receive.
After supplying the required information, press ENTER to start file transfer. You can cancel a file transfer after it has started by pressing CTRL-Break.
File transfer in any of the 3270 sessions can be invoked from the DOS session using Send and Receive commands. This feature allows you to enter file transfer commands in a batch file for frequent transfer of files with the same names or for unattended file transfer.
Before file transfer can begin, the 3270 session should be logged on to the desired host environment.
To send a file from the PC to the TSO host, type the following at the DOS prompt:
Press ENTER.
To receive a file from the TSO host to the PC, type the following at the DOS prompt:
Press ENTER.
where:
a: is the optional drive specifier of where the SEND.EXE/RECEIVE.EXE file resides (usually the directory where you installed the BARR/3270 program).
send is the file transfer Send program.
receive is the file transfer Receive program.
/N is the NOWAIT option. When specified, the file transfer is started when the DOS prompt is displayed. Allows you to execute another DOS function before the file transfer is complete. Transfer progress messages will not display.
d: is the drive specifier of the PC file. If not specified, the default drive is assumed.
path is the directory path of the file to be sent or received.
filename is the name of the PC file to be sent or received.
.ext is the extension of the PC file to be sent or received.
s: is the EHLLAPI short name of the 3270 session in which file transfer is to take place. Each 3270 display terminal session is assigned a short name starting at A for the first session. For example, if Session 1 is a display terminal session, Session 2 is a printer, and Session 3 is another display terminal session, the short names would be A for Session 1 and B for Session 3; printer sessions are not assigned short names. If this parameter is not specified, the transfer takes place in the first display terminal session.
dsn is the TSO data set name of the host file.
(member) Member name to use if the data set name is a partitioned data set.
options Options to be used during the file transfer. (See Section 11.2 for available TSO Send/Receive options.)
Press ENTER.
For example,
will use the c:\SEND.EXE program to send the ASCII file a:\senddir\grades.dat to the EBCDIC host data set student(grades) via Session 3. The DOS prompt redisplays after the transfer begins.
To send a file from the PC to the VM/CMS host, type the following at the DOS prompt:
Press ENTER.
To receive a file from the VM/CMS host to the PC, type the following at the DOS prompt:
Press ENTER.
where:
a: is the optional drive specifier of where the SEND.EXE/RECEIVE.EXE resides (usually the directory where you installed the BARR/3270 program).
send is the file transfer send program.
receive is the file transfer receive program.
/N is the NOWAIT option. When specified, the file transfer is started when the DOS prompt is displayed. Allows you to execute another DOS function before the file transfer is complete. Transfer progress messages will not display.
d: is the drive specifier of the PC file. If not specified, the default drive is assumed.
path is the directory path of the PC file.
filename is the name of the PC file.
.ext is the extension of the PC file.
s: is the EHLLAPI short name of the 3270 session in which file transfer is to take place. Each 3270 display terminal session is assigned a short name starting at A for the first session. For example, if Session 1 is a display terminal session, Session 2 is a printer, and Session 3 is another display terminal session, the short names would be A for Session 1 and B for Session 3; printer sessions are not assigned short names. If this parameter is not specified, the transfer takes place in the first display terminal session.
fn is the 1-8 character CMS file name.
ft is the 1-8 character CMS file type.
fm is the optional CMS file mode.
(options) is options to be used when sending/receiving a file. Refer to Section 11.3 for a list of available CMS Send/Receive options.
Press ENTER.
For example,
will use the c:\SEND.EXE file to send the ASCII file a:\senddir\grades.dat to the EBCDIC host file student grade A1 via Session 3. The DOS prompt redisplays after the transfer begins.
To send a file from the PC to the MVS/CICS host, type the following at the DOS prompt:
Press ENTER.
To receive a file from the MVS/CICS host to the PC, type the following at the DOS prompt:
where:
a: is the optional drive specifier of where the SEND.EXE/RECEIVE.EXE resides (usually the directory where you installed the BARR/3270 program).
send is the file transfer Send program.
receive is the file transfer Receive program.
/N is the NOWAIT option. When specified, the file transfer is started and the DOS prompt displays. Allows you to execute another DOS function before the file transfer is complete. Transfer progress messages will not display.
d: is the drive specifier of the PC file. If not specified, the default drive is assumed.
path is the directory path of the PC file.
filename is the name of the PC file.
.ext is the extension of the PC file.
s: is the EHLLAPI short name of the 3270 session in which file transfer is to take place. Each 3270 display terminal session is assigned a short name starting at A for the first session. For example, if Session 1 is a display terminal session, Session 2 is a printer, and Session 3 is another display terminal session, the short names would be A for Session 1 and B for Session 3; printer sessions are not assigned short names. If this parameter is not specified, the transfer takes place in the first display terminal session.
fn is the name the file will have at the MVS/CICS host.
(options) is options to be used when sending/receiving a file. (See Section 11.4 for available MVS/CICS send/receive options.)
Press ENTER.
For example,
will use the c:\SEND.EXE program to send the ASCII file a:\senddir\grades.dat to the EBCDIC host data set grades via Session 3. The DOS prompt redisplays after the transfer begins.
After a file transfer is started, the progress of the file transfer is continuously displayed and updated on the 3270 session screen.
The progress is measured in terms of the number of data packets and bytes sent or received. An example of a progress message is shown below:
If the file transfer is started from the DOS session with the /N (NOWAIT) option, the progress message is not displayed.
If errors occur during file transfer, an error message is displayed near the bottom of the screen. These error messages are either received from the host or the BARR/3270 program. When an error message is displayed, you can exit the file transfer program by selecting the Escape option or attempt again to send or receive the file.
BARR 3270 HLLAPI/FILE TRANSFER NOT INSTALLED File Transfer Canceled
Explanation: BARR 3270 file transfer program has not been installed.
User Action: Select Yes for the HLLAPI and File Transfer Options on the 3270 Description screen during installation.
DOS File Open Error with DOS Error Code: xx File Transfer Canceled
where xx is:
01 Disk is Full
Explanation: Disk does not have enough space to receive the file.
User Action: Use another disk or free some disk space.
02 File not Found
Explanation: The file you are trying to send is not in the specified directory.
User Action: Verify the file name and path name; then retry.
04 Too many files are open
Explanation: Cannot open the file for the operation you want to perform.
User Action: Increase the FILES= value in config.sys to 20 or more.
06 Directory Full or Read-only file
Explanation: Tried to receive to a read-only file or your subdirectory is full.
User Action: Make sure you are not receiving to an existing file and that there is enough space remaining in your subdirectory.
File Transfer Communications Error: Session is not Active File Transfer Canceled
Explanation: The 3270 session from which file transfer is to take place is not connected to the host environment.
User Action: Logon and connect the session to the host environment.
Command Line Too Long for Input Space
Explanation: The file transfer command line entered is greater than the allowed length (256 characters).
User Action: Re-enter the command line.
Extended Log Mode Required
Explanation: An extended DLOGMODE has not been specified for the 3270 session from which file transfer is to take place.
User Action: Logon to the host with an extended DLOGMODE. For an example of an extended file transfer DLOGMODE, see Appendix D.
Session was not Configured or is Printer
Explanation: Session from which file transfer is to take place is configured as a 3270 printer. File transfer can only take place from a terminal session.
User Action: Use another 3270 session which is a terminal or reconfigure the session.
File Transfer Busy -- Retry Later
Explanation: Resources required for file transfer are currently not available.
User Action: Retry at a later time.
Control Break Issued: File Transfer Canceled
Explanation: File transfer has been aborted because you hit the CTRL-Break key.
User Action: None.
TRANS03 File Transfer Complete
Explanation: The file transfer operation has been successfully completed.
User Action: None
TRANS04 File Transfer Complete with Records Segmented
Explanation: The file transfer operation has completed. Any records greater than the logical record length of the file being appended to have been split into multiple records.
User Action: Retry with the correct value for LRECL.
TRANS06 Command Incomplete: File Transfer Canceled
Explanation: All required parameters for the file transfer command were not supplied.
User Action: Retry with the correct number of parameters.
TRANS13 Error Writing File to Host: File Transfer Canceled
Explanation: Host program has detected an error in the data file during the Send operation.
User Action: Retry. If problem persists, call your host personnel.
TRANS14 Error Reading File from Host: File Transfer Canceled
Explanation: Host program has detected an error in the data file during the Receive operation.
User Action: Retry. If problem persists, call your host personnel.
TRANS15 Required Host Storage Unavailable: File Transfer Canceled
Explanation: You need 30KB of main storage (not disk space) on the host for the file transfer in addition to the normal host storage requirement.
User Action: Contact host personnel.
TRANS16 Incorrect Request Code: File Transfer Canceled
Explanation: An invalid parameter was sent by the Send or Receive operation.
User Action: Contact host personnel.
TRANS17 Missing or incorrect TSO data set name: File Transfer Canceled
Explanation: The TSO data set name is missing or not a sequential or partitioned data set.
User Action: Enter the correct TSO data set name and retry.
TRANS17 Missing or incorrect CMS file name: File Transfer Canceled
Explanation: The CMS file name is missing or incorrectly specified.
User Action: Enter the correct file name and retry.
TRANS18 Incorrect option specified: File Transfer Canceled
Explanation: An invalid option was specified.
User Action: Retry, specifying with valid option.
TRANS19 Error reading or writing to host disk: File Transfer Canceled
Explanation: Not enough space available for data on the host.
User Action: Contact host personnel.
TRANS 28 Invalid option xxxxxxxx: File Transfer Canceled
Explanation: Option xxxxxxxx is either not recognized, is specified as a positional keyword, or has an associated value that is incorrect.
User Action: Retry with the correct option.
TRANS 29 Invalid option xxxxxxxx with RECEIVE: File Transfer Canceled
Explanation: Option xxxxxxxx cannot be used with RECEIVE but it can be used with SEND.
User Action: Retry after removing the option.
TRANS 30 Invalid option xxxxxxxx with APPEND: File Transfer Canceled
Explanation: Option xxxxxxxx is not valid with APPEND but can be used otherwise.
User Action: Retry after removing the option.
TRANS 31 Invalid option xxxxxxxx without SPACE: File Transfer Canceled
Explanation: Option xxxxxxxx can only be used if space is also specified.
User Action: Retry after removing the option.
TRANS 32 Invalid option xxxxxxxx with PDS: File Transfer Canceled
Explanation: Option xxxxxxxx is not valid for a partitioned dataset on the host.
User Action: Retry after removing the option.
TRANS33 Only one of TRACKS, CYLINDERS, AVBLOCK allowed: File Transfer Canceled
Explanation: Space can be specified in units of only one of these: TRACKS, CYLINDERS, or AVBLOCKS.
User Action: Retry after removing the unwanted option.
TRANS34 CMS file not found: File Transfer Canceled
Explanation: The specified CMS file does not exist.
User Action: Verify the CMS file name and specification and retry.
TRANS35 CMS disk is Read-Only: File Transfer Canceled
Explanation: The CMS FILEMODE specified for the SEND operation does not allow write access.
User Action: Use the correct FILEMODE specification and retry.
TRANS36 CMS disk is not accessed: File Transfer Canceled
Explanation: The CMS FILEMODE specified is not in the search order.
User Action: Retry with the correct FILEMODE.
TRANS37 CMS disk is full: File Transfer Canceled
Explanation: Either the CMS disk is full, the maximum number of files (3400) on the mini-disk has been reached, or the maximum number of data blocks per file (16060) has been reached.
User Action: Use another disk with enough space or remove unwanted files from the disk.
TRANS99 Host program error xx xxxxxxxx: File Transfer Canceled
Explanation: A host program error.
User Action: Contact host personnel.