fxfer Command

Purpose

Transfers files between a local system and a host computer connected by HCON.

Syntax

To Restart an Interrupted File Transfer

fxfer -R [ -n SessionName ]

To Download a File from the Host

fxfer [ -n SessionName ] [ -a | -r ] [ -d ] [ -c | -C ] [ -J ] [ -f FileName ] [ -F ] [ -H HostType ][ -I InputField ] [ -q ] [ -t [ [ -l ] [ -s ] [ -b ] ] | -T [ [ -l ] [ -s ] [ -b ] ] ]

[ -v ] [ -x HostLogin ] [ -e ] [ -X CodeSet ] SourceFile DestFile

To Upload a File to the Host

fxfer [ -n SessionName ] [ -a | -r ] [ -u ] [ -c | -C] [ -J] [ -f FileName ] [ -H HostType ] [ -q ] [ -t [ [ -l ] [ -s] ] | -T [ [ -l ] [ -s] ] ] [ -l ] [ -s] [ -v ] [ -x HostLogin ] [ -X CodeSet ] [ -F | -V | -U ] [ -B BlockSize ] [ -L LoglRecLength ] [ -I InputField ] [ -S NumberUnits [ ,IncreaseUnits | ,IncreaseUnits,UnitType | ,,UnitType ] ] [ -M Volume] [ -N Unit] [ -k] SourceFile DestFile

To Display the Help Screen

fxfer -h

Description

The fxfer command transfers files between local system and mainframe hosts connected by the Host Connection Program (HCON). Files may transfer from a local system to the host (uploading) or from the host to a local system (downloading). The fxfer command transfers the file named by the SourceFile parameter to the file named by the DestFile parameter. The transfer occurs over an HCON session requiring a specific session profile or an existing session.

The host operating system may be VM/CMS, MVS/TSO, CICS/VS (for CICS/MVS or CICS/VSE), VSE/ESA, or VSE/SP, with the corresponding version of the 3270 File Transfer Program (IND$FILE or its equivalent) installed. The version of the host file transfer program is determined by the File Transfer Program value in the session profile. The fxfer command supports transfer of either text or binary data. Files will transfer to or from the host with or without ASCII or EBCDIC translation.

Security mechanisms prevent unauthorized access, the destruction of existing files, or the loss of data. If a non-HCON user issues the fxfer command, the command fails. If the fxfer command is interrupted before completion, the state of the transfer is saved in a RESTART file.

If the fxfer command is issued with the -h flag, it displays a help screen. If the command is issued with the -R flag, it searches the $HOME directory for a restart file. If a restart file exists, the restart menu displays, enabling a restart of the file transfer. If the -h and -R flags are not specified, the command attempts to perform the specified file transfer.

The fxfer command information includes:

• Flags
• Flags for Host File Characteristics
• Examples
• Files

This command requires:

• One or more adapters used to connect to a mainframe host.
• One of the following mainframe operating systems be installed on the host:
  • VM/SP CMS
  • VM/XA CMS
  • MVS/SP TSO/E
  • MVS/XA TSO/E
  • CICS/VS (for CICS/MVS or CICS/VSE)
  • VSE/ESA
• The mainframe Host-Supported File Transfer Program (IND$FILE or equivalent) be installed on the mainframe.

Session Profiles for Using the fxfer Command

The fxfer command communicates with an HCON session and may require a specific session profile. The session profile defines:

• Communication path to the host
• Host type
• Default file transfer direction (down or up)
• Recovery time
• File transfer wait period

When the fxfer command is performing an automatic logon, the profile can also define:

• Host logon ID
• AUTOLOG node ID
• Whether the AUTOLOG trace is on
• AUTOLOG time out value

The user usually specifies a session profile when invoking the fxfer command. The exception occurs when the command is run from a subshell of an existing session. In this case, if the user does not specify a session profile, the fxfer command uses the existing session. If the appropriate session is not running, the fxfer command attempts to invoke a new session.

The fxfer command searches for an HCON session as follows:

• When issued without the -n SessionName flag:
  • If the fxfer command is issued from a subshell of an existing session, the command uses the session associated with the subshell (defined by the $SNAME environment variable).
  • If not issued from a subshell of an emulator session, the fxfer command issues an error message and terminates.
• When issued with the -n SessionName flag, the file transfer performs over the specified session. If the specified session does not exist, the command searches for a session profile for that session. If the specified session profile cannot be found, the fxfer command issues an error message and terminates. If the specified profile exists, the fxfer command attempts an automatic logon to the host using either the AUTOLOG values defined in the session profile, the values defined with the -x flag, or by prompting the user for the necessary logon information.

