SUBROUTINE Statement
Identifies a DataBasic module as an external subroutine that can be called by other DataBasic programs.
Syntax
SUB{ROUTINE} {name} {(parameterList)}
Syntax Elements
name The name of the subroutine. If supplied, should be the same as the item-id. Subroutine names must obey the rules for identifiers.
Note
When the subroutine is compiled, the item-id is used as the subroutine name (name is ignored).
parameterList A comma-separated list of parameters, representing the values passed to the subroutine. Each parameter has the following syntax:
{MAT }paramName
MAT Specifies that the parameter is a dimensioned array. The array must be dimensioned within the subroutine before being used.
paramName The parameter name. Parameter names must obey the rules for identifiers.
Comments
An external subroutine must contain a SUBROUTINE statement, a RETURN statement, and (preferably) an END statement. Except for comments, $OPTIONS and INCLUDE statements, SUBROUTINE must be the first statement in the program.
An external subroutine must be executed by means of the CALL statement. The number and types of parameters passed to the subroutine must match those declared in the SUBROUTINE statement. If there is a mismatch, an error message is displayed and the program enters the debugger.
External subroutines must be cataloged (see the CATALOG command for details). It is recommended that you also catalog the calling program, because this will make your program more efficient.
The ENTER and CHAIN statements cannot be used to execute external subroutines. Nor can external subroutines be executed from TCL.
You cannot use the ENTER statement to run another program from within an external subroutine.
Passing Data
Data can be passed from the calling program to the subroutine and back again through:
-
The parameters in the argument list.
-
COMMON variables.
It is strongly recommended that you do not use the same name for more than one parameter, whether passed in the argument list or in COMMON variables.
Note
Data can also be passed by DATA statements in the calling program and INPUT statements in the subroutine and vice versa.
For more details about passing data, refer to the CALL statement.
Internal Subroutines
An external subroutine can itself contain internal subroutines (each starting with a statement label and ending with a RETURN statement) called with GOSUB or ON GOSUB statements. If a RETURN is encountered for which there is no corresponding GOSUB or ON GOSUB statement, the external subroutine returns.
Program Termination
If a STOP or CHAIN statement is executed before the subroutine's END statement, control never returns to the calling program.
Precision
A calling program and the corresponding subroutine do not need to have the same precision. When a value is passed back to the calling program, the value retains the precision used in the subroutine (until an operation is performed that changes its precision, as defined in the description of the PRECISION statement).
Examples
SUBROUTINE REPORT
CALL REPORT
Called subroutine REPORT has no parameters.
SUBROUTINE ADD(X, Y, Z)
CALL ADD(A + 2, F, 395)
Subroutine ADD is passed three parameters. On return to the calling routine, any changes to the variable Y made in the subroutine are returned to the calling routine as the value of variable F. Changes to X and Z are not returned to the calling routine.
SUBROUTINE VENDOR(NAME, ADDR, NUM)
CALL VENDOR(NAME, ADDRESS, NUMBER)
Subroutine VENDOR accepts and returns three values.
SUBROUTINE ARYSUB(MAT ARY, INDEX)
DIM ARY(10)
DIM MYDATA(10)
.
.
.
CALL ARYSUB(MAT MYDATA, ELEMENT)
Subroutine ARYSUB accepts and returns two values, the first of which must be a dimensioned array with 10 elements.