CC-tea/org-hyperion-cules
1
0
Fork 0
mirror of https://github.com/SDL-Hercules-390/hyperion.git synced 2026-04-10 22:24:32 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
04cbb443da170f390093d7bc40015a8d451648a1
org-hyperion-cules/README.REXX
Enrico Sorichetti a0f35c3135 fixed the sample rexx configuration to use the <ausiliary> variables 
fixed a typo in the REXX.README
2012-06-18 07:24:51 +02:00

619 lines
18 KiB
Rexx
Raw Blame History

Hercules REXX support
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
NOTE fixed a typo for the error handler variable name
NOTE the changes in the Address HERCULES invocation
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
This is a full rewrite of the original Rexx implementation by Jan Jaeger
the Rexx packages supported are
Open Object Rexx ( from now on called simply ooRexx )
Regina Rexx ( from now on called simply Regina )
Building Hercules with Rexx support
The support is completely dynamic, only the headers are needed to provide Rexx support
if the headers rexx.h and oorexxapi.h are found ooRexx support will be included
if the headers rexxsaa.h is found Regina support will be included
if Rexx support is not <needed/wanted> configure supports the flags
--disable-object-rexx
--disable-regina-rexx
Using Rexx
Since the support is completely dynamic the available rexx interpreters will be
determined at run time ( trying to load the appropriate dynamic libraries )
unless specified otherwise ( see further down the available options )
the rexx initialization stub will check in the order ooRexx and Regina
so in case both interpreters are available ooRexx will be the first choice.
no action is required by the user,
all will be automatic at the first execution of a rexx script
to invoke a rexx script the command is
EXEC <scriptname> <script arguments>
within the Rexx script Hercules commands can be issued using the constructs
1 - ...Address <ENVIRONMENT> interface
* the original implementation was forced to do parsing/subparsing
of the <string> passed to extract the <command> options
since the <command string> might/ contain arbitrary char sequences
the subparsing was prone to errors
now Address Hercules has as the ONLY parameter the command
all the <local> option are defined/passed thru predefined and reserved rexx variables
( even IBM used this approach in the original RXSQL interface :-) )
and here they are
HREXX.ERRORHANDER "RETCODE"/"SYSTEM"
to determine how error situations must be handled
( usually a non 0 return code from the command )
for example a devlist with no devices present exits with a return code 1
from the subcommand interface point of view it should not be considered an error
( also RXSQL when no rows satify the query does not raise an error condition )
just play around a bit with the different situations to understand better the reason
why I let the user choose
HREXX.RESPSTEMNAME
to tell the stem <root> to be used for the response
the variable is dropped at every call so that each Address HERCULES invocation
will find an unbiased environment
if on the other side a response is alway wanted the variable
HREXX.PERSISTENTRESPSTEMNAME will provide such facility
as usual the Rexx variable RC contains the return code from the hercules command
the <stemname> will contain the reply with the usual convention that
<stemname>.0 will contain the number of lines returned
NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW NEW
2 - external function interface ( much cleaner IMO )
the parameter passing does nor depend on any parsing/subparsing
the function name is awscmd
( I liked the name, but if somebody feels that it infringes some IP I will change it )
the format and the parameters are
<rc> = awscmd(<command>,[<stemname>],[<error handling mode>])
or
call awscmd <command>, [<stemname>], [<error handling mode>]
in both cases ( command and external function )
the error handling default is "RETCODE"
NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE
When a response stemname is not specified, Hercules will display the command
results normally, just like it always does.
When a response stemname is used however, Hercules does NOT display the results
of the command.
Instead, the results of the command are captured and returned in the specified
REXX stem variable, and it is Your prerogative to preocess in any way You feel
appropriate... ( for example )
display them yourself using the REXX 'say/lineout' statement."
write them to a file using lineout ( for ooRexx EXECIO or the stream class )
analyze the content to process accordingly
to manage the Rexx environment the command is
REXX <option> <arguments>
the option are
-- to define the search path for the Rexx script invoked
PATH a path with the system defined PATH separator
( ; for windows / : for linux and similar )
well no need to tell about it
PATH clear
to clear the path
PATH reset
to reset the PATH to the default startup path ( see later for the meaning )
as an alternate spelling for those who might be confused REXXPATH is also accepted
SYSP[ATH] on/off
to extend the search to the standard system PATH used for executables
the above behavior mimicks the ooRexx behavior for the search of external
function/classes ( ::library ::requires directives)
the default is to extend the search
-- to define the extensions to be used when resolving the script name
EXT[ENSIONS] list of the extension to use when autocompleting the script name
EXT[ENSIONS] reset
to reset the EXTENSIONS list to the default startup list ( see later for the meaning )
the default extension are
(NONE) the plain file name ==> always checked
.REXX:.rexx:.REX:.rex:.CMD:.cmd:.RX:.rx
if a script name contains a (.) ==> is in the format <filename>.<filetype>
it is used as is without any further processing
note the alias of SUF[FIXES] can be used
-- control the script name resolution process
RESOL[VER] on/off
defines who will resolve the script name
on the hercules rexx interface will take care of that and issue the appropriate
message if the process fail
off the command name will be passed AS IS to the rexx interpreter
the behavior is different from ooRexx and Regina
for ooRexx
HHC01603I exec notfound
REX0003E: Error 3: Failure during initialization
REX0534E: Error 3.901: Failure during initialization: Program "notfound" was not found
HHC17502E REXX(ooRexx) ooRexx RC(-3)
for Regina
HHC01603I exec notfound
HHC17502E REXX(Regina) Regina RC(-3)
-- control the verbosity of the interface
MSGL[EVEL] 0-9
0 is the default
as far as now any value between 1 and 9 will have the same effect
it will display at the end of the script the messages
HHC17503I REXX(<package name>) Exec/Script '<script name>' RetRC(0)
HHC17504I REXX(<package name>) Exec/Script '<script name>' RetValue'0'
-- define a prefix to be used for standard and error/trace messages
MSGP[REFIX] a <string> up to 9 chars ( no blanks allowed ) / reset
ERRP[REFIX]
-- define the argument passing mode to the invoked script
see the hbasics example in the script directory
and read the rexx documentation - no reason to retype the manuals :-)
MODE com[mand]
sub[routine] ( support arg() construct )
I guess that no further details are needed
for each command issued at the end a status of the rexx interface is displayed
the same info as in
-- displaying the status of the rexx interface
the command REXX without any operands will display the status of the interface
HHC01603I rexx
HHC17500I REXX(ooRexx) Rexx Path : /hercules/scripts
HHC17500I REXX(ooRexx) SystemPath: (ON)
HHC17500I REXX(ooRexx) Extensions: .REXX:.rexx:.REX:.rex:.CMD:.cmd:.RX:.rx
HHC17500I REXX(ooRexx) Resolver : (ON)
HHC17500I REXX(ooRexx) Msg Level : 0
HHC17500I REXX(ooRexx) Msg Prefix: (OFF)
HHC17500I REXX(ooRexx) Err Prefix: (OFF)
HHC17500I REXX(ooRexx) Mode : (Command)
HHC17500I REXX(ooRexx) REXX-ooRexx_4.2.0(MT) 6.04 21 Mar 2012
HHC17500I REXX(ooRexx) MACOSX FUNCTION Instore
HHC01603I rexx
HHC17500I REXX(Regina) Rexx Path : /hercules/scripts
HHC17500I REXX(Regina) SystemPath: (ON)
HHC17500I REXX(Regina) Extensions: .REXX:.rexx:.REX:.rex:.CMD:.cmd:.RX:.rx
HHC17500I REXX(Regina) Resolver : (ON)
HHC17500I REXX(Regina) Msg Level : 0
HHC17500I REXX(Regina) Msg Prefix: (OFF)
HHC17500I REXX(Regina) Err Prefix: (OFF)
HHC17500I REXX(Regina) Mode : (Command)
HHC17500I REXX(Regina) REXX-Regina_3.6(MT) 5.00 31 Dec 2011
HHC17500I REXX(Regina) UNIX FUNCTION Instore
or when no interface is enabled
HHC01603I rexx
HHC17500I REXX() Rexx Path : /hercules/scripts
HHC17500I REXX() SystemPath: (ON)
HHC17500I REXX() Extensions: .REXX:.rexx:.REX:.rex:.CMD:.cmd:.RX:.rx
HHC17500I REXX() Resolver : (ON)
HHC17500I REXX() Msg Level : 0
HHC17500I REXX() Msg Prefix: (OFF)
HHC17500I REXX() Err Prefix: (OFF)
HHC17500I REXX() Mode : (Command)
HHC17521I REXX() Support not started/enabled
since the builtin support is bilingual two other commands are provided
to manage the Rexx interface
REXX stop/disable
REXX start/enable without any operands will enable the default Rexx interpreter
and as expected specifyng oorexx/regina will override the default
NOTE the start/stop command are not available if hercules has been built with just
one package available
environment variables and defaults
the defaults are those hardcoded in the <code>
some environment variables are provided to override them
HREXX_PACKAGE=<value>
acceptedvalues are
AUTO, not really needed, but implements the default search order for interpreters
NONE no default rexx interpreter will be autostarted, a manual start is needed
oorexx/regina self explanatory
HREXX_PATH[S]=<a well formed path concatenation>
wher to find the rexx scripts
HREXX_EXTENSIONS=<a well formed extensions list >
HREXX_MODE=command/subroutine
when issuing a
REXX <some option> reset
the relative values are reset to the hardcoded values or to the value provided
by the environment variables
never wrote so much doc in my whole IT life :-)
if something is not clear , let me know and I will try to explain better
Enrico Sorichetti
possibly duplicate and inconsistent info, will fix later !
to clean up the <sources> the content of
hRexx_readme.txt and hRexx_readme_install.txt
have been moved here
OLD : hRexx_readme.txt
********************************************************************************
********************************************************************************
********************************************************************************
some preliminary doc for Rexx support
installation/enabling
at configure use :
--enable-object-rexx
--enable-regina-rexx
since support is fully dynamic no library checking is done
I hope to have done the proper error checking
when loading the Rexx dynamic libraries and resolving the symbols
oops I forgot about windows
to enable REXX support on windows just
set/export the environment variables
OBJECT_REXX_DIR
REGINA_REXX_DIR
to the appropriate directory
if the installation was standard
for object rexx ==> <programs files>\oorexx\api
for REGINA rexx the silly installer wants to install
to c:\Regina, smarter to force the install to <Program Files>\regina
anyway the include directory is <regina install path>\include
when enabling multilanguange support, REXX is not <autostarted>
the desired <package> must be manually started (*)
the REXX command is used to manage the Rexx environment
rexx start oorexx/regina
rexx stop
! enable/disable are the alternative forms
to tell rexx what path to use to search for the execs
rexx paths < a list of paths >
rexx paths reset to reset the search path to the default
( the deafult path is the current PATH )
an alternative spelling is
rexx path
to tell rexx what extensions to use when searching
rexx extensions < a list of extensions >
rexx extensions reset to reset the extensions to the defaults
the extensions defaults are : .REXX;.rexx;.REX;.rex;.CMD;.cmd;.RX;.rx
in the order
an alternative spelling is
rexx suffixes
when the IO handler issues the messages to the hercules console
it start from position 0/1 ( depending on how You count )
the commands
rexx errpref
rexx msgpref
will set the prefix for error and standard messages ( say )
as You can imagine
rexx errpref reset/ rexx msgpref reset, will disable message prefixing
to ba able to use a config file written in rexx
rexx must be autostarted
three environment variables are available
HREXX_PACKAGE=oorexx/regina
HREXX_PATHS/HREXX_PATH
HREXX_EXTENSIONS/HREXX_SUFFIXES
if the HREXX_PACKAGE environment variable is set
no need to start rexx support, it will be autostarted at the first exec invocation
as far as the exec command is concerned
using the format
exec name arg1 arg2 ... argn
will use the rexx defined extensions and packages
if the exec name is a fully resolved path it will not be tampered with and
<hRexx> will just pass the name asis to the interpreter
now for the Address HERCULES command
I mimicked the EXECIO format
address HERCULES <command>
no output is returned
Address HERCULES <command> ( STEM somestemname.
well You are all smart enough to understand how it works
enoug documenation for now! I am fed up of writing :-)
! oops I forgot an important thing ...
! when starting/enabling object rexx, receiving a 1002 error is not really
! a RXAPI_MEMFAIL
! it is a consequence of the RXAPI daemon not being active
! it should be enough to start it according to the documentation
! or have it autostarted at ipl/boot time
I tested with a standard ooRexx and Regina Rexx installation
and as long the installer sets up correctly the path for dynamic libraries
the hercules rexx interface will find them
( tested on fedora core 15, both oorexx and regina )
if the installation is <not standard> then it is a user task to
setup properly the overall environment
for example defining the relevant symlinks from /usr/<whatever> to the
relative paths for the non standared rexx installation
from :
/usr/bin to <rexx>/bin
/usr/lib to <rexx>/lib ( on some linux[es] regina uses lib64 )
the above are needed to run, to compile
/usr/include to <rexx>/include
please let me know of standard installations where the Rexx interface
fails to find the dynamic libraries
changes ..
implemented the "full" autostart facility.
relation with the HREXX_PACKAGE environment variable
when HREXX_PACKAGE undefined/unset ( the most common situation )
hercules will attempt to enable oorexx first , regina rexx next
when HREXX_PACKAGE has the value "auto"
same as above
when HREXX_PACKAGE has the value "none"
no autostart will be attempted
when HREXX_PACKAGE has the value oorexx/regina
the selected package will be started
the start command has been changed,
if no package name is entered the above sequence is followed
the help has been modified accordingly
NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE
the REXX path will be used to search ONLY for the scripts invoked via the exec command
the hercules configuration written in rexx DOES NOT FOLLOW that setup
the configuration is read at the beginning of the startup process and it must
be read by the hercules configuration program to understand that it is a rexx script
so it must be reached thru a PATH available to the shell
after that rexx will be invoked passing the absolute path to the configuration
example
current directory ==> /Hercules/sandhawk.390.build
hercules invoked with ==> ./hercules -f hercules.rexx
inside the hercules rexx
parse source _src
say _src
returned ==> MACOSX COMMAND /Hercules/sandhawk.390.build/hercules.rexx
note the full resolved path of the configuration file
03/18
fixed a small glitch where sometimes the rexx status display
returned a dirty buffer
fixed the logic glitch in the extension separator
USES NOW THE SAME separator as the one used by PATH,
only one separator to remember !
to do ...
some cosmetics
small optimizations
comment the code ( pretty linear and sequential ) but better do it
enjoy
OLD : hRexx_readme_install.txt
********************************************************************************
********************************************************************************
********************************************************************************
here are the the installation steps for the REXX packages I used
as a prerequisite for implementing full rexx support
mkdir /opt
for Object Rexx - 4.2.0 ( svn revision 7688 )
cd /opt
svn co https://oorexx.svn.sourceforge.net/svnroot/oorexx/main/trunk ooRexx-svn
cd ooRexx-svn
./bootstrap
./configure --prefix="/opt/ooRexx"
--with-pic
CFLAGS=-O3
CXXFLAGS=-O3
make
make install
cd /usr/bin
sudo ln -s -f /opt/ooRexx/bin/(*) .
cd /usr/lib
sudo ln -s -f /opt/ooRexx/lib/(*)* .
cd /usr/include
sudo ln -s -f /opt/ooRexx/include/(*) .
SAME process used on SNOW LEOPARD, LION and LINUX ( RHEL and Fedora 15 )
I' ll let You find out the most comfortable way of starting the rxapi daemon
for Regina ( svn revision 89 )
cd /opt
svn co https://regina-rexx.svn.sourceforge.net/svnroot/regina-rexx/interpreter/trunk Regina-svn
cd Regina-svn
./configure --prefix="/opt/Regina"
--without-staticfunctions
--without-testpackage
--without-regutil
--without-rexxcurses
--without-rexxtk
--without-rexxgd
--without-rexxcurl
--without-rexxsql
--without-rexxeec
--without-rexxisam
--without-rxsock
--without-rexxdw
CFLAGS=-O3
CXXFLAGS=-O3
( the withouts are for , in my case, useless options; Your mileage might vary )
make
make install
for REGINA executable naming is a bit illogic
./regina -v
REXX-Regina_3.6(MT) 5.00 31 Dec 2011
./rexx -v
REXX-Regina_3.6 5.00 31 Dec 2011
so for full usability it might be better to make a symlink only to the GOOD ONE
cd /usr/bin
sudo ln -s -f /opt/Regina/bin/Regina rexx
sudo ln -s -f /opt/Regina/include/(*) .
cd /usr/include
sudo ln -s -f /opt/Regina/include/(*) .
for APPLE
cd /usr/lib
sudo ln -s -f /opt/Regina/lib/(*) .
for Linux 32 bits ( same )
cd /usr/lib
sudo ln -s -f /opt/Regina/lib/(*) .
for Linux 64 bits
cd /usr/lib64
sudo ln -s -f /opt/Regina/lib64/(*) .
BUT CHECK YOUR SYSTEM LAYOUT and fix the logic accordingly
when doing a bilingual installation just do the symlink stuff only for the
PRIMARY rexx ,
or for Regina do the symlink only for the Regina executable
so the scripts will have to use the shebang #! /usr/bin/regina
with this setup a small script to switch the symlinks might be the only thing
needed to change on the fly the default REXX package
after all this
You can build hercules with rexx support
as soon as I have a bit more time I will update this install readme
with the considerations for a rexx install from a binary package
all the above is for well behaved linuxes, for the others ... well You all are on Your own
I STRONGLY BELIEVE THAT WE SHOULD DECLARE A REFERENCE PLATFORM WITH <COMMITTED>
SUPPORT
For other platform a best effort is all that we should commit for
Reference in New Issue View Git Blame Copy Permalink