Interrupted and Restarted File Transfers

The fxfer command can be interrupted by the operator or an unrecoverable communication error, before completion. If interrupted, the command saves the state of the transfer in a RESTART file. The transfer can be restarted from the beginning without loss of data.

If you run a new file transfer after an interrupted transfer, the fxfer command signals that a RESTART file has been created and displays these choices:

• Restart the interrupted file transfer.
• Save the RESTART file and exit the file transfer program.
• Delete the RESTART file and exit the file transfer program.
• Delete the RESTART file and continue the present transfer.

The fxfer command with the -R flag also restarts an interrupted file transfer.

If the host communication is lost or disconnected during a file transfer started with an automatic logon, the file transfer attempts to recover by reconnecting and logging back on to the host. The recovery time for this attempt is determined by the File Transfer Recovery Time value in the session profile. Once the host connection is re-established, the file transfer resumes from the start. If communication cannot be re-established, the file transfer program generates a RESTART file.

When an explicit file transfer loses communication with the host, the user must restart the emulator session and log back in to the host before attempting to restart the file transfer.

Source and Destination Files

The fxfer command SourceFile and DestFile parameters are required. The SourceFile parameter specifies the source file for a file transfer. The DestFile parameter specifies the destination file for a file transfer. The local system file names are in the normal format. The host file names conform to the host naming convention, which is one of the following formats:

Flags

-I   "FILE=TS)   This   is   a   comment"

UserID,AutologNodeID[,Trace,Time   .   .   .]

Flags for Host File Characteristics

The following flags specify host file characteristics and can be used only to upload files (with the exception of the -F flag, which can be used when downloading from a VSE host):

-S   NumberUnits,IncreaseUnits,UnitType

-S   NumberUnits,IncreaseUnits

-S   NumberUnits

-S   NumberUnits,,UnitType

Examples

The following examples assume the session profile for session a is:

Session   type         DFT
Communication   device         3270c0
Language         English   (U.S.A.)
Host   type         CMS
File   transfer   direction         up
File   transfer   wait   period         10
File   transfer   recovery   time         30

where:

