Q(uick)BASIC Statement: ON SIGNAL

Quick View

ON SIGNAL

A statement that specifies a routine to branch to when an OS/2 protected-mode signal is received

Worth knowing

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

Syntax

ON SIGNAL(n%) GOSUB {linenumber | linelabel}

Description/Parameter(s)

The number of the protected-mode signal:

n%	Signal	n%	Signal
1	Ctrl+C	5	Process flag A
2	Pipe connection broken	6	Process flag B
3	Program terminated	7	Process flag C
4	Ctrl+Break

linenumber or linelabel

A linenumber value of 0 disables event trapping and does not specify line 0 as the start of the routine.

Usage Notes

Process flags A, B, and C are used for communicating between processes.
Although BASIC has no built-in mechanism for activating a process flag, you can activate the signal handler in a separate process by invoking the OS/2 function DOSFLAGPROCESS.

The ON SIGNAL statement specifies only the start of an event-trapping routine. The ⮜ SIGNAL Statements ⮞ determine whether the routine is called and how events are handled when trapping is off:

SIGNAL ON	Enables event trapping. Event trapping occurs only after a SIGNAL ON statement is executed.
SIGNAL OFF	Disables event trapping. Even if an event takes place, it is not remembered.
SIGNAL STOP	Suspends event trapping. Any events that occur are remembered and are trapped as soon as a SIGNAL 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 other 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 EVENT and SIGNAL statements to enable event trapping. The ON SIGNAL statement passes control to a handling routine when Ctrl-Break is pressed.
Note: The SIGNAL and ON SIGNAL statements can only be used in the OS/2 operating system.

CLS
ON ERROR GOTO ErrHandler
PRINT "This program traps Control-Break in the OS/2 operating system."
EVENT ON
'Set up the signal event trap.
ON SIGNAL(4) GOSUB CtrlBreak
'Wait until the SIGNAL event occurs.
'Enable the trap.
SIGNAL(4) ON
DO
LOOP UNTIL UCASE$(INKEY$) = "Q"
PRINT "'Q' pressed - Program terminating normally."
END
 
CtrlBreak:
    PRINT "A SIGNAL(4) event occurred."
    PRINT "Press 'Q' to quit."
    RETURN
 
ErrHandler:
    SELECT CASE ERR
  CASE 73
      PRINT : PRINT "You cannot use the ON SIGNAL feature in DOS."
  CASE ELSE
    END SELECT
    END