RE: MessageQ Break-Handling Programs -- MIDRANGE-L

Well, sure enough, you're right about being in break mode.  I screwed up,
sorry.  The break handler program has to have a job to run in.  Whoever
issues the command provides the "context" for the break handler.  If the job
that issues the CHGMSGQ command ends, the break-handler-program function
stops working.

The section from the V4R3 CL Programmers Guide on break handlers is attached
below.  I would be a little careful about insisting that you have to stay
logged on to make it work.  If Jeff puts the CHGMSGQ in the front of the
backup job, he won't have to stay logged on.  He could also submit another
job that does the CHGMSGQ then waits forever.  If a message arrives on the
queue, the break handler will run inside that job.  When the backup job
completes, it could send a "die" message to the message queue.  The break
handler could recognize that message and kill the job that it is running in.

I am wondering about the "initialize" inquiry messages being sent by the
job.  Are those sent to QSYSOPR no matter what?  That sounds wrong but it
would explain why the messages always break without triggering the program.
Another possible reason -- the severity level may be set above the severity
of the message thus preventing the break handler from starting.

I am also thinking about the add reply list entry (ADDRPYLE) command.  You
can put message IDs in there and specify a particular reply or tell it to
use a default.  Seems to me like it might work pretty well to add a reply
list entry at the beginning of the backup job and remove the RPYLE when you
finished.  Whenever the message was sent, the system would automatically
reply with INZ or whatever.  Jeff, could you make that work?

Again, sorry about the mistake.  I hope that this helps a little.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8.4 Break-Handling Programs

A break-handling program is one that is automatically called when a message
arrives at a message queue that is in *BREAK mode. Both the name
of the program and the break delivery name must be specified on the same
Change Message Queue (CHGMSGQ) command. Although the program
is specified on the CHGMSGQ command, it is one or more procedures within the
program that processes the message. A procedure within this
program must run a Receive Message (RCVMSG) command to receive the message.
To receive and handle the message, the user-defined
program called to handle messages for break delivery is passed parameters
(more specifically, the first procedure to run within the program is
passed these parameters). The parameters identify the message queue and the
message reference key (MRK) of the message causing the
break. See the Break Handling exit program in the System API Reference,
SC41-5801 book, for a list of the parameters. If the break-handling
program is called, it interrupts the job in which the message occurred and
runs. When the break-handling program ends, the original program
resumes processing.

The following program (PGMA), which consists of only this one procedure, is
an example of a break-handling program.

  PGM PARM(&MSGQ &MSGLIB &MRK)
  DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10)
  DCL VAR(&MSGLIB) TYPE(*CHAR) LEN(10)
  DCL VAR(&MRK) TYPE(*CHAR) LEN(4)
  DCL VAR(&MSG) TYPE(*CHAR) LEN(75)
  RCVMSG  MSGQ(&MSGLIB/&MSGQ) MSGKEY(&MRK) +
          MSG(&MSG)
  .
  .
  .
  ENDPGM

After the break-handling program is created, running the following command
connects it to the QSYSMSG message queue.

  CHGMSGQ   MSGQ(QSYS/QSYSMSG) DLVRY(*BREAK) PGM(PGMA)

Notes:

1.  When messages are handled, they should be removed from the message
queue.  When a message queue is put in break mode, any message
    on the queue will cause the break-handling program to get called.

2.  The procedure or program receiving the message should not be coded with
a wait-time other than zero to receive a message. You can specify
    a value other than zero for the wait parameter with the Receive Message
(RCVMSG) command.  The message arrival event cannot be handled
    by the system while the job is running a break-handling event.



An example of a break-handling program is to have the program send a
message, which is normally sent to the QSYSOPR queue, to another
queue in place of or in addition to QSYSOPR.

