MessageQ Break-Handling Programs

The section from the V4R3 CL Programmers Guide on break handlers.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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

Break message handling program

To compile, use the following command:

      CRTCLPGM PGM(xxx/MSG2LIN24) SRCFILE(xxx/QCLSRC) 
Key the program into source physical file QCLSRC in one of your libraries (represented by xxx), 
then compile the program by executing the CRTCLPGM as indicated. Now run the following command:

      CHGMSGQ MSGQ(…) DLVRY(*BREAK) PGM(xxx/MSG2LIN24)