Hercules's Rexx support provides support for the following two Rexx packages:
.hheader file is found during build time.
If the headers
oorexxapi.h are found,
then support for OORexx will be provided. If the header
is found, then support for Regina Rexx will be provided. If all three headers
are found, then support for both OORexx and Regina will be provided and you
can then specify at runtime which one you want Hercules to use. (See the
rexx' "start" option further below.)
On Linux, support for both packages are enabled by default but whether support is provided depends of course on whether the previously mentioned headers are found. If either package is installed the headers should be found and corresponding support within Hercules should be provided.
Support for either package can be disabled by simply specifying
either the "
--disable-regina-rexx" options on your
command at build time (Linux only). On Windows, the only way to purposely disable support
is to rename the header file(s) to prevent Hercules from finding them.
Hercules runtime support for Rexx is completely dynamic based on the availability of each package's dynamic libraries which are automatically loaded at startup.
When both packages are found to be available then OORexx will be chosen as the
default Rexx interpreter unless overridden by the optional '
environment variable. The only valid values for
"none", "auto", "OORexx" or "Regina". The default (preferred) Rexx package
when "auto" is specified is Object Rexx (OORexx). Use "none" to prevent Rexx
support for either package from being automatically enabled at startup, thereby
requiring you to manually enable (start) Rexx yourself via the Hercules
rexx' command's "start" option (see just below).
Other optional environment variables can be used to define your own default values for
some of Hercules Rexx's runtime options. The '
environment variable for example defines a default value for the
rexx' command's "rexxpath" option. Similarly the
HREXX_MODE' and '
variables define default values for the '
"mode" and "extensions" options.
rexx' command is:
rexx [option value] ...
Entering the '
rexx' command without any arguments displays the
current settings. Otherwise an option / value pair must be specified to set
the specified option to the specified value. More than one option/value pair
can be specified on the same command.
- Enable/Start a Rexx Package, where package is either 'OORexx' (the default) or 'Regina'. Use the
HREXX_PACKAGEenvironment variable to define a preferred default value. "auto" will automatically start the default package. Use "none" to prevent automatic enablement.
- Disable/Stop the Rexx package. Any attempt to execute a Rexx script via the '
exec' command will result in an error.
- List of directories to search for scripts. No default. Use the
HREXX_PATHenvironment variable to define your preferred default.
- Extend the search to the System Paths too. 'On' (default) or 'Off'.
- List of extensions to use when searching for scripts. A search with no extension is always done first. The
HREXX_EXTENSIONSenvironment can be used to set a different default list.
- Alias for 'Ext[ensions]'.
- 'On' (default): Hercules will resolve the script's full path. 'Off': the scriptname is used as-is.
- 'Off' (default) or 'On' to disable or enable Hercules messages
HHC17504Ithat display a script's return code and return value when it finishes executing.
- 'Off' (default) or 'On' to disable or enable prefixing Rexx script 'say' messages with Hercules message number
- 'Off' (default) or 'On' to disable or enable prefixing Rexx script
TRACEmessages with Hercules message number
- Define the preferred argument passing style. 'Com[mand]' (default) or 'Sub[routine]'. Use the
HREXX_MODEenvironment variable to define your preferred default mode. See further below for the difference between the two.
- Lists currently running asynchronous scripts.
See next section below.
- to halt a running asynchronous script.
See next section below.
exec' command is:
exec [mode] scriptname [[args...][&&]]
Where 'scriptname' is the name of the Rexx script, 'args' is an optional list of arguments to be passed to the script and '&&' as the last argument requests that the script be run asynchronously in the background. The rexx command's 'list' and 'cancel' options can be used to list/cancel any currently running asynchronous scripts.
Take special care when using the '&&' option to run a script asynchronously. Be careful to not accidentally enter a single '&' instead (which invokes the Hercules 'exec' command asynchronously, but not the rexx script, leaving you with no way to cancel it should you need to).
If you need to run a script in the background always use two ampersands '&&' to cause the script itself to run in the background. Of course, if the script ends quickly then there is no need to run it asynchronously in the background. The ability to run scripts in the background is designed for never-ending 'monitoring' type scripts that continuously monitor and report such things as Hercules status.
The 'mode' setting determines how arguments are passed to your Rexx script. In command mode (the default) there is only one argument passed, with that single argument being the string of characters which immediately follows the script's name. This allows your script to parse the string into individual arguments however it may decide, potentially contrary to the way command line arguments are normally parsed.
In subroutine mode Hercules parses the string normally and passes each argument to your script individually as shown in the examples below.
The argument passing style is determined by the 'rexx' command's current "Mode"
setting, but can be temporarily overridden for the current execution by simply
specifying the 'mode' parameter on the command itself, immediately before the
scriptname (e.g. '
exec cmd ...' for command style argument passing,
exec sub ...' for subroutine style argument passing):
Contents of script example.rexx:parse arg str say "" say "parse arg str: " str say "arg(1): "arg(1) say "arg(2): "arg(2) say "arg(3): "arg(3) exit
Running the script from a command line (outside of Hercules) results in:C:\> example.rexx one, Two "Buckle MY shoe" parse arg str: one, Two "Buckle MY shoe" arg(1): one, Two "Buckle MY shoe" arg(2): arg(3):
Running the script from within Hercules via the '
exec' command using the default 'Command' mode setting results in:HHC01603I exec example.rexx one, Two "Buckle MY shoe" HHC17540I HHC17540I parse arg str: one, Two "Buckle MY shoe" HHC17540I arg(1): one, Two "Buckle MY shoe" HHC17540I arg(2): HHC17540I arg(3):
Running the script using 'Subroutine' mode results in:HHC01603I exec sub example.rexx one, Two "Buckle MY shoe" HHC17540I HHC17540I parse arg str: one, HHC17540I arg(1): one, HHC17540I arg(2): Two HHC17540I arg(3): Buckle MY shoe
The Hercules Rexx '
exec' command is considered to be a "shell" command
from Hercules's point of view since both of the supported Rexx interpreters provide
the ability to directly target the host operating system environment. Both of
sh' and '
exec' commands are thus disabled by default
for security reasons.
To enable the ability to '
exec' Rexx scripts from the Hercules command line
(or via the Hercules DIAG 8 instruction interface) use the
For more information on each please refer to Hercules
documentation describing configuration file statements.
Rexx scripts run from within Hercules (via the '
are able to issue Hercules commands via the Rexx "
or via the Hercules "
AWSCMD" special function:
Address HERCULES "command..."
rc = AWSCMD( "command..." [,stemvar[,errmode]] )
Call AWSCMD "command..." [,stemvar[,errmode]]
The Rexx variable "RC" contains the return code from the Hercules command. The specified stem variable "stemvar" will contain the response from Hercules with the usual convention of "stemvar.0" being set to the number of response lines and "stemvar.1" to "stemvar.n" holding the Hercules response lines themselves. A sample script called "hcommand.rexx" illustrating both techniques ("Address" and "AWSCMD") can be found in the "
scripts" subdirectory of the Hercules source code distribution.
Note that when a response stemname is used Hercules does not display the results of the command on the hardware console panel. Instead, the results are captured and returned in the specified Rexx stem variable, and it becomes your decision what to do with them (such as displaying them on the hardware console panel via the Rexx "Say" command).
Since the Rexx "Address" keyword syntax does not provide any means of specifying
additional parameters (such as the stem variable name and error handling option
AWSCMD technique provides), options for the "Address" keyword
syntax are passed to the Hercules Rexx subcommand environment via several predefined
(reserved) Rexx variables instead:
defines the stem variable name to be used to hold the Hercules response lines. "HREXX.RESPSTEMNAME" is dropped after every call so each "Address 'HERCULES'" invocation finds an unbiased environment. "HREXX.PERSISTENTRESPSTEMNAME" provides the same functionality but is never dropped.
defines how errors (non-zero RC) should be handled. Setting the variable to "SYSTEM" requests the Rexx interpreter itself handle any non-zero return code in the standard Rexx fashion.
Setting it to the value "RETCODE" delegates all error handling to the caller, allowing your script to react to the "error" in whatever way it deems is appropriate.
The ability to specify error handling is provided since some Hercules commands
might return a non-zero return code (such as the "
devlist" command when there
are no devices defined in the configuration) and from the subcommand interface's
point of view such non-zero return codes should not be considered a subcommand
The default error handler setting is thus "RETCODE".