Rexx/Wrapper
Version 2.4
21 Sep 2006

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:

1. A supported Rexx interpreter
2. 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).