The following is an example of a user-defined program (again with only one
procedure) to handle break messages. The display station user does
not need to respond to the messages CPA5243 (Press Ready, Start, or
Start-Stop on device &1) and CPA5316 (Verify alignment on device &3)
when this program is used.

  BRKPGM:     PGM (&MSGQ &MSGQLIB &MSGMRK)
              DCL &MSGQ TYPE(*CHAR) LEN(10)
              DCL &MSGQLIB TYPE(*CHAR) LEN(10)
              DCL &MSGMRK TYPE(*CHAR) LEN(4)
              DCL &MSGID TYPE(*CHAR) LEN(7)
              RCVMSG MSGQ(&MSGQLIB/&MSGQ) MSGKEY(&MSGMRK) +
                     MSGID(&MSGID) RMV(*NO)
              /* Ignore message CPA5243 */
              IF (&MSGID *EQ 'CPA5243') GOTO ENDBRKPGM
              /* Reply to forms alignment message */
              IF (&MSGID *EQ 'CPA5316') +
                     DO
                     SNDRPY MSGKEY(&MSGMRK) MSGQ(&MSGQLIB/&MSGQ) RPY(I)
                     ENDDO
              /* Other messages require user intervention */
              ELSE CMD(DSPMSG MSGQ(&MSGQLIB/&MSGQ))
  ENDBRKPGM:  ENDPGM

Attention:

In the above example of a break-handling program, if a CPA5316 message
should arrive at the queue while the DSPMSG command is running, the
DSPMSG display shows the original message that caused the break and the
CPA5316 message. The DSPMSG display waits for the operator to
reply to the CPA5316 message before proceeding.

Note:  This program cannot open a display file if the interrupted program is
waiting for input data from the display.

You can use the system reply list to indicate the system will issue a reply
to predefined inquiry messages. The display station user, therefore,
does not need to reply. For more information, see "Using the System Reply
List" in topic 8.6.

A procedure within a user break-handling program may need a Suspend and
Restore procedure to ensure the display is suspended and restored
while the message handling function is being performed. The Suspend and
Restore procedure is necessary only if the following conditions exist:

   A procedure in the break-program displays other menus or screens

   The break-program calls other programs which may display other menus or
screens.


The following example clarifies the user procedure and display file needed
to suspend and restore the display:

