1.11.7. Variable Reference Term

A variable reference term represents a reference to a variable. Variable reference terms can be used as arguments to subroutines, functions, methods, or routines, thus allowing the original variable to be modified or created by the called Rexx code.

While subroutines, functions, methods, or routines can modify argument objects when accessed with the USE ARG instruction without using a variable reference, changing the value of arguments to new objects—like setting them to a new string, a new Array, or to .nil—can only be done using a variable reference term.

Variable reference terms start with either of the two reference operators, > or <, followed by a simple variable name or a stem variable name. Variable references to compound variables are not allowed.

Here is an example:

call dir >files, ".txt"
say files~items "files with extension .txt"

::routine dir
  use strict arg >array, extension = ""
  array = .Array~new
  do file over .File~new(".")~list
    if file~caselessEndsWith(extension) then
      array~append(file)
  end

Variable reference arguments and USE ARG names must match. They must either be both simple variable references, or both stem references. USE ARG variable references can never be optional, a default value is not allowed.