Kilowatt Software's
Classic Rexx Tutorial
Language Level 4.00 (TRL-2)

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

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.

The above program would normally use a function call instead. The following shows how the main program would be coded in this case.

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.

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.


Trap subroutine call activation/deactivation

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.


Kilowatt Software's -- Classic Rexx Tutorial -- Back to top
Click here if you have any comments or questions regarding this tutorial

Last updated on: 31 Aug 2002