The Retrieve Program  Stack command provides  return variables to  a CL
program for the programs in the program stack of the current job.

A typical series of commands would be entered as:

          DCL        &PGMLST *CHAR LEN(1515)
          DCL        &PGMCNT *DEC LEN(5 0)
           .
          RTVPGMSTK  PGMLST(&PGMLST) PGMCNT(&PGMCNT)

The  &PGMLST variable  would  contain 15  byte  entries for  up  to 100
programs  where each 15 character program  name is followed by 5 blanks
(for expansion).   The last 15  bytes are always blank  to allow for  a
'blank' test' The  first program in the list is the  top program in the
stack.    The last  program in  the list  is  the program  that invoked
RTVPGMSTK (the CPP for RTVPGMSTK is not included).

Specific return  variables  also exist  for  the current  program,  the
program that invoked  the current program, and the  program just before
that  program.  These are  considered the bottom three  programs in the
program stack.

The command provides for up to 100  programs in the program stack.   If
the number is exceeded, an escape message is sent.

Command parameters                                    *CMD
------------------

   CURPGM        The return  variable for  the current  program in  the
                 program stack.   The CPP for RTVPGMSTK  is bypassed so
                 this  is  the  program that  invoked  RTVPGMSTK.   The
                 variable must be declared as *CHAR LEN(10).

   FSTPGM        The return variable  for the first program  before the
                 CURPGM.    The  variable  must be  declared  as  *CHAR
                 LEN(10).   This is the program  that called the CURPGM
                 unless TFRCTL has occurred.

   SECPGM        The return  variable  for the  second  program  before
                 the CURPGM.   The variable  must be declared  as *CHAR
                 LEN(10).   This is the program  that called the FSTPGM
                 unless TFRCTL has occurred.

   THRPGM        The return variable for  the third program before  the
                 CURPGM.    The  variable must  be  declared  as  *CHAR
                 LEN(10).

   PGMCNT        The  return variable  for  the number  of  programs in
                 the  program stack.  The  variable must be declared as
                 *DEC LEN(5 0).

   PGMLST        The return  variable for the  list of  programs.   The
                 variable must  be declared  as *CHAR LEN(1515).   This
                 allows  for up to  100 programs in the  stack with the
                 last 15 bytes  always blank  (this allows testing  for
                 a  blank entry  to  determine the  end  of the  list).
                 Each  entry in  the  list is  made up  of  the program
                 name  (10  bytes)   followed  by  a   5  blanks   (for
                 expansion).

Technique used
--------------

RTVPGMSTK  is implemented  by  using the  QMHSNDPM  and QMHRCVPM  APIs.
These  allow  the sending  and  receiving of  messages  to any  program
message  queue in  the program  stack on  the basis  of a number.   The
QMHRCVPM program returns a  variable which acts like the  SENDER return
value  on  RCVMSG.   This  data  structure  contains  the name  of  the
program  that the message  was received from.   A loop is  used with an
increasing program number  to send  and receive from  until a  specific
message ID  is monitored for indicating  no more programs exist  in the
program stack.

Restrictions
------------

Because  the command returns  variables, it can  only be executed  in a
CL program.

Prerequisites
-------------

The following TAA Tools must be on your system:

         SNDESCMSG      Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   RTVPGMSTK     *CMD                   TAAPGMJ       QATTCMD
   TAAPGMJC      *PGM       CLP         TAAPGMJC      QATTCL