Hercules-REXX integration allows you to use
REXX scripts as
.rc files and to execute REXX scripts using the exec command.
REXX scripts can issue commands to the Hercules console.
REXX integration is not required to use runtest, which uses REXX for log analysis. REXX is used by runtest to run a script to analyse a Hercules log after the test scripts have have been run. If all you wish to do is use runtest, you do not need to integrate a REXX interpreter with Hercules.
Hercules can be integrated with either or both of the following REXX interpreters.
Each interpreter, when integrated with Hercules, offers the same set of capabilities. Open Object Rexx also allows for object-oriented REXX programming.
If Hercules is integrated with both REXX interpreters when built,
the rexx start/enable and rexx stop/disable
are enabled;
these commands allow you to select which REXX interpreter should
be used by Hercules following execution of the commands.
That depends.
If you are new to integrating REXX with Hercules, Regina Rexx represents an easier path and offers the capabilities of the traditional REXX language.
Regina Rexx is included in selected open source distributions,
including Debian, Leap/Tumbleweed, and Ubuntu,
and Windows and mac OS installables are available.
If you choose to build from source,
the build process includes targets for rpm and deb files for
later installation by your system's package manager.
And Regina Rexx will build from source on Solaris and FreeBSD,
although make install is your next step on these systems;
targets for those systems' package managers do not exist in
the Regina Rexx build scripts.
If you have Open Object Rexx installed on your system and the rxapi daemon/service is set up to run at system start-up, then ooRexx is a fine choice. In addition to the traditional REXX language, ooRexx includes object-oriented programming capabilities. Open Object Rexx installable binaries exist for many older GNU/Linux distributions, and Leap 42.2 includes Open Object Rexx in its library of installable packages.
For most newer GNU/Linux distributions, though, you will need to build from source. Open Object Rexx will not build on Solaris 11.3, nor on FreeBSD 11, so on these target systems, Regina Rexx is your best choice.
You can find Regina Rexx at its Sourceforge site. The site includes links to documentation, release notices, and downloadable installation packages for a number of target systems. The installation packages seem to reflect target system releases avaialble in April, 2015.
Release 3.9.1, available since April of 2015, has been tested with Hercules, as has release 3.6. A review of release notices suggests that older versions may work as well, although it makes sense to use the newest version available if you are starting from scratch. Regina Rexx is also included in the software repositories of some newer open system distributions, including:
Regina Rexx is easily built from source using a standard GNU autotools-based build (configure, make, make install).
You must do the following if you install Regina Rexx in other than the default installation directory:
export LD_LIBRARY_PATH=<ReginaRexxPrefix/lib> or /lib64
before starting Hercules so that Hercules can dynamically
load the Regina Rexx libraries.File INSTALL in the Regina Rexx source tarball documents the build from source process for many open source and UNIX-like platforms.
Release 4.2.0, available since Febuary 2014, has been tested with Hercules. A review of release notices suggests that older versions may work as well, although it makes sense to use the newest version available if you are starting from scratch. Open Object Rexx is also included in the software repositories of some newer open system distributions, including:
Open Object Rexx is built from source using a standard GNU autotools-based build (configure, make, make install). Open Object Rexx also requires a daemon/service process, rxapi, to enable its Application Programming Interface (API). Hercules uses the ooRexx API as part of its integration with ooRexx. Configuring the target system to start this process at boot-up is specific to the target OS (init.d, systemd, or something else).
Files INSTALL and unix-like-build.txt included with the source distribution provide guidance on building and installing Open Object Rexx. Also, you should review the file _ReadMe.pdf in the ooRexx 4.2.0 directory on sourceforge.net. That file contains more detail about installing the rxapi service.
You must do the following if you install Open Object Rexx in other than the default installation directory:
export LD_LIBRARY_PATH=<OpenObjectRexxPrefix/lib> or /lib64
before starting Hercules so that Hercules can dynamically
load the Open Object Rexx libraries.The rxapi process,
either daemon or service depending on your target OS,
must be running for Hercules to successfully integrate
with Open Object Rexx.
On open source and UNIX-like systems,
the process name is rxapi.
In systemd service name terms,
it is rxapid.service.
If rxapi is not running,
you will receive intermittent return code 1002
("out of memory")
errors when:
rexx enable command), rexx command without operands),
when Open Object Rexx has been previously enabled.exec <scriptname> command)
when Open Object Rexx has been previously enabled. The pre-packaged binaries normally make an attempt to set up
rxapi as a daemon/service started at system boot,
but the attempt may or may not be successful.
The rxapi daemon/service will not start at system boot
if you have built and installed Open Object Rexx in a
non-standard location, for example --prefix=$HOME/ooRexx/.
The rxapi service may be started from the command line
using root privileges via sudo /usr/bin/rxapi
or the equivalent if you prefer to use su.
If you start it manually,
it will remain running until you reboot your system.
If you receive intermitent 1002 return codes from Hercules when
executing the rexx
command or running REXX scripts using the exec
command,
check to see that the rxapi process is running.
On open source systems, a missing rxapi daemon/service will be reported as return code 1002. Open Object Rexx documentation describes rc=1002 as an out of memory error, but a missing rxapi process will generate the same return code.
If you get this return code, consider the possibility that the rxapi process has failed. See The ooRexx rxapi Daemon/Service, above, for additional information.
The following web sites have good information about REXX script development and are worth a look:
The following REXX script is a sample that can be used to verify that Hercules-REXX integration is working, and it shows what can be accomplished using a REXX script "inside" of Hercules. It is taken from the Hercules User Reference, pages 376-377.
You can copy and past the example below into a file sample.rexx on your system and give it a try.
/* REXX */ parse arg parms parms = space(parms) argc = words(parms) parse version ver parse source src env = address() parse var src . . cmd who = filespec("n",cmd) parse var who who "." . say who " started" say who " version . . . . :" ver say who " source . . . . :" src say who " hostenv . . . . :" env say who " date . . . . . :" date() say who " time . . . . . :" time() if parms = "" then do say who " arguments . . . : no arguments given" ret = 0 end else do say who " arguments . . . :" parms ret = parms end Say who " Hercules version :" value('version',,'SYSTEM') Say who " RC environment . :" value('HERCULES_RC',,'ENVIRONMENT') address hercules 'uptime' say who " ended" exit ret
This web page Copyright © 2017 by Stephen R. Orso.
This work is licensed under the Creative Commons Attribution-
ShareAlike 4.0 International License.
To view a copy of this license,
visit
http://creativecommons.org/licenses/by-sa/4.0/
or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.