The Receive Message (RCVMSG) command is used by a program to receive a message 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 does not exist on 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 Concepts book, SC41-5606.

Parameters

Keyword	Description	Choices	Notes
PGMQ	Call stack entry message queue	Single values: *EXT Other values: Element list	Optional, Positional 1
	Element 1: Relationship	*SAME, *PRV
	Element 2: Call stack entry identifier	Element list
	Element 1: Call stack entry	Character value, *
	Element 2: Module	Name, *NONE
	Element 3: Bound program	Name, *NONE
MSGQ	Message queue	Single values: *PGMQ Other values: Qualified object name	Optional, Positional 2
	Qualifier 1: Message queue	Name
	Qualifier 2: Library	Name, *LIBL, *CURLIB
MSGTYPE	Message type	*ANY, *NEXT, *PRV, *INFO, *INQ, *RPY, *FIRST, *COPY, *COMP, *DIAG, *EXCP, *RQS, *LAST	Optional, Positional 3
MSGKEY	Message key	Character value, *NONE, *TOP	Optional, Positional 4
WAIT	Wait time	Integer, 0, *MAX	Optional, Positional 5
RMV	Remove message	*YES, *NO, *KEEPEXCP	Optional
CCSID	Coded character set ID	1-65535, *HEX, *JOB	Optional
RJTDFTRPY	Reject default reply	*NOALWRJT, *ALWRJT	Optional
KEYVAR	CL var for KEYVAR (4)	Character value	Optional
MSG	CL var for 1st level text	Character value	Optional
MSGLEN	CL var for MSGLEN (5 0)	Decimal number	Optional
SECLVL	CL var for 2nd level text	Character value	Optional
SECLVLLEN	CL var for SECLVLLEN (5 0)	Decimal number	Optional
MSGDTA	CL var for msg data	Not restricted	Optional
MSGDTALEN	CL var for MSGDTALEN (5 0)	Decimal number	Optional
MSGID	CL var for MSGID (7)	Character value	Optional
SEV	CL var for SEV (2 0)	Decimal number	Optional
SENDER	CL var for SENDER (80)	Character value	Optional
SENDERFMT	Sender format	*SHORT, *LONG	Optional
RTNTYPE	CL var for RTNTYPE (2)	Character value	Optional
ALROPT	CL var for ALROPT (9)	Character value	Optional
MSGF	CL var for MSGF (10)	Character value	Optional
MSGFLIB	CL var for MSGFLIB (10)	Character value	Optional
SNDMSGFLIB	CL var for SNDMSGFLIB (10)	Character value	Optional
TXTCCSID	CL var for text CCSID (5 0)	Decimal number	Optional
DTACCSID	CL var for data CCSID (5 0)	Decimal number	Optional

Top

Call stack entry message queue (PGMQ)

Specifies the call stack entry message queue from which a message is received. The call stack entry message queue can be the *EXT queue or it can be a message queue that is associated with a call stack entry for a program or an ILE procedure.

If values are specified for this parameter, specifying *PGMQ for the Message queue (MSGQ) parameter is allowed.

Single values

*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.

Element 1: Relationship

Element 1 of this parameter specifies whether the message queue is associated with the program or procedure identified by Element 2, 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 of this parameter.

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: Call stack entry identifier

The second element of this parameter has three elements. Element 1 specifies an OPM program or ILE procedure name or a special value. Element 2 specifies an ILE module name which is used as a qualifier for the value specified in element 1. Element 3 can specify either an OPM program name or an ILE program name or a service program name, depending on what is specified in element 1. Element 3 is also used as a qualifier for what is specified in element 1.

Element 1: Call stack entry

*

Specifies the OPM program or ILE procedure running this command.

name

Specify the name of the OPM program or ILE procedure used to identify the call stack entry.

If this element identifies an OPM program, the name specified can be a maximum of 10 characters. If this element identifies an ILE procedure, the name specified can be a maximum of 256 characters.

Nested procedure names can be specified by separating each procedure name with a colon (:). When specifying nested procedure names, the outermost procedure name is identified first, followed by its contained procedures. The innermost procedure name is identified last in the string.

