Q(uick)BASIC Statement: ON UEVENT

Quick View

ON UEVENT GOSUB

An error-trapping statement that defines the event-handler for a user-defined event

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax
  • ON UEVENT GOSUB { linenumber | linelabel }
Description/Parameter(s)

The linenumber or linelabel argument is the number or label of the first line in the event-handling routine. ON UEVENT GOSUB lets your program branch to an event-handling routine when a user-defined event occurs. The event is usually a hardware interrupt.

This gives user-defined events one of the features enjoyed by the COM, KEY, and other events in BASIC. Once these events have been defined with an ON event statement, they act like interrupts. The program does not need to poll for the event.

Likewise, once ON UEVENT GOSUB 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.

  • At least two (and sometimes three) pieces of code are needed to set up a user-defined event.
    • 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.

If the initialization routine "steals" an interrupt used by another service routine, the original address must be restored before your program terminates.

These routines are usually 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 GOSUB 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.

When the interrupt 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. SetUEvent sets a flag checked by QuickBASIC 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 GOSUB.

The SetUEvent procedure is a part of BASIC, and is automatically included in compiled applications or when running QuickBASIC with the /L command-line option. Your interrupt service routine must call SetUEvent; it is the only way to alert your program that the event has occurred. You can call SetUEvent from any language, not just assembly language.

SetUEvent is not a function; it cannot return a value to BASIC. If you wish to return a value, you must write a function for your BASIC program to call. (It would usually be called by your event-handling routine.) This function must be described in a declare statement so your BASIC program can find and use it.

Although ON UEVENT GOSUB 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.

Example

The following example illustrates the use of ON UEVENT GOSUB:

ON UEVENT GOSUB Event1 UEVENT ON INPUT "Enter a number"; a IF a = 5 THEN CALL Setuevent END ' Event1: PRINT "Got to the event handler" RETURN

See also:

Syntax
  • ON UEVENT GOSUB {linenumber | linelabel}
Description/Parameter(s)
linenumber or linelabel The first line of an event-handling routine to branch to when the user-defined event occurs.
A linenumber value of 0 disables event trapping and 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 ONEnables event trapping. Event trapping occurs only after a UEVENT ON statement is executed.
    UEVENT OFFDisables event trapping. Even if an event takes place, it is not remembered.
    UEVENT STOPSuspends 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.
Example

This example uses the UEVENT and ON UEVENT statements to enable user-defined event trapping. The SetUEvent routine signals a user-defined event, and control is passed to an event-handling routine. This example is a primitive use of the UEVENT statements, which are best suited for interfacing hardware to a computer.
Note: In order to use this program or any user-defined event trapping, you must load the Quick library QBX.QLB using the /L option.

CLS PRINT "This program asks for 10 numbers between 0 and 9, inclusive." PRINT "As each number is input, it is evaluated to determine whether" PRINT "it is odd or even. Odd numbers cause a user-defined event" PRINT "to occur. Even numbers do not.": PRINT ON UEVENT GOSUB Event1 UEVENT ON DO PRINT "Enter a number --> "; N = VAL(INPUT$(1)): PRINT N: PRINT SELECT CASE N CASE 1, 3, 5, 7, 9 PRINT "An odd number was input causing a user-defined event."; CALL SetUEvent CASE ELSE PRINT "No user-defined event occurred.": PRINT END SELECT LoopCount = LoopCount + 1 LOOP UNTIL LoopCount = 10 END Event1: PRINT "Now processing the UEVENT. The odd number was"; N PRINT RETURN

See also: