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 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:




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 %i




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,

end the batch file with QUIT or CANCEL

chain to another batch file (without using CALL).


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.


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.