Partial names of programs or procedures can be specified by placing three less-than symbols (<<<) at the beginning of the name or by placing three greater-than symbols (>>>) at the end of the name. If both the greater-than symbols and the less-than symbols are used, the program or procedure name specified is limited to 250 characters.

The system begins its search for the specified program or procedure name with the most recently called program or procedure.

When searching for a partial program or procedure name:

• The less-than symbols (<<<) are truncated when specified only at the beginning of a program or procedure name and the remaining character string is right-justified. The remaining characters in the specified string are compared to the current program or procedure on the call stack, starting with the last position of the program or procedure name and comparing backward.
• The greater-than symbols (>>>) are truncated when specified only at the end of a program or procedure name. The remaining characters in the specified string are compared to the current program or procedure on the call stack, starting with the first position of the program or procedure name.
• The less-than symbols (<<<) and the greater-than symbols (>>>) are truncated when both are specified for a program or procedure name. The remaining characters are used to scan and compare the entire length of the specified string with the current program or procedure on the call stack.

Element 2: Module

*NONE

No ILE module qualifier is provided.

name

Specify the ILE module name to be used to identify the message queue.

Element 3: Program

*NONE

No program qualifier is provided.

name

Specify the program name to be used to identify the message queue.

Message queue (MSGQ)

Specifies the message queue (not a program message queue) from which a message is to be received.

Single values

*PGMQ

The program message queue specified for the Call stack entry message queue (PGMQ) parameter is the only queue from which a message is received.

Qualifier 1: Message queue

name

Specify the name of the message queue from which a message is to be received. If a message queue name is specified, the Call stack entry message queue (PGMQ) parameter cannot be specified.

Qualifier 2: Library

*LIBL

All libraries in the library list for the current thread are searched until the first match is found.

*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, QGPL is used.

name

Specify the library where the message queue is located.

Message type (MSGTYPE)

Specifies the type of message received by this program.

*ANY

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

*NEXT

