Visara Master Console Center Scripting Guide - Manual (Page 168)

Chapter 5 Script Commands
Scripting Guide 168
QREAD
Syntax:
QREAD( %QueueID, $MsgArray, %Wait[, $Filter]) ==> $MsgLine
Description:
Reads the next message from a message queue.
Action: The next message in the specified queue is read. The message is
defined by the current message pointer for the message queue created
by the QOPEN() command.
The entire “raw” message is returned as a string. The message source (the
name of the OS that the message came from) and the entire message are
placed in the normal string array specified by the $MsgArray parameter.
When the queue is empty, QREAD() acts as specified by the Wait
parameter.
Parameters:
%QueueID. Numeric expression. The message queue from which to read
the next message. This is the unique queue ID created by QOPEN().
$MsgArray. Normal string array. The array to populate with the
message source (the OS name from which the message came) and each
word from the message. The first array element contains the message
source. Each subsequent element contains a word from the message,
sequentially by position in the message. For example:
$MsgArray[ 1] contains the message source
$MsgArray[ 2] contains the first word of the message
$MsgArray[ 3] contains the second word of the message
$MsgArray[ 4] contains the third word of the message etc.
The length of the array (the number of elements) is determined by the
number of words in the message. The words are split by “white
space”—one or more space characters; SPLIT() works in the way, with
the split characters parameter not specified.
%Wait. Numeric expression. The number of seconds to wait before
timing out. When the queue is empty, this number specifies how long
the command waits for a message before returning a null string (“”).
$Filter. String expression. Optional. The text in this string acts as
filter criteria—the criteria text must be in the message in order for
QREAD() to receive it. Messages will only “appear” to QREAD() if
they contain the criteria text. A Filter value of null string “” is the
same as omitting the Filter parameter.
Returns:
String value. The complete original message.
Notes:
1. QREAD() only reads messages from printer console queues, queues
created with the QOPEN() command.
2. Although platforms such as Unix and AS/400 do not have
mainframe-style printer consoles, the MCC internally creates a
“printer console-like” facility for non-mainframe platforms. This
facility is a sequential message queue of the messages received
from the OS consoles. To the QREAD() command, this is the same
queue as created from the mainframe’s printer consoles.
For the message from the OS console to appear in the printer message
queue, the message must be completed with a newline or carriage
return first. For example, when logging into a Unix system, the user
is prompted with “login:”. This prompt is on the screen but not yet in