RFtp PRO Advanced Usage
Advanced Usage
- Everything you wanted to know about the Command Line Interface (CLI)
- Beyond CLI: Return Codes
- What can I do with an RFtp Shortcut?
Everything you wanted to know about the Command Line Interface (CLI)
The CLI allows you to perform file transfer operations without having to interact with the RFtp PRO graphical interface. In fact, you don't even have to be at your computer to use it!
In the simple case, RFtp PRO is started via a menu entry or a desktop shortcut, and doesn't need any "command line" options or parameters. And you get an ordinary "interactive" FTP session. BUT, there is another way. Through the use of defined command line options and parameters, you can, for instance, cause RFtp PRO to start, connect to a remote FTP server, download (or upload) an arbitrary number of files, and finally, to logoff from the remote site and exit the program!
To clarify how one would actually use this facility, it would most likely be in one of the following ways:
- from a batch or cmd file (or script)
- from the System Agent
- from some sort of executable program, whether it be C[++], VB, or virtually any language/environment that allows you to execute an external program file.
You could, of course, actually use it from a command line (i.e., Command Prompt) interface, but that isn't where its power is (if you have to sit there and interact in real-time anyway, you might as well use normal interactive mode).
While there are a number of ways of using RFtp PRO's CLI, most of them involve supplying a remote site via a URL, optionally specifying a transfer mode and/or a local directory, filename(s), and an "action" command (e.g., GET or PUT). The exception crops up when using the Open command; here, you just give the name of an RFtp Shortcut - the action command is implied, and the URL, local directory, and transfer mode are all supplied (as needed) by the RFtp Shortcut itself.
Here is the syntax for the CLI form you will probably use:
- Transfer
RFtpPro -u <URL> [-d <xfer-dir>] [-x<a|i|x>] [-v] [-z] -<p|g> file-args
This form is not actually used internally by either RFtp PRO or RFtp Shortcuts. You would use it for most of your non-interactive RFtp PRO file transfer tasks, as it handles uploads and downloads of any number of files.
Here are the other valid forms of CLI usage:
- Open
RFtpPro -o <RFtp-Shortcut-name>
Used when you double-click on an RFtp Shortcut, this will open an interactive session to the FTP server identified by the URL contained in the RFtp Shortcut, and [pre-]set any local directory and/or transfer mode optionally specified therein.
- Absolute Upload
RFtpPro -u <URL> [-x<a|i|x>] [-v] [-z] absolute-file-paths
This form is employed, for instance, when you drop files on an RFtp Shortcut. You probably wouldn't use it for your own CLI adventures, since it depends on absolute-file-paths (a file name format mostly encountered when accepting drops from the system Explorer).
- Fetch
RFtpPro -f <full-URL> [-d <download-dir>] [-x<a|i|x>] [-v]
Finally, this last case is used when you select either of the RFtp PRO -related entries ("Paste URL for Download" and "Paste URL for Listing") at the top of the right-click ("context") menu of an RFtp Shortcut. Unless your needs consisted of downloading single files at a time specified by full-URLs, you would be more likely to call on the Transfer form (with the "-g" variant).
What those options and parameters mean:
| Option | Definition / Meaning |
|---|---|
| -u | URL specifier; requires a URL as the next parameter |
| URL | A Uniform Resource Locator (may name a directory or a file) |
| -d | Directory specifier; requires a local directory name as the next parameter |
| xfer-dir | The filesystem path of a [pre-existing] local directory; may be a source or a destination directory, depending on the "action" command |
| -x<a|i|x> | The transfer mode specifier; "-xa" forces ASCII (text) mode, "-xi" forces an Image (binary) transfer, while "-xx" activates the Smart (automatic type detection) facility |
| -v | Enables Update-ONLY transfer control; files will only be transferred if the source file has a date/time stamp later than the destination (the transfer will always take place if there is no corresponding destination file) |
| -z | Enable "extended" return codes (see Beyond CLI: Return Codes) |
| -<p|g> | Transfer "action" command; "-p" makes this a Put (upload) operation, while "-g" means Get (download) |
| file-args | The [individual] source files to transfer in this upload or download operation; a space-separated list of names in the local (upload case) or remote (download case) directory. Note that the names used at the destination will be the same (including character case) |
| -o | Open command; requires an RFtp Shortcut-name as the next parameter |
| RFtp-Shortcut-name | The filesystem path of a [pre-existing] .rftp object |
| absolute-file-paths | A space-separated list of absolute (volume name all the way down to file) path names |
| -f | Fetch "action" command; requires a full-URL as the next parameter |
| full-URL | This is a URL that specifies a single remote file (usually obtained via a Copy Shortcut or a Copy Link Location operation, depending on which Web browser you are using) |
| download-dir | The filesystem path of a [pre-existing] local destination directory |
Fine print:
- It's good practice to enclose each of the entries in a file-args list in double-quotes; that way you don't have to remember to do it for Long File Names containing embedded spaces!
- If a particular URL usage [only] needs a directory, and you supply a full-URL, the file will be ignored and its containing directory used.
- Both the local directory and the transfer mode, if not specified on a command line built by a program or from an RFtp Shortcut, can be determined using non-CLI RFtp PRO rules.
Beyond CLI: Return Codes
Often, when using the CLI, it is desirable to not only perform some FTP operation, but to know whether it was successful... this where return codes come in.
RFtp PRO accumulates status info on various FTP operations during execution, and then presents a structured report (in one of two formats) on the overall session as the application's exit code (returned from WinMain).
The default return codes are useful for making a simple "did it work?" determination - a value of 0 means no errors were encountered, while other values reflect specific failures.
| Bit # | Value | Meaning |
|---|---|---|
| 0 | 1 | 1 or more DOWNLOADS failed |
| 1 | 2 | 1 or more UPLOADS failed |
| 2 | 4 | Unable to LOGIN |
| 3 | 8 | Unable to CONNECT |
The "extended" return codes (obtained via the CLI switch "-z") provide additional information, adding "what worked?" and "what date-dependent operations were skipped?" status to the report. Note that in this format, a value < 16 says "no errors".
| Bit # | Value | Meaning |
|---|---|---|
| 0 | 1 | 1 or more DOWNLOADS succeeded |
| 1 | 2 | 1 or more UPLOADS succeeded |
| 2 | 4 | 1 or more DOWNLOADS skipped (no-UPDATE) |
| 3 | 8 | 1 or more UPLOADS skipped (no-UPDATE) |
| 4 | 16 | 1 or more DOWNLOADS failed |
| 5 | 32 | 1 or more UPLOADS failed |
| 6 | 64 | Unable to LOGIN |
| 7 | 128 | Unable to CONNECT |
Note: 192 (0xC0), or "NO connect + NO login", is reserved for future expansion
What can I do with an RFtp Shortcut?
To appreciate fully what is possible with RFtp Shortcuts, it is useful to understand what they are.
At one level, they are just small data files of type "RFtp Shortcut" (signified by a .rftp extension). While designed to be extensible, they currently contain a URL (for designating an FTP site), a transfer directory (for supplying a local source or destination directory for uploads or downloads respectively), and a transfer mode (applying to transfer operations involving this RFtp Shortcut).
But through the magic of Shell Extension DLLs, they become helpers that assist you with repetitive tasks!
After you have clicked the
on the Host page toolbar (see
Create an RFtp Shortcut),
you have an RFtp Shortcut that only specifies a URL.
This would be useful for double-clicking to Open, for
instance, but it doesn't say anything about a [local] directory or a transfer mode.
Or you might drop files on it to be uploaded to the associated FTP site.
To realize more of the customization possibilities
inherent in an RFtp Shortcut, you need to modify its properties.
Do this by right-clicking on the RFtp Shortcut's
icon and selecting
Properties
in the pop-up menu. At this point, you should see a property sheet dialog.
Select the RFtp Shortcut page, and it should look something like
this:
This particular RFtp Shortcut's name is "ftp.rftp.com Downloads" and it points at the "pub" directory on the "ftp.rftp.com" FTP site. Whenever RFtp PRO is started using this shortcut, it will have its transfer directory set to "d:\tmp" and will have a preset "Smart" (auto-selected) transfer mode. Finally, any transfers initiated using this RFtp Shortcut will only take place if the source is newer than the destination.
How (or whether) you adjust the various attributes of an RFtp Shortcut depends on how you plan to use the shortcut. For the garden-variety opening of interactive FTP sessions to specific servers, you would probably want to set both the transfer directory and transfer mode. For "drop and forget" uploads using a shortcut, the transfer directory setting is less important (since the local directory is always supplied by the absolute-file-paths you dropped).
It's good practice to set a transfer directory anyway, so that a special form of downloading will work in the way you expect; if you happen to have a full-URL in the system clipboard when you right-click an RFtp Shortcut, two new entries will appear on the pop-up menu:
- Paste URL for Download - Connects to the server, downloads the file named by the URL, and automatically does a Logoff and Exit
- Paste URL for Listing - Connects to the server, changes to the remote directory containing the file named by the URL, and generates a directory listing to a local file, followed by a Logoff and Exit