CL Programming

Receiving Messages in a CL Procedure or Program

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.

Request Messages

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:



RSLF166

(1)
The CL processor QCMD receives a request message from *EXT.

(2)
If there is no request message on *EXT, the Command Entry display is displayed. The display station user enters a command on the display. When the command is entered, it is placed on *EXT as a request message.

(3)
The command is then moved to the end of the QCMD call message queue and is passed from there to QCMD.

(4)
The command is analyzed and its command processing program (CPP) is called.

(5)
The command processing program sends diagnostic messages to the call message queue for QCMD.

(6)
Then the command processing program sends an escape message to the call message queue for QCMD. The escape message notifies QCMD that diagnostic messages are on the queue and that QCMD should end processing of the CPP.

(7)
QCMD is monitoring for the arrival of a request-check (CPF9901) or function-check (CPF9999) escape message. QCMD then tries to receive the next request message. If a request processor receives message CPF9901 or CPF9999, it should run a Reclaim Resources (RCLRSC) command. The request processor should also monitor for messages CPF1907 (end request) and CPF2415 (which indicates that the user pressed F3 or F12 on the Command Entry display).

(8)
Because a request message was being processed, all the messages on the call message queue for QCMD are written to the Command Entry display, which then prompts the display station user for another command.

(9)
The previous request message (command) and its associated messages are contained in the job log according to the message logging level specified for the job. For more information, see Message Logging.

Writing Request-Processing Procedures and Programs

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.

Determining if a Request-Processor 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.

Note:
In the sample programs, the RCVMSG command uses the minimal number of parameters needed to become a request processor. You need to say you want to receive a request message but do not want to remove it. You also need to identify the specific call queue from which the message request originated. Other parameters can be added as necessary.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]