SNDESCMSG       SEND ESCAPE MESSAGE                    TAAMSGQ

 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

Added to TAA Productivity Tools April 1, 1995


Home Page

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.