ON event Statements ---------------------------------------------------------------------------- Action Indicate the first line of an event-trapping routine. Syntax ON event GOSUB { linenumber | linelabel} Remarks The ON event statements let you specify a routine that is executed whenever a specified type of event occurs on a specified device. The ON event statements use the following arguments. ----------------------------------------------------------------------------- Argument Description ---------------------------------------------------------------------------- event Specifies the event that causes a branch to the event-trapping routine. See below for more information about specific types of events. linenumber or linelabel The number or label of the first line in the event-trapping routine. This line must be in the module-level code. A linenumber value of 0 disables event trapping and does not Argument Description ---------------------------------------------------------------------------- event trapping and does not specify line 0 as the start of the routine. The following list describes the events that can be trapped. ----------------------------------------------------------------------------- Event Description ---------------------------------------------------------------------------- COM( n%) Branches to the routine when characters are received at a communications port. The integer expression n% indicates one of the serial ports, either 1 or 2. For more information, see "Using ON COM" later in this entry. KEY( n%) Branches to the routine when a Event Description ---------------------------------------------------------------------------- KEY( n%) Branches to the routine when a specified key is pressed. The integer expression n% is the number of a function key, direction key, or user-defined key. For more information, see "Using ON KEY" later in this entry. PEN Branches to the routine when a lightpen is activated. For more information, see "Using ON PEN" later in this entry. PLAY( queuelimit%) Branches when there are fewer than queuelimit% notes in the background-music queue. A PLAY event-trapping routine can be used with a PLAY statement to play music in the background while a Event Description ---------------------------------------------------------------------------- music in the background while a program is running. For more information, see "Using ON PLAY" later in this entry. SIGNAL( n%) Branches to the routine when an OS-2 protected-mode signal is received. For more information, see "Using ON SIGNAL" later in this entry. STRIG( n%) Branches to the event-trapping routine when a joystick trigger is pressed. The integer expression n% is the joystick trigger number. For more information, see "Using ON STRIG" later in this entry. TIMER( n&) Branches to the routine when n Event Description ---------------------------------------------------------------------------- TIMER( n&) Branches to the routine when n seconds have passed. The numeric expression n& is in the range 1 to 86,400 (1 second to 24 hours). UEVENT Branches to the event-trapping routine for a user-defined event. This event usually is a hardware interrupt (although it can be a software interrupt). For more information, see "Using ON UEVENT" later in this entry. The ON event statement specifies only the start of an event-trapping routine. Another set of statements determines whether or not the routine is called. This set of statements turns event trapping on or off and determines how events are handled when trapping is off. The following list describes these statements in a general way. See the entries for particular statements for more specific information. ----------------------------------------------------------------------------- Event Description ---------------------------------------------------------------------------- event ON Enables event trapping. Event trapping occurs only after an event ON statement is executed. event OFF Disables event trapping. No trapping takes place until the execution of another event ON statement. Events occurring while trapping is off are ignored. event STOP Suspends event trapping so no trapping takes place until an event ON statement is executed. Events occurring while trapping is inhibited are remembered and processed when an event ON Event Description ---------------------------------------------------------------------------- processed when an event ON statement is executed. When an event trap occurs and the routine is called, BASIC performs an automatic event STOP that prevents recursive traps. The RETURN statement from the trapping routine automatically performs an event ON statement unless an explicit event OFF is performed inside the routine. If your program contains event-handling statements and you are compiling from the BC command line, use the BC -W or -V option. (The -W option checks for events at every label or line number; the -V option checks at every statement.) If you do not use these options and your program contains event traps, BASIC generates the error message ON events without -V or -W on command line. Note Because of the implicit event STOP and event ON statements, events that occur during execution of the trapping routine are remembered and processed when the routine ends. The RETURN linenumber or RETURN linelabel forms of RETURN can be used to return to a specific line from the trapping routine. Use this type of return with care, however, because any GOSUB, WHILE, or FOR statements active at the time of the trap remain active. BASIC may generate error messages such as NEXT without FOR. In addition, if an event occurs in a procedure, a RETURN linenumber or RETURN linelabel statement cannot get back into the procedure because the line number or label must be in the module-level code. The next sections contain additional information about the ON COM, ON KEY, ON PEN, ON PLAY, ON SIGNAL, ON STRIG, and ON UEVENT statements. Using On Com You can use ON COM( n%) to specify a routine to branch to when characters are received at communications port n%, which can be either 1 or 2. If your program receives data using an asynchronous communications adapter, the BASIC command-line option -C can be used to set the size of the data buffer. For an example of the ON COM statement, see the COM statements programming example. Using On Key You can use ON KEY( n%) to specify a routine to branch to when key n% is pressed. The argument n% is the number of a function key, direction key, or user-defined key. Keys are processed in the following order. - The line printer's echo-toggle key is processed first. Defining this key as a user-defined key trap does not prevent characters from being echoed to the line printer when pressed. - Function keys and the direction keys are examined next. Defining a function key or direction key as a user-defined key trap has no effect because these keys are predefined. - Finally, the user-defined keys are examined. The ON KEY statement can trap any key, including break or system reset. This makes it possible to prevent accidentally breaking out of a program or rebooting the machine. Note After a key is trapped, the information on which key was trapped is no longer available. This means that you cannot subsequently use the INPUT statement or INKEY$ function to find out which key caused the trap. Because you do not know which key press caused the trap, you must set up a different event-handling routine for each key you want to trap. For an example of the ON KEY statement, see the KEY statements programming example. Using On PEN You can use ON PEN to specify a routine to branch to when the lightpen is activated. ON PEN is not available for OS-2 protected mode. For an example of the ON PEN statement, see the PEN statements programming example. Using On PLAY You can use ON PLAY( queuelimit%) to specify a routine to branch to when there are fewer than queuelimit% notes in the background-music queue. The argument queuelimit% is an integer expression between 1 and 32, inclusive. The following three rules apply to the use of ON PLAY. - A play-event trap occurs only when music is playing in the background. Play-event traps do not occur when music is running in the foreground. - A play-event trap does not occur if the background music queue has already gone from having queuelimit% to queuelimit%-1 notes when a PLAY ON is executed. - If queuelimit% is a large number, event traps may occur often enough to slow down the program. ON PLAY is not available for OS-2 protected mode. For an example of the ON PLAY statement, see the PLAY function programming example. Using On SIGNAL You can use ON SIGNAL to specify a routine to branch to when an OS-2 protected-mode signal is trapped. The following table lists the numbers of the protected-mode signals. ----------------------------------------------------------------------------- Number Signal ---------------------------------------------------------------------------- 1 Ctrl+C 2 Pipe connection broken 3 Program terminated 4 Ctrl+Break 5 Process flag A 6 Process flag B 7 Process flag C Process flag A, process flag B, and process flag C are used for communicating between processes. Although BASIC has no built-in mechanism for activating a process flag, you can activate the signal handler in a separate process by invoking the OS-2 function DOSFLAGPROCESS. The ON SIGNAL statement is available only for OS-2 protected mode. For an example of the ON SIGNAL statement, see the SIGNAL statements programming example. Using On STRIG You can use ON STRIG( n%) to specify a routine to branch to when the button on the joystick is pressed. The argument n% is the trigger number as defined in the following table. ----------------------------------------------------------------------------- n% Button Joystick ---------------------------------------------------------------------------- 0 Lower First 2 Lower Second 4 Upper First 6 Upper Second ON STRIG is not available for OS-2 protected mode. For an example of the ON STRIG statement, see the STRIG statements programming example. Using On UEVENT You can use ON UEVENT to specify a routine to branch to when a user-defined event occurs. The event usually is a hardware interrupt (although it also can be a software interrupt). When using DOS, at least two (and sometimes three) pieces of code are needed. The first is the interrupt-service routine. The second is an initialization routine to insert the address of the service routine into the interrupt-vector table. The third is the routine your BASIC program calls to retrieve the data (if any) collected by the interrupt-service routine. For more information, see "Event Handling" in the Programmer's Guide. If the initialization routine "steals" an interrupt used by another service routine, the original address must be restored before your program terminates. These routines usually are written in assembly language. However, any language whose compiler can generate interrupt-service routines and whose object code can be linked with BASIC can be used. There are four steps in creating a user-defined event. - Write an event-handling routine and add it to your BASIC program. - Execute the ON UEVENT statement to specify the user-event handling routine. - Execute the UEVENT ON statement to enable user-event trapping. - Call the interrupt-initialization routine to insert the address of the interrupt-service routine into the interrupt-vector table. You're now ready for the interrupt when it occurs. The interrupt transfers execution to the interrupt-service routine. The service routine collects and stores the data the user wants. It then calls SetUEvent (see the entry for SetUEvent for details). SetUEvent sets a flag checked by BASIC before going to the next BASIC statement (or label if executing compiled code using -W instead of -V). When the flag is set, control transfers to the event-handling routine designated in ON EVENT. For an example of the ON UEVENT statement, see the UEVENT statements programming example. See Also COM, EVENT, KEY (Event Trapping), PEN, PLAY (Event Trapping), RETURN, SIGNAL, STRIG, TIMER, UEVENT