Identify a call stack entry

If a CL procedure is to send a message to an OPM program or another 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. Since program CLPGM2 is ILE, it can consist of several procedures, such as: CLPROC1, CLPROC2, CLPROC3, and CLPROC4. At runtime the following calls take place:

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

This figure below illustrates the following considerations:

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.

Figure 1. Example of runtime call stack with an OPM program and an ILE program with multiple procedures

Use the command as a base
To use the program or procedure that runs the Send Program Message (SNDPGMMSG) command as the base call stack entry, you can use the TOPGMQ parameter.
Identify the base entry by name
You can identify the base call stack entry by providing the name of the OPM program or ILE procedure running in that entry.
Use the program boundary as a base
You can specify the program boundary as the base call stack entry by using the *PGMBDY special value.
Use the most recently called procedure as a base
You can specify the most recently called procedure as the base call stack entry by using the *PGMNAME special value.
Use a control boundary as a base
You can identify the base call stack entry as the one at the nearest control boundary by using the special value *CTLBDY.
Considerations for service programs
This topic describes differences between ILE programs and ILE service programs.

Parent topic: Send messages from a CL program

Related concepts

Call message queue

Use the command as a base