            Example of RxQueue & Intertask Communication

This package and its contents were written by Dick Goran, author of
the "REXX Reference Summary Handbook" (CIS 72200,347; IBMLink
DEV4672; FIDO 1:209/705; Internet 72200.347@compuserve.com), in
response to a question posted on the CompuServe OS2DF1 forum. It is
released to the general domain with the hope that it might help
others understand the use of REXX queues and intertask
communication and synchronization between multiple programs using
REXX.

This package should contain the following files:

     TEST80A.CMD    The parent program.
     TEST80B.CMD    The child program.
     TEST80.TXT     This file.
     TEST80.TRC     An annotated TRACE R output of both programs
                    showing the interaction of the two.

I have applied sequence numbers to both of the programs for two
reasons: 1) to make discussion of them easier; 2) to correlate the
source statements to the .TRC trace output file.

It is assumed that the user has loaded and registered the REXXUTIL
DLL with:

     call RxFuncAdd 'SysLoadFuncs', 'REXXUTIL', 'SysLoadFuncs'
     call SysLoadFuncs

This is best accomplished within a STARTUP.CMD since it is then
accomplished automatically when OS/2 is IPL'ed (Initial Program
Load).

The following indicates the functions of each program in a time-
line fashion, of sorts. The numbers preceding each description
relate to the sequence numbers in the respective source programs.

TEST80A   TEST80B
-------   -------
02 - 03   The value of an environment variable, TRACE, is retrieved
          for the session and used as and expression in a TRACE
          command. If the environment variable has not been set, no
          tracing will occur in either the parent or the child.

          The NOP command is present because of a quirk in the REXX
          trace facility which can cause a trace line which would
          be desired to be ignored. If an instruction is ignored,
          it will be the NOP command.

          Since there is no way to use a similar environment
          variable in the child's session, this value is passed to
          the child as a calling parameter.

06 - 08   A new queue, named TEST80, will be created and made the
          active queue. The active queue at the times (normally
          SESSION) is stored in the variable "old_queue" for later
          restoration.

11 - 14   Two lines, each containing "TEST80 - Line number n"
          (where n is the line number) are stowed in the active
          queue with the QUEUE command in a FIFO (first in, first
          out) manner.

16 - 19   The child, TEST80B.CMD is started, minimized (/MIN). This
          new task will have a title of "Test80B Child" which will
          appear in both the OS/2 task list (Ctrl-Esc) and the
          title bar at the top of the session's window.

          Three parameters are passed to the child - the name of
          the queue where the lines were QUEUED, the number of
          lines in the queue, and the value of the TRACE=
          environment variable from the parent. Commas are not used
          to separate these three parameters as all of the data
          following the program name (TEST80B.CMD) is passed as a
          single string.

20 - 23   The parent then "sleeps" for 2 seconds followed by
          checking to see how many lines still exist in the queue.
          If the queue has been drained (i.e. the number of lines
          = 0) then the DO loop is exited; otherwise, the parent
          iterates through this "wait and check" sequence. The
          value of 2 seconds is arbitrary and any convenient value
          could be used.

          07 - 08   The parameters passed to the child are parsed
                    into the variables named in the template. I.e.
                    queue name, number of lines queued and the
                    value of the TRACE environment variable from
                    the parent. All three parameters are received
                    as a single string exactly as they were built
                    by the parent.

                    The presence of the period (.) as a fourth
                    expression in the template is used to cause
                    any trailing spaces to be assigned to a dummy
                    or null variable.

                    A TRACE command is issued with the same value
                    used by the parent. A file, containing the
                    trace output like the TEST80.TRC file included
                    in this package, can be created by starting
                    the parent with:

                         SET TRACE=R
                         TEST80A 2>SYSTRACE

                    This would cause the trace output from both
                    the parent and the child to be written to a
                    file named SYSTRACE in the current directory.
                    (Note: - This file will be locked by the child
                    process until the child's session is ended
                    with an EXIT command.)

          10 - 11   The line counter variable is initialized and
                    the current REXX queue for the session is set
                    to the same private queue that was used by the
                    parent.

          13 - 17   Each line is retrieved from the queue and
                    echoed on the display.


          19 - 24   The two line counts are compared and the
                    result is written to the display. The child
                    task is then exited to the command line
                    session. This incomplete ending (i.e. the
                    session was still active) was left this way as
                    specifically for the example.

                    The session could be terminated by passing an
                    EXIT command to the command processor
                    (CMD.EXE) from the REXX program by including
                    'EXIT' (with the quotes) in place of the REXX
                    EXIt command on line 24.

26 - 32   When the queue has been depleted, the private queue
          designation for the session is replaced with the original
          queue, the result of the private queue being deleted is
          checked and the program exits.
