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
|
