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 value
```
The 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 value
```
The 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,...)
```

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.

Subroutines and functions: similarities and differences

Subroutines and functions have the following similarities:

They can be internal or external.
- Internal
  - Can pass information by using common variables
  - Can protect variables with the PROCEDURE instruction
  - Can pass information by using arguments.
- External
  - Must pass information by using arguments
  - Can use the ARG instruction or the ARG built-in function to receive arguments.
They use the RETURN instruction to return to the caller.

Table 1. Differences between subroutines and functions
	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.