============================================================================
 VX-REXX Tech Note #3:                           
			         Using the REXX Queue to start VIO programs

                                                          February 16, 1994

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

                                                       Paul Prescod
                                                       WATCOM International

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

Abstract
--------

Certain programs require OS/2 VIO support to run.  Since VX-REXX provides
only a Presentation Manager environment, these programs must be run in a
seperate session using the "Start" command.  This may introduce unwanted
concurrency issues.  A function StartVIO is provided to resolve these
issues.


Recognizing Programs that require VIO Support
---------------------------------------------

Some OS/2 text mode programs require certain VIO functions that are not
provided in a Presentation Manager environment. For example, the OS/2 PSTAT 
command relies on VIO support.  If you try to run it within a VX-REXX 
program, you will get a "SYS0436: An invalid VIO handle was found" error.

Other programs which exhibit this problem are the CM/2 SEND.EXE and
RECEIVE.EXE programs, and the SPF/2 editor.  Unfortunately, the error
message varies, so it is not always easy to recognize that the problem
is caused by the fact that VX-REXX programs are Presentation Manager
based.

The easy way to check is to make a small REXX TEST.CMD file which runs
the program, i.e.

/* Test program */
'send filename'

Run it from the command line like this:

[C:\] test.cmd

Then run it in a Presentation Manager session like this:

[C:\] pmrexx test.cmd

If it works in the first case, but not the second, the program is probably
dependant on VIO support.

OS/2 Start
----------

The easiest way to get around VIO problems is the OS/2 "Start" command 
which allows you to launch any program in a different session.  Using start
you can launch VIO programs from PM or vice versa.  More information on the
using the start command from within VX-REXX can be found in the VX-REXX 
Read Me First in the section "Tips", "Launching Programs from REXX."  
The start command has many command line switches to specify the type of
program to run and the type of window (full screen, minimized etc.) to run
it in. There is more information on  the start command features in the 
OS/2 Command Reference object in the information folder. If you are 
familiar with the start command, however, you will know that it runs the 
new process concurrently (at the same times as) the current program.  If 
this is a problem, you must force the original program to halt until the 
second program exits.  Because these two programs are in different 
processes, the most efficient way to do this is the standard REXX 
interprocess communication facility, a REXX queue.

StartVIO
--------

StartVIO, listed below, is a REXX function which you can add to your 
programs to start a text mode process, halt the main program until it 
returns, and send the return code via a REXX queue.  StartVIO and RUN.CMD 
are simple enough that you can modify them if they don't fit your needs.  
They also serve as a good example of the power of REXX queues.  For more 
information on REXX queues, read the chapter "Queue Interface" in the 
online "REXX Information" reference in the VX-REXX folder.


Syntax
-----

rc = StartVIO(command)


Setup
-----

You must add the StartVIO function to your program, and put the run.cmd
program in your path.  To add StartVIO to your program, you can cut and
paste it somewhere in your project.  Do not add run.cmd to your file or
project. Start is an OS/2 command interpreter command, and not a VX-REXX 
or REXX command.  So run.cmd must be somewhere in the path so that the 
command interpreter can find it.


Example
-------
This example runs the OS/2 pstat command, stores its return code in the
variable called rc, and prints rc.

    rc = StartVIO("Pstat")
    say rc




Code
----
----------------------------------------------------

StartVIO:procedure
/* Run a VIO program synchronously */
/* Should be part of your program */
parse arg command

    /* Create queue */
    queue = RXQueue( "Create" )
    oq = RXQueue( "Set", queue )
    
    "start /win /c run.cmd" queue command "<con >con"
    
    /* Wait */
    rc = linein( "QUEUE:" )
    
    
    /* Destroy Queue */
    call RXQueue "Set", oq
    call RXQueue "Delete", queue
    
return rc

----------------------------------------------------

/* run.cmd - run program and signal completion on rexx queue */
/*           Should be in your path  */
Main:
    parse arg queue commands

    commands
    retval = rc
    call RXQueue "Set", queue
    push rc
return


