The ::REQUIRES directive specifies that the program requires access to the classes and objects of the Rexx program programname.

If the LIBRARY option is not specified, all public classes and routines defined in the named program are made available to the executing program. The programname is a literal string or a symbol that is taken as a constant. The string or symbol programname can be any string or symbol that is valid as the target of a CALL instruction. The program programname is called as an external routine with no arguments. The program is searched for using the external program search order.

If any Rexx code precedes the first directive in programname then that code is executed at the time the ::REQUIRES is processed by the interpreter. This will be executed prior to executing the main Rexx program in the file that specifies the ::REQUIRES statement.

If the LIBRARY option is specified, programname is the name of an external native library that is required by this program. The library will be loaded using platform-specific mechanisms, which generally means the library name is case sensitive. Any routines defined in the library will be made available to all programs running in the process. If the native library cannot be loaded, the program will not be permitted to run. All LIBRARY ::REQUIRES directives will be processed before ::REQUIRES for Rexx programs, which will ensure that the native libraries are available to the initialization code of the Rexx packages.

If the NAMESPACE option is specified, namespace must be a symbol that is taken as a constant; a literal string is not allowed.

The NAMESPACE option attaches the qualifier namespace to the package loaded by the ::REQUIRES directive. To distinguish public classes or public routines of the same name in different ::REQUIRES files, use a namespace-qualified symbol of the form namespace:class or namespace:routine. For details see Section 1.14, “Namespaces”.

::REQUIRES directives can be placed anywhere after the main section of code in the package. The order of ::REQUIRES directives determines the search order for classes and routines defined in the named programs and also the load order of the referenced files. Once a program is loaded by a ::REQUIRES statement in a program, other references to that same program by ::REQUIRES statements in other programs will resolve to the previously loaded program. The initialization code for the ::REQUIRES file will only be executed on the first reference.

The following example illustrates that two programs, ProgramA and ProgramB, can both access classes and routines that another program, ProgramC, contains. (The code at the beginning of ProgramC runs prior to the start of the main Rexx program.)

The language processor uses local routine definitions within a program in preference to routines of the same name accessed through ::REQUIRES directives. Local class definitions within a program override classes of the same name in other programs accessed through ::REQUIRES directives.

Another directive, or the end of the program, must follow a ::REQUIRES directive. Only null clauses can appear between them.