3.9. ::ROUTINE

The ::ROUTINE directive creates named routines within a program.

The routinename is a literal string or a symbol that is taken as a constant. Only one ::ROUTINE directive can appear for any routinename in a program.

If the EXTERNAL option is not specified, the ::ROUTINE directive starts a routine, which is ended by another directive or the end of the program.

If you specify the PUBLIC option, the routine is visible beyond its containing Rexx program to any other program that references this program with a ::REQUIRES directive. If you do not specify the PUBLIC option, or specify the PRIVATE option, the routine is visible only within its containing Rexx program.

Routines you define with the ::ROUTINE directive behave like external routines. In the search order for routines, they follow internal routines and built-in functions but precede all other external routines.

Example 3.15. ROUTINE examples

::class c
::method a
call r "A"  /* displays "In method A" */

::method b
call r "B"  /* displays "In method B" */

::routine r
use arg name
say "In method" name

If the EXTERNAL option is specified, then spec identifies a routine in an external native library that will be defined as the named routine for this program. The spec is a literal string containing a series of whitespace delimited tokens defining the external function. The first token identifies the type of native routine to locate:

LIBRARY: Identifies a routine in an external native library of the type supported by the ::REQUIRES directive. The second token must identify the name of the external library. The external library is located using platform-specific mechanisms for loading libraries. For Unix-like systems, the library name is case-sensitive. The third token is optional and specifies the name of the routine within the library package. If not specified, the ::ROUTINE name is used. The routine name is not case sensitive.
REGISTERED: Identifies a routine in an older-style Rexx function package. The second token must identify the name of the external library. The external library is located using platform-specific mechanisms for loading libraries. For Unix-like systems, the library name is case-sensitive. The third token is optional and specifies the name of the function within the library package. If not specified, the ::ROUTINE name is used. Loading of the function will be attempted using the name as given and as all uppercase. Using REGISTERED is the equivalent of loading an external function using the RXFUNCADD built-in function.

Example 3.16. ROUTINE EXTERNAL examples

-- load a function from rxmath library
::routine RxCalcPi external "LIBRARY rxmath"
-- same function, but a different internal name
::routine Pi external "LIBRARY rxmath RxCalcPi"
-- same as call rxfuncadd "SQLLoadFuncs", "rexxsql", "SQLLoadFuncs"
::routine SQLLoadFuncs EXTERNAL "REGISTERED rexxsql SQLLoadFuncs"

Notes:

It is an error to specify ::ROUTINE with the same routine name more than once in the same program. It is not an error to have a local ::ROUTINE with the same name as another ::ROUTINE in another program that the ::REQUIRES directive accesses. The language processor uses the local ::ROUTINE definition in this case.
Calling an external Rexx program as a function is similar to calling an internal routine. For an external routine, however, the caller's variables are hidden and the internal values (NUMERIC settings, for example) start with their defaults.

Note

If you specify the same ::ROUTINE routinename more than once in different programs, the last one is used. Using more than one ::ROUTINE routinename in the same program produces an error.