• The host type is VM/CMS.
• The connection is made using the DFT 3270 connection device.
• The file transfer default direction is upload (to use session profile a for downloading files, the user must specify the -d flag with the fxfer command).
• The file transfer process stays logged in for 10 minutes.
• If a transfer is interrupted, the process attempts recovery for 30 minutes before saving information in the RESTART file for later transfer.
• The translation language is U.S.A. ASCII-EBCDIC.
  1. To upload the samplefile file (in the current directory) to the host and translate it to EBCDIC using the U.S.A. translation table, enter:

     fxfer   -n   a   -t   samplefile   "test   file   a"

     • -n instructs the fxfer command to use session a to transfer the file.
     • -t instructs the command to translate using the new-line character.
     The translated data is placed in the test file a on the host. Because the host file name contains spaces, quotation marks around the file name are required.
  2. To upload the file2 file to the VM/CMS host test file b, enter:

     fxfer   -urv   -L   132   -V   -H   CMS   file2   "test   file   b"

     • -u instructs the fxfer command to upload the file.
     • -H indicates that the host type is a VM/CMS host. If the destination file exists, it is replaced (since the -r flag is specified) by the transferred file.
     • -v causes fxfer to display the number of bytes transferred and elapsed time. The status or diagnostic output is displayed on the terminal.
     • If the host file does not exist, the host file maximum logical record length is set to 132 bytes ( -L flag).
     • The host file record format is variable ( -V flag). No translation is performed.
  3. To upload, from a subshell of emulator session a, the local system /etc/motd file to the CICS motdfile host file with translation and padding of blanks, enter:

     fxfer   -utFH   CICS   -I   ")This   is   a   comment"   /etc/motd   "motdfile"

     • -u instructs the command to upload the file.
     • -t causes translation from ASCII to EBCDIC.
     • -F causes the transfer program to pad the uploaded file with blanks to column 80 (the default record length). To change the default column, use the -L flag with a different record length (column).
     • -H specifies the host as type CICS.
     • -I specifies that the InputField value be added to the IND$FILE command.
     In this example, "This is a comment" is a host comment field.

     To upload or download files with the fxfer command, to or from a TSO environment other than your current environment, you must have authorization for the other environment. You must completely qualify the file (or dataset) within single quotes ('), then double quotes (" ").

  4. For example, to upload the file newfile to a TSO environment where the complete qualified name is sys4.parmlib.samplefile, enter:

     fxfer   -urtvH   TSO   'newfile'   "sys4.parmlib.samplefile"

     • -u instructs the command to upload the file.
     • If the sys4.parmlib.samplefile file exists, it is replaced ( -r flag) with the translated contents of the newfile file ( -t flag).
     • -v instructs the fxfer command to write the file transfer status to the local screen every few seconds.
     • -H instructs the fxfer command that the host is a MVS/TSO host.
       Note: This example assumes that the fxfer command is issued from a subshell of an established session (use the e789 command to establish a session).
  5. To download the file spfuser.test from the MVS/TSO host to the local system, enter:

     fxfer   -n   a   -d   -r   -H   TSO   spfuser.test   samplefile1

     • -n instructs the fxfer command to use session a to transfer the file. If session a has not already been established, the command attempts an automatic login. Since no host login ID is specified, the fxfer command checks the session profile for a login ID. If one is not specified there, the user is prompted for the login ID and password.
     • -d overrides the default file transfer direction of upload.
     • If the samplefile1 file already exists, it is replaced ( -r flag) with the downloaded file from the host.
     • -H instructs the fxfer command that the host is an MVS/TSO host instead of VM/CMS (the default from the session profile).
     The transferred file is placed in the samplefile1 file on the local system. The file transfer is performed synchronously.
  6. To download the VM/CMS host test file a and append it to the local system mydir/samplefile file, using session profile a and automatic login, enter:

     fxfer   -n   a   -dat   -q   -f   status.out
     -x   laura,vm1,trace   "test   file   a"   mydir/samplefile

     • -n instructs the fxfer command to use session profile a to transfer the file.
     • -x provides the host login ID. The fxfer command first checks to see if session is established on the local system. If so, the command transfers the file over the existing session. If session a is not established, the fxfer command performs an automatic login using the host logon ID laura and the AUTOLOG script vm1, and traces the login activity. The user is prompted for the password. The command transfers the file.
     • -dat instruct the fxfer command to download the file ( -d flag), translate the data from EBCDIC to ASCII ( -t flag) using the U.S.A. translation table (defined in the session profile), and append ( -a flag) the translated file to the mydir/samplefile file on the local system. If the mydir/samplefile file does not already exist, the fxfer command ignores the -a flag and creates the file.
     • The status or diagnostic output is placed in the status.out file in the current local directory ( -f flag).
     • -q instructs the fxfer command to transfer the file asynchronously.
     When the user enters the password, the prompt is returned and the file transfer is performed in the background.

     To queue another file transfer to be performed by the same file transfer process, enter:

     fxfer   -n   a   -daq   -f   status.out   "test   file   b"   
     mydir/samplefile

     • -n instructs the fxfer command to use session a to transfer the file. Since session a has been established by the previous command, the fxfer command does not need to log in to the host again.
     • -d instructs the command to download a file from the host.
     • -a instructs the command to append the test file b host file to the mydir/samplefile file on the local system.
     • -q instructs the fxfer command to transfer the file asynchronously.
     The fxfer command continues to send status information to the status.out file on the local system ( -f flag).
     Notes:

     1. If the text for the fxfer command extends beyond the limit of the screen, the text wraps automatically to the next line. Pressing the Enter key to wrap the text causes an error.
     2. Attempting to start a synchronous file transfer when there is an asynchronous transfer in the queue causes an error.
     3. The user will not be prompted for a login ID or a password as long as the session remains running and the dfxfer process remains logged in to the host. The amount of time the process remains logged in is determined by the File Transfer Wait Period in the session profile.
  7. To restart an interrupted file transfer from an emulator subshell, enter:

     fxfer   -R

     -R instructs the fxfer command to use the information saved in one of the RESTART files to execute a file transfer. The RESTART file is the $HOME/x_fxfer.r explicit restart file or $HOME/i_fxfer.r implicit restart file. If the -R flag is specified in conjunction with other file transfer flags, the other flags are ignored. The RESTART file transfer menu is displayed. Using this menu, instruct the fxfer command to transfer the interrupted file.
  8. To restart the file transfer from the command line instead of from an emulator subshell, enter:

     fxfer   -R   -n   a

     The -n flag instructs the fxfer command to use session a to perform the restarted transfer.

Files