The message that follows the one specified for the Message key (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 specified for the Message key (MSGKEY) parameter is received.

*INFO

An informational message is received.

*INQ

An inquiry message is received.

*RPY

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

*FIRST

The first message currently on the message queue or program queue is received.

*COPY

A copy of an inquiry message that was previously sent is received by this program. The message queue specified for the Call stack entry message queue (PGMQ) parameter or the Message queue (MSGQ) parameter must be the same queue that was specified for the Message queue to get reply (RPYMSGQ) parameter when the INQ message was sent.

*COMP

A completion message is received. This type of message can only be received from a program message queue.

*DIAG

A diagnostic message is received. This type of message can only be received from a program message queue.

*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.

*RQS

A request message is received. This type of message can only be received from a program message queue.

*LAST

The last message currently on the message queue or program queue is received.

Message key (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 *NEXT is specified for the Message type (MSGTYPE) parameter. 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.

name

Specify the name of the CL variable that contains the message reference key of the message to be used by this receive function. The variable must be a character variable having a length of 4 characters.

Wait time (WAIT)

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

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.

*MAX

The program waits indefinitely for the arrival of the specified message.

number-of-seconds

Specifies the number of seconds that the program waits for the arrival of a message.

Remove message (RMV)

Specifies whether the message received by the program is removed from the message queue. For messages that are unhandled exceptions, this parameter also specifies whether the exception is to be handled. If *INQ is specified for the Message type (MSGTYPE) parameter, then *NO must also be specified for this parameter so a reply to the inquiry message can be sent, otherwise the default reply will be sent before the unanswered inquiry is removed.

*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 Message type (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).

Coded character set ID (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. See the Globalization information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter for a list of valid values. Only CCSID values that a job can be changed to are accepted.

For more information on the message handler and its use of CCSIDs, see the Globalization topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.

Reject default reply (RJTDFTRPY)

Removing an unanswered inquiry message causes the default reply to be sent to the inquiry message. This value indicates whether a reply handling exit program will be allowed to reject a default reply that is sent as a result of using this command. A reply handling exit program can be registered via the system registration facility for exit point QIBM_QMH_REPLY_INQ. This parameter is only applicable when *YES is specified for the RMV keyword.

*NOALWRJT

A reply handling exit program will not be allowed to reject a default reply.

*ALWRJT

A reply handling exit program will be allowed to reject a default reply. If an exit program rejects the reply, message CPD2476 (Reply rejected by a reply handling exit program) will be sent as a diagnostic message to the program using this command. The CPD2476 will be followed by a CPF2422 (Reply not valid) escape message that the program using this command should monitor for to handle and recover from error situations.

CL var for KEYVAR (4) (KEYVAR)

Specifies the name of the control language (CL) character variable, if any, that contains the message reference key identifying the message received by the program containing this 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 for 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.

CL var for 1st level text (MSG)

Specifies the name of the control language (CL) character variable, if any, that contains the message when it 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 message text is less than 132 characters in length.

CL var for MSGLEN (5 0) (MSGLEN)

Specifies the name of the control language (CL) decimal variable, if any, that contains the total length of the message text available to be received. The variable must be a decimal variable having a length of 5 positions.

CL var for 2nd level text (SECLVL)

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

CL var for SECLVLLEN (5 0) (SECLVLLEN)

Specifies the name of the control language (CL) decimal variable, if any, that contains the total length of the message help available to be received. The variable must be a decimal variable having a length of 5 positions.

CL var for msg data (MSGDTA)

Specifies the name of the control language (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.

CL var for MSGDTALEN (5 0) (MSGDTALEN)

Specifies the name of the control language (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.

CL var for MSGID (7) (MSGID)

Specifies the name of the control language (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, the message identifier is returned as blanks. The minimum length of the variable is 7 characters.

CL var for SEV (2 0) (SEV)

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

CL var for SENDER (80) (SENDER)

Specifies the name of the control language (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 must be a minimum of 80 characters. If the CL variable is longer than 80 characters, additional information will be returned. If SENDERFMT(*LONG) is specified, the variable must be a minimum of 720 characters.

Sender format (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 a minimum of 80 characters, If the CL variable is longer than 80 characters, additional information will be returned. Positions in the CL variable beyond the last returned field will be 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 program 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 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 6 characters are the microseconds
• The last 10 characters are the name of the user profile that the thread was running under when the message was sent, and is returned if the length of the CL variable is at least 87

*LONG

The long format of the sender information is returned. The long format is 720 characters, with the last 30 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 QMHRCVPM 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 all 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)
• The next 6 characters are the microseconds
• The last 10 characters are the name of the user profile that the thread was running under when the message was sent

CL var for RTNTYPE (2) (RTNTYPE)

Specifies the name of the control language (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

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, already checked for validity

23

Reply, message default used

24

Reply, system default used

25

Reply, from System Reply List

26

Reply, from exit program

CL var for ALROPT (9) (ALROPT)

Specifies the name of the control language (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.

CL var for MSGF (10) (MSGF)

Specifies the name of the control language (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 the send function, not the overriding message file. If an override was specified when sending the message, the same override should be used when receiving the message.

CL var for MSGFLIB (10) (MSGFLIB)

Specifies the name of the control language (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 of the library containing the message file of the stored message 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 the send function, 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.

CL var for SNDMSGFLIB (10) (SNDMSGFLIB)

Specifies the name of the control language (CL) variable, if any, used to return the message file library name used to send the message. If the message received is a stored message, the message file library name of the library containing the message file of the stored message is returned. If *LIBL was specified on the send command, this parameter would have the actual name of the library. If the received message is not a stored message, the message file library name is returned as blanks. If the received message is a stored message and the original message file is destroyed, the message file library name is returned as blanks. If the received message is not a stored message, this parameter is returned as blanks. The variable must be a character variable of 10 positions in length.

CL var for text CCSID (5 0) (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 the CCSID that the message description or the text for an immediate message is stored in, specify 65535 for the CCSID parameter, and the CCSID is returned in 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. The variable must be a decimal variable having a length of 5 positions.

CL var for data CCSID (5 0) (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 message data is returned. If there is no *CCHAR replacement data in the data, 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, a conversion error occurred. The variable must be a decimal variable having a length of 5 positions.

Examples

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

*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.

CPF2422

Reply not valid.

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.