Robo-FTP User's Guide > Script Programming > Select Topics in Script Programming

The best way to ensure that the scripts you write are able to properly respond to unexpected situations is through proper error-handling. Every Robo-FTP command returns an error code, and you can use these error codes to make decisions on whether it is safe to proceed with normal execution of the script, or if it is best to terminate the script at that point and notify the user of an error.

You can use the IFERROR command and its variants to test for any error (IFERROR) or a specific error (IFERROR=) after a command has run. Consider the FTPLOGON command. Imagine a situation where you have written a script to log in to a particular FTP server to upload files. If the initial FTPLOGON command fails, then there is nothing else than can be done. You will be unable to upload any files to the server in question. One course of action is to immediately stop normal execution of the script:

FTPLOGON "mysite" ; on error, %lasterror will be set to the corresponding error code

IFERROR RETURN %lasterror ; IFERROR tests %lasterror for any non-success value and if so, returns it, aborting the script

; ... rest of the script goes here ...

Since oftentimes a script will run in the background as part of a service, this is almost always insufficient. Using the example above, days or weeks could go by without anybody noticing that the server is down and files have not been uploaded. Instead, it might be better to send an email notification if such an error occurs. To do so, we will make use of an error handler, which for our purposes is a section of code that begins with a unique label which we will jump to when an error is encountered:

FTPLOGON "mysite" ; on error, %lasterror will be set to the corresponding error code

IFERROR GOTO logon_failure_handler ; jump to the logon_failure_handler label

; ... rest of the script goes here ...

EXIT $ERROR_SUCCESS

:logon_failure_handler

; ... we will handle the error here ...

Note that in the code above, we have also added an additional line "RETURN $ERROR_SUCCESS". This is used at the end of the normal execution part of a script to terminate it, returning a "success" value of 0 at the same time. Without this line, if every command ran correctly we would still end up continuing on to the next line, which happens to be our error handler. We use this "RETURN $ERROR_SUCCESS" to prevent that from occurring unless we jump there explicitly using GOTO.

Now that we have the basic structure of the script mapped out, we will want to fill out our error handler. The most common situation is to have the script send an email to a responsible party to let them know that their script has encountered an error, and why. To do so, we just use the EMAIL command:

:logon_failure_handler

SET stored_err = %lasterror

SET email_subj = %currentscript + ": Log on error"

SET email_msg = "We could not log on to site 'mysite': " + %lasterrormsg + "[" + %lasterror + "]"

EMAIL email_msg /subject=email_subj ; send an email to the default recipient for

; the default configured SMTP server

EXIT %lasterror ; return any error code given by EMAIL (ideally $ERROR_SUCCESS)

Note: In order to send emails, Robo-FTP must be properly configured with an SMTP server. See the Outbound Email for more information on configuring an SMTP server.

Continuing on with this example, we can create separate error handlers for any commands that we expect may fail, each with their own unique label.

However, it is important to be aware that some commands such as GETNEXTFILE and GETSITEFILE return specific error codes under non-error conditions. For example, for these two commands, the error $ERROR_NO_FILE_FOUND indicates that the files have been fully enumerated. In such a case it is best to place an IFERROR= specific_error_code GOTO label command before we check for a more general error which would send us to an error handler. See below:

:loop_top

GETSITEFILE "*" /next

IFERROR= $ERROR_NO_FILE_FOUND GOTO loop_end

IFERROR GOTO remote_listing_error_handler

GOTO loopx

DISPLAY %sitefile

:loop_end

RETURN $ERROR_SUCCESS

:remote_listing_error_handler

; ...

Error Handling

Error Handling