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.

  ◄Syntax►  ◄Details►  ◄Example►                 ◄Contents►  ◄Index►  ◄Back►
──────────────────────────────────────────────────────────────────────────────
The ON UEVENT statement defines the event-handler for a user-defined event.
 
ON UEVENT GOSUB {linenumber | linelabel}
    ■ linenumber or    A linenumber value of 0 disables event trapping and
      linelabel        does not specify line 0 as the start of the
                       routine.
 
Usage Notes
    ■ ON UEVENT lets your program branch to an event-handling routine
      when a user-defined event occurs. The event usually is a hardware
      interrupt (although it also can be a software interrupt).
    ■ Like other BASIC events (such as COM and KEY), a user-defined event
      acts as an interrupt once it has been defined with an ON UEVENT
      statement. The program does not need to poll for the event.
    ■ Likewise, once ON UEVENT and UEVENT ON have been executed, the
      user-defined event automatically triggers execution of the BASIC
      routine to handle it. The program does not have to poll.
    ■ Although ON UEVENT ties an event-handling routine to a user-defined
      event, it does not enable the event trap. The UEVENT statement is
      used to enable, disable, and suspend user-defined event trapping.
    ■ To set up a hardware interrupt as a user-defined event when using
      DOS, at least two (and sometimes three) pieces of code are needed:
        - The interrupt-service routine.
        - An initialization routine to insert the address of the service
          routine into the interrupt-vector table.
        - The routine your BASIC program calls to retrieve the data (if
          any) collected by the interrupt-service routine.
      For more information, see Chapter 9, "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 may be used.
    ■ There are four steps in creating a user-defined event:
 
        1. Write an event-handling routine and add it to your BASIC program.
        2. Execute the ON UEVENT statement to specify the user-event
           handling routine.
        3. Execute the UEVENT ON statement to enable user-event trapping.
        4. 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 ◄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.
    ■ The ON UEVENT statement specifies only the start of an event-trapping
      routine. The ◄UEVENT Statements► determine whether the routine is
      called and how events are handled when trapping is off:
 
        UEVENT ON      Enables event trapping. Event trapping occurs only
                       after a UEVENT ON statement is executed.
        UEVENT OFF     Disables event trapping. Even if an event takes place,
                       it is not remembered.
        UEVENT STOP    Suspends event trapping. Any events that occur are
                       remembered and are trapped as soon as a UEVENT ON
                       statement is executed.
 
    ■ 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 event without /V or /W on command line."
    ■ 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.