Rexx/Wrapper
Version 2.3
23 May 2004
Introduction
Rexx/Wrapper is a tool that wraps Rexx source or tokenised code
into an executable program.
The Rexx source code can be optionally compressed and encoded to ensure
that the original Rexx code cannot be viewed (unless you have the original
encryption key).
Note that Rexx/Wrapper is NOT a compiler; the executable program still
requires a Rexx interpreter to execute the program.
Getting Started
The first time you run Rexx/Wrapper you should display the help information.
To do this run the rexxwrap.cmd program with your Rexx interpreter; eg.
rexx rexxwrap.cmd -h
-h, -?, and -help can all be
specified to display help.
Requirements
To use Rexx/Wrapper you need two extra bits of software:
- A supported Rexx interpreter
- A supported C compiler
The Rexx interpreter that is linked with the executable must be capable
of executing an instore Rexx macro via the SAA API.
The Rexx interpreter used to build the executable wrapper can be different
to the interpreter used to run the executable program.
If wrapping tokenised code, then the Rexx interpreter that creates the
tokenised code, must be the same interpreter that runs the tokenised code.
All suppliers of Rexx interpreters provide access to their interpreter
via a shared or dynamic library. This means that it is not possible to
build a completely stand-alone executable; you will always have to include
the shared or dynamic library with the executable built with Rexx/Wrapper.
There is one exception to this rule; Regina. Regina also provides a
static library, which means you can link your program with Regina's static
library, and you will get a completely stand-alone executable.
There is a catch however with using the Regina static library :-(. The
Rexx program that you wrap, cannot dynamically load an external function
package. This is because the Regina static library does not (and cannot)
support the dynamic loading of external functions. External functions, by
their very nature, require the presence of a dynamic or shared library to
operate.
Rexx/Wrapper requires a C compilers that supports ANSI prototypes.
It will not work with older K&R C Compilers.
For a list of the supported C compilers for the current platform, run
rexxwrap.cmd with the -h.
Modes of Operation
Rexx/Wrapper can be run in one of 3 ways.
Interactive
To run Rexx/Wrapper interactively, simply run the rexxwrap.cmd
program with your Rexx interpreter; eg.
rexx rexxwrap.cmd
You will then be prompted for several pieces of information that Rexx/Wrapper
needs to build the executable program. The equivalent command-line switch
is included below in parentheses. To set a value to an empty value, enter
a dash at the prompt.
- Program Name (-program)
This will be the name of the executable that Rexx/Wrapper creates.
Do not specify a .exe extension.
- Rexx filename (-rexxfiles)
The full file name of the source Rexx program. This can contain an
absolute file name like c:\rexx\rexxcps.rexx or /home/me/rexx/rexxcps
or a relative file name like ..\rexx\rexxcps.rexx or ../rexxcps.rexx.
- Rexx interpreter (-interpreter)
The name of the Rexx interpreter to which you will be linking the executable.
The valid names can be determined by running rexxwrap.cmd with the -h
command line option.
- Compiler (-compiler)
The symbolic name of the C compiler you will be using to build the
executable. Again, these are listed when you run rexxwrap.cmd with the
-h command line option.
- Rexx Interpreter Library (-intlib)
The full filename of the Rexx interpreter library to link to. This
will be something like librexx.so, on Unix platforms, and something
like rexx.lib on Windows, DOS and OS/2. Again, absolute or relative
path names can be specified. This value is ignored if
using os2rexx and the EMX compiler on OS/2, or MinGW
or Cygwin compilers on Win32.
- Rexx Interpreter Header File Directory (-intincdir)
The full directory in which the Rexx interpreter header file(s) reside.
Header files have a file extension of .h, and will be named something like
rexx.h or rexxsaa.h. This value is ignored if
using os2rexx and the EMX compiler on OS/2.
- Rexx/Wrapper Source Directory (-srcdir)
The full path to the Rexx/Wrapper source directory. This can be an absolute
or relative path. It is the directory where the files, loader.c, rexxtok.c
etc reside.
- Encrypt source: yes/no (-encrypt)
Answer yes or no if you want the source code encrypted.
Answering yes will make it very difficult for someone to extract
the source code form the executable without knowing the encryption key,
but it will add a small amount of extra processing time when you
execute the program.
- Compress source: yes/no (-compress)
Answer yes or no if you want the source code compressed.
Answering yes will reduce the size of the executable program
but it will add a small amount of extra processing time when you
execute the program.
- Use tokenised code rather than source: yes/no (-token)
Answer yes or no if you want Rexx/Wrapper to generate
tokenised code from your source code. Note that using tokenised code
in the executable program, will NOT include the source code. So any trace
or use of SOURCELINE in your tokenised program will not work as
expected.
Some Rexx interpreters do not allow tokenised code to be generated.
- Call Rexx program as subroutine: yes/no (-subroutine)
Answer Yes or No if you want Rexx/Wrapper to run the
Rexx program as a subroutine. This option will only work with Rexx/Trans
or Regina as the Rexx interpreter. Running as a subroutine allows you
to pass parameters to your Rexx program with embeded spaces.
- Win32 Only
- Do you want to build a GUI version: yes/no (-win32gui)
This option allows you to build a Win32 GUI application from your Rexx program.
The resultant executable will not display a console window when started. Any
data written to stdout or stderr, such as output from SAY or TRACE commands or
a stack trace as a result of a syntax error may
be lost depending on the answer to the following option (-guiconsole). Similarly
attempting to obtain data from stdin, such as PULL or interactive TRACE will result
in the program hanging, unless -guiconsole is set to yes.
This option is really only of use for wrapping Rexx/DW programs and other Rexx
programs written with GUI-based Rexx extensions.
- Do you want a console window if required: yes/no (-guiconsole)
Specifying no for this option will result in all output being thrown away
and a program hang if you attempt to obtain input via PULL or interactive TRACE.
Generally it is not a good idea to set this to no.
Specifying yes for this option will result in a console window appearing
as soon as any output or input is made from your Rexx program; either as a result
of SAY, TRACE, PULL or interactive TRACE. Also, once the console window appears
you must press any key in the console window once the program completes
and displays a message to that effect.
- Do you want to specify versioning information and add an icon to the executable: yes/no -resource
Answer yes to enable a resource file and an optional icon to be built into your executable.
- Program version. eg 2.0.1 (-version)
Specify the version number; x.y.z to apply to the exectable.
Only valid if -resource=yes.
- Program description (-desc)
A short description of the exectable.
Only valid if -resource=yes.
- License (-license)
Specify the license that you want associated with the exectable.
Only valid if -resource=yes.
- Icon filename (-icon)
The full filename of a valid Windows ICO file to be associated with the exectable.
Only valid if -resource=yes.
- OS/2 Only
- Do you want to build a GUI version: yes/no (-win32gui)
Answer yes to build the resultant executable as an OS/2 GUI program.
- Do you want to add an icon to the executable: yes/no -resource
Answer yes to enable an icon to be built into your executable.
- Icon filename (-icon)
The full filename of a valid OS/2 ICO file to be associated with the exectable.
Only valid if -resource=yes.
Command line
To run Rexx/Wrapper from the command line (not really recommended) you
supply all options on the Operating System command line. The options
are defined above, and consist of the option concatenated with an equals
sign concatenated with the option value. eg
rexx rexxwrap.cmd -encrypt=yes -intlib=..\rexx\rexx.lib ...
Defaults
This mode of operation assumes you have already run Rexx/Wrapper at least once
and want to use the values you supplied the last time Rexx/Wrapper was run. You
also must be running Rexx/Wrapper in the same directory you last ran it.
To run with default values, supply the simgle option -d on the command line.
Rexx/Wrapper will read the values specified in the rexxwrap.prm file in the
current directory. This file consists of a number of Rexx statements, that
set compound variables, which are interpreted.
You can also supply a filename to the -d switch to specify the file containing
the Rexx/Wrapper parameters to use.
Sample session
An example session using the prompt method and REXX/imc is shown below. User
entered values are displayed in bold.
This is Rexx/Wrapper 2.0 - 18 July 2002
---------------------------------------
Program Name(-program) [] rexxcps
Rexx filename(-rexxfiles) [] ../rexx/demo/rexxcps.rexx
Rexx interpreter(-interpreter) [] rexximc
Compiler(-compiler) [] gcc
Rexx Interpreter Library(-intlib) [] /tmp/rexx-imc-1.7/librexx.so
Rexx Interpreter Header File Directory(-intincdir) [] /tmp/rexx-imc-1.7
Rexx/Wrapper Source Directory(-srcdir) [] ..
Encrypt source: yes/no(-encrypt) [] yes
Compress source: yes/no(-compress) [] no
Use tokenised code rather than source: yes/no(-token) [] no
Call Rexx program as subroutine: yes/no(-subroutine) [] no
Running configure script...
creating cache ./config.cache
updating cache ./config.cache
creating ./config.status
creating configur
creating config.h
Compiling DES modules...rand_key set_key str2key ecb_enc cbc_cksm des_enc
Compiling intbuild.c...
Linking intbuild...
Running intbuild to produce rexxcps.c...
The generated key for this program is: tlxNhsju
If you need to dump the original code from the rexxcps executable, run:
rexxcps '--key=tlxNhsju'
Compiling rexxcps.c...
Linking rexxcps
Done!
The following example session uses the default method and Rexx/Trans (under Win32). User
entered values read from the rexxwrap.prm file are displayed in bold.
This is Rexx/Wrapper 2.0 - 18 July 2002
---------------------------------------
Program Name(-program) [aces]
Rexx filename(-rexxfiles) [d:\rexxtk\demo\aces.rexx]
Rexx interpreter(-interpreter) [rexxtrans]
Compiler(-compiler) [vc]
Rexx Interpreter Library(-intlib) [d:\rexxtrans\rexxtrans.lib]
Rexx Interpreter Header File Directory(-intincdir) [d:\rexxtrans]
Rexx/Wrapper Source Directory(-srcdir) [d:\rexxwrapper]
Encrypt source: yes/no(-encrypt) [no]
Compress source: yes/no(-compress) [no]
Use tokenised code rather than source: yes/no(-token) [no]
Call Rexx program as subroutine: yes/no(-subroutine) [no]
Do you want to build a GUI version: yes/no(-win32gui) [yes]
Do you want a console window if required: yes/no(-guiconsole) [yes]
Do you want to specify versioning information and add an icon to the executable: yes/no(-resource) [yes]
Program version. eg 2.0.1(-version) [1.0]
Program description(-desc) [Aces Card Game]
License(-license) [LGPL]
Icon filename(-icon) [d:\\rexxtk\\demo\\aces.ico]
Compiling intbuild.c...
intbuild.c
Linking intbuild...
Running intbuild to produce aces.c...
If you need to dump the original code from the aces executable, run:
aces --key=1
Compiling aces.c...
aces.c
Linking aces
Done!
Other uses of the tokenised file
If you run Rexx/Wrapper and request that tokenised code be generated for your
program, you have another option when it comes to running your program.
In this mode. Rexx/Wrapper creates an executable progam called rexxtok
or rexxtok.exe. This program can be run independently of the rexxwrap.cmd
program, and can create or execute tokenised Rexx code.
To generate a file of tokeinsed Rexx code, run rexxtok with the following
options:
- -ssource file name
The name of the Rexx source program. See Rexx Filename
for the format of the filename.
- -ttokenised code file name
The name of the output Rexx tokenised code. This can also include a
absolute or relative path name.
eg.
rexxtok -srexxcps.rexx -trexxcps.tok
To execute the tokenised Rexx code, run rexxtok with the following options:
- -x
This indicates that the tokenised code is to be executed.
- -ttokenised code file name
The name of the output Rexx tokenised code. This can also include a
absolute or relative path name.
- -ssource file name
The name of the Rexx source program. See Rexx Filename
for the format of the filename. This is an optional parameter when
executing the tokenised code. If your tokenised program uses trace
or SOURCELINE, specifying the name of the Rexx program that the
tokenised code was generated from, will allow these featues to work.
You are on your own if the Rexx program supplied is not the
program the tokenised code was generated from!
eg.
rexxtok -x -trexxcps.tok
Getting at the original program
When Rexx/Wrapper runs, it will display details on how to extract the
source code (or tokenised code) from the executable Rexx/Wrapper built.
Essentially, this involves running the generated executable program with the
--key=key value option. Assuming you created an executable called
rexxcps, and you did not request encryption of the Rexx code or
tokenised code:
rexxcps --key=1
will display the original source code. The encryption code generated
by Rexx/Wrapper will be displayed during the building phase, so make a note
of it. If you asked for tokensed code, then the executable will still dump
out the tokenised code, but it won't make much sense, or be much use.
Supported C compilers
Rexx/Wrapper supports the following C compilers:
Acknowlegements
All compression code in the zlib directory is Copyright (C) 1995-1998
Jean-loup Gailly and Mark Adler.
All encryption code in the des directory is Copyright (C) 1995-1997
Eric Young (eay@cryptsoft.com).
Copyright ©
Mark Hessling 1999-2004
<M.Hessling@qut.edu.au>
Last updated 23 May 2004