Q(uick)BASIC Statement: CHAIN

Quick View

CHAIN

A program control statement that transfers control to another program

Worth knowing

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

Syntax

CHAIN filespec$

Description/Parameter(s)

filespec$

The name of the program to which control is passed.

Differences from BASICA

QBasic does not allow you to specify a line number with CHAIN and does not support the ALL, MERGE, or DELETE options in BASICA.

Example

'Assumes the program TEST.BAS is in a \DOS directory.
CHAIN "C:\DOS\TEST.BAS"

Syntax

CHAIN filespec

Description/Parameter(s)

The behavior of CHAIN and RUN is almost identical. The principal differences are that RUN closes all open files and does not support COMMON data blocks.

Programs running within the QuickBASIC environment assume a .BAS extension (if no extension is given) and cannot chain to executable files (files with a .COM or .EXE extension).
Programs running outside the QuickBASIC environment assume an .EXE extension and cannot chain to QuickBASIC source files (files with a .BAS extension).

You can pass variables between programs using the COMMON statement to set up a blank COMMON block. See the entry for COMMON.

If you are compiling a program outside the QuickBASIC environment, note that the BCOM45.LIB library does not support COMMON. There are two ways to use COMMON with chained programs outside the environment.

Use the default (BRUN45.EXE) by compiling the programs using the option in the Make EXE dialog box called EXE Requiring BRUN45.EXE.
Use BRUN45.LIB by compiling from the command line without the /O option.

Note:

When programs use BRUN45.LIB, files are left open during chaining unless they are explicitly closed with a CLOSE statement.

Difference from BASICA

BASICA assumes the extension .BAS. QuickBASIC assumes an extension of either .BAS or .EXE, depending on whether the program is run within the environment or compiled and run outside the environment. If you omit the file extension, CHAIN works the same in both QuickBASIC and BASICA.
BASIC does not support the ALL, MERGE, or DELETE options available in BASICA, nor does it allow you to specify a line number.
Without the line-number option, execution always starts at the beginning of the chained-to program. Thus, a chained-to program that chains back to a carelessly written chaining program can cause an endless loop.

Example

The ⮜ COMMON statement programming example ⮞ illustrates the use of the CHAIN statement.

Syntax

CHAIN filespec$

Description/Parameter(s)

The argument filespec$ is a string expression; can include a path specification. (With DOS 2.1 or earlier versions, you cannot use CHAIN unless filespec$ provides a complete path, including drive.)
Programs running within the QBX environment assume a .BAS extension (if no extension is given) and cannot chain to executable files (files with a .COM or .EXE extension).
Programs running outside the QBX environment assume an .EXE extension and cannot chain to BASIC source files (files with a .BAS extension).

Usage Notes

You can pass variables between programs using the COMMON statement to set up a blank COMMON block. See ⮜ COMMON Statement ⮞.
When you compile a program outside the QBX environment, the BCL71EFR.LIB library does not support COMMON. There are two ways to use COMMON with chained programs outside the environment:

Use the default (BRT71EFR.EXE for DOS and OS/2 real mode; BRT71EFR.DLL for OS/2 protected mode) by compiling the programs using the option in the "Make EXE" dialog box called "EXE Requiring BRT Module."
Use BRT71EFR.LIB by compiling from the command line without the /O option.

When programs use BRT71EFR.EXE or BRT71EFR.DLL, files are left open during chaining unless they are explicitly closed with a CLOSE.

Note:

The filenames BCL71EFR.LIB, BRT71EFR.EXE, and BRT71EFR.DLL assume that you selected these compiler options when you installed BASIC: emulator floating-point math, far strings, and real mode. If you used different options, see "About Linking and Libraries" in the Programmer's Guide for information on compiler options.

Differences from BASICA

BASICA assumes the extension .BAS. the current version of BASIC assumes an extension of either .BAS or .EXE, depending on whether the program is run within the environment or compiled and run outside the environment. If you omit the file extension, CHAIN works the same in BASICA and in the current version of BASIC.
The current version of BASIC does not support the ALL, MERGE, or DELETE options available in BASICA, nor does it allow you to specify a line number.
Without the line-number option, execution always starts at the beginning of the chained-to program. Thus, a chained-to program that chains back to a carelessly written chaining program can cause an endless loop.

Example

This example uses the COMMON statement to pass variables between two chained programs. It uses the CHAIN statement, in the first program, to load and run a second program which finds and prints the average of the values.
Note: After running this example from QBX, you will be left in PROG2.BAS.

 'Set up the variables that are passed from PROG1 to PROG2.
DIM values(1 TO 50)
COMMON values(), NumValues%
 
'The following few lines of code creates the second program on the disk
'so that it can load and run with the CHAIN statement. It is, in fact, a
'series of PRINT # statements to put the proper BASIC statements in a file.
 
OPEN "PROG2.BAS" FOR OUTPUT AS #1
PRINT #1, "'This is PROG2 for the CHAIN and COMMON statement examples"
PRINT #1, "DIM X(1 TO 50)"
PRINT #1, "COMMON X(), N%"
PRINT #1, "PRINT"
PRINT #1, "IF N% > 0 THEN"
PRINT #1, "   Sum% = 0"
PRINT #1, "   FOR I% = 1 TO N%"
PRINT #1, "      Sum% = Sum% + X(I%)"
PRINT #1, "   NEXT I%"
PRINT #1, "   PRINT "; CHR$(34); "The average of the values is";
PRINT #1, CHR$(34); "; Sum% / N%"
PRINT #1, "END IF"
PRINT #1, "END"
CLOSE #1
'End of PROG2 creation section.
 
CLS
PRINT "Enter values one per line. Type 'END' to quit."
NumValues% = 0
DO
   INPUT "-> ", N$
   IF I% >= 50 OR UCASE$(N$) = "END" THEN EXIT DO
   NumValues% = NumValues% + 1
   values(NumValues%) = VAL(N$)
LOOP
PRINT "Press any key to continue... "
DO WHILE INKEY$ = ""
LOOP
CHAIN "PROG2.BAS"
END