REXX Support

Support for Rexx (both ooRexx and Regina Rexx) is built into the downloadable version of Hercules. The only thing needed is to install one (or both) of the two supported Rexx packages (see Appendix H. Links).

If the Rexx packages are installed with the standard installation procedures (using the provided installers) then the needed environment variables are created automatically during the installation and no manual action is required. For more information on how to build Rexx support into Hercules please refer to the “Installation Guide”.

Rexx can be used in various ways within Hercules:

• Invoking Rexx scripts explicitely through the EXEC console command.
• Invoking Rexx in the run-commands file.
• Invoking Rexx in the configuration file.

The EXEC console command may be used to explicitely invoke a Rexx script. The required argument is the name (and optionally path) of the Rexx script. Optional arguments will be passed to the Rexx script.

Example 1:

  EXEC [[file:/d:/rexx/script.rex|d:\rexx\script.rex]] arg1 arg2

In the above example the Rexx script named “script.rex” located on drive d: in directory “rexx” will be called with “arg1” and “arg2” as arguments.

Rexx will be invoked implicitely if existing script files (e.g. a configuration file or a run-commands file) start with “ SELECT

  WHEN SYSTEM = 'S/370' THEN DO
      ADDRESS HERCULES 'ARCHLVL S/370'
      ADDRESS HERCULES 'ENGINES 1*CP'
      ADDRESS HERCULES 'MAINSIZE 16'
      ADDRESS HERCULES 'XPNDSIZE 0'
  END
  WHEN SYSTEM = 'ESA/390' THEN DO
      ADDRESS HERCULES 'ARCHLVL ESA/390'
      ADDRESS HERCULES 'MAINSIZE 2048'
      ADDRESS HERCULES 'ENGINES 2*CP'
      ADDRESS HERCULES 'XPNDSIZE 2048'
  END
  WHEN SYSTEM = 'z/ARCH' THEN DO
      ADDRESS HERCULES 'ARCHLVL z/ARCH'
      ADDRESS HERCULES 'MAINSIZE 4096'
      ADDRESS HERCULES 'ENGINES 4*CP,2*AP'
      ADDRESS HERCULES 'XPNDSIZE 0'
  END
  OTHERWISE DO
      SAY 'Invalid architecture mode specified'
  RETURN 16

END

</file>

The above extract from a configuration file shows the different settings of system parameters depending on the value of a variable.

Hercules commands can be issued from Rexx through the Hercules command environment. The Her­cules command environment is the default environment, therefore it is not necessary to specify it, when using Hercules commands within a Rexx script.

Example 1:

Executing the Hercules ‘ARCHLVL’ command from a Rexx script specifying the Hercules command en­vironment.

  ADDRESS HERCULES 'ARCHLVL S/370'  Example 2:

Executing the Hercules ‘ARCHLVL’ command from a Rexx script without specifying the Hercules command environment.

  'ARCHLVL S/370'

Hercules symbols and environment variables can be retrieved with “value()” or “getenv()”. The builtin function “getenv()” is obsolete and has been replaced by “value()” and should no longer be used.

The Rexx builtin function “value()” is used to retrieve the value of existing variables. On optional para­meter can be used to searchwithin a specific variable pool. To retrieve the values of Hercules symbols the “SYSTEM” pool must be specified, to retrieve the values of Hercules (and other) environment variables the “ENVIRONMENT” pool must be specified. See the Regina Rexx documentation for more details on “value()”.

symbol This names an existing variable. If symbol does not name an existing variable, the default value is returned, and the NOVALUE condition is not raised.

If symbol is not a valid symbol name and the function is used to access an normal Rexx variable, an error occurs.

value If the optional second parameter value is specified, the variable will be set to that value, after the old value has been extracted.

pool The optional parameter pool might be specified to select a particular variable pool to search for symbol. The contents and format of pool is implementation depen­dent.

The default is to search in the variables at the current procedural level in Rexx. Which pools that are available is implementation dependent, but typically one can set variables in application programs or in the operating system.

Specify “SYSTEM” to retrieve the value of a Hercules symbol or “ENVIRONMENT” to retrieve the value of a Hercules (or another) environment variable.

Example 1:

Retrieve the value of the Hercules symbol “version”.

  say 'Hercules version = ' VALUE('version',,'SYSTEM')

Example 2:

Retrieve the value of the Hercules environment variable “HERCULES_RC”.

  say 'Hercules RC = ' value('HERCULES_RC',,'ENVIRONMENT')

The error handling differentiates between the following types of errors:

• Command Errors
• Command Failures

An invalid command (‘command not found’) is treated as a ‘command error’. Command errors may be handled with “SIGNAL ON ERROR”.

Failures in an otherwise valid command are treated as ‘command failures’. Command failures may be handled with “SIGNAL ON FAILURE”.

Command return codes < 0 are interpreted as ERROR, return codes > 0 are interpreted as FAILURE. Hercules will abort the startup process if the configuration file Rexx script returns with a non-zero return code.