BARR/3270 manual

11. File Transfer

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.


11.1 Introduction

Foreground and Background 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.

Types of File Transfer Supported

Performing file transfer between the PC and an IBM host requires that the IND$FILE program be installed at the host.

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.

Other Features

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.

Invoking the File Transfer Program from a 3270 Session

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.

File Name Conventions

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.

11.2 TSO File Transfer

TSO Send Command and Options

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 Password specified for the data set if it is password-protected.

APPEND Append the file being sent to an existing TSO file. This option overrides any values specified for LRECL, BLKSIZE, or RECFM.

ASCII Convert an ASCII PC file to EBCDIC during transfer to the host. To be readable, a file at the host should be in EBCDIC.

CRLF Delete the Carriage Return/Line Feed characters from the PC file during transfer to the host.

LRECL(n) Specify the Logical Record Length of the host file, where n is the length. If LRECL is not specified, a default length of 80 is assumed. If the APPEND option is also specified, LRECL is ignored.

BLKSIZE(n) Specify the number of bytes per data block for the host data set. BLKSIZE is ignored if you are appending to or replacing a data set. Default BLKSIZE is 1 record per block.

RECFM(F) Specifies that the host file contains fixed-length records. The length is the default or that specified by LRECL. The records are padded with blanks if they are shorter than the specified length. For a new file, this is the default if neither RECFM nor CRLF is specified.

RECFM(V) Specifies that the host file contains variable-length records. This is the default when CRLF is specified.

RECFM(U) Specifies that the host file contains records of undetermined length. This option should be used when transferring transparent files.

SPACE(q[,i]) Specifies the amount of space to be allocated for a new data set. q is the initial quantity, and i is the expansion increment size. i has three options:

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.

TSO Receive Command and Options

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 Append the received file to the end of an existing PC file.

ASCII Convert the EBCDIC file at the host to ASCII during transfer. Necessary for a file to be readable on the PC.

CRLF Specifies that trailing blanks in the host file record be deleted and a Carriage Return/Line Feed be inserted at the end of each record.

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.

11.3 VM/CMS File Transfer

VM/CMS Send Command and Options

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 Append the file being sent to an existing CMS file. This option overrides any values specified for LRECL and RECFM.

ASCII Convert an ASCII PC file to EBCDIC during transfer to the host. To be readable, a file at the host should be in EBCDIC.

CRLF Delete the Carriage Return/Line Feed characters from the PC file during transfer to the host.

LRECL n Specify the Logical Record Length of the host file. n is the numeric length value. If LRECL is not specified, default length of 80 is assumed for new files. If the APPEND option is also specified, LRECL is ignored.

RECFM F Specifies that the host will contain fixed-length records. The length is the default or that specified by LRECL. The records are padded with blanks if they are shorter than the specified length. For a new file, this is the default if RECFM is not specified and CRLF is not specified.

RECFM V Specifies that the host file will contain variable length records. This is the default when CRLF is specified.

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.

VM/CMS Receive Command and Options

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 Append the received file to the end of an existing PC file.

ASCII Convert the EBCDIC file at the host to ASCII during transfer. Necessary for a file to be readable on the PC.

CRLF Specifies that trailing blanks in the host file record be deleted and a Carriage Return/Line Feed be inserted at the end of each PC file record.

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.

11.4 CICS File Transfer

CICS Send Command and Options

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 Convert an ASCII PC file to EBCDIC during transfer to the host. To be readable, a file at the host should be in EBCDIC.

BINARY File contains binary data which should not be altered before writing to the host file.

CRLF Delete the Carriage Return/Line Feed characters from the PC file during transfer to the host.

NOCRLF Do not delete Carriage Return/Line Feed characters before writing the file at the host.

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.

CICS Receive Command and Options

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 Convert the EBCDIC file at the host to ASCII during transfer. Necessary for a file to be readable on the PC.

BINARY File contains binary data which should not be altered before storing to the PC file NOCRLF Do not insert Carriage Return/Line Feed characters at the end of each record before transferring to the PC.

CRLF Insert Carriage Return/Line Feed characters at the end of each record before transferring to the PC.

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.

11.5 File Transfer from DOS Session

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.

TSO Send/Receive Command and Options

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.

VM/CMS Send/Receive Command and Options

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.

CICS Send/Receive Command and Options

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.

11.6 File Transfer Progress

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.

11.7 BARR/3270 Error Messages

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.

Host Messages

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.