Identifying a call stack entry

If a CL procedure is to send a message to an original program model (OPM) program or another Integrated Language Environment® (ILE) procedure, you must identify the call stack entry to which the message is sent.

The message is sent to the call message queue of the identified call stack entry.

The TOPGMQ parameter of the Send Program Message (SNDPGMMSG) command is used to identify the call stack entry to which a message is sent. Identification of a call stack entry consists of the following two parts:

Specification of a base entry
This specification identifies a program or procedure within the call stack (this is element 2 of TOPGMQ).
Offset specification of a base entry
The offset specification (element 1 of TOPGMQ) identifies if you send the message to the base (*SAME) or if you send the message to the caller of the base (*PRV).

The specification TOPGMQ(*PRV *) identifies the base entry as being the one in which the procedure using the Send Program Message (SNDPGMMSG) command is running. The offset is specified as being one entry previous to that base. This specification identifies the caller of the procedure which is using the command.

To understand how to identify the base entry, element 2 of TOPGMQ, you also need to understand the call stack when an ILE program is running. Two programs are used to illustrate this. Program CLPGM1 is an OPM CL program and Program CLPGM2 is an ILE program. Because program CLPGM2 is ILE, it can consist of several procedures, such as: CLPROC1, CLPROC2, CLPROC3, and CLPROC4. At run time, the following calls take place:

CLPGM1 is called first.
CLPGM1 calls CLPGM2.
CLPGM2 calls CLPROC1.
CLPROC1 calls CLPROC2.
CLPROC2 calls CLPROC3 or CLPROC4.

The following figure illustrates the considerations about the structure of the call stack when CLPROC2 calls CLPROC4:

There is a one-to-one correspondence between a call stack entry and an OPM program; for each call of an OPM program, one new entry is added to the call stack.
An ILE program, as a unit, is not represented on the stack; instead, when an ILE program is called, one entry is added to the stack for each procedure that is called in the program. As a result, you send a message to an ILE procedure, not to an ILE program.

Note: The first procedure to run when an ILE program is called is the Program Entry Procedure (PEP) for the program. In CL, this procedure (_CL_PEP) is generated by the system and calls the first procedure you provide. In this example, the entry for the PEP is between the entry for the OPM program CLPGM1 and the entry for the procedure CLPROC1.