===========================================================================
 VX-REXX Tech Note #9:

                                       Creating Ami Pro macros with VX-REXX

                                                          February 15, 1995

                                  Applies to VX-REXX Version 2.0 and higher
----------------------------------------------------------------------------

                                                       Watcom International
                                                          tech@watcom.on.ca

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


Abstract
--------

This technical note describes how to use VX-REXX to create macro files for Ami 
Pro for OS/2.  These files can be invoked from within Ami Pro, and have access 
to all of the facilities of the Ami Pro native macro language. 

Creating an application macro is not very different from creating an executable 
program.  Create the program as you normally would.  You can give it a visual 
interface if you want, or use a code file. When you are done, select "Make 
Macro" from the "Project" menu.  You should give the macro a .CMD extension.

You can run the macro in Ami Pro by selecting "Play REXX File" in the "Macros" 
submenu of the "Tools" menu.  A file dialog will come up, and you can select
the macro you want to run.


Making menu items
-----------------

It is possible to create a menu item for your VX-REXX macro to provide 
convenient access to it. To create a menu item for your REXX program, you must 
make a small Ami Pro macro language "stub" program that invokes your REXX 
program.  VXAMBMP.SMM is an example of such a program. To make a stub for
your REXX program, copy VXAMBMP.SMM to a new name and select
(from the Ami Pro menubar) "Tools/Macros/Edit"
to change it.  By modifying the "Defines" at the top, you can customize the 
macro for your REXX program.


Making your windows feel "at home"
----------------------------------

VX-REXX windows in Ami Pro macros behave slightly differently than Ami Pro 
built-in macros.  Built-in dialogs stay in front of their "parent" window, 
known in PM terms as the "FrameOwner."  You can set the FrameOwner property on 
VX-REXX windows to get the same behavior. A VX-REXX window that has its
FrameOwner property set will never move in front of its owner.  For instance:

    AmiPro = VRMethod( 'Application', 'GetActiveWindow' )
    call VRSet window, 'FrameOwner', AmiPro
    
You can also disable the parent window to get the effect of a modal window: 
    
    call VRSet AmiPro, 'Enabled', 0

But be sure to re-enable the window when your macro exits!  If you are
going to disable Am Pro windows, be sure to add signal handlers to your
REXX macro so that in the case of a syntax error or some other
unforseen condition your macro will exit gracefully and re-enable
the windows.
            

More Information
----------------

There is a thorough discussion of integrating Ami Pro and REXX in the Ami Pro
online Macro document, under the title: "Integrating REXX Commands."  


Known Limitations
-----------------

Ami Pro 3.0 and 3.0a will GPF if a call to an external REXX function contains 
omitted arguments (this applies to any REXX function).  You can work
around this by providing all arguments.

