CALL Statement

Transfers control to an external subroutine.

Syntax

CALL ctlg-name {(argument-list)}

CALL @ctlg-var {(argument-list)}

Syntax Elements

ctlg-name The name of the cataloged external subroutine. This must be compiled and cataloged separately from the program(s) that calls it.

ctlg-var A variable that evaluates to the name of the cataloged subroutine to be called.

CALL @ctlg-var 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 current account. You cannot specify a different account.

argument-list 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 argument-list; if the number of items differ, an error message is displayed and the program enters the debugger.

The use of an intrinsic function as the expression in an argument list is illegal.

Passing Data

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

The argument-list parameter.
COMMON variables.

The variables and values in the argument-list of the calling program are passed to the variables in the argument-list of the called subroutine. However, the variable names in the two lists are independent of each other. The same variable must not appear more than once in the argument-list. This includes passing one element of a dimensioned array and the whole array. COMMON variables must not appear in the argument-list.

Note: To pass a whole dimensioned array, precede the array name by MAT and a space in both CALL and SUBROUTINE argument lists, and include a DIM statement in the subroutine (see Example 5).

Variables in a CALL statement (including elements of dimensioned arrays) are passed by reference; literals, symbols and expressions are passed by value. The data contained by variables passed by reference, and changed by the external subroutine, are copied back to the calling program when a RETURN is executed in the subroutine.

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.

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

DIM MATR(2,2)
CALL SUB1(MAT MATR, CVAR)
.
.
SUB SUB1(MAT VEC, SVAR)
DIM VEC(4)

Array MATR is passed to subroutine SUB1 together with variable CVAR. These are renamed for use in 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.