home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / pub / public_html / ftpdoc.old < prev    next >
Text File  |  2020-01-01  |  107KB  |  2,219 lines

  1. <html><head>
  2. <title>The Kermit FTP Client</title>
  3. </head><body>
  4. <h1><a name="top"><tt>3. The Kermit FTP Client</tt></a></h1>
  5.  
  6. <p>
  7. <big><tt><b>D R A F T</b></tt></big>
  8. <p>
  9. <tt>  </tt><i>As of:</i> <b>C-Kermit 7.1.199 Alpha.01</b><br>
  10. <tt>  </tt><i>This file last updated:</i>  <b>14 December 2000</b>
  11. <p>
  12. <tt>  </tt>Copyright © 2000, Frank da Cruz and Christine M. Gianone.<br>
  13. <tt>  </tt>All rights reserved.
  14. <p>
  15.  
  16. <b>C-Kermit 7.1 includes a new built-in FTP client.</b>
  17. This documant, which was extracted from the
  18. <a href="ftp://kermit.columbia.edu/kermit/test/text/ckc71.txt">
  19. C-Kermit 7.1 update notes</a> and converted to HTML for easy reading on
  20. the Web, contains preliminary FTP client documentation, pending
  21. publication of the next edition of <a href="ck60manual.html"><cite>Using
  22. C-Kermit</cite></a>.  Familiarity with C-Kermit usage and commands is assumed. 
  23. Section numbering is based on the original plain-text document.
  24. <p>
  25. <tt>  </tt>  <a href="#x3.1"><b>3.1. Making and Managing FTP Connections</b></a><br>
  26. <tt>  </tt>  <tt>  </tt>  <a href="#x3.1.1">3.1.1. Kermit Command-Line Options for FTP</a><br>
  27. <tt>  </tt>  <tt>  </tt>  <a href="#x3.1.2">3.1.2. The FTP Command-Line Personality</a><br>
  28. <tt>  </tt>  <tt>  </tt>  <a href="#x3.1.3">3.1.3. The FTP URL Interpreter</a><br>
  29. <tt>  </tt>  <tt>  </tt>  <a href="#x3.1.4">3.1.4. Interactive FTP Session Establishment</a><br>
  30. <tt>  </tt>  <a href="#x3.2"><b>3.2. Making Secure FTP Connections</b></a><br>
  31. <tt>  </tt>  <a href="#x3.3"><b>3.3. Setting FTP Preferences</b></a><br>
  32. <tt>  </tt>  <a href="#x3.4"><b>3.4. Managing Directories and Files</b></a><br>
  33. <tt>  </tt>  <a href="#x3.5"><b>3.5. Uploading Files With FTP</b></a><br>
  34. <tt>  </tt>  <tt>  </tt>  <a href="#x3.5.1">3.5.1. FTP PUT Switches</a><br>
  35. <tt>  </tt>  <tt>  </tt>  <a href="#x3.5.2">3.5.2. Update Mode</a><br>
  36. <tt>  </tt>  <tt>  </tt>  <a href="#x3.5.3">3.5.3. Recovery</a><br>
  37. <tt>  </tt>  <a href="#x3.6"><b>3.6. Downloading Files With FTP</b></a><br>
  38. <tt>  </tt>  <tt>  </tt>  <a href="#x3.6.1">3.6.1. FTP GET Switches</a><br>
  39. <tt>  </tt>  <tt>  </tt>  <a href="#x3.6.2">3.6.2. Filename Collisions</a><br>
  40. <tt>  </tt>  <tt>  </tt>  <a href="#x3.6.3">3.6.3. Recovery</a><br>
  41. <tt>  </tt>  <a href="#x3.7"><b>3.7. Translating Character Sets</b></a><br>
  42. <tt>  </tt>  <tt>  </tt>  <a href="#x3.7.1">3.7.1. Character Sets and Uploading</a><br>
  43. <tt>  </tt>  <tt>  </tt>  <a href="#x3.7.2">3.7.2. Character Sets and Downloading</a><br>
  44. <tt>  </tt>  <a href="#x3.8"><b>3.8. FTP Command Shortcuts</b></a><br>
  45. <tt>  </tt>  <a href="#x3.9"><b>3.9. Dual Sessions</b></a><br>
  46. <tt>  </tt>  <a href="#x3.10"><b>3.10. Automating FTP Sessions</b></a><br>
  47. <tt>  </tt>  <tt>  </tt>  <a href="#x3.10.1">3.10.1. FTP-Specific Variables and Functions</a><br>
  48. <tt>  </tt>  <tt>  </tt>  <a href="#x3.10.2">3.10.2. Examples</a><br>
  49. <tt>  </tt>  <a href="#x3.11"><b>3.11. Advanced FTP Protocol Features</b></a><br>
  50. <p>
  51. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  52. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  53. [ <a href="index.html"><b>Kermit Home</b></a> ]
  54. <hr>
  55.  
  56. <h3><a name="x3.1">3.1. Making and Managing FTP Connections</a></h3>
  57.  
  58. Each copy of Kermit can have one FTP connection open at a time.  FTP
  59. connections are independent of regular Kermit connections; a Kermit connection
  60. (serial or network via SET LINE, DIAL, SET HOST, TELNET, etc) may be, but need
  61. not be, open at the same time as an FTP connection, and Kermit connections can
  62. also be closed, and new connections opened, without interfering with the FTP
  63. connection (and vice versa).  Thus, for example, Kermit can have an FTP
  64. connection and a TELNET connection open to the same host simultaneously, using
  65. the TELNET connection (e.g.) to send mail or take other desired actions as
  66. various FTP actions complete.  Of course, each copy of Kermit can do only one
  67. thing at a time, so it can't (for example) transfer a file with FTP and
  68. another file with Kermit protocol simultaneously.
  69. <p>
  70. A Kermit FTP session can be established by
  71. <a href="#x3.1.1">command-line options</a>, by
  72. <a href="#x3.1.3">URL</a>, or by
  73. <a href="#x3.1.4">interactive commands</a>.
  74.  
  75. <h3><a name="x3.1.1">3.1.1. Kermit Command-Line Options for FTP</a></h3>
  76.  
  77. The new command-line option '<tt>-9</tt>' (sorry, we're out of letters) can be
  78. used when starting C-Kermit, telling it to make an FTP connection:
  79. <p><pre>
  80.   kermit -9 hostname
  81. </pre><p>
  82. or if a non-default FTP port is needed:
  83. <p><pre>
  84.   kermit -9 hostname:port
  85. </pre><p>
  86. You can also specify the username on the command line with the <tt>-M</tt>
  87. ("My User ID") option that was already there for other connection types:
  88. <p><pre>
  89.   kermit -9 hostname -M olga
  90. </pre><p>
  91. If you specify the username on the command line, Kermit uses it when making
  92. the connection and does not prompt you for it (but it does prompt you for
  93. the password if one is required).
  94. <p>
  95. Once the connection is made, you get the regular Kermit prompt, and can give
  96. interactive commands such as the ones described below.  When you give a BYE
  97. command, Kermit closes the session and exits, just as a regular FTP client
  98. would do.  If you don't want Kermit to exit when you give a BYE command,
  99. include the <tt>-S</tt> ("Stay") option on the command line.
  100. <p>
  101. Other Kermit command-line options that are not specific to non-FTP connections
  102. should affect the FTP session in the expected ways; for example, <tt>-i</tt>
  103. and <tt>-T</tt> force binary and text mode transfers, respectively.
  104. <p>
  105. File transfers can not be initiated on the "<tt>kermit</tt> <tt>-9</tt>"
  106. command line; for that you need to use Kermit's FTP personality (next section).
  107. <p>
  108. <h3><a name="x3.1.2">3.1.2. The FTP Command-Line Personality</a></h3>
  109. <p>
  110. If you want to replace your regular FTP client with C-Kermit, you can make
  111. a link called "ftp" to the C-Kermit binary (or you can store a copy of the
  112. C-Kermit binary under the name "ftp").  When C-Kermit is invoked with a
  113. program name of "ftp" (or "FTP", case doesn't matter), it assumes the
  114. command-line personality of the regular FTP client:
  115. <p><pre>
  116.   ftp <i>[ options ] hostname [ port ]</i>
  117. </pre>
  118. <p>
  119. In this case the options are like those of a regular FTP client:
  120. <p><pre>
  121.   -d  Debug: enables debug messages and creates a debug.log file.
  122.   -n  No autologin: Kermit should not send your user ID automatically.
  123.   -t  Packet trace: accepted but is treated the same as -d.
  124.   -v  Verbose: accepted but ignored (operation is verbose by default).
  125.   -i  Not interactive: accepted but ignored.
  126. </pre><p>
  127. and the hostname can also be a URL (explained in
  128. <a href="#x3.1.3">Section 3.1.3</a>).  To specify a
  129. non-default TCP port for the FTP server, include the port number or name after
  130. the hostname.
  131. <p>
  132.  
  133. There are also some bonus options that allow you to execute an entire FTP
  134. session from the shell command line, as long as you don't include the
  135. <tt>-n</tt> option.  These are not available with regular FTP clients, and at
  136. least one of these options (<tt>-g</tt>) conflicts with UNIX ftp (where
  137. <tt>-g</tt> means "no globbing", which does not apply to Kermit), and some of
  138. them (like the options above) also conflict with regular Kermit command-line
  139. options:
  140. <p>
  141. <pre>
  142.   -Y            Don't execute the Kermit initialization file [1]
  143.   -q            Quiet, suppresses all but error messages [1]
  144.   -S            Stay, don't exit automatically [1]
  145.   -A            Autologin anonymously [2]
  146.   -u name       Username for autologin [2] (synonym: -M [1])
  147.   -P password   Password for autologin (see cautions below) [2]
  148.   -D directory  cd after autologin [2]
  149.   -b            Binary mode [2]
  150.   -a            Text ("ascii") mode [2] (synonym: -T [1])
  151.   -p files      Files to put (upload) after autologin [2] (synonym: -s [1])
  152.   -g files      Files to get (download) after autologin [3]
  153. </pre><p>
  154. <tt>[1] </tt>Same as Kermit, not available in regular FTP clients.<br>
  155. <tt>[2] </tt>Conflicts with Kermit, not available in regular FTP clients.<br>
  156. <tt>[3] </tt>Same as Kermit, conflicts with regular FTP clients.<br>
  157. <p>
  158. Fancier options such as restart, character-set translation, filename collision
  159. selection, automatic move/rename/delete, etc, are not available from the
  160. command line; for these you can use the commands described in the following
  161. sections.
  162. <p>
  163. The following security options are also available, explained in
  164. <a href="#x3.2">Section 3.2</a>:
  165. <p><pre>
  166.   -k realm      Kerberos 4 realm [2]
  167.   -f            Kerberos 5 credentials forwarding [2]
  168.   -x            autoencryption mode [2]
  169.   -c cipher     SRP cipher type [2]
  170.   -H hash       SRP encryption hash [2]
  171.   -z option     Security options [2]
  172. </pre>
  173. <p>
  174.  
  175. If you include <tt>-A</tt> or specify a name of "anonymous" or "ftp", you are
  176. logged in anonymously and, in the absence of <tt>-P</tt>, Kermit automatically
  177. supplies a password of "<i>user</i><tt>@</tt><i>host</i>", where "user" is
  178. your local user ID, and "host" is the hostname of the computer where Kermit is
  179. running.  If you do not include <tt>-p</tt> or <tt>-g</tt>, Kermit enters
  180. command mode so you can type commands or execute them from a script.
  181.  
  182. <p>
  183.  
  184. If you include <tt>-p</tt> or <tt>-g</tt>, Kermit attempts to transfer the
  185. specified files and then exits automatically at the end of the transfer unless
  186. you also included <tt>-S</tt> (Stay).  It uses the "brief" file transfer
  187. display (one line per file) unless you include the <tt>-q</tt> option to
  188. suppress it.
  189.  
  190. <p>
  191.  
  192. When uploading files with <tt>-p</tt>, Kermit switches automatically between
  193. text and binary mode for each file.
  194.  
  195. <p>
  196.  
  197. When downloading, you should always specify the desired mode, and there is no
  198. per-file mode switching (see <a href="#x3.5">Sections 3.5</a> and
  199. <a href="#x3.6">3.6</a> for greater detail).  In
  200. UNIX be sure to quote any wildcard characters to prevent the shell from
  201. expanding them.  Filename collisions are handled according Kermit's FILE
  202. COLLISION setting (if specified in your Kermit customization file; otherwise
  203. the default, which is BACKUP).
  204. <p>
  205.  
  206. It should go without saying that the <tt>-P</tt> option should be used with
  207. caution.  In addition to the well-known risks of transmitting plaintext
  208. passwords over the Internet, in this case the password also echos to the
  209. screen if you type it, and can be seen in <tt>ps</tt> and <tt>w</tt> listings
  210. that show the user's currently active command and command-line arguments.
  211. Thus command-line FTP sessions are most appropriate for secure or anonymous
  212. connections.
  213.  
  214. <p>
  215. Here's an example in which you download the latest C-Kermit "tarball" from
  216. the Columbia University FTP archive:
  217. <p><pre>
  218.   ftp -A kermit.columbia.edu -bg kermit/archives/ckermit.tar.gz
  219. </pre><p>
  220. This assumes that "ftp" is a symbolic link to C-Kermit.  It logs you in
  221. anonymously and gets the <tt>ckermit.tar.gz</tt> file in binary mode from the
  222. <tt>kermit/archives</tt> directory.
  223. <p>
  224. Here's a slightly more ambitious example that illustrates CD'ing to the
  225. desired server directory to get a group of files in text mode (in this case
  226. the C-Kermit source files):
  227. <p><pre>
  228.   ftp -A kermit.columbia.edu -D kermit/f -ag "ck[cuw]*.[cwh]" makefile
  229. </pre>
  230. <p>
  231.  
  232. In this case we CD to the <tt>kermit/f</tt> directory so we don't have to
  233. include it in each file specification, and we quote the
  234. <tt>ck[cuw]*.[cwh]</tt> specification so the shell doesn't expand it, since we
  235. have to pass it as-is to the server.  Note also that the quotes don't go
  236. around the entire file list; only around each file specification that needs to
  237. be quoted.
  238.  
  239. <p>
  240.  
  241. Here's one more example, that uploads a debug log file in binary mode to the
  242. Kermit incoming directory (as we might ask you to do when following up on a
  243. problem report):
  244. <p>
  245. <pre>
  246.   ftp -A kermit.columbia.edu -D kermit/incoming -bp debug.log
  247. </pre><p>
  248. In this case the <tt>-D</tt> option is required to tell the server where to
  249. put the incoming file.
  250. <p>
  251. Unless the <tt>-Y</tt> option is included, your Kermit initialization file
  252. (<tt>.kermrc</tt> in UNIX, <tt>K95.INI</tt> in Windows) is executed before the
  253. command line options, so you can set any FTP-related preferences there, as
  254. described in the subsequent sections.
  255.  
  256. <h3><a name="x3.1.3">3.1.3. The FTP URL Interpreter</a></h3>
  257.  
  258. <dl>
  259. <dt>If Kermit is invoked with its FTP personality, you can also give a URL
  260. (Universal Resource Locator) instead of a hostname and options, with or
  261. without a username and password:</dt>
  262. <dd><tt>ftp ftp://<i>user</i>:<i>password</i>@<i>host</i>/<i>path</i></tt><br>
  263. <tt>ftp ftp://<i>user</i>@<i>host</i>/<i>path</i></tt><br>
  264. <tt>ftp ftp://<i>host</i>/<i>path</i></tt>
  265. </dl>
  266. <p>
  267. The service must be "ftp" and a hostname or address must be included.  If a
  268. user is included but no password, you are prompted for the password.  If a
  269. path (filename) is included:
  270. <p><ul>
  271. <li>If no user is included, "anonymous" is used.
  272. <li> GET is assumed.
  273. </ul>
  274. <p>
  275. <dl>
  276. <dt>If no path (and no action options) are included, an interactive FTP
  277. session is started, as in this example:</dt>
  278. <dd><tt>ftp ftp://kermit.columbia.edu/</tt>
  279. </dl>
  280. <p>
  281.  
  282. If a path is included, but a username is not included, "anonymous" is used and
  283. an appropriate <i>user</i><tt>@</tt><i>host</i> password is supplied
  284. automatically.  If authentication is successful, Kermit attempts to GET the
  285. file indicated by the path or, if the path is the name of a directory, it asks
  286. the server for a directory listing.  In both cases, Kermit disconnects from
  287. the server and exits after the operation is complete (unless you have included
  288. the <tt>-S</tt> option on the command line).
  289. <p>
  290. <dl>
  291. <dt>Here's an example that gets a listing of the top-level directory at the
  292. Kermit ftp site:</dt>
  293. <dd><tt>ftp ftp://kermit.columbia.edu/kermit/</tt>
  294. <p>
  295. <dt>This example gets the top-level <tt>READ.ME</tt> file from the same directory:</dt>
  296. <dd><tt>ftp ftp://kermit.columbia.edu/kermit/READ.ME</tt>
  297. <p>
  298. <dt>Here's the same example, but requesting a text-mode transfer:</dt>
  299. <dd><tt>ftp -T ftp://kermit.columbia.edu/kermit/READ.ME</tt><br>
  300. This illustrates that you can mix command-line options and URLs if you desire.
  301. <p>
  302. <dt>Here's an example that logs in as a (fictitious) real user to get a file:</dt>
  303. <dd><tt>ftp ftp://olga@ftp.xyzcorp.com/resume.txt</tt><br>
  304. The password is not included, so Kermit prompts for it.
  305. </dl>
  306.  
  307. <h3><a name="x3.1.4">3.1.4. Interactive FTP Session Establishment</a></h3>
  308.  
  309. As you read this and the following sections, bear in mind that any command
  310. that can be given at the prompt can also be used in a script program.
  311. Kermit's script programming language is the same as its interactive command
  312. language.  <a href="ftpscript.html">CLICK HERE</a> if you would like to learn
  313. a bit more about script writing.
  314.  
  315. <p>
  316. An FTP session is established with the FTP OPEN command:
  317. <p><dl>
  318. <dt><tt><b>FTP</b> <i>[</i> <b>OPEN</b> <i>] hostname [ switches ] [ port ]</i></b></tt></dt>
  319. <dd>Opens an FTP connection to the given host on the given port and, if FTP
  320. AUTOLOGIN is ON, also logs you in to the server, prompting for username and
  321. password if necessary.  If no port is specified, the regular FTP protocol
  322. port (21) is used.  The OPEN keyword is optional (unless the hostname
  323. conflicts with one of the FTP command keywords, which you can list
  324. by typing "<tt>ftp</tt> <tt>?</tt>").
  325. </dl>
  326. <p>
  327. The hostname can be an IP host name, numeric IP address, or if you have a
  328. network directory active (SET NETWORK DIRECTORY; see 
  329. <a href="ck60manual,html"><cite>Using C-Kermit</cite></a>), an
  330. entry name in the directory.  In the latter case, if the given hostname
  331. matches exactly one entry, the associated name or address is used; if it
  332. matches more than one, Kermit cycles through them until one is found that can
  333. be opened; if it matches none, then the hostname is used as-is.  If a
  334. directory is active but you want to bypass directory lookup, include an "="
  335. sign at the beginning of the hostname, and/or use a numeric IP address.
  336. <p>
  337. When an FTP connection is opened, the default file-transfer mode is set to
  338. binary if the client and server platforms are alike (e.g. both of them are
  339. some kind of UNIX), and to text ("ascii") if they are not alike.  This has
  340. no particular effect for uploading since Kermit automatically switches between
  341. text and binary mode for each file, but is important for downloading.
  342. The connection is also set to Stream mode and File structure.  Record- or
  343. page-oriented file transfers are not supported by C-Kermit's FTP client.
  344. <p>
  345. The optional FTP OPEN switches are:
  346. <p><dl>
  347. <dt><tt><b>/ANONYMOUS</b></tt></dt>
  348. <dd>Logs you in anonymously, automatically supplying username "anonymous"
  349.   and <i>user</i>@<i>host</i> as the password, based on your local user and 
  350.   host names.
  351. <p>
  352. <dt><tt><b>/USER:</b><i>name</i></tt></dt>
  353. <dd>Uses the given username to log you in, thus avoiding the Name: prompt.
  354. <p>
  355. <dt><tt><b>/PASSWORD:</b><i>text</i></tt></dt>
  356. <dd>Uses the given text as your password, thus avoiding the Password: prompt.
  357.   This switch is not recommended for use in script files, which would be a
  358.   security risk.
  359. <p>
  360. <dt><tt><b>/ACCOUNT:</b>text</i></tt></dt>
  361. <dd>Uses the given text as your account (or secondary password, depending on
  362.   the requirements of the server; most servers do not require or accept an
  363.   account name).  If an account is not supplied, you are not prompted for
  364.   one.
  365. </dl><p>
  366. When a username or password is missing, a prompt is issued at the controlling
  367. terminal and you must type the response; the response can not be scripted.
  368. Use the switches to avoid prompts, or one of the secure authentication methods
  369. described in the next section, or see SET FTP AUTOLOGIN and the FTP USER and
  370. similar commands described later in this section.
  371. <p>
  372. Examples:
  373. <p><pre>
  374.   ftp open kermit.columbia.edu /anonymous  ; Open and log in anonymously
  375.   ftp kermit.columbia.edu /anonymous       ; The OPEN keyword can be omitted
  376.   ftp xyzcorp.com                          ; Open and maybe prompt for username
  377.   ftp xyzcorp.com /user:olga               ; Open and log in as olga
  378.   ftp testing.abccorp.com 449              ; Specify a special TCP port number
  379.   ftp testing.abccorp.com /user:olaf /password:secret 449
  380. </pre><p>
  381. If you don't give a username, Kermit prompts you for one if FTP AUTOLOGIN is
  382. ON; otherise it opens the connection without trying to log in.
  383. <p>
  384. The FTP OPEN command succeeds if a connection was opened to the server (even
  385. if the given username and password were not valid) and fails otherwise (see
  386. <a href="#x3.8">Section 3.8</a> for details).
  387. <p>
  388. When your FTP session is complete, you can terminate it as follows:
  389. <p><dl>
  390. <dt><tt><b>FTP BYE</b></tt></dt>
  391. <dd>Closes the FTP connection if one was open.  Synonym: FTP CLOSE.  The FTP
  392. prefix can be omitted if no other connection is open at the same time (see <a
  393. href="#x3.8">Section 3.8</a> for details).  If a connection log is active, an
  394. FTP record is written to it.  If Kermit was started with the <tt>-9</tt>
  395. command-line option or with its FTP command-line personality, and the
  396. <tt>-S</tt> (Stay) option was
  397. not given, AND there is no other active connection, the FTP BYE command also
  398. exits, just as it does on a regular FTP client.
  399. </dl><p>
  400. The following commands can be used to achieve greater control over the
  401. connection and login process:
  402. <p><dl>
  403. <dt><tt><b>SET FTP AUTOLOGIN</b> <i>{</i> ON, OFF</b> <i>}</i></tt></dt>
  404. <dd>If you give this command prior to opening an FTP connection, it controls
  405. whether Kermit tries to log you in automatically as part of the connection
  406. process.  Normally ON, which means the username and password are sent
  407. automatically (and prompted for if they are not yet known).  When OFF, FTP
  408. OPEN connects to the server without logging in.  OFF is equivalent to the
  409. <tt>-n</tt> command-line option when using Kermit's FTP command-line
  410. personality. 
  411. <p>
  412. <dt><tt><b>FTP USER</b> <i>name [ password [ account ] ]</i></tt></dt>
  413. <dd>Used to log in to an FTP server to which a connection has been made without
  414.   autologin, or when autologin failed.  If the password is furnished on the
  415.   command line, it is used; otherwise you are prompted for a password.  An
  416.   account may also be furnished if required by the server; it is not required
  417.   by Kermit and is not prompted for if omitted.  Synonym: FTP LOGIN.
  418. <p>
  419. <dt><tt><b>FTP ACCOUNT</b> <i>text</i></tt></dt>
  420. <dd>Sends an account name to a server that supports accounts.  If the server
  421.   does not support accounts, an error response occurs.  If the server does
  422.   support accounts, the account is accepted if it is valid and rejected if
  423.   it is not.  The account might be used for charging purposes or it might
  424.   be a secondary password, or it might be used for any other purpose, such
  425.   as an access password for a particular disk.  Servers that support
  426.   accounts might or might not allow or require the account to be sent
  427.   prior to login; usually it is sent after login, if at all.
  428. </dl>
  429. <p>
  430. Example:
  431. <p><pre>
  432.   set ftp autogin off                    ; One thing at a time please
  433.   ftp xyzcorp.com                        ; Try to make the connection
  434.   if fail exit 1 FTP connection failed   ; Check that it was made
  435.   user olga secret                       ; Now log in to the server
  436.   if fail exit 1 FTP login failed        ; Check that it worked
  437.   account 103896854                      ; Login OK - send account
  438.   if fail echo WARNING - FTP ACCT failed ; Warn if problem
  439.   ...                                    ; (have session here)
  440.   bye                                    ; Log out and disconnect
  441. </pre><p>
  442. The following commands are used to control or get information about the FTP
  443. connection.  A particular FTP server does not necessarily support all of them.
  444. <p><dl>
  445. <dt><tt><b>FTP RESET</b></tt></dt>
  446. <dd>Terminates a user session but leaves the connection open, allowing a new
  447.   login via FTP USER.
  448. <p>
  449. <dt><tt><b>FTP IDLE</b> <i>[ number ]</i></tt></dt>
  450. <dd>Most FTP servers automatically log you out and and disconnect your session
  451.   if there has been no activity for a certain amount of time.  Use this
  452.   command to ask the server to set its idle limit to the given number of
  453.   seconds.  Omit the number to ask the server to inform you of its current
  454.   idle limit.
  455. <p>
  456. <dt><tt><b>FTP STATUS</b></tt></dt>
  457. <dd>Asks the FTP server to send information about the current session.
  458.   The result is a free-format report that might include server 
  459.   identification, username and login time, FTP protocol settings, and
  460.   file-transfer statistics.
  461. <p>
  462. <dt><tt><b>FTP SYSTEM</b></tt></dt>
  463. <dd>Asks the FTP server to identify its operating system (Listed in Internet
  464.   Assigned Numbers, Operating System Names).  Examples: UNIX, VMS, VM/CMS,
  465.   WINDOWS-NT.  Unfortunately many variations are allowed (e.g. LINUX-2.0,
  466.   LINUX-2.2, FREEBSD, ULTRIX, etc, instead of UNIX; WINDOWS-NT-3,
  467.   WINDOWS-NT-3.5, WINDOWS-NT-3.51, WINDOWS-NT-4, etc).  The report might
  468.   also include other information like "Type L8", "Type I", or "Type A",
  469.   indicating the file-transfer mode. 
  470. <p>
  471. <dt><tt><b>FTP HELP</b> [ keyword  [ keyword [ ... ] ]</i></tt></dt>
  472. <dd>Asks the server to list the commands it supports.  The response is usually
  473.   cryptic, listing FTP command mnemonics, not the commands used by the client
  474.   (since the server has no way of knowing anything about the client's user
  475.   interface).  For example, the PUT command is STOR in FTP protocol.  If a
  476.   keyword is given, which should be an FTP protocol command, slightly-more-
  477.   detailed help is given about the corresponding command (if the FTP server
  478.   supports this feature).  Examples: "ftp help", "ftp help stor".
  479. <p>
  480. <dt><tt><b>FTP SITE</b> <i>text</i></tt></dt>
  481. <dd>(Advanced) Sends an FTP SITE (site-specific) command.  Usually this means
  482.   that the FTP server is asked to run an external command with the given
  483.   arguments.  You might be able to find out what SITE commands are available
  484.   by sending "ftp help site" to the server, but in general the availability
  485.   of and response to SITE commands is (not surprisingly) site specific.
  486. <p>
  487. <dt><tt><b>FTP QUOTE</b> <i>text</i></tt></dt>
  488. <dd>(Advanced) Sends an FTP command in FTP protocol format.  Use this command
  489.   to send commands to the server that the FTP client might not know about.
  490. <p>
  491. <dt><tt><b>SHOW FTP</b></tt></dt>
  492. <dd>Lists client (Kermit) FTP settings and information.
  493.   Also SHOW CONNECTION, SHOW COMMUNICATIONS.
  494. <p>
  495. <dt><tt><b>HELP FTP</b> <i>[ keyword ]</i></tt></dt>
  496. <dd>Asks Kermit to list and describe its built-in FTP commands.
  497. <p>
  498. <dt><tt><b>HELP SET FTP</b> <i>[ keyword ]</i></tt></dt>
  499. <dd>Asks Kermit to list and describe its built-in SET FTP commands.
  500. </dl>
  501. <p>
  502. [ <a href="#top"><b>Contents</b></a> ] 
  503. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  504. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  505. [ <a href="index.html"><b>Kermit Home</b></a> ]
  506. <hr>
  507. <h3><a name="x3.2">3.2. Making Secure FTP Connections</a></h3>
  508.  
  509. In the previous section, you can see several examples of traditional insecure
  510. authentication: username and password sent across the network in clear text.
  511. Of course this is bad practice on at least two counts: (1) storing passwords
  512. in files (such as script files) gives access to the target systems to anybody
  513. who can obtain read access to your scripts; and (2) sending this information
  514. over the network leaves it open to interception by network sniffers or
  515. compromised hosts.
  516. <p>
  517. Because of the increasing need for security on the Internet, FTP servers are
  518. beginning to appear that offer secure forms of authentication, in which no
  519. information is sent over the network that would allow anyone who intercepts
  520. it to usurp your identity and gain your access rights.
  521. <p>
  522. Kermit provides an equivalent form of FTP security for each type of security
  523. implemented in Telnet.  These include GSSAPI-KERBEROS5, KERBEROS4, Secure
  524. Remote Password (SRP), and Transport Layer Security (SSL and TLS).  When
  525. Kermit is built with the necessary libraries, secure FTP connections are
  526. attempted by default, in which all connections are authenticated and the
  527. command and data channels are private.
  528. <p>
  529. The use of authentication and encryption for FTP connections can be 
  530. adjusted with the commands listed below, which are available only if your
  531. version of Kermit was built with the corresponding security options and
  532. libraries:
  533. <p><dl>
  534. <dt><tt><b>SET FTP AUTHTYPE</b>
  535. <i>{</i> <b>AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS</b> <i>}</i>
  536. </tt></dt>
  537. <dd>Specifies an ordered list of authentication methods to be attempted when
  538.   AUTOAUTHENTICATION is ON.  The default list is: GSSAPI-KRB5, SRP,
  539.   KERBEROS_V4, TLS, SSL.  If none of the selected methods are supported by
  540.   the server, an insecure login is used as a fallback.
  541. <p>
  542. <dt><tt><b>SET FTP AUTOAUTHENTICATION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  543. <dd>Tells whether authentication should be negotiated by the FTP OPEN command.
  544.   Default is ON.
  545. <p>
  546. <dt><tt><b>SET FTP AUTOENCRYPTION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  547. <dd>Tells whether encryption (privacy) should be negotiated by the FTP OPEN
  548.   command.  Default is ON.
  549. <p>
  550. <dt><tt><b>SET FTP COMMAND-PROTECTION-LEVEL</b> <i>{</i> <b>CLEAR, CONFIDENTIAL, PRIVATE, SAFE</b> <i>}</i></tt></dt>
  551. <dd>Determines the level of protection applied to the command channel:
  552. <p><pre>
  553.   CLEAR         Data is sent in plaintext and not protected against tampering.
  554.   CONFIDENTIAL  Data is encrypted but not protected against tampering.
  555.   PRIVATE       Data is encrypted and is protected against tampering.
  556.   SAFE          Data is sent in plaintext but protected against tampering.
  557. </pre><p>
  558. The default is PRIVATE.
  559. <p>
  560. <dt><tt><b>SET FTP CREDENTIAL-FORWARDING</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  561. <dd>Tells whether end-user credentials are to be forwarded to the server if
  562.   supported by the authentication method (GSSAPI-KRB5 only).  This is often
  563.   required to allow access to distributed file systems (e.g. AFS.)
  564. <p>
  565. <dt><tt><b>SET FTP DATA-PROTECTION-LEVEL</b> <i>{</i> <b>CLEAR, CONFIDENTIAL, PRIVATE, SAFE</b> }</i></tt></dt>
  566. <dd>Tells what level of protection is applied to subsequent data channels.
  567.   The meanings of the protection-level keywords are the same as for
  568.   SET FTP COMMAND-PROTECTION-LEVEL.  The default is PRIVATE.
  569. <p>
  570. <dt><tt><b>SET FTP SRP CIPHER</b> <i>name</i></tt></dt>
  571. <dd>Specifies the cipher to be used for encryption when SRP authentication
  572. is in use.  The list of possible choices is computed based on the
  573. capabilities of the local SRP library and includes NONE plus zero or 
  574. more of the following:
  575. <p><pre>
  576.   BLOWFISH_ECB        CAST5_ECB          DES_ECB          DES3_ECB 
  577.   BLOWFISH_CBC        CAST5_CBC          DES_CBC          DES3_CBC
  578.   BLOWFISH_CFB64      CAST5_CFB64        DES_CFB64        DES3_CFB64
  579.   BLOWFISH_OFB64      CAST5_OFB64        DES_OFB64        DES3_OFB64
  580. </pre><p>
  581. The default is CAST5_CBC.
  582. <p>
  583. <dt><tt><b>SET FTP SRP HASH name</b></tt></dt>
  584. <dd>Specifies the hash to be used for data protection when SRP authentication
  585.   is in use.  The choices are MD5 and SHA.  The default is SHA.
  586. </dl><p>
  587. Command-line options:
  588. <p><dl>
  589. <dt><tt><b>-k</b> <i>name</i></tt></dt>
  590. <dd>Specifies the realm to be used with Kerberos 4 authentication
  591.   (= SET AUTH K4 REALM name).
  592. <p>
  593. <dt><tt><b>-f</b></tt></dt>
  594. <dd>Enables forwarding of Kerberos 5 credentials to the host when using
  595.   GSSAPI authentication (= SET AUTH K5 FORWARDABLE ON).
  596. <p>
  597. <dt><tt><b>-x</b></tt></dt>
  598. <dd>Enables autoencryption (= SET FTP AUTOENCRYPTION ON).
  599. <p>
  600. <dt><tt><b>-c</b> <i>cipher</i></tt></dt>
  601. <dd>Specifies the kind of cipher to be used for encryption with SRP 
  602.   authentication.  Equivalent to SET FTP SRP CIPHER, with the same
  603.   choices.  If this option is not given, CAST5_CBC is used.
  604. <p>
  605. <dt><tt><b>-H</b> <i>hash</i></tt></dt>
  606. <dd>Specifies the hash to be used for encryption with SRP authentication.
  607.   Equivalent to SET FTP SRP HASH, with the same choices.  If this option
  608.   is not given, SHA is used.
  609. <p>
  610. <dt><tt><b>-z debug</b></tt></dt>
  611. <dd>Turns on SSL/TLS debugging.
  612. <p>
  613. <dt><tt><b>-z secure</b></tt></dt>
  614. <dd>Requires secure connection.
  615. <p>
  616. <dt><tt><b>-z certsok</b></tt></dt>
  617. <dd>Says to accept all certificates without checking validity.
  618. <p>
  619. <dt><tt><b>-z verify=</b><i>n</i></tt></dt>
  620. <dd>Sets certificate verification mode to the given number, <i>n</i>:
  621. <pre>
  622.   0 = no verification
  623.   1 = verify certificate if presented
  624.   2 = require verification of certificate
  625. </pre>
  626. <p>
  627. <dt><tt><b>-z cert=</b><i>filename</i></tt></dt>
  628. <dd>Specifies a file containing a client certificate to be presented to the
  629. FTP server.
  630. <p>
  631. <dt><tt><b>-z key=</b><i>filename</i></tt></dt>
  632. <dd>Specifies a file containing a private key matching the client certificate.
  633. <p>
  634. <dt><tt><b>-z !krb4</b></tt></dt>
  635. <dd> nokrb4
  636. Disables the use of Kerberos 4.
  637. <p>
  638. <dt><tt><b>-z !gss</b></tt></dt>
  639. <dt><tt><b>-z nogss</b></tt></dt>
  640. <dd>Disables the use of GSSAPI - Kerberos 5.
  641. <p>
  642. <dt><tt><b>-z !srp</b></tt></dt>
  643. <dt><tt><b>-z nosrp</b></tt></dt>
  644. <dd>Disables use of SRP.
  645. <p>
  646. <dt><tt><b>-z !ssl</b></tt></dt>
  647. <dt><tt><b>-z nossl</b></tt></dt>
  648. <dd>Disables the use of SSL.
  649. <p>
  650. <dt><tt><b>-z !tls</b></tt></dt>
  651. <dt><tt><b>-z notls</b></tt></dt>
  652. <dd>Disables the use of TLS.
  653. </dl>
  654. <p>
  655. [ <a href="#top"><b>Contents</b></a> ] 
  656. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  657. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  658. [ <a href="index.html"><b>Kermit Home</b></a> ]
  659. <hr>
  660. <h3><a name="x3.3">3.3. Setting FTP Preferences</a></h3>
  661.  
  662. You can control the amount of feedback received from your FTP session with
  663. the following commands:
  664. <p><dl>
  665. <dt><tt><b>SET TRANSFER DISPLAY</b> <i>{</i> <b>FULLSCREEN, CRT, SERIAL,
  666. BRIEF, NONE</b> <i>}</i></tt></dt>
  667. <dd>FTP transfers use Kermit's normal file-transfer display styles.  Use this
  668. command to choose the desired format; the default on most platforms is
  669. FULLSCREEN.  The display is automatically disabled if Kermit is running in
  670. the background or in batch.  BRIEF is always used for command-line initiated
  671. transfers (unless suppressed by <tt>-q</tt>).
  672. </dl><p>
  673. While a file-transfer is in progress, you can interrupt it in the normal
  674. Kermit ways:
  675. <p><pre>
  676.   X - Cancel current file but go on to the next one (if any).
  677.   Z - Cancel the entire transfer.
  678.   Ctrl-L or Ctrl-W - Refresh the file-transfer display (if any).
  679. </pre><p>
  680. Other FTP preferences can be set globally and persistently with the following
  681. commands; most of these can also be overridden on a per-command basis with
  682. switches that have the same name.
  683. <p><dl>
  684. <dt><tt><b>SET QUIET</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  685. <dd>This command applies to Kermit in general, not just FTP.  OFF by default;
  686.   when ON, it surpresses most messages from most commands as well as the
  687.   file-transfer display.
  688. <p>
  689. <dt><tt><b>SET FTP ERROR-ACTION</b> <i>{</i> <b>PROCEED, QUIT</b> <i>}</i></tt></dt>
  690. <dd>When transferring a group of files with FTP, and an error occurs with one
  691. of the files, Kermit normally goes on the next file.  Use SET FTP
  692. ERROR-ACTION to QUIT to make Kermit stop the transfer immediately and
  693. fail if an error occurs with any single file in the group.  Example:
  694. you have given Kermit a list of files to send, and one of the files can
  695. not be found, or read permission is denied.  Note that cancelling a
  696. file by typing 'X' during transfer is not considered an error (if you want
  697. to cancel the entire transfer, type 'Z' or Ctrl-C).
  698. <p>
  699. <dt><tt><b>SET FTP CHARACTER-SET-TRANSLATION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  700. <dd>Whether to translate character sets when transferring text files with FTP
  701. (explained in <a href="#x3.7">Section 3.7</a>).  OFF by default.
  702. <p>
  703. <dt><tt><b>SET FTP SERVER-CHARACTER-SET</b> <i>name</i></tt></dt>
  704. <dd>Tells Kermit the character set used by the FTP server
  705. (<a href="#x3.7">Section 3.7</a>).
  706. <p>
  707. <dt><tt><b>SET FTP PERMISSIONS</b> <i>{</i> <b>AUTO, ON, OFF</b> <i>}</i></tt></dt>
  708. <dd>When uploading files with PUT or MPUT, this tells whether Kermit should
  709.   send each file's permissions.  The default is OFF, which means not to send
  710.   permissions, in which case the uploaded file's permissions are set by the
  711.   FTP server according to its own criteria.  ON means to send them, AUTO
  712.   means to send them only if the client (Kermit) and server are on like
  713.   platforms (e.g. both UNIX).  Also see FTP PUT /PERMISSIONS.  Note that
  714.   setting permissions after uploading is likely to work (correctly or at
  715.   all) only when the client and server platforms are alike (e.g. both of
  716.   them are some form of UNIX).  Also note that Windows files don't have
  717.   permissions.  Also see FTP CHMOD.
  718. <p>
  719. <dt><tt><b>SET FTP PROGRESS-MESSAGES</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  720. <dd>Tells whether Kermit should print locally-generated feedback messages for
  721.   each non-file-transfer command.  ON by default.
  722. <p>
  723. <dt><tt><b>SET FTP VERBOSE-MODE</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  724. <dd>Tells whether to display all responses from the FTP server.  ON by default.
  725.   This shows all responses to all commands.  When OFF, responses are shown
  726.   only for commands such as FTP PWD whose purpose is to display information.
  727. <p>
  728. <dt><tt><b>SET FTP DEBUG</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  729. <dd>Tells whether local client debugging information should be displayed.
  730.   OFF by default.  When ON, the commands that are sent to the server are
  731.   shown, as well as its responses (even if VERBOSE-MODE is OFF), plus
  732.   additional informational messages are printed regarding the progress of
  733.   secure operations.
  734. </dl>
  735. <p>
  736. Set all of these to OFF (or NONE) when silent running is desired.
  737. <p><dl>
  738. <dt><tt><b>SET FTP AUTOLOGIN</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  739. <dd>Described in <a href="#x3.1">Section 3.1</a>.
  740. <p>
  741. <dt><tt><b>SET FTP FILENAMES</b> <i>{</i> <b>AUTO, CONVERTED, LITERAL</b> <i>}</i></tt></dt>
  742. <dd>When uploading (sending) files, this tells whether to convert outbound
  743.   filenames to "common form".  This means allowing only one period in a name,
  744.   uppercasing any lowercase letters, replacing spaces by underscores, etc.
  745.   AUTOMATIC is the default, meaning LITERAL when client and server are the
  746.   same type of system (e.g. UNIX) and CONVERTED otherwise.  Special case: if
  747.   the setting is AUTOMATIC and the client is not UNIX and the server
  748.   identifies itself as UNIX, Kermit uses a less-strict form of conversion, in
  749.   which lowercase letters are not uppercased and the filename can contain any
  750.   number of periods, but spaces are still converted to underscore.  When
  751.   receiving, conversion generally means to change all-uppercase names to
  752.   lowercase and spaces to underscore.
  753. <p>
  754. <dt><tt><b>SET FTP UNIQUE-SERVER-NAMES</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  755. <dd>Applies only to uploads.  Tells the server to create new, unique names for
  756. incoming files that have the same names as existing files.  OFF by default,
  757. in which case the server overwrites existing files with new files of the
  758. same name.  When ON, the server uses its own built-in method for creating
  759. new names for incoming files; for example, appending a period (<tt>.</tt>)
  760. and a number to the name.
  761. <p>
  762. <dt><tt><b>SET FTP COLLISION</b> <i>{</i> <b>...</b> <i>}</i></tt></dt>
  763. <dd>When downloading, what to do if an incoming file has the same name as an
  764.   existing file.  Options are the same as for SET FILE COLLISION.  If this
  765.   command is not given, Kermit's regular FILE COLLISION setting is used.  If
  766.   this command is given, it overrides the FILE COLLISION setting for FTP
  767.   transfers only.  See <a href="#x3.6.2">Section 3.6.2</a> for details.
  768. <p>
  769. <dt><tt><b>SET FTP PASSIVE-MODE</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  770. <dd>ON by default, to avoid random TCP port assignment for data connections,
  771.   which can prevent FTP protocol from working through firewalls.  Set to
  772.   OFF in case the FTP server does not support passive mode.
  773. <p>
  774. <dt><tt><b>SET FTP SEND-PORT-COMMANDS</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  775. <dd>This command determines whether the FTP client sends a new PORT command
  776.   to the server when accepting incoming data connections (as when not using
  777.   passive mode.)  When PASSIVE-MODE is OFF and SET SEND-PORT is OFF, the port
  778.   that was originally specified is reused.  This is the default behavior for
  779.   normal FTP clients but it is not compatible with many firewalls.
  780. <p>
  781. <dt><tt><b>SET FTP TYPE</b> <i>{</i> <b>TEXT, BINARY</b> <i>}</i></tt></dt>
  782. <dd>Changes the default transfer mode.  When sending (uploading) files, this
  783. command has no effect unless you disable automatic text/binary mode
  784. switching (<a href="#x4">Section 4</a>)
  785. with SET FILE SCAN OFF.  When getting (downloading)
  786. files, this command determines the mode in which Kermit will request the
  787. server to send the files you request.  In all cases, the FTP TYPE can be
  788. overridden in any GET or PUT command by including a /TEXT (/ASCII) or
  789. /BINARY switch.  The FTP TYPE is independent of the Kermit FILE TYPE
  790. setting.  Synonym: ASCII = TEXT.
  791. </dl>
  792. <p>
  793. [ <a href="#top"><b>Contents</b></a> ] 
  794. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  795. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  796. [ <a href="index.html"><b>Kermit Home</b></a> ]
  797. <hr>
  798. <h3><a name="x3.4">3.4. Managing Directories and Files</a></h3>
  799.  
  800. In Kermit, commands for directory and file management can refer to:
  801. <p><ul>
  802. <li>The local computer
  803. <li>A remote computer when you have a connection to a Kermit server or IKSD.
  804. <li>A remote computer when you have a connection to an FTP server.
  805. </ul><p>
  806. (There can also be an HTTP connection, but the commands in this section don't
  807. apply to HTTP connections.)
  808. <p>
  809. Thus in general, each such command comes in three forms:
  810. <p><ul>
  811. <li>With no prefix, it refers to the local computer (CD, DIR, etc).
  812. <li>With the REMOTE prefix, it is for a Kermit server (REMOTE CD, REMOTE DIR).
  813. <li>With the FTP prefix, it's for an FTP server (FTP CD, FTP DIR).
  814. </ul><p>
  815. Note the difference in command format between the Kermit FTP client and most
  816. other FTP clients: in Kermit, unprefixed file management commands apply
  817. locally; the FTP prefix is required to send them to the server (but see
  818. <a href="x3.8">Section 3.8</a>).  In most FTP clients, on the other hand,
  819. unprefixed commands are for the server, and local commands require a prefix.
  820. <p>
  821. Kermit's FTP file and directory management commands are:
  822. <p><dl>
  823. <dt><tt><b>FTP CD</b> <i>[ directory ]</i></tt></dt>
  824. <dd>Tells the FTP server to change its default (working) directory to the
  825.   one given, which usually must be expressed in the syntax of the server
  826.   platform (UNIX, VMS, etc).  If the directory is not specified, the result
  827.   depends on the FTP server -- it might complain that the command is illegal,
  828.   or it might change to your original login directory.  Synonym: FTP CWD
  829.   (Change Wording Directory). 
  830. <p>
  831. <dt><tt><b>FTP UP</b></tt></dt>
  832. <dd>Tells the FTP server to change its default (working) directory to the
  833. parent directory of its current one (equivalent to "<tt>cd</tt> <tt>..</tt>"
  834. in UNIX, or "<tt>cd</tt> <tt>[-]</tt>" in VMS).
  835. <p>
  836. <dt><tt><b>FTP PWD</b></tt></dt>
  837. <dd>Asks the FTP server to report ("print") its current working directory.
  838. <p>
  839. <dt><tt><b>FTP MKDIR</b> <i>directory</i></b></tt></dt>
  840. <dd>Asks the FTP server to create the directory whose name is given.  In
  841. general, the name must be in the syntax of the server's file system, and
  842. it must be either absolute (a full pathname) or relative to the server's
  843. current (working) directory.  This command fails if the directory can't
  844. be created for any reason, including that it exists already.
  845. <p>
  846. <dt><tt><b>FTP RMDIR</b> <i>directory</i></tt></dt>
  847. <dd>Asks the FTP server to remove the directory whose name is given.  The rules
  848. are the same as for MKDIR, plus in most cases, the server will not remove
  849. any directory unless it is empty.
  850. <p>
  851. <dt><tt><b>FTP DIRECTORY</b> <i>[ filespec ] [ redirectors ]</i></tt></dt>
  852. <dd>Tells the FTP server to send a directory listing of the specified files.
  853.   If no filespec is given, the server lists all files in its current working
  854.   directory.  The results are in whatever format the server chooses to send
  855.   them.  You can use UNIX-line redirectors to send the listing to a file or
  856.   a pipeline, exactly as with the regular Kermit client/server REMOTE
  857.   DIRECTORY command (<a href="ck60manual.html"><cite>Using C-Kermit</cite></a>, Chapter 11).  Examples:
  858. <p><pre>
  859.     ftp dir                           ; Show listing of all files on screen
  860.     ftp dir *.txt                     ; List *.txt files on screen
  861.     ftp dir *.txt > somefile          ; Put listing in somefile
  862.     ftp dir *.txt >> somefile         ; Append listing to somefile
  863.     ftp dir *.txt | sort > somefile   ; Put sorted listing in somefile
  864.     ftp dir | more                    ; Runs list through "more"
  865.     ftp dir | sort | more             ; Runs list through "sort" and "more"
  866. </pre><p>
  867. <dt><tt><b>FTP MODTIME</b> <i>filename</i></tt></dt>
  868. <dd>Asks the FTP server to send the modification date and time of the given
  869. file.  The response should be a numeric string in the format:
  870. yyyymmddhhmmssxxxxx...  where yyyy is the year, mm is the month, dd is the
  871. day, hh is the hour (0-23), mm is the minute, ss is the second, and xxx...
  872. is the optional fraction of the second (0 or more digits).  The date and time
  873. is expressed in UTC (GMT, Zulu, Zero-Meridian).
  874. <p>
  875. <dt><tt><b>FTP SIZE</b> <i>filename</i></tt></dt>
  876. <dd>Asks the FTP server to send the size (in bytes) of the given file.
  877. The result might vary depending on whether the current FTP TYPE is binary
  878. or text ("ascii").  For a reliable byte count, do FTP TYPE BINARY first.
  879. <p>
  880. <dt><tt><b>FTP CHMOD</b> <i>permissions filename</i></tt></dt>
  881. <dd>Tells the FTP server to set the permissions (protection) of the given
  882. file to the ones given.  The permissions and filename must be given in
  883. whatever syntax is required by the server.  Example (for a UNIX-based FTP
  884. server):
  885. <p><pre>
  886.   ftp chmod 664 oofa.txt
  887. </pre>
  888. <p>
  889. Not all servers support this
  890. command.  For non-UNIX-based servers, you might need to use FTP QUOTE
  891. or FTP SITE and the appropriate platform-specific FTP server command.
  892. <p>
  893. <dt><tt><b>FTP UMASK</b> <i>[ number ]</i></tt></dt>
  894. <dd>This command is probably specific to UNIX-based servers; it sets the UNIX
  895. "umask", which is the default permissions mask for new (in this case,
  896. incoming) files.  Crudely put, the UNIX umask is an octal representation of
  897. a binary number in in which a 1 bit stands for a permission bit that must be
  898. 0, and a 0 bit stands for a permission bit that can be 0 or 1 depending on
  899. other factors, such as the permissions of the parent directory.  Example:
  900. "umask 007" requires that new files are created without read/write/execute
  901. world permission.  If the number is not specified, the server's current
  902. umask is reported.
  903. <p>
  904. <dt><tt><b>FTP RENAME</b> <i>filename newname</i></tt></dt>
  905. <dd>Asks the FTP server to rename the file whose name is "filename" to
  906. "newname".  Works only for one file; can not be used with wildcards.  The
  907. server's interpretation of "newname" can vary (in some cases it must be a
  908. filename, in others perhaps it can also be a directory name, in which case if
  909. the filename denote a regular file, the file might be moved to the given
  910. directory).
  911. <p>
  912. <dt><tt><b>FTP DELETE</b> <i>[ switches ] filespec [ filespec [ ... ] ]</i></tt></dt>
  913. <dd>Tells the FTP server to delete the file or files listed.  Each file
  914. specification may, but need not, contain wildcard characters to match
  915. multiple files.  File specifications and wildcard syntax must be those
  916. of the server.  Any file specifications that contain spaces must be
  917. enclosed in braces or doublequotes.  FTP MDELETE switches are:
  918. <p><pre>
  919.  /ERROR-ACTION:  /FILENAMES:     /NOBACKUPFILES  /QUIET
  920.  /EXCEPT:        /LARGER-THAN:   /NODOTFILES     /RECURSIVE
  921.  /SMALLER-THAN:
  922. </pre><p>
  923. For details, see the decriptions of these switches in
  924. <a href="#x3.6">Section 3.6</a>.
  925. Synonym: FTP MDELETE (Kermit makes no distinction between DELETE and
  926. MDELETE).
  927. </dl>
  928. <p>
  929. [ <a href="#top"><b>Contents</b></a> ] 
  930. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  931. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  932. [ <a href="index.html"><b>Kermit Home</b></a> ]
  933. <hr>
  934. <h3><a name="x3.5">3.5. Uploading Files With FTP</a></h3>
  935.  
  936. Uploading means sending files from the client (Kermit) to the FTP server.  
  937. The basic command for uploading files with FTP is PUT:
  938. <p><dl>
  939. <dt><tt><b>FTP PUT</b> <i>[ switches ] [ filespec [ as-name ] ]</i></tt></dt>
  940. <dd>Uploads (sends) the file or files that match the file specification, which
  941. may include wildcards, to the server.  If no filespec is given, the names
  942. of files to send are taken from the /LISTFILE: file, if any, otherwise
  943. from the SEND-LIST, if any.  Unless you go out of your way to prevent it,
  944. Kermit determines the transfer mode (text or binary) for each file
  945. automatically, and switches automatically on a per-file basis.  If an
  946. as-name is given, the file is sent under that name instead of its own (if
  947. an as-name is given with a wildcard filespec, the result is a bit more
  948. complicated, and is explained later in this section).
  949. </dl>
  950. <p>
  951. Unlike normal FTP clients, Kermit does not prompt you by default (or at all)
  952. for each file; it just sends them, just as it does with Kermit protocol.
  953. <p>
  954. The filespec can be a literal filename or a Kermit pattern, described in
  955. Section 4.9 of the ckermit2.txt file and on the web in:
  956. <p><pre>
  957.   <a href="http://www.columbia.edu/kermit/ckermit2.html#x4.9">http://www.columbia.edu/kermit/ckermit2.html#x4.9</a>
  958. </pre><p>
  959. Kermit patterns are equivalent to C-Shell patterns and provide a fair amount
  960. of flexibility in selecting which files to send, which is augmented by the
  961. file-selection switches presented below in
  962. <a href="#x3.5.1">Section 3.5.1</a>.
  963. <p>
  964. <dl>
  965. <dt><tt><b>FTP MPUT</b> <i>[ switches ] filespec [ filespec [ ... ] ]</i></tt></dt>
  966. <dd>FTP MPUT is just like FTP PUT except it allows you to give more than one
  967. file specification, and it does not allow an as-name in the file list.
  968. However, as-names can be given to either PUT or MPUT with the /AS-NAME:
  969. switch.
  970. </dl>
  971. <p>
  972. If a PUT or MPUT command results in one file being uploaded, it succeeds if
  973. the file is uploaded completely and fails otherwise.  If more than one file
  974. is selected for upload, success or failure depends on the FTP ERROR-ACTION
  975. setting; if it is PROCEED (the default setting), then the [M]PUT command
  976. succeeds if at least one of the files was completely uploaded, and fails
  977. otherwise,  If FTP ERROR-ACTION is QUIT, the [M]PUT command succeeds if all
  978. selected files were uploaded successfully, and fails if any file failed.
  979. <p>
  980. FTP uploads may be interrupted just like Kermit uploads.  While the transfer
  981. is in progress, type:
  982. <p><pre>
  983.   X to interrupt the current file and go on to the next file.
  984.   Z to cancel the current file and all remaining files.
  985.   ^C (Control-C): Like Z, but might act more quickly.
  986. </pre><p>
  987. MPUT may be used as in regular FTP clients, but it is not required to send
  988. multiple files; in Kermit it is required only if you want to give multiple
  989. file specifications.  Examples:
  990. <p><pre>
  991.   ftp put oofa.txt               ; Send a single file oofa.txt
  992.   ftp put oofa.txt budget.txt    ; Send single file oofa.txt as budget.txt
  993.   ftp put *.txt                  ; Send all *.txt files
  994.   ftp mput *.txt                 ; Send all *.txt files (same as "put *.txt")
  995.   ftp mput *.txt foo.bar         ; Send all *.txt files plus foo.bar
  996. </pre><p>
  997. The distinction between PUT and MPUT is important only when more than one
  998. filespec is given, just like the distinction between Kermit SEND and MSEND:
  999. <p><pre>
  1000.   ftp put oofa.txt budget.txt    ; Send oofa.txt AS budget.txt
  1001.   ftp mput oofa.txt budget.txt   ; Send oofa.txt AND budget.txt
  1002. </pre><p>
  1003. If the source file specification includes any path segments, for example:
  1004. <p><pre>
  1005.   put /tmp/oofa.txt
  1006.   put subdir/another/andanother/oofa.txt
  1007. </pre>
  1008. <p>
  1009. the path portion is stripped from the filename that is sent to the server.
  1010. However, if an as-name contains a path, it is retained.  Examples:
  1011. <p><pre>
  1012.   ftp put /usr/doc/oofa.txt      ; Send as "oofa.txt".
  1013.   ftp put oofa.txt /tmp/oofa.txt ; Send as "/tmp/oofa.txt"
  1014. </pre>
  1015. <p>
  1016.  
  1017. The latter example sends the file <tt>oofa.txt</tt> from your current local
  1018. directory to the server's /tmp directory.  This works only if the server uses
  1019. the same directory notation that you used in the as-name AND the given
  1020. directory already exists on the server AND if you have write access to it.
  1021.  
  1022. <h3><a name="x3.5.1">3.5.1. FTP PUT Switches</a></h3>
  1023.  
  1024. FTP PUT and MPUT are similar in format and behavior to the regular Kermit
  1025. SEND and MSEND commands, and they allow most of the same optional switches:
  1026. <p><pre>
  1027. C-Kermit>ftp put ? Filename, or switch, one of the following:
  1028.  /after:                 /filenames:             /recover
  1029.  /array:                 /larger-than:           /recursive
  1030.  /as-name:               /listfile:              /rename-to:
  1031.  /before:                /local-character-set:   /server-character-set:
  1032.  /binary                 /move-to:               /smaller-than:
  1033.  /command                /nobackupfiles          /text
  1034.  /delete                 /nodotfiles             /transparent
  1035.  /dotfiles               /not-after:             /type:
  1036.  /error-action:          /not-before:            /update
  1037.  /except:                /permissions:           /unique-server-names
  1038.  /filter:                /quiet
  1039. </pre><p>
  1040. Most of these switches are common to Kermit's SEND and MSEND commands, so are
  1041. described only briefly here.  For greater detail see:
  1042. <p><pre>
  1043.   <a href="http://www.columbia.edu/kermit/ckermit2.html#x1.5">http://www.columbia.edu/kermit/ckermit2.html#x1.5</a> (explanation of switches)
  1044.   <a href="http://www.columbia.edu/kermit/ckermit2.html#x4.7">http://www.columbia.edu/kermit/ckermit2.html#x4.7</a> (file-transfer switches)
  1045. </pre><p>
  1046. First the file-selection switches:
  1047. <p>
  1048. <dl>
  1049. <dt><tt><b>/AFTER:</b><i>date-time</i></tt></dt>
  1050. <dt><tt><b>/BEFORE:</b><i>date-time</i></tt></dt>
  1051. <dt><tt><b>/NOT-AFTER:</b><i>date-time</i></tt></dt>
  1052. <dt><tt><b>/NOT-BEFORE:</b><i>date-time</i></tt></dt>
  1053. <dd>Only send those files modified on or after or before the given date and
  1054. time.  These switches can be combined to select files modified between
  1055. two date/times.  Various date-time formats are accepted; if the date-time
  1056. contains spaces, it must be enclosed in braces or doublequotes.
  1057. Examples:<br><pre>  ftp put /after:{1 jan 2000 0:00:00} *
  1058.   ftp put /after:-5days *
  1059. </pre><p>
  1060. <dt><tt><b>/LARGER-THAN:</b><i>number</i></tt></dt>
  1061. <dt><tt><b>/SMALLER-THAN:</b><i>number</i></tt></dt>
  1062. <dd>Only send files larger (smaller) than the given number of bytes
  1063. (characters, octets).  These switches can be combined to select files in a
  1064. certain size range.
  1065. <p>
  1066. <dt><tt><b>/TYPE:</b><i>{</i><b>TEXT,BINARY</b><i>}</i></tt></dt>
  1067. <dd>Only send files that are the given type, which is determined for each
  1068. file just before sending it by file scanning.
  1069. <p>
  1070. <dt><tt><b>/[NO]DOTFILES</b></tt></dt>
  1071. <dd>[Don't] include files whose names begin with dot (<tt>.</tt>).  By default,
  1072. such files are not included unless your filespec explicitly mentions
  1073. them.
  1074. <p>
  1075. <dt><tt><b>/NOBACKUPFILES</b></tt></dt>
  1076. <dd>Don't include files whose names end with <tt>.~<i>nnn</i>~</tt>, where
  1077. <i>nnn</i> is a number.  These are backup files created by Kermit, EMACS, and
  1078. other applications.   By default, backup files are included.
  1079. <p>
  1080. <dt><tt><b>/EXCEPT:</b><i>pattern</i></tt></dt>
  1081. <dd>Exception list -- don't send files whose names match the given pattern.
  1082. See <a href="http://www.columbia.edu/kermit/ckermit.html#x1.5.4">http://www.columbia.edu/kermit/ckermit.html#x1.5.4</a>
  1083. for details.
  1084. <p>
  1085. <dt><tt><b>/RECURSIVE</b></tt></dt>
  1086. <dd>Sends the desired files from the current (or given) directory, plus all
  1087. directories beneath it, replicating the directory structure on the server.
  1088. No special capabilities are required in the server, but of course your
  1089. login ID on the server must have the appropriate access and permission to
  1090. create directories.  Recursive PUTs work not only between like platforms
  1091. (e.g. UNIX to UNIX) but also between unlike ones (e.g. UNIX to VMS or
  1092. Windows), in which case text-file format differences are handled by Kermit's
  1093. automatic text/binary mode switching
  1094. (<a href="#x4">Section 4</a>) and character-set
  1095. translation (<a href="#x3.7">Section 3.7</a>).  Synonym: /SUBDIRECTORIES.
  1096. <p>
  1097. <dt><tt><b>/UPDATE</b></tt></dt>
  1098. <dd>Send only files that have changed since last time
  1099. (<a href="#x3.5.2">Section 3.5.2</a>).
  1100. <p>
  1101. <dt><tt><b>/ARRAY:</b><i>arrayname</i></b></tt></dt>
  1102. <dd>The "file" to be sent is an array, or a segment of one, rather than a
  1103. real file.  In this case the other selection switches don't apply.
  1104. The array contents are sent in text mode, and each array element is
  1105. treated as a line.  Example:
  1106. <pre>
  1107.   ftp put /as-name:array.txt /array:&a
  1108. </pre>
  1109. (or, to send a segment of the array, <tt>/array:&a[100:199]</tt>).  If you
  1110. don't include an /AS-NAME, a name of "<tt>_array_x_</tt>" is used (where x is
  1111. the array letter).  If you include this switch, most other switches are
  1112. meaningless and ignored.
  1113. <p>
  1114. <dt><tt><b>/COMMAND</b></tt></dt>
  1115. <dd>The "file" to be sent is the standard output of a command, rather than
  1116. a real file.  It is sent in text or binary mode according to the prevailing
  1117. FTP TYPE, which can be overridden with a /TEXT or /BINARY switch.  Example:
  1118. Example:
  1119. <pre>
  1120.   ftp put /command /as-name:{userlist} {finger | sort -r}
  1121. </pre>
  1122. <p>
  1123. <dt><tt><b>/LISTFILE:</b><i>filename</i></tt></dt>
  1124. <dd>Tells Kermit to obtain the list of files to be sent from the file whose
  1125. name is given.  This file must contain one file specification (which may
  1126. be wild) per line.
  1127. </dl>
  1128. <p>
  1129. Now the other switches:
  1130. <p>
  1131. <dl>
  1132. <dt><tt><b>/AS-NAME:</b><i>text</i></tt></dt>
  1133. <dd>If a single file is being sent, send it with the given <i>text</i> as
  1134. its name.
  1135. If multiple files are being sent, the <i>text</i> must be a template that
  1136. includes variables such as <tt>\v(filename)</tt>, <tt>\v(filenumber)</tt>,
  1137. <tt>\v(ntime)</tt>, to allow dynamic creation of each name.  The same applies
  1138. to the as-name field of the FTP PUT command.  If this switch is not included
  1139. (and an as-name is not included as the second filename to PUT), each file is
  1140. sent with its own name.
  1141. <p>
  1142. <dt><tt><b>/BINARY</b></tt></dt>
  1143. <dt><tt><b>/TEXT</b></tt></dt>
  1144. <dd>Forces this upload to take place in the given mode, regardless of the
  1145. current FTP TYPE setting, and without automatic text/binary switching.
  1146. /ASCII is a synonym for /TEXT.
  1147. <p>
  1148. <dt><tt><b>/FILTER:</b><i>command</i></tt></dt>
  1149. <dd>Specifies that the file(s) is/are to be passed through the given
  1150. command or pipeline on their way to the server.  Example:
  1151. <p><pre>
  1152.   ftp put /binary /filter:{gzip -c \v(filename)} /as-name:\v(filename).gz *
  1153. </pre><p>
  1154. <dt><tt><b>/TRANSPARENT</b></tt></dt>
  1155. <dt><tt><b>/LOCAL-CHARACTER-SET:</b><i>name</i></tt></dt>
  1156. <dt><tt><b>/SERVER-CHARACTER-SET:</b><i>name</i></tt></dt>
  1157. <dd>Character-set translation for text files, explained in
  1158. <a href="#x3.7">Section 3.7</a>.
  1159. <p>
  1160. <dt><tt><b>/ERROR-ACTION:</b><i>{</i><b>PROCEED,QUIT</b><i>}</i></tt></dt>
  1161. <dd>Overrides the prevailing FTP ERROR-ACTION for the duration of this
  1162. PUT or MPUT command only.
  1163. <p>
  1164. <dt><tt><b>/RECOVER</b></tt></dt>
  1165. <dd>Resume an interrupted transfer where from the point of interruption
  1166. (explained in <a href="#x3.5.2">Section 3.5.2</a>).  Synonym: /RESTART.
  1167. <p>
  1168. <dt><tt><b>/DELETE</b></tt></dt>
  1169. <dd>Tells Kermit to delete each source file immediately after, and only if,
  1170. it has been uploaded completely and successfully.  This, in effect, moves
  1171. the file from the client to the server.
  1172. <p>
  1173. <dt><tt><b>/MOVE-TO:</b><i>directory</i></tt></dt>
  1174. <dd>Tells Kermit to move each source file to the named local directory after,
  1175. and only if, it has been uploaded completely and successfully.
  1176. <p>
  1177. <dt><tt><b>/RENAME-TO:</b><i>template</i></tt></dt>
  1178. <dd>Tells Kermit to rename each source file according to the given template
  1179.   after, and only if, it has been uploaded completely and successfully.  The
  1180.   template works as in /AS-NAME.
  1181. <p>
  1182. <dt><tt><b>/FILENAMES:</b><i>{</i><b>AUTOMATIC,CONVERTED,LITERAL</b><i>}</i></tt></dt>
  1183. <dd>Overrides the FTP FILENAMES setting for this upload only.
  1184. <p>
  1185. <dt><tt><b>/PERMISSIONS:</b><i>{</i><b>ON,OFF</b><i>}</i></tt></dt>
  1186. <dd>Overrides the FTP PERMISSIONS setting for this upload only.  
  1187. <p>
  1188. <dt><tt><b>/UNIQUE</b></tt></dt>
  1189. <dd>Tells Kermit to tell the server to give unique names to incoming files that
  1190.   would otherwise overwrite existing files that have the same name.  This
  1191.   switch conflicts with /UPDATE, /RECOVER, and /PERMISSIONS, since the client
  1192.   has no way of knowing the name assigned by the server.
  1193. <p>
  1194. <dt><tt><b>/QUIET</b></tt></dt>
  1195. <dd>Don't display file-transfer progress or statistics.
  1196. </dl>
  1197.  
  1198. <h3><a name="x3.5.2">3.5.2. Update Mode</a></h3>
  1199.  
  1200. When you include the /UPDATE switch, this means to skip sending any file that
  1201. already exists on the server if the local file's modification date/time is not
  1202. later than that of the corresponding file on the server.  Here is a typical
  1203. application for update mode: Suppose that on Computer A, you maintain a large
  1204. set of files (say, a collection of Web pages and graphics images, or the
  1205. source files for a software application), and you need to keep a parallel copy
  1206. on another Computer, B.  Of course you could upload the entire collection
  1207. every day:
  1208. <p><pre>
  1209.   cd <i>source-directory</i>
  1210.   ftp computerb.xyzcorp.com
  1211.   <i>( authentication details... )</i>
  1212.   ftp cd <i>target-directory</i>
  1213.   ftp put <i>[ switches ]</i> *
  1214. </pre><p>
  1215. But if the total size is large or the network slow, this would be
  1216. unnecessarily time-consuming.  By including the /UPDATE switch:
  1217. <p><pre>
  1218.   ftp put /update [ other-switches ] *
  1219. </pre><p>
  1220. only those files that changed since last time are uploaded.  Here's how it
  1221. works.  For each local file that is selected for uploading:
  1222. <p><ul>
  1223. <li>The remote filename is determined in the normal way, according to
  1224.    the FTP FILENAMES setting, /FILENAMES switch, or the as-name, if any.
  1225. <p>
  1226. <li>Kermit sends an MDTM (modification time) command for the corresponding
  1227.    remote filename to the server.
  1228. <p>
  1229. <li>If the server does not understand the MDTM command, the file is sent.
  1230. <p>
  1231. <li>If the server can't find a file with the given name, the file is sent.
  1232. <p>
  1233. <li>If the local file's modification time is later than that of the remote
  1234.    file, the file is sent.
  1235.    
  1236. <li>Otherwise -- the remote file exists but its modification time is equal
  1237.    to or earlier than that of the local file -- the file is skipped.
  1238. </ul><p>
  1239. All time comparisons take place in Coordinated Universal Time
  1240. (UTC)(<a href="#note_utc">1</a>), also
  1241. known as GMT or Zulu time: Timezone 0; standard time, without daylight savings.
  1242. <p>
  1243. Update mode is useful only when always used in the same direction.  When you
  1244. transfer a file with FTP, the destination file receives the current timestamp
  1245. on the receiving computer, not the original file's timestamp.  If you try to
  1246. FTP PUT /UPDATE the same file again, it will be skipped (as expected) since
  1247. the remote copy is newer.  However, if you try to FTP GET /UPDATE the same
  1248. file (<a href="#x3.6">Section 3.6</a>), it will be transferred for the same
  1249. reason.
  1250. <p>
  1251. To check the availability of PUT /UPDATE on a particular connection, issue an
  1252. FTP MODTIME command for a file that is known to exist on the server.  If it
  1253. succeeds, PUT /UPDATE should work and in that case, you can run a procedure
  1254. like the one above every day: the first time, it sends all the files; after
  1255. that, it sends only the ones that changed.
  1256. <p>
  1257. If a transaction log is active, a notation is included for any files that
  1258. are skipped.
  1259. <p><blockquote><a name="note_utc">(1)</a>
  1260. Why is Coordinated Universal Time abbreviated UTC?  From the
  1261. <a href="http://www.boulder.nist.gov/timefreq/faq/faq.htm#10:">
  1262. National Institute of Standards and Technology FAQ</a>:
  1263. "In 1970 the Coordinated Universal Time system was devised by an
  1264. international advisory group of technical experts within the
  1265. International Telecommunication Union (ITU).  The ITU felt it was
  1266. best to designate a single abbreviation for use in all languages in
  1267. order to minimize confusion.  Since unanimous agreement could not be
  1268. achieved on using either the English word order, CUT, or the French
  1269. word order, TUC, the acronym UTC was chosen as a compromise."
  1270. </blockquote>
  1271.  
  1272. <h3><a name="x3.5.3">3.5.3 Recovery</a></h3>
  1273.  
  1274. Suppose that while you are uploading a large file over a slow connection, the
  1275. connection is lost before the entire file is transferred.  With most FTP
  1276. clients, you would have to start over, thus resending the portion of the file
  1277. that was sent already, and that is already on the server.  But Kermit's
  1278. /RECOVER switch (synonym: /RESTART) lets you continue an interrupted transfer
  1279. from the point of failure, thus transferring only the part that wasn't sent
  1280. already.  The prerequisites for recovery are:
  1281. <p><ul>
  1282. <li>The transfer must be in BINARY mode, or else the client and server must
  1283.    reside on like systems (e.g. both on some form of UNIX).
  1284. <p>
  1285. <li>The FTP server must support the SIZE command.
  1286. </ul><p>
  1287. Here's how it works.  When you include the /RECOVER switch:
  1288. <p><ul>
  1289. <li>Kermit checks for conflicting switches, such as /UPDATE and /UNIQUE;
  1290.    if /RECOVER is given with these switches an error occurs.  If /RECOVER
  1291.    is given in other circumstances where it could serve no useful purpose
  1292.    (e.g. with arrays, pipes, or filters), it is ignored.
  1293. </ul><p>
  1294. If the switch is accepted, then for each selected file:
  1295. <p><ul>
  1296. <li>If it is not binary (determined by scanning) and the client and server
  1297.    are not on like platforms, recovery is canceled (the entire file is sent).
  1298.    Otherwise:
  1299. <p>
  1300. <li>A SIZE command is sent for the file (using its remote name).  If the
  1301.    reply indicates the file was not found, or the SIZE command was not
  1302.    understood, or any other kind of error, recovery is canceled.  Otherwise:
  1303. <p>
  1304. <li>A MDTM (modification time) command is sent for the file.  If a valid
  1305.    reply is received, and the modification time of the local file is later
  1306.    than that of the remote file, recovery is canceled.  Otherwise:
  1307. <p>
  1308. <li>If the sizes of the two files are identical, the file is not sent.
  1309.    Otherwise:
  1310. <p>
  1311. <li>Kermit seeks to the recovery spot in the local file, tells the server
  1312.    to APPEND the data which is about to arrive to the remote file, and then
  1313.    sends the data starting at the recovery point.
  1314. </ul><p>
  1315. To safeguard file integrity, recovery is not attempted unless all the
  1316. preconditions are met.  For the widest possible usefulness, APPEND is used
  1317. rather than RESTART.  For stream transfers (the only kind that Kermit
  1318. supports) the results are the same.
  1319. <p>
  1320. By design, the /RECOVER switch can be included with any FTP PUT or MPUT
  1321. command, even if it specifies a group of files.  This allows you to resume
  1322. an interrupted batch transfer from where it left off.  The files that were
  1323. already completely sent are skipped, the file that was interrupted is
  1324. recovered, and the remaining files are uploaded.
  1325. <p>
  1326. By the way, it doesn't matter how the original partial file was uploaded --
  1327. FTP, Kermit, Zmodem, etc: as long as the preconditions are met, it can be
  1328. recovered with FTP PUT /RECOVER, or for that matter also using Kermit
  1329. protocol and SEND /RECOVER.
  1330. <p>
  1331. A word of caution, however, when the original upload was in text mode with
  1332. character-set translation (<a href="#x3.7">Section 3.7</a>):
  1333. <p><ul>
  1334. <li>If the original upload involved a translation from one single-byte
  1335.    character set to another (e.g. Code Page 850 to Latin-1), recovery is
  1336.    safe if you specify the same translations for the recovery.  If you don't,
  1337.    the resulting file will contain a mixture of character sets.
  1338. <p>
  1339. <li>If the original upload involved a translation that changed the size
  1340.    of the file (e.g. from an alphabetic Code Page or Latin Alphabet to
  1341.    Unicode, or vice versa), recovery is NOT safe, even if you specify
  1342.    the same translations.
  1343. </ul><p>
  1344. Kermit has no way of knowing anything about the previous upload.  As a
  1345. safefuard, an error occurs if you include /RECOVER and also specify a
  1346. character-set of UCS2 or UTF8, since recovery can't possibly work in that
  1347. situation.  Otherwise, it's up to you to avoid unsafe recovery operations.
  1348. <p>
  1349. <p>
  1350. [ <a href="#top"><b>Contents</b></a> ] 
  1351. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  1352. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  1353. [ <a href="index.html"><b>Kermit Home</b></a> ]
  1354. <hr>
  1355. <h3><a name="x3.6">3.6. Downloading Files With FTP</a></h3>
  1356.  
  1357. Although uploading files with Kermit's FTP client is just as easy and flexible
  1358. as sending files with Kermit protocol, the same is not always true for
  1359. downloading because FTP servers lack some of the capabilities of a Kermit
  1360. server:
  1361. <p><ul>
  1362. <li>The FTP server does not switch between text and binary mode automatically
  1363.    on a per-file basis and even if it could, it would not have a way to let
  1364.    the client know the transfer mode of each file.  Therefore: (a) you have
  1365.    to give an FTP TEXT or BINARY command prior to downloading to put the
  1366.    server into the desired mode, and (b) you can't download a mixture of text
  1367.    and binary files in the same operation, at least not when client and
  1368.    server are on unlike platforms.
  1369. <p>
  1370. <li>If you want to get more than one file, you have to use MGET, not GET,
  1371.    since the underlying FTP protocol is different in the two cases.  Kermit
  1372.    can't "autodetect" which one you mean, as it can with PUT and MPUT,
  1373.    since it can't be expected to know the wildcard syntax of the remote
  1374.    platform and/or FTP server (the same is true for all other FTP clients).
  1375. <p>
  1376. <li>Some options that are available with FTP PUT can not be used with FTP
  1377.    [M]GET or don't work the same way:
  1378.   
  1379.     /PERMISSIONS (FTP protocol has no mechanism for this).
  1380.     /[NOT-]BEFORE, /[NOT-]AFTER (because of the timezone problem).
  1381.     /RECOVER works only in binary mode.
  1382.     /RECURSIVE has limited utility.
  1383. </ul><p>
  1384. The commands for downloading are:
  1385. <p>
  1386. <dl>
  1387. <dt><tt><b>SET FILE DOWNLOAD-DIRECTORY</b> <i>[ directory ]</i></tt></dt>
  1388. <dd>As with Kermit transfers, this command, if given, tells C-Kermit where to
  1389.   store incoming files in the absence of a specific as-name.  If not given,
  1390.   incoming files are stored as indicated by the as-name, if any, otherwise
  1391.   in the current directory, just as with Kermit transfers.
  1392. <p>
  1393. <dt><tt><b>FTP GET</b> <i>[ switches ] filename [ as-name ]</i></tt></dt>
  1394. <dd>Asks the server to send the given file, and if it comes, stores it locally
  1395.   under the given as-name, if any, otherwise under its original name (modified
  1396.   according to the selected filename conversion option), in your download
  1397.   directory, if you have specified one, otherwise in the directory indicated
  1398.   in the as-name, if any, otherwise in your current directory.  If you
  1399.   accidentally use a wildcard in the filename ("get *.txt") the server will
  1400.   reply with a message like "File not found" (unless there is a file whose
  1401.   name actually is "*.txt").
  1402. <p>
  1403. <dt><tt><b>FTP MGET</b> <i>[ switches ] filespec [ filespec [  filespec [ ... ] ] ]</i></tt></dt>
  1404. <dd>Like GET, but for multiple files.  One or more file specifications can be
  1405.   given, and any or all (or none) of them can contain wildcards.
  1406. </dl>
  1407. <p>
  1408. In both the FTP GET and MGET commands, any filenames that contain spaces
  1409. must be enclosed in braces or doublequotes (see 
  1410. <a href="ftp://kermit.columbia.edu/kermit/test/text/ckc71.txt">Section 5</a>
  1411. for details).
  1412. <p>
  1413. FTP downloads may be interrupted just like Kermit uploads.  While the 
  1414. transfer is in progress, type:
  1415. <p><pre>
  1416.   X to interrupt the current file and go on to the next file.
  1417.   Z (or Control-C) to cancel the current file and all remaining files.
  1418. </pre>
  1419.  
  1420. <h3><a name="x3.6.1">3.6.1. FTP GET Switches</a></h3>
  1421.  
  1422. The following switches are available with FTP GET and MGET:
  1423. <p>
  1424. <dl>
  1425. <dt><tt><b>/TEXT</b></tt></dt>
  1426. <dd>Specifies a text-mode transfer.  Overrides the global FTP TYPE setting
  1427.   for the duration of the current command only.  All files are downloaded
  1428.   in text mode.  Synonym: /ASCII.
  1429. <p>
  1430. <dt><tt><b>/BINARY</b></tt></dt>
  1431. <dd>Specifies a binary-mode transfer.  Overrides the global FTP TYPE setting
  1432.   for the duration of the current command only.  All files are downloaded
  1433.   in binary mode.
  1434. <p>
  1435. <dt><tt><b>/RECOVER</b></tt></dt>
  1436. <dd>This instructs Kermit to try to recover an incomplete download from the
  1437. point of failure.  Works only in binary mode, and only if the server
  1438. supports the (not-yet-standard) FTP "REST" command.  See
  1439. <a href="#x3.6.3">Section 3.6.3</a>
  1440. for details.  Synonym: /RESTART.
  1441. <p>
  1442. <dt><tt><b>/FILENAMES:</b><i>{</i><b>CONVERTED,LITERAL</b><i>}</i></tt></dt>
  1443. <dd>Overrides the <tt>FTP</tt> <tt>FILENAMES</tt> (filename conversion)
  1444. setting for this download only.
  1445. <p>
  1446. <dt><tt><b>/AS-NAME:</b><i>text</i></tt></dt>
  1447. <dd>For GET, this is equivalent to giving an as-name after the filename.
  1448. For MGET, this is the only way to specify alternative names for the incoming
  1449. files.  With MGET, the /AS-NAME text should (must) contain a Kermit variable,
  1450. usually <tt>\v(filename)</tt> or <tt>\v(filenumber)</tt>.  Example:
  1451. <p><pre>
  1452.   mget /text /as-name:\v(filename).new *.c
  1453. </pre><p>
  1454. This gets all "<tt>.c</tt>" files and stores them with "</tt>.new</tt>"
  1455. appended to their names.
  1456. See
  1457. <a href="http://www.columbia.edu/kermit/#x4.1">http://www.columbia.edu/kermit/#x4.1</a>
  1458. for details.
  1459. <p>
  1460. <dt><tt><b>/COMMAND</b></tt></dt>
  1461. <dd>This specifies that the incoming file is to be written to the standard
  1462. input of a command, rather than to a file.  The command name is the as-name
  1463. from the GET command or the /AS-NAME argument.  If you need to refer to the
  1464. incoming file's name in the command, use <tt>\v(filename)</tt>.  See the
  1465. description of the regular Kermit GET /COMMAND command for details and
  1466. examples.
  1467. <p>
  1468. <dt><tt><b>/QUIET</b></tt></dt>
  1469. <dd>Transfer the files quietly; don't put up a file-transfer display.
  1470. <p>
  1471. <dt><tt><b>/ERROR-ACTION:</b><i>{</i><b>QUIT,PROCEED</b><i>}</i></tt></dt>
  1472. <dd>This switch affects only MGET.  If an error occurs with a particular file,
  1473. this tells whether to go on to the next file (PROCEED) or to stop right
  1474. away and fail (QUIT).  The default is PROCEED.
  1475. </dl>
  1476. <p>
  1477. The file selection switches are:
  1478. <p>
  1479. <dl>
  1480. <dt><tt><b>/EXCEPT:{</b><i>pattern</i><b>}</b> <i>or</i>
  1481. <b>/EXCEPT:{{</b><i>pattern</i><b>}{</b><i>pattern</i><b>}{...}}</b></tt></dt>
  1482. <dd>Exception list for MGET; skip downloading any file whose name matches
  1483. any of the given patterns (when using the second format, up to 8 patterns
  1484. may be specified).
  1485. <p>
  1486. <dt><tt><b>/SMALLER-THAN:</b><i>number</i></tt></dt>
  1487. <dd>Download only files whose size is smaller than the given number of bytes.
  1488. Requires that the FTP server support the SIZE command.
  1489. <p>
  1490. <dt><tt><b>/LARGER-THAN:</b><i>number</i></tt></dt>
  1491. <dd>Download only files whose size is greater than the given number of bytes.
  1492. Requires that the FTP server support the SIZE command.
  1493. <p>
  1494. <dt><tt><b>/NOBACKUPFILES</b></tt></dt>
  1495. <dd>During MGET, don't download any files whose names end with backup suffixes
  1496. (<tt>.~<i>n</i>~</tt> where <i>n</i> is a number).
  1497. <p>
  1498. <dt><tt><b>/NODOTFILES</b></tt></dt>
  1499. <dd>During MGET, don't download any files whose names begin with period
  1500. (<tt>.</tt>).   Equivalent to <tt>/EXCEPT:{.*}</tt>.
  1501. <p>
  1502. <dt><tt><b>/LISTFILE:</b><i>filename</i></tt></dt>
  1503. <dd>The given file contains a list of files to GET, one per line.  Filenames
  1504. in the listfile can contain wildcard characters in the syntax of the
  1505. server.  There is no limit on the number of lines in the listfile.
  1506. <p>
  1507. <dt><tt><b>/UPDATE, /COLLISION:</b><i>keyword</i></tt></dt>
  1508. <dd>Explained in <a href="#x3.6.2">Section 3.6.2</a>.
  1509. <p>
  1510. <dt><tt><b>/RECURSIVE</b></tt></dt>
  1511. <dd>This means to try to download an entire directory tree, rather than just
  1512. files from a particular directory.  In fact, FTP protocol does not provide
  1513. a method to request a recursive download, so this works only if the FTP
  1514. server does it anyway, without being asked.  In this case, Kermit detects
  1515. that names in the returned file list contain directory separators, and
  1516. therefore attempts to create the needed directories as the files arrive.
  1517. But this can work only if the server is on the same kind of platform as the
  1518. client, so the pathname syntax can be recognized, and also because the
  1519. server does not switch between text and binary mode, which would be vital
  1520. for cross-platform transfers.  Use with caution.  Synonym: /SUBDIRECTORIES.
  1521. </dl>
  1522. <p>
  1523.  
  1524. The FTP protocol does not include explicit mechanisms for recursion, so Kermit
  1525. builds upon what is available.  Although an Internet draft describes a mechanism
  1526. ("MLST") that would allow protocol-driven recursion, similar to Kermit's File
  1527. Attribute packets (circa 1984), it has not yet attained RFC or standard
  1528. status, and servers are not yet widely available that offer this feature.  In
  1529. the meantime, the effectiveness of MGET /RECURSIVE depends on the FTP server
  1530. implementation.  For example, WU-FTPD always returns a recursive file list,
  1531. but only of those files that match the given wildcard; thus "<tt>mget</tt>
  1532. <tt>/recursive</tt> <tt>*.txt</tt>" descends only into those subdirectories
  1533. whose names end with "<tt>.txt</tt>", which is probably not what you wanted,
  1534. whereas "<tt>mget</tt> <tt>/recursive</tt> <tt>*</tt>" does the whole tree.
  1535.  
  1536. <p>
  1537. When used with FTP DELETE, the /RECURSIVE switch deletes files but not
  1538. directories.
  1539. <p>
  1540. The /BEFORE:, /AFTER:, /NOT-BEFORE:, and /NOT-AFTER: switches are not
  1541. available for downloading because of the confusion with timezones.  Would the
  1542. given times be in the local timezone, the server's timezone, or GMT?  The FTP
  1543. server's directory listings show its own local times but since we don't know
  1544. what timezone the server is in, there's no way to reconcile our local times
  1545. with the server's.
  1546. <p>
  1547. Source-file disposition switches:
  1548. <p>
  1549. <dl>
  1550. <dt><tt><b>/DELETE</b></tt></dt>
  1551. <dd>Each file that is downloaded successfully is to be deleted from the server.
  1552.   Requires the appropriate file access rights on the server.
  1553. </dl>
  1554. <p>
  1555. Destination-file disposition switches:
  1556. <p>
  1557. <dl>
  1558. <dt><tt><b>/TO-SCREEN</b></tt></dt>
  1559. <dd>Displays the incoming file on the screen rather than storing it on disk.
  1560.   If this switch is given, the /RENAME-TO and /MOVE-TO switches are ignored,
  1561.   the file-transfer display is suppressed, and the given file(s) is/are
  1562.   shown on the screen.  Can be used with /FILTER, e.g.
  1563. <p><pre>
  1564.     get /text /to-screen /filter:more oofa.txt
  1565. </pre><p>
  1566.   In fact, you should always use /TO-SCREEN with /FILTER or /COMMAND when 
  1567.   the command would result in displaying the incoming file on the screen;
  1568.   otherwise C-Kermit would have no way of knowing to suppress its file
  1569.   transfer display (since it can't be expected to know what the command
  1570.   or filter does).
  1571. <p>
  1572. <dt><tt><b>/RENAME-TO:</b><i>text</i></tt></dt>
  1573. <dd>Each file that is downloaded is to be renamed as indicated if and only if
  1574. it was received completely and without error.  The text can be literal text
  1575. or can contain variables that are evaluated for each file.  For MGET, the
  1576. text must contain variables; for GET it can be a literal string.  The
  1577. <tt>\v(filename)</tt> variable contains the name of the current file, so:
  1578. <p><pre>
  1579.   ftp mget /rename-to:\v(filename).ok *
  1580. </pre>
  1581. <p>
  1582. causes each file that is successfully downloaded to have "<tt>.ok</tt>"
  1583. appended to its name.  For details see
  1584. <a href="http://www.columbia.edu/kermit/ckermit2.html#x4.1">http://www.columbia.edu/kermit/ckermit2.html#x4.1</a>.
  1585. <p>
  1586. <dt><tt><b>/MOVE-TO:</b><i>text</i></tt></dt>
  1587. <dd>Just like /RENAME-TO:, except the text denotes the name of a directory to
  1588. which successfully downloaded files are to be moved.  If the directory does
  1589. not exist, it is created.
  1590. </dl>
  1591. <p>
  1592. The file transfer display does not show the /MOVE-TO or /RENAME-TO value,
  1593. since the incoming file has not yet been moved or renamed.
  1594.  
  1595. <h3><a name="x3.6.2">3.6.2. Filename Collisions</a></h3>
  1596.  
  1597. What should happen if an incoming file has the same name as an existing file
  1598. in the same directory?  By default, Kermit's FILE COLLISION setting applies:
  1599. BACKUP, RENAME, UPDATE, DISCARD, etc, as described in <a href="ck60manual.html"><cite>Using C-Kermit</cite></a>.
  1600. Kermit's default FILE COLLISION setting is BACKUP (rename the existing file
  1601. and store the incoming file under its own name) and therefore this is also the
  1602. default FTP collision action.
  1603. <p>
  1604. The name under which an incoming file is to be stored is determined as
  1605. follows:
  1606. <p><ul>
  1607. <li>If an as-name was given, the as-name is used.  Otherwise:
  1608. <p>
  1609. <li>If the client and server platforms are alike or FTP FILENAMES is set to
  1610.    LITERAL (or the /FILENAMES:LITERAL switch was given for this download),
  1611.    the incoming filename is used literally.  Otherwise:
  1612. <p>
  1613. <li>The incoming filename is converted to a form that is friendly to the
  1614.    local platform.  For UNIX, for example, incoming filenames that are all
  1615.    uppercase (as they might be from, say, VMS or an IBM mainframe) are
  1616.    converted to lowercase.
  1617. </ul><p>
  1618. If the resulting name coincides with the name of a local file that already
  1619. exists, we have a filename collision.  Collisions are handled according to
  1620. the currently selected collision action:
  1621. <p>
  1622. <dl>
  1623. <dt><tt><b>SET FTP COLLISION</b> <i>{</i> <b>BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE</b> <i>}</i></tt></dt>
  1624. <dd>This establishes a filename collision for FTP, separate from the Kermit
  1625. one.  The initial FTP collision setting is inherited from Kermit's FILE
  1626. COLLISION setting when the first FTP command is given, but subsequent changes
  1627. to Kermit's FILE COLLISION setting do not affect the FTP COLLISION setting.
  1628. SHOW FTP tells the current FTP COLLISION setting.
  1629. <p>
  1630. <dt><tt><b>FTP GET /COLLISION:</b><i>{</i><b>BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE</b><i>}</i></tt></dt>
  1631. <dd>Overrides the current FTP COLLISION action for this download only.
  1632. <p>
  1633. <dt><tt><b>FTP GET /UPDATE</b></tt></dt>
  1634. <dd>This is equivalent to GET /COLLISION:UPDATE, and is included for symmetry
  1635. with PUT /UPDATE
  1636. </dl>
  1637. <p>
  1638. FTP GET /UPDATE and /COLLISION:UPDATE mean to download only those files whose
  1639. modification dates on the server are later than those on the client.
  1640. Date-time comparisons are done in Coordinated Universal Time (UTC, GMT, ZULU).
  1641. <p>
  1642. As when uploading, update mode is effective only when used consistently in one
  1643. direction.  When you download a file with FTP, the local file receives the
  1644. current timestamp, not the original file's timestamp.  If you try to FTP GET
  1645. /UPDATE the same file again, it is skipped (as expected) since the local copy
  1646. is newer.  However, if you try to FTP PUT /UPDATE the same file, it is sent
  1647. for the same reason.
  1648. <p>
  1649. (It might be possible to set the downloaded file's date from the server file's
  1650. date but (a) UNIX does not offer the necessary time conversion APIs, and (b)
  1651. FTP protocol offers no mechanism for doing the same thing in the opposite
  1652. direction.)
  1653.  
  1654. <h3><a name="x3.6.3">3.6.3. Recovery</a></h3>
  1655.  
  1656. Recovery is available for downloads too, but there are some differences from
  1657. the uploading case described in <a href="#x3.5.3">Section 3.5.3</a>:
  1658. <p><ul>
  1659. <li>The transfer must be in BINARY mode.  It can not be in text mode, even
  1660.    if the FTP server is on the same kind of platform as Kermit, and even
  1661.    if there is no character-set translation.  The original download must also
  1662.    have been in binary mode.
  1663. <p>
  1664. <li>The FTP server must support the REST ("restart") command.  Unfortunately,
  1665.    this is not a standard command; at this writing, it is described only in
  1666.    an Internet Draft, not an RFC or Internet Standard, but nevertheless it is
  1667.    found in several popular FTP servers, including WU-FTP.
  1668. </ul><p>
  1669. Here's how download recovery works:
  1670. <p><ul>
  1671. <li>Kermit checks for conflicting switches, such as /UPDATE, /COMMAND, or
  1672.    /FILTER.  If /RECOVER is given with these switches an error occurs.
  1673. <p>
  1674. <li>The prevailing transfer mode (SET FTP TYPE) must be BINARY.  If it is not,
  1675.    the /BINARY switch must have been included with the FTP [M]GET command.
  1676. <p>
  1677. If the /RECOVER switch is accepted, then for each selected file:
  1678. <p>
  1679. <li>A SIZE command is sent for the file (using its remote name).  If the
  1680.    reply indicates the file was not found, or the SIZE command was not
  1681.    understood, or any other kind of error, recovery is canceled (i.e. the
  1682.    entire file is downloaded).  Otherwise:
  1683. <p>
  1684. <li>A MDTM (modification time) command is sent for the file.  If a valid
  1685.    reply is received, and the modification time of the remote file is later
  1686.    than that of the local file, recovery is canceled.  Otherwise:
  1687. <p>
  1688. <li>If the sizes of the two files are identical, the file is not sent.
  1689.    Otherwise:
  1690. <p>
  1691. <li>Kermit sends the REST command to the server, indicating the size of the
  1692.    local file.  If the server responds affirmatively, Kermit opens the local
  1693.    file in append mode and appends the incoming data to it.  Otherwise,
  1694.    recovery is canceled and the entire file is downloaded.
  1695. </ul><p>
  1696. The /RECOVER switch can be included with any FTP GET or MGET command, even if
  1697. it specifies a group of files.  This lets you resume an interrupted batch
  1698. transfer from where it left off.  The files that were already completely sent
  1699. are skipped, the file that was interrupted is recovered, and the remaining
  1700. files are uploaded.  BUT... unlike with uploading, where this can be done with
  1701. any mixture of text and binary files, when downloading, it can only be done if
  1702. all the files are binary.
  1703. <p>
  1704. It doesn't matter how the original partial file was downloaded -- FTP, Kermit,
  1705. Zmodem, etc: as long as the preconditions are met, it can be recovered with
  1706. FTP [M]GET /RECOVER, or for that matter also with GET /RECOVER (using Kermit
  1707. protocol).
  1708. <p>
  1709. <p>
  1710. [ <a href="#top"><b>Contents</b></a> ] 
  1711. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  1712. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  1713. [ <a href="index.html"><b>Kermit Home</b></a> ]
  1714. <hr>
  1715. <h3><a name="x3.7">3.7. Translating Character Sets</a></h3>
  1716.  
  1717. A possibly unique feature of Kermit's FTP client is its ability to convert
  1718. character sets when transferring files in text mode, independent of the
  1719. capabilites of the FTP server.  For compatibility with existing FTP clients,
  1720. and because there is a certain performance penalty, Kermit won't do this
  1721. unless you ask for it.  If you enable this feature, you need to inform Kermit
  1722. of the character set (to be) used on the server and in some cases (explained
  1723. below) also the local file character set.  Here are the commands:
  1724.  
  1725. <p>
  1726. <dl>
  1727. <dt><tt><b>SET FTP CHARACTER-SET-TRANSLATION</b> <i>{</i> <b>ON, OFF</b> <i>}</i></tt></dt>
  1728. <dd>Whether to translate character sets when transferring text files with FTP.
  1729.   OFF by default.  Set this to ON to enable character-set translation
  1730.   for subsequent FTP uploads and downloads.
  1731. <p>
  1732. <dt><tt><b>SET FTP SERVER-CHARACTER-SET</b> <i>name</i></tt></dt>
  1733. <dd>Text character set (to be) used by the server.  Most FTP servers are
  1734.   ignorant of character sets, so all translations are done unilaterally by
  1735.   Kermit's FTP client.  This means that when downloading files, you must
  1736.   know in advance the character-set used in the files you are downloading.
  1737.   When uploading, you must specify the character-set to which local text
  1738.   files are to be translated for transmission to the server.  If you SET FTP
  1739.   CHARACTER-SET-TRANSLATION ON but do not specify an FTP SERVER-CHARACTER-SET,
  1740.   UTF8 is used, since this is the new Internet standard international
  1741.   character set; it is upwards compatible with ASCII and it encompasses most
  1742.   most written languages and therefore does not favor any particular group
  1743.   of people, as any other default would do.
  1744. <p>
  1745. <dt><tt><b>SET FILE CHARACTER-SET</b> <i>name</i></tt></dt>
  1746. <dd>This is the regular Kermit (non-FTP-specific) command for identifying the
  1747.   character set (to be) used in local text files.
  1748. </dl>
  1749. <p>
  1750. To reiterate: If you SET FTP CHARACTER-SET TRANSLATION ON but do not specify
  1751. an FTP SERVER-CHARACTER-SET, outbound text files are converted to UTF-8 and
  1752. inbound text files are assumed to be UTF-8.  If this is not appropriate,
  1753. be sure to also specify the desired FTP SERVER-CHARACTER-SET.
  1754.  
  1755. <h3><a name="x3.7.1">3.7.1. Character Sets and Uploading</a></h3>
  1756.  
  1757. Kermit's PUT and MPUT commands include full file-scanning capabilities, as
  1758. described in 
  1759. <a href="#x4">Section 4</a>.
  1760. Thus if FTP CHARACTER-SET-TRANSLATION is ON and your
  1761. character-set associations are set up appropriately, Kermit automatically
  1762. switches on a per-file basis between text and binary mode, and for each text
  1763. file between your chosen 7-bit text character set (e.g. ASCII or ISO 646
  1764. German), 8-bit text (e.g. Latin-1 or Japanese EUC), UCS-2, and UTF-8, and
  1765. converts each of these automatically to the server character-set, and
  1766. furthermore automatically differentiates between the Little and Big Endian
  1767. forms of UCS-2, always sending in Big Endian form.
  1768. <p>
  1769. FTP character-set translations differ from the regular Kermit ones by not
  1770. restricting translations to a file-character-set / transfer-character-set pair.
  1771. You can have Kermit's FTP client translate between any pair of character sets
  1772. it knows about.  You can see the list of supported character sets by typing
  1773. either of the following:
  1774. <p><pre>
  1775.   set ftp server-character-set ?
  1776.   set file character-set ?
  1777. </pre><p>
  1778. A typical list looks like this:
  1779. <p><pre>
  1780.   C-Kermit>set file char ? One of the following:
  1781.    ascii            cp869-greek       hebrew-7         mazovia-pc
  1782.    british          cyrillic-iso      hebrew-iso       next-multinational
  1783.    bulgaria-pc      danish            hp-roman8        norwegian
  1784.    canadian-french  dec-kanji         hungarian        portuguese
  1785.    cp1250           dec-multinational iso2022jp-kanji  shift-jis-kanji
  1786.    cp1251-cyrillic  dg-international  italian          short-koi
  1787.    cp1252           dutch             jis7-kanji       spanish
  1788.    cp437            elot927-greek     koi8             swedish
  1789.    cp850            elot928-greek     koi8r            swiss
  1790.    cp852            euc-jp            koi8u            ucs2
  1791.    cp855-cyrillic   finnish           latin1-iso       utf8
  1792.    cp858            french            latin2-iso
  1793.    cp862-hebrew     german            latin9-iso
  1794.    cp866-cyrillic   greek-iso         macintosh-latin
  1795.   C-Kermit>
  1796. </pre><p>
  1797. Thus you can translate not only between private sets (like PC code pages) and
  1798. standard ones (like Latin-1) as in regular Kermit, but also between any given
  1799. pair of private sets (e.g. CP852 and Mazovia).  All conversions go through
  1800. Unicode as the intermediate character set, resulting in a minimum of character
  1801. loss, since Unicode is a superset of all other character sets known to Kermit.
  1802. <p>
  1803. In addition to the SET commands listed above, the FTP PUT and MPUT commands
  1804. include switches that apply only to the current command:
  1805. <p>
  1806. <dl>
  1807. <dt><tt><b>/LOCAL-CHARACTER-SET:</b><i>name</i></tt></dt>
  1808. <dt><tt><b>/SERVER-CHARACTER-SET:</b><i>name</i></tt></dt>
  1809. <dd>Use these switches to force a particular translation.  These switches
  1810. override the global FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET
  1811. settings and also character-set differentiation by file scanning for the
  1812. duration of the PUT or MPUT command.  The file scan is still performed,
  1813. however, to determine whether the file is text or binary; thus these
  1814. switches do not affect binary files unless you also include the /TEXT
  1815. switch to force all files to be treated as text.
  1816. </dl>
  1817. <p>
  1818. In other words, if you include one or both of these switches with a PUT or
  1819. MPUT command, they are used.  Similarly, the /TRANSPARENT switch disables
  1820. character-set translation for the PUT or MPUT command despite the prevailing
  1821. FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET settings.
  1822. <p>
  1823. When uploading, the FILE CHARACTER-SET setting is ignored unless you have
  1824. forced Kermit not to scan local files (see <a href="#x4">Section 4</a>).
  1825. Examples:
  1826. <p>
  1827. Suppose you have a CP852 (East European) text file that you want to upload
  1828. and store in ISO Latin Alphabet 2 encoding:
  1829. <p><pre>
  1830.   ftp put /local-char:cp852 /server-char:latin2 magyar.txt
  1831. </pre><p>
  1832. Suppose you always want your text files converted to Latin-2 when uploading
  1833. with FTP.  Then put:
  1834. <p><pre>
  1835.   set ftp server-character-set latin2
  1836. </pre><p>
  1837. in your Kermit customization file, and then you can omit the
  1838. /SERVER-CHARACTER-SET: switch from your FTP PUT commands:
  1839. <p><pre>
  1840.   ftp put /local-char:cp852 magyar.txt
  1841. </pre><p>
  1842. Now suppose that all the text files on your PC are written in Hungarian, but
  1843. they have a variety of encodings, and you don't want to have to include the
  1844. /LOCAL-CHARACTER-SET: switch on every FTP PUT command, or (more to the point)
  1845. you want to be able to send a mixture of these files all at once.  Put these
  1846. commands in your Kermit customization file:
  1847. <p><pre>
  1848.   set ftp server-character-set latin2            ; ISO 8859-2
  1849.   set file default 7-bit-character-set hungarian ; ISO 646 Hungarian
  1850.   set file default 8-bit-character-set cp852     ; PC East European Code Page
  1851. </pre><p>
  1852. and now PUT and MPUT will automatically detect and switch among ISO 646
  1853. Hungarian, Code Page 852, UTF-8, and UCS-2 encodings, translating each one
  1854. to Latin-2 for uploading:
  1855. <p><pre>
  1856.   ftp put *.txt
  1857. </pre><p>
  1858. And since binary files are also detected automatically, this can be
  1859. simplified to:
  1860. <p><pre>
  1861.   ftp put *
  1862. </pre><p>
  1863. even when "*" matches a diverse collection of binary and text files, because
  1864. translations are skipped automatically for binary files.
  1865.  
  1866. <h3><a name="x3.7.2">3.7.2. Character Sets and Downloading</a></h3>
  1867.  
  1868. The commands and switches are the same as for uploading, but remember there
  1869. is no automatic text/binary switching during downloading, and there is also
  1870. no automatic character-set switching.  Whatever selections you make for a
  1871. particular GET or MGET command apply to all the files that are downloaded by
  1872. that command.  Example:
  1873. <p><pre>
  1874.   mget /text /server:latin1 /local:utf8 *.txt
  1875. </pre><p>
  1876. This command:
  1877. <p><ul>
  1878. <li>Tells C-Kermit that the server's files are encoded in ISO 8859-1
  1879. Latin Alphabet 1.
  1880. <li>Tells C-Kermit to translate the incoming files into Unicode UTF-8 for
  1881. storage.
  1882. <li>Asks the server to send all "<tt>.txt</tt>" files in text mode.
  1883. </ul>
  1884.  
  1885. <h3><a name="x3.7.3">3.7.3. RFC2640</a></h3>
  1886.  
  1887. <a href="ftp://ftp.isi.edu/in-notes/rfc2640.txt"> RFC2640</a>, July 1999,
  1888. specifies a method by which the FTP client and server can negotiate the use of
  1889. UTF8.  However, RFC2640-capable servers are rare to nonexistent at this
  1890. writing, and in any case you don't need them to be able to transfer text in
  1891. UTF8.  C-Kermit lets you upload and download text files in any character set
  1892. it knows about, converting to or from any other character set it knows about,
  1893. without the knowledge, permission, or cooperation of the server, and
  1894. regardless of its capabilities.
  1895.  
  1896. <p>
  1897. [ <a href="#top"><b>Contents</b></a> ] 
  1898. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  1899. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  1900. [ <a href="index.html"><b>Kermit Home</b></a> ]
  1901. <hr>
  1902. <h3><a name="x3.8">3.8. FTP Command Shortcuts</a></h3>
  1903.  
  1904. C-Kermit's FTP client coexists with other C-Kermit functions by requiring the
  1905. "ftp" prefix for each FTP-related command: FTP OPEN, FTP GET, FTP BYE, and so
  1906. on.  For interactive use, however, this can be rather awkward and sometimes
  1907. surprising, for example when a GET command starts a Kermit GET rather than an
  1908. FTP GET.  In fact, many Kermit commands might just as easily apply to an FTP
  1909. connection: GET, PUT (SEND), BYE, and CLOSE.  The following command lets you
  1910. choose how these commands are interpreted:
  1911. <p>
  1912. <dl>
  1913. <dt><tt><b>SET GET-PUT-REMOTE</b> <i>{</i> <b>AUTO, KERMIT, FTP</b> <i>}</i></tt></dt>
  1914. <dd>Controls the orientation of GET, PUT, REMOTE and other file-transfer and
  1915.   client/server commands that might apply to either Kermit or FTP.  The
  1916.   default setting is AUTO, meaning that these commands apply to FTP if an
  1917.   FTP connection is open, and to Kermit otherwise.  KERMIT means they always
  1918.   apply to Kermit, FTP means they always apply to FTP.
  1919. </dl>
  1920. <p>
  1921. Here is a complete list of affected commands:
  1922. <p><pre>
  1923.  <u>Kermit Command</u>               <u>FTP Equivalent</u>
  1924.   (none)                       FTP <i>[</i> OPEN <i>]</i>
  1925.   LOGIN                        FTP USER
  1926.   LOGOUT                       FTP RESET
  1927.   BYE                          FTP BYE
  1928.   FINISH                       FTP BYE
  1929.   CLOSE                        FTP BYE
  1930.   HANGUP                       FTP BYE
  1931.   BINARY                       FTP TYPE BINARY
  1932.   TEXT (or ASCII)              FTP TYPE ASCII
  1933.   SEND (or PUT)                FTP PUT
  1934.   MSEND (or MPUT)              FTP MPUT
  1935.   RESEND                       FTP PUT /RECOVER
  1936.   CSEND                        FTP PUT /COMMAND
  1937.   GET                          FTP GET
  1938.   MGET                         FTP MGET
  1939.   REGET                        FTP GET /RECOVER
  1940.   REMOTE HELP      (RHELP)     FTP HELP
  1941.   REMOTE CD        (RCD)       FTP CD (CWD)
  1942.   REMOTE PWD       (RPWD)      FTP PWD
  1943.   REMOTE DIRECTORY (RDIR)      FTP DIRECTORY
  1944.   REMOTE DELETE    (RDEL)      FTP DELETE
  1945.   REMOTE MKDIR     (RMKDIR)    FTP MKDIR
  1946.   REMOTE RMDIR     (RRMDIR)    FTP RMDIR
  1947.   REMOTE RENAME    (RRENAME)   FTP RENAME
  1948.   REMOTE TYPE      (RTYPE)     FTP TYPE
  1949.   REMOTE EXIT      (REXIT)     FTP BYE
  1950. </pre>
  1951. <p>
  1952. The commands in the right-hand column always access FTP.  The commands in
  1953. the left column can access either Kermit protocol or FTP:
  1954. <p><ul>
  1955. <li>When GET-PUT-REMOTE is set to KERMIT, or to AUTO when there is no FTP
  1956.    connection, the commands in the left-hand column access Kermit protocol,
  1957.    and those right-hand column are required for FTP.
  1958. <p>
  1959. <li>When GET-PUT-REMOTE is set to FTP, or to AUTO when there is an active FTP
  1960.    connection, the commands in the left-hand column access the FTP connection
  1961.    and can not be used to access Kermit protocol.  In this case, if you want
  1962.    to be able to use both Kermit protocol and the FTP connection, you must SET
  1963.    GET-PUT-REMOTE KERMIT, and then use the FTP commands in the right-hand
  1964.    column to access the FTP connection.
  1965. </ul><p>
  1966. Note that file-management commands such as DIRECTORY, DELETE, CD, PWD, MKDIR,
  1967. RMDIR, HELP, RENAME, COPY, TYPE, and so on, always apply locally, no matter
  1968. what kind of connection you have.  This is the opposite of most FTP clients,
  1969. where these commands are intended for the server, and require an "L" prefix
  1970. for local execution (e.g. "dir" gets a directory listing from the server,
  1971. "ldir" gets a local directory listing).  To illustrate with the CD command
  1972. and a typical UNIX FTP client:
  1973. <p><pre>
  1974.  <u>Client</u>   <u>Server</u>      <u>Change Local Directory</u>     <u>Change Remote Directory</u>
  1975.   FTP      FTP         lcd                        cd (cwd)
  1976.   Kermit   Kermit      cd                         rcd, remote cd
  1977.   Kermit   FTP         cd                         ftp cd, rcd, remote cd
  1978. </pre><p>
  1979. Also note that not all REMOTE commands are useful with FTP, since FTP servers
  1980. do not offer the corresponding functions.  These include:
  1981. <p><pre>
  1982.   REMOTE ASSIGN  - FTP servers don't have variables
  1983.   REMOTE COPY    - FTP servers don't copy files
  1984.   REMOTE HOST    - FTP servers don't execute host (shell) commands
  1985.   REMOTE KERMIT  - FTP servers don't execute Kermit commands
  1986.   REMOTE PRINT   - FTP servers don't print files
  1987.   REMOTE QUERY   - FTP servers don't have variables
  1988.   REMOTE SET     - FTP servers don't have Kermit settings
  1989.   REMOTE WHO     - FTP servers don't send user lists
  1990. </pre><p>
  1991. <p>
  1992. [ <a href="#top"><b>Contents</b></a> ] 
  1993. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  1994. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  1995. [ <a href="index.html"><b>Kermit Home</b></a> ]
  1996. <hr>
  1997. <h3><a name="x3.9">3.9. Dual Sessions</a></h3>
  1998.  
  1999. You can have an FTP session open at the same time as a regular Kermit SET
  2000. LINE or SET HOST session.  In this case, the default SET GET-PUT-REMOTE AUTO
  2001. setting should ensure that all "two-faced" commands like GET, PUT, REMOTE,
  2002. HANGUP, BYE, etc, apply to the Kermit session, and all commands for the FTP
  2003. session must include the FTP prefix.  To be absolutely certain, you can use
  2004. SET GET-PUT-REMOTE KERMIT.
  2005. <p><pre>
  2006.   ftp foo.bar.baz.com
  2007.   if fail ...
  2008.   (log in)
  2009.   set host foo.bar.baz.com
  2010.   if fail ...
  2011.   (log in)
  2012. </pre><p>
  2013. Now you have both an FTP and Telnet connection to the same host (of course
  2014. they could also be to different hosts, and you could also have a direct or
  2015. dialed serial connection instead of a Telnet connection).  Now assuming you
  2016. have a Kermit server on the far end of the Kermit connection:
  2017. <p><pre>
  2018.   rcd incoming      ; Changes Kermit server's directory (= REMOTE CD)
  2019.   ftp cd incoming   ; Changes FTP server's directory
  2020.   put oofa.txt      ; Sends a file on the Kermit connection
  2021.   ftp put oofa.txt  ; Sends a file on the FTP connection
  2022.   bye               ; Shuts down the Kermit connection
  2023.   ftp bye           ; Shuts down the FTP connection
  2024. </pre><p>
  2025. Note that PUT and SEND are synonyms for both FTP and Kermit connections.
  2026. <p>
  2027. You can also establish dual sessions on the Kermit command line:
  2028. <p><pre>
  2029.   kermit -j host1 -9 host2
  2030. </pre><p>
  2031. This makes a Telnet connection to host1 and an FTP connection to host2.
  2032. <p>
  2033. [ <a href="#top"><b>Contents</b></a> ] 
  2034. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  2035. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  2036. [ <a href="index.html"><b>Kermit Home</b></a> ]
  2037. <hr>
  2038. <h3><a name="x3.10">3.10. Automating FTP Sessions</a></h3>
  2039.  
  2040. Most of Kermit's scripting features can be used to make and control FTP
  2041. sessions: FOR and WHILE loops, IF-ELSE and SWITCH constructions, variables,
  2042. arrays, built-in functions, and all the rest.  You can't use INPUT, MINPUT,
  2043. OUTPUT, CLEAR, or SCRIPT on an FTP session, but these are not needed since
  2044. the FTP protocol is well defined.
  2045.  
  2046. <h3><a name="x3.10.1">3.10.1. FTP-Specific Variables and Functions</a></h3>
  2047.  
  2048. The following variable tells whether an FTP connection is open:
  2049. <p><dl>
  2050. <dt><tt><b>\v(ftp_connected)</b></tt></dt>
  2051. <dd>1 if there is an active FTP connection, 0 if there isn't.
  2052. </dl>
  2053. <p>
  2054. The FTP OPEN command sets:
  2055. <p><dl>
  2056. <dt><tt><b>\v(ftp_host)</b></tt></tt>
  2057. <dd>The host to which the most recent FTP connection was made.
  2058. <p>
  2059. <dt><tt><b>\v(ftp_server)</b></tt></tt>
  2060. <dd>The OS type (UNIX, VMS, etc) of the FTP server host.
  2061. <p>
  2062. The FTP USER command (or FTP OPEN /USER:, or FTP with automatic login) sets:
  2063. <p>
  2064. <dt><tt><b>\v(ftp_loggedin)</b></tt></tt>
  2065. <dd>1 if you are logged in to an FTP server, 0 if you are not.
  2066. </dl>
  2067. <p>
  2068. plus the following, which apply to Kermit's secure authentication methods:
  2069. <p><pre>
  2070.  \v(authtype)     Name of secure authentication method used, if any.
  2071.  \v(authname)     Username for which secure authentication was obtained.
  2072.  \v(authstate)    User, Valid, Rejected, Other, or Unknown.
  2073. </pre>
  2074. <p>
  2075. The FTP GET-PUT-REMOTE setting is reflected in:
  2076. <p><pre>
  2077.  \v(ftp_getputremote)
  2078. </pre><p>
  2079. Every FTP command sets the \v(success) variable, as well as the following
  2080. two FTP-specific variables: 
  2081. <p><dl>
  2082. <dt><tt><b>\v(ftp_code)</b></tt></tt>
  2083. <dd>The standardized numeric FTP protocol code from the server's response 
  2084. to the last client command, a 3-digit decimal number defined in
  2085. <a href="ftp://ftp.isi.edu/in-notes/rfc959.txt"> RFC959</a>.
  2086. Briefly:
  2087. <p><pre>
  2088. 1xx = Positive Preliminary Reply
  2089. 2xx = Positive Completion Reply
  2090. 3xx = Positive Intermediate Reply
  2091. 4xx = Transient Negative Completion Reply
  2092. 5xx = Permanent Negative Completion Reply
  2093. </pre>
  2094. <p>
  2095. <dt><tt><b>\v(ftp_msg)</b></tt></tt>
  2096. <dd>The text message, if any, from the server's response to the last
  2097. client command.  If the most recent response had multiple lines,
  2098. this variable has only the final line.  These messages are not
  2099. standardized and vary in format and content from server to server.
  2100. </dl>   
  2101. FTP file transfers set the regular Kermit transfer status variables:
  2102. <p><pre>
  2103.   \v(cps)         Characters per second of most recent transfer.
  2104.   \v(filespec)    File specification used in most recent transfer.
  2105.   \v(fsize)       Size of file most recently transferred.
  2106.   \v(tfsize)      Total size of file group most recently transferred.
  2107.   \v(xferstatus)  Status of most recent transfer (0 = success, 1 = failure).
  2108.   \v(tftime)      Elapsed time of most recent transfer, in seconds.
  2109. </pre><p>
  2110. During an FTP transfer, the per-file variables are:
  2111. <p><pre>
  2112.   \v(filename)    Name of current file.
  2113.   \v(filenumber)  Ordinal file number in group (1, 2, 3, ...)
  2114. </pre><p>
  2115. *** Macros to bundle settings for different servers ***
  2116.  
  2117. <h3><a name="x3.10.2">3.10.2. Examples</a></h3>
  2118.  
  2119. Let's begin with a simple example showing how to log in, send some files,
  2120. and log out:
  2121. <p><pre>
  2122.   define error if fail { ftp bye, stop 1 Error: \%1 }
  2123.   set transact brief
  2124.   log t
  2125.   ftp ftp.xyzcorp.com /anonymous
  2126.   if fail stop 1 Connection failed
  2127.   if not \v(ftp_loggedin) stop 1 Login failed
  2128.   ftp cd incoming
  2129.   error {ftp cd}
  2130.   cd upload
  2131.   error {local cd}
  2132.   ftp put /delete *
  2133.   error {put}
  2134.   ftp bye
  2135. </pre><p>
  2136. First we define an error handling macro to be used after the connection is
  2137. made.  Then we set up a brief-format transaction log to keep a record of our
  2138. file transfers.  Then we make a connection to the host and log in anonymously.
  2139. The "if fail" command checks whether the connection was made.  The "if not"
  2140. command checks whether login was successful.  Obviously the script should not
  2141. continue unless both tests succeed.
  2142. <p>
  2143. Next we change to the server's 'incoming' directory and to our own 'upload'
  2144. directory, and send all the files that are in it (they can be any mixture of
  2145. text and binary files), deleting each source file automatically after it is
  2146. successfully uploaded.  Each of these operations is checked with the ERROR
  2147. macro, which prevents the script from continuing past a failure.
  2148. <p>
  2149. Finally we close the FTP session with the "bye" command.
  2150. <p>
  2151. Just like any other Kermit script, this one can be used in many ways:
  2152. <p><ul>
  2153. <li>It can be stored in a file, and Kermit can be told to TAKE the file.
  2154. <li>In UNIX, it can be a "kerbang" script and therefore run directly from
  2155. the shell prompt or as a cron job.
  2156. </ul><p>
  2157. We could have used command shortcuts like "rcd", "put", and "bye", but since
  2158. they can be ambiguous under certain circumstances, it is better to avoid them
  2159. in scripts; they are intended mainly for convenience during interactive use.
  2160. However, if you wish to use the shortcuts in a script, you can do it this way
  2161. (error handling omitted for brevity):
  2162. <p><pre>
  2163.   local \%t                       ; Declare a local temporary veriable
  2164.   assign \%t \v(ftp_getputremote) ; Save current FTP GET-PUT-REMOTE setting
  2165.   set ftp get-put-remote ftp      ; Choose FTP orientation
  2166.   ftp xyzcorp.com /anonymous      ; Open an FTP connection
  2167.   get oofa.txt                    ; GET a file
  2168.   put foo.bar                     ; PUT a file
  2169.   rdel yesterday.log              ; Delete a file on the server
  2170.   bye                             ; Log out and disconnect from server.
  2171.   set ftp get-put-remote \%t      ; Restore previous GET-PUT-REMOTE setting
  2172. </pre><p>
  2173. Of course, FTP scripts can also be written as macros.  This lets you pass
  2174. parameters such as hostnames, usernames, and filenames to them:
  2175. <p><pre>
  2176.   define doftpget {
  2177.       if < \v(argc) 4 end 1 Usage: \%0 host user remotefile [ localfile ]
  2178.       ftp \%1 /user:\%2
  2179.       if fail end 1 FTP OPEN \%1 failed
  2180.       if not \v(ftp_loggedin) end 1 FTP LOGIN failed
  2181.       ftp get {\%3} {\%4}
  2182.       if fail end 1 FTP GET \%3 failed
  2183.       ftp bye
  2184.   }
  2185. </pre><p>
  2186. Add this definition to your Kermit customization file, and it will always
  2187. be available when you start Kermit (unless you start it in a way that bypasses
  2188. the normal initialization file).  This macro lets you download a file with FTP
  2189. by giving a single command, e.g.:
  2190. <p><pre>
  2191.   doftpget xyzcorp.com anonymous oofa.txt
  2192. </pre>
  2193. <p>
  2194. <a href="ftpscript.html">CLICK HERE</a> to visit the Kermit FTP script-writing
  2195. tutorial.
  2196. <p>
  2197. [ <a href="#top"><b>Contents</b></a> ] 
  2198. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  2199. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  2200. [ <a href="index.html"><b>Kermit Home</b></a> ]
  2201. <hr>
  2202. <h3><a name="x3.11">3.11. Advanced FTP Protocol Features</a></h3>
  2203.  
  2204. FEAT and NLST are not supported by C-Kermit since they are not yet
  2205. standardized, nor can they be found in most FTP servers at this writing.
  2206. Similarly for the various mail-sending options.
  2207. <p>
  2208.  
  2209. [ <a href="#top"><b>Contents</b></a> ] 
  2210. [ <a href="ck71.html"><b>C-Kermit 7.1</b></a> ]
  2211. [ <a href="ckermit.html"><b>C-Kermit Home</b></a> ]
  2212. [ <a href="index.html"><b>Kermit Home</b></a> ]
  2213. <hr>
  2214. <address>
  2215. The Kermit Project / Columbia University / <a href="mailto:kermit@columbia.edu">kermit@columbia.edu</a> / 14 December 2000
  2216. </address>
  2217. </body>
  2218. </html>
  2219.