CALL and CALLS

ANSI

The CALL and CALLS instructions initiate a subroutine or function. Repetitive procedures may be coded into a single subroutine or function and initiated through a CALL. When the CALL or CALLS instruction is executed, the address of the next sequential instruction is placed as the top element of the subroutine call stack and control is transferred to the address specified by the first operand. The instructions use one of the following formats:

(1)	[label]	CALL	{routine}[GIVING {return}]
(2)	[label]	CALL	{routine} [GIVING {return}] IF [NOT] {flag}
(3)	[label]	CALL	{routine} [GIVING {return}] IF {expression}
(4)	[label]	CALL	{routine} [GIVING {return}] USING {parameters}
(5)	[label]	CALLS	{name} [GIVING {return}]
(6)	[label]	CALLS	{name} [GIVING {return} USING {parameters}

Where:

label

Optional. A Program Execution Label.

routine

Required. A Program Execution Label or string Literal containing the name of the subroutine or FUNCTION.

return

Optional. A Character String Variable, Numeric Variable, or Object that receives the return value from the {routine}.

name

Required. A previously defined Character String Variable or string Literal containing the name of the subroutine.

flag

Required. One of the condition, pseudo condition or function Flags that determines if the CALL should occur.

expression

Required. An Expression that, if true, causes the program to call the specified label.

parameters

Optional. A list of previously defined variables that are passed to the named subroutine.

Flags Affected: Any tested Function Key flag

Note the following:

Function Flags (Function keys) are cleared if tested and found TRUE. All other Flags remain unchanged.
Format (2) or (5) initiates the subroutine or function designated by {routine} only if the {flag} is as specified, set or not set (FALSE). Otherwise, execution continues with the next sequential instruction.
Format (3) or (6) initiates the subroutine or function designated by {routine} only if {expression} evaluates to a true condition. Otherwise, execution continues with the next sequential instruction.
If a FILEPI instruction is active, the FILEPI count is not decremented by this instruction.
A RETURN instruction within the destination subroutine or function or a FUNCTIONEND in the destination function returns execution to the next sequential instruction after the CALL. A NORETURN within the destination subroutine destroys the stack return reference of the last CALL.
Execution of a CHAIN instruction clears the call stack.
If the subroutine called is external to the program, an EXTERNAL instruction must be defined to inform the compiler that the subroutine is not contained in the program. The names provided in the EXTERNAL statement or the string variable are not case sensitive (Unless the PLB_CASE=ON environment variable is set).
If the separately compiled subroutine has not been previously loaded with a prior CALL or by using the LOADMOD instruction, it is loaded dynamically at the time of this CALL or CALLS.
The optional [USING {parameters}] signifies a parameterized CALL instruction. The target of the CALL must be a subroutine defined by the ROUTINE, LROUTINE, FUNCTION, LFUNCTION or PROCEDURE instructions. Each variable in the parameter list must correspond to a variable of the same type for the receiving instruction. It is possible to mix DIM and FORM types if the receiving instruction is a PROCEDURE. If corresponding variables are not of the same data type, an F05 error occurs.
Any variable type may be used in the parameters list for the CALL instruction.
When calling a ROUTINE, LROUTINE, FUNCTION, or LFUNCTION, the variables in the corresponding list for the ROUTINE, LROUTINE, FUNCTION, or LFUNCTION instruction should be defined as pointer variables. If defined in this manner, all argument passing is done by variable addresses and any variable modified in the subroutine or function modifies the original variable (call by reference).
If any DIMs, FORMs, or INTEGERs in the ROUTINE, LROUTINE, FUNCTION, or LFUNCTION list are defined as simple variables, the passing of information to the ROUTINE, LROUTINE, FUNCTION, or LFUNCTION is by value. That is, an internal MOVE instruction is performed to move the contents of the variable specified on the CALL instruction to the contents of the variable specified on the ROUTINE,LROUTINE, FUNCTION or LFUNCTION instruction (call by value).
When calling a PROCEDURE, the variables in the corresponding list for the instruction must be defined as real variables. The passing of information is by value. That is, an internal MOVE instruction is performed to move the contents of the variable specified on the CALL instruction to the contents of the variable specified on the PROCEDURE instruction.
If more variables are specified in the CALL parameter list than in the called routine or function list, the extra variables are ignored. If more variables are specified in the called routine or function list than in the CALL list, the extra variables are left as previously defined. Care should be taken in this instance to make sure that at least one CALL has been performed that initializes all variables in the ROUTINE, LROUTINE, FUNCTION, or LFUNCTION list.
If more variables are specified in the CALL parameter list than in the PROCEDURE list, the extra variables are ignored. If more variables are specified in the PROCEDURE list than in the CALL parameter list, the extra variables are blanked or zeroed.
The GIVING clause indentifies the receiving variable for data returned by the routine.
Common Data is not propagated to LOADMOD modules and does not require data alignment. Any calling routine variables needed in a LOADMOD module should be declared as GLOBAL or passed as arguments to the ROUTINE or PROCEDURE in the module.
The CALLS instruction (non-ANSI) uses a string variable or string literal to contain the name of the subroutine. Both the name of a separately compiled module and the name of actual subroutine called may be given if separated by a semi-colon. The routine called may be local to the executing module or in an external module. If no module name is given, an attempt is made to locate the label in the program.
Any separately compiled modules that have been loaded explicitly or implicitly are unloaded when a program chains to another program by using a CHAIN, STOP, or DSCNCT instruction. Any global data items that have been defined remain defined in the global data area.
To create a unique instance of a LOADMOD routine, prepend an instance number and a vertical bar to {name}. Each instance of the LOADMOD maintains it own copy of any variables defined within the LOADMOD.
The module name format allowed for load module operations allows a SWDBC form that identifies an instance string. The instance string in this case is transformed into a Sunbelt alias name. The alternate runtime module name format is as follows:

modulename<instance>;procedure