TAA Tools

 RTVPGMSTK2    RETRIEVE PROGRAM QUEUE 2               TAAPGNFR

 The RTVPGMSTK2 command  allows you to  extract one or more  values from
 a  program  stack  entry  into  a  CL  program.    This  provides  such
 information  as  who the  caller of  your program  is.   You  may 'walk
 thru'  the  stack by  bumping  the  stack  number  each  time  you  use
 RTVPGMSTK2.   If the  user has *JOBCTL  special authority,  the command
 may be used against any job.

 RTVPGMSTK2 uses the QWVRCSTK API to access the information.

 A  typical  use of  the  command is  to  extract the  program  name and
 library of the caller of a program.

         DCL        VAR(&PGM) TYPE(*CHAR) LEN(10)
         DCL        VAR(&PGMLIB) TYPE(*CHAR) LEN(10)
          .
         RTVPGMSTK2 JOB(*) PGM(&PGM) PGMLIB(&PGMLIB)

 Another example is where  you want to send  a message to the  procedure
 or program that  called your program.  Because the  procedure name will
 not  exist if  you are  called by  an OPM  program, the  following code
 uses this fact to determine how to send a message.

         DCL        VAR(&PROCNAME) TYPE(*CHAR) LEN(256)
         DCL        VAR(&PGM) TYPE(*CHAR) LEN(10)
          .
         RTVPGMSTK2 JOB(*) PGM(&PGM) PROCNAME(&PROCNAME)
                    /* If there is a procedure, send to it */
         IF         COND(&PROCNAME *NE ' ') THEN(DO)
         SNDPGMMSG  MSGID(CPF9897) MSGF(QCPFMSG) MSGDTA('xxx') +
                      TOPGMQ(*SAME (&PROCNAME)) MSGTYPE(*ESCAPE)
         ENDDO
                    /* If there is no procedure, send to program */
         ELSE       CMD(DO)
         SNDPGMMSG  MSGID(CPF9897) MSGF(QCPFMSG) MSGDTA('xxx') +
                      TOPGMQ(*SAME (&PGM)) MSGTYPE(*ESCAPE)
         ENDDO

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

    JOB           The job whose stack is to  be used.  This defaults  to
                  *, the  current job.   Otherwise, the  fully qualified
                  job name is required.

                  You must  have *JOBCTL special authority  to specify a
                  job name other than your own.

    STKNBR        The  requested  stack number.    This defaults  to the
                  special value *FIRSTPGM.

                  The definition  of *FIRSTPGM for  JOB(*) or the  fully
                  qualified job  of the current job, is  the first stack
                  entry  above  the caller's  program.   For  example if
                  PGMA calls PGMB  which uses  RTVPGMSTK2, PGMA will  be
                  returned.

                  If  a  job  other  than  the  current  job  is  named,
                  *FIRSTPGM means the first program in the stack.

                  If you  know where the program or  procedure is in the
                  stack,  you  may  enter   a  specific  number.     For
                  example,  if you  use RTVPGMSTK2  to  'walk thru'  the
                  stack,  you  would  probably  use *FIRSTPGM  and  then
                  bump  the STKNBRRTN  by 1  and use  the new  value for
                  STKNBR on the next iteration of RTVPGMSTK2.

                  *TOP may be entered  to return the program at  the top
                  of  stack  (in  most  cases  this  will  be  a  system
                  program).

    STKCNT        An  optional  return variable  that  will  contain the
                  number  of  stack  entries  found  in  the  job.    If
                  specified,  the  variable  must be  declared  as  *DEC
                  LEN(11 0).

    STKNBRRTN     An  optional  return variable  that  will  contain the
                  value of  the number  of the  stack entry  found.   If
                  specified,  the  variable must  be  declared  as  *DEC
                  LEN(11 0).

    PGM           An  optional  return variable  that  will contain  the
                  name  of  the program  of the  stack  entry found.   A
                  special value,  *N,  is returned  if  the program  has
                  been destroyed  or the library  containing the program
                  has  been locked.  If specified,  the variable must be
                  declared as *CHAR LEN(10).

    PGMLIB        An optional  return variable  that will  contain  name
                  of the  library in  which the program  is located.   A
                  special  value,  *N, is  returned if  the  program has
                  been destroyed  or  is  locked.    If  specified,  the
                  variable must be declared as *CHAR LEN(10).

    MIINST        An  optional return  variable  that will  contain  the
                  current  MI instruction number  of the program  of the
                  stack  entry found.  This  parameter is not meaningful
                  for    integrated    language    environment     (ILE)
                  procedures,  for which the  value 0  is returned.   If
                  specified,  the  variable  must  be  declared  as *DEC
                  LEN(11 0).

    MODULE        An optional  return  variable that  will  contain  the
                  name   of  the   module   containing  the   integrated
                  language  environment  (ILE)  procedure.    A  special
                  value,  *N,  is  returned  if  the  program  has  been
                  destroyed or  is locked.   Blanks will be  returned if
                  the  call stack  entry is  not an  ILE procedure.   If
                  specified,  the  variable  must be  declared  as *CHAR
                  LEN(10).

    MODULELIB     An  optional return  variable  that will  contain  the
                  name of  the library in  which the module  is located.
                  A  special value, *N,  is returned if  the program has
                  been  destroyed  or  is   locked.    Blanks  will   be
                  returned  if  the  call  stack entry  is  not  an  ILE
                  procedure.     If  specified,  the  variable  must  be
                  declared as *CHAR LEN(10).

    CTLBND        An  optional  return   variable  that  will   indicate
                  whether a control  boundary is active for  the program
                  or procedure.  Possible values are:

                      0  No control boundary is active
                      1  A control boundary is active

                  If specified,  the variable must be  declared as *CHAR
                  LEN(1).

    ACTGRPNBR     An  optional  return  variable that  will  contain the
                  activation  group  number   within  which  the   stack
                  entry's  program  or  procedure   is  running.    This
                  system-assigned   number   uniquely   identifies   the
                  activation group within  the job.   If specified,  the
                  variable must be declared as *DEC LEN(11 0).

    ACTGRPNAME    An  optional return  variable  that  will contain  the
                  name  of the activation  group within  which the stack
                  entry's program or procedure is running.

                  One of the following  special values is returned  when
                  the activation group does not have a name:

                  *DFTACTGRP  The  activation   group  is  one   of  the
                  default activation groups for the system.

                  *NEW  The  activation   group  was  created  when  the
                  program was called.

                  If  specified, the variable must  be declared as *CHAR
                  LEN(10).

    STMTID        An  optional return  variable  that will  contain  the
                  first high  level language  statement identifier.   If
                  this  parameter contains  the character representation
                  of a number, the  number is right-adjusted and  padded
                  on the  left with  zeros (for  example: '0000000645').
                  Although   Integrated   language   environment   (ILE)
                  procedures may  have multiple  statement  identifiers,
                  only  the first  will  be returned.    Blanks will  be
                  returned  if  the  call  stack  entry  is not  an  ILE
                  procedure.     If  specified,  the  variable  must  be
                  declared as *CHAR LEN(10).

    PROCNAME      An optional  return  variable  that will  contain  the
                  name  of  the  integrated language  environment  (ILE)
                  procedure.    Blanks  will  be  returned  if  the call
                  stack entry is  not an ILE  procedure.  If  specified,
                  the variable must be declared as *CHAR LEN(256)

 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
    ------        -----      ---------      ----------     -----------

    RTVPGMSTK2    *CMD                      TAAPGNF        QATTCMD
    TAAPGNFR      *PGM          RPG         TAAPGNFR       QATTRPG

Added to TAA Productivity Tools September 15, 2002


Home Page

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.