|Purpose:||Execute a command in a batch file when a specific condition occurs|
|Format:||ON BREAK [command]|
ON CLOSE [command]
ON CONDITION [condition command]
ON DBLCLICK [command]
ON ERROR [command]
ON ERRORLEVEL n [command]
ON ERRORMSG [command]
ON LOGOFF [command]
ON LBUTTON [command]
ON MBUTTON [command]
ON RBUTTON [command]
ON RESUME [command]
ON SHUTDOWN [command]
ON SUSPEND [command]
command command to execute when the event occurs
ON sets a watch that remains in effect for the duration of the current batch file, or until replaced by another ON command of the same type. Whenever a break or error condition occurs after ON has been executed, the corresponding command is automatically executed. You can have multiple ON commands active at a time, as long as no two are the same type. (For example, you can have an ON BREAK and an ON CLOSE, but not two ON LBUTTON.)
If the last argument on the line is a single (, it is interpreted as the beginning of a command group. ON will append the following lines (in a batch file) or prompt you for more input (at the command line) until it gets a closing ).
Activation of ON BREAK
ON BREAK will execute command if the user presses Ctrl-C or Ctrl-Break.
Activation of ON CLOSE
ON CLOSE will execute command when the TCC tab is closed.
Activation of ON CONDITION
ON CONDITION will execute command when condition is true. condition can be any test that is valid in IF. The test will be done after each command is executed. If you are executing a loop (DO or FOR), the test will be done each time through the loop.
Activation of ON DBLCLICK
ON DBLCLICK will execute command when the left mouse button is double clicked when TCC is the active window. (Note that if you also have an ON LBUTTON command, it will be executed on the first click.)
Activation of ON ERROR and ON ERRORMSG
ON ERROR or ON ERRORMSG will execute command after any critical error, operating system error (such as a disk write error) or internal command error (such as a COPY command that fails to copy any files, or the use of an invalid command option).
ON ERROR executes command immediately after the error occurs, without displaying any TCC error message (Windows errors may still be displayed). ON ERROR will also set the %_SYSERR internal variable.
ON ERRORMSG first displays the appropriate error message, then executes command.
If both are specified, ON ERROR will take precedence, and ON ERRORMSG will be ignored.
Activation of ON ERRORLEVEL
ON ERRORLEVEL n will execute command when the internal ERRORLEVEL variable is equal to the integer specified by n. You can also use the IF ERRORLEVEL tests; for example:
ON ERRORLEVEL EQ 37 ...
Activation of ON LBUTTON
ON LBUTTON will execute command when the left mouse button is clicked.
Activation of ON LOGOFF
ON LOGOFF will execute command when the user logs off.
Activation of ON MBUTTON
ON MBUTTON will execute command when the middle mouse button is clicked when TCC is the active window.
Activation of ON RBUTTON
ON RBUTTON will execute command when the right mouse button is clicked when TCC is the active window.
Activation of ON RESUME
ON RESUME will execute command when the system resumes after sleeping or hibernating.
Activation of ON SHUTDOWN
ON SHUTDOWN will execute command when the system is being shut down.
Activation of ON SUSPEND
ON SUSPEND will execute command when the system is going to sleep or hibernation. Windows will continue suspending after a maximum of 2 seconds.
Each time an ON statement is defined, it defines a new command to be executed for that event, and any prior command is discarded.
If you do not specify a command, TCC restores the default handler.
An ON statement only affects the current batch file. When the batch file containing ON is exited for any reason, whether temporarily (e.g., by a CALL to another batch file) or permanently, the TCC default break and error handlers become effective. A CALLed batch file may then use ON to define its own handlers. When control returns to the calling batch file, its break and error handlers that had been in effect at the CALL are 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:
on break gosub gotabreak
do i = 1 to 1000
echo Hey! Stop that!!
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 assumes that you want to continue executing the batch file. After the command is executed, control automatically returns to the command in the batch file immediately after the one that was interrupted by the event. To avoid continuing the batch file after the event at the next command perform one of the following in command:
•transfer control with GOTO,
•chain to another batch file (without using CALL).
To force TCC to ignore break or error, use the REM command as your command.
ON can only be used in batch files.
The ON ERROR[MSG] command will not be invoked if an error occurs while reading or writing redirected input, output, or a pipe.
Caution: If a break or error occurs while the command specified in ON BREAK, ON ERROR, ON ERRORLEVEL, or ON ERRORMSG is executing, the command will be restarted. This means you must use caution either to avoid or to handle any possible errors in the commands invoked by ON, since such errors can cause an infinite loop.