Writing Subroutines and Functions
Subroutines and functions are routines made up of a sequence of
instructions that can receive data, process it, and return a value.
The routines can be:
- Internal
- The routine is within the current program , marked by a label, and only that program uses the routine.
- External
- A REXX subroutine that exists as a separate file.
In many aspects, subroutines and functions are the same. However,
they are different in a few major aspects, such as how to call them
and the way they return values.
- Calling a subroutine
To call a subroutine, use the CALL instruction followed by the subroutine name (label or program member name). You can optionally follow this with up to 20 arguments separated by commas. The subroutine call is an entire instruction.
CALL subroutine_name argument1, argument2,... - Calling a function
To call a function, use the function name (label or program member name) immediately followed by parentheses that can contain arguments. There can be no space between the function name and the left parentheses. The function call is part of an instruction, for example, an assignment instruction.
z = function(argument1, argument2,...) - Returning a value from a subroutine
A subroutine does not have to return a value, but when it does, it sends back the value with the RETURN instruction.
RETURN valueThe calling program receives the value in the REXX special variable named RESULT.SAY 'The answer is' RESULT - Returning a value from a function
A function must return a value. When the function is a REXX program , the value is returned with either the RETURN or EXIT instruction.
RETURN valueThe calling program receives the value at the function call. The value replaces the function call, so that in the following example, z = value.z = function(argument1, argument2,...)
Subroutines and functions: similarities and differences
The following tables highlight similarities and differences between subroutines and functions:
| Similarities between subroutines and functions |
|---|
Can be internal or external.
Uses the RETURN instruction to return to the caller. |
| Subroutines | Functions | |
|---|---|---|
| Calling | Call by using the CALL instruction, followed by the subroutine name and, optionally, up to 20 arguments. | Call by specifying the function's name, immediately followed by parentheses that optionally contain up to 20 arguments. |
| Returning a Value | Might return a value to the caller. If you include a value on the RETURN instruction, the language processor assigns this value to the REXX special variable RESULT. | Must return a value. Specify a value on the RETURN instruction; the language processor replaces the function call with this value. |
When to write subroutines instead of functions
The
actual instructions that make up a subroutine or a function can be
identical. It is the way you want to use them in
a program
that
turns them into either a subroutine or a function. For example, you
can call the built-in function SUBSTR as either a function or a
subroutine.
This is how to call SUBSTR as a function to shorten a word to its
first eight characters:
a = SUBSTR('verylongword',1,8) /* a is set to 'verylong'
*/
You
get the same results if you call SUBSTR as a subroutine.
CALL SUBSTR 'verylongword', 1, 8
a = RESULT /* a is set to 'verylong' */
When
deciding whether to write a subroutine or a function, ask yourself
the following questions:
- Is a returned value optional? If so, write a subroutine.
- Do I need a value returned as an expression within an instruction? If so, write a function.
The rest of this chapter describes how to write subroutines and functions and finally summarizes the differences and similarities between the two.