CALL Statement
Transfers control to an external subroutine.
Syntax
CALL ctlgName {(argumentList)}
CALL @ctlgVar {(argumentList)}
Syntax Elements
ctlgName The name of the cataloged external subroutine. This must be compiled and cataloged separately from the program(s) that calls it.
ctlgVar A variable that evaluates to the name of the cataloged subroutine to be called.
CALL @ctlgVar is the indirect form of the CALL statement. The argument list performs the same function as in a direct call.
Note
The subroutine's catalog entry must be in the MD of the current account. You cannot specify a different account.
argumentList One or more expressions, separated by commas, representing actual values passed to the subroutine. The called subroutine must have the same number of items in its argumentList; if the numbers of items differ, an error message is displayed and the program enters the debugger.
Dimensioned arrays can be passed to external subroutines by prefixing the array name with the MAT keyword and a space (see Example 5). The parameter concerned must have been declared as an array in the subroutine and the array passed must have the same number of elements as in this declaration (it is recommended that you use a constant to specify the sizes of both arrays).
Passing Data
Data can be passed from the calling program to the subroutine and back again through:
-
The argument list.
The variables and values in the argument list of the calling program are passed to the called subroutine's parameters; any variable names used in the two lists are independent of each other.
Variables in a CALL statement (including elements of dimensioned arrays) are normally passed by reference, while literals, symbols and expressions are passed by value. For variables passed by reference, values set within the subroutine are returned to the calling program.
It is strongly recommended that you avoid using the same variable more than once in argumentList (including passing one element of a dimensioned array and the whole array). If this is done, should the subroutine change any of these variables, the values returned to the calling program will be unpredictable.
-
COMMON variables.
In terms of execution time, passing data by means of COMMON variables is the most efficient way. COMMON variables in the subroutine must be declared in the same order as in the calling program and must match them in number and type, but their names can be different.
It is recommended that you do not include COMMON variables in the argument list.
Note
Data can also be passed by DATA statements in the calling program and INPUT statements in the subroutine and vice versa.
Example 1
CALL REVERSE (A,B)
Calls the external subroutine called REVERSE, passing the parameters A and B.
Example 2
CALL ADD (A+2,F,X)
Calls the external subroutine called ADD, passing the parameters A+2, F and X.
Example 3
CALL REPORT
Calls the external subroutine called REPORT; no parameters are passed.
Example 4
VAR = "SUB" IF X > 10 THEN VAR=VAR:1 ELSE VAR=VAR:2 CALL @VAR
If variable X is greater than 10, subroutine SUB1 is invoked. If variable X is less than 10, subroutine SUB2 is invoked.
Example 5
In the subroutine module:
SUB SUB1(MAT VEC, SVAR)
DIM VEC(4)
In the calling program:
DIM MATR(2,2)
CALL SUB1(MAT MATR, CVAR)
Array MATR is passed to subroutine SUB1 together with variable CVAR (these these have different names within SUB1). Any changes to them in SUB1 are returned to the calling routine. Elements of MATR are copied to and from VEC as described for the MAT statement.