LOOPIF        Test result code and conditionally branch using looping

This script command performs two or three-way conditional branching based on the result of the previous command and the current value of the LOOPCOUNT counter. The previous operation is considered to have failed when the %lasterror variable contains a non-zero value. The LOOPCOUNT counter value is decremented each time LOOPIF jumps to [ label 1] or any time the LOOPTO command is executed.

This command is most commonly used in three-way mode to implement a "retry loop" that attempts a failed operation several times but eventually fails rather than looping indefinitely. This type of automatic retry loop is especially desirable in command scripts that depend on access to external network resources.

Three-way Branching

When the LOOPCOUNT counter value is greater than zero, the LOOPIF command jumps to [ label1 ] if the previous command failed or to [ label2 ] if the previous command succeeded. If the value of the LOOPCOUNT counter is zero then neither branch is taken and control falls through to the command immediately below the LOOPIF command.

Consider the following where the DIALNET command is repeated up to three times or until it is successful. An email is sent if DIALNET fails three times.

LOOPCOUNT 3

:retry_dial

DIALNET "My Connection"

LOOPIF GOTO retry_dial ELSE GOTO connected

;; dialing failed three times

SET email_body = "Unable to establish dialup connection."

CREATEMAIL "Robo-FTP" "[email protected]" "Upload failed" email_body ""

SENDMAIL "smtp.mydomain.com" "" "[email protected]"

EXIT

:connected

FTPLOGON "ftp.acme-widget.com" /user=anonymous /pw=itchy

SENDFILE "*"

FTPLOGOFF

DISCONNECT

EXIT

Two-way Branching

When LOOPCOUNT is unassigned or explicitly set to zero the LOOPIF command branches to [ label1 ] if the previous command failed or to [ label2 ] if the previous command succeeded. Unlike the three-way branching described above, the number of times the previous command failed does not alter this branching behavior.

Consider the following where the DIALNET command is repeated until it is successful:

LOOPCOUNT 0 ;; error expected

:retry_dial

DIALNET "My Connection"

LOOPIF GOTO retry_dial ELSE GOTO connected

:connected

The example above is functionally equivalent to more common implementation shown in the example below:

:retry_dial

DIALNET "My Connection"

IFERROR!= $ERROR_SUCCESS GOTO retry_dial

:connected

Note: A single LOOPCOUNT counter value is shared by all instances of LOOPTO and LOOPIF that appear in a command script. The LOOPCOUNT command may be called multiple times if necessary to reset the counter.

Related command(s): LOOPCOUNT, LOOPTO, GOTO, IFERROR

See also: Fault Tolerant Scripts