ON - Handle Ctrl-Break and errors in batch files
Purpose: Execute a command in a batch file when a specific condition
occurs.
Format: ON BREAK [command ]
or
ON ERROR [command ]
or
ON ERRORMSG [command ]
Usage
ON can only by used in batch files.
ON sets a "watchdog" that remains in effect for the duration of the
current batch file. Whenever a BREAK or ERROR condition occurs after ON
has been executed, the corresponding command is automatically executed.
ON BREAK will execute the command if the user presses Ctrl-C or
Ctrl-Break.
ON ERROR and ON ERRORMSG will execute the command after any command
processor or operating system error (including critical errors). That
is, they will detect errors such as a disk write error, and CMD.EXE
errors such as a COPY command that fails to copy any files, or the use of
an unacceptable command option.
ON ERROR executes the command immediately after the error occurs, without
displaying any command processor error message (operating system errors
may still be displayed in some cases). ON ERRORMSG displays the
appropriate error message, then executes the command. If both are
specified, ON ERROR will take precedence, and the ON ERRORMSG setting
will be ignored. The remainder of this section discusses both settings
together, using the term "ON ERROR[MSG]".
ON BREAK and ON ERROR[MSG] are independent of each other. You can use
either one, or both, in any batch file.
Each time ON BREAK or ON ERROR[MSG] is used, it defines a new command to
be executed for a break or error, and any old command is discarded. If
you use ON BREAK or ON ERROR[MSG] with no following command, that type of
error handling is disabled. Error handling is also automatically
disabled when the batch file exits.
ON BREAK and ON ERROR[MSG] only affect the current batch file. If you
CALL another batch file, the first batch file's error handling is
suspended, and the CALLed file must define its own error handling. When
control returns to the first batch file, its error handling is
reactivated.
The command can be any command that can be used on a batch file line by
itself. Frequently, it is a GOTO or GOSUB command. For example, the
following fragment traps any user attempt to end the batch file by
pressing Ctrl-C or Ctrl-Break. It scolds the user for trying to end the
batch file and then continues displaying the numbers from 1 to 1000:
on break gosub gotabreak
do i = 1 to 1000
echo %i
enddo
quit
:gotabreak
echo Hey! Stop that!!
return
You can use a command group as the command if you want to execute
multiple commands, for example:
on break (echo Oops, got a break! & quit)
ON BREAK and ON ERROR[MSG] always assume that you want to continue
executing the batch file. After the command is executed, control
automatically returns to the next command in the batch file (the command
after the one that was interrupted by the break or error). The only way
to avoid continuing the batch file after a break or error is for the
command to transfer control to another point with GOTO, end the batch
file with QUIT or CANCEL, or start another batch file (without CALLing
it).
When handling an error condition with ON ERROR[MSG], you may find it
useful to use internal variables, particularly %_? and %_SYSERR, to help
determine the cause of the error.
The ON ERROR[MSG] command will not be invoked if an error occurs while
reading or writing a redirected input file, output file, or pipe.
Caution: If a break or error occurs while the command specified in ON
BREAK or ON ERROR[MSG] is executing, the command will be restarted. This
means you must use caution to avoid or handle any possible errors in the
commands invoked by ON ERROR[MSG], since such errors can cause an
infinite loop.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs