RCVMSG (Receive Message)

RCVMSG Command syntax diagram

 

Purpose

The Receive Message (RCVMSG) command is used by a program to receive a message that was previously sent to a message queue.

The RCVMSG command receives messages from a job message queue (a message queue associated with a call stack entry or the external message queue (*EXT)), or from a named message queue. The program can receive a message from a message queue associated with its own call stack entry or from a message queue associated with another call stack entry.

This command copies a message received in the specified message queue into control language (CL) variables within the program. The message and its attributes are copied into the CL variables specified by the parameters KEYVAR through DTACCSID.

You can specify the message being received by indicating the message type, the reference key of the message, or both. The program receiving the message can also specify, on the RCVMSG command, whether a message is removed from the message queue or left there as an old message. If the specified message queue is not allocated to the job in which this command is entered, or to any other job, the message queue is implicitly allocated by this command for the duration of the command's processing.

If a message of the specified type has not been received by the queue, the requesting program can either wait for a message to arrive or continue with other processing. This allows a set of message queues to be polled.

If the message received is an unhandled exception message, the program can specify whether this command should handle the exception. An unhandled exception message is an escape, status, or notify message that has been sent to an Integrated Language Environment (ILE) procedure. When this command is run, the ILE procedure has not yet taken action to tell the system that the exception is handled. One action the ILE procedure can take is to call a CL program that receives the message using this command. More information on actions that can be taken is in the ILE C book.

Restriction: This command is valid only in compiled CL programs.

Optional Parameters or if it is associated with the caller of the program or procedure.

*SAME: The message is received from the message queue of the program or procedure identified by Element 2.

*PRV: The message is received from the message queue of the program or procedure that called the program or procedure identified by Element 2.

Note: If the message queue previous to the one identified by Element 2 is for an ILE program entry procedure (PEP), the message will be received from the message queue immediately previous to the PEP message queue. (Effectively this would be two message queues previous to the one identified by Element 2).

Element 2: Program or Qualified Procedure

Element 2 of this parameter has three items. Item 1 specifies the program or procedure of the job message queue. Items 2 and 3 specify the module name and the bound program name, which can be used to qualify the procedure name.

Item 1: Program or Procedure Name

*: Identifies the program running the RCVMSG command.

program-or-procedure-name: Specify the name of the program or procedure used.

If Item 1 identifies a program, the name specified can be a maximum of 10 characters. If Item 1 identifies a procedure, the name specified can be a maximum of 256 characters.

The procedure name alone may not identify the correct procedure. Several different procedures with the same name can run in a job. To further identify a procedure, the name specified can be qualified by a module name, or by both a module name and a bound program name.

Item 2: Module Name

The module name qualifier identifies the module into which the procedure was compiled.

*NONE: No module name is specified.

module-name: Specify the module name to be used as a qualifier for the specified procedure name (modules are associated only with procedures). The module name can be a maximum of 10 characters.

If a module name is not specified but a bound program name is, *NONE must be specified in the module name position.

Item 3: Bound Program Name

The bound program name qualifier identifies the program to which the procedure was bound.

*NONE: No bound program name is specified.

bound-program-name: Specify the bound program name to be used as a qualifier for the specified procedure name (and module name if specified). The bound program name can be a maximum of 10 characters.

Single Value

*EXT: The message is received from the external message queue of the job. The external message queue is used to communicate with the external requester of the job, such as a display station user.

MSGQ
Specifies the qualified name of the message queue (not a program message queue) from which a message is received. If MSGQ is specified, the PGMQ parameter cannot be specified.

*PGMQ: The job message queue specified in the PGMQ parameter is the only queue from which a message is received. The possible library values are:

*LIBL: The library list is used to locate the message queue.

*CURLIB: The current library for the job is used to locate the message queue. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library where the message queue is located.

message-queue-name: Specify the name of the message queue from which a message is received.

MSGTYPE
Specifies the type of message received by this program. The message types *EXCP, and *RQS exists only on job message queues and therefore can be received only from a job message queue. For the coding relationships between the MSGTYPE and MSGKEY parameters, see Coding Relationships in the MSGKEY parameter description.

