Q(uick)BASIC Statement: ON COM

Quick View

ON COM(n)

An event trapping statement that specifies a subroutine to branch to when characters are received at communications port n

Worth knowing

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

Syntax

COM(n%) ON
COM(n%) OFF
COM(n%) STOP
ON COM(n%) GOSUB line

Description/Parameter(s)

n%	The number of a COM (serial) port (1 or 2).
COM(n%) ON	Enables trapping of a communications event.
COM(n%) OFF	Disables communications event trapping.
COM(n%) STOP	Suspends communications event trapping. Events are processed once event trapping is enabled by COM ON.
line	The label or number of the first line of the event-trapping subroutine.

Example

COM(1) ON       'Enable event trapping on port 1.
ON COM(1) GOSUB ComHandler
DO : LOOP WHILE INKEY$ = ""
COM(1) OFF
END

ComHandler:
    PRINT "Something was typed at the terminal attached to COM1."
    RETURN

Syntax

ON COM(n) GOSUB {linelabel | linenumber}

Description/Parameter(s)

n, an integer expression, indicates one of the serial ports, either 1 or 2
linelabel or linenumber is the first line of the event-handling subroutine

If your program receives data using an asynchronous communications adapter, the BASIC command-line option /C can be used to set the size of the data buffer.

Example

There is no programming example for the ON COM(n) statement.
The following programming examples show how to integrate ON event statements, statements that enable traps, and event-handling subroutines into a working program:⮜ ON PLAY(n) statement programming example ⮞
⮜ ON TIMER(n) statement programming example ⮞

Syntax

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

Description/Parameter(s)

n%	An integer expression that indicates one of the COM (serial) ports: 1 = serial port 1; 2 = serial port 2.
linenumber or linelabel	The first line of the event-handling routine to branch to when characters are received at a communications port.

Usage Notes

If your program receives data using an asynchronous communications adapter, the BASIC command-line option /C can be used to set the size of the data buffer.
The COM statement specifies only the start of an event-trapping routine. The ⮜ COM Statements ⮞ determine whether the routine is called and how events are handled when trapping is off:

COM ON	Enables event trapping. Event trapping occurs only after a COM ON statement is executed.
COM OFF	Disables event trapping. Even if an event takes place, it is not remembered.
COM STOP	Suspends event trapping. Any events that occur are remembered and are trapped as soon as a COM 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 OPEN COM statement to open the COM1 port for input and the COM statement to enable event trapping. The COM statement passes control to a subroutine when there is activity on a terminal.
Note: To run this program, you must have a terminal connected to the COM1 port.

CLS
'Set up error handling in case COM1 doesn't exist.
ON ERROR GOTO ErrHandler
'Open the COM port.
OPEN "COM1:9600,N,8,1,BIN" FOR INPUT AS #1
 
'Turn on COM event processing.
COM(1) ON
'Set up COM event handling.
ON COM(1) GOSUB Com1Handler
'Wait for a COM event to occur or a key to be pressed.
DO
LOOP WHILE INKEYspan> = ""
'Turn off COM event handling.
COM(1) OFF
CLS
END
 
Com1Handler:
    PRINT Aspan>; "Something was typed on the terminal attached to COM1."
    RETURN
 
ErrHandler:
    SELECT CASE ERR
  CASE 68: PRINT "COM1 is unavailable on this computer.": END
  CASE ELSE: END
    END SELECT