|
|
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:
| ACCOUNT | APPEND | ASCII | BINARY | |
| CD | CDUP | CLOSE | DEBUG | DELETE |
| DELIMIT | DIR | EBCDIC | GET | ../../../../../../lib/help.htm |
| LCD | LMKDIR | LOCSITE | LOCSTAT | LPWD |
| LS | MDELETE | MGET | MKDIR | MODE |
| MPUT | NOOP | OPEN | PASS | PUT |
| PWD | QUIT | QUOTE | RENAME | RESTART |
| RMDIR | SENDSITE | SITE | STATUS | STRUCT |
| SYSTEM | TRACE | TSO | TYPE | USER |
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.
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.
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.
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 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 Program in the Three-Party Model shows the relationship between the Client FTP3 program and the two Server FTP programs 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).
The Client FTP3 program runs as a TSO command and can be called as a regular batch program with MVS JCL.
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.
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]| 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 |
| '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. |
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.
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.
//<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 * unix user pass stat quit //
Optionally, you may include a NETRC file, as shown here:
//NETRC DD DISP=SHR,DSN=userid.NETRC
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 * unix user pass stat quit //
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:
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.
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. Figure 3-2 illustrates the allocation sequence.
FTP3 follows the search path described below to locate the TCPIP.DATA file.
1 . FTP3 looks first for a SYSTCPD DD statement, which is used to define an override for the high-level qualifier.
2 . If no SYSTCPD DD statement is located, FTP3 searches for a userid.TCPIP.DATA file.
3 . If no userid.TCPIP.DATA file is located, FTP3 searches for a TCPDATA member in the SYS1.TCPPARMS partitioned data set (PDS).
4 . If the TCPDATA member is not located, FTP3 looks for the hlq.TCPIP.DATA data set.
5 . Once the TCPIP.DATA file is located, FTP3 uses the high-level qualifier defined by the DATASETPREFIX statement in the TCPIP.DATA file.
6 . Overriding: If no TCPIP.DATA file is located, no default values are imposed, with the exception that FTP3 will connect to either
7 . If the FTP3 command includes neither the SSID nor TCP option, FTP3 connects to the SSID default subsystem ID, ACSS.
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 . It searches first for a SYSFTPD DD statement.
2 . If no SYSFTPD DD statement is found, FTP3 searches for a userid.FTP.DATA file.
3 . If no userid.FTP.DATA file is located, FTP3 searches for an FTPDATA member in the SYS1.TCPPARMS PDS.
4 . If a userid.FTP.DATA is not found, FTP3 looks for hlq.FTP.DATA.
5 . If no FTP.DATA file is located, or if configuration parameters are missing from FTP.DATA, FTP3 sets no defaults except for these timeout parameters:
Normal settings for local SITE parameters are determined by the Cisco IOS for S/390 administrator in the Server FTP configuration statements in APPCFGxx.
For additional detailed information about the FTP.DATA file, refer to SC31-7134-01 IBM TCP/IP V3R1 for MVS: Customization and Administration Guide.
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:
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.
Table 3-1 describes the parameters are supported in the TCPIP.DATA data set.
| Parameter | Description |
| DATASETPREFIX dsn_prefix | dsn_prefix identifies the high-level qualifier to be used to determine the hlq.FTP.DATA data set name and the translate table data set name.
Default: None |
| HOSTNAME host_name | host_name specifies the host name of the local FTP server.
Default: None |
| DOMAINORIGIN origin | The origin is to be appended to the host_name to form the fully-qualified host name.
Default: None |
| MESSAGECASE MIXED | UPPER | Specifies whether messages from the FTP client will be displayed in mixed case or translated to upper case.
Default: MIXED |
| TCPIPJOBNAME tcpip_proc | Identifies the started procedure name or job name of the Cisco IOS for S/390 stack. This is resolved to a subsystem ID by the client.
Default: None |
The parameters listed in Table 3-2 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.
| Parameter | Description |
| AUTOMOUNT TRUE | FALSE | If TRUE, the client will send SITE AUTOMount to local host; if FALSE, the client will send SITE NOAUTOmount.
Default: None. |
| AUTORECALL TRUE | FALSE | If TRUE, the client will send SITE AUTORecall to local host; if FALSE, the client will send SITE NOAUTOrecall.
Default: None. |
| BLKSIZE blk_size
BLOCKSIZE blk_size | The client will send a SITE BLKSize=blk_size command to the local host.
Default: None. |
| CHKPTint checkpoint_interval | The client will send a SITE CHKPTint=checkpoint_interval command to the local host.
Default: None. |
| CCONNTIME close_connection_time | Set internal timer. Defines the timeout value (in seconds) for closing a control connection.
Default: 300 seconds. |
| DATACLASS SMS_data_class | Sends a SITE DATAClass=SMS_data_class command to the local host.
Default: None. |
| DATACTTIME data_connection_timeout_time | Sets internal timer; sends SITE DIDle=data_connection_timeout_time to the local host. Defines the timeout value when sending or receiving data.
Default: 300 seconds. |
| DCBDSN DCB_dataset_name | Sends a SITE DCBdsn=DCB_dataset_name command to the local host.
Default: None. |
| DCONNTIME data_connection_close_time | Sets internal timer; sends a SITE DClose=data_connection_close_time command to the local host. Defines the timeout value when closing a data connection.
Default: 300 seconds. |
| DIRECTORY directory_blocks | Sends a SITE Directory=directory_blocks command to the local host.
Default: None. |
| DIRECTORYMODE TRUE | FALSE | If TRUE, the client will send SITE DIRECTORYmode to local host; if FALSE, the client will send SITE DATASETmode.
Default: None. |
| FILETYPE SEQ | JES | Sends a SITE FILEType=SEQ | JES command to the local host.
Default: None. |
| INACTTIME control_connection_inactive_time | Sets internal timer. Defines the timeout for a reply on the control connection. Default: 300 seconds. |
| LRECL logical_record_length | Sends a SITE LRecl=logical_record_length command to the local host.
Default: None. |
| MGMTCLASS SMS_management_class | Sends a SITE MGmtclass=SMS_management_class command to the local host.
Default: None. |
| MIGRATEVOL migrate_volser | Default: None. |
| MYOPENTIME data_connection_open_time | Sets internal timer; sends a SITE DOpen=data_connection_open_time command to the local host. Defines the timeout when opening a new control or data connection.
Default: 300 seconds |
| NCP number_of_channel_programs | Sends a SITE NCP=number_of_channel_programs command to the local host.
Default: None |
| PRIMARY primary_space | Sends a SITE PRImary=primary_space command to the local host.
Default: None. |
| RDW TRUE | FALSE | If TRUE, the client will send SITE RDW to local host; if FALSE, the client will send SITE NORDW.
Default: None. |
| RECFM record_format | Sends a SITE RECfm=record_format command to the local host.
Default: None. |
| RETPD retention_period | Sends a SITE RETpd=retention_period command to the local host.
Default: None. |
| SECONDARY secondary_space | Sends a SITE SECONDary=secondary_space command to the local host.
Default: None. |
| SPACETYPE BLOCKS | CYLINDERS | TRACKS | Sends a SITE BLocks/CYlinders/TRacks command to the local host.
Default: None. |
| STORCLASS SMS_storage_class | Send SITE STORclass=SMS_storage_class command to the local host.
Default: 300 seconds. |
| UNITNAME unit_name | Sends a SITE Unit=unit_name command to the local host.
Default: None. |
| VOLUME volume_serial | Sends a SITE VOLume=volume_serial command to the local host.
Default: None. |
| WRAPRECORD TRUE | FALSE | If TRUE, the client will send SITE WRAPrecord to local host; if FALSE, the client will send SITE NOWRAPrecord.
Default: None. |
These steps outline the general procedure for using Client FTP3 program:
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 Server FTP.
Table 3-3 provides general notes that apply to the Client FTP3 commands:
| Convention | Description |
|---|---|
| Program Prompt | To indicate successful completion of most commands, the Client FTP3 program gives a new prompt. |
| Completion of Data Transfer | Final completion of the data transfer command is indicated with a message. |
| Testing the Control Connections | You can use the VERBOSE command to see the specific FTP commands and responses sent and received over the control connections as a result of Client FTP3 commands. If you want more information about this test, refer to RFC 959. |
| Case Sensitivity | The Client FTP3 commands are not case sensitive. |
| Abbreviations in Commands | Abbreviations are permitted if they are not ambiguous. For example, you can type AB for ABORT but you cannot type only A because several commands begin with this letter. |
| Brackets in Commands | In the examples, parameters enclosed by brackets are optional for the command line. In many cases, if the optional parameters are omitted from the command line, you are prompted for them. |
| Syntax Conventions | Command words are shown in uppercase and parameters are shown in lowercase. When the actual values for a parameter are given (such as LSOUTPUT), they are shown in uppercase. |
| Example Conventions | In all examples of Client FTP3 input and output in this manual, user entries are shown in boldface type.
The Client FTP3 examples in this manual assume that you have issued OPEN and implied LOG commands similar to this example to connect an IBM MVS TSO user to another system: |
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.
Table 3-4 gives a brief description of each command and its function; detailed descriptions of each command follow the table.
| Command | Function |
|---|---|
| ? | Get help on all commands or one command |
| ACCOUNT | Send account information |
| APPEND | Append data to file on remote host |
| ASCII | Set the transfer type to ACSII |
| BINARY | Set the file transfer mode to binary |
| CD | Change working directory on the remote |
| CDUP | Change to parent directory on remote |
| CLOSE | Disconnect from remote host |
| CWD | Change working directory (same as CD) |
| DEBUG | Toggle to activate or deactivate the DEBUG option |
| DELETE | Delete file on remote host |
| DELIMIT | Display file delimiter on local host |
| DIR | List directory on remote host |
| EBCDIC | Set file transfer type to EBCDIC |
| GET | Copy file from remote host |
| HELP | Display help information |
| LCD | Change working directory on local host |
| LMKDIR | Create a PDS on local host |
| LOCSITE | Send SITE to local host |
| LOCSTAT | Display status for local host |
| LPWD | Print the local directory name |
| LS | List file names on remote host |
| MDELETE | Delete multiple files on remote host |
| MGET | Retrieve multiple files from remote host |
| MKDIR | Create a new directory on remote host |
| MODE | Set transmission mode |
| MPUT | Store multiple files on remote |
| NOOP | Send NOOP to remote |
| OPEN | Open connection to remote host |
| PASS | Send password to remote host |
| PROMPT | Toggle prompting for MGET, MPUT and MDELETE |
| PUT | Store file on remote host |
| PWD | Show name of working directory on remote host |
| QUIT | Exit FTP |
| QUOTE | Send uninterpreted string to remote host |
| RENAME | Rename file on remote host |
| RESTART | Restart a transfer |
| RMDIR | Remove directory on remote host |
| RUNIQUE | Toggle STORAGE method on local host |
| SENDSITE | Toggle sending of SITE command |
| SITE | Send SITE parameters to remote host |
| STATUS | Send STATUS to remote |
| STRUCT | Set file structure |
| SUNIQUE | Store unique file names on remote host |
| SYSTEM | Display remote host operating system |
| TSO | Execute TSO command |
| TYPE | Set transfer type |
| USER | Send userid to remote host |
| VERBOSE | Display system replies with additional information |
| command_name | Command for which you are requesting information. |
If the ? command is specified with no arguments, it displays a list of Client FTP3 commands.
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.
? DIR
DIR pathr pathl - Directory list of remote host
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]| account_info | Information to be sent to the remote host. |
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 ]| 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. |
If either file name is omitted, you are prompted for the file name.
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.
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.
ASCIIThe 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.
BINARYThis command has no arguments or keywords.
The CD command requests that the remote Server FTP change the current directory to a new directory.
CD [ path_name ]| path_name | Indicates to the remote Server FTP the name of the directory to be made the current directory. |
If you omit path_name, the Client FTP3 program prompts you for the desired value.
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.
The following example shows a change of directory to a remote UNIX system:
CD /u/lpn/d.ddn
250 CWD command successful.
The following example shows a change to a directory on a remote system running Cisco IOS for S/390:
CD ACCES
250 "'USER1.ACCES.'" is current prefix
The following example shows a change to a specific directory:
CD 'TEST.DIR'
250 "'TEST.DIR'" is current prefix
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.
CDUPA 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).
The following example shows a change to the parent directory of the old current directory on a remote UNIX system:
CDUP
250 CWD command successful.
The CLOSE command logs you out and terminates the connection between you and the remote Server FTP.
CLOSECLOSE221 Goodbye.
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.
DEBUGThe 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.
DEBUG
The DELETE command directs the remote Server FTP to delete the specified file.
DELETE [ path_name ]| path_name | The specific file to delete. |
If you omit path_name, you are prompted to supply one.
The syntax for path_name depends on the associated Server FTP.
DELETE oldfile
250 DELE command successful.
The DELIMIT command displays the character delimiter used between the file name and the file type.
DELIMITThe delimiter cannot be changed by this command.
The DIR command requests that the remote Server FTP provide a directory list for the specified path.
DIR [ remote_path ] [local_path ] [ ( DISK ]| remote_path | Remote directory to be listed. If remote_path is not specified, you receive a list of your current directory. |
| local_path | File to which the directory list is written. If local_path is not specified, the directory list is displayed on your screen. |
| DISK | Stores output in a data set named local_directory.FTP.DIROUTP. If local_directory is a PDS, output is stored in member DIROUTP. |
The following example lists the contents of a directory on an MVS system.
dir /export/home/user1/mvs 150 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 ibmlink2 226 ASCII Transfer complete.
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
EBCDIC
EBCD ENTERED
stat
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 ]| remote_path | File name to be retrieved from the remote host. |
| local_path | File name at the local host into which the file from the remote host is copied |
| REPLACE | Specifies that the data set on the local host be overwritten. |
If you omit either file name, you are prompted for one.
The syntax for each path depends on the associated Server FTP.
The HELP command requests help information from the local Server FTP.
HELP [ALL | ? | command | [SERVER [remote_command]]]| HELP | (Without any parameters) requests a list of commands available to the FTP3 client. |
| ALL | Provides a brief description of all the commands available to the FTP3 client. |
| ? | Lists the syntax for the HELP command. |
| command | Provides a description of a specific command from the local FTP3 client. |
| SERVER remote_command | Requests information from the remote FTP server. If a specific remote_command is specified, a description of the command is returned from the remote server. |
If no command is specified, a list of supported commands is returned.
The LCD command changes the current working directory on the local host.
LCD [local_path_name]| local_path_name | Specifies the name of the directory on the local host. 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. |
The LMKDIR command creates a directory (or PDS) on the local host.
LMKDIR [local_path_name]| local_path_name | Specifies the name of the directory or PDS that is to be created on the local host. If you want to specify a path name that is not to be appended to 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. |
The LOCSITE command allows you to specify SITE information to be used by the local host.
LOCSITE [ options ]| options | Local site information. For a list of the SITE commands, read the SITE section in Server FTP. |
The LOCSTAT command displays local FTP status information.
LOCSTATThe LPWD command displays the name of the current working directory on the local host.
LPWDThe LS command requests a remote Server FTP to provide a list of file names for the specified path.
LS [ remote_path ] [ local_path ] [ ( DISK ]| remote_path | Path to be listed from the remote host. |
| local_path | Local file into which the list from the remote server is printed. |
| DISK | Stores output in a data set named local_directory.FTP.LSOUTPUT. If local_directory is a PDS, output is stored in member LSOUTPUT. |
If a local path is not specified, the list of files appears on your screen.
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.
The following example shows of the LS command with parameters:
ls /export/home/user1 unix.dir.temp
150 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:
ls 150 ASCII data connection for /bin/ls (138.42.224.15,4135) (0 bytes). -Transfer complete channel comten dump filea tempfile 226 ASCII Transfer complete.
The MDELETE command allows you to delete multiple files on the remote host.
MDELETE [remote_path_name] | [mask]| 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. |
MDELETE userid.myfiles.*
MDELETE file199?
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]| 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. |
ftp> lcd mget.pds"'GAM2.MGET.PDS'" partitioned data set is current directory ftp> cd tstdir ---> CWD tstdir 250 CWD command successful.ftp> mget TST*---> PORT 138,42,160,55,17,34 200 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,35 200 PORT command successful. 550 Catalog structure invalid or user lacks authority to catalog GET TST2 ---> PORT 138,42,160,55,17,36 200 PORT command successful. ---> RETR TST2 150 ASCII data connection for TST2 (138.42.160.55,4388) (29 bytes). 226 ASCII Transfer complete. GET TST3 ---> PORT 138,42,160,55,17,37 200 PORT command successful. ---> RETR TST3 150 ASCII data connection for TST3 (138.42.160.55,4389) (37 bytes). 226 ASCII Transfer complete. ftp>
The MKDIR (make directory) command directs a remote Server FTP to create the specified directory.
MKDIR [ path_name ]| path_name | Directory to be created. |
If you omit path_name, you are prompted for it.
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.
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.new
257 MKD command successful.
The MODE command sets one of three transmission modes:
MODE S | B | C| S | Stream mode. |
| B | Specifies block mode. |
| C | Compressed mode. Data transfer type must be set to EBCDIC. |
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.
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]| 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. |
MPUT userid.myfiles.*
MPUT file199?
The NOOP command is used to test the response of the remote host.
NOOPThe 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 ]| 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 |
The PASS command is used to send a password to the remote host.
PASS password| password | Specifies your password on the remote host. |
The PASS command must follow the USER command.
Read USER for more information.
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]| local_path | File name of the file to be copied from the local server. |
| remote_path | File name of the file at the remote Server into which the file from the local server is copied. If no name is specified, the name from the local host is used. |
The syntax for each path depends on the associated Server FTP. If you omit either path, you are prompted for the file name.
The PWD command directs a remote Server FTP to return the path name of the current working directory.
PWDThis command has no arguments or keywords.
PWD
257 "/u/lpn" is current directory.
The QUIT command terminates the Client FTP3 program.
QUIT
QUIT
221 Goodbye.
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 ]| 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 |
QUOTE pasv
227 Entering Passive Mode (26,131,0,17,4,216).
The RENAME command directs a remote Server FTP to rename a file.
RENAME [ old_path_name ] [ new_path_name ]| old_path_name | File name to be renamed. |
| new_path_name | New name to be assigned to that file. |
If you omit either argument, you are prompted to enter it.
The syntax of the path names depends on the associated Server FTP.
RENAME titlecol coltitle
350 File exists, ready for destination name
250 RNTO command successful.
The RESTART command restarts the last checkpointed file transfer.
RESTThe 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 Server FTP.
The RMDIR (remove directory) command directs a remote Server FTP to remove the specified directory.
RMDIR [ path_name ]| path_name | Directory to be removed. |
If you omit path_name, you are prompted for it.
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.
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.samp
250 RMD command successful.
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.
SENDSITEThe 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.
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 Server FTP.
SITE textThe text argument is required and is passed through unchanged to the specified server.
The STATUS command requests status information from the remote system.
STATUS [ path_name ]| path_name | Directory or file name for which information is requested. |
The STRUCT (file structure) command provides information on file structure to the remote Server FTP.
STRUCT F | R| F | File structure is specified by F. This is the default if no STRUCT command has been used. File structure is used for files with no internal structure, and the file is considered to be a contiguous sequence of data bytes. File structure is accepted for text files (in other words, files with type ASCII or EBCDIC) by all FTP implementations. |
| R | Record structure is set by R. This is for files made up of sequential records. |
Record structure is set by R. This is for files made up of sequential records.
STRUCT F
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.
SUNIQUEThe 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.
The SYSTEM command displays the name of the operating system on the remote host.
SYSTEM
SYSTEM
215 MVS is the operating system of this server.
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.
TRACEThe 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.
DEBUG
The TSO command requests the client FTP3 program to execute a TSO command for you.
TSO command| command | Specifies the TSO command. |
The TYPE command tells a Server FTP the data type to use.
TYPE I | L byte_size | { A | E [ N | T | C ] }ASCII is the default file type.
For both ASCII and EBCDIC file types, vertical format control N is the default.
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.
The USER command identifies your userid to the remote FTP server.
USER user_id [password] [old_password] [/ new_password]| user_id | Your login name on the remote host. |
| password | Your password on the remote host. You will be prompted for your password if you do not supply it. |
| old_password | Your current password on the remote host. |
| new_password | Your new password on the remote host. |
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.
|
|