*ANY: Any type of message (except a sender's copy) is received. To receive a sender's message, MSGTYPE(*COPY) must be specified.

*COPY: A copy of an inquiry message that was previously sent is received by this program. The message queue specified for the PGMQ or MSGQ parameters must be the same queue that was specified for the RPYMSGQ parameter when the inquiry message was sent.

*COMP: A completion message is received. It indicates the status of the work that this program requested of another program.

*DIAG: A diagnostic message is received. It provides information about errors detected by another program in the input sent by this program or errors that occurred when the requested function was being processed by the other program.

*EXCP: An exception message is received. Exception messages (escape, notify, status) are received by the program in last-in first-out (LIFO) order. The receiving program can monitor for exception messages by using the MONMSG command.

Note: Non-exception messages are received in first-in first-out (FIFO) order.

If an exception message is received from a message queue for a procedure, the related exception may not be handled at the time the RCVMSG command is run. The RMV parameter can be used to specify whether the exception is to be handled by the RCVMSG command.

*FIRST: The first message currently on the specified message queue is received.

*INFO: An information only message is received.

*INQ: An inquiry message is received.

*LAST: The last message currently on the specified message queue is received.

*NEXT: The message that follows the one specified in the MSGKEY parameter is received. If there is not another message available, blanks are returned in all CL variables.

When a message is received from a message queue associated with a call stack entry, *NEXT works only for one call stack entry. *NEXT cannot be used to receive messages for multiple call stack entries of the same program.

*PRV: The message previous to the message indicated by the MSGKEY parameter is received.

*RPY: A reply message is received. This program has sent an inquiry message to a message queue and expects a reply.

*RQS: A request message is received. The message specifies a request for a function. The receiving program can then perform the function requested.

MSGKEY
Specifies the message reference key of the message that is received.

*NONE: No message reference key is specified.

*TOP: The top of the message queue is used. *TOP can be used only when MSGTYPE(*NEXT) is specified. It causes the first message on the message queue to be received. For program message queues, this is the message following the last request message that was received, if any.

&CL-variable-name: Specify the name of the control language (CL) variable that contains the message reference key of the message received by this program. This key is assigned by the system and cannot be shown. The variable must be a character variable having a length of 4 characters.

Coding Relationships: The MSGTYPE and MSGKEY parameters can be used separately in the RCVMSG command, or together.

  • If neither MSGTYPE nor MSGKEY is specified, MSGTYPE(*ANY) is assumed and the first new message in the queue is received; that is, the messages are received in FIFO (first-in, first-out) order.

  • If one of the message types specified on the MSGTYPE parameter is *COMP, *DIAG, *INFO, *INQ, *RPY, *COPY, or *RQS, a new message of the specified type is received in FIFO order. If the type is *EXCP, new messages are received in LIFO (last-in, first-out) order.

  • If only MSGKEY is specified with a CL variable name and the message queue contains a message with the specified message reference key, that message is received. If the MSGKEY specified is for a sender's copy message, the reply to the message is received if it is available. If the reply is not available, blanks will be returned in all CL variables. If a message is requested by key and the message is not available, an escape message is sent to the requesting program.

  • If MSGTYPE(*COPY) and MSGKEY (&CL-variable-name) are specified, the sender's copy of an inquiry message is received.

  • If both MSGTYPE and MSGKEY (&CL-variable-name) are specified and the message queue has a message of that type, the message is received by the program. If the reference key is correct and the message type is not, then an error message is sent to the program.

  • If MSGTYPE(*NEXT) is specified, MSGKEY must be specified. The message following the message with the specified reference key is received. If MSGKEY(*TOP) is specified with MSGTYPE(*NEXT), the first message on the message queue is received. For call message queues, this is the first message following the last request message received.

  • If MSGTYPE(*PRV) is specified, MSGKEY must be specified. The message previous to the message with the specified reference key is recieved.

If MSGTYPE(*RPY) is specified with a MSGKEY value that refers to either a sender's copy or an inquiry message, any reply to the sender's copy or inquiry message is returned. If there is no reply to that sender's copy or inquiry message, blanks are returned. When the MSGKEY value refers to an inquiry message, the WAIT parameter is ignored (this implies WAIT(0), which is the default value for the WAIT parameter).

If MSGTYPE(*ANY) is specified with a KEYVAR variable and the first message type found is a reply message, the KEYVAR variable returns the message reference key of the sender's copy message. Similarly, if MSGTYPE(*RPY) is specified with a KEYVAR variable, the message reference key of the sender's copy message is returned.

WAIT
Specifies the length of time (in seconds) that the program waits for a message of the specified type to arrive in the message queue if it is not there when this RCVMSG command is processed. If the message does not arrive in the specified time, the CL variables named to receive message fields are filled with blanks.

The program cannot wait for a message from a program message queue unless it is receiving a reply.

If a wait time is specified (not zero), the message queue is implicitly allocated to the first user whose message is received, and it is not released until the request has been handled by the program.

If a message is sent to a message queue in the same job, and the message queue is in break delivery mode, this parameter is ignored. (that implies WAIT(0), which is the default value for the WAIT parameter).

If the value specified for MSGKEY refers to an inquiry message, and MSGTYPE(*RPY) has been specified, the program ignores the WAIT parameter (Value for Wait is 0).

0: The program does not wait for the arrival of a message. If a message of the specified type is not in the queue when this command is processed, the specified CL variables are filled with blanks (or zeros, if they are decimal variables).

*MAX: The program waits indefinitely for the arrival of the specified type of message.

number-of-seconds: Specifies the number of seconds that the program waits for the arrival of a specific type of message.

RMV
Specifies whether the message received by the program is removed from the message queue. For exception messages for unhandled exceptions, also specifies whether the exception is to be handled by the RCVMSG command. If MSGTYPE(*INQ) is specified, RMV(*NO) must also be specified so a reply to the inquiry message can be sent.

*YES: The message is removed from the message queue. If the message is an unhandled exception, the exception is handled by running the RCVMSG command.

*NO: The message is not removed from the message queue. It is left on the message queue as an old message. If the message is an unhandled exception, the exception is handled by running the RCVMSG command.

Note: Old messages are messages that have been received but not deleted. An old message can be received again in one of the following ways:

  1. The message reference key of the message is specified for the MSGKEY parameter.

  2. A message type of *FIRST, *LAST, *NEXT, or *PRV is specified for the MSGTYPE parameter.

*KEEPEXCP: If the message is an exception message and the exception has not been handled, the exception is left unhandled and the message is left on the message queue as a new message. It can be received again by using the RCVMSG command to receive an *EXCP message. If the message is not an exception message, or if it is but the exception has already been handled, the message is left on the message queue as an old message.

To handle an exception after the RCVMSG has been run, the command can be run a second time by specifying RMV(*YES) or RMV(*NO).

CCSID
Specifies the coded character set identifier (CCSID) that you want the message text returned in. This only applies to text returned in the MSG, SECLVL and MSGDTA parameters. When replacement data is returned in the MSGDTA parameter or substituted into the text returned in the MSG or SECLVL parameters, only the part of the replacement text that is defined as a character that can be converted (*CCHAR) is converted. The rest of the replacement data is not converted. For more information about the *CCHAR field, see the ADDMSGD command.

*JOB: The received message is converted to the CCSID of the job before being returned.

*HEX: The received message is not converted before being returned.

coded-character-set-identifier: Specify the CCSID that you want your message converted to before being returned. Valid values range from 1 through 65535. For a list of valid CCSID values, see the Globalization topic in the Information Center. Only CCSID values that a job can be changed to will be accepted.

For more information on the message handler and its use of CCSIDs, see the Globalization topic in the Information Center.

Parameters for Received Message Fields

All of the following parameters are used to specify the names of the CL variables that receive the specified fields and attributes of a message when the message is received by the program. If WAIT (number-of-seconds) is specified, and the time-out occurs, the variables, which must already be declared in the program, are filled with blanks. If the message field returned is larger than the CL variable specified, the message field is truncated; if the message field is shorter, it is padded with blanks. If the program does not need the value for a specific message parameter, no CL variable is specified for it. If a parameter is not specified, the corresponding message value is not received in the program.

KEYVAR
Specifies the name of the CL character variable, if any, that contains the message reference key identifying the message received by the program containing this RCVMSG command. At the time the RCVMSG command is processed, the system returns the message reference key to the variable specified by KEYVAR in this command and changes the received message to an old message. The message reference key can then be used in the MSGKEY parameter in a subsequent RCVMSG command to receive the old message. If the message is not found, blanks are returned for the KEYVAR variable. For reply type messages, use the MSGKEY parameter on this command in conjunction with the KEYVAR parameter on the SNDPGMMSG command. The message reference key can also be used by this program for building message subfiles. The CL variable is the name of the field for which the SFLMSGKEY keyword is specified in the DDS for the message subfile.

Note: For message queues not associated with call stack entries, message reference keys can be used again after a message has been received and then removed (by specifying *YES on the RMV parameter).

The variable must be a character variable having a length of 4 characters.

Note: When using the message reference key (obtained from the CL variable specified by the KEYVAR parameter of the Send Program Message (SNDPGMMSG) command) to receive the reply to an inquiry message, note that the message reference key refers to the sender's copy. The sender's copy message is located on the reply message queue (which defaults to the program message queue that sent the inquiry message), not the message queue to which the inquiry message was sent.

MSG
Specifies the name of the CL character variable, if any, that contains the message text when the message is received by the program. This includes the message data fields that were substituted for substitution variables in the text before the message was sent (replies and immediate messages contain no message data fields). This is a variable-length field, but most first-level message text is less than 132 characters in length. This parameter receives the reply from an *INQ message sent by the same program that issued the RCVMSG command.

MSGLEN
Specifies the name of the CL decimal variable, if any, that contains the total length of the first-level message text available to be received. The variable must be a decimal variable having a length of 5 positions.

SECLVL
Specifies the name of the CL character variable, if any, that contains the help text when the message is received by the program. This includes the message data fields that were substituted for substitution variables in the text before the message was sent (replies and immediate messages do not have second-level messages). A message data field is a variable length field, but most help text is less than 3000 characters in length.

SECLVLLEN
Specifies the name of the CL decimal variable, if any, that contains the total length of the second-level message available to be received. The variable must be a decimal variable having a length of 5 positions.

MSGDTA
Specifies the name of the CL character variable, if any, that contains the message data record received by the program as part of the message. The message data record contains the substitution values (in a single character string) that are used in the text of the received message. The amount of data returned and its format depend on the message. Pointers contained in system messages are invalidated.

Note: If you use data that has an invalidated pointer in it an error message can occur.

MSGDTALEN
Specifies the name of the CL decimal variable, if any, that contains the total length of the message data record available to be received. The variable must be a decimal variable having a length of 5 positions.

MSGID
Specifies the name of the CL character variable, if any, that contains the message identifier of the message received by the program. If the message being received is an immediate message, a message identifier is not returned. The minimum length of the variable is 7 characters.

SEV
Specifies the name of the CL decimal variable, if any, that contains the severity code of the message received by the program. The variable must be a decimal variable having a length of two positions. If the message being received is an immediate message, the message severity is not returned.

SENDER
Specifies the name of the CL character variable, if any, that contains the identification of the sender of the message received through the RCVMSG command. The length of the CL variable depends on the SENDERFMT specification. If SENDERFMT(*SHORT) is specified, the variable should be a minimum of 80 characters. If SENDERFMT(*LONG) is specified, the variable should be a minimum of 720 characters.

SENDERFMT
Specifies which format of the sender identification is returned. This parameter is valid only when the SENDER parameter is specified.

*SHORT: The short format of the sender information is returned. The short format is 80 characters, with the last 9 characters set to blanks. The following information is returned:

  • The first 26 characters identify the sending job

    • Job name (10)

    • User name (10)

    • Job number (6)

  • The next 16 characters identify the sending program

    • Program name (12) (for an ILE procedure, this is the bound program name); if the sender type is 3, the first three characters of this field are less than symbols (<<<) followed by the last nine characters of the program name

    • Instruction number (4) (for an ILE procedure, this field is set to blanks)

  • The next 13 characters are the date and time

    • Date (7) (in the format 0yymmdd)

    • Time (6) (in the format hhmmss)

  • The next 14 characters identify the sent-to call stack entry if the message is sent to a call message queue

    • Program name (10) (for an ILE procedure, this is the bound program name)

    • Instruction number (4) (for an ILE procedure, this field is set to blanks)

  • The next 1 character identifies the sender type

    • "0*" if the sender is an OPM program or a SLIC program with 12 characters or less

    • "1" if the sender is an ILE procedure and the name is 256 characters or less

    • "2" if the sender is an ILE procedure and the name is more than 256 characters

    • "3" if the sender is a SLIC program with more than 12 characters

  • The last 1 character identifies the sent-to type

    • "0" if the receiver is an OPM program

    • "1" if the receiver is an ILE procedure and the name is 256 characters or less

    • "2" if the receiver is an ILE procedure and the name is more than 256 characters

*LONG: The long format of the sender information is returned. The long format is 720 characters, with the last 46 characters set to blanks. The following information is returned:

  • The first 26 characters identify the sending job

    • Job name (10)

    • User name (10)

    • Job number (6)

  • The next 13 characters are the date and time

    • Date (7) (in the format 0yymmdd)

    • Time (6) (in the format hhmmss)

  • The next 1 character identifies the sender type

    • "0" if the sender is an OPM program or a SLIC program with 12 characters or less

    • "1" if the sender is an ILE procedure and the name is 256 characters or less

    • "2" if the sender is an ILE procedure and the name is more than 256 characters

    • "3" if the sender is a SLIC program with more than 12 characters

  • The next 1 character identifies the sent-to type

    • "0" if the receiver is an OPM program

    • "1" if the receiver is an ILE procedure and the name is 256 characters or less

    • "2" if the receiver is an ILE procedure and the name is more than 256 characters.

  • The next 12 characters are the sender's program name (for an ILE procedure, this is the bound program name); if the sender type is 3 and the program name is greater than 12 characters in length, the first three characters of this field are less than symbols (<<<) followed by the last nine characters of the program name.

  • The next 10 characters are the sender's module name (if the sender is not an ILE procedure, this field is set to blanks)

  • The next 256 characters are the sender's procedure name (if the sender is not an ILE procedure, this field is set to blanks)

    • For a nested procedure name, each procedure name is separated by a colon (:) starting with the outer-most procedure name , and ending with the inner-most procedure name.

    • For a procedure name that is longer than 256 characters, three less than symbols (<<<) are returned followed by the last 253 characters of the procedure name; the QMHRCPM API can be used to obtain the entire procedure name

  • The next 1 character is blank

  • The next 4 characters are the number of statement numbers available

    Note: A statement number represents a point in the sending program at which the message was sent. For programs and non-optimized procedures, this count is always 1. For optimized procedures, this count can be greater than 1, and each statement number represents a point at which the message could have been sent. If it is not possible to return statement numbers, this count will be 0.

  • The next 30 characters return a maximum of 3 statement numbers, 10 characters each

  • The next 320 characters return program or procedure information if the message being received was originally sent to a message queue associated with a call stack entry (otherwise, this field is set to blanks)

    • Sent-to program name (10) (for an ILE procedure, this is the bound program name)

    • Sent-to module name (10) (if the sender is not an ILE procedure, this field is set to blanks)

    • Sent-to procedure name (256) (if the sender is not an ILE procedure, this field is set to blanks)

      • For a nested procedure name, each procedure name is separated by a colon (:) starting with the outer-most procedure name, and ending with the inner-most procedure name.

      • For a procedure name that is longer than 256 characters, three less than symbols (<<<) are returned followed by the last 253 characters of the procedure name; the QMHRCVPM API can be used to obtain the entire procedure name

    • Blanks (10)

    • Number of statements available for the receiving call stack entry (4)

      Note: A statement number represents a point at which the sent-to program was suspended (for example, due to a call operation) at the time the message was sent. For programs and non-optimized procedures, this count is always 1. For optimized procedures, this count can be greater than 1, and each statement number represents a point at which the message could have been sent. If it is not possible to return statement numbers, this count will be 0.

    • Statement numbers (30) (a maximum of 3 statement numbers, 10 characters each)

RTNTYPE
Specifies the name of the CL variable, if any, that contains the type code for the message received by the program. The variable must be a character variable having a length of 2 positions. The following values are returned to indicate the message type:
Value
Message Type
01
Completion
02
Diagnostic
04
Information
05
Inquiry
06
Sender's Copy
08
Request
10
Request with prompting
14
Notify (exception already handled at time of RCVMSG)
15
Escape (exception already handled at time of RCVMSG)
16
Notify (exception not handled at time of RCVMSG)
17
Escape (exception not handled at time of RCVMSG)
21
Reply, not checked for validity
22
Reply, checked for validity
23
Reply, message default used
24
Reply, system default used
25
Reply, from System Reply List

ALROPT
Specifies the name of the CL variable, if any, used to return the alert option of the message received by the program. The variable must be a character variable 9 positions in length.

MSGF
Specifies the name of the CL variable, if any, used to return the message file name of the message received by the program. If the message received is a stored message, the message file name of the file containing the stored message is returned. If the received message is not a stored message, the message file name is returned as blanks. The variable must be a character variable 10 positions in length.

Note: The message file name returned on this parameter is the message file specified or defaulted on either the SNDPGMMSG or SNDUSRMSG command, not the overriding message file. If an override was specified when sending the message, the same override should be used when receiving the message.

MSGFLIB
Specifies the name of the CL variable, if any, used to return the message file library name of the message received by the program. If the message received is a stored message, the message file library name specified when the message was sent is returned. If *LIBL was specified on the send command, *LIBL is returned. If the received message is not a stored message, the message file library name is returned as blanks. The variable must be a character variable 10 positions in length.

Note: The message file library name returned on this parameter is the message file specified or defaulted on either the SNDPGMMSG or SNDUSRMSG command, not the overriding message file library. If an override was specified when sending the message, the same override should be used when receiving the message.

SNDMSGFLIB
Specifies the name of the CL variable, if any, used to return the name of the library that contains the message file used to send the message. If the message received is stored in a message file, the name of the library containing the message file is returned. For example, if the name of the library containing the message file is MYLIB, and *LIBL is used to send a predefined message, this parameter would return MYLIB. If the message received is not a stored message, the message file library name is returned as blanks.

TXTCCSID
Specifies the name of the CL variable, if any, used to return the coded character set identifier (CCSID) associated with the text returned by the MSG and SECLVL parameters. If a conversion error occurs, or if the CCSID you requested the text to be converted to is 65535, the CCSID that the message description or the text for an immediate message is stored in is returned. Otherwise, the CCSID you wanted the text converted to is returned. If you do not want the text converted before it is returned to you but you do want to know which CCSID that the message description or the text for an immediate message is stored in, specify 65535 on the CCSID parameter, and the CCSID is returned by the TXTCCSID parameter. You can also check for a conversion error by comparing the CCSID you passed in against the TXTCCSID returned. If they are not equal and they are not 65535, a conversion error occurred.

DTACCSID
Specifies the name of the CL variable, if any, used to return the coded character set identifier (CCSID) associated with the replacement data defined as *CCHAR. All other replacement data is not converted before it is returned. If a conversion error occurs, or if the CCSID you requested the text to be converted to is 65535, the CCSID of the message data is returned. If there is no *CCHAR replacement data in the text, 65535 is returned. Otherwise, the CCSID you wanted the text converted to is returned. For immediate messages, 0 is returned. You can check for a conversion error by comparing the CCSID you passed in against the DTACCSID returned. If they are not equal and they are not 65535 or 0, a conversion error occurred.

Examples for RCVMSG

Example 1: Receiving a Message 

RCVMSG  MSGQ(SMITH)  MSGKEY(&KEY)  MSG(&WORK)

This command receives the message having the message reference key specified by the program variable &KEY from the message queue SMITH. The text of the message is copied into the CL variable &WORK.

Example 2: Receiving a New Message 

RCVMSG  MSGQ(INV)  WAIT(120)  MSG(&WORK)

This command receives a new message from the message queue named INV into the CL variable &WORK. The program waits no more than 120 seconds for the arrival of a new message if there are no new messages in the message queue. If there is more than one new message in the queue, the first message in the queue is the message received by the program.

Example 3: Receiving a Message From a Procedure 

RCVMSG   PGMQ(*SAME CURRENT_MONTH_TOTALS)  MSGTYPE(*EXCP)
  RMV(*KEEPEXCP)  MSGID(&MID)  MSG(&MTEXT)

This command receives an exception message from the procedure CURRENT_MONTH_TOTALS. Since the specified name is more than 10 characters, the system does search for any programs. If the message is an unhandled exception, the message is left on the call message queue as a new message and the exception is not handled by the RCVMSG command. The message ID is returned in the CL variable &MID and the message text in the CL variable &MTEXT. To handle the exception and remove the message, run the following RCVMSG command: 

RCVMSG   PGMQ(*SAME CURRENT_MONTH_TOTALS)
  MSGTYPE(*EXCP)  RMV(*YES)

Example 4: Receiving a Message from a Program or Procedure 

RCVMSG   PGMQ(*SAME TARGETPGM)  MSGTYPE(*EXCP)
  RMV(*NO)  MSGID(&MID)  MSG(&MTEXT)

This command receives an exception message from the message queue of the program or procedure named TARGETPGM. Since the specified name is only 9 characters, the system searches both programs and procedures. Because RMV(*NO) is specified, if the message is an unhandled exception, the exception is handled by the RCVMSG command. The message is left on the message queue as an old message.

Example 5: Receiving a Message Using Qualifiers 

RCVMSG   PGMQ(*SAME PRINT_RPT_FMT1 DEPTRPTS AREARPTS)
  MSGTYPE(*EXCP)  RMV(*YES)
  MSGID(&MID)  MSG(&MTEXT)

This command receives an exception message from the message queue of the procedure named PRINT_RPT_FMT1. The procedure must have been compiled into the module DEPTRPTS and have been bound into the bound program AREARPTS. Since RMV(*YES) is specified, the exception is handled if the exception message is for an unhandled exception. The message is always removed from the message queue.

Example 6: Receiving a Message Using a Partial Procedure Name 

RCVMSG   PGMQ(*SAME HANDLE_FORM_NUM>>>)
  MSGID(&MID)  MSG(&MTEXT)

This command receives a new message from the most recent procedure whose name begins with HANDLE_FORM_NUM.

Error messages for RCVMSG

*ESCAPE Messages

CPF2401
Not authorized to library &1.
CPF2403
Message queue &1 in &2 not found.
CPF2407
Message file &1 in &2 not found.
CPF2408
Not authorized to message queue &1.
CPF2411
Not authorized to message file &1 in &2.
CPF241C
Variable for SENDER parameter is too small.
CPF2410
Message key not found in message queue &1.
CPF2415
End of requests.
CPF2423
Variable specified in SENDER parameter less than &1 bytes.
CPF2433
Function not allowed for system log message queue &1.
CPF2449
Message that should be a reply, is not a reply.
CPF2450
Work station message queue &1 not allocated to job.
CPF2451
Message queue &1 is allocated to another job.
CPF247A
Call stack entry not found.
CPF247E
CCSID &1 is not valid.
CPF2471
Length of field not valid.
CPF2477
Message queue &1 currently in use.
CPF2479
Call stack entry not found.
CPF2482
Message type &1 not valid.
CPF24A3
Value for call stack counter parameter not valid.
CPF24A8
Value for wait time not valid.
CPF24B3
Message type &1 not valid.
CPF2531
Message file &1 in &2 damaged for &3.
CPF2532
Job message queue is damaged. Job log ended.
CPF2548
Damage to message file &1 in &2.
CPF2551
Message key and message type combination not valid.
CPF36F7
Message queue QSYSOPR is allocated to another job.
CPF8127
&8 damage on message queue &4 in &9. VLIC log-&7.
CPF8176
Message queue for device description &4 damaged.