Transfers files between a local system and a host computer connected by HCON.
fxfer -R [ -n SessionName ]
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
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
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:
This command requires:
The fxfer command communicates with an HCON session and may require a specific session profile. The session profile defines:
When the fxfer command is performing an automatic logon, the profile can also define:
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:
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:
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.
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:
|Host Type||File Name Format|
|VM/CMS||"FileName FileType FileMode"
Note: The " " (double quotation marks) are required for all VM/CMS file names to ensure proper file transfer.
(MemberName) ] [
Note: For Double-Byte Character Set (DBCS) support that includes either Japanese-English, Japanese Katakana, Korean, or Traditional Chinese, these considerations apply:
|-a||Appends the file designated by SourceFile to the file designated by DestFile, if the destination file
exists. This flag is ignored and the destination file is created if the
file designated by DestFile does not exist.
Note: The -a flag is not valid when uploading a file to a CICS/VS host. For VSE/ESA, the -a flag is valid only for uploading to CICS temporary storage (FILE=TS).
|-b||Retains the blanks at the end of each record when used with the -t, -T, -c, or -C flags. The -b flag is only supported in the DBCS environment.|
|-c||In a DBCS environment, the -c flag changes LF (line-feed) code of a file to CRLF (carriage return line-feed) code if the file transfer is an upload. For a downloading file transfer, the -c flag changes the CRLF code of a file to LF code.|
|-C||In a DBCS environment, the -C flag inhibits the sending of the EOF (end-of-file) code of a PC-DOS file if the file transfer is an upload. For a downloading file transfer, the -C flag appends an EOF code: x'1A at the end of a PC-DOS file.|
|-d||Downloads the file by transferring it from the host to the local
system. If neither this flag nor the -u flag is specified, the File Transfer
Direction characteristic in the session profile determines the direction of
Note: When downloading a translated file from a VSE/ESA host file transfer (FILE=HTF) the file is deleted from the host system unless you specify the -I "KEEP" flag.
|-e||Deletes the temporary storage queue at the completion of the file transfer. Use this flag only with the CICS host for downloading. The -e flag is only supported in the DBCS environment.|
|-f FileName||Places the file transfer process diagnostic output (or file transfer
status) in the file specified by the FileName variable.
If the -f flag is not specified for an asynchronous transfer, messages are placed in the $HOME/hconerrors file. If the -f flag is not specified for a synchronous transfer, messages are sent to standard output.
Messages due to errors in specifying file transfer parameters or file names, or failures in the file transfer process, are directed to standard output (if it is a local system screen) or to the $HOME/hconerrors file (if standard output is not a local system screen).
|-h||Displays a help screen for the fxfer command. This
screen summarizes each available command flag and command operation.
When this flag is specified all other flags are ignored and no files are
|-H HostType||Specifies the type of host. The HostType variable may
have any of these values:
|-I InputField||Specifies host file transfer options placed directly within the
IND$FILE command. Also allows comments within the
IND$FILE command placed after a ) (right
parentheses). The value specified by the InputField variable
is placed in quotation marks, as follows:
-I "FILE=TS) This is a comment"
Note: The -I field is not supported in a DBCS environment.
|-J||Allows data conversion between EBCDIC and ASCII, and normalization of
SI/SO characters. The translation depends on the direction of the
Note: The -J field is only supported in a DBCS environment.
|-k||Releases unused records in the dataset at the completion of file transfer. Use this flag only in the MVS/TSO environment. The -k flag is only supported in the DBCS environment.|
|-l||Specifies the host language in the DBCS environment. This option must be used with one of the translate flags (-t, -T, or -J ). If -t, -T, or -J is omitted, the -l flag is ignored. If the -l flag is not specified, the host language defined in the session profile is used. If the -l flag is specified, the host language used is the alternate language of the language defined in the session profile. For example, if the Language characteristic in the session profile is JPK (Japanese Katakana), the host language used for file transfer will be Japanese-English. The -l flag is only supported in the DBCS environment.|
|-M Volume||Specifies the volume serial number of the host disk for dataset allocation. Use this flag only in the MVS/TSO environment. The -M flag is only supported in the DBCS environment.|
|-n SessionName||Specifies the name of a previously defined session whose characteristics
control the file transfer. The session name is a single character in
the range of a to z. Capital letters are interpreted as lowercase
The -n SessionName flag is required except when the user is initiating the fxfer command from a subshell of an existing session. In this case, if the -n flag is not used the fxfer command defaults to the existing session.
|-N Unit||Specifies the unit type of the host disk for dataset allocation. Use this flag only in the MVS/TSO environment. The -N flag is only supported in the DBCS environment.|
|-q||Runs the file transfer asynchronously as a background process. If
any file transfers are not completed, the current transfer request is
queued. If the -q flag is not specified, the file transfer
operation is synchronous. If the -f flag is not specified, diagnostic output
and status is placed in the $HOME/hconerrors file.
Note: The system limits the number of bytes allowed in one Interprocess Communication (IPC) message queue. As a result, the maximum number of file transfers that can be queued at any one time is approximately 580.
|-r||Specifies replacement of an existing file on the host (upload) or an
existing file on the local system (download). On downloads, the
replacement is done only when the transfer is successful. This ensures
the existing file is not lost or destroyed if the transfer does not complete
for any reason.
Note: The host file transfer program usually defaults to replace for a file. If it does not, add -I "replace" to the fxfer command to specify replace.Attention: When replacing a file on the host, you must specify a logical record length ( -L flag) and a record format ( -F or -V flag) equal to the logical record length and record format of the existing file. If you do not do this, data corruption may result. This does not apply to VSE/ESA.
|-R||Restarts a previous file transfer (which was interrupted by the user or
an unsuccessful recovery attempt) using the information saved in one of the
RESTART files: the $HOME/x_fxfer.r file or the
$HOME/i_fxfer.r file. If the file transfer is not
invoked from the subshell of an existing session, the -n SessionName flag must be
included to specify the session to be used. If the -R flag
is specified in conjunction with any other file transfer flags, those flags
are ignored and the RESTART file transfer menu is displayed.
Note: With the -R flag, all other flags except the -n SessionName flag are ignored. The RESTART file transfer menu displays.
|-s||Specifies the SO/SI handling in the DBCS environment. The
-s flag must be used with one of the translate flags
(-t, -T, or -J). If -t,
-T, or -J is omitted, the -s flag is
ignored. When the -s flag is specified, the following
functions are performed for file transfer:
|-t||Performs ASCII-EBCDIC translation for a file. If downloading, the fxfer command translates EBCDIC to ASCII. If uploading, the fxfer command translates ASCII to EBCDIC. The language is specified by the Language characteristic in the session profile. The -t flag assumes the file is a text file. The new-line character is the line delimiter.|
|-T||Performs ASCII-EBCDIC translation for a disk operating system
file. The character sequence, CRLF, used as the line delimiter, and a
disk operating system EOF (end-of-file) character are inserted at the end of
the downloaded file. The language to be used for EBCDIC to ASCII
translation is specified by the Language characteristic in the session
profile. The -T flag is used to translate disk operating
Note: If neither the -T, -t, nor the -J flag is specified, the file transfer assumes no translation and transfers the information in binary form.
|-u||Uploads the file by transferring the file from the local system to the host. If neither this flag nor the -d flag is specified, the File Transfer Direction characteristic in the session profile determines the direction of the transfer.|
|-v||Periodically writes the current status of the file transfer to the screen or to the status file specified by the -f flag. The status includes the number of bytes transferred and the elapsed time since the file transfer process began transferring data.|
|-x HostLogin||Uses the login ID specified by the HostLogin variable to log
in to the host. The user is prompted to enter the password.
The HostLogin string consists of the host login ID, the AUTOLOG node ID, and other optional AUTOLOG values. The string cannot contain any blanks and must contain the AUTOLOG node ID. Format the AUTOLOG string as:
UserID,AutologNodeID[,Trace,Time . . .]
If you omit certain parameters from the host login string, they are retrieved from the profile, if defined there. For example, if the you set the AUTOLOG Node ID, AUTOLOG Trace, and AUTOLOG Time parameters in the profile, only the host login ID must be entered at the prompt.
The file transfer process logs in to the host and establishes an emulation session using the session profile specified with the -n flag. Once the process is successfully logged in, the file transfer begins.
The File Transfer Wait Period parameter in the session profile determines how long the login session is maintained. Using this parameter, the host login session is maintained for subsequent file transfers. The need to log in again is eliminated.
|-X CodeSet||Specifies an alternate code set to use for ASCII-EBCDIC
translation. If the -X flag is omitted, the code set
specified by the system locale is used. The following code sets are
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
|-B BlockSize||Specifies the block size of the host data set. The -B flag can only be used in the MVS/TSO environment and only for sequential data sets. The BlockSize variable cannot exceed the capacity of a single track. The -B flag is ignored if the file is being appended. A block size value of 0 causes an error.|
|-F||Specifies fixed-length records. This is the default if neither the
-V, -t, -T,
-c, nor -C flag is specified. The
-F flag is ignored if the file is being appended.
On a CICS or VSE host, one of the translate flags (-t or -T) or one of the CRLF flags (-c or -C) must be specified along with the -F flag, since the CICS and VSE host file transfer programs do not support fixed record lengths. The combination of the -F flag and the translate flag causes the transfer program to pad the records with blanks to the end of the logical record length. The default is 80.
Note: Use the -F flag when downloading from a VSE host to prevent the deletion of trailing blanks from the translated file.
|-L LoglRecLength||Specifies the logical record length in bytes of the host file. For
new files, the default is 80. For variable-length records,
LoglRecLength is the maximum size of the record. The
-L flag is ignored if the file is being appended. A
LoglRecLength value of 0 causes an error.
The CICS and VSE host file transfer programs do not support logical record lengths. For transfers to or from a CICS or VSE host the -L flag must be accompanied by the -F flag. The combination of the -F and -L flags causes the transfer program to pad the records with blanks to the end of the logical record length. The default is 80.
Note: The -L flag is required if a record length is greater than the default record length of 80.
|-S NumberUnits [ ,IncreaseUnits | ,IncreaseUnits,UnitType | ,,UnitType ]|
|Specifies the amount of space to be allocated for a new sequential data
set on TSO. For large MVS files, the maximum block size permissible on
the host is used to ensure that the whole disk track is filled. The
-S flag can be used only with MVS/TSO hosts.
The following variables can be used with the -S flag. If used, they must be specified in the order given and separated by commas. If a variable preceding another variable is omitted, a comma must be included as a placeholder. A space is required between the -S flag and the NumberUnits variable. However, no spaces can appear in the variable string.
|-U||Specifies records of undefined length. The -U flag can only be used in the MVS/TSO environment. The -U flag is ignored if the file is being appended.|
|-V||Specifies records of variable length. This is the default if the
-F flag is not specified, and either the
-t, -T, -c, or -C flag is specified. The
-V flag is ignored if the file is being appended.
The -V flag is not supported by the CICS or VSE host file transfer programs, since variable record lengths are the default.
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
fxfer -n a -t samplefile "test file a"
fxfer -urv -L 132 -V -H CMS file2 "test file b"
fxfer -utFH CICS -I ")This is a comment" /etc/motd "motdfile"
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 (" ").
fxfer -urtvH TSO 'newfile' "sys4.parmlib.samplefile"
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).
fxfer -n a -d -r -H TSO spfuser.test samplefile1
fxfer -n a -dat -q -f status.out -x laura,vm1,trace "test file a" mydir/samplefile
fxfer -n a -daq -f status.out "test file b" mydir/samplefile
- 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.
- Attempting to start a synchronous file transfer when there is an asynchronous transfer in the queue causes an error.
- 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.
-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.
fxfer -R -n a
The -n flag instructs the fxfer command to use session a to perform the restarted transfer.
|/usr/bin/fxfer||Contains the fxfer command.|
|/usr/bin/dfxfer||Contains the dfxfer process.|
|$HOME/i_fxfer.r||Contains RESTART information for automatic login queues. Temporary file created by the fxfer command.|
|$HOME/x_fxfer.r||Contains RESTART information for manual login queues. Temporary file created by the fxfer command.|
|$HOME/hconerrors||Contains HCON diagnostic output and file transfer status. Temporary file created by any HCON command.|
|/usr/lib/libfxfer.a||Contains the library for programmatic file transfers.|
For information on installing the Web-based System Manager, see Chapter 2: Installation and System Requirements in AIX 5L Version 5.1 Web-based System Manager Administration Guide.