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

Chapter 5 Script Commands
Scripting Guide 164
QOPEN
Syntax:
QOPEN( [%ObjIdArray]) ==> %QueueID
Description:
Opens a new queue of OS printer console messages.
Action: Creates a new message queue in a script by creating a new current
message pointer. The current message pointer is set to the end of the
currently available messages—the next new message received will be
the first message in the script’s queue and therefore the next message
retrieved for processing. Messages from the printer console for each
OS ObjID specified in the array are placed in the queue represented by
the QueueID return value.
Parameters:
%ObjIdArray. Normal numeric array. Optional. An array of OS
ObjIDs for which to create a message queue. Refer to Object ID on
page 26 for more information. If not specified, a queue is created only
for the OS that the script is running on.
Returns:
Numeric value, as follows:
Value
Meaning
-1 An error occurred – see below.
Any other value The numeric ID of the newly created
queue pointer—a unique number used
for subsequent access to the queue in
the current script thread.
Use the manifest constant ERROR for clarity in your code (refer to
Manifest Constants on page 42 for more information).
Possible Errors
An invalid array of object IDs. All object IDs must be created by the
OBJID() command or the OBJIDARRAY() commands.
Notes:
1. The other queue commands utilize the queue id for their
operations.
2. QOPEN() only creates a queue for OS printer console messages. If
object IDs are specified, they must be object IDs for OSs. If object
IDs are not specified, the script must be executing on an OS icon.
3. The MCC has one large message queue that holds all of the
incoming printer console messages. The queue holds the most
recent 10,000 messages. The oldest message is discarded when a
new message is added (a circular message queue).
4. Each script can have multiple current message pointers into the
message queue. The message pointers are created with QOPEN(),
and advanced with QREAD() and QSKIP().
5. A queue ID is only valid within the script thread in which it was
created. It becomes invalid in another script when a new thread is
begun, such as with the START() command.
6. As with any array, the %ObjIdArray parameter can contain one or
more elements. Having multiple object IDs enables a QREAD()
command to automatically read the next message from any of the
OSs specified in the QOPEN() command. Refer to the QREAD()
command for more information.
7. The OS must have a valid printer defined. The Q series of