%TARGET (program-or-procedure { : offset } )

%TARGET is used as the third operand of the SND-MSG operation. %TARGET does not return a value, and it cannot be specified anywhere other than for the SND-MSG operation.

%TARGET specifies the target program or procedure for the message.

The first operand can be
  • *SELF. This is the default for an informational message. The message is sent to the current procedure.
  • *CALLER. This is the default for an escape message. The message is sent to the caller of the current procedure.
  • The name of a program or procedure on the program stack. It must be a character value in the job CCSID.
    Note: A program or procedure is on the program stack if it was called prior to the current procedure, and has not returned yet from that call.

The second operand is the offset on the program stack. It is optional. If it is not specified, it defaults to zero. It must be a numeric value with zero decimal positions. The value cannot be negative. It represents the number of programs or procedures on the program stack prior to the specified program or procedure for the message to be sent. For example, if PROC1 called PROC2, and you want to send a message to the caller of PROC2, you specify %TARGET('PROC2':1), indicating that you want to send the message to the program or procedure at offset 1 from PROC2.

Note: If the current procedure is the main procedure of the program, the caller is the Program Entry Procedure (PEP) for the program. If you want to send the message to the caller of the program, specify *CALLER for the first operand of %TARGET and specify a value of 1 for the second operand of %TARGET to indicate that you want to send the message to the caller's caller.

Examples of %TARGET

For the following examples, in the RPG programmer's application, CL program MYCLPGM calls RPG program RPGMAIN, which calls RPG program RPGSUB1. Within RPGSUB1, the main procedure calls subProc1, which calls subProc2.

When subProc2 is running, the following represents the call stack for the job. The call stack can be seen by using the DSPJOB command with parameter OPTION(*PGMSTK). 


     Program    Library       Statement         Procedure
     -------    -------       ---------         ---------
     ...
     MYCLPGM    MYLIB         100
     RPGMAIN    MYLIB                           _QRNP_PEP_RPGMAIN
     RPGMAIN    MYLIB         1                 RPGMAIN
     RPGSUB1    MYLIB                           _QRNP_PEP_RPGSUB1
     RPGSUB1    MYLIB         2                 RPGSUB1
     RPGSUB1    MYLIB         5                 subProc1
     RPGSUB1    MYLIB         8                 subProc2

The subProc2 has several SND-MSG operations.

  1. The message type is not specified, and %TARGET is not specified. The default message type is *INFO, so an informational message is sent. The default target procedure for an informational message is the current procedure. The message is sent from subProc2 to itself.
  2. The SND-MSG operation is the same as the previous one, but the message type and target are explicitly specified. The message is sent from subProc2 to itself.
  3. The SND-MSG operation is the similar to the previous one, but target procedure is the caller of the current procedure. The message is sent from subProc2 to subProc1.
  4. The message type is *ESCAPE, so an exception message is sent. The default target procedure for an exception message is the caller of the current procedure. The message is sent from subProc2 to its caller subProc1.
  5. The SND-MSG operation is similar to the previous one, but the second operand of %TARGET is set to 1, indicating that the target procedure is the caller of the procedure specified in the first operand of %TARGET. The message is sent from subProc2 to its caller's caller, RPGSUB1.
  6. The SND-MSG operation is similar to the previous one, but the second operand of %TARGET is set to 2, indicating that the target procedure is the two call-levels above procedure specified in the first operand of %TARGET. The message is sent from subProc2 to _QRNP_PEP_RPGSUB1. If RPGMAIN is the intended target procedure, then the value of 3 must be specified for the stack offset, to account for the presence of the Program Entry Procedure _QRNP_PEP_RPGSUB1 on the program stack.
  7. The SND-MSG operation is intended for the program or procedure that calls the RPGMAIN program. However, the call stack shows that the caller of RPGMAIN is the Program Entry Procedure (PEP) for the program, _QRNP_PEP_RPGMAIN. The offset for %TARGET must account for any PEP procedures. The message is sent from subProc2 to MYCLPGM. 

SELECT;
WHEN option = 1;
   SND-MSG 'Msg 1'; //  1 
WHEN option = 2;
   SND-MSG *INFO 'Msg 2' %TARGET(*SELF); //  2 
WHEN option = 3;
   SND-MSG 'Msg 3' %TARGET(*CALLER); //  3 
WHEN option = 4;
   SND-MSG *ESCAPE 'Msg 4'; //  4 
WHEN option = 5;
   SND-MSG *ESCAPE 'Msg 5' %TARGET(*CALLER : 1); //  5 
WHEN option = 6;
   SND-MSG *ESCAPE 'Msg 6' %TARGET(*CALLER : 2); //  6 
WHEN option = 7;
   SND-MSG *INFO 'Msg 7' %TARGET('RPGMAIN' : 2); //  7 
ENDSL;