Note:  RSTDSP(*YES) must be specified to create the display file.

         A          R SAVFMT                    OVERLAY  KEEP
         A*
         A          R DUMMY                     OVERLAY
         A                                      KEEP
         A                                      ASSUME
         A            DUMMYR         1A     1  2DSPATR(ND)


     PGM PARM(&MSGQ &MSGLIB &MRK)
         DCL VAR(&MSGQ) TYPE(*CHAR) LEN(10)
         DCL VAR(&MSGLIB) TYPE(*CHAR) LEN(10)
         DCL VAR(&MRK) TYPE(*DEC) LEN(4)
         DCLF FILE(UDDS/BRKPGMFM)
         SNDF RCDFMT(SAVFMT)
         CALL PGM(User's Break Program)
         SNDF RCDFMT(SAVFMT)
     ENDPGM

If you do not want the user specified break-handling program to interrupt
the interactive job, the program may be submitted to run in batch. You
may do this by specifying a break-handling program that receives the message
and then performs a SBMJOB. The SBMJOB performs a call to the
current break-handling program with any parameters that you want to use. (An
example is information from the receive message.) Control will
then be returned to the interactive job and it will continue normally.

Another example of a break-handling program is shown in QUSRTOOL with the
STSMSG tool. It allows you to change some or all of the messages
received at your work station into status messages.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Richard Jackson
mailto:richardjackson@richardjackson.net
www.richardjacksonltd.com
Voice: 1 (303) 808-8058
Fax:   1 (303) 663-4325

-----Original Message-----
From: owner-midrange-l@midrange.com
[mailto:owner-midrange-l@midrange.com]On Behalf Of Bob Buchanan
Sent: Thursday, August 17, 2000 3:49 PM
To: MIDRANGE-L@midrange.com
Subject: Re: MessageQ Break-Handling Programs


Yes, if you want the break handling program to process the message, it
must be in break mode.  The message queue being in break mode is only
valid while someone is signed on.  In other words, it applies to a
single interactive job.  You have to sign on, change the msgq to *break
at your workstation, and STAY signed on.  If the break handling program
isn't handling the message properly, turn CL logging on and find out
what is happening.  You can contact me off-list if you would like. (yes,
I'll post the resolution when there is one)
-Bob Buchanan

> Richard Jackson wrote:
>
> The message queue should not be in break mode.
>
> Richard Jackson
> mailto:richardjackson@richardjackson.net
> www.richardjacksonltd.com
> Voice: 1 (303) 808-8058
> Fax:   1 (303) 663-4325
>
> -----Original Message-----
> From: owner-midrange-l@midrange.com
> [mailto:owner-midrange-l@midrange.com]On Behalf Of Bull, Jeff
> Sent: Thursday, August 17, 2000 10:01 AM
> To: 'MIDRANGE-L@midrange.com'
> Subject: MessageQ Break-Handling Programs
>
> Hi all,
>         I need the advice of a CL guru . . .
>
>         I have a backup program that handles multi-volumes (on an ACL)
>
> unattended using system reply list entries; this is ok but, I am
> trying to
> get control of the initialise-tape function when it encounters an
> unformatted cartridge, an incorrectly formatted cartridge or
> 'files-in-use'.
>         I have changed the tape device msgq to 'x' (from qsysopr),
> changed
> the msgq to *BREAK and specified a handling program, but the messages
> still
> *DSPMSG, i.e. the program is not called, though when you dspmsg the x
> msgq,
> the status is *BREAK and the program is indeed attached.
>         I've written one of these program types before, though not for
> a
> save operation; am I missing something, is what I'm trying simply not
> possible?
>
> Kind regards,
> Jeff Bull.
> Senior AS/400 Support Consultant (AS/400)
> Midas Kapiti International Ltd
>
> Tel:    44 (0) 175 370 8224
> Fax:    44 (0) 175 357 0233
> Mailto:Jeff.Bull@Midas-Kapiti.Com  << == Replies to
> The views and opinions expressed in this e-mail are the senders own
> and do
> not necessarily represent the views and opinions of Misys Plc.
>
> This email message is intended for the named recipient only.  It may
> be
> privileged and/or confidential.  If you are not the intended named
> recipient
> of this email then you should not copy it or use it for any purpose,
> nor
> disclose its contents to any other person.  You should contact
> Midas-Kapiti
> International as shown below so that we can take appropriate action at
> no
> cost to yourself.
>
> Midas-Kapiti International Ltd, Key West, 53-61 Windsor Road, Slough,
> Berkshire, SL1 2DW, England
> Email: Postmaster@midas-kapiti.com Tel: (44) 1753 573244 Fax: (44)
> 1753
> 570233
> Midas-Kapiti International Ltd is registered in England and Wales
> under
> company no. 971479
>
> +---
> | This is the Midrange System Mailing List!
> | To submit a new message, send your mail to MIDRANGE-L@midrange.com.
> | To subscribe to this list send email to MIDRANGE-L-SUB@midrange.com.
>
> | To unsubscribe from this list send email to
> MIDRANGE-L-UNSUB@midrange.com.
> | Questions should be directed to the list owner/operator:
> david@midrange.com
> +---
>
> +---
> | This is the Midrange System Mailing List!
> | To submit a new message, send your mail to MIDRANGE-L@midrange.com.
> | To subscribe to this list send email to MIDRANGE-L-SUB@midrange.com.
>
> | To unsubscribe from this list send email to
> MIDRANGE-L-UNSUB@midrange.com.
> | Questions should be directed to the list owner/operator:
> david@midrange.com
> +---
+---
| This is the Midrange System Mailing List!
| To submit a new message, send your mail to MIDRANGE-L@midrange.com.
| To subscribe to this list send email to MIDRANGE-L-SUB@midrange.com.
| To unsubscribe from this list send email to MIDRANGE-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator:
david@midrange.com
+---

+---
| This is the Midrange System Mailing List!
| To submit a new message, send your mail to MIDRANGE-L@midrange.com.
| To subscribe to this list send email to MIDRANGE-L-SUB@midrange.com.
| To unsubscribe from this list send email to MIDRANGE-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---