7.2.1. Search Order

Functions are searched in the following sequence: internal routines, built-in functions, external functions.

Function calls or subroutines may use a name that is specified as a symbol or a literal string. For example, these calls are equivalent:

    call MyProcedure
    call 'MYPROCEDURE'

Note that the name value when specified as a symbol is the symbol name translated to upper case. Both of the calls above will search for a routine named "MYPROCEDURE". When the name is specified as a literal string, then the literal string value is used as-is. Thus the following two calls are not equivalent:

    call MyProcedure    -- calls "MYPROCEDURE"
    call 'MyProcedure'  -- calls "MyProcedure"

Some steps of the function and subroutine search order are case sensitive, so some care may need to be exercised that the correct name form is used:

Internal routines. Normally, labels are specified as a symbol followed by a ":". These labels have a name value that's all uppercase. Since unquoted (symbol) names also have uppercase values, these will match easily. It is also possible to use literal strings for label names. If these labels contain lowercase characters, they will not be located using normal call mechanisms

Built-in functions. The built-in function names are all uppercase, so using a mixed-case literal string built-in function name will fail to locate the function.

    x = wordPos(needle, haystack)     -- calls "WORDPOS", which works
    x = "wordPos"(needle, haystack)   -- calls "wordPos", which will fail

External routines. Some steps of the external function search order may be case sensitive, depending on the system. This may occasionally require a function or subroutine name to be specified as a mixed case literal string to be located.

If the call or function invocation uses a literal string, then the search for internal label is bypassed. This bypass mechanism allows you to extend the capabilities of an existing internal function, for example, and call it as a built-in function or external routine under the same name as the existing internal function. To call the target built-in or external routine from inside your internal routine, you must use a literal string for the function name.

Example 7.2. DATE function — overriding

/* This internal DATE function modifies the          */
/* default for the DATE function to standard date.   */
date: procedure
  arg in
  if in="" then in="Standard"
  -- This calls the DATE built-in function rather than recursively
  -- calling the DATE: internal routine.  Note that the name needs to
  -- be all uppercase because built-in functions have uppercase names.
  return "DATE"(in)

Since built-in functions have uppercase names the literal string must also be in uppercase for the search to succeed.

External functions and subroutines have a system-defined search order.

The search order for external functions is as follows:

Functions defined on ::ROUTINE directives within the program.
Public functions defined on ::ROUTINE directives of programs referenced with ::REQUIRES.
Functions that have been loaded into the macrospace for preorder execution. (See the Open Object Rexx: Application Programming Interfaces for details.)
Functions that are part of a function package or library package. (See the Open Object Rexx: Application Programming Interfaces for details.)
Rexx functions located in an external file. See below for how these external files are located.
Functions that have been loaded into the macrospace for postorder execution.