The  Send Escape  Message  command provides  two  simple solutions  for
sending an escape message from a CL program or a HLL program.

The simplest form is the SNDESCMSG command:

  **   For a CL program you would specify:

            SNDESCMSG  MSG('You blew it')

  **   For an RPG program you would specify:

     IMSGDS       DS                            512
     .
     C                     CALL 'SNDESC'
     C                     PARM           MSGDS

       Prior to  calling the SNDESC  program, you would  fill the MSGDS
       data structure with the text you want to send.

SNDESCMSG  sends CPF9898  as an escape  message with  the text provided
in the MSG  parameter as  the MSGDTA for  CPF9898.   The Message ID  is
always CPF9898.

The  use of  CPF9898  is good  for  those conditions  that  you do  not
expect  to be monitored  for such  as bad parameter  values or internal
limits have  been  exceeded.   If  you  expect  the user  may  want  to
monitor for a  message ID, a separate command  (SNDESCMSG2) is provided
that requires you specify a Message ID and Message file.

There  is  no real  advantage  to SNDESCMSG2  if  you are  coding  a CL
program (you could use  the system command  SNDPGMMSG instead).   There
are two subtle advantages of SNDESCMSG2:

  **   The command has fewer  parameters so you concentrate on  what is
       needed to send an escape message.

  **   From  a documentation  viewpoint, some  users  prefer SNDESCMSG2
       because  the most significant attribute  of SNDPGMMSG is MSGTYPE
       which can be  buried in the code.   SNDESCMSG2 makes it  obvious
       what is occurring.

SNDESCMSG2  has definite  advantages when  used from  a HLL  program in
that there are fewer parameters to deal with than the API.

The  TAAMSGF in TAATOOL  already has a  series of  blank messages (like
CPF9898) that you could use rather  than defining your own in order  to
gain a  unique Message  ID for  your function  that could be  monitored
for.    The  TAA  messages are  in  the  range  of TAA9881-TAA9888  and
TAA9891-TAA9897.

The typical interfaces for SNDESCMSG2 would be:

  **   For a CL program you would specify:

            SNDESCMSG2  MSGID(TAA9891) MSGF(TAAMSGF) MSGFLIB(TAATOOL)
                          MSGDTA(...)

  **   For an RPG III program you  would specify the following to  send
       Message ID TAA9891 in the TAAMSGF message file.

     IMSGDS       DS                            512
     .
     C                     CALL 'SNDESC2'
     C                     PARM 'TAA9891' MSGID   7
     C                     PARM 'TAAMSGF' MSGF   10
     C                     PARM 'TAATOOL' MSGFLB 10
     C                     PARM           MSGDS

       Prior to calling the  SNDESC2 program, you would fill  the MSGDS
       data structure with the text you want to send.

RPG IV code would appear as:

     C                   CALL      'SNDESC2'
     C                   PARM      'TAA9895'     MSGID             7
     C                   PARM      'TAAMSGF'     MSGF             10
     C                   PARM      'TAATOOL'     MSGFL            10
     C                   PARM                    MSGDTA          512

RPG IV  allows you to define the  512 byte MSGDTA field as  part of the
PARM  statement  (no data  structure is  needed).   Your  program would
place the text of the message in MSGDTA.

There is  no  difference between  SNDESCMSG/SNDESCMSG2 and  sending  an
escape  message using  SNDPGMMSG in  regards  to what  happens to  your
program.   In  either case, your  program will  be ended  and an escape
message is  sent  to  the  program that  called  your  program  (unless
TFRCTL was used).

If you  want a more  flexible solution  for your HLL  program, consider
the use of the TAA Tool RPGSNDMSG.

The SNDESCMSG  tool uses the QMHSNDPM API  and sends the escape message
to the  program  prior  to yours  on  the  Call Stack.    The  'calling
program' (the  name of the  program which uses  one of the  Send Escape
programs)  is determined  in the  CPP and  the message  is sent  to the
program message queue prior to the calling program.

ILE Program use of SNDESC
-------------------------

SNDESC  or  SNDESCMSG2 may  also  be used  from  an ILE  program.   ILE
programs are  made  up of  modules.   When  one  of the  modules  calls
SNDESC, the escape  message is sent to the program  previous to the one
that called SNDESC.

This  happens regardless of how many modules  are in the call stack for
the same program.

For example, assume you  have used CRTBNDRPG for  a program named  RPG1
which calls SNDESC.   CRTBNDRPG creates a Procedure  Entry Module (PEP)
and  a temporary  module.  Assume  CLBEGIN calls  RPG1.   The structure
looks like:

          CLBEGIN - Calls RPG1
                      - The PEP calls the Module RPG1
                         - RPG1 Module calls SNDESC

The escape message is sent to CLBEGIN.

Even in a  more complex  case where  a program  is made  up of  several
modules such as:

          CLBEGIN - Calls ILE program ABC with an entry Module ABC1
                         - ABC1 Module calls ABC2 Module
                            - ABC2 Module calls ABC3 Module
                              - ABC3 Module calls ABC4 Module
                                - ABC4 Module calls SNDESC

The escape message is still sent to CLBEGIN.

The SNDESC  program is  an OPM program,  but it  will send  the message
correctly.

SNDESCMSG Command parameters                          *CMD
----------------------------

   MSG           The text  of the message you want to  send.  A maximum
                 of 512 bytes may be sent.

SNDESCMSG2 Command parameters                         *CMD
-----------------------------

   MSGID         The Message ID of the message to be sent.

   MSGF          The Message file containing the message.

   MSGFLIB       The  library  of the  message file.    If you  use the
                 command interface,  *LIBL  is  the default.    *CURLIB
                 may also be  specified.  If you use  the CPP directly,
                 a  value must  be entered.   *LIBL  or *CURLIB  may be
                 used.

   MSGDTA        The message data to be  included with the message.   A
                 maximum  of 512  bytes  may be  sent.   If  you use  a
                 message like  CPF9898 or one of  the TAA messages like
                 TAA9891, the message data will  be the entire text  of
                 the message.

Restrictions
------------

None.

Prerequisites
-------------

None.

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   SNDESCMSG     *CMD                   TAAMSGQ       QATTCMD
   SNDESCMSG2    *CMD                   TAAMSGQ2      QATTCMD
   SNDESC        *PGM       CLP         TAAMSGQC      QATTCL
   SNDESC2       *PGM       CLP         TAAMSGQC2     QATTCL

Structure
---------

SNDESCMSG  Cmd
   SNDESC   CL pgm

SNDESCMSG2 Cmd
   SNDESC2  CL pgm