FTUA(1) Network Queuing Env. 3.3 Last changed: 4-13-98 NNAAMMEE ffttuuaa - Transfers files to and from a remote network site SSYYNNOOPPSSIISS ffttuuaa [--dd] [--gg] [--hh] [--ii] [--nn] [--qq] [--vv] [_h_o_s_t [_d_o_m_a_i_n]] IIMMPPLLEEMMEENNTTAATTIIOONN IRIX systems UNICOS/mk systems UNICOS systems AIX systems Digital UNIX systems HP-UX systems Solaris systems DDEESSCCRRIIPPTTIIOONN The ffttuuaa utility is the file transfer user agent (user interface) for the file transfer agent ffttaa(8). The program lets users transfer files to and from a remote network site by using the file transfer protocols supported by the File Transfer Agent (FTA). ffttuuaa can operate in either immediate or queue mode. The qquueeuuee and iimmmmeeddiiaattee commands control the mode of operation. The ffttuuaa interface is similar to the ffttpp(1B) program, which provides access to the file transfer protocol (FTP) of the Advanced Research Projects Agency network (ARPAnet). The ffttuuaa utility accepts the following options: --dd Enables debugging, which causes messages to be displayed during file transfers. These messages may assist support personnel in resolving problems. Debugging is off by default. After starting an ffttuuaa session, you can turn debugging off or on by using the ddeebbuugg command. --gg Disables file name globbing; that is, metacharacters (**, ??, [[......]]) in file names are not expanded to the string they represent. Globbing is on by default. After starting an ffttuuaa session, you can turn globbing off or on by using the gglloobb command. --hh Displays help for the command-line usage of ffttuuaa and provides a brief description of each command's use. This display also shows the FTA version that you are running. --ii Turns off interactive prompting during multiple file transfers. Interactive prompting is on by default. After starting an ffttuuaa session, you can turn prompting off or on by using the pprroommpptt command. --nn Prevents ffttuuaa from trying autologin on initial connection. When autologin is enabled, ffttuuaa checks the ..nneettrrcc file in the user's home directory for an entry that describes an account on the remote machine. If no entry exists, ffttuuaa prompts for a user name and password. --qq Enables queue mode operation for action commands. The default mode of operation is immediate. After starting an ffttuuaa session, you can change the mode of operation by using the qquueeuuee or iimmmmeeddiiaattee command. The --vv, --ii, --dd, and --gg options change the default for the vveerrbboossee, pprroommpptt, ddeebbuugg, and gglloobb commands, respectively. --vv Engages the verbose option, forcing ffttuuaa to show all responses from the file transfer server, including data transfer statistics. Verbose mode is off by default. After starting an ffttuuaa session, you can turn verbose mode off or on by using the vveerrbboossee command. [_h_o_s_t [_d_o_m_a_i_n]] Indicates the node name or alias of a remote host. The name used depends on the _d_o_m_a_i_n used for connection to the remote host. Optionally, you can follow the name by a space and a domain name. If you omit the domain name, the domain iinneett is used. By default, this is configured to access the TCP/IP FTP file transfer service, but check with your network administrator for a list of valid domain names. When using ffttuuaa noninteractively, use the --ii and --nn options and specify the user name and password by using the uusseerr command. You can enclose command arguments that have embedded spaces in double quotation marks (""). You can specify on the command line the client _h_o_s_t with which ffttuuaa will communicate. FTA tries to connect to _h_o_s_t either when you issue an iimmmmeeddiiaattee command or after it successfully queues a transfer request. When ffttuuaa is waiting for your commands, it displays the ffttuuaa>> prompt. You can supply either a host name or a host name and domain name; however, you cannot supply only a domain name. ffttaa(8) uses _d_o_m_a_i_n to determine the file transfer service that is used. On UNICOS systems that run only the NQE subset (NQS and FTA components), the ffttaa..ccoonnff(5) configuration file determines the requirements for a valid _d_o_m_a_i_n__n_a_m_e. The ffttuuaa commands are organized into six categories: * Action commands * Format commands * Miscellaneous commands * Queue commands * Session commands * Status commands Subsections describe each of these command categories and three additional topics: * Aborting a file transfer * File naming conventions * IBM block mode transfers AAccttiioonn CCoommmmaannddss You can issue action commands when operating ffttuuaa in either immediate or queue mode. In immediate mode, the action associated with a command is executed immediately. You are notified of the status of a command and prompted to continue. In queue mode, the actions are queued and performed when the session with the file transfer agent is closed. The following action commands are available: aappppeenndd _l_o_c_a_l__f_i_l_e [_r_e_m_o_t_e__f_i_l_e] Appends a local file to a file on the remote machine. If you omit _r_e_m_o_t_e__f_i_l_e, the local file name will be used in naming the remote file after the name is altered by any nnttrraannss or nnmmaapp setting. File transfer uses the current settings for ttyyppee, ffoorrmm, mmooddee, and ssttrruucctt. If the remote file does not exist at the remote machine, it is created. ccdd _r_e_m_o_t_e__d_i_r_e_c_t_o_r_y Changes the current directory on the remote machine to _r_e_m_o_t_e__d_i_r_e_c_t_o_r_y. The initial working directory is the home directory of the user under whose account the connection to the remote system was established. ccdduupp Changes the current directory on the remote machine to its parent directory. ddeelleettee _r_e_m_o_t_e__f_i_l_e Deletes the file _r_e_m_o_t_e__f_i_l_e on the remote machine. ggeett _r_e_m_o_t_e__f_i_l_e [_l_o_c_a_l__f_i_l_e] Retrieves _r_e_m_o_t_e__f_i_l_e and stores it on the local machine. If you omit the local file name (_l_o_c_a_l__f_i_l_e), FTA gives the file the name it has on the remote machine, subject to alteration by the current nnttrraannss and nnmmaapp settings. The current settings for ttyyppee, ffoorrmm, mmooddee, and ssttrruucctt are used during the transfer of the file. mmkkddiirr _d_i_r_e_c_t_o_r_y__n_a_m_e Creates the directory _d_i_r_e_c_t_o_r_y__n_a_m_e on the remote machine. mmoovveeoouutt _l_o_c_a_l__f_i_l_e [_r_e_m_o_t_e__f_i_l_e] Stores a local file (_l_o_c_a_l__f_i_l_e) on the remote machine and deletes the local file when the transfer is completed successfully. If you omit _r_e_m_o_t_e__f_i_l_e, FTA uses the local file name to name the remote file after it is processed according to any nnttrraannss or nnmmaapp setting. File transfer uses the current settings for ttyyppee, ffoorrmm, mmooddee, and ssttrruucctt. mmppuutt _l_o_c_a_l__f_i_l_e_s Expands wildcards in the list of local files given as arguments and executes a ppuutt for each file in the resulting list. For details of file name expansion, see gglloobb in the Miscellaneous Commands subsection. Resulting file names are then processed according to nnttrraannss and nnmmaapp settings. ppuutt _l_o_c_a_l__f_i_l_e [_r_e_m_o_t_e__f_i_l_e] Stores a local file (_l_o_c_a_l__f_i_l_e) on the remote machine. If you omit _r_e_m_o_t_e__f_i_l_e, FTA uses the local file name to name the remote file after it is processed according to any nnttrraannss or nnmmaapp setting. File transfer uses the current settings for ttyyppee, ffoorrmm, mmooddee, and ssttrruucctt. rreeccvv _r_e_m_o_t_e__f_i_l_e [_l_o_c_a_l__f_i_l_e] A synonym for ggeett. rreennaammee [_f_r_o_m] [_t_o] Renames file _f_r_o_m on the remote machine to file _t_o. rrmmddiirr _d_i_r_e_c_t_o_r_y__n_a_m_e Deletes directory _d_i_r_e_c_t_o_r_y__n_a_m_e on the remote machine. Depending on the remote file transfer service, the directory might have to be empty before you can delete it. sseenndd _l_o_c_a_l__f_i_l_e [_r_e_m_o_t_e__f_i_l_e] A synonym for ppuutt. FFoorrmmaatt CCoommmmaannddss To define the format of files to be used with the file transfer commands and to define the mode in which the file will be transferred, use format commands. If the format will be in effect for the transfer, you must issue format commands before a file transfer command. You can use only the default values for the ffoorrmm, mmooddee, and ssttrruucctt commands. The type of files supported will vary depending on the _d_o_m_a_i_n__n_a_m_e used and the underlying file transfer protocol selected. For more information on file type support for the various file transfer protocols, see ffttaa(8). The following format commands are available: aasscciiii A synonym for ttyyppee aasscciiii. bbiinnaarryy A synonym for ttyyppee bbiinnaarryy. bbllkkmmddbbssiizzee Sets the transfer size used in block mode ppuuttss. The default is 16 Kbytes. This command is necessary to set the transfer size correctly relative to the block size required by IBM's Multiple Virtual Storage Operating System (MVS). For conditions in which you can use this command, see the IBM Block Mode Transfers subsection. ffoorrmm [_f_o_r_m_a_t] Sets the file transfer form to _f_o_r_m_a_t. The default format is nonprint. iibbmmbblloocckk Sets the transfer format mmooddee value to bblloocckk and sets the transfer format ttyyppee to eebbccddiicc. IBM MVS FTP requires these settings. iibbmmbblloocckk is a convenience command to set the FTA environment for block mode transfers between MVS FTP and UNICOS systems. mmooddee [_m_o_d_e__n_a_m_e] Sets the file transfer mode to _m_o_d_e__n_a_m_e. mmooddee must be set to either bblloocckk or ssttrreeaamm. The default mode is ssttrreeaamm. bblloocckk mode is supported only on UNICOS systems. sseettddeeffaauulltt Sets the transfer mmooddee to ssttrreeaamm and the transfer ttyyppee to aasscciiii. These are the default values for these parameters. sseettddeeffaauulltt is a convenience command to undo iibbmmbblloocckk. ssttrruucctt [_s_t_r_u_c_t__n_a_m_e] Sets the file transfer structure to _s_t_r_u_c_t__n_a_m_e. The default structure is file (no record structure). ttyyppee [_t_y_p_e__n_a_m_e] Sets the file transfer type to _t_y_p_e__n_a_m_e. If you omit a type, the current type will be printed. Valid _t_y_p_e__n_a_m_es are aasscciiii, bbiinnaarryy, eebbccddiicc, iimmaaggee (same effect as bbiinnaarryy), and tteenneexx (sets type to local byte size; same effect as bbiinnaarryy). Use aasscciiii when transferring standard text files; use bbiinnaarryy when transferring binary files (such as compiled programs). The default type is aasscciiii. MMiisscceellllaanneeoouuss CCoommmmaannddss The following miscellaneous commands are available: !! [_c_o_m_m_a_n_d [_a_r_g_s] ] Invokes an interactive shell on the local machine. If you specify arguments, the first is taken to be a command to execute directly, with _a_r_g_s as its arguments. The type of shell invoked is that specified in the SSHHEELLLL environment variable. $$ _m_a_c_r_o__n_a_m_e [_a_r_g_s] Executes the _m_a_c_r_o__n_a_m_e macro, which was defined by using the mmaaccddeeff command. Arguments are passed to the macro unglobbed. ?? [_c_o_m_m_a_n_d] A synonym for hheellpp. bbeellll Toggles the bell mode. With the bell mode on, a bell is sounded after each file transfer command is completed. The bell is sounded only when the user is operating in immediate mode. The default is not to sound the bell. bbyyee Terminates the session with the file transfer server and exits ffttuuaa. An end-of-file also terminates the session and exits ffttuuaa. ddeebbuugg [_d_e_b_u_g__v_a_l_u_e] Toggles debugging mode. When you specify _d_e_b_u_g__v_a_l_u_e, it is used to set the debugging level. When debugging is on, ffttuuaa prints each command sent to the file transfer server, preceded by the string -->. A debug value of 0 turns off debugging; a positive debug value turns on debugging. The default is no debugging, unless you start ffttuuaa by using the --dd option. gglloobb Toggles file name expansion for mmppuutt. _G_l_o_b_b_i_n_g is the process of expanding wildcard characters in file names (as in ccsshh(1)) to give a list of names that match existing files. When globbing is turned off with gglloobb, the file name arguments are taken literally and not expanded. Globbing for mmppuutt is done as in ccsshh(1). The default is globbing on, unless you start ffttuuaa by using the --gg option. hheellpp [_c_o_m_m_a_n_d] Prints an informative message about the meaning of _c_o_m_m_a_n_d. If you omit _c_o_m_m_a_n_d, ffttuuaa prints a list of the known ffttuuaa commands. llccdd [_d_i_r_e_c_t_o_r_y] Changes the current directory on the local machine. When you omit _d_i_r_e_c_t_o_r_y, your home directory becomes the local working directory. llhheellpp [ccoommmmaanndd] Provides information about the commands supported by the local FTA server. If you specify the optional ccoommmmaanndd argument, a brief description of the command is displayed. If you omit ccoommmmaanndd, a list of ffttuuaa prints a list of the commands supported by the local server. mmaaccddeeff _m_a_c_r_o__n_a_m_e Defines a macro. Subsequent lines are stored as the _m_a_c_r_o__n_a_m_e macro; an empty line terminates macro input mode. Lines can contain any ffttuuaa command; you cannot call a macro from within another macro. Limits are 16 macros and 4096 total characters in all defined macros. Macros remain defined until you execute a cclloossee, bbyyee, or qquuiitt command. The macro processor interprets $$ and \\ as special characters. A $$ followed by a numeral (or numerals) is replaced by the corresponding argument on the macro invocation command line. A $$ followed by an ii signals the macro processor that the executing macro should be looped. On the first pass, $$ii is replaced by the first argument on the macro invocation command line; on the second pass, it is replaced by the second argument, and so on. A \\ followed by any character is replaced by that character. To prevent special treatment of $$, use the \\. nnmmaapp [_i_n_p_a_t_t_e_r_n _o_u_t_p_a_t_t_e_r_n] Sets or unsets the file name mapping mechanism. When you omit arguments, the file name mapping mechanism is unset. When you specify arguments, FTA maps remote file names during the execution of mmppuutt and ppuutt commands that you issue without a specified remote target file name, and local file names are mapped during the execution of ggeett commands you issue without a specified local target file name. This command is useful when you are connecting to an operating system that has different file naming conventions or practices than those of the UNIX system. The mapping follows the pattern set by _i_n_p_a_t_t_e_r_n and _o_u_t_p_a_t_t_e_r_n. The _i_n_p_a_t_t_e_r_n argument is a template for incoming file names (which may already have been processed according to the nnttrraannss setting). Variable templating is accomplished by the inclusion of sequence $$11, $$22, ..., $$99 in _i_n_p_a_t_t_e_r_n. To prevent this special treatment of the $$ symbol, use \\. All other symbols are treated literally and are used to determine the nnmmaapp _i_n_p_a_t_t_e_r_n variable values. For example, given _i_n_p_a_t_t_e_r_n $$11..$$22 and remote file name mmyyddaattaa..ddaattaa, $$11 would have the value mmyyddaattaa, and $$22 would have the value ddaattaa. The _o_u_t_p_a_t_t_e_r_n argument determines the resulting mapped file name. The sequence $$11, $$22, ..., $$99 is replaced by any value resulting from the _i_n_p_a_t_t_e_r_n template. $$00 is replaced by the original file name. Additionally, sequence [_s_e_q_1,_s_e_q_2] is replaced by _s_e_q_1 if _s_e_q_1 is not a null string; otherwise, it is replaced by _s_e_q_2. For example, the nnmmaapp $$11..$$22..$$33 [[$$11,,$$22]]..[[$$22,,ffiillee]] command would yield an output file name mmyyffiillee..ddaattaa for input file names mmyyffiillee..ddaattaa and mmyyffiillee..ddaattaa..oolldd, an output file name mmyyffiillee..ffiillee for input file name mmyyffiillee, and an output file name mmyyffiillee..mmyyffiillee for input file name ..mmyyffiillee. You can include spaces in _o_u_t_p_a_t_t_e_r_n, as in the following example: nmap $1 |sed "s/ *$//" > $1 To prevent special treatment of the $$, [[, ]], and ,, characters, use the \\. nnoottiiffyy [ssuucccceessss | ffaaiilluurree] [oonn | ooffff] Lets you select the circumstance under which you receive mail, either when your transfer request fails or when it succeeds. The default is notification for file transfer failure. nnttrraannss [_i_n_c_h_a_r_s [_o_u_t_c_h_a_r_s] ] Sets or unsets the file name character translation mechanism. When you omit all arguments, FTA does no character translation in file names. When you specify arguments, FTA translates characters in remote file names during the execution of mmppuutt and ppuutt commands you issue without specifying a remote target file name. FTA also translates characters in local file names during the execution of ggeett commands you issue without specifying a local target file name. This command is useful when connecting to an operating system other than UNIX that has different file naming conventions or practices. Characters in a file name that match a character in _i_n_c_h_a_r_s are replaced with the corresponding character in _o_u_t_c_h_a_r_s. If the character's position in _i_n_c_h_a_r_s is longer than the length of _o_u_t_c_h_a_r_s, the character will be deleted from the file name. pprroommpptt Toggles interactive prompting. Prompting lets you transfer multiple files and retrieve or store those files selectively. When prompting is turned off, an mmppuutt command transfers all files. By default, prompting is on, unless you start ffttuuaa by using the --ii option. Prompting occurs in immediate mode and queue mode. qquuiitt A synonym for bbyyee. qquuoottee _a_r_g_1 _a_r_g_2 ... Sends the specified arguments, verbatim, to ffttaa(8). Support personnel use this command to diagnose problems. rrhheellpp [ccoommmmaanndd] Provides information about the commands supported by the remote FTP server. If you specify the optional ccoommmmaanndd argument, a brief description of the command is displayed. If the ccoommmmaanndd argument is absent, a list of commands supported by the remote server is displayed. Not available in qquueeuueedd mode. rrqquuoottee _a_r_g_1 _a_r_g_2 ... Sends the specified arguments, verbatim, to the remote FTP server. rreesseett Clears the reply queue. This command resynchronizes command-reply sequencing with FTA. If a server violates FTA protocol, resynchronization may be necessary. This command usually is needed only when you have used the qquuoottee command. rruunniiqquuee Toggles storing of files that have unique file names on the local system. If you issue a ggeett command and the file name you specify already exists locally, FTA appends a ..11 to the name. If the resulting name matches another existing file, FTA appends a ..22 to the original name. If this process continues up to ..9999, FTA prints an error message, and the transfer will not occur. The unique file names generated are not reported. The rruunniiqquuee command does not affect local files generated from a shell command. (For more information, see the File Naming Conventions subsection.) The default is to store files without unique file names (rruunniiqquuee is off). ssiittee _a_r_g_1 _a_r_g_2 ... Sends the specified arguments, verbatim, prefixed by SSIITTEE, to the remote FTP server. ssttaattuuss Prints the current status of ffttuuaa. vveerrbboossee Toggles verbose mode. In verbose mode, all responses from the file transfer server are displayed to the user. By default, vveerrbboossee is off, unless you start ffttuuaa by using the --vv option. wwaaiitt When entered in queue mode, suspends ffttuuaa until ffttaa returns a status for the transfer, and terminates the ffttuuaa session. If a transfer fails because of a transient error, it is requeued but not recovered. When you enter this command in immediate mode, FTA issues an error message. QQuueeuuee CCoommmmaannddss Queue commands let you examine and modify the status of the file transfer queue. You do not have to issue any session commands. The following queue commands are available: iimmmmeeddiiaattee Switches to immediate mode operation. In immediate mode, action commands are performed at the time the command is issued. ffttuuaa starts in immediate mode, unless you use the --qq option. qqddeelleettee [_q_u_e_u_e__i_d] ... Removes the specified file transfers from the queue. File transfer requests are specified by using their _q_u_e_u_e__i_d, which you can obtain from the display produced by qqddiirr. You can specify more than one _q_u_e_u_e__i_d; separate them by using spaces. qqddiirr [_q_u_e_u_e__i_d] [_l_o_c_a_l__f_i_l_e] Prints a list of the user's current file transfer queue status and optionally places the output in _l_o_c_a_l__f_i_l_e. The list includes the _q_u_e_u_e__i_d and the local file and remote file names. If you include a _q_u_e_u_e__i_d argument, the list is restricted to a specific request. If you omit _l_o_c_a_l__f_i_l_e, or if _l_o_c_a_l__f_i_l_e is --, output is sent to standard output. qqllss [_q_u_e_u_e__i_d] [_l_o_c_a_l__f_i_l_e] Prints a list of the user's current file transfer queue status and optionally places the output in _l_o_c_a_l__f_i_l_e. The list includes the user name and the time the transfer was queued. If you include a _q_u_e_u_e__i_d argument, the list is restricted to a specific request. If you omit _l_o_c_a_l__f_i_l_e, or if _l_o_c_a_l__f_i_l_e is --, output will be sent to standard output. qquueeuuee Switches to queue mode operation. In queue mode, action commands are queued and are performed only when the session with the file transfer agent is closed. To start ffttuuaa in queue mode, use the --qq option. SSeessssiioonn CCoommmmaannddss Session commands define the parameters required to identify the remote host and the file transfer protocol appropriate for the host's domain. They also define user identification and authorization parameters. In a typical sequence of commands, you issue session commands before the format and action commands. The following session commands are available: aaccccoouunntt [_p_a_s_s_w_o_r_d] Supplies a supplemental password required by a remote system for access to resources after a login is completed successfully. If you omit arguments, ffttuuaa prompts you for an account password (after the local echo is disabled). cclloossee Terminates the session with the file transfer server and returns to the command interpreter. Defined macros are erased. ddiissccoonnnneecctt A synonym for cclloossee. ddoommaaiinn _d_o_m_a_i_n__n_a_m_e Supplies an FTA _d_o_m_a_i_n__n_a_m_e. FTA uses the domain to determine the file transfer service that will be used. On UNICOS systems that run only the NQE subset (NQS and FTA components), the ffttaa..ccoonnff(5) configuration file determines the requirements for a valid _d_o_m_a_i_n__n_a_m_e. If you are using the Network Queuing Environment (NQE), use the domain ffttaa if you are transferring files to or from another NQE system and the domain ffttpp if you are transferring files to or from a non-NQE system. If you are using ffttuuaa without NQE, the default domain names are iinneett (for the TCP/IP FTP service) and ddnneett (for the DAP (DECnet) service). ooppeenn _h_o_s_t_n_a_m_e [_d_o_m_a_i_n__n_a_m_e] Supplies a _h_o_s_t_n_a_m_e (and _d_o_m_a_i_n__n_a_m_e) to be used with ffttaa(8). If the autologin feature was disabled by the --nn command-line option, you are prompted for a user name and password to use to log in to the remote host. If the autologin option is enabled, ffttuuaa tries to log you in automatically to the file transfer server by using settings from your ..nneettrrcc file. Autologin is enabled by default. uusseerr _u_s_e_r_n_a_m_e [_p_a_s_s_w_o_r_d] [_a_c_c_o_u_n_t] Identifies the user to the file transfer server. If you omit the password but the server requires it, ffttuuaa prompts you for it (after disabling local echo). If you omit an account field but the file transfer server requires it, ffttuuaa prompts you for it. If you specify an account field and the remote server did not require it, ffttuuaa relays an aaccccoouunntt command to the remote server after the login sequence is completed. Unless you invoke ffttuuaa with autologin disabled (the --nn option), this process is done automatically on initial connection to the file transfer server. SSttaattuuss CCoommmmaannddss Status commands retrieve information from the remote file transfer server. These commands are not available in queue mode: ddiirr [_r_e_m_o_t_e__d_i_r_e_c_t_o_r_y] [_l_o_c_a_l__f_i_l_e] Prints a listing of the contents of directory _r_e_m_o_t_e__d_i_r_e_c_t_o_r_y and optionally places the output in _l_o_c_a_l__f_i_l_e. When you omit _r_e_m_o_t_e__d_i_r_e_c_t_o_r_y, ffttuuaa uses the current directory on the remote machine. When _l_o_c_a_l__f_i_l_e is either unspecified or --, output is sent to standard output. llss [_r_e_m_o_t_e__d_i_r_e_c_t_o_r_y] [_l_o_c_a_l__f_i_l_e] Synonym for ddiirr. mmddiirr _r_e_m_o_t_e__f_i_l_e_s _l_o_c_a_l__f_i_l_e Like ddiirr, except that you can specify multiple remote directories. When interactive prompting is on, ffttuuaa prompts you to confirm that the last argument is indeed the target local file for receiving mmddiirr output. If prompting is off, ffttuuaa tries to write the output to the last argument specified in the mmddiirr command line. To send the output to standard output, use the -- character as the last argument. mmllss _r_e_m_o_t_e__f_i_l_e_s _l_o_c_a_l__f_i_l_e Like nnlliisstt, prints an abbreviated listing of the specified remote files or directories, except that you can specify multiple remote files. When interactive prompting is on, ffttuuaa prompts you to confirm that the last argument is indeed the target local file for receiving mmllss output. If prompting is off, ffttuuaa tries to write the output to the last argument specified in the mmddiirr command line. To send the output to standard output, use the -- symbol as the last argument. nnlliisstt [_r_e_m_o_t_e__f_i_l_e] [_l_o_c_a_l__f_i_l_e] Prints an abbreviated listing of the contents of directory _r_e_m_o_t_e__f_i_l_e on the remote machine. When you omit _r_e_m_o_t_e__f_i_l_e, the current directory is used. When you omit _l_o_c_a_l__f_i_l_e, the output is sent to standard output. ppwwdd Prints the name of the current directory on the remote machine. AAbboorrttiinngg aa FFiillee TTrraannssffeerr To abort a file transfer when operating in immediate mode, press the terminal interrupt key (usually <>). ffttuuaa immediately halts transfers being sent. ffttuuaa halts transfers being received by sending a protocol abort command to the file transfer server and the discarding of any further data received. The speed at which transfers are halted depends on the file transfer server's support for the aabboorrtt command. The qqddeelleettee command aborts a queued file transfer. To determine the _q_u_e_u_e__i_d that you should use with qqddeelleettee, use the qqllss command. FFiillee NNaammiinngg CCoonnvveennttiioonnss Files specified as arguments to ffttuuaa commands are processed according to the following rules: * When globbing is enabled, local file names are expanded according to the rules used in the C shell ccsshh(1). See gglloobb in the Miscellaneous Commands subsection. If the ffttuuaa utility expects a single local file (such as ppuutt), only the first file name generated by the globbing operation will be used. * For ggeett commands that have unspecified local file names, the local file name is the remote file name. To alter this convention, change the nnttrraannss or nnmmaapp setting. * For mmppuutt commands, the remote file name is determined by the nnttrraannss and nnmmaapp settings. * For ppuutt commands that have unspecified remote file names, the remote file name is the local file name. To alter this convention, change the nnttrraannss or nnmmaapp setting. * When you specify the file name --, ffttuuaa uses standard input for reading or standard output for writing. This file name is unavailable for the action commands. * When the first character of the file name is ||, the remainder of the argument is interpreted as a shell command. ffttuuaa then forks a shell, using ppooppeenn(3C) with the argument supplied, and reads (writes) from standard output (standard input). If the shell command includes spaces, you must enclose the argument in quotation marks. Example: "|ls -lt" A particularly useful example of this mechanism is as follows: dir |more This is not available for the action commands. IIBBMM BBlloocckk MMooddee TTrraannssffeerrss The ffttuuaa block mode primarily is used to transfer Cray Research binary-blocked files between UNICOS and IBM's Multiple Virtual Storage Operating System (MVS) FTP. To perform successful ggeett and ppuutt operations, the remote FTP server must support the FTP block transfer mode. (For text file transfers, use the default FTP ASCII mode transfer.) To facilitate transfer, records must be disassembled or assembled into FTP blocks. When executing a block mode ppuutt of a file, the ffttuuaa client uses the Cray Research flexible file input/output system (FFIO) to read each record from the UNICOS file. The record is sent to the remote FTP server by using as many FTP blocks as necessary to complete the transfer. These FTP blocks are reassembled into a record on the remote side. When executing a block mode ggeett, FTP blocks are written to a file as one record by using FFIO. In either case, the remote FTP server must perform complementary actions, assembling or disassembling records into or from FTP blocks. Currently, the only FTP server known to support block transfer mode in this manner is that provided by IBM's TCP/IP for MVS. For more information on using IBM's FTP server, see the manuals IBM supplies with the product. The remainder of this section assumes that you are using this FTP server. To use block mode file transfers successfully, you must know the size of the data records to be transferred, the file structure on the UNICOS system, and the dataset structure on MVS. To inform the FTP client (ffttuuaa) and the MVS FTP server about the necessary file attributes and record size, use sets of ffttuuaa commands, as follows: * For the UNICOS file, use a qualifier in the local file specification on the ppuutt or the ggeett command to specify the FFIO attributes. (FFIO attributes are described in the _A_p_p_l_i_c_a_t_i_o_n _P_r_o_g_r_a_m_m_e_r'_s _I/_O _G_u_i_d_e, publication SG-2168.) * For the MVS dataset, use the ffttuuaa ssiittee command to send information to the server about the dataset characteristics. (A subset of these is similar, but not identical, to a subset of the parameters on the MVS DDDD JJCCLL command.) To see the parameters accepted by the ssiittee command for the remote server, enter the following command: ftua> rrhheellpp ssiittee To see warning messages sent by the remote server that may help to diagnose problems with ssiittee command parameters, use the vveerrbboossee command. To specify the maximum size FTP block to be used by ffttuuaa when sending a file in block mode, use the ffttuuaa bbllkkmmddssiizzee command. See the examples of ggeett and ppuutt commands in the EXAMPLES section. The MVS system administrator can customize the default dataset characteristics for datasets created by the FTP server. Depending on your application, you may want to specify key site parameters to reduce the reliance on particular site defaults. (See the CAUTIONS section.) To see a listing of the current status of many of the server's current transfer settings, use the server ssttaatt command, as follows: ftua> rrqquuoottee ssttaatt Avoid the use of rreeccffmm==vv or rreeccffmm==vvss because without warning you may receive results that are not valid. For files with arbitrary-sized records or records larger than 32,768 bytes, use datasets with characteristics RREECCFFMM==VVBBSS and LLRREECCLL==XX. To set the FTP transfer size to be 8 bytes less than the MVS bblloocckkssiizzee, use the bbllkkmmddbbssiizzee command. Example: ftua> iibbmmbblloocckk ftua> bbllkkmmddbbssiizzee 3322775522 ftua> ssiittee rreeccffmm==vvbbss llrreeccll==xx bblloocckkssiizzee==3322776688 ftua> ppuutt ccrraayyffiillee((ccooss)) mmvvssqquuaall..ddssnn Some choices for bbllkkmmddbbssiizzee and bblloocckkssiizzee versus record size may lead to inefficient storage of the MVS dataset. Generally, choose a value such that the smaller of the average record size or the bbllkkmmddbbssiizzee is close to but less than (bblloocckkssiizzee -- 88). For UNICOS systems, the FFIO specification is for the UNICOS file format, not the MVS dataset. Unless the UNICOS file is already in an IBM format, do not use FFIO IBM format specifications. NNOOTTEESS If the FFTTAAPPAATTHH environment variable is defined, ffttuuaa will use the value as the full path for ffttaa(8). If FFTTAAPPAATTHH is set to the string ffttaa, the user's path will be used to locate ffttaa(8). If FFTTAAPPAATTHH is null, ffttuuaa will fail. To use the default value, you must unset the environment variable. The SSHHEELLLL environment variable defines the shell used in shell escapes. When SSHHEELLLL is undefined, the default shell //bbiinn//sshh is used. To locate your home directory when reading the ..nneettrrcc file, use the HHOOMMEE environment variable. For information about additional FTA environment variables that can can be set, see the ffttaa(8) man page. CCAAUUTTIIOONNSS TTrraannssffeerrss wwiitthh MMLLSS When using ffttuuaa with the UNICOS multilevel security (MLS) feature or the UNICOS/mk security enhancements, your current directory's security level and compartment must match that of the file you are requesting. IIBBMM BBlloocckk MMooddee TTrraannssffeerrss When doing IBM block mode transfers, be very careful when specifying UNICOS FFIO and MVS dataset attributes. In many cases, if you accept the default values or specify values inconsistent with the structure of the UNICOS file or MVS dataset, the file transfer may complete without error but the records in the dataset will be truncated or otherwise incorrect. Use only one ssiittee command per session. Unexpected side-effects may occur because of new default values overriding values specified on previous ssiittee commands. Many ssiittee command parameters also apply only to datasets created by FTP. If the dataset already exists, existing characteristics might be used without warning. When using ssiittee commands to MVS while in queue mode, syntax errors are not reported. If syntax errors exist, IBM MVS FTP server incorrectly returns a success code. BBUUGGSS The correct execution of many commands depends on proper behavior by the file transfer server. An error in the treatment of carriage returns in the 4.2BSD UNIX ASCII-mode transfer code was corrected. This correction may result in incorrect transfers of binary files to and from 4.2BSD servers that use the ASCII type. To avoid this problem, use the binary image type. EEXXAAMMPPLLEESS Example 1: The following example uses queue mode to transfer all plain files in the current directory to a new directory called ttmmpp on the remote system. The transfer is started after the qquuiitt(1) command is issued. $ ffttuuaa --ii --qq ssnn99999999 Name (sn9999:brock): Password: ftua> mmkkddiirr ttmmpp ftua> ccdd ttmmpp ftua> mmppuutt ** ftua> qquuiitt Example 2: The following example shows the status of the transfer that was started in the preceding example: $ ffttuuaa ftua> qqddiirr aaaa1100882255 --QID-- ---Queued On --- --User-- --Group-- aa10825 Fri Jun 29 11:59 brock brock State: Active Status: Connecting Priority: 0 Last Attempt: Fri Jun 29 11:59 Domain: inet Host: sn9999 Username: brock MakeDir RemoteDir: tmp ChangeDir RemoteDir: tmp Copy (put) LocalFile: /x/brock/ftua/cmds.c RemoteFile: cmds.c Copy (put) LocalFile: /x/brock/ftua/cmdtab.c RemoteFile: cmdtab.c Copy (put) LocalFile: /x/brock/ftua/ftuacmds.c RemoteFile: ftuacmds.c ftua> qquuiitt The next two examples illustrate typical ggeett and ppuutt procedures that use block mode. Example 3: The following example illustrates the use of the ggeett command in block mode. To receive a dataset from MVS to a UNICOS file within an ffttuuaa session, take the following steps: 1. Set mmooddee to bblloocckk and ttyyppee to eebbccddiicc by using the iibbmmbblloocckk command. Typically, you do not have to specify a ssiittee command if you want the server to read the dataset by using the attributes stored in the MVS catalog. 2. Describe how a UNICOS file should be written for a ggeett command by appending the FFIO attributes (in parentheses) to the local file specification. Whenever mmooddee is bblloocckk, ffttuuaa uses FFIO to write a file. If you do not specify FFIO attribute, the file is written in UNICOS binary-blocked format (FFIO ccooss format). The ggeett command syntax follows: ftua> ggeett rreemmoottee__ffiillee llooccaall__ffiillee((ffffiioo__aattttrriibbuutteess)) A specific example of the command follows: ftua> ggeett mmvvssqquuaall..ddssnn ccrraayyffiillee((ccooss)) Example 4: The following example illustrates use of the ppuutt command in block mode. To send a UNICOS file to an MVS dataset within an ffttuuaa session, follow these steps: 1. Set mmooddee to bblloocckk and ttyyppee to eebbccddiicc by using the iibbmmbblloocckk command. 2. Specify the characteristics of a new MVS dataset by using the ssiittee command. 3. Depending on the maximum record size of the UNICOS file and the block size and record format of the MVS dataset, you may have to use the bbllkkmmddbbssiizzee command to specify the maximum size of each FTP block that ffttuuaa will send to the server. The default FTP block size used by ffttuuaa is 16,384 bytes. ftua> bbllkkmmddbbssiizzee ssiizzee__iinn__bbyytteess 4. Describe how a UNICOS file should be read for a ppuutt command by appending the FFIO attributes (in parentheses) to the local file specification. ffttuuaa uses FFIO to read a file whenever mmooddee is bblloocckk. If you do not specify a FFIO attribute, the file is assumed to be in UNICOS binary-blocked format (FFIO ccooss format). The ppuutt command syntax follows: ftua> ppuutt llooccaall__ffiillee((ffffiioo__aattttrriibbuutteess)) rreemmoottee__ffiillee A specific example of the command follows: ftua> ppuutt ccrraayyffiillee((ccooss)) mmvvssqquuaall..ddssnn FFIILLEESS The ..nneettrrcc file contains login and initialization information used during the autologin process. It resides in your home directory on the local host. For more information, see the nneettrrcc(5) man page. SSEEEE AALLSSOO ffttpp(1B) for information on the TCP/IP file transfer mechanism ppooppeenn(3C) ffttaa..ccoonnff(5) for information on configuring aspects of FTA on UNICOS systems that run only the NQE subset (NQS and FTA components) nneettrrcc(5) for information on the format of autologin information used by ffttuuaa nnqqeeiinnffoo(5) for information on the nnqqeeiinnffoo file ffttaa(8) for information on domain names and other aspects of file transfer management _N_Q_E _U_s_e_r'_s _G_u_i_d_e, publication SG-2148, for detailed information on using ffttuuaa(1) with NQE This man page is available only online.