Q(uick)BASIC Statement: STOP

Quick View

STOP

A control flow statement that terminates the program

Worth knowing

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

Syntax

STOP

Description/Parameter(s)

The STOP keyword also suspends trapping of events in these statements:
⮜ COM, ON COM ⮞	⮜ KEY, ON KEY ⮞	⮜ PEN, ON PEN ⮞
⮜ PLAY, ON PLAY ⮞	⮜ STRIG, ON STRIG ⮞	⮜ TIMER, ON TIMER ⮞

Example

FOR i% = 1 TO 10
    PRINT i%
    IF i% = 5 THEN STOP     'STOP pauses; F5 Continues.
NEXT i%

Syntax

STOP

Description/Parameter(s)

STOP statements can be used anywhere in a program to terminate execution.

When running in the QuickBASIC environment, the STOP statement leaves files open and does not exit to the operating system. In contrast, a STOP statement in a stand-alone .EXE file does close all files and return to the operating system.

If you use the /D, /E, or /X compile options on the BC command line, the STOP statement prints the number of the line where execution stopped, if your program has line numbers. If there is no line number associated with the STOP statement, the most recent line number is printed. If your program has no line numbers, then the line number printed is 0.

In the past, STOP statements were used for debugging. QuickBASIC's new debugging features make this use of STOP unnecessary.

Other Uses of the STOP Keyword

The STOP keyword is used in various statements to suspend trapping of various events in the following statements:

Statement	Type of Event Trapping Suspended
COM(n) STOP	events on communications port n
KEY(n) STOP	a keypress event on key n
PEN STOP	lightpen events
PLAY STOP	background music buffer events
STRIG(n) STOP	events on joystick trigger n
TIMER STOP	timer events
UEVENT STOP	user-defined events

Syntax

STOP (n%)

Description/Parameter(s)

n%	Halts a program and returns the value n% to the operating system. If n% is omitted, a value of 0 is returned to the operating system.

The STOP keyword suspends trapping of events in these statements:
⮜ COM(n%) STOP ⮞	⮜ PEN STOP ⮞	⮜ SIGNAL(n%) STOP ⮞	⮜ TIMER STOP ⮞
⮜ KEY(n%) STOP ⮞	⮜ PLAY STOP ⮞	⮜ STRIG(n%) STOP ⮞	⮜ UEVENT STOP ⮞

The value n% can be used by DOS or OS/2 batch files or by non-BASIC programs. Untrapped errors and fatal errors set the value of n% to -1.

Usage Notes

You can place STOP statements anywhere in a program to terminate execution.
In a stand-alone program, STOP closes all files and returns to the operating system; in the QBX environment, STOP leaves files open and returns to the environment.
If you use the /D, /E, or /X compile option on the BC command line,
the STOP statement prints line numbers as follows:
If your program has STOP prints
Line numbers Number of the line where execution stopped
No line number for STOP Most recent line number
No line numbers 0
In the QBX environment, STOP always returns an error level of 0 even if you specify a different error level.
In some previous versions of BASIC, STOP statements were used for debugging. In the current version of BASIC, you do not have to use STOP for debugging.

Example

The program uses the ON ERROR statement to enable error trapping. The program attempts to write a large file to the disk. If an error occurs, control is passed to a handling routine, and the ERR function is used to determine an appropriate message to display. The ERROR, ERR, and RESUME statements are used to exit the handling routines, and the END, STOP, and SYSTEM statements demonstrate ways to exit a program.

DECLARE SUB ErrorMessage (Message$)
DECLARE SUB WriteBigFile (Filenum%)
ON ERROR GOTO ErrHandler
CLS
PRINT "This program will attempt to write a large file to a disk drive"
PRINT "you select. The file will be erased when the program ends."
PRINT
DO
    INPUT "Which drive"; DR$
    DR$ = UCASE$(DR$)
LOOP UNTIL LEN(DR$) >= 1 AND LEN(DR$) <= 2 AND DR$ >= "A" AND DR$ <= "Z"
IF LEN(DR$) > 1 THEN
    IF RIGHT$(DR$, 1) <> ":" THEN
        DR$ = LEFT$(DR$, 1) + ":"
    END IF
ELSE
    DR$ = DR$ + ":"
END IF
'Put together a complete file specification.
FileSpec$ = DR$ + "BIGFILE.XXX"
'Get the next available file number.
Filenum% = FREEFILE
'Try to open the file.
OPEN FileSpec$ FOR OUTPUT AS Filenum%
WriteBigFile Filenum%
CLOSE Filenum%
CLS
PRINT "Everything was OK. No errors occurred."
PRINT "Deleting the file that was created."
KILL FileSpec$
'Same as END, returns to operating system.
SYSTEM
 
ErrHandler:
 
SELECT CASE ERR
    CASE 52  'Bad file name or number.
        END
    CASE 53  'File not found.
        RESUME NEXT
    CASE 57  'Device I/O error.
        ErrorMessage "You should probably format the diskette."
        END
    CASE 64  'Bad File Name.
        ErrorMessage "The drive name you specified was not correct."
        END
    CASE 68  'Device unavailable.
        ErrorMessage "The drive you named is unavailable."
        END
    CASE 71  'Drive not ready.
        ErrorMessage "The drive was not ready. Check the drive!"
        END
    CASE ELSE
        ErrorMessage "An unexpected FATAL error has occurred."
        STOP
END SELECT

SUB ErrorMessage (Message$)
    ON LOCAL ERROR GOTO MessageError
    CLS
    PRINT Message$
    PRINT "Cannot continue."
    PRINT
    PRINT "Press any key to exit."
    DO
    LOOP WHILE INKEY$ = ""
    EXIT SUB
MessageError:
    RESUME NEXT
END SUB

SUB WriteBigFile (Filenum%)
    ON LOCAL ERROR GOTO LocalHandler
    TEXT$ = STRING$(1024, "A")
    FOR I% = 1 TO 400
        PRINT #Filenum%, TEXT$
    NEXT I%
    EXIT SUB
LocalHandler:
    SELECT CASE ERR
        CASE 61             'Disk full.
            ErrorMessage ("There is no room remaining on the disk.")
            KILL "BIGFILE.XXX"
            END
        CASE ELSE
            ERROR ERR
    END SELECT
END SUB

If your program has	STOP prints
Line numbers	Number of the line where execution stopped
No line number for STOP	Most recent line number
No line numbers	0