TAA Tools

 TAAEXC          TAAEXC PROGRAM                         TAACMEC

 The TAAEXC  program is intended  to be used  instead of QCMDEXC  from a
 HLL program  to allow for  better handling of messages.   An externally
 described  data structure is supplied which  must be defined in the HLL
 program.   Fields  within the  data  structure allow  a command  to  be
 passed, options to be set, and information to be returned.

 The advantage of TAAEXC is that it provides a simpler interface for:

   **   'Remove message'  function.   The default is  *NO to  retain any
        messages.   *YES may  be specified to clear  any messages caused
        by the command that was executed.

   **   MONMSG function.   The  default  is to  have TAAEXC  resend  any
        escape message  (caused by  the command to  be executed)  to the
        HLL  program.     You  may  easily  check  for  a  single  error
        condition by  specifying the  exception  ID in  a field  in  the
        data structure.   Multiple messages may  be checked for  in your
        program.  See the sample code provided.

   **   Easy  access to  the completion  or escape  message sent  by the
        command  that  was executed.   The  data  is returned  in fields
        within  the  data  structure  for  Message   ID,  message  text,
        message data, etc.   The information may be  used in the program
        or  with the TAA Tool SNDESC to  resend the message as an escape
        message.

   **   Easy access  to the  diagnostic  message preceding  the  escape.
        This provides  for more specific  error handling when  a command
        such  as CPYF is used  which sends a  generalized escape message
        and specific  diagnostic  messages.   The  data is  returned  in
        fields within the  data structure for Message ID,  message text,
        message data, etc.

   **   Simple building  of the command  to be executed.   Parameters of
        the   command  are  automatically   concatenated  together  with
        spaces  rather  than  having   the  user  program  perform   the
        concatenation.

 A typical set of RPG statements would be:

      I* TAAEDS is the data structure used by the TAA Tool TAAEXC
      ITAAEDS    E DSTAACMECP
      .
      C* Your statements to build the command such as CHKOBJ
      C                     MOVEL'CHKOBJ'  TAACM1    P      CHKOBJ
      C                     MOVEL'xxx'     TAACM2    P      CHKOBJ
      C                     MOVEL'*PGM'    TAACM3    P      CHKOBJ
      C* Call TAAEXC to execute
      C                     CALL 'TAAEXC'                   TAAEXC
      C                     PARM           TAAEDS           Cmd DS

 A typical set of RPG IV statements would be:

      D* TAAEDS is the data structure used by the TAA Tool TAAEXC
      D TAAEDS        E DS                  EXTNAME(TAACMECP)
      .
      C* Your statements to build the command such as CHKOBJ
      C                   MOVEL(P)  'CHKOBJ'      TAACM1
      C                   MOVEL(P)  'xxx'         TAACM2
      C                   MOVEL(P)  '*PGM'        TAACM3
      C* Call TAAEXC to execute
      C                   CALL      'TAAEXC'
      C                   PARM                    TAAEDS


 If  an error  occurred,  the  TAAEXC program  would  resend any  escape
 message  to the RPG  program.   See the later  discussion on monitoring
 for messages.

 What commands may be executed
 -----------------------------

 TAAEXC uses  the  QCMDEXC function  internally  and therefore  has  the
 same restrictions  as QCMDEXC.   Most commands  are valid  except those
 that are limited for use within CL programs (such as RTV commands).

 The  command  definition object  must  be specified  as  ALLOW(*ALL) or
 ALLOW(*EXEC).

 An exception  is  OVR commands.    Because  TAAEXC is  a  program,  any
 normal OVR commands  issued are lost when  the program goes out  of the
 stack.   The  OVR commands  support the  OVRSCOPE parameter  which will
 allow you to retain the override.

 Field names in the TAACMECP data structure
 ------------------------------------------

 All  the fields used are  named TAAxxx.  You may  review the names with
 the DSPFMT TAA Tool.

             DSPFMT     FILE(TAACMECP)

 There are 5  command fields.   TAACM1 has a length  of 256 bytes.   The
 TAACM2 - TAACM5 fields each has a length of 50 bytes.

 The TAACMx  fields are  concatenated in sequence  to build  the command
 with spaces  in between.  For a very  simple command such as the CHKOBJ
 command shown in  the previous example,  you just fill  the fields  and
 let TAAEXC concatenate the values together before execution.

 The TAAMON  field (described later)  determines what will  be monitored
 for.   If TAAMON is blank  or *NONE, any escape  messages received will
 be resent to the HLL program.

 The TAARMV field (described  later) controls whether messages  received
 by TAAEXC will be removed.

 All the other  fields in the  TAAEDS data structure are  return values.

 The   TAARES  field  will   contain  '0'   if  the   command  completed
 successfully.    If you  are  monitoring for  messages,  a '1'  will be
 returned if the command failed.

 The remaining  fields  such as  the TAAMID  (message  ID) will  contain
 information from messages  sent by the command that  was executed.  The
 fields  are  similar to  the return  variables  provided by  the RCVMSG
 command.  If no information is available, the fields will be blank.

 Monitoring for messages
 -----------------------

 The TAAMON field allows you to monitor for messages.

   **   The default  (blanks)  causes  any escape  message  received  by
        TAAEXC to  be resent  to the  HLL program.   *NONE  may also  be
        specified to cause this function.

        Prior   to   sending  the   escape,   any   previously  received
        diagnostic message  will  be  resent as  a  diagnostic  message.
        For  example,  CPYF  will  send  a  generalized  escape  message
        CPF2817 preceded by a specific diagnostic message.

        To use  the default technique,  just copy the code  shown at the
        beginning of the documentation.

   **   You  may monitor  for a single  error condition  by entering the
        escape message  ID in the  TAAMON field in  the same manner  you
        would describe on a CL MONMSG command.

        If  the  specified  escape   message  occurs,  TAAEXC  completes
        normally,  but posts  a '1'  in the  TAARES field  for 'failure'
        instead of  '0' for a  'normal completion'.   If  a message  had
        been sent  prior to the  escape message, it  will appear  in the
        TAADxx  fields (such  as the message  ID will  be in  the TAADID
        field).   Your program  should  check the  TAARES value  if  you
        have specified a message to monitor for.

        If an  escape message occurs  that you  have not specified,  the
        escape  message  would  be resent  to  your  HLL  program.   Any
        previously  received  diagnostic  message  will  be  sent  as  a
        diagnostic message.

        See the later sample for how to code this technique.

   **   You may  specify *ALL  to mean that  all message  IDs should  be
        monitored  for.    If  an  error occurs,  TAAEXC  will  complete
        normally  with a  '1' in  the TAARES field.   The  TAAMxx fields
        will contain the  message information  (such as  the message  ID
        in  TAAMID)  and  any previous  diagnostic  message  information
        would be placed in the TAADxx fields.

        Your  program needs to check  the TAARES field for  '1' and then
        check the TAAMID field.  Sample code is shown later.

 Note that unlike the  CL MONMSG command, you  cannot specify a  generic
 message  ID  such as  CPF9800  nor  can  you specify  the  'any  error'
 condition  of CPF0000.   To achieve  the 'any error'  function, specify
 TAAMON = *ALL and code your program to test for the message IDs.

 You  cannot specify a list of message IDs  to monitor for in the TAAMON
 field.   You  can  code for  a  list of  messages  in your  program  as
 described in later sample code.

 Note that any  value other than blanks, *NONE, or *ALL  is treated as a
 message ID that you want to monitor for.

 Previous Diagnostic message
 ---------------------------

 The  TAADxx fields are for  a previous diagnostic message  such as when
 CPYF fails with the CPF2817  generalized escape which is preceded by  a
 specific diagnostic  message ID that describes  the error.   The TAADxx
 fields would contain the information from the diagnostic message.

 If  the previous message  is other than  a diagnostic type,  the TAADxx
 fields are not filled.

 The technique  used  to retrieve  the  diagnostic message  may  not  be
 accurate in  all cases.   Since messages in  the program message  queue
 are  not associated with  a command,  the technique used  retrieves the
 previous  message that occurred before  an escape message.   If it is a
 diagnostic type, the  technique assumes that  it belongs to the  escape
 message.   It is  possible that  a diagnostic  message could  have been
 issued  earlier  from a  previous function  and  then a  later function
 caused an escape  message in  which case the  diagnostic message  would
 be incorrectly associated with the escape message.

 The  Call command  is treated  separately  from other  commands by  the
 system  so that  monitoring for  Call  exceptions requires  some unique
 handling.

 If you use a command entry display  and enter a Call to a  non-existent
 program, the  system sends the  CPD0170 diagnostic message  followed by
 the CPF0001 generalized escape message.

 If you  execute the invalid Call using QCMDEXC,  the system resends the
 CPD0170  as  a diagnostic,  but changes  the  CPF0001 message  into the
 generalized escape  message CPF0006.   Consequently,  you must  monitor
 for CPF0006 and not CPF0001.

 Removing messages caused by your command
 ----------------------------------------

 The command  you execute may  cause messages to  be sent to  the TAAEXC
 program  message queue.   The default  (TAARMV =  blanks) retains these
 messages so they  will exist in the  job log.   To remove any  messages
 sent to TAAEXC, set TAARMV to *YES such as:

      C                     MOVE '*YES'    TAARMV           Remove msgs

 Any value other than *YES will retain the messages.

 Checking for a single error condition
 -------------------------------------

 The  following  error  handling  code  checks  for  the  CPF9801  error
 message.   Note that the RPG program will fail  if a message other than
 CPF9801 occurs.

 The following is RPG III code:

      I* TAAEDS is the data structure used by the TAA Tool TAAEXC
      ITAAEDS    E DSTAACMECP
      .
      C* Your statements to build the command such as CHKOBJ
      C                     MOVEL'CHKOBJ'  TAACM1    P      CHKOBJ
      C                     MOVEL'xxx'     TAACM2    P      CHKOBJ
      C                     MOVEL'*PGM'    TAACM3    P      CHKOBJ
      C* Set TAAMON to the message ID to be monitored for
      C                     MOVEL'CPF9801' TAAMON    P      Monitor msg
      C* Call TAAEXC to execute
      C                     CALL 'TAAEXC'                   TAAEXC
      C                     PARM           TAAEDS           Cmd DS
      C* Check result (TAARES is '0' = Successful and '1' = Failure)
      C           TAARES    IFEQ '1'                        Cmd failed
      C*  Your code to process the CPF9801 error
      C*    Any other errors such as CPF9802, will cause an escape
      C*      message to be sent to the RPG program
      C                     ENDIF                           Cmd failed

 The following is RPG IV code:

      D TAAEDS        E DS                  EXTNAME(TAACMECP)
      .
      C* Your statements to build the command such as CHKOBJ
      C                   MOVEL(P)  'CHKOBJ'      TAACM1
      C                   MOVEL(P)  'xxx'         TAACM2
      C                   MOVEL(P)  '*PGM'        TAACM3
      C* Set TAAMON to the message ID to be monitored for
      C                   MOVEL(P)  'CPF9801'     TAAMON
      C* Call TAAEXC to execute
      C                   CALL      'TAAEXC'
      C                   PARM                    TAAEDS
      C* Check result (TAARES is '0' = Successful and '1' = Failure)
      C     TAARES        IFEQ      '1'
      C*  Your code to process the CPF9801 error
      C*    Any other errors such as CPF9802, will cause an escape
      C*      message to be sent to the RPG program
      C                   ENDIF

 Handling multiple error conditions
 ----------------------------------

 In the following  code, the  CPF9801 and CPF9802  error conditions  are
 specifically handled within the  program.  Any other error  from CHKOBJ
 would  cause the  RPG  program to  resend  the error  condition  to the
 calling program.  This occurs by use of the TAA SNDESCMSG Tool.

 The following is RPG III code:

      I* TAAEDS is the data structure used by the TAA Tool TAAEXC
      ITAAEDS    E DSTAACMECP
      I* MSG area used by SNDESCMSG TAA Tool
      IMSGDS       DS                            512
      .
      C* Your statements to build the command such as CHKOBJ
      C                     MOVEL'CHKOBJ'  TAACM1    P      CHKOBJ
      C                     MOVEL'xxx'     TAACM2    P      CHKOBJ
      C                     MOVEL'*PGM'    TAACM3    P      CHKOBJ
      C* Set TAAMON to *ALL
      C                     MOVEL'*ALL   ' TAAMON    P      Monitor msg
      C* Call TAAEXC to execute
      C                   CALL      'TAAEXC'
      C                   PARM                    TAAEDS
      C* Check result (TAARES is '0' = Successful and '1' = Failure)
      C           TAARES    IFEQ '1'                        Cmd failed
      C                     SELEC                           Select MsgID
      C* Select on error ID
      C           TAAMID    WHEQ 'CPF9801'                  If CPF9801
      C* Your handling of CPF9801                           Print
      C           TAAMID    WHEQ 'CPF9802'                  If CPF9802
      C* Your handling of CPF9802                           Print
      C                     OTHER                           Any other
      C* Any other escape message causes a resend of the escape message
      C                     CALL 'SNDESC2'                  TAA Tool
      C                     PARM           TAAMID           Msg ID
      C                     PARM           TAAMFL           Msg file
      C                     PARM           TAAMLB           Msg lib
      C                     PARM TAAMSD    MSGDS            Msg data
      C                     ENDSL                           Select MsgID
      C                     ENDIF                           Cmd failed

 An  alternative  would be  to  just display  whatever  message received
 whether it is an  escape or completion.   In the following code,  MSG80
 would be a display field.

      .
      C                     MOVEL'*ALL   ' TAAMON    P      Monitor msg
      C* Call TAAEXC to execute
      C                   CALL      'TAAEXC'
      C                   PARM                    TAAEDS

      C                   MOVELTAAMSGMSG80        MSG80

 The following is RPG IV code:

      D* TAAEDS is the data structure used by the TAA Tool TAAEXC
      D TAAEDS        E DS                  EXTNAME(TAACMECP)
      D* MSG area used by SNDESCMSG TAA Tool
      D MSGDS           DS           512
      .
      C* Your statements to build the command such as CHKOBJ
      C                   MOVEL(P)  'CHKOBJ'      TAACM1
      C                   MOVEL(P)  'xxx'         TAACM2
      C                   MOVEL(P)  '*PGM'        TAACM3
      C* Set TAAMON to *ALL
      C                   MOVEL(P)  '*ALL   '     TAAMON
      C* Check result (TAARES is '0' = Successful and '1' = Failure)
      C     TAARES        IFEQ      '1'
      C                   SELECT
      C* Select on error ID
      C     TAAMID        WHENEQ    'CPF9801'
      C* Your handling of CPF9801                           Print
      C     TAAMID        WHENEQ    'CPF9802'
      C* Your handling of CPF9802                           Print
      C                   OTHER
      C* Any other escape message causes a resend of the escape message
      C                   CALL      'SNDESC2'
      C                   PARM                    TAAMID
      C                   PARM                    TAAMFL
      C                   PARM                    TAAMLB
      C                   PARM      TAAMSD        MSGDS
      C                   ENDSL
      C                   ENDIF

 Other message handling
 ----------------------

 The most  typical message handling  function would be to  handle escape
 messages as described previously.

 You  may also handle completion messages.   For example, CRTDTAARA will
 send a  completion message.    The same  field names  (TAAMID,  TAAMSG,
 etc) are used  to contain the last  message sent to the  TAAEXC program
 (the  field data will  exist for the  last message received).   You can
 determine the  type of  message by  using the  contents of  the  TAAMTP
 field.   It will contain  the same values  as described for  the RCVMSG
 RTNTYPE parameter.   For example, 01 = Completion  and 02 = Diagnostic.
 You  may choose to resend  the message using the QMHSNDPM  API or a TAA
 Tool such as SNDESCMSG or SNDDIAGMSG.

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

 No command exists.  TAAEXC is just a program.

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

   **   Normal override commands  will be lost  when the TAAEXC  program
        ends.    The  OVRSCOPE  parameter  allows  you  to  control  the
        duration of the override.

   **   CL program commands may not be executed.

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

 None.

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

 None, the tool is ready to use.

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

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

    TAAEXC        *PGM       CLP         TAACMECC      QATTCL
    TAACMECP      *FILE      PF          TAACMECP      QATTDDS

Added to TAA Productivity Tools March 1, 1998


Home Page

Last modified on November 19, 2014 © 1995, 2014 - TAA Tools, Inc.