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:

This command requires:

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:

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:

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:

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:

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.
MVS/TSO "[']DataSetName [ (MemberName) ] [ /Password ][']"

where:

DataSetName
Indicates either a physical sequential data set or a partitioned data set.
(MemberName)
Indicates the name of one of the members in the directory of an existing partitioned data set. The () (parentheses) enclosing the MemberName are required.
/Password
Required if password protection is specified for the MVS/TSO data set. The / (slash) preceding the Password is required.
Notes:
  1. The " " (double quotation marks) are required for all MVS/TSO file names to ensure proper file transfer.
  2. When specifying a complete path name for MVS/TSO file names, use ' (single quotation marks) within the " (double quotation marks). Do not put spaces between the double and single quotation marks or between the quotation marks and the file names.
CICS/VS "FileName"
VSE/ESA "FileName FileType"
Notes:
  1. The " " (double quotation marks) are required for all CICS/VS, VSE/ESA, and VSE/SP file names to ensure proper file transfer.
  2. CICS/VS, VSE/ESA, and VSE/SP file name conventions allow for a file name up to 8 characters long.
  3. In a DBCS environment, HCON does not support a VSE host.

Flags

Note: For Double-Byte Character Set (DBCS) support that includes either Japanese-English, Japanese Katakana, Korean, or Traditional Chinese, these considerations apply:
  • If the DBCS -l or -s flag is specified, one of the translate flags (-t, -T, or -J) must also be specified or the DBCS flags are ignored.
  • The -M, -N, and -k flags are used only with MVS/TSO hosts.
  • The -e flag is valid only with the CICS® program for downloading.
  • The -b flag is valid only for downloading.
Item Description
-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 the transfer.
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 transferred.
Notes:
  1. If the -h flag is used, all other flags are ignored. No files transfer.
  2. If the fxfer command is not initiated from a subshell of an existing HCON session, either the -h flag or the -n flag is required.
-H HostType Specifies the type of host. The HostType variable may have any of these values:
CMS
VM/SP CMS or VM/XA CMS
TSO
MVS/SP TSO or MVS/XA TSO
CICS
CICS/VS (The CICS host type includes CICS/VSE, CICS/MVS, CICS/ESA, and CICS/MVS/ESA.)
VSE
VSE/ESA (Not supported in a DBCS environment.)

If the -H flag is omitted, the value specified by the Host Type characteristic in the session profile is used. The user must specify the correct host operating system.

Notes:
  1. If you specified the CICS or VSE value and the system returns an error, retry the command with the alternate value. The CICS and VSE IND$FILE programs are functionally interchangeable; however, there is a 6-byte header-size discrepancy that makes the versions operationally incompatible. The destination host may be using the alternate version of the program.
  2. To transfer files to an MVS/TSO host, you may need to leave session manager mode before initiating the file transfer.
-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 transfer:
Upload
Translates 1-byte characters of a file to EBCDIC code. For DBCS countries, the extended code is translated to the appropriate DBCS code. SO/SI characters are inserted into DBCS fields containing DBCS characters. If the file contains control codes 0x1E or 0x1F, they are replaced with SO and SI characters respectively.
Download
Translates EBCDIC code to 1-byte characters of a file; For DBCD, the DBCS code is translated to extended code. Deletes SO/SI characters from DBCS fields.
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 letters.

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.

Notes:
  1. The specified session must have been previously defined using the Web-based System Manager, the smit hcon fast path command or the mkhcons command.
  2. If the fxfer command is not initiated from a subshell of an existing HCON session, either the -h flag or the -n flag is required.
-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.

If the -r flag is specified and the file does not exist, it is created during the file transfer. If the -r flag is not specified and the destination file exists, an error message is produced.

For uploading, the -r flag must be specified when using a version of the host file transfer program below PTF UR20455 for MVS/TSO or PTF UR90118 for VM/CMS. For VSE and CICS the -r flag is ignored.

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:
Upload
SO/SI characters are not inserted in DBCS fields.
Download
SO/SI characters are replaced with control characters (0x1E/0x1F) in DBCS fields.

The -s flag is only supported in the DBCS environment.

-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.

When the -t flag is used in a DBCS environment with other DBCS supported flags, the behavior of the -t flag changes as follows:

Upload
Translates JISCII (Japan) or ASCII (Korean, Traditional Chinese) to EBCDIC. Inserts SO/SI characters in DBCS fields.
Download
Translates EBCDIC to JISCII (Japan) or ASCII (Korean, Traditional Chinese). Deletes SO/SI characters from DBCS fields.
-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 system files.
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 the -x flag is not specified, the information for the HostLogin string is taken from the session profile as follows:

  • If the host login ID is set in the session profile, you are prompted for the password. The remaining parameters are retrieved from the profile.
  • If the host login ID is not set in the profile, you are prompted for both the host login string and the password.
  • Your response to a prompt always overrides a profile parameter. For example, if the AUTOLOG time is set in the profile but you enter a different value at the prompt, the value entered at the prompt is used.

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 supported:
Default
Uses current system ASCII code page.
IBM-932
Uses IBM® code page 932 for translation in a DBCS environment.
ISO8859-1
Uses ISO 8859-1 Latin alphabet number 1 code page.
ISO8859-7
Uses ISO 8859-7 Greek alphabet.
ISO8859-9
Uses ISO 8859-9 Turkish alphabet.
IBM-eucJP
Uses IBM Extended UNIX Code for translation in the Japanese Language environment.
IBM-eucKR
Uses IBM Extended UNIX Code for translation in Korean Language environment.
IBM-eucTW
UsesIBM Extended UNIX Code for translation in Traditional Chinese Language environment.

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):

Item Description
-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.

Because of MVS™ overhead, the actual number of bytes stored in the variable length records on an MVS/TSO host is four bytes less than the value specified by the LoglRecLength variable.

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.

NumberUnits
Specifies the number of units of space to be added initially. A value of 0 or a negative value cannot be specified for the NumberUnits variable.
IncreaseUnits
Specifies the number of units of space to be added to the data set each time the previously allocated space is filled (optional).
UnitType
Defines the unit of space and may be T for tracks, C for cylinders, or a number specifying the average block size (in bytes) of the records written to the data set. If the UnitType variable is not specified, the default is the value specified by the -B flag. If the -B BlockSize flag is not specified, the default value is 80.

Following are the possible combinations of variables used with the -S flag:

-S   NumberUnits,IncreaseUnits,UnitType
-S   NumberUnits,IncreaseUnits
-S   NumberUnits
-S   NumberUnits,,UnitType
-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.

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:

Files

Item Description
/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.