============================================================================
 VX-REXX Tech Note #12:
                                Adding splash page support to your projects

                                                         September 11, 1995

                                         Applies to all versions of VX-REXX
                     
----------------------------------------------------------------------------

                                                       Watcom International

============================================================================

This Technical Note builds on the material found in Technical Note #5, 
however you do not need to have Technical Note #5 to use or understand
this one.


Abstract
--------

When VX-REXX builds an executable file from your project (using the
"Make EXE..." menu option), it binds your program to a stub file called
PMEXE.EXE.  This tech note and the accompanying code shows you how to
build your own PMEXE.EXE file.  In particular, this Tech Note shows
you how to add splash screen support to PMEXE, so that your application
can display a splash screen as it loads.



To Add a Splash Screen To Your Project
--------------------------------------

To add splash screens to your application, do the following:

1) If you are running VX-REXX 2.0, either upgrade to 2.1 or install
   the resource compiler (VXREZ 1.2, available at the same place you
   got this file).
   
2) Copy the PMEXE.EXE that accompanies this Tech Note into your
   project's directory.
   
3) Copy SPLASH.RC into your project directory. 
   
4) Load your project into VX-REXX and edit its resources.  Add the
   following two lines to the .RC file for your project: 
   
        rcinclude "splash.rc"
        bitmap PMEXE_BITMAP_ID d:\os2\bitmap\os2logo.bmp
        
   Change the path of the bitmap above to whatever bitmap you
   wish to use as your splash screen. 

5) Compile the resource file and then make a .EXE file for your
   project. 

When you run the .EXE it will display the bitmap when it
starts up.

Note that the splash screen disappears either when the timeout
value has been reached or when the user clicks on it with a 
mouse button.


Customization of the Splash Screen
----------------------------------

You can change a few parameters by defining macros before 
the "rcinclude" line.  The macros and their
default values are defined in the file "splash.rc".

For example, if you wanted to change the timeout value for
the splash screen to 15 seconds and prevent the splash
screen from being hidden once the project has been loaded,
you would do this:

     #define PMEXE_TIMEOUT_INTERVAL 15
     #define PMEXE_HIDE_AFTER_LOAD   0
     
     rcinclude "splash.rc"
     bitmap PMEXE_BITMAP_ID d:\os2\bitmap\os2logo.bmp
     
The source is included if you wish to do more extensive customization
than is available with the macros.


=============== Below is the original text for Tech Note #5 ===============

Important Note
--------------

This tech note assumes you have either WATCOM C/C++ 9.5 or higher or
IBM's CSet++ 2.1 and know how to compile files.


PMEXE.EXE's role in life
------------------------

When building an executable, VX-REXX simply takes PMEXE.EXE (found
in your VX-REXX directory) and binds the REXX code and binary window
data to the end of it.  PMEXE.EXE doesn't really do much.  As shipped
with VX-REXX, this is what it does:

      1) Finds and loads the VROBJ.DLL runtime library.
      2) Checks to see that the version of VROBJ is at least the
         same version as PMEXE.EXE.
      3) Calls an entry point in the DLL to get things started.

That's it.  By building your own PMEXE.EXE and installing it in
the VX-REXX directory (or using VXREZ 1.1 as described later) you can
modify this behaviour.  Why would you?  Well, you might want to display
your own splash page, disable the version warnings, register your
own exe-based REXX external functions, and so on.


Building a new PMEXE.EXE
------------------------

Building a new PMEXE.EXE is very simple.  Look in the PMEXE directory.
In the H and C subdirectories are the files PMEXE.H and PMEXE.C.  These
contain cover functions that do all the dirty work for you.  All you
need to do is call them from another C file, such as STUB.C which
has been provided for you to examine.  Basically all STUB.C does
is:

       -- Calls PMExeLoadDLL to load the DLL
       -- Calls PMExeVersion to check the version number
       -- Calls PMExeRun to run the VX-REXX program.

Very simple.  See the README.TXT for notes on how to build the
PMEXE.EXE from the source.  Makefiles have been provided for WATCOM C
and for IBM's CSet.  The code has not been optimized to be as small
and efficient as possible, so there are things you can do to simplify
it if you want.

WARNING:  If you do register your own external functions, be sure not
          to register functions that have the same name as one of the
          files in your VX-REXX program, otherwise your program will
          refuse to run....


Using the new PMEXE.EXE
-----------------------

To use the new PMEXE.EXE, you can do one of two things:

   1. Make a backup copy of the original PMEXE.EXE in your VX-REXX
      directory.  Copy the new PMEXE.EXE into that directory.  Now
      every executable you make will use that PMEXE.EXE as its
      stub.

   2. Get and install VXREZ 1.1, a set of VX-REXX macros that let
      you bind resources to your VX-REXX executables.  (It is available
      the same place you got this tech note from.)  This version of
      VXREZ has a new feature:  if it sees a PMEXE.EXE in the same
      directory as your project's .VRP file, it will bind the resources
      to it and use it as the stub file instead of VX-REXX's own
      PMEXE.EXE.  (Note that if you created a PMEXE.EXE with resources
      already bound to it, the resource compiler will first strip
      off these resources before binding the new ones.)

That's it! Have fun....


Sample Code
-----------

There are two subdirectories with sample code.  The PMEXE subdirectory
builds a simple PMEXE.EXE much like the one that comes with VX-REXX 2.0.
The SCAT subdirectory builds a version of PMEXE.EXE that registers
a new external function that the VX-REXX program then uses.
