Use the Receive Message (RCVMSG) command to receive messages from a message queue for your procedure or program. Messages can be received in the following ways:
To receive a message, you can specify:
RCVMSG MSGQ(QGPL/INVN) MSGTYPE(*ANY) MSG(&MSG)
The message received is placed in the variable &MSG. *ANY is the default value on the MSGTYPE parameter.
When working with the call stack entry message queue of an ILE procedure written in a language other than CL, it is possible to receive an exception message (Escape or Notify) when the exception is not yet handled. The RCVMSG command can be used to both receive a message and indicate to the system that the exception has been handled.
This can be controlled by using the RMV keyword. If *NO is specified for this keyword, the exception is handled and the message is left on the message queue as an old message. If *KEEPEXCP is specified, the exception is not handled and the message is left on the message queue as a new message. If *YES is specified, the exception message is handled and the message is removed from the message queue.
The RTNTYPE keyword can be used to determine if the message received is an exception message, and if so, whether the exception has been handled.
Receiving request messages is a method for your CL procedure or program to process CL commands. For example, your procedure or program can obtain input from a display station and handle the messages that result from the analysis and processing of the program. Usually, request messages are received from the external message queue (*EXT) of the job. For batch jobs, the requests received are those read from the input stream. For interactive jobs, the requests received are those the display station user enters one at a time on the Command Entry display. For example, CL commands are requests that are received by the IBM-supplied CL processor.
Your procedure or program must define the syntax of the data in the request message, interpret the request, and diagnose any errors. While the request is being analyzed or the request function is being run, any number of errors can be detected. As a result of these errors, messages are sent to the call message queue for the procedure or program. The procedure or program handles these messages and then receives the next request message. Thus, a request processing cycle is defined; a request message is received, the request is analyzed and run by your procedure or program with resulting messages displayed, and the next request received. If there are no more request messages to be received in a batch job, an escape message is sent to your procedure or program to indicate this.
More than one OPM program or ILE procedure of a job can receive request messages for processing. The requests received by more recent program calls are considered to be nested within those received by higher level program calls. The request processing cycles at each nesting level are independent of each other. Within an ILE program, one or more procedures within that program can be receiving request messages. If more than one procedure is processing requests than the nesting occurs within the same ILE program and the nesting levels remain independent.
The following diagram shows how request messages are processed by QCMD:
Specifying a CL procedure as a request processor within a program has many advantages. The following list specifies three advantages:
To become a request-processor procedure or program, your procedure or program must include the Send Program Message (SNDPGMMSG) and Receive Message (RCVMSG) commands. For example, the following commands would allow a procedure or program to become a request processor:
SNDPGMMSG MSG('Request Message') TOPGMQ(*EXT) MSGTYPE(*RQS) RCVMSG PGMQ(*EXT) MSGTYPE(*RQS) RMV(*NO)
The request message is received from PGMQ *EXT. When any request message is received, it is moved (actually, it is removed and resent) to the call message queue of the procedure or program that specified the RCVMSG command. Therefore, the correct call message queue must be used when the message is removed.
If the request message is removed using the message reference key (MRK), you should obtain the MRK from the KEYVAR keyword of the RCVMSG command and not the SNDPGMMSG command. (The MRK changes when receiving a request message.) You must specify RMV(*NO) on the RCVMSG command because the procedure or program is not a request processor if the request message is removed from the call message queue.
The procedure or program is identified as a request processor when the request message is received. While the procedure or program is a request processor, other called procedures or programs can be ended using option 2 (End request) on the System Request menu. The request-processor procedure or program should include a monitor for message CPF1907 (MONMSG command). This is necessary because the end request function (from either option 2 on the System Request menu or the End Request command) sends this message to the request processor.
The procedure or program remains a request processor until the procedure ends (either normally or abnormally) or until a RMVMSG command is run to remove all the request messages from the request-processor's call message queue. For example, the following command removes all request messages from the message queue and, therefore, ends request processing:
RMVMSG CLEAR(*ALL)
Call the QCAPCMD API and specify the message retrieve key to have the OS/400 command analyzer to process a request message for an OS/400 command. You can get the message retrieve key when you receive the request message. Process Commands (QCAPCMD) will update the request message in the job log and add any new value supplied. QCAPCMD also hides any parameter values, such as passwords, that are to hidden in the job log. The system will not update the request message in the job log when one of two conditions exists.
To determine if a job has a request processor, display the job's call
stack. Use either option 11 on the Display Job (DSPJOB) or Work with
Job (WRKJOB) command, or select option 10 for the job listed on the WRKACTJOB
display. If a number is shown in the request level column on the
display of the job's call stack, the program or ILE procedure associated
with the number is a request-processor. In the following example, both
QCMD and QTEVIREF are request processors:
+--------------------------------------------------------------------------------+
| Display Call Stack |
| System: S0000000 |
|Job: WS31 User: QSECOFR Number: 000173 |
| |
|Type options, press Enter. |
| 5=Display details |
| |
| Request Program or |
|Opt Level Procedure Library Statement Instruction |
| QCMD QSYS 01DC |
| 1 QCMD QSYS 016B |
| QTECADTR QSYS 0001 |
| 2 QTEVIREF QSYS 02BA |
| |
| |
| |
| |
| |
| |
| |
| Bottom |
| |
|F3=Exit F10=Update stack F11=Display activation group F12=Cancel |
|F17=Top F18=Bottom |
| |
+--------------------------------------------------------------------------------+
The following is an example of a request-processing procedure:
PGM SNDPGMMSG MSG('Request Message') TOPGMQ(*EXT) MSGTYPE(*RQS) RCVMSG PGMQ(*EXT) MSGTYPE(*RQS) RMV(*NO) . . . CALL PGM(PGMONE) MONMSG MSGID(CPF1907) . . . RMVMSG CLEAR(*ALL) CALL PGM(PGMTWO) . . . ENDPGM
The first two commands in the procedure make it a request processor. The procedure remains a request processor until the RMVMSG command is run. A Monitor Message command is placed after the call to program PGMONE because an end request may be sent from PGMONE to the request-processor. If monitoring is not used, a function check would occur for an end request. No message monitor is specified after the call to PGMTWO because the RMVMSG command ends request processing.
If an end request is attempted when no request-processing procedure or program is called, an error message is issued and the end operation is not performed.
(C) Copyright IBM Corporation 1992, 2005. All Rights Reserved.