CALL

Call a Public Program

This directive executes a public program, passing and receiving data, without disturbing the environment of the main program, which CALLed the public program.

Syntax

CALL program-name [,ERR=line-ref|,ERC=error-code] [,value-list]

program-name: is a string of characters that names the public program and its program file.
line-ref: is the program line number or label to branch to if this directive produces an error.
value-list: is a list of numeric and/or string variables and constants passed to the public program.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

This directive searches the opened object libraries, then the logical disk directories until it finds the public program file specified by program-name. It loads the file into memory and begins execution of the public program at its first program line.

Use of the ADDR directive saves the overhead time required to locate and load the public program when CALLed.

When a CALLed public program is completed, execution of the calling program is transferred to the statement following the CALL directive.

The CALL directive can be executed from a public program or a non-public program. For example, a public program can CALL another public program, which can call another public program up to 127 levels of nesting.

The optional value-list contains values (constants or variables) that are used to transfer selected data to the public program and to designate which variables receive data back from the public program when it returns.

The optional value-list is passed to the public program when execution encounters an
ENTER directive in the public program.

Any return variables are set when the public program executes an EXIT directive.

The variable names do not have to be the same in the CALL directive and the public program’s ENTER directive, but they must match in order sequence and type (see EXAMPLES below).

If program-name cannot be found, an ERR=12 results.

If program-name is not a program file, an ERR=17 results.

If the value-list in the CALL directive does not match the ENTER directive in the public program, an ERR=36 or ERR=42 results in the public program.

Numeric and string arrays used in the CALL/ENTER linkage must use the ALL option to pass the full array if the CALLing program expects the public program to change the data in the array. Single-element array values can be passed to the public program but changes made within the public program are not sent back to the CALLing program. Similarly, substring references are not sent back to the CALLing program.

Examples

CALL "PUBLIC1"

This example loads and executes the PUBLIC1 public program. If PUBLIC1 has no ENTER statement then no data is passed back and forth between these programs. If PUBLIC1 has an ENTER statement with no variable-list, then all variables from the CALLing program are available to the PUBLIC1 public program.

CALL A$, ERR=CALL-ERROR,A,D[ALL],D%,E%[1],C$,"XYZ",X$+"1"

If A$=“PUBLIC1”, this has the same effect as the first example. If an error occurs while processing this directive the program branches to the CALL-ERROR line label.

This example shows that the CALL is passing 7 items in its value-list: a numeric variable, a numeric array, an integer variable, an integer array element, a string variable, a string constant, and a string expression. The ENTER directive in the public program must have a variable-list of 7 variables that match the order sequence and type. If the public program’s variable-list does not correctly match the CALLing program’s value-list an ERR=36 or ERR=42 results.

CALL

Syntax

Remarks

Examples

See also