CALL statement

Syntax

CALL name [ ( [MAT] argument [ , [MAT] argument ...] ) ]
variable = 'name'
CALL @variable [ ( [MAT] argument [ , [MAT] argument ...] ) ]

Description

Use the CALL statement to transfer program control from the calling program to an external subroutine or program that has been compiled and cataloged.

Locally cataloged subroutines can be called directly. Specify name using the exact name under which it was cataloged. For more details, see The CATALOG Command on page 1-15.

External subroutines can be called directly or indirectly. To call a subroutine indirectly, the name under which the subroutine is cataloged must be assigned to a variable or to an element of an array. This variable name or array element specifier, prefixed with an at sign (@), is used as the operand of the CALL statement.

The first time a CALL is executed, the system searches for the subroutine in a cataloged library and changes a variable that contains the subroutine name to contain its location information instead. This procedure eliminates the need to search the catalog again if the same subroutine is called later in the program. For indirect calls, the variable specified in the CALL as the @variable is used; for direct calls, an internal variable is used. With the indirect method, it is best to assign the subroutine name to the variable only once in the program, not every time the indirect CALL statement is used.

arguments are variables, arrays, array variables, expressions, or constants that represent actual values. You can pass one or more arguments from the calling program to a subroutine. The number of arguments passed in a CALL statement must equal the number of arguments specified in the SUBROUTINE statement that identifies the subroutine. If multiple arguments are passed, they must be separated by commas. If an argument requires more than one physical line, use a comma at the end of the line to indicate that the list continues.

If argument is an array, it must be preceded by the MAT keyword, and the array should be named and dimensioned in both the calling program and the subroutine before using this statement. If the array is not dimensioned in the subroutine, it must be declared using the MAT keyword in the SUBROUTINE statement. Other arguments can be passed at the same time regardless of the size of the array.

The actual values of arguments are not passed to the subroutine. Instead, a pointer to the location of each argument is passed. Passing a pointer instead of the values is more efficient when many values need to be passed to the subroutine. This method of passing arguments is called passing by reference; passing actual values is called passing by value.

All scalar and matrix variables are passed to subroutines by reference. If you want to pass variables by value, enclose them in parentheses. When data is passed by value, the contents of the variable in the main program do not change as a result of manipulations to the data in the subroutine. When data is passed by reference, the memory location of the variable is changed by manipulations in both the main program and the subroutines. Constants are passed to subroutines by value.

When an array is passed to an external subroutine as an argument in a CALL statement, any dimensions assigned to the array in the subroutine are ignored. The dimensions of the original array as it exists in the calling program are maintained. Therefore, it is a common and acceptable practice to dimension the array in the subroutine with subscripts or indices of one. For example, you could dimension the arrays in the subroutine as follows:

DIM A (1), B (1, 1), C (1, 1)

When the corresponding array arguments are passed from the calling program to the subroutine at run time, arrays A, B, and C inherit the dimensions of the arrays in the calling program. The indices in the DIMENSION statement are ignored.

A better way to declare array arguments in a subroutine is to use the MAT keyword of the SUBROUTINE statement in the first line of the subroutine. The following example tells the subroutine to expect the three arrays A, B, and C:

SUBROUTINE X(MAT A, MAT B, MAT C)

When a RETURN statement is encountered in the subroutine, or when execution of the subroutine ends without encountering a RETURN statement, control returns to the statement following the CALL statement in the calling program. For more details, see the RETURN statement.

Examples

The following example calls the local subroutine SUB. It has no arguments.

CALL SUB

The following example calls the local subroutine QTY.ROUTINE with three arguments:

CALL QTY.ROUTINE(X,Y,Z)

The following example calls the subroutine cataloged as *PROGRAM.1 with six arguments. The argument list can be expressed on more than one line.

AAA="*PROGRAM.1"
CALL @AAA(QTY,SLS,ORDER,ANS,FILE.O,SEQ)

The following example calls the subroutine *MA with three arguments. Its index and three arguments are passed.

STATE.TAX(1,2)='*MA'
CALL @STATE.TAX(1,2)(EMP.NO,GROSS,NET)

The following example calls the subroutine cataloged as *SUB and two matrices are passed to two subroutine matrices. A third, scalar, argument is also passed.

GET.VALUE="*SUB"
DIM QTY(10)
DIM PRICE(10)
CALL @GET.VALUE( MAT QTY,MAT PRICE,COST )

The following example shows the SUBROUTINE statement in the subroutine SUB that is called by the preceding example. The arrays Q and P need not be dimensioned in the subroutine.

SUBROUTINE SUB( MAT Q,MAT P,C )