.-,--------------.                  
                V                |                  
>>-CALL--+-name---+------------+-+-----------+--;--------------><
         |        '-expression-'             |      
         +-OFF-+-ERROR---+-------------------+      
         |     +-FAILURE-+                   |      
         |     '-HALT----'                   |      
         '-ON-+-ERROR---+-+----------------+-'      
              +-FAILURE-+ '-NAME--trapname-'        
              '-HALT----'                           

To call a routine, specify name, a literal string or symbol that is taken as a constant. The name must be a symbol, which is treated literally, or a literal string. The routine called can be:

An internal routine

A function or subroutine that is in the same program as the CALL instruction or function call that calls it.

A built-in routine

A function (which may be called as a subroutine) that is defined as part of the REXX language.

An external routine

A function or subroutine that is neither built-in nor in the same program as the CALL instruction or function call that calls it.

The called routine can optionally return a result, and when it does, the CALL instruction is functionally identical with the clause:

                 .-,--------------.         
                 V                |         
>>-result=name(----+------------+-+--)--;----------------------><
                   '-expression-'           

The CALL then causes a branch to the routine called name, using exactly the same mechanism as function calls. (See Functions.) The search order is in the section on functions (see Search order) but briefly is as follows:

Internal routines:

These are sequences of instructions inside the same program, starting at the label that matches name in the CALL instruction. If you specify the routine name in quotation marks, then an internal routine is not considered for that search order. You can use SIGNAL and CALL together to call an internal routine whose name is determined at the time of execution; this is known as a multi-way call (see SIGNAL). The RETURN instruction completes the execution of an internal routine.

Built-in routines:

These are routines built into the language processor for providing various functions. They always return a string that is the result of the routine (see Built-in functions).

External routines:

Users can write or use routines that are external to the language processor and the calling program. You can code an external routine in REXX or in any language that supports the system-dependent interfaces. For information about using the system-dependent interfaces, see External functions and subroutines, and function packages. For information about the search order the system uses to locate external routines, see Search order. If the CALL instruction calls an external routine written in REXX as a subroutine, you can retrieve any argument strings with the ARG or PARSE ARG instructions or the ARG built-in function.

Example:

/* Recursive subroutine execution... */
arg z
call factorial z
say z'! =' result
exit

factorial: procedure     /* Calculate factorial by  */
  arg n                  /*  recursive invocation.  */
  if n=0 then return 1
  call factorial n-1
  return  result * n

During internal subroutine (and function) execution, all important pieces of information are automatically saved and are then restored upon return from the routine. These are:

• The status of DO loops and other structures: Executing a SIGNAL while within a subroutine is safe because DO loops, and so forth, that were active when the subroutine was called are not ended. (But those currently active within the subroutine are ended.)
• Trace action: After a subroutine is debugged, you can insert a TRACE Off at the beginning of it, and this does not affect the tracing of the caller. Conversely, if you simply wish to debug a subroutine, you can insert a TRACE Results at the start and tracing is automatically restored to the conditions at entry (for example, Off) upon return. Similarly, ? (interactive debug) and ! (command inhibition) are saved across routines.
• NUMERIC settings: The DIGITS, FUZZ, and FORM of arithmetic operations (in NUMERIC) are saved and are then restored on return. A subroutine can, therefore, set the precision, and so forth, that it needs to use without affecting the caller.
• ADDRESS settings: The current and previous destinations for commands (see ADDRESS) are saved and are then restored on return.
• Condition traps: (CALL ON and SIGNAL ON) are saved and then restored on return. This means that CALL ON, CALL OFF, SIGNAL ON, and SIGNAL OFF can be used in a subroutine without affecting the conditions the caller set up.
• Condition information: This information describes the state and origin of the current trapped condition. The CONDITION built-in function returns this information. See CONDITION.
• Elapsed-time clocks: A subroutine inherits the elapsed-time clock from its caller (see TIME), but because the time clock is saved across routine calls, a subroutine or internal function can independently restart and use the clock without affecting its caller. For the same reason, a clock started within an internal routine is not available to the caller.
• OPTIONS settings: ETMODE and EXMODE are saved and are then restored on return. For more information, see OPTIONS.