Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

  ◄QuickSCREEN►      ◄Details►      ◄Example►      ◄Contents►      ◄Index►
──────────────────────────────────────────────────────────────────────────────
ON event Statements Details
 
The ON event statement lets you specify a subroutine that is executed
whenever an event occurs on a specified device.
 
Syntax
  ON event GOSUB {linenumber | linelabel}
 
  Argument     Description
  event        A keyword that specifies the event that causes a branch to
               the event-trapping subroutine. An event is a condition on a
               specific device:
 
                 COM    characters received at a communications port
                 KEY    a designated keystroke
                 PEN    lightpen activated
                 PLAY   too few notes in background music queue
                 STRIG  joystick trigger pressed
                 TIMER  time interval has elapsed
 
  linenumber   The number or label of the first line in the event-
  or           trapping subroutine. This line must be in the module-
  linelabel    level code.
 
      Note: A linenumber of 0 disables event trapping and does not
            specify line 0 as the start of the subroutine.
 
The ON event statement only specifies the start of an event-trapping
subroutine. Another set of statements determines whether or not the
subroutine 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.
 
  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   Inhibits 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 statement is executed.
 
  For specific information about each of these statements, see the
    ◄COM statement►,
    ◄KEY statement►,
    ◄PEN statement►,
    ◄PLAY (event) statement►,
    ◄STRIG statement►, or
    ◄TIMER statement►.
 
When an event trap occurs (the subroutine is called), BASIC performs
an automatic event STOP that prevents recursive traps. The RETURN from
the trapping subroutine automatically performs an event ON statement
unless an explicit event OFF is performed inside the subroutine.
 
  Note: Because of the implicit event STOP and event ON statements,
        the events during execution of the trapping subroutine are
        remembered and processed when the trapping subroutine ends.
 
The RETURN linenumber or RETURN linelabel forms of RETURN can be used
to return to a specific line number from the trapping subroutine. Use
this type of return with care, however, because
 
  ■ any other GOSUB, WHILE, or FOR statements active at the time of
    the trap remain active. This may produce error messages such as
    "NEXT without FOR."
  ■ 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.
 
Differences from BASICA
 
If you use BC from the DOS prompt and a program contains ON event
statements, you must use /V or /W. These options allow the compiler
to function correctly when event-trapping subroutines are included
in a program. BASICA does not require additional options.