The CALL statement transfers execution to an external subroutine.
An external subroutine is a sequence of statements that performs a discrete function, compiled separately from the calling program. Unless the subroutine is in the same file as the calling program, it must be cataloged in the account before being called.
The first statement of the subroutine must be the SUBROUTINE statement, and the last statement executed must be the RETURN statement. The SUBROUTINE statement can take several parameters that correspond to the parameters on the CALL statement that calls the subroutine. The nth parameter on the SUBROUTINE statement and the nth parameter on the CALL statement become equivalent.
Example
Suppose a simple subroutine named ADDEMUP is called with the following source lines:
|
PRINT "ENTER A NUMBER": INPUT NUMBER1 PRINT "ENTER ANOTHER NUMBER": INPUT NUMBER2 CALL ADDEMUP(NUMBER1, NUMBER2, NUMBER3) PRINT NUMBER1 : " PLUS " : NUMBER2 : " IS " : NUMBER3 |
and the subroutine ADDEMUP reads:
|
SUBROUTINE ADDEMUP(A,B,C) C = A + B RETURN |
The value of NUMBER1 is passed to the variable A in the subroutine, the value of NUMBER2 is passed to B, and the value of NUMBER3 is passed to C. At the conclusion of the subroutine, the parameters are returned with their new values (if any). Thus, ADDEMUP serves to place the sum of the first two numbers in the variable NUMBER3.
The alternative to passing parameters with the CALL and SUBROUTINE lines is the COMMON area, by which several programs can share the same variables.
The COMMON statement permits multiple programs and subroutines to use the same variables by accessing them according to the sequence in which they are stored. Each program using the COMMON area must include a COMMON statement, and the variables will be considered equivalent according to their positions. For example, in the simple example of a subroutine shown earlier in this section, the main program might have read:
|
COMMON NUMBER1, NUMBER2, NUMBER3 PRINT "ENTER A NUMBER": INPUT NUMBER1 PRINT "ENTER ANOTHER NUMBER": INPUT NUMBER2 CALL ADDEMUP PRINT NUMBER1 : " PLUS " : NUMBER2 : " IS " : NUMBER3 |
and the subroutine ADDEMUP:
|
SUBROUTINE ADDEMUP COMMON A, B, C C = A + B RETURN |
The variable NUMBER1 in the main program and the variable A in the subroutine are considered equivalent because of their positions in the COMMON statement. The same is true of NUMBER2 and B, and of NUMBER3 and C.
The CHAIN and EXECUTE statements can both be used for executing a TCL command. EXECUTE is by far the more powerful of the two statements, and is preferred to CHAIN.
The EXECUTE statement executes any TCL command and returns to the current program. In addition, the RETURNING clause can be used to determine error messages which may have resulted, and the CAPTURING clause can be used to capture the terminal output generated by the command.
The CHAIN statement will execute the command but will not return to the calling program.
The DATA statement places data in the secondary output buffer, or data stack. If the data stack is not empty, any subsequent requests for input will accept the response directly from the data stack, and the user will not be given the opportunity to respond.
The data stack is helpful for executing TCL commands that request information that the program can supply. For example, if a programmer wishes to copy a file item before altering it in a program, the COPY command might be used (rather than writing a new item with the WRITE statement). The COPY command requests the operator to supply the new item-ID, so the DATA statement could be used to store the new item-ID on the data stack before using EXECUTE to run the COPY command.
Before EXECUTE returns to the calling program, it checks the data stack for input. If the data stack is not empty, its contents will be sent to TCL. Any data left in the data stack will be cleared upon exit from EXECUTE.
Although the mvBASIC language has a SELECT statement for creating a select-list, the EXECUTE statement can be used to run one of the INFO/ACCESS select-list generators (e.g., SELECT, SSELECT, QSELECT). The INFO/ACCESS select-list generators are often preferable to the SELECT statement because they can include selection expressions. Selection expressions cannot be supplied with the mvBASIC SELECT statement.
A select-list generated by EXECUTE will be placed in the external select-list variable. The select-list will be unavailable to subsequent EXECUTE statements; however, the DATA statement can be used to stack a SAVE-LIST command to be executed before returning to the program, and a future EXECUTE statement can be used to run a GET-LIST to retrieve it. See Reading and Updating File Items later in this section for more information on select-lists.
To execute another mvBASIC program, the EXECUTE statement is recommended. However, there is an ENTER statement which acts only to execute another mvBASIC program and then exit without returning to the calling program.
The CAP-HUSH-ON command turns off the display of captured output for the issuing process. The CAP-HUSH-OFF command turns on the display of captured output for the issuing process. Both commands are most effectively used within an EXECUTE statement.
Windows command line commands can be executed by prefixing them with the bang (!) sign in an EXECUTE statement. The output from the executed command can be stored in a variable by use of the CAPTURING clause. For example:
|
EXECUTE "! dir /w " CAPTURING DirectoryList |
This example does a wide directory listing of the current directory using the Windows DIR command and puts the results into the mvBASIC variable DirectoryList.
See Also
Overview of mvBASIC Statements and Functions
Sending Output to the Screen and Printer
Reading and Updating File Items
Reading and Writing Tapes or Floppy Disks