Example: Send an immediate message and handling a reply

This example shows how a procedure sends an inquiry message and handles the reply.

In this example, the procedure does the following:

Sends an immediate inquiry message to QSYSOPR
Requests a reply of yes or no (Y or N)
Ensures that a valid reply has been entered
Does a time-out if the operator does not reply within 120 seconds

           PGM
           DCL        &MSGKEY *CHAR LEN(4)
           DCL        &MSGRPY *CHAR LEN(1)
SNDMSG:    SNDPGMMSG  MSG('.... Reply Y or N') TOMSGQ(QSYSOPR) +
                        MSGTYPE(*INQ) KEYVAR(&MSGKEY)
           RCVMSG     MSGTYPE(*RPY) MSGKEY(&MSGKEY) WAIT(120) +
                        MSG(&MSGRPY)
           IF         ((&MSGRPY *EQ 'Y') *OR (&MSGRPY *EQ 'y')) DO
           .
           .
           GOTO       END
           ENDDO      /* Reply of Y */
           IF         ((&MSGRPY *EQ 'N') *OR (&MSGRPY *EQ 'n')) DO
           .
           .
           GOTO       END
           ENDDO      /* Reply of N */
           IF         (&MSGRPY *NE ' ') DO
           SNDPGMMSG  MSG('Reply was not Y or N, try again') +
                        TOMSGQ(QSYSOPR)
           GOTO       SNDMSG
           ENDDO      /* Reply not valid */
    /* Timeout occurred */
           SNDPGMMSG  MSG('No reply from the previous message +
                        was received in 120 seconds and a 'Y'' +
                        value was assumed') TOMSGQ(QSYSOPR)
           .
           .
END:       ENDPGM

The SNDUSRMSG command cannot be used instead in this procedure because it does not support a time-out option (SNDUSRMSG waits until it receives a reply or until the job is canceled).

The SNDPGMMSG command sends the message and specifies the KEYVAR parameter. This returns a message reference key, which uniquely identifies this message so that the reply can be properly matched with the RCVMSG command. The KEYVAR value must be defined as a character field length of 4.

The RCVMSG command specifies the message reference key value from the SNDPGMMSG command for the MSGKEY parameter to receive the specific message. The reply is passed back into the MSG parameter. The WAIT parameter specifies how long to wait for a reply before timing out.

When the reply is received, the procedure logic checks for an upper or lower case value of the Y or N. Normally the value is entered by the operator as a lower case value. If the operator enters a non-blank value other than Y or N, the procedure sends a different message and then repeats the inquiry message.

If the operator had entered a blank, no reply is sent to the procedure. If a blank is returned to the procedure, the time out occurred (the operator did not reply). The procedure sends a message to the system operator stating that a reply was not received and the default was assumed (the 'Y'' value is shown as 'Y' in the message queue). Because the assumed value of 'Y' is not displayed as the reply, you cannot determine when looking at a message queue whether the message should be answered or has already timed out. The procedure does not remove a message from the message queue once it has been sent. The second message should minimize this concern and provides an audit trail for what has occurred.

If the time out has already occurred and the operator replies to the message, the reply is ignored. The operator receives no indication that the reply has been ignored.