This tries to explain what the MSEXTRACT_SCRIPTS script does.

First of all, some history.

Back in the bad old days, when I had a potential reginald bug, I would send Jeff a whole slew
of scripts with an explanation of how to create the "bug" scenario. (Hopefully, I'm MUCH better
at reducing the scenario to a couple of trivial scripts). Be that as it may. One of the problems
I kept on having was that I would create a zip file, send it to Jeff, only to get an irritated
note back stating that this or that script hadn't been included. So .....  I decided to write
MSEXTRACT_SCRIPTS. The original idea behind it was simply to be able to specify a starting script
and then the application would search through ALL the scripts called by this as well as any called
by sub-scripts. You would then be shown a list of all the scripts needed by the starting one
and you could opt to zip these scripts automatically.

After a while, when Jeff introduced the idea of projects, I started adding the ability to take
this list of scripts and automatically move/create directories to which the source code would
be moved. (The idea being that you would then create a project in that directory and create
your exe or dll).

This got put on the back-burner for two reasons Firstly, Jeff introduced the idea of being able
to create a project in the same directory as all your scripts. (Before, when you created the
project, you had to specify a directory, whereupon the project was created with the same name
as the actual directory). The second reason was the fact that generated DLL's and exe's simply
didn't work.

A couple of months ago (approx May 2007) Jeff found the "last" offending bug and suddenly it
made sense to dust off the exe/dll part of msextract_scripts.



What can you do with the script.

Well, if you had the energy to wade through the text above, you'll start to see that it can
"analyze" your scripts so if you want to package your application into an exe and or DLL it's
pretty trivial.

Start the script and choose your starting rexx script via the ... button. Select OK
(By default, the debug menu is on - it's been so long since I ever switched it off that
 I have forgotten how that affects the results. I thnk the warnings are fewer)
 
What you'll see is a list of all scripts called by the first one. In addition, you'll
also see warnings for any unexpected code lines. (These will obviously vary greatly from
one programmer to another. I have my programming style and the extract program has been
written/tailored based on that). Warnings that you might see are:-

-  a call to an external script where you haven't specified .rex as a suffix to the call.
   Jeff talked about removing this "requirement", but, personally, I think it's a very
   good standard. If I see the following in my code
          rc = do_something.rex(fred)
   I KNOW it's an external script. If I write
             rc = do_something(fred)
   it could be a procedure in the current script OR an external script - I have no way of
   knowing.
-  a (misspelled) call to a procedure/script. This'll happen when msextract can't find the
   call as an internal procedure or an external script
-  "doubled" calls to rexx functions. For example
              rc = translate(userid())
   I don't know why these get flagged and I haven't put any effort into analyzing why either.
   When the warning "bothers" me, I simply change the code to
              temp = userid()
              rc = translate(temp)
   and the extract program is happy.
-  esoteric calls. These are going to vary depending on your programming style
-  an internal procedure name in a script that also exists as an external rex script
   (chances are that this is unintentional)

In addition, the extract application CAN'T find code where a call to a rex script is contained
in a character string that is then rex INTERPRET'ed. If you have that sort of code (and I do)
you'll have to remember to include such scripts in your project manually (or if possible, include
them as internal procedures in the script where they are used).

REMEMBER - these "warnings" are just that. They can either be an indication that your application
           won't run properly (a misspelled call) or they can mean nothing.

Okay - you're looking at the extracted script results. If you look at the menu Options, there are
four choices

1)       Exe/DLL
2)       Zip
3)       Print
4)       Save

Let's take the easiest ones first. Print and save do just that with the results shown in the
progress control. ZIP will zip all the scripts into a file with the same name as the starter
script.

EXE/DLL.

Here comes the fun. Select this option and you'll be shown a new window. All the script names
from the first window will be shown in the left-hand pane. What you do now depends on what you
want to do.

Let me digress a little and explain what I use Reginald for at work (mainly). I'm a COBOL
developer, and as such, I've written a number of applications that can facilitate
development/analysis of COBOL source code. These can vary from sorting the sections in a program
in alphabetical order, to checking that the developer has balanced IF statements, to generating
default SQL code that can be inserted into the source code. Since they are all based on COBOL
programs, it follows that I've developed, over time, a number of common routines based on
a "standard" way of processing the code.
With Reginald's projects and exe/DLL's, it means that I can generate "utility" DLL's that can be
used by almost all the scripts (for example, one general utility DLL and another general one
for programs that access SQL via ODBC)
What does this have to do with the window you were just looking at ?? It results in a simple method
of maintaining your projects without necessarily having duplicate code in multiple DLL's and/or
EXE's.

Back to the window. You'll see that the right-hand pane is empty - it's just waiting to be filled
with objects from one of two sources:-
1)    the left-hand pane (mark one of more items and press the ===> button to move them across)
2)    via the menu pulldown. Select Options, Show project contents. The first time you do this, you'll
      see "Utilities" as the only option (hey, I wrote the application). You'll also see "Search for
      project" which allows you to select an existing project and load its contents to the right-hand pane-
      (Once you select a project this way, it will be shown every time you run the application. A total
      of 10 projects can be used this way - they're saved in the windows registry if you ever want to
      clean up a bit). If you select a project in this way, you'll see that the entry
      control above the right-hand pane shows which project was loaded.

Assuming you have some form of Utility project/DLL, you can now select the menu pulldown Options,
Show/hide duplicates on left. The application will now match any scripts on both sides and remove any
duplicates from the list on the left-hand side (obviously, they are ONLY removed from the list, NOT
from disk).
You're now left with the unique scripts for your application. Now it's up to you - are these scripts
REALLY unique, or as in my case, maybe they're ODBC utilities that will be used by other applications.
Simply move any scripts you DON'T want saved in the project for your starting script to the
right-hand pane. NOW you're left with your unique scripts in the left-hand pane.
 
Select Options, Create project, Left side and a project will be created with the same name as the
FIRST script in the list (this will be your starter script normally).

Now let's suppose that you moved five scripts to the right-hand pane. You intend to put three of these
in the ODBC project, but you want to add the other two to the current loaded project. Mark the three
unwanted scripts in the right-hand pane and press the <=== button to move them back to the left.
Now select Options, Create project, Right side and you will have updated your "utility" project.

REMEMBER - YOU'RE ONLY CREATING/UPDATING THE PROJECT, NOT THE EXE/DLL'S (If you browse a project
using a hex editor such as XVI32, you'll see that it only contains the NAMES of the items in the
project, but not the actual code itself).

Once you've created your exe/dll'd from the project, I would STRONGLY advise that you move them to
a different directory before testing. The reason for this is as follows. You have your exe/dll's in
the same directory as all your source code. You start running your exe which does a macro call to
any DLL's you've created. Unfortunately, you've forgotten to include some script that's needed.
When the time comes to run this script, since it's not in the DLL, reginald finds it in the current
directory as ordinary source code and runs it. Then of course, it all falls over when you move the
exe/dll's to their own directory and reginald can't find that missing script. By moving them to
a separate directory FIRST, you'll find that sort of problem more easily/quickly.