IFERROR        Test result code and conditionally branch to label

Top  Previous  Next

Syntax:

IFERRORxx

[ rcode ]  [ action ]  [ label ]

Forms:

IFERROR

[ rcode ] [ action ]  [ label ]

 

IFERROR=

[ rcode ] [ action ]  [ label ]

 

IFERROR<

[ rcode ] [ action ]  [ label ]

 

IFERROR>

[ rcode ] [ action ]  [ label ]

 

IFERROR<=

[ rcode ] [ action ]  [ label ]

 

IFERROR>=

[ rcode ] [ action ]  [ label ]

 

IFERROR!=

[ rcode ] [ action ]  [ label ]

Arguments:

[ rcode ]

Optional numeric value or $ERROR variable associated with result codes returned by script commands upon completion; any successful operation returns a value of 0. If unspecified, rcode defaults to 0.

 

[ action ]

Optional action if the test of the previously executed command's error code evaluates to true. Support values are: GOTO, LOOPTO, and RETURN. If not provided, a default value of GOTO is assumed.

 

[ label ]

A valid label within the current script file which is branched to if the conditional test is successful.

Options:

none

 

 

This script command checks the result of the previously executed command to see if IFERRORxx [ rcode ] is true. If so, the script file branches to [ label ], otherwise execution continues with the next command. The following variations of the IFERROR command are supported:

 

IFERROR= (equal to)
IFERROR< (less than)
IFERROR> (greater than)
IFERROR<= (less than or equal to)
IFERROR>=(greater than or equal to)
IFERROR!= (not equal to)
IFERROR (not equal to - alternate syntax)

 

Syntactically, no space is permitted to the left of the ‘!’, '=', '<' or '>' symbols, and a space is required to the right of these symbols.

 

Consider the following example where execution branches to the :next label if the result code is greater than 1046:

 

IFERROR> 1046 GOTO next

 

In the following example execution branches to the :halt_error label if the result code indicates any error (non-zero result):

 

IFERROR!= $ERROR_SUCCESS GOTO halt_error

 

The [ rcode ] may be omitted if you do not wish to test for a specific error condition, in which case an implicit value of 0 is assumed. The next example is functionally equivalent to the previous example:

 

IFERROR GOTO halt_error  ; equivalent to IFERROR!= $ERROR_SUCCESS GOTO halt_error

                        ; note that $ERROR_SUCCESS is equal to 0

 

The usefulness of the IFERROR command extends beyond simple error handling. In the following example, we construct a simple download loop by using IFERROR to catch a specific result code returned by the FTPGETFILE command that indicates there are no more files. In this case we are determining when to exit the loop rather than reacting to an error condition:

 

:fetch_file

FTPGETFILE "*"

IFERROR= $ERROR_NO_FILE_FOUND GOTO no_more_files

RCVFILE %sitefile

GOTO fetch_file

:no_more_files

 

 

Related command(s): LOOPIF, GOTO

See also: Simple Error Handling Example, Script File Result Codes, %lasterror, Fault Tolerant Scripts