The call instruction is used for two purposes.
|call procedureName [ argumentExpression [ , argumentExpression [ , ...etc ] ]|
This form of the call instruction invokes an internal or external procedure named procedureName, or a built-in function, as a subroutine. A series of arguments can optionally be prepared by the argumentExpression values. These arguments can be acquired in the subroutine by using either the parse arg or arg instructions, or the arg built-in function. The subroutine can optionally return a result, which can be acquired by referencing the special RESULT variable. Often the result can be processed directly in-place, by using a function call instead.
The name provided as procedureName can be provided as a quoted string -- e.g. 'X2C'. When it is a quoted string, an internal procedure is not invoked, and a built-in function or external procedure is invoked instead. When a built-in function is invoked, using this technique, the name in quotes should be in upper case.
The search order for the target procedure, or built-in function is:
The mechanism for locating and activating an external procedure is implementation-dependent.
Click here to study the procedure instruction.
Click here to review the structure of Rexx programs and procedures.
Here is an example of a subroutine invocation using the call instruction.
/* main program */ do n=1 to 5 call factorial n say 'The factorial of' n 'is:' RESULT end return factorial : procedure n = arg(1) if n = 1 then return 1 return n * factorial( n - 1 )
The above program would normally use a function call instead. The following shows how the main program would be coded in this case.
/* main program */ do n=1 to 5 say 'The factorial of' n 'is:' factorial( n ) end return
Normally, you use the call instruction to invoke a function, when you will ignore (or not require) a return value. The following shows how the value built-in function is invoked as a subroutine.
call VALUE 'Destination', 'Nice', 'Vacation' /* assigns new destination */
The processing state of the following information is saved when a function or subroutine call is performed. The state of this information is restored when the function or subroutine returns.
call ON conditionName [ NAME trapLabel ]
call OFF conditionName
The call ON or OFF instructions activate or deactivate the handling of condition traps by an associated procedure. When active, a conditional trap will cause the trapLabel to be invoked as a subroutine. In a call ON instruction, if the trapLabel is absent, the label that is invoked is the same as the condition name. The handling of condition traps can alternatively be activated or deactivated by the signal ON or OFF instructions.
The conditionName in the call ON or OFF is one of the following:
Unlike the signal ON or OFF trap anticipation instructions, the following condition names are ineligible in a call ON or OFF instruction:
Click here to review the Rexx condition handling.
Note: the call ON or OFF instructions were introduced in Rexx Language Level 4.00 (TRL-2). Consequently this capability may not be available in all implementations.