TAA Tools
MSGCTL          MESSAGE CONTROL              TAAMSGA

The Message Control function  is designed to assist in  operating in an
unattended or  mostly unattended environment.  The  normal use would be
to  control the QSYSOPR message  queue, but any queue  can be named and
multiple versions of the function can be executing simultaneously.

The Message  Control  function  is similar  to  the System  Reply  List
function, but  has more  flexibility.  The  System Reply  List function
only  works with Inquiry Messages and  allows for an automatic response
to designated  messages.   The Message  Control  function provides  for
this  capability  as  well  as controlling  any  message  that  arrives
regardless  of whether  it  is an  inquiry or  not.   Depending  on the
message received, a command may be  executed and/or the message can  be
forwarded to a specific message queue.

The STRMSGCTL  command  names a  message queue  and a  data base  file.
When a  message arrives on  the queue, the corresponding  message ID is
searched  for in the data base file.   The data base file describes the
disposition of the message.

The following describes  some of the  functions of the Message  Control
function based on the message ID received.

  **   Filter out  unwanted messages from the  actual operators message
       queue.   In a  mostly unattended environment,  the real operator
       queue becomes the Forwarding Queue.   This allows you to  filter
       out  messages that  should  not clutter  up  the real  operators
       queue.

  **   Forward the message to another message queue

  **   Automatic reply to an inquiry message

  **   Forward  an  inquiry  message  to  a  designated message  queue,
       periodically check  for  a reply  and  respond to  the  original
       inquiry  when  the reply  is  made.    The same  message  ID  as
       received is  used to forward  the inquiry.   Therefore, if there
       is  validity checking  to be  performed on  the reply (i.e.   as
       specified on  the ADDMSGD command),  the reply  is checked  when
       it is entered at the forwarded queue.

  **   Check different  values of the  message data to  compare against
       multiple  records  for the  same message  ID  in the  data base.
       Each  record for  the  same  message  ID  would  have  different
       compare  values.   This allows  different actions  based on  the
       actual  message data.   This is the  same concept as  the System
       Reply List to  allow different processing  for the same  message
       ID.

  **   Execute a specific command (either system or user written)

  **   Call a  program.   The program  is passed  a standard  parameter
       list  including the  message ID,  the  message data,  the sender
       information  and the message text.   This allows more capability
       than  just a  simple  comparison  against the  message  data  as
       described previously.

  **   Operate on generic  message IDs.  If a  message ID arrives which
       does  not exist  in the data  base file,  the data  base file is
       first checked  for  a  partial  generic message  ID  (e.g.    if
       CPF2421 arrives  and is  not in  the file,  CPF2400 is  searched
       for).    If this  message  does  not exist,  a  full  generic is
       searched for (e.g.   CPF0000).   This is the  same concept  that
       exists  for  the  MONMSG  command  and  the  System  Reply  List
       function.

  **   Cause  a default action  if the message  ID is not  found either
       specifically  or  via  one  of the  generic  searches.   Command
       parameters describe  a default  forwarding message  queue and  a
       Severity Level  value.  The  Severity level of the  message must
       be  equal  or  greater than  the  command  parameter  before the
       message is forwarded.

  **   Handle impromptu  messages  caused by  a  SNDMSG command.    The
       type may  be either *INFO  or *INQ and  may be forwarded  to the
       default forwarding message queue.

A  log  (data  base file)  is  kept  of the  actions  that  the Message
Control function performs.   A  data base  record is  written for  each
message received  which describes what  the message is  and how it  was
handled.   Each log entry receives a  unique Log ID.  If  an inquiry is
forwarded  and a  reply occurs,  the reply is  also written  to the log
along with  the  original Log  ID.   The original  Log  record is  then
updated with  the corresponding Log ID of  the reply as well  as a time
stamp of when the reply was received.

If errors  occur, they are written to the log  and a message is sent to
the default  forwarding  message  queue  identifying  the  problem  and
which Log ID  it occurred on.   For example, the command  stored in the
data  base to  be executed  for a  particular message  could fail  or a
stored reply value could be invalid.

Both a current and a  history log are kept.   When the Message  Control
function begins,  it copies the  Current Log  (MSGCURP) to the  History
log (MSGHSTP)  and then clears  the current log.   Thus the  user has a
complete  record of  what transpired  and can  back up the  history log
each  time the  Message  Control  function  is started.    Because  the
current log  is open for update,  it cannot be saved  while the Message
Control  function  is  active  (unless  you  are  using  the  SAVWHLACT
function).

A command  (DSPMSGCTL) is  provided to  display either  the current  or
the  history log.    This  shows a  subfile  of  entries and  allows  a
selection  to  show more  details.   Because  the  logs  are externally
described data base files,  queries or HLL programs  can be written  to
analyze the data.

In order  to  ensure that  all messages  are properly  received by  the
Message  Control function,  the named  queue is  exclusively allocated.
This  allows anyone to send messages  to the queue, but prevents DSPMSG
of  the  queue.    Because  of  the  processing  technique,  there  are
normally  very few  messages  (if any)  in  the log  if  you wanted  to
display them.

As  messages are processed, they are removed  from the queue.  The data
base log represents  the actions of  the queue and  is more  meaningful
to look  at.  If  QSYSOPR is being  controlled, copies of  all messages
are sent to QHST and the DSPLOG command can also be used.

System support of messages
--------------------------

This  section describes  a  brief overview  of how  the  system handles
messages and need not be read if you already familiar with it.

       Most  messages  sent  from  a  job  are  of  an   informational,
       diagnostic  or completion  type  which become  part  of the  job
       log.    These  cannot  be  monitored  for within  the  job,  but
       normally  can  be  received  with  RCVMSG.    Exception messages
       (escape, notify  and  status  types)  can be  monitored  for  by
       MONMSG.

       For  some  functions, a  message  is  sent  to a  message  queue
       outside of the job.  For example:

         --   For  device related  errors, the  message is sent  to the
              name supplied  on  the MSGQ  parameter of  the  CRTDEVxxx
              command.

         --   The  STRxxxWTR  commands  support  a  MSGQ  parameter  to
              determine  where to send  messages to.   This defaults to
              the device description MSGQ value.

         --   Some data  base  messages (e.g.    the file  has  reached
              it's   maximum  size)   are   always  sent   to   QSYSOPR
              regardless of the type of job it occurs in.

         --   The journal  support allows a  MSGQ to be  named when the
              threshold value of the receiver size is exceeded.

       If  this type  of message occurs  and it is  an inquiry message,
       the job  waits for a  reply and the  application program is  not
       informed.    You  can  automatically respond  to  these  inquiry
       messages  by having the message queue in  default mode or by use
       of the System Reply List.

       The System Reply list is  invoked only for inquiry messages  and
       only  if the  job  attribute  INQMSGRPY(*SYSRPYL) is  specified.
       This can occur as follows:

         --   If  an  interactive job  sends  an  inquiry message,  the
              system reply list  will respond without  the user  seeing
              the  inquiry.   No  message is  sent  to QSYSOPR  or  the
              named message queue.

         --   If  a batch  job sends  an  inquiry message,  the message
              queue  receiving  the message  will normally  be QSYSOPR.
              If  the  System  Reply  List  implicitly   responds,  the
              message and the reply will appear in QSYSOPR.

       The  System  Reply  List  offers  a dump  option  which  is  not
       available  with  the  Message Control  function.    A meaningful
       approach may  be  to use  both the  System  Reply List  and  the
       Message  Control function.    See the  later  discussion on  Use
       with the System Reply List.

       There are  some inquiry messages which are  not sent to the job,
       but are  rather sent  directly  to QSYSOPR  so that  the  system
       reply list  is not  capable of  answering them.   An example  of
       this is the CPA5305 message 'Data Base file is full'.

Message Control Commands
------------------------

   CRTMSGCTL     Creates  the files in  a named  library that  are used
                 by the other commands.

   STRMSGCTL     Identifies  which message  queue is  to be controlled,
                 the  forwarding  message  queue  and   other  optional
                 parameters.   It submits the  Message Control function
                 to batch.

   ENDMSGCTL     Sends  a special  message to  the message  queue being
                 controlled that  will  shutdown  the  Message  Control
                 function.

   DSPMSGCTL     Displays either  the current  log or  the history  log
                 and  allows  the detail  information  to  be accessed.
                 It allows  a review  of  what messages  were  received
                 and what actions were taken.

Data Base files
---------------

   MSGCTLP       This  is the  data  base file  where  message IDs  are
                 entered  as  well as  what  actions  to perform  (e.g.
                 execute  a command, forward the  message to a specific
                 queue,  etc.).   No  programs  are  supplied  for  the
                 maintenance  of  this file.    A  DFU  program can  be
                 used.

   MSGCURP       This  is the  current log  file where all  actions are
                 recorded.  The  DSPMSGCTL command  is used to  display
                 the log.

   MSGHSTP       This is  the history log  file which will  receive the
                 contents  of the MSGCURP file  each time the STRMSGCTL
                 command is executed.   The DSPMSGCTL  command is  used
                 to display the log.

   MSGINQP       This  is a  work  file  used  by the  Message  Control
                 function  to  allow a  match  of  a forwarded  inquiry
                 message  and the  original inquiry  message.   This is
                 kept  as  a  permanent  file  to   assist  in  problem
                 determination  if  some   unforeseen  problem  occurs.
                 The  file is cleared  each time  the STRMSGCTL command
                 is executed.

CRTMSGCTL command                                     *CMD
-----------------

The CRTMSGCTL command creates the  file MSGCTLP, MSGCURP, MSGINQP,  and
MSGHSTP in a named library.

   LIB           The library to create the files in.

   SRCLIB        The source library  to use for the QATTDDS  file.  The
                 default  is *TAAARC which  means to use  the source in
                 the TAA Archive.

STRMSGCTL command                                     *CMD
-----------------

The STRMSGCTL command is designed  to be executed interactively and  to
submit  the message  control function  to  batch.   If  the command  is
executed in batch, the submit step is ignored.

To  start the Message  Control function  for the QSYSOPR  message queue
and use QUEUE1 as the default forwarding queue, you would specify:

       STRMSGCTL   MSGQ(QSYSOPR) DFTFWDQ(QUEUE1)

The command supports the following parameters:

   MSGQ          The   qualified   message   queue   that   should   be
                 controlled.

   DFTFWDQ       The qualified  message queue  which  will receive  any
                 forwarded   messages   from    the   Message   Control
                 function.

   JOBD          The  qualified job  description to  be used  to submit
                 the job to  batch.  The  default is *USRPRF.   If  the
                 command  is  executed  in  batch,  this  parameter  is
                 ignored.     You   should   ensure  that   the  ENDSEV
                 parameter in  the JOBD  is not  greater than  40  (the
                 default for CRTJOBD is  30).  By having a  value of 40
                 or  less,  you  will  ensure that  any  un-planned-for
                 errors  found  using  Message Control  will  cause the
                 job to abnormally terminate.

   MSGCTLLIB     The library name  for the MSGCTLP  file.  The  default
                 is  *LIBL.    If  you have  multiple  Message  Control
                 functions  in  execution,  they  may  share  the  same
                 file.

   MSGCURLIB     The library name  for the MSGCURP  file.  The  default
                 is  *LIBL.    If you  have  multiple  Message  Control
                 functions  in execution,  they  cannot share  the same
                 file.

   MSGHSTLIB     The library name  for the MSGHSTP  file.  The  default
                 is  *LIBL.    If you  have  multiple  Message  Control
                 functions  in  execution, they  should  not share  the
                 same file if you want unique sequence numbers.

   MSGINQLIB     The  library name for  the MSGINQP file.   The default
                 is  *LIBL.   If  you  have  multiple  Message  Control
                 functions  in execution,  they cannot  share the  same
                 file.

   SEV           The   Severity  Level   of  messages  (not   found  in
                 MSGCTLP) which are  to be  ignored.  If  a message  ID
                 cannot be identified  in the MSGCTLP file,  this value
                 determines  whether  the  message  will be  forwarded.
                 The default is  20 meaning  any unidentified  messages
                 of severity  00-19  will not  be forwarded.   This  is
                 like the  SEV parameter on CHGMSGQ.  It  is a means of
                 filtering  out what the  user must see.   Note that if
                 a message  is  identified in  the  MSGCTLP file,  this
                 parameter  is   not  considered  and   the  data  base
                 information is used to determine the disposition.

   INQPOLL       The  frequency  in  seconds  for  how often  forwarded
                 unanswered inquiry  messages should  be polled.    See
                 the  later   discussion  of   polling  of   unanswered
                 inquiry messages.  The default is 30 seconds.

   RESETLOGID    Controls  if  the  unique  Log  ID  assigned  to  each
                 record in  the log  should  be reset  to begin  at  1.
                 The default is  *NO meaning the  next LOGID will  be 1
                 greater than  the last record in the  log before it is
                 cleared.   The LOGID  field is 7  digits long allowing
                 for   10   million    messages   before   the    field
                 automatically  rolls  over.    Since the  current  log
                 (MSGCURP)   will  be  copied   into  the  history  log
                 (MSGHSTP) each time  the Message  Control function  is
                 activated, it  is desirable  to keep  the History  log
                 unique and in sequence.

                 RESETLOGID(*YES)  should  only be  specified  when you
                 are at the end  of some period and  wish to start  the
                 history  file  over.     After  the   Message  Control
                 function  is activated  with a  reset  to the  Log ID,
                 you  should back  up the  MSGHSTP file  and then clear
                 it.

   RESTART       A  *YES/*NO parameter  that  defaults  to *NO.    *YES
                 allows  the  message   control  function  to  resubmit
                 itself  when the  number of  program messages  sent to
                 the job message queue approaches the system limit.

                 Messages are  sent to  the program  message queue  for
                 each message  received and timeout conditions.   After
                 a  count of  20,000 messages  and no  active inquiries
                 are outstanding,  the  message control  job  will  end
                 and  resubmit itself  if  RESTART(*YES) is  specified.
                 The same job queue is used.

                 After  30,000  messages,  RESTART(*YES) will  cause  a
                 the   job  to  be  re-submitted   even  if  there  are
                 outstanding  inquiry  messages.    When  the  new  job
                 occurs, the  inquiry message  will be found  again and
                 forwarded  to the  same  queue.   This will  result in
                 two inquiry messages with  the same information.   The
                 second one is  the one to be answered.   See the later
                 discussion of this.

ENDMSGCTL command                                     *CMD
-----------------

The  ENDMSGCTL command  is used  to end  the Message  Control function.
You specify the  name of the  message queue which  is being  controlled
and a special message is  sent to the queue which is  recognized by the
Message Control function as a shutdown request.

To  end the  Message Control  function for  the QSYSOPR  message queue,
you would specify:

       ENDMSGCTL   MSGQ(QSYSOPR)

The command supports the following parameter:

   MSGQ          The  qualified  message  queue that  was  specified on
                 the STRMSGCTL command.

DSPMSGCTL command                                     *CMD
-----------------

The DSPMSGCTL  command is  used to display  either the  current log  or
the history log.   A subfile is displayed with one  line per log entry.
A  display option can  be entered  next to one  or more  log entries to
specify that more detail information should be displayed.

To display the current Message Control Log, you would specify:

       DSPMSGCTL

The command supports the following parameters:

   LOG           Which log should  be displayed.   The default is  *CUR
                 to display  the current log.   *HST can be  entered to
                 display the history log.

   LOGID         The LOGID  to display at the top  of the subfile.  The
                 default is *LAST meaning the  last page of entries  is
                 displayed.   *FIRST  may be  specified  for the  first
                 page  of  entries.    A  specific  LOGID can  also  be
                 specified.

   LIB           The  library  where the  log file  is contained.   The
                 default is *LIBL.

Rollup and rolldown are supported.   The top line of the  display shows
the Log ID  of the first detail line and the  date/time the message was
received.    The Log  ID  field can  be  entered to  randomly  access a
different value.   If detail information is  displayed, a function  key
allows  access to  the  DSPMSGD command  for  the  specific message  ID
received.

Entering data into the MSGCTLP file
-----------------------------------

The  MSGCTLP records define the  actions that will be  performed on the
message IDs when they arrive on the  queue.  You will need to create  a
HLL program or a DFU  application, or use the EDTDBF tool  to enter and
modify the data  in this file.  For most of  the fields, you just leave
the  entries blank.  If you use a  COBOL program to enter the data, you
must fill the numeric fields with valid digits.

The following is  an example of how  some typical message IDs  would be
entered.   The TEXT field  is used only  for documentation.   All other
fields in the record can be left blank if you use DFU.

  **   The  "Verify alignment" inquiry  message should  be answered 'I'
       to ignore.

          MSGID   -   CPA4002
          TEXT    -   Verify alignment message
          REPLY   -   I

  **   The "Press  READY  or  START"  message should  be  forwarded  to
       message queue QUEUE1.

          MSGID   -   CPA5243
          FWDQ    -   QUEUE1
          TEXT    -   Press READY or START message

  **   The  "Subsystem  Varied  Off  Device"   message  should  not  be
       forwarded.    This  message is  sent  with  SEV(70) which  would
       normally cause it to  be forwarded unless  the SEV parameter  on
       STRMSGCTL was  at least 70.   Placing a  record of this  type in
       the data base avoids forwarding specific message IDs.

          MSGID   -   CPF1189
          TEXT    -   Subsystem varied off a device

  **   The  "Lost  contact  with a  device"  message  should cause  the
       execution of the user command CHKINTO.

          MSGID   -   CPF2677
          TEXT    -   Lost contact with a device
          CMD     -   CHKINTO

  **   The  "Hardware failure on device"  message should cause the user
       program HDWFAIL to be executed.

          MSGID   -   CPF5201
          TEXT    -   Hardware failure on device
          USRPGM  -   HDWFAIL

The following describes the fields  to be entered in the  MSGCTLP file.

   MSGID         The  message ID  of the  message.   This is  a  7 byte
                 character  field.   Note  that similar  to  the System
                 Reply List support, the  message file and library  are
                 not  used to  identify  the message.    It is  assumed
                 that  your  message  IDs are  unique.    You can  have
                 multiple records for  the same MSGID  value, but  this
                 is  only meaningful  when  you  are using  the  CMPDTA
                 field.

                 You can  have a generic message ID  in the same manner
                 as  the  system  reply  list.   For  example,  you can
                 specify CPF9800  or  CPF0000.   You  can have  both  a
                 specific  value  and  a  generic  value  in  the  same
                 range.  The sequence of processing is as follows:

                     - Specific message IDs (e.g. CPF9815)
                     - Two zero generic IDs (e.g. CPF9800)
                     - Four zero generic IDs (e.g. CPF0000)

                 Note that this field must be upper case.

   IDSEQ         The  message ID sequence.   This is a  3 digit numeric
                 field that is  only used  to sequence  the records  if
                 duplicate  MSGID  values  exist.   The  field  may  be
                 defaulted.  See the later discussion of CMPDTA.

   CMPDTA        The  compare data  that is used  to match  against the
                 message data supplied  when a message  is sent to  the
                 queue.     This  has  the   same  definition   as  the
                 corresponding  parameter  for  the system  reply  list
                 function.   This  is a  character field  with a length
                 of 28 bytes.   If the field  is blank, only the  MSGID
                 field  will be  used.   See  the  later discussion  on
                 CMPDTA.

   CMPSTR        The  compare  start  position.    This  has  the  same
                 definition  as  the  corresponding  parameter  on  the
                 System  Reply list  function.   This  is a  3 digit  0
                 decimal  field.  If  a blank  exists, a 1  is assumed.
                 See the later discussion on CMPDTA.

   FWDQ          The message queue  to forward  the message  to.   This
                 is a 10 byte  character field.  The value  *DFT may be
                 specified  to cause  the  message  to be  sent  to the
                 DFTFWDQ  parameter name  on STRMSGCTL.   If  the field
                 is blank,  the message  will not  be forwarded  except
                 for  an inquiry  message without  a REPLY  value.   In
                 this  case,  the DFTFWDQ  parameter  on  the STRMSGCTL
                 function is used.

                 If an  inquiry message  is given  an automatic  reply,
                 this field can  still be used to forward  a message to
                 a  message queue.   The CPF9898  message (this  is the
                 the system  supplied  message  ID that  is  blank  and
                 allows MSGDTA to be  sent as the text) is  sent with a
                 text  that describes the  LOG ID,  the message  ID and
                 the reply.

   FWDQLB        The  message queue library to  forward the message to.
                 This is a 10 byte  character field.  If a  blank value
                 exists, *LIBL is assumed.

   TEXT          The text  field associated with  the record.   This is
                 a  50 byte character field.  The  field is not used by
                 the  Message  Control  function  and  exists  only  to
                 assist  in  your  documentation.    For  example,  you
                 might  include  a  brief  description  of the  message
                 text for this MSGID.

   REPLY         The reply value  to be  used for  an inquiry  message.
                 This  is a  50  byte  character  field.   If  a  value
                 exists  it will be  used as  the automatic reply.   If
                 *DFT  is entered, the default  assigned to the message
                 description is  used.   If  the  value is  blank,  the
                 inquiry  will  be  forwarded   to  the  message  queue
                 specified  in the FWDQ  field.  If FWDQ  is blank, the
                 inquiry will  be forwarded  to the  STRMSGCTL  DFTFWDQ
                 value.   If the  message received  was not an  inquiry
                 type,  this  value is  ignored.   If  the  message has
                 already been replied  to, (e.g.   by the System  Reply
                 List), this value is ignored.

   CMD           The  command  to  be executed  when  this  message  is
                 received.   This is a 100 byte character  field.  If a
                 non-blank  value  exists,  it will  be  executed  as a
                 command.   See  also  the comments  about  the  USRPGM
                 field.

   USRPGM        The  user  defined  handling   program  that  will  be
                 called.   This  is a  10 byte character  field.   If a
                 non-blank value  exists,  the  program  name  will  be
                 called.   See the  later discussion  of the  parameter
                 list passed to the program.

                 A  single record can  have both  a command and  a user
                 program.  The command is executed first.

                 If an  inquiry  is  forwarded, the  command  and  user
                 program  are executed  when  the inquiry  is  received
                 and not when the reply is received.

   USRPGMLB      The  library for  the user  defined  handling program.
                 This  is a 10 byte character  field.  If a blank value
                 exists, it is assumed to be *LIBL.

CMPDTA Function
---------------

The CMPDTA function allows  you to enter multiple records for  the same
message ID  and select  which record  to be used  based on  the message
data  received with the message.   This is the  same function as exists
on the System Reply List function.

For example,  assume  the message  data has  the  name of  the  printer
device being used.   You want to  take a different action  depending on
which printer  device caused the message.  You  will need to know where
in the message data the  printer device name is.   If it begins in  the
first position,  you  do not  need to  make an  entry in  CMPSTR.   You
would specify:

     CMPDTA = QSYSPRT  (or the name of the printer device you want)
     CMPSTR = blank    (assumed start position is 1)

If the  printer device is in  positions 11-20 of the  message data, you
would specify:

     CMPDTA = QSYSPRT  (or the name of the printer device you want)
     CMPSTR =11

The  processing of  the CMPDTA  value is  to read  the records  for the
specified MSGID  value in  sequence by the  IDSEQ field.   The  message
data received  from the message  is trimmed off  the left based  on the
CMPSTR  position.  The  data in the  CMPDTA field is  then scanned from
the right  for  the  first  non-blank.   The  corresponding  number  of
positions are  then blanked in  the message data.   The two  fields are
then compared.

If a  record is blank in the  CMPDTA field, it is always  a match.  The
first match  is  used  so  it is  important  to  sequence  the  records
properly.  If  the record does not match,  the next record in  the file
with the same  message ID is read and so on.   If no records match, the
generic test (e.g.  CPFxx00) is searched.

Assume  the  message data  sent with  the message  is ABCDEFGHIJ.   The
following describes the conditions:

      CMPDTA           CMPSTR        Result
      ------           ------        ------

      ABCDEFGHIJ       Blank         Match
      ABCDEF           Blank         Match
      ABC                1           Match
      ABC                4           No match
      DEF                4           Match
      AXC                1           No match

User written handling program
-----------------------------

The  USRPGM field  in  the MSGCTLP  file  controls  if a  user  written
program should  be called when the  specific message ID arrives.   This
function  differs  from the  CMD  field  in that  the  command function
always executes  the  same  command  with fixed  parameter  values  (no
variables are  allowed).   The user handling  program is  more flexible
in  that it is passed  the message data  sent with the  message and can
react differently depending on the message data.

The parameter list passed is as follows:

   MSGID         The message ID received.   This is a 7 byte  character
                 field.

   MSGF          The  message  file  the  message  was  received  from.
                 This is a 10 byte character field.

   MSGFLB        The  message  file library  the  message was  received
                 from.  This is a 10 byte character field.

   MSGDTA        The  message data received with  the message.  This is
                 a 100 byte character field.

   MSG           The  message text  received.    This  is  a  200  byte
                 character field.

   SEV           The  severity level  of  the  message.   This  is a  2
                 digit 0 decimal field.

   RTNTYPE       The  message  type.   The  codes  are  defined  in the
                 RTNTYPE parameter of  the RCVMSG command.   This is  a
                 2 byte character field.

   SENDER        The  sender  information received  with  the  message.
                 This  is  the  information from  the  SENDER  field on
                 RCVMSG.   It is  an  80 byte  character field.    This
                 includes the qualified  job name of the job  that sent
                 the message and the program name.

   DFTQ          The  DFTFWDQ message  queue value  from  the STRMSGCTL
                 command.  It is a 10 byte character field.

   DFTQLB        The   DFTFWDQLB   message  queue   library   from  the
                 STRMSGCTL command.  It  is a 10 byte  character field.

A sample skeleton  program is included to allow you  to copy the source
to  help create a user handling program.   See the TAAMSGAC5 CL program
source in the QATTCL file of TAATOOL.

Polling of unanswered inquiry messages
--------------------------------------

The system Message facility assigns  message keys to any message  which
is received or  sent.  The only way  to reply to a message  from within
a  program  is to  use  SNDRPY  and identify  the  message  key of  the
message received.   The only  way to  receive a reply  to a  particular
message is to  do a RCVMSG command  and identify the message  key which
was  returned as a  result of the  SNDPGMMSG command (the  reply itself
is returned in the MSG parameter).

When  an  inquiry  message  must  be  forwarded,  the  Message  Control
function  writes a  record  to  the  MSGINQP file  which  contains  the
message key  of the message  that was received  as well as  the message
key for the message that was sent (forwarded).

The  Message  Control  function  must  wake  up  periodically and  loop
through  any  unanswered  inquiry  messages  (i.e.     each  unanswered
inquiry is  polled).  RCVMSG  is used to  determine if a  reply exists.
WAIT(0) is  specified on the RCVMSG command  during this polling.  Once
all the  unanswered inquiry  messages have  been polled  and there  are
still  unanswered inquiries  existing, you  control  the timeout  value
(STRMSGCTL  INQPOLL  parameter)   which  determines  when  the  Message
Control  function  should  wake  up  again  and  try  another  round of
polling.

If  there are  no  unanswered  inquiry messages,  the  Message  Control
function will  wait indefinitely on the  named message queue for  a new
message to arrive.

If  a message  arrives  on the  queue, it's  arrival  will wake  up the
Message  Control  function.    After  the  message  is  processed,  the
Message  Control   function  will  again   check  for   any  unanswered
inquiries before going to the general RCVMSG wait again.

The  default for INQPOLL  is 30 seconds.   Assume that  an inquiry came
in which  is  to be  forwarded.    After forwarding  the  inquiry,  the
Message  Control function  will  check for  any  replies to  unanswered
inquiries.   Assuming that  the inquiry  was not  immediately responded
to,  the Message  Control function issues  a RCVMSG to  the queue being
controlled with  the INQPOLL timeout  value.   Assume that an  operator
sees the forwarded  inquiry and replies.  The  Message Control function
will  not pick up  the reply until  either the timeout occurs  or a new
message arrives.  Assuming no  new message arrived, the job which  sent
the original inquiry will  be waiting for a reply  for at least INQPOLL
time.   It will be longer than this time  if the operator answering the
message does not reply within that timeframe.

For example,  assume  that INQPOLL  =  60  seconds.   If  the  operator
replies in 15  seconds, the message  handling program will  not attempt
to  receive the reply  until 60 seconds  have expired.   Therefore, the
program  that originally  sent the  inquiry will  wait approximately 60
seconds  even  though  the  operator  has  already  replied.    If  the
operator replies  after 100 seconds, the original  program will receive
the  reply  at  the  next  timeout  period  (approximately  20  seconds
later).   The  times mentioned  could  be  earlier if  another  message
happened  to arrive  to cause  the program  to  wake up.   The  message
handling program does not wake up when a reply is made.

If  the value for  INQPOLL is too  small, you will  be suffering excess
overhead by checking  too frequently.   If the value  is too high,  you
will not  be responding quickly  to the job  which originally sent  the
inquiry   message.     The   proper   setting  will   vary   with  your
requirements.   You should consider  the number of forwarded inquiries,
the  normal  length of  time  for  the  operator  to  respond  and  the
requirements of the jobs which are waiting for a response.

If  the  Message Control  function  is  ended  while forwarded  inquiry
messages  remain unanswered, the original  inquiry message also remains
unanswered.  The log  keeps a special field  for an indication of  this
(See the  INQUNA field).  Once  the Message Control function  ends, the
message  queue being  controlled  is no  longer allocated  and  you can
respond to  the messages  directly with  DSPMSG.   The inquiry  message
will still  exist in the  Forwarded Queue.   Responding to the  message
in  the Forwarded Queue  will be  ignored.   See also the  next section
for  the handling  of messages which  already exist  when the STRMSGCTL
command is executed.

Message queue considerations (MSGQ parameter)
---------------------------------------------

The queue  identified in  the MSGQ parameter  is exclusively  allocated
at the  beginning of the Message  Control function.  This  allows other
users  to send messages, but  DSPMSG cannot be used  against the queue.
This is necessary to ensure  the proper handling of the messages  being
received.

When the Message  Control function starts, it sets all  messages in the
queue  to *NEW and processes  them as if  they just arrived.   If there
were any  unanswered  inquiries from  a  previous use  of  the  Message
Control  function, they  will  be processed  again.   If  the  operator
responds to the first occurrence, it is ignored.

Default forwarding queue considerations (DFTFWDQ parameter)
-----------------------------------------------------------

A  default forward queue  must be  specified on the  STRMSGCTL command.
This  can  be  any  message  queue  (except  any  message  queue  being
controlled).   It can  be a  WS message  queue  and can  be in  *BREAK,
*HOLD or *NOTIFY mode.

When  the  STRMSGCTL or  ENDMSGCTL  commands  are  executed, a  special
message  is  sent  to this  queue.   If  the  Message  Control function
receives an un-planned  escape message,  it will terminate  and send  a
message to the DFTFWDQ message queue.

Any messages that  are found in the MSGCTLP file  which request default
forwarding  are forwarded to this  queue.  Any *INFO  message IDs which
are not  found  in  the MSGCTLP  file  and  have a  severity  equal  or
greater than  the SEV  parameter are forwarded  to this  queue.   If an
*INQ  message ID  does not  exist  in the  MSGCTLP file,  it  is always
forwarded.

Any  error notifications (e.g.  a user  program failed) are sent to the
this queue with the LOGID of the error specified.

You will want  to ensure that the  CRTMSGQ SIZE parameter is  specified
large enough to contain the number of messages in this queue.

If the  Message Queue  is in default  mode, default replies  to Inquiry
messages  will  occur.    If the  ADDMSGD  parameter  does  not  have a
default, an *N (null) value is sent as the reply.

Use with the System Reply list
------------------------------

The System  Reply  List  can be  used  to answer  inquiry  messages  in
conjunction with the  Message Control function.  The  system reply list
allows  both  'dump'  and 'cancel'  functions  to  occur.   The  MSGCTL
function allows only a single response.

When an  inquiry  message  is received,  MSGCTL  tries  immediately  to
receive the reply.  If  the system reply list was used,  the reply will
be  available and  the message  will  be logged,  but not  sent  to the
forwarding  queue.  No  separate reply message will  appear in the log.
The reply will be placed into the inquiry message.

If  your entry  in  the  System  Reply  list is  a  generic  one  (e.g.
CPA4000), you  can make  the same generic  entry in MSGCTLP.   However,
all  messages for the generic  group would be  handled identically.  It
is possible  to  have both  a  specific entry  (e.g.   CPA4055)  and  a
generic entry.

Performance considerations
--------------------------

When a message arrives,  a data base random access is always  made.  If
no  record is  found for the  message ID,  another access is  tried for
the partial generic message ID (e.g.   CPF2400) and if it is still  not
found, another  access is made  for the full  generic (e.g.   CPF0000).
Consequently, you  can improve the  performance of the  Message Control
function  by  entering records  into  the MSGCTLP  file  for frequently
appearing message  IDs.  Note  that this  is true  even if the  message
has a low severity and will not be forwarded.

After using  the Message Control  function for awhile, you  could write
a  query  against  the  MSGHSTP file  and  select  those  records where
MSGTYP=MSG and  FNDMSG=N, group  the  records by  MSGID and  count  the
occurrences.   This will  tell you  the messages  which are  frequently
not found and should be added to the MSGCTLP file.

You  should try and minimize  the number of inquiry  messages that must
be forwarded.    When  there  is an  unanswered  inquiry  message,  the
Message  Control  function  must wake  up  periodically  and  poll  for
replies  as  described  in   a  previous  section.    You  control  the
frequency in which the polling occurs.

If  you  specify  compare  data (CMPDTA  field  in  the  MSGCTLP file),
additional data base accesses  may be needed to determine  which record
matches the message  data.  The most frequently  occurring message data
should  be the  lowest  sequence number  within a  message ID  group to
minimize data base accesses.

Use of SNDMSG (Impromptu messages)
----------------------------------

The SNDMSG command does not send  a message ID.  A blank value  appears
in  this field,  but the  Message  Control function  still attempts  to
find  a record  in  MSGCTLP.   If you  have a  blank  MSGID field  in a
record in MSGCTLP, you can direct  the processing of this message.   If
no blank  MSGID record  exists, the severity  is assumed  to be  80 and
will normally be  forwarded based on your SEV  parameter.  If SNDMSG is
used  with  TYPE(*INQ)  and  no  blank  message  ID  record  exists  in
MSGCTLP, the message will  be forwarded to the DFTFWDQ  parameter using
the CPF9898 message ID.

Assume there  is no one operating  the system when an  end user invokes
the  SNDMSG command.   You  could have a  USRPGM specified  which would
reply back  with a message  stating that  no one  is listening.   If  a
SNDMSG is  used for  inquiry against  a queue  in default  mode, an  *N
(null) is used as the reply.

It is  also possible to have a blank MSGID  field record in the MSGCTLP
file with a reply  (REPLY field) of 'Nobody  home' to achieve the  same
effect.

MSGCURP file    Log of messages received for this STRMSGCTL
-----------------------------------------------------------

The log  file  contains records  with uniquely  assigned  LOGIDs.   The
LOGID  value begins  with the  next value  from the  previous STRMSGCTL
execution unless RESETLOGID(*YES) is specified.

The  different  type  entries are  identified  in the  LOGTYP  field as
follows:

   STR           This is  always  the first  record and  describes  the
                 beginning  of the  STRMSGCTL  function.   The  DFTFWDQ
                 name appears in the FWDQ field.

   MSG           This  is the  entry  for a  message received  into the
                 queue.

   RPY           This is the  entry for a reply  to an inquiry  message
                 that  does  not have  an  automatic  reply.   When  an
                 inquiry  is received,  a MSG  type record  is written.
                 If the  inquiry is  answered via  the REPLY  field  in
                 the MSGCTLP  file, the  MSG record  will contain  both
                 the  inquiry  and  the   reply.    In  this  case,  no
                 separate  RPY record type will  exist.  This will also
                 be  the  case for  messages  which  are  automatically
                 answered (e.g.  the system reply list).

                 The  RPY record type  will only  exist if  the inquiry
                 message  was forwarded to another  queue and the reply
                 was later received.  When  the reply is received,  the
                 RPY record is  written and the original  MSG record is
                 re-accessed and updated with the reply.

   ERR           This  denotes  some error  condition.   See  the later
                 discussion of the ERRID field.

   END           This  is  always  the  last  record  written  if   the
                 Message Control  function was  ended by the  ENDMSGCTL
                 command.

   RS1           This   message   is   caused   by   the   request   of
                 RESTART(*YES)  when  at  least  20,000  messages  have
                 occurred.

   RS2           This   message   is   caused   by   the   request   of
                 RESTART(*YES)  when  at  least  30,000  messages  have
                 occurred.

Most  of the fields  in the MSGCURP  file are fairly obvious  as to the
contents.  In  general, it is  a combination of  what is received  from
the  message  and the  data  extracted  from  the  MSGCTLP file.    The
following describes those fields which may not be obvious:

   FNDMSG        A  Y/N value  only for MSG  log types  which specifies
                 if the message was found in the MSGCTLP file.

   MSGTYP        A 2  byte character  field containing  the value  from
                 the   RTNTYPE  parameter   on   the  RCVMSG   command.
                 Normally, you will see

                  - '04'   Informational message
                  - '05'   Inquiry message

                 If  an inquiry message  is sent  to the queue  you are
                 going  to  control and  is  answered manually  but not
                 removed, the reply  will be processed.   This will  be
                 a '21-25' code.   This will only occur  if the message
                 is  not removed from  the queue prior  to starting the
                 Message Control function.

   SENDER        The RCVMSG  SENDER  parameter  which  describes  where
                 the message came from.

   SEVLVL        The   RCVMSG  SEV   parameter   which  describes   the
                 severity level of the message.

   CMD           The command extracted from the MSGCTLP file.

   USRPGM        The  handling   program  extracted  from  the  MSGCTLP
                 file.

   ERRTYP        Also ERRID and  ERRTXT.  See  the later discussion  of
                 Error Indication.

   DFTFWD        An 'X'  or  blank value  for whether  the message  was
                 forwarded  because  the  default  occurred (i.e.    no
                 message  ID  existed  in  the  MSGCTLP  file  and  the
                 message was either  an inquiry  or the severity  level
                 did not  prevent it).   An 'X'  means the  message was
                 default  forwarded.  You  can determine  a message was
                 forwarded by  reviewing the  FWDQ field.   The  DFTFWD
                 field determines what caused the forwarding.

   RCVDAT        The date the message was received.

   RCVTIM        The time the message was received.

   INQUNA        A  blank or  'X' value.    The 'X'  indicates that  an
                 inquiry    message   was    forwarded    and   remains
                 unanswered.  When an  inquiry is forwarded, the  field
                 is  set  to  X  and  is  blanked  when  the  reply  is
                 received.    An  'X'  can  appear  after  the  Message
                 Control   function  is  ended.     This  could  happen
                 because no  one answered  the message  or the  Message
                 Control   function  was   terminated  before   it  was
                 answered.   You  may  want to  analyze this  field for
                 exceptions.

   RPYDAT        The date the  reply was made.   If an automatic  reply
                 is given, the RCVDAT/RCVTIM will be identical.

   RPYTIM        The time  the reply was made.   If an  automatic reply
                 is given, the RCVDAT/RCVTIM will be identical.

   RPYID         A  cross reference  to the  corresponding RPY  Log ID.
                 This  field  allows  a   cross  reference  between   a
                 forwarded  inquiry  and  a  reply.     If  an  inquiry
                 message  is replied  to automatically,  this  field is
                 not  updated (in the  MSG log type  entry) and will be
                 zero.

                 If a  reply  is received  later, this  field  contains
                 the log  ID of  the reply in  the MSG type  log entry.
                 For  a RPY  log  type entry,  this field  contains the
                 log ID of the original message.

Error indication
----------------

For  typical  error  conditions,  the  Message  Control  function  will
remain  active, post  notice  of the  error to  the  DFTMSGQ queue  and
write  an entry  in the  log.  The  message sent  to the  DFTMSGQ queue
will contain the LOGID of the error.

In the MSGCURP file,  the ERRTYP field denotes  the type of error,  the
ERRID field will contain  the escape message ID (if it  exists) and the
ERRTXT  field  will  contain  the  text  of  the escape  message  or  a
generated  description  of  the  problem.   The  following  entries may
appear in the ERRTYP field.

   CMD           A command from the  CMD field in the MSGCTLP  file has
                 failed.

   USR           The USRPGM program in the MSGCTLP file failed.

   SND           An  error  occurred  on  the  SNDPGMMSG  command.    A
                 typical  error causing  the  CPF2469 message  is where
                 the message  queue from  the  MSGCTLP file  cannot  be
                 found.

   RPY           An error  occurred on the  SNDRPY command.   A typical
                 error  causing   the  CPF2422  message  is  where  the
                 automatic reply in the MSGCTLP  file is not valid  per
                 the  validation  specified  on  the  ADDMSGD  command.
                 Another error  is CPF2420 where the  reply has already
                 been sent through some other means.

                 A  typical  reason  for receiving  CPF2420  is  if the
                 message is  being answered  by the  System Reply  List
                 and  the message  ID  does not  exist  in the  MSGCTLP
                 file.   This  can  be avoided  by adding  the specific
                 message ID to  the MSGCTLP file.   See the section  on
                 Use with the System Reply List.

   CMP           An error  where the CMPSTR  field in the  MSGCTLP file
                 is not valid.  It must be 0 or greater.

   LOG           An  internal  error  denoting that  a  reply  has been
                 processed and  the  Message  Control  function  cannot
                 find the original LOGID.

If  an  un-planned-for  escape  message  is  received  by  the  Message
Control  function, it  will attempt to  send a  failure message  to the
forwarding  message queue.  It  will set the LOG  parameter to ensure a
meaningful job  log  and send  CPF9999 (Function  Check)  as an  escape
message.  This will  cause the job to terminate.  If  the ENDSEV of the
job  (set in the  JOBD) is 40  or less,  the job will  considered to be
abnormally terminated.  The default ENDSEV for CRTJOBD is 30.

Controlling multiple message queues simultaneously
--------------------------------------------------

If you  want to  control multiple  message  queues simultaneously,  you
must have separate  versions of the MSGCURP, MSGHSTP  and MSGINQP files
for  each message queue  being controlled.   The same MSGCTLP  file may
be used or you may have multiple versions.

Backup and Cleanup
------------------

The message  control data  base files  are created  in  a library  that
should be  backed up  regularly.   If you  run a  Save operation  while
STRMSGCTL  is active, the  MSGCURP and MSGINQP  files will be  open for
update  and  you  cannot backup  the  files  unless you  are  using the
system SAVWHLACT function.   The MSGINQP  file is a  work file and  the
data does not need to be backed up.

When  STRMSGCTL is used,  the MSGCURP  is copied  into the  MSGHSTP and
the  MSGCURP  file  is  cleared.   Thus  you  can  normally  backup the
MSGHSTP file whenever you feel like it.

The Message  Control function  never  clears the  MSGHSTP file  so  you
must provide a cleanup solution.

  **   After you  have backed  up the  MSGHSTP file,  you can clear  it
       unless  you  are  interested  in  using  the DSPMSGCTL  function
       against the older messages.

  **   If you  are interested  in retaining  older messages,  a  simple
       solution  would be  to  use  CRTDUPOBJ to  make  a copy  of  the
       MSGHSTP file  in another library  and copy the data  to it until
       you  no  longer need  the information.    You can  use DSPMSGCTL
       against the duplicate file by specifying the LIB parameter.

  **   Another alternative  would be  to  use CRTDUPOBJ  to create  the
       MSGHSTP2 file  in the  same library.   When you want  to cleanup
       the  MSGHSTP file,  use DSPMSGCTL  and determine the  last LOGID
       that you  want to  retain.   A CL  program could  copy from  the
       specified LOGID  to the  MSGHSTP2 file and  then copy  back with
       replace.   Here  are the  commands  (nnn is  the last  LOGID you
       want to keep):

         CPYF    FROMFILE(MSGHSTP) TOFILE(MSGHSTP2) +
                   MBROPT(*REPLACE) INCREL((*IF LOGID *GE nnn))
         CPYF    FROMFILE(MSGHSTP2) TOFILE(MSGHSTP) +
                   MBROPT(*REPLACE)
         CLRPFM  FILE(MSGHSTP2)

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

  **   Operational assistant provides  a function to  allow cleanup  of
       QSYSOPR.   This function  should not  be used if  you are  using
       MSGCTL  because OA  attempts to  remove  messages even  though a
       lock is held on a message queue.

  **   There  will  be a  delay between  the  time a  forwarded inquiry
       message is answered and  the time the originator of  the message
       sees the  response.   See the section  on Polling  of Unanswered
       Inquiry Messages.

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

The following TAA Tools must be on your system:

        EDTVAR        Edit variable
        SNDCOMPMSG    Send completion message
        SNDESCMSG     Send escape message
        TAAARC        TAA Archive

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

The  tool is ready to use,  but you must first create  the the files to
be used by MSGCTL in a named library:

      CRTMSGCTL     LIB(xxx)

You will need  a program  to enter  and maintain the  MSGCTLP file  you
created in  your own  library.   DFU can  be used.   You  will probably
want to  set the TEXT field for lower case  entry when defining the DFU
application.

Enter records into  the MSGCTLP  file for  the common  message IDs  and
those you want to  describe a disposition for.  The  following are some
typical  messages which can  appear in QSYSOPR  that you may  choose to
enter into the MSGCTLP file:

          CPC1126  Controlled cancel initiated
          CPC1163  Job released
          CPC1235  Control cancel delay time expired

          CPF0927  Subsystem terminated
          CPF1103  Subsystem started
          CPF1187  Subsystem cannot allocate a device
          CPF1189  Subsystem varied off a device
          CPF1393  User profile disabled
          CPF1804  Start of subsystem in progress
          CPF2456  Log version full
          CPF2677  Lost contact with a device
          CPF3382  Writer started
          CPF3390  Writer ended normally
          CPF3433  Writer stopped printing
          CPF3471  Writer terminated abnormally

          CPI5906  Local system has sent SNA negative
          CPI5908  Remote system trying to contact device

       None of the  previous messages are inquiry types.  Therefore any
       inquiries will be forwarded unless you add a specific record and
       describe how the inquiry should be handled.

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

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

   STRMSGCTL     *CMD                      TAAMSGA        QATTCMD
   ENDMSGCTL     *CMD                      TAAMSGA2       QATTCMD
   DSPMSGCTL     *CMD                      TAAMSGA3       QATTCMD
   CRTMSGCTL     *CMD                      TAAMSGA6       QATTCMD
*  MSGCTLP       *FILE         PF          TAAMSGAP       QATTDDS
*  MSGCURP       *FILE         PF          TAAMSGAP2      QATTDDS
*  MSGINQP       *FILE         PF          TAAMSGAP3      QATTDDS
*  MSGHSTP       *FILE         PF            Same src as MSGCURP
   TAAMSGAD      *FILE         DSPF        TAAMSGAD       QATTDDS
   TAAMSGAC      *PGM          CLP         TAAMSGAC       QATTCL
   TAAMSGAC2     *PGM          CLP         TAAMSGAC2      QATTCL
   TAAMSGAC3     *PGM          CLP         TAAMSGAC3      QATTCL
   TAAMSGAC4     *PGM          CLP         TAAMSGAC4      QATTCL
**   No object                 CLP         TAAMSGAC5      QATTCL
   TAAMSGAC6     *PGM          CLP         TAAMSGAC6      QATTCL
   TAAMSGAR      *PGM          RPG         TAAMSGAR       QATTRPG
   TAAMSGAR2     *PGM          RPG         TAAMSGAR2      QATTRPG
   TAAMSGAR3     *PGM          RPG         TAAMSGAR3      QATTRPG
   TAAMSGAR4     *PGM          RPG         TAAMSGAR4      QATTRPG

* These files will exist in the library specified on CRTMSGCTL.

**  The skeleton source  TAAMSGAC5 exists to allow  a simple copy using
SEU when writing a user handling program.

Structure
---------

   CRTMSGCTL
     TAAMSGAC6 CL pgm

   STRMSGCTL
     TAAMSGAC  CL pgm  submits   TAAMSGAC4   CL pgm
                                   TAAMSGAR    RPG
                                   TAAMSGAR2   RPG
                                   TAAMSGAR3   RPG

   ENDMSGCTL
     TAAMSGAC2 CL

   DSPMSGCTL
     TAAMSGAC3   CL
       TAAMSGAR4  RPG
         TAAMSGAD    DSPF
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top