## CALL

PURPOSE: Transfers control to a subroutine in the same or another program. Values are passed to and returned by an argument list in the statement.
STATEMENT SYNTAX:
{stno} CALL stno{,ERR=stno}{,arg list}
{stno} CALL progname{,ERR=stno}{,arg list}
where:
stno = a statement number within the same program where control is to pass.
progname = the name of an SM32 program.
arg list = a list of constants, variables, and expressions whose values are to be passed to the called subroutine or program.
EXAMPLE:
0100 CALL "SUBROUT01",A$,A1$,K(10),G
0325 CALL A$,T$,MONEY(ALL),T,G$,G1$
NOTES: See RUN for a description of how a program is loaded (CALL by program name).
The CALL statement causes the data area level(LEV system variable) to increase by 1. This new data area is cleared just as if a CLEAR statement had been executed.
The argument list contains 2 types of arguments:
1. Call by Reference: After the ENTER statement has been executed the memory in the calling level will be accessed/modified each time the linked variable is used in the called routine. Examples of call by reference variables are as follows:
0100 CALL "OVER",A
with ENTER N
A (in LEV-1) is updated every time N is accessed/modified in the called routine.
0100 CALL "OVER",A$
with ENTER N$
On a partial string assignment or a reference (N$(X,Y)= or N$(X)= or ..=N$+...) the string area for A$ (in LEV-1) will be accessed/modified. On a reassignment of N$ (N$=..) the memory currently assigned to A$ (in LEV-1) will be released and the memory required for N$ will be assigned to A$ (in LEV-1).
0100 CALL "OVER",A(ALL)
with ENTER N(ALL)
The corresponding element of array A (in LEV-1) is updated every time an element of array N is accessed/modified in the called routine. If array N is re-DIMdimed in the called routine array A (in LEV-1) is re-DIMdimed.
2. Call by Value: When the ENTER statement is executed the value from the call statement is assigned to the variable in the ENTER statement. Examples of call by value are as follows:
0100 CALL "OVER",5
0100 CALL "OVER",A(5)
0100 CALL "OVER",A*B
0100 CALL "OVER",0+A (force call by value)
with ENTER N
N receives the value from the call no number is returned at EXIT time.
0100 CALL "OVER","ABC"
0100 CALL "OVER",A$+B$
0100 CALL "OVER",A$(X,Y)
0100 CALL "OVER",""+A$ (force call by value)
with ENTER N$
N$ receives the string from the CALL no string is return at EXIT time.
0100 CALL "OVER",""+ A(ALL) (this forces call by value since A(ALL) is really a string) with ENTER N(ALL)
All of array A (from LEV-1) is moved into array N
Special Note:
If the program name ends in "[X]!!" where X is a number then the "[X]!!" is removed from the progarm name and TCB(9) is set to X. This allows multiple entry points into a program. TCB[9]=-1 if the "[X]!!" does not exist.
Example:

    100 CALL "MYPROG",A,B
    110 CALL "MYPROG[0]!!",A$,B$
    120 CALL "MYPROG[1]!!",A![ALL]
    ...
    ...
    0010 REM "MPROG"
    0020 IF TCB(9)=-1 GOTO 0100
    0030 IF TCB(9)=0 GOTO 2000
    0040 IF TCB(9)=1 GOTO 3000
    0050 ESCAPE
    ...
    ...
    0100 ENTER X,Y
    ...
    2000 ENTER X$,Y$
    ...
    3000 ENTER X![ALL]
    ...