SUBROUTINE Statement

Identifies a DataBasic module as an external subroutine that can be called by other DataBasic programs.

Syntax

SUB{ROUTINE} {name} {(argument-list)}

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 however, that when the subroutine is compiled, the item-id is used as the subroutine name (name is ignored).

argument-list One or more expressions, separated by commas, representing the values passed to the subroutine. The number of parameters passed from the CALL statement to the SUBROUTINE statement must match. If not, an error message is displayed and the program enters the debugger.

Comments

A CALL statement transfers control to a cataloged subroutine name. Both the calling program and the external subroutine must be cataloged. An external subroutine cannot, however, be executed from TCL.

An external subroutine must contain a SUBROUTINE statement, a RETURN statement, and (preferably) an END statement. SUBROUTINE must be the first statement in the program.

Passing Data

Data can be passed from the calling program to the subroutine and back again through:

the argument-list;
COMMON variables;
DATA and INPUT statements.

For more details about passing data, refer to the CALL statement.

Internal Subroutines

GOSUB and RETURN combinations can be used in a subroutine. If a RETURN is executed and there is no corresponding GOSUB statement, the program returns control to the statement following CALL in the calling program.

Program Termination

If a STOP, CHAIN or ENTER statement is executed before the subroutine's END statement, control never returns to the calling program.

The CHAIN statement should not be used to chain from an external subroutine to another DataBasic program.

The ENTER statement should not be used to execute a SUBROUTINE.

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

CALL REPORT
.
.
.
SUBROUTINE REPORT

Called subroutine REPORT has no parameters.

CALL ADD (A+2,F,395)
.
.
.
SUBROUTINE ADD (X,Y,Z)

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.

CALL VENDOR (NAME, ADDRESS, NUMBER)
.
.
.
SUBROUTINE VENDOR (NAME, ADDR, NUM)

Subroutine VENDOR accepts and returns three values.