Introduction to Regina
This chapter provides an introduction to Regina, an Open Source Rexx Interpreter distributed under the GNU General Library License.
The purpose of this document is to provide an overview of the Rexx language and the Regina implementation of the Rexx language. It is not intended as a definitive reference to Rexx; you should really have a copy of the Rexx "bible"; The Rexx Language, by Mike Cowlishaw [TRL2].
The Regina Rexx Interpreter is implemented as a library suitable for linking into third-party applications. Access to Regina from third-party applications is via the Regina API, which is consistent with the IBM's REXX SAA API. This API is implemented on most other Rexx interpreters.
The library containing Regina is available either as a static library or as a dynamically loadable library. The only functional difference between the two libraries is that the ability to dynamically load Rexx external function packages via the built-in function; RxFuncAdd, is only available with the dynamically loadable library.
The Regina distribution also includes a front end to the Regina library, to enable the execution of Rexx programs directly from the command line. The command line referred to here relates to the a Unix shell, an OS/2 or DOS command window or a Windows NT/9x command prompt.
On platforms where both a static and a dynamic executable exist, it should be noted that the ability to load an execute external functions via the RxFuncAdd function, is only available by running the dynamic executable.
Regina has been ported to many operating systems. The following table provides implementation details of each of the ports of Regina.
Operating System |
Dynamic Library |
Static Library |
ThreadSafe Library |
Dynamic Executable |
Static Executable |
Linux |
libregina.so |
libregina.a |
libregina_ts.so |
regina |
rexx |
HP-UX |
libregina.sl |
libregina.a |
N/A |
regina |
rexx |
AIX |
libregina.a |
libregina.a |
libregina_ts.a |
regina |
rexx |
Other Unix |
libregina.so |
libregina.a |
libregina_ts.so |
regina |
rexx |
32-bit DOS (DJGPP) (Uses DPMI memory manager) |
N/A |
libregina.a |
N/A |
N/A |
rexx.exe |
32-bit DOS (EMX) (Uses VCPI memory manager) |
N/A |
regina.a |
N/A |
N/A |
rexx.exe |
OS/2 (EMX) |
regina.dll (regina.lib) |
regina.a |
reginats.dll (reginats.lib) |
regina.exe |
rexx.exe |
Windows 9x/Me/NT/2k/XP |
regina.dll (regina.lib) |
rexx.lib |
reginats.dll (reginats.lib) |
regina.exe |
rexx.exe |
BeOS |
libregina.so |
libregina.a |
N/A |
regina |
rexx |
AmigaOS |
N/A |
libregina.a |
N/A |
N/A |
rexx |
EPOC32 |
N/A |
N/A |
N/A |
N/A |
rexx.exe |
AtheOS |
libregina.so |
libregina.a |
N/A |
regina |
rexx |
QNX 4.2x |
N/A |
regina.lib |
N/A |
N/A |
rexx |
QNX 6.x |
libregina.so |
libregina.a |
libregina_ts.so |
regina |
rexx |
Rexx programs are generally executed by Regina from the command line in the following manner:
regina [switches] [program] [program parameters]
where:
regina is the name of the Regina executable (see table above)
switches are optional switches. See the section below for an explanation of the switches currently supported by Regina
program the name of the Rexx program to be executed. See the section External Rexx Programs, below, for details on how Regina interprets this argument. If no program name is specified, Regina waits for Rexx commands to be typed in and will execute those commands when the appropriate end-of-file character (^D on Unix and ^Z on DOS, OS/2 and Windows NT/95) is typed.
program parameters any optional parameters to be passed to the Rexx program.
Rexx programs to be executed by Regina can take advantage of a feature of Unix shell programs called magic numbers. By having the first line of a Rexx program consist of the special sequence of #! followed by the full file name of the Regina executable, you can invoke this program simply by typing the name of the Rexx program on the command line followed by any parameters you wish to pass to the Rexx program. The file name must also have the appropriate execute bit set for this to work. As an example suppose your Rexx program, myprog, contained:
#!/usr/local/bin/regina
Parse Version ver
Say ver
When executing this program from the command line by typing myprog, the Unix shell program would execute the program /usr/local/bin/regina and pass the remainder of the lines in the file to this program via stdin.
The special processing done by Regina to find the file name in REGINA_MACROS and the file extension searching is not able to be carried out when using the magic number method of invocation.
The following switches allow the user to control how Regina executes the supplied Rexx program. Switches are recognised by a leading hyphen character; `-', followed immediately by a single alphabetic character. Some switches allow for optional parameters. These, too must follow the switch without any intervening spaces. All switches and their optional parameters are case-sensitive.
-t[trace parameter] Turn on the specified tracing level. The optional trace parameter indicates the tracing level to be used. See the TRACE command later in this document for an explanation of each trace level. Use of this switch will result in any TRACE commands in the program to be ignored.
-a Without this switch, all command line parameters are passed to Regina as a single argument. Specifying -a, ensures that the Rexx program invoked has access to the command line parameters as separate arguments, as passed from the command line interpreter. ie. The BIF ARG() can return a value of other than 1 or 0. Also PARSE SOURCE will return SUBROUTINE instead of the normal COMMAND value.
-r Run Regina in restricted mode. See the section on Regina Restricted Mode for more details.
Regina searches for Rexx programs, using a combination of the REGINA_MACROS environment variable and the addition of filename extensions. This rule applies to both external function calls and the program specified on the command line.
Assume you have a call to an external function, and it is coded as follows:
Call myextfunc arg1, arg2
First, Regina looks for a file called myextfunc in the current directory. If it can't find that file, it looks in each directory specified in the REGINA_MACROS environment variable for a file called myextfunc. If the file is not found, Regina then attempts to find a file called myextfunc.rexx in the current directory, then in each directory in REGINA_MACROS. Regina continues, next by appending .rex to the supplied external function name, followedby .cmd and .rx
Only if a file does not exist in either the current directory, or any directory in REGINA_MACROS, either with the supplied filename or with that filename appended with .rexx, .rex, .rx or .cmd does Regina complain that the external function is unknown.
Table of Contents
Introduction to Regina 1
1Purpose of this document 1
2Implementation 1
3Ports of Regina 2
4Executing Rexx programs with Regina 2
4.1Switches 3
4.2External Rexx programs 3