Call instruction

The call instruction is used for two purposes.

1. to invoke an internal or external procedure as a subroutine

2. to activate/deactivate a condition trap subroutine handler

Subroutine call

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:

1. internal procedure -- unless the procedure name was enclosed in quotes
2. built-in function
3. external procedure

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 */

Processing state information is SAVED during function and subroutine calls

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.

pending control structures

• if ... then ... else ...
• do ... end
• do i=1 to n ... end [and similar do loops]
• select when ... then ... ...etc otherwise ... end

numeric option settings

digits, fuzz, form

command address settings

current and saved destinations

pending condition handler information

call/signal on : error, failure, halt, notready, novalue, syntax

pending condition information

information that is returned by the condition built-in function

settings associated with the options instruction

note: support for the options instruction is implementation-dependent, and the settings may not be saved and restored during function or subroutine calls.

elapsed time clock

a function or subroutine can alter the setting of the elapsed time clock, which is provided by the time built-in function, without affecting the setting that is used in the calling procedure.

trace settings

a function or subroutine can alter trace settings, which are established by the trace instruction or the trace built-in function, without affecting the settings that are used in the calling procedure.

Trap subroutine call activation/deactivation

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:

• ERROR

• FAILURE

• HALT

• NOTREADY

Unlike the signal ON or OFF trap anticipation instructions, the following condition names are ineligible in a call ON or OFF instruction:

• SYNTAX
• NOVALUE

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.