Robo-FTP is built around a powerful script language that permits a wide range of FTP file transfer applications to be automated. While the script language is powerful enough to handle many complex file transfer situations, it is also relatively simple to produce scripts to handle basic FTP uploads and downloads. The purpose of this web page is to introduce you to the basic steps used to produce a simple script and help you understand the concepts of the Robo-FTP script language.
Analysis of a Simple Script
For the purposes of this introduction, we will be creating a script to log on to a FTP server, upload a file, and then disconnect. Scripts are saved in text files that are usually created and edited with the supplied Robo-EDIT Script File Editor, but any other text editor (such as Windows NotePad) may be used. Robo-EDIT has the advantage of recognizing keywords and doing attractive syntax highlighting.
Script files are normally named using a .s file name extension. For example: MyScript.s.
The more than 100 Robo-FTP script commands are documented more fully in the help file provided with the product. Basic scripts usually fall into a simple structure like this:
Connect to the FTP server
Upload and/or download file(s)
Disconnect from the server
More complex scripts might loop to repeat one or more of the operations; do extended operations such as sending e-mail messages, encrypting/decrypting PGP files, copying or deleting local files; and will include error detection to catch any connection or file transfer errors and possibly take appropriate recovery steps (e.g., resend a file).
We're going to have you jump in with both feet right off the bat by showing you a complete script file that does the log on, send file, and log off operations that we mentioned above. Here it is:
;; Robo-FTP Script File
;; Created by Serengeti Systems Incorporated. On Mon. August 23, 2004
;;
;; Description: This script will log on to a server, upload a file, then disconnect.
;;
FTPLOGON "ftp.myserver.com"
IFERROR= $ERROR_SUCCESS GOTO TimeToSend
STOP
:TimeToSend
SENDFILE "test.txt" /timeout=30
FTPLOGOFF
EXIT
Now just follow along below for a break-down of how the script works.
;; Robo-FTP Script File
;; Created by Serengeti Systems Incorporated On Mon. August 23, 2004
;;
;; Description: This script will log on to a server, upload a file, then disconnect.
;;
It is common practice to include comments at the top of a script file to describe what it does, when it was created, etc. so we started by adding comment lines at the top of the file with information regarding date, author, and description of the script. Any lines that begin with a semi-colon (;) are comments which are ignored by the Robo-FTP script processor. White-space is also ignored, so you may use blank lines, spaces, and tabs to space out commands and add comments in order to make a script more humanly readable.
FTPLOGON "ftp.myserver.com"
This line specifies the FTPLOGON script command to log onto the FTP server. In this example, the server is called "ftp.myserver.com". When the FTPLOGON command is used like this, Robo-FTP expects that the log on information about this site (i.e., the user name and password) have been previously saved using the Manage Sites tab in the Robo-FTP Configurator.
The user name and password can also be specified explicitly in the FTPLOGON command using command options. In that case, the command might look like this:
FTPLOGON "ftp.myserver.com" /user=username /pw=password
More on command options later. If the site has not been pre-defined or if the appropriate options are not included in the command, the user will be prompted for user name and password.
IFERROR= $ERROR_SUCCESS GOTO TimeToSend
This line does an error check to make sure that there were no errors during the logon process. This also introduces an example of branching, which is common in Robo-FTP script programming. If there were no errors, flow is transferred to the label TimeToSend (as indicated by the command GOTO with the label TimeToSend). If there was an error in the logon process, the flow is continued on the next line.
STOP
The STOP command ends script processing. We have placed this command immediately after checking to see if a log on error had occurred -- if so, script execution simply stops. This is not something that you'd probably want to do in a real world production environment (you'd more likely retry the log on, send an e-mail failure notification, etc. in an attempt to recover from the error) but this suffices for our simple example script.
:TimeToSend
Any lines that begin with a colon (:) are labels. Labels are used in conjunction with branching commands (e.g., LOOP, GOTO). This line contains the label TimeToSend which is where script processing resumes after a successful log on.
SENDFILE "test.txt" /timeout=30
This line sends the file "test.txt". Included is an optional time-out switch indicated by the '/'. In this example, there is a timeout of 30 seconds. This time-out results in an error being reported if Robo-FTP cannot begin uploading the file within 30 seconds.
FTPLOGOFF
This script command performs a log off and terminates the connection with a FTP server.
EXIT
This script command ends script processing and terminates Robo-FTP.
There are many more commands available. Consult the Robo-FTP help file for a complete list of commands as well as more details and examples involving the commands used in this script.