RE: die() RE: rpg <-> ifs sample...

[Scott Klement <klemscot@xxxxxxxxxxxx>]

>
> Thank you... Does this *escape end the JOB, or just the RPG Program?  And
> would it be considered as a LR *ON or *OFF
>

It ends the call stack entries above the one where the message was sent
to, and signals an error to the entry that receives it.   Does that make
sense?  That's the best way I can think to say it.

I guess you could say that it's like having *INLR turned on, as it closes
all of the files, cleans up the variables, etc.   The key difference is
that *ESCAPE messages are intended to end programs "abnormally".  They're
how programs signal fatal errors to the ones who called them, so that
the caller knows that something went wrong.

Below is some code to demonstrate what I'm saying...   This is a program
called "TESTESC".   It will display the call stack just before sending the
escape message, and then send the message to the call stack entry you
specify as a paramter.

The way it works, the parameter is the number of call stack entries prior
to the one containing the DIE() procedure...

So, if you do:

CALL TESTESC PARM(1)

it will send the message to the TESTESC procedure (the program's main
procedure) which just ends the die() procedure, and signals an error.  The
main procedure thinks that die() crashed, and says "The call to DIE ended
in error".

CALL TESTESC PARM(2)

For this it sends to the PEP call stack entry, which is just a call stack
entry generated by the compiler that does nothing but call the main
procedure of the program.   So, both die() and testesc() are ended, and
the PEP signals a function check error to complain that you didn't monitor
for this escape message.

CALL TESTESC PARM(3)

This is the number I used in my examples in the IFS tutorial.   Since this
goes to the first entry before the program in the stack, the entire
program is ended.   Since we called TESTESC from the command-line, the
error message is displayed in the message line, and we're shown the failed
command, so we can try again.   Had you called this from a program, that
program would've received an error, and would've had to monitor for that
error, otherwise it would go to the display program/messages screen with
a function check.

If you take this a few steps further, you can also use it to end the call
stacks before that... or if you end all of the call stack levels, the job
will end.

In all cases, the end is an "abnormal" end, the idea is to signal an error
to the caller.

Here's the sample program, TESTESC:

     H DFTACTGRP(*NO)

     D die             PR             1N
     D    ent                        10I 0 value
     D    msg                       256A   const

     c     *entry        plist
     c                   parm                    count            15 5

     c                   callp     die(count: 'Crunch')

     c                   eval      *inlr = *on


     P die             B
     D die             PI             1N
     D    ent                        10I 0 value
     D    msg                       256A   const

     D QMHSNDPM        PR                  ExtPgm('QMHSNDPM')
     D   MessageID                    7A   Const
     D   QualMsgF                    20A   Const
     D   MsgData                    256A   Const
     D   MsgDtaLen                   10I 0 Const
     D   MsgType                     10A   Const
     D   CallStkEnt                  10A   Const
     D   CallStkCnt                  10I 0 Const
     D   MessageKey                   4A
     D   ErrorCode                    1A

     D dsEC            DS
     D  dsECBytesP             1      4I 0 inz(%size(dsEC))
     D  dsECBytesA             5      8I 0 inz(0)
     D  dsECMsgID              9     15
     D  dsECReserv            16     16
     D  dsECMsgDta            17    256

     D MsgLen          S             10I 0
     D TheKey          S              4A

     D QCMDEXC         PR                  ExtPgm('QCMDEXC')
     D   command                    200A   const
     D   len                         15P 5 const

     c     ' '           checkr    msg           MsgLen
     c                   if        MsgLen<1
     c                   return    *off
     c                   endif

     c                   callp     qcmdexc('DSPJOB OPTION(*PGMSTK)': 200)

     c                   callp     QMHSNDPM('CPF9897': 'QCPFMSG   *LIBL':
     c                               Msg: MsgLen: '*ESCAPE':
     c                               '*': ent: TheKey: dsEC)

     c                   return    *off
     P                 E