WATCH_MSGQ
This is an iterator activity. It will repeatedly attempt to receive a message from a named message queue on the IBM i server and on each iteration output the details of the message received, if any. It is supported only on IBM i servers.
The processing logic nested beneath the WATCH_MSGQ activity is repeated each time that a message is received or each time the specified wait time (MSGWAIT parameter) is exceeded (if no message is available to receive).
Upon each iteration in which 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 iterates 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. This behavior allows your solution to perform processing periodically whether a message is received or not. For example, your processing sequence might check the value of the *SHUTDOWN built-in variable in order to permit the long running process to be ended in a controlled fashion.
Refer also to the companion MSGQ_RECEIVE and MSGQ_SEND activities that allows you to send and receive single messages to or from a named 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.
Note: Unlike many other iterator activities, this activity will iterate indefinitely unless you take specific action in the iterator block to exit the iteration. It is designed to be used in a potentially long running processing sequence that perpetually waits on a message arriving at the specified message queue and then processes the message or initiates another processing sequence to process the message. For more information refer to Considerations for Extended Duration Processing Sequences .
INPUT Parameters:
MSGQ : Required
This parameter must specify the name of the message queue from which the messages are 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.
MSGWAIT: Optional
Specifies the length of time (in seconds) that the activity will wait, on each iteration, for a message to arrive in the message queue.
The default value is 20 (twenty) seconds. This default value has been chosen to be less than the default controlled end delay times used on IBM i system commands such as ENDJOB (End Job). You should consider also the corresponding delay times used with IBM i system commands such as ENDSBS (End Subsystem) or PWRDWNSYS (Power Down System). This enables your processing sequence to have the opportunity to check the value of the *SHUTDOWN built-in variable and end in a controlled fashion if one of those commands is issued.
You may specify the special value of 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. Instead the next iteration is performed immediately. Use of this value is not generally recommended with the WATCH_MSGQ activity as it may result in your long-running processing sequence being heavily CPU intensive, instead of simply entering an idle/wait state when it has no work to perform.
You may also specify the special value *MAX which means that the activity waits indefinitely for a message to arrive. Use of this value is not generally recommended with the WATCH_MSGQ activity as it will prevent any possibility of effecting controlled end of the processing sequence.
MSGRMV: Optional
Specifies whether each 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. 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. Upon each iteration, if data is received successfully, the value will be one (1). Otherwise the value will be zero (0).
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.