ON

ON CLOSE [command]

ON ERROR [command]

ON ERRORLEVEL n [command]

ON ERRORMSG [command]

ON LOGOFF [command]

ON SHUTDOWN [command]

ON LBUTTON [command]

ON MBUTTON [command]

ON RBUTTON [command]

command        command to execute when the event occurs

Usage:

ON sets a watch that remains in effect for the duration of the current batch file, or until replaced by another ON command. Whenever a break or error condition occurs after ON has been executed, the corresponding command is automatically executed.

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 TCC tab is closed.

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 greater than or equal to the integer specified by n.  You can also use the IF ERRORLEVEL tests; for example:

       ON ERRORLEVEL EQ 37 ...

Activation of ON LOGOFF

ON LOGOFF will execute command when the user logs off.

Activation of ON SHUTDOWN

ON SHUTDOWN will execute command when the system is being shut down.

Activation of ON LBUTTON

ON LBUTTON will execute command when the left mouse button is clicked.

Activation of ON MBUTTON

ON MBUTTON will execute command when the middle mouse button is clicked.

Activation of ON RBUTTON

ON RBUTTON will execute command when the right mouse button is clicked.

Scope

Each time an ON statement is defined, it defines a new command to be executed for that event, and any prior command is discarded.

ON BREAK or ON ERROR[MSG] without a command restores the TCC 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 TCCdefault 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.

Operation

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

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, ON ERROR, ON ERRORLEVEL, ON ERRORMSG, ON LBUTTON, ON MBUTTON, and ON RBUTTON assume 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:

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.

Limitations

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.