MSGQ_RECEIVE
This activity receives a message from a named message queue on the IBM i server. It is supported only on IBM i servers.
When the activity receives a message from the named message queue, a range of attributes of the message are available through the output parameters of the activity, including message text, message data, message identifier and sender information.
When no message is available to be received (after waiting for the interval specified by the MSGWAIT parameter, if used), the activity ends normally but the output parameters containing message attributes are not filled. The value of the RCVCOUNT output parameter may be used to determine whether a message was received.
Refer also to the companion MSGQ_SEND and WATCH_MSGQ activities that allow you to send a message to a named message queue or to iteratively wait on messages arriving at a message queue. Refer to IBM i documentation concerning message queues, message descriptions and message files for further information about the operating system features upon which this activity depends.
INPUT Parameters:
MSGQ : Required
This parameter must specify the name of the message queue from which the message is to be received.
MSGQLIB: Optional
This parameter may specify the name of the library containing the message queue. If not specified, a default of *LIBL is used which means the library list is used to locate the named message queue.
MSGPOS: Optional
You may specify this parameter to control which message is to be received from the message queue or to receive messages that are "old" (that is, messages that have previously been received without being removed).
The usual (and default) value, *NEW, specifies that the activity will receive a "new" message, that is one that has not been previously received (without being removed). When this value is specified (or assumed) the messages are received in FIFO (first-in, first-out) order.
Alternatively you may use the values *FIRST or *LAST to specify that the first or last message on the message queue is to be received. These values permit "old" messages to be received again, but will also receive "new" messages where applicable.
MSGWAIT: Optional
Specifies the length of time (in seconds) that the activity will wait for a message to arrive in the message queue if one is not immediately available when the activity is processed.
The default value is 0 (zero) which means that the activity does not wait for the arrival of a message if one is not immediately available when the activity is processed.
You may also specify the special value *MAX which means that the activity waits indefinitely for a message to arrive. You should understand that this value may cause the activity and hence the processing sequence in which it is contained to stall indefinitely if no message is sent to the message queue. Other than by the arrival of a message, such a processing sequence run may only be terminated by terminating the job, the subsystem in which the job is running or the system. If you wish a process to wait indefinitely for a message to arrive, the WATCH_MSGQ activity may provide a more suitable solution.
MSGRMV: Optional
Specifies whether the message received by the activity is removed from the message queue. The default is *YES, which means the message is removed. You may specify *NO to cause the message not to be removed from the message queue. If you do so, the system considers the message to be "old" and it will not be received again by this activity except by specifying *FIRST or *LAST for the MSGPOS parameter. If your processing sequence leaves "old" messages on the message queue, it is your responsibility to remove them by other means such as by executing the CLRMSGQ operating system command.
OUTPUT Parameters:
RCVCOUNT:
The received message count. If a message is received successfully, the value will be one (1). Otherwise the value will be zero (0). The activity ends normally when no message is available to receive after waiting for the interval specified by the MSGWAIT parameter.
RCVMSGSEV:
If a message is received, this parameter contains the severity code of the received message. Impromptu messages sent by the MSGQ_SEND activity will usually have a severity code of '00'. For pre-defined messages, the severity code is defined by the message description.
RCVMSGTYPE:
If a message is received, this parameter contains the message type of the received message. Messages sent by the MSGQ_SEND activity will have a message type of *INFO. For messages sent by other means, the message type is specified by the sending program.
RCVMSGID:
If a message is received, this parameter contains the message identifier of the received message. An impromptu message has no message identifier. Otherwise, this value identifies the message description in the message file identified by the RCVMSGF and RCVMSGFLIB parameters.
RCVMSGF:
If a message is received, this parameter contains the name of the message file of the received message. An impromptu message has no message file name. Otherwise, this value identifies the message file name containing the message description used to send the message.
RCVMSGFLIB:
If a message is received, this parameter contains the name of the library containing the message file, if any.
RCVMSGTXT:
If a message is received, this parameter contains the first level message text of the received message. For a pre-defined message, this includes the message data fields that were substituted for substitution variables in the text before the message was sent. A maximum of 256 characters of the first level text will be returned.
RCVSECLVL:
If a message is received, this parameter contains the second level message text of the received message, if any. An impromptu message has no second level message text. For a pre-defined message, this includes the message data fields that were substituted for substitution variables in the second level text before the message was sent. A maximum of 256 characters of the second level text will be returned.
RCVMSGDTA:
If a message is received, this parameter contains the message data field values of the received msg. An impromptu message has no message data. Otherwise this contains a single string of the message data values used to send the message. A maximum of 256 characters of message data will be returned.
SENDJOB:
If a message is received, this parameter contains the name of the job that sent the message.
SENDUSER:
If a message is received, this parameter contains the user name of the job that sent the message.
SENDJOBNBR:
If a message is received, this parameter contains the job number of the job that sent the message.
SENDDATE:
If a message is received, this parameter contains the date that the message was sent. The date is in ISO format - that is, CCYY-MM-DD.
SENDTIME:
If a message is received, this parameter contains the time that the message was sent. The time is in ISO format - that is, HH:MM:SS.