◄Summary►  ◄Details►  ◄Example►                ◄Contents►  ◄Index►  ◄Back►
──────────────────────────────────────────────────────────────────────────────
 ON UEVENT GOSUB {linenumber | linelabel}
 
 Usage Notes
   ■ The ON UEVENT statement does not affect form- or control-specific
     events. Forms and controls use different event handlers. Use object-
     specific events with forms. See: ◄Object Events Summary►
 
   ■ If your program contains event-handling statements and you are compiling
     from the BC command line, use the /W or /V option. If you do not use
     these options and your program contains event traps, Visual Basic
     generates the error message, "ON event without /V or /W on command
     line." See: ◄BC Command-Line Options►
 
   ■ Use the RETURN linenumber or RETURN linelabel forms of RETURN to return
     to a specific line from a trapping routine. However, any GOSUB, WHILE,
     or FOR statements active at the time of the trap remain active. Visual
     Basic may generate 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.
 
   ■ ON UEVENT enables your program to 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).
 
   ■ 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.
 
   ■ 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 under MS-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 program calls to retrieve the data (if any)
       collected by the interrupt-service routine
 
   ■ 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 Visual Basic may be used.
 
   ■ There are four steps to creating a user-defined event:
     • Write an event-handling routine and add it to your Visual 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.
 
   ■ Once a user-defined event is created, your program is 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, then calls SetUEvent. See: ◄SetUEvent Routine►
 
   ■ SetUEvent sets a flag checked by Visual Basic before going to the next
     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 UEVENT.
 
   ■ The ON UEVENT statement specifies only the start of an event-trapping
     routine. The UEVENT statement determines whether the routine is called
     and how events are handled when trapping is off.
     See: ◄UEVENT Statement►