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

 

Usage:

 

ON sets a watch that remains in effect for the duration of the current session or 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 ).

 

Global Conditions:

 

The following ON conditions can be run from the command prompt (a "global condition"); all others will only work in a batch file.

 

ON CLOSE

ON LOGOFF

ON SHUTDOWN

ON SUSPEND

ON RESUME

 

If no command is specified, TCC-RT will remove the existing command for the specified condition. 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 an ON condition is defined for the current batch file, it will override a global ON condition.

 

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-RT session 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-RT 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-RT 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-RT is the active window.

 

Activation of ON RBUTTON

 

ON RBUTTON will execute command when the right mouse button is clicked when TCC-RT 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.

 

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.

 

If you do not specify a command, TCC-RT 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-RT 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.

 

Limitations

 

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.

 

Examples:

 

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 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-RT to ignore break or error, use the REM command as your command.

 

Options:

 

 

ON /G LOGOFF command