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
|
