CALL Verb

Syntax

CALL fileid{::label}{,ERR=lineref}{,expr...}

Description

For BBj-specific information, see CALL Verb - BBj.

The CALL verb invokes another program as if it was a subroutine and is used for writing common procedures, such as printer select programs, without conflicting variable names. The called program, also referred to as a "public program," executes with its own variables. See the Program and Workspace Management section in the User's Reference Guide for a detailed discussion on public programs.

To create public programs that can act as event handler libraries and related routines, the fileid parameter can contain an embedded label reference, preceded by two colons (::), to specify the location for starting the called program. A distinct ENTER statement can exist for each entry point. If the specified label does not exist, PRO/5 will issue an !ERROR=21 in the public program.

An argument list can be specified to pass data to and from the called program. PRO/5 supports both call-by-reference and call-by-value arguments.

A call-by-reference argument is a numeric variable, integer variable, or simple string variable. The called program returns values to the calling program through these arguments. An entire array can be passed by reference using X[ALL], where X is any array name. PRO/5 can pass a nondimensioned array without an error but does issue an error when the called program accesses the array.

Any other argument is a call-by-value argument. The called program receives the value of the argument from the calling program, but the called program cannot return a value to the calling program through this argument.

In the example below, the first three arguments are call-by-reference arguments because they are simple variables or arrays:

>CALL "PROG",A,B$,A0[ALL],(A),X+3,D$(1,4),F[30],"XX"

The remaining arguments are call-by-value arguments because:

(A) is a simple variable forced by parentheses to be a value argument.
X+3 is an expression.
D$(1,4) is a subscripted string (not considered a simple variable).
F[30] is a single array element.
"XX" is a constant.

The same call-by-reference argument can only appear once in the argument list. The ENTER statement in the called program completes the linkage to the arguments.

File channels are global. The calling program and the called program share all file channels. Channels opened in the called program are not automatically closed when control returns to the calling program.

PRO/5 executes the CALL statement in two steps: 1) it processes the argument list, and 2) it locates the called program in memory or on disk and loads it using the LOAD verb if necessary.

Execution continues with the first statement of the called program. EXIT, END, and STOP verbs are used in the called program to return to the calling program.

PRO/5 uses the optional ERR= branch if there is an error in the argument list, an error in loading the program, or if the called program EXITs with an error. See ESCAPE Handling in the User's Reference Guide for additional information.

Saved Information

PRO/5 saves the following information when a program is called and restores it on EXIT from the called program:

Variables, except those passed by reference, or unless the called program chooses to share all variables (see ENTER for additional information).
Error retry information.
Current arithmetic precision.
SETERR value.
SETESC value.
Active GOSUBs, FOR .. NEXT, REPEAT .. UNTIL, and WHILE .. WEND loops.
DATA statement pointer.

Reset Information

PRO/5 resets the following items when the called program is entered:

Variables.
SETERR value.
SETESC value.
Error retry information
GOSUB, FOR .. NEXT, REPEAT .. UNTIL, and WHILE .. WEND information
DATA statements.

A public program may be edited if the appropriate OPTS bit is set. Enabling this bit causes PRO/5 to allocate additional space for a public program.

NOTE: Public programs are not shared in memory between multiple users on a multi-user system because of the limited identification between two programs having the same name on the same system. PRO/5 identifies a public program by name, and, therefore, cannot share programs between multiple users. Similarly, on a system that folds case, PRO/5 cannot distinguish between a program named "ABC" and the same program named "abc."

Examples