Client FTP3
Available Languages
Table Of Contents
Connections to the FTP Servers
Throughput and CPU Utilization
Invoking Client FTP3 through TSO
Understanding the Configuration Data Sets
Related References on the FTP.DATA File
Changing the High-Level Qualifier
Client FTP3 Command Conventions
Client FTP3
This chapter describes Client FTP3, the File Transfer Protocol (FTP) that allows file transfers among unlike hosts in diverse internetworking environments. It contains these sections:
Provides a brief overview of the Cisco IOS for S/390 File Transfer Protocol implementation.
Describes the FTP3 data flow and includes an illustration showing how Client FTP3 works.
Describes how to use Client FTP3 as both a TSO command and as a regular batch program.
•
General Client FTP3 Operation
Describes the general operation of the Client FTP3 program.
Includes a table listing all of the Client FTP3 commands and provides a brief description of each.
Commands are:
Introducing Client FTP3
Like Client FTP and Client FTP2, Client FTP3 is a three-party model FTP client. Two control connections are established and maintained by the client. Like Client FTP2, Client FTP3 connects automatically to the local Cisco IOS for S/390 FTP server and signs on the user.
Despite these basic similarities, Client FTP3 differs from both Client FTP and Client FTP2 in several significant ways. The differences are described in this chapter.
PL/I Runtime Libraries
Client FTP3 is written in C, and so does not require PL/I runtime libraries, as do the other clients. It does require the SAS/C runtime libraries.
Connections to the FTP Servers
Client FTP3 is a true client application. Both Client FTP and Client FTP2 communicate with a client agent through a VTAM LU0 connection in the Cisco IOS for S/390 server address space. Client FTP3, on the other hand, uses the Cisco IOS for S/390 C/Sockets library to establish direct socket connections with both the local Cisco IOS for S/390 FTP server (local server) and the remote FTP server. This eliminates the need for VTAM LU resources, and improves response time.
Throughput and CPU Utilization
Although primarily a three-party client, Client FTP3 performs some operations in two-party mode to take advantage of the high throughput and low CPU utilization of the Cisco IOS for S/390 FTP server. The result is improved response to the user and quick response time of a direct connection to the remote server.
For file-transfer operations, such as the client commands GET, PUT, and APPEND, Client FTP3 works in three-party mode. For directory commands, such as the client commands LS and DIR, as well as the implied directory commands in the MGET, MPUT, and MDELETE commands, Client FTP3 operates in two-party mode. Unlike Client FTP2, Client FTP3 does not need to be run under the TMP to support LS and DIR in batch jobs.
Client FTP3 Data Transfer
Client FTP3 appears to the user as a two-party model by suppressing almost all local server replies, simplifying the client responses considerably. Also, Client FTP3 operates in blocked mode. When a data transfer is initiated, the terminal remains blocked until the transfer completes.
By comparison, Client FTP2 returns a command prompt and allows the user to enter commands as soon as a data transfer is initiated between the local and remote servers. This allows you to enter the STAT command to check on progress, or the ABORT command to abort the transfer, but it also means that user running interactively must press ENTER to be notified of the end of the transfer. Client FTP3, on the other hand, does not allow terminal input during a data transfer. For long-running transfers, a statistics message is written to the terminal every 10 seconds. You can abort the transfer by pressing the attention key on the terminal keyboard. When the transfer ends, Client FTP3 displays the reply, and returns to the command prompt.
Client FTP3
shows the relationship between the Client FTP3 program and the two Server FTP programs in the three-party model.
Figure 3-1 Client FTP3 Program in the Three-Party Model
Note that two Data Connections are shown. The data connection between the Remote Server FTP and the Local Server FTP is used for the GET, PUT, and APPEND client commands (RETR, STOR, APPE and STOU server operations). The data connection between the Client FTP3 and the Remote Server FTP is used for the client LS and DIR commands and the implied LS in the MGET, MPUT, and MDELETE commands (LIST and NLST server operations).
Invoking Client FTP3
The Client FTP3 program runs as a TSO command and can be called as a regular batch program with MVS JCL.
Invoking Client FTP3 through TSO
In a TSO environment, Client FTP3 can be accessed as a TSO command or it can be called as a program with the TSO CALL command. Because Client FTP3 does not use full-screen facilities, it can be used from any type of terminal supported by TSO, including 3270 systems, 3767 systems, and asynchronous ASCII terminals supported by NTO or NPSI.
Note
FTP3 TSO Command
Some keywords used in the FTP3 command can be used to override values specified in the TCPIP.DATA data set. Read Understanding the Configuration Data Sets for more information.
Invoke Client FTP3 by entering the FTP3 TSO command in this format.
FTP3 remote_host [port_number] [options]
Syntax Description
FTP3
Invokes the Client FTP3 program.
remote_host
Name of the remote host. Client FTP3 will automatically connect to this host at initialization. This parameter is required. If you do not supply this parameter, you will be prompted for it.
port_number
Port number of the FTP server on the remote host.
Default: 21
BLOCK | NOBLOCK
Specifies whether the ftp client will permit user input while a file transfer is in progress.
Default: BLOCK
DEBUG
Toggle used to activate or deactivate the debugging option. Use the DEBUG or TRACE options interchangeably. You may include either DBUG or TRACE on the command line, but not both; the second option cancels the first.
EXIT | EXIT=nn
Specifies that the client is to terminate in case of an error if the exit_if_error flag is true. Exit=nn provides a return code for error conditions.
LOCALHOST host_name
Specifies the host name of the local FTP server host.
Override note: This option will override the HOSTNAME statement in the TCPIP.DATA data set.
SSID subsystem_id
Specifies the subsystem id for the Cisco IOS for S/390 API.
Default: ACSS
TCP tcpip
Specifies the job name of the Cisco IOS for S/390 sockets API address space. If no job name is specified, FTP3 uses the subsystem ID specified in the SSID parameter of the FTP statement. If SSID does not indicate a subsystem ID, ACSS is used.
Override note: This option will override the TCPIPJOBNAME statement in the TCPIP.DATA data set.
TIMEOUT nn
Sets the following timeout parameters
MyopenTime
DconnTime
CconnTime
InactTime
DataCtTime
See the discussion Understanding the Configuration Data Sets for the meaning of these timers.
TRACE
Toggle used to activate or deactivate the debugging option. Use the DEBUG or TRACE options interchangeably. You may include either DBUG or TRACE on the command line, but not both; the second option cancels the first.
TRANSLATE data_set_name
Specifies the name of a nonstandard translate table. If this parameter is not supplied, FTP will use the translate table in hlq.STANDARD.TCPXLBIN (read TCPIP.DATA for an explanation of the hlq). If present, this parameter will be used to construct a data set name in the form user_id.data_set_name.TCPXLBIN. If this data set does not exist, FTP will attempt to allocate hlq.data_set_name.TCPXLBIN.
VERBOSE
Specifies VERBOSE mode. All commands to and replies from the local host will be echoed to the user.
Note A left parenthesis "(" separates the remote_host and port_number from the other options.
Example ftp unix.company.com (translate standard
TSO CALL Command
Use the TSO CALL command in a TSO environment to call and execute the FTP3 program out of a specific library. This is especially useful at sites that run multiple releases of the product or have test and production versions of the product at different maintenance levels.
CALL `T01TCP.FTPLOAD(FTP3)' [`remote_host port options']
Syntax Description
'T01TCP.FTPLOAD(FTP3)
Library from which FTP3 will be called .
`options'
Any number of FTP3 invocation options can be included in the CALL command. Read Invoking Client FTP3 through TSO for a complete list.
Usage Guidelines
The data set name, T01TCP.FTPLOAD, might need to be replaced by the appropriate data set name at your installation. Check with your Cisco IOS for S/390 site administrator.
When options are specified in the command statement, they must be enclosed in single quotes.
When invoked by the CALL command, Client FTP3 runs as a program and not as a TSO command.
You can use the NETRC file with the TSO FTP3 call. Read The NETRC File for more information.
'Batch Invocation
The Client FTP3 program can be run in batch as either a program like any other, or as a TSO command by running it under a batch Terminal Monitor Program (TMP).
You can specify a NETRC file in batch mode. Specify a NETRC DD file with the name of your NETRC file.
Batch Program
You can invoke Client FTP3 in batch in a manner similar to any other batch utility program. A sample JCL file is contained in the SAMP data set as T00PFBJB
//<jobname> JOB job_stmt_parms//FTPSTEP EXEC PGM=FTP3,REGION=1024K,// PARM='remote_host port options'//STEPLIB DD DSN=T01TCP.FTPLOAD,DISP=SHR//SYSTCPD DD DISP=SHR,DSN=userid.TCPIP.DATA//SYSFTPD DD DISP=SHR,DSN=userid.FTP.DATA//SYSTERM DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSPRINT DD SYSOUT=*//OUTPUT DD SYSOUT=*//INPUT DD *unixuser passstatquit//Optionally, you may include a NETRC file, as shown here:
//NETRC DD DISP=SHR,DSN=userid.NETRCBatch TMP
An example of this JCL is located in the SAMP data set as member T00PFTMP.
//<jobname> JOB job_stmt_parms//*//* RUN FTP3 UNDER BATCH TSO//*//FTP3 EXEC PGM=IKJEFT01,REGION=4096K,//STEPLIB DD DISP=SHR,DSN=T01TCP.FTPLOAD// DD DISP=SHR,DSN=T01TCP.LOAD//SYSTSPRT DD SYSOUT=*//OUTPUT DD SYSOUT=*,DCB=BLKSIZE=133//SYSTCPD DD DISP=SHR,DSN=userid.TCPIP.DATA//SYSFTPD DD DISP=SHR,DSN=userid.FTP.DATA//SYSTERM DD SYSOUT=*//SYSTSIN DD *FTP3 remote_host port options//INPUT DD *unixuser passstatquit//Understanding the Configuration Data Sets
If you have previously installed the IBM TCP/IP for MVS, the configuration files described here might already exist. Cisco IOS for S/390 provides support for these data sets to allow former IBM customers to run their applications using Cisco IOS for S/390.
Client FTP3 automatically searches for and dynamically allocates the configuration data sets when you start FTP3. You can define user-specific environment settings for FTP3 by setting parameters in these configuration data sets:
•
TCPIP.DATA defines the Cisco IOS for S/390 system environment on the local host. You can set your own values by creating a userid.TCPIP.DATA data set.
•
FTP.DATA defines the local SITE parameters that are sent to the local host in the form of SITE commands. You can set your own values by creating a userid.FTP.DATA data set.
The high-level qualifier is specified in T00PFUM. See Changing the High-Level Qualifier for instructions on changing the default HLQ.
Samples of these files are located in the SAMP data set. The member names are T00FTPDS (FTP.DATA) and T00TCPDS (TCPIP.DATA).
Caution
These configuration data sets must be preconfigured before you execute FTP3.
If you want more details about how the configuration data sets are allocated, see Dynamic Data Set Allocation.
Dynamic Data Set Allocation
Client FTP3 searches first for the TCPIP.DATA file. If the TCPIP.DATA file is found and contains a DATASETPREFIX statement, the prefix will be used to search for the FTP.DATA file. You can override the search sequence if you want to use high-level qualifiers other than the defaults for the configuration data sets. If the data sets are not found, the search continues as described for each file. illustrates the allocation sequence.
Figure 3-2 Dynamic Data Set Allocation
TCPIP.DATA Allocation
FTP3 follows the search path described below to locate the TCPIP.DATA file.
1
2
The user ID is the TSO user ID of the TSO user issuing the FTP3 command or the user ID of the FTP3 batch job if the command is issued from a batch job.
3
SYS1.TCPPARMS will be used during initialization; it may have been created previously if the IBM product was installed.
4
5
6
•
or
•
7
FTP.DATA Allocation
After the TCPIP.DATA search is complete, FTP3 starts searching for the FTP.DATA file. Once the FTP.DATA file is located, the search is complete.
1
The data set name specified in this statement will be used by FTP3.
2
The user ID prefix in userid.FTP.DATA is the TSO user ID of the TSO user issuing the FTP3 command or the user ID of the FTP3 batch job.
3
SYS1.TCPPARMS will be used during initialization; it may have been created previously if the IBM product was installed.
4
5
•
•
•
•
•
The default for each of these parameters is 300 seconds.
Normal settings for local SITE parameters are determined by the Cisco IOS for S/390 administrator in the Server FTP configuration statements in APPCFGxx.
Related References on the FTP.DATA File
For additional detailed information about the FTP.DATA file, refer to SC31-7134-01 IBM TCP/IP V3R1 for MVS: Customization and Administration Guide.
Changing the High-Level Qualifier
Client FTP3 uses both implicit and explicit data set allocation. You can use the pre-assigned data set names, hlq. TCPIP.DATA and hlq.FTP.DATA, or you can override the pre-assigned data set names with your JCL.
Client FTP3 is distributed with the high-level qualifier TCPIP. The name is defined in the T00PFUM module. You may change the default high-level qualifier by doing one of the following:
•
•
TCPIP.DATA
The data set TCPIP.DATA defines TCP/IP parameters. An example of this file is located in the SAMP data set member T00TCPDS.
FTP3 does not support multiple host definitions in a single TCPIP.DATA file. If you have a TCPIP.DATA file which contains more than one host definition, you need to modify your file and create a separate TCPIP.DATA file for each host.
describes the parameters are supported in the TCPIP.DATA data set.
Table 3-1
TCPIP.DATA Parameters
FTP.DATA
The FTP.DATA data set defines local SITE parameters that are sent to the local host in the form of SITE commands. You can set your own values by creating a userid.FTP.DATA data set. An example of this file is contained in the SAMP data set member T00FTPDS.
The parameters listed in are set in the FTP.DATA file. Many of these parameters correspond to SITE commands available in Cisco IOS for S/390 Server FTP. You can use the LOCSITE command to change any of these parameters during the FTP session.
General Client FTP3 Operation
These steps outline the general procedure for using Client FTP3 program:
•
•
•
If your user ID and password fail the logon because one or both were entered incorrectly, you must enter the LOG command to sign on to the remote host.
•
•
Path Name
A path name is a string that identifies a file to a file system. A path name must contain a device and/or directory name and a file name. The FTP specification does not specify a standard path name convention. Each user must follow the file naming conventions of the file systems involved in the transfer. Consult the System Administrators at the host sites involved in the transfer for file naming conventions.
Many of the Client FTP3 commands take one or more path name arguments.
For information about the syntax for MVS path names supported by the Cisco IOS for S/390 Server FTP, read Data Set Names in .
Client FTP3 Command Conventions
provides general notes that apply to the Client FTP3 commands:
Table 3-3
Client FTP3 Command Conventions
The NETRC File
The Client FTP3 program uses information in the NETRC file for automatic login to the remote host. The NETRC filename is assumed to be userid.NETRC. To use a different naming convention for this file, you must pre-allocate it with an NETRC DD statement.
You can specify any number of MACHINE/LOGIN/PASSWORD sets to define remote hosts. If you define a machine with no login, password, and/or account, you are prompted for this information when needed. When a user connects to a remote host, if a remote MACHINE/LOGIN/PASSWORD set exists for the host, this set logs the user on to the remote host.
If you have not created a NETRC file, you are prompted to supply a user ID and password for the remote host whenever you open a connection to a remote host.
This is the format of the NETRC file; edit this file to specify user IDs, passwords, and accounts, or to create a macro.
MACHINE remhost LOGIN userid (for remhost) PASSWORD password (for remhost)[ACCOUNT account (for remhost)If an installation does not require a password and/or an account, these can be omitted. Before using the Client FTP3 commands, you must log on to a remote host with an OPEN command.
Caution
You should use your local access control facility to protect NETRC files since these files can contain valid user ID password combinations for remote hosts. Only the TSO user ID using the NETRC file should be able to read their own NETRC file.
The NETRC file can also be used in batch jobs by using the NETRC invocation along with a NETRC DD pointing to your NETRC data set.
Note
Client FTP3 Commands
gives a brief description of each command and its function; detailed descriptions of each command follow the table.
? Command
Use the ? command to display information about using the Client FTP3 program. This command is very similar to the HELP command.
? [ command_name ]
Syntax Description
Default
If the ? command is specified with no arguments, it displays a list of Client FTP3 commands.
Usage Guidelines
The ? command can be used either with or without arguments.
If command_name is specified as an argument to the ? command, a line of information displays similar to the information in the table in Client FTP3 Commands. The line shows the command syntax and a short description of the command function.
Example
? DIRDIR pathr pathl - Directory list of remote hostACCOUNT
The ACCOUNT command displays information that is needed by the remote host. Refer to documentation for the remote FTP server for information that it needs.
ACCOUNT [account_info]
Syntax Description
APPEND
The APPEND command requests that a file from the local host be appended to a file at the remote host.
APPEND [ local_path ] [ remote_path ]
Syntax Description
local_path
Name of the file to be retrieved from the local host.
remote_path
Remote file to which the local file is to be appended.
Default
If either file name is omitted, you are prompted for the file name.
Usage Guidelines
The syntax for each path depends on the associated Server FTP.
Data set attributes are maintained for the transferred data set.
If the data set already exists, and the LRECL is less than that of the transferred data set, the transmitted data set will be truncated.
ASCII
The ASCII command sets the data type to ASCII for the data transfer. This command is equivalent to a TYPE command with the ASCII (A) parameter specified.
ASCII
BINARY
The BINARY command sets the data type to binary for the data transfer.This command is equivalent to a type command with the image (I) parameter specified.
BINARY
This command has no arguments or keywords.
CD
The CD command requests that the remote Server FTP change the current directory to a new directory.
CD [ path_name ]
Syntax Description
path_name
Indicates to the remote Server FTP the name of the directory to be made the current directory.
Default
If you omit path_name, the Client FTP3 program prompts you for the desired value.
Usage Guidelines
The syntax for path_name depends on the associated Server FTP.
If you want to specify a path name that is not a subdirectory of the current directory, enclose the path name in single quotes. Do not leave a space after the first quote; FTP3 will ignore the quotation mark.
A UNIX Server FTP in session with the Client FTP3 program is using /u/user1/work as the current directory. If a CD junk command is issued by the Client FTP3 to that UNIX Server FTP, the resulting current directory is /u/user1/work/junk. The same result is achieved by specifying CD /u/user1/work/junk.
Example
The following example shows a change of directory to a remote UNIX system:
CD /u/lpn/d.ddn250 CWD command successful.The following example shows a change to a directory on a remote system running Cisco IOS for S/390:
CD ACCES250 "'USER1.ACCES.'" is current prefixThe following example shows a change to a specific directory:
CD `TEST.DIR'250 "'TEST.DIR'" is current prefixCDUP
The CDUP command directs the remote Server FTP to change the current directory to the parent directory of the old current directory. The CDUP command is most useful when the Server FTP manipulates a hierarchical file system such as UNIX.
CDUP
A UNIX Server FTP in session with the Client FTP3 program has /u/user1/work as the current directory. If a CDUP command is issued by the Client FTP3 to that UNIX Server FTP, the resulting current directory is the parent of the old current directory (/u/user1).
Example
The following example shows a change to the parent directory of the old current directory on a remote UNIX system:
CDUP250 CWD command successful.CLOSE
The CLOSE command logs you out and terminates the connection between you and the remote Server FTP.
CLOSE
Example
CLOSE221 Goodbye.DEBUG
The DEBUG command displays all commands and responses going to and from the Server FTPs and the user. This command is equivalent to specifying the TRACE option on the Client FTP3 command line.
DEBUG
Usage Guidelines
The DEBUG command toggles the previous state. If DEBUG or TRACE was turned on previously, then a subsequent DEBUG or TRACE command will turn it off.
Example
DEBUGDELETE
The DELETE command directs the remote Server FTP to delete the specified file.
DELETE [ path_name ]
Syntax Description
Default
If you omit path_name, you are prompted to supply one.
Usage Guidelines
The syntax for path_name depends on the associated Server FTP.
Example
DELETE oldfile250 DELE command successful.DELIMIT
The DELIMIT command displays the character delimiter used between the file name and the file type.
DELIMIT
The delimiter cannot be changed by this command.
DIR
The DIR command requests that the remote Server FTP provide a directory list for the specified path.
DIR [ remote_path ] [local_path ] [ ( DISK ]
Syntax Description
Example
The following example lists the contents of a directory on an MVS system.
dir /export/home/user1/mvs150 ASCII data connection for /bin/ls (138.42.224.15,4126) (0 bytes).-rw------- 1 user1 dvlp 2730 Oct 22 08:36 channel-rw------- 1 user1 dvlp 2901 Sep 1 09:17 comten-rw------- 1 user1 dvlp 1276 Oct 21 14:43 dump-rw------- 1 user1 dvlp 729 Nov 12 05:24 ibmlink-rw------- 1 user1 dvlp 751 Nov 12 07:41 ibmlink2226 ASCII Transfer complete.EBCDIC
The EBCDIC command sets the data type to EBCDIC for data transfer. The command is equivalent to the type command with the EBCDIC (E) parameter specified.
EBCDIC
Example
EBCDICEBCD ENTEREDstatGET
The GET command requests that a file from the remote host be copied to a file on the local host by the appropriate Server FTPs. The file to be retrieved is always at the remote host, and the file to be copied into is always at the local host.
GET [ remote_path ] [ local_path ] [ ( REPLACE ]
Syntax Description
Default
If you omit either file name, you are prompted for one.
Usage Guidelines
The syntax for each path depends on the associated Server FTP.
Note
HELP
The HELP command requests help information from the local Server FTP.
HELP [ALL | ? | command | [SERVER [remote_command]]]
Syntax Description
Default
If no command is specified, a list of supported commands is returned.
LCD
The LCD command changes the current working directory on the local host.
LCD [local_path_name]
Syntax Description
LMKDIR
The LMKDIR command creates a directory (or PDS) on the local host.
LMKDIR [local_path_name]
Syntax Description
LOCSITE
The LOCSITE command allows you to specify SITE information to be used by the local host.
LOCSITE [ options ]
Syntax Description
options
Local site information. For a list of the SITE commands, read the SITE section in .
LOCSTAT
The LOCSTAT command displays local FTP status information.
LOCSTAT
LPWD
The LPWD command displays the name of the current working directory on the local host.
LPWD
LS
The LS command requests a remote Server FTP to provide a list of file names for the specified path.
LS [ remote_path ] [ local_path ] [ ( DISK ]
Syntax Description
Default
If a local path is not specified, the list of files appears on your screen.
Usage Guidelines
If the path specifies a directory or other group of files, the remote Server FTP transfers a list of files.
The syntax for each path depends on the associated FTP server.
If a local path is specified, the list of files is written to the specified file.
Example
The following example shows of the LS command with parameters:
ls /export/home/user1 unix.dir.temp150 ASCII data connection for /bin/ls (138.42.224.15,4134) (0 bytes).226 ASCII Transfer complete.350 bytes received in 1.54 seconds (227 bytes/s)This is an example of the LS command without parameters:
ls150 ASCII data connection for /bin/ls (138.42.224.15,4135) (0 bytes).-Transfer completechannelcomtendumpfileatempfile226 ASCII Transfer complete.MDELETE
The MDELETE command allows you to delete multiple files on the remote host.
MDELETE [remote_path_name] | [mask]
Syntax Description
remote_path_name
Name of the file to be deleted on the remote host.
mask
Mask to use to describe files. This mask complies with mask conventions on the remote host.
Example
MDELETE userid.myfiles.*MDELETE file199?MGET
The MGET command copies multiple files from the remote host to the local host. You cannot specify a different name for the files that are retrieved. Filenames created on the local host will be identical to those on the remote host.
MGET [remote_path_name] [( REPLACE]
Syntax Description
remote_path_name
Name of the files to be copied from the remote host.
REPLACE
Specifies that the data set on the local host be overwritten.
Note
Example
ftp> lcd mget.pds"'GAM2.MGET.PDS'" partitioned data set is current directoryftp> cd tstdir---> CWD tstdir250 CWD command successful.ftp> mget TST*---> PORT 138,42,160,55,17,34200 PORT command successful.---> NLST TST*150 ASCII data connection for /bin/ls (138.42.160.55,4386) (0 bytes).226 ASCII Transfer complete.GET TST1---> PORT 138,42,160,55,17,35200 PORT command successful.550 Catalog structure invalid or user lacks authority to catalogGET TST2---> PORT 138,42,160,55,17,36200 PORT command successful.---> RETR TST2150 ASCII data connection for TST2 (138.42.160.55,4388) (29 bytes).226 ASCII Transfer complete.GET TST3---> PORT 138,42,160,55,17,37200 PORT command successful.---> RETR TST3150 ASCII data connection for TST3 (138.42.160.55,4389) (37 bytes).226 ASCII Transfer complete.ftp>MKDIR
The MKDIR (make directory) command directs a remote Server FTP to create the specified directory.
MKDIR [ path_name ]
Syntax Description
Default
If you omit path_name, you are prompted for it.
Usage Guidelines
If the path name is relative, the specified subdirectory is created in the current working directory.
If the path name is absolute, the specified directory is created.
The syntax for path depends on the associated Server FTP.
Example
A UNIX Server FTP in session with the Client FTP3 program has /u/user1/work as the current directory. If a mkdir junk command is issued by the Client FTP3 to that UNIX Server FTP, the subdirectory junk is created in the current directory (/u/user1/work/junk). The same result is achieved by specifying MKDIR /u/user1/work/junk.
MKDIR /u/lpn/d.new257 MKD command successful.MODE
The MODE command sets one of three transmission modes:
MODE S | B | C
•
Block mode formats the data and allows for restart procedures.
•
Stream mode passes the data with little or no processing. It interacts with the structure attribute to determine the type of processing. Stream mode is the default if no MODE command was used.
•
Compressed mode transmits the data blocks with no repetitive characters or blanks.
For the purpose of standardized transfer, the sending host translates its internal end-of-line or end-of-record representation into the representation required by the transfer mode and file structure, and the receiving host performs the inverse translation to its internal representation. Since these transformations make extra work for some systems, identical systems transferring non-record structured text files might use binary representation and stream mode to simplify transfer.
Syntax Description
Usage Guidelines
One of the three codes (either S, B, or C) is required as an argument on the MODE command.
Each of the possible transmission modes is discussed in the following sections. For a detailed description of the effect of various transmission modes, read the "Transmission Modes" section in RFC 959, File Transfer Protocol.
Not all Server FTPs support all transmission modes; review the Server FTP documentation if you have questions concerning transmission mode support.
Block Mode
Block mode is indicated with the character B. In block mode, the file is transmitted as a series of data blocks preceded by one or more header bytes. Record structures are allowed in this mode, and any representation type can be used. Restart markers are embedded in the data stream.
Stream Mode
Stream mode is set with the character S. This is the default if no MODE command has been used. In stream mode, the data is transmitted as a stream of bytes. There are no restrictions on the representation type used, and record structures are allowed. In a record structured file, End of Record (EOR) and End of File (EOF) are each indicated by a two-byte control code included with the data sent over the data connection. If the structure is a file structure, the EOF is indicated by the sending host closing the data connection, and all bytes sent over the data connection are data bytes.
Compressed Mode
Compressed mode is set with the character C. In compressed mode, data blocks are transmitted with one or more header bytes. Logical record boundaries of the data set are preserved with compressed mode. Data is transmitted with no repetitive characters or blanks.
MPUT
The MPUT command copies multiple files from the local host to the remote host.
You cannot specify a different name for the files that are transferred. Filenames created on the remote host will be identical to those on the local host.
MPUT [local_path_name] | [mask]
Syntax Description
local_path_name
File name on the local host.
mask
Mask to use to describe files. This mask complies with mask conventions on the remote host.
Example
MPUT userid.myfiles.*MPUT file199?NOOP
The NOOP command is used to test the response of the remote host.
NOOP
OPEN
The OPEN command is used to open a connection to the FTP server on the remote host. This command can be issued while you are in the FTP environment.
OPEN remote_host [ port_number ]
Syntax Description
Note
PASS
The PASS command is used to send a password to the remote host.
PASS password
Syntax Description
Usage Guidelines
The PASS command must follow the USER command.
Read USER for more information.
PUT
The PUT command requests that the local Server FTP copy a file to the remote system. The file to be copied is always at the local Server and the file destination is always at the remote Server.
PUT [local_pat] [remote_path]
Syntax Description
Usage Guidelines
The syntax for each path depends on the associated Server FTP. If you omit either path, you are prompted for the file name.
PWD
The PWD command directs a remote Server FTP to return the path name of the current working directory.
PWD
Syntax Description
This command has no arguments or keywords.
Example
PWD257 "/u/lpn" is current directory.QUIT
The QUIT command terminates the Client FTP3 program.
QUIT
Example
QUIT221 Goodbye.QUOTE
The QUOTE command sends an uninterpreted, unaltered character string to the remote Server FTP over the control connection. This mechanism sends FTP commands to the Server that the Client FTP3 program might not be able to send.
QUOTE [ text ]
Syntax Description
text
Sent to the Server over the control connection exactly as you enter it; if the text is omitted, you are prompted to enter it
Example
QUOTE pasv227 Entering Passive Mode (26,131,0,17,4,216).RENAME
The RENAME command directs a remote Server FTP to rename a file.
RENAME [ old_path_name ] [ new_path_name ]
Syntax Description
Default
If you omit either argument, you are prompted to enter it.
Usage Guidelines
The syntax of the path names depends on the associated Server FTP.
Example
RENAME titlecol coltitle350 File exists, ready for destination name250 RNTO command successful.RESTART
The RESTART command restarts the last checkpointed file transfer.
REST
The data set USERID.FTP.CHKPOINT on the local host holds the valid checkpoint for the last checkpointed file transfer. Any parameters that may have changed for the last transfer, such as transfer mode and type, must be re-set before restarting the transfer.
When file transfer is in blocked or compressed mode (mode=b/c), and Client FTP3 processes a GET or PUT command, it allocates a fixed-block data set named userid.FTP.CHKPOINT. It uses this file to save the GET or PUT command and checkpoint record returned from the FTP server. If the userid.FTP.CHKPOINT file already exists, Client FTP3 will rewrite the checkpoint data set from the beginning of the data set.
If the GET or PUT command is successful, the checkpoint data set is deleted upon completion of the command processing. If the GET or PUT command fails or is interrupted, the userid.FTP.CHKPOINT data set will be kept in the system for the RESTART command to use to restart the file transfer.
If the RESTART command is executed successfully, Client FTP3 will delete the checkpoint data set. If the RESTART command fails or is interrupted, the checkpoint data set is kept for future use.
Users are responsible for deleting the checkpoint data set once it is determined the data set is no longer needed.
For more information, read about the RESTART interval option for the SITE command in the SITE section in .
RMDIR
The RMDIR (remove directory) command directs a remote Server FTP to remove the specified directory.
RMDIR [ path_name ]
Syntax Description
Default
If you omit path_name, you are prompted for it.
Usage Guidelines
If the path name is relative, the specified subdirectory is removed from the current working directory.
If the path name is absolute, the specified directory is removed.
The syntax of path_name depends on the associated Server FTP.
Note
Example
As an example, if a UNIX Server FTP in session with the Client FTP3 program has /u/user1/work as the current directory, and a RMDIR junk command is issued by Client FTP3 to that UNIX Server FTP, the junk subdirectory of the current directory is removed. The same result is achieved by specifying RMDIR /u/user1/work/junk.
RMDIR /u/lpn/d.samp250 RMD command successful.SENDSITE
The SENDSITE command is used to automatically send the SITE commands when sending a file to a remote host. This commands is useful only with other IBM-based FTP servers.
SENDSITE
The SENDSITE command is turned on when you start your FTP session. You can toggle it on and off by issuing the SENDSITE command. To determine the current state of the SENDSITE command, issue the LOCSTAT command.
SITE
The SITE (site parameters) command provides the local Server FTP with specific information it requires. This information is essential to file transfers involving that Server FTP, but is not sufficiently universal to have been included specifically in the FTP. Typically, you use a HELP SITE Client FTP3 command to find the SITE requirements for a specific local Server FTP. Otherwise, review the Server FTP documentation for the SITE requirements. SITE command parameters are described in the SITE section in .
SITE text
The text argument is required and is passed through unchanged to the specified server.
STATUS
The STATUS command requests status information from the remote system.
STATUS [ path_name ]
Syntax Description
STRUCT
The STRUCT (file structure) command provides information on file structure to the remote Server FTP.
STRUCT F | R
Syntax Description
Usage Guidelines
Record structure is set by R. This is for files made up of sequential records.
Example
STRUCT FSUNIQUE
Use the SUNIQUE (STORE UNIQUE) command to store transferred files by unique file names on a remote machine. SUNIQUE is a toggle command (meaning it is either off or on). When used, the target server automatically ensures that files received in FTP transfer are stored under a unique name.
SUNIQUE
Usage Guidelines
The target remote FTP server must support the STOU (store unique) command.
If SUNIQUE is not used, FTP3 will issue the standard STOR command. If file names are not unique, files in the target directory could be overwritten.
Default for SUNIQUE is OFF.
SYSTEM
The SYSTEM command displays the name of the operating system on the remote host.
SYSTEM
Example
SYSTEM215 MVS is the operating system of this server.TRACE
Use the TRACE command to activate or deactivate the tracing option. With the tracing option active, you can rerun failing commands to discover the reason for the failure.
TRACE
Usage Guidelines
The TRACE command toggles the previous state. If TRACE or DEBUG was turned on previously, then a subsequent TRACE or DEBUG command will turn it off.
Example
DEBUGTSO
The TSO command requests the client FTP3 program to execute a TSO command for you.
TSO command
Syntax Description
TYPE
The TYPE command tells a Server FTP the data type to use.
TYPE I | L byte_size | { A | E [ N | T | C ] }
Syntax Description
Default
ASCII is the default file type.
For both ASCII and EBCDIC file types, vertical format control N is the default.
Usage Guidelines
One of the four arguments (I, L byte_size, A, or E) is required.
If local type (L) is set, the integer byte size argument must also be set.
If ASCII (A) or EBCDIC (E) type is set, one of the three vertical format control arguments, N, T, or C, can also be set.
USER
The USER command identifies your userid to the remote FTP server.
USER user_id [password] [old_password] [/ new_password]
Syntax Description
Usage Guidelines
You can issue the USER command to change your userid at any time while you are in the FTP environment.
Your password will not be printed if you allow the client FTP3 to prompt you for it.
For more information about using the NETRC file, read The NETRC File.
Feedback