advr.hlp (Topic list)
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.
ON UEVENT Statement Details
  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