To use STOQ communications, a program must first declare a STOQ parameter block. A STOQ parameter block serves as a buffer for the data in a single send operation or receive operation. A program can reuse the same STOQ parameter block for successive operations, provided that the program reinitializes the data in the parameter block appropriately each time. The same STOQ parameter block can be reused even for operations that involve different STOQs.
It is not necessary for a program to explicitly create or link to a STOQ. Before each send or receive operation, the program simply stores the STOQ name in the appropriate portion of the STOQ parameter block. If the STOQ specified by a send operation does not yet exist, the system creates the STOQ at that point. Any process can thereafter access the same STOQ by specifying the same STOQ name for a send or receive operation.
The STOQ grows one message longer after each send operation. Each receive operation removes a message from the STOQ and decreases the length of the STOQ by one.
A STOQ can continue to exist even after the process or processes that sent messages to it have terminated. The messages placed in the STOQ by those processes remain in the STOQ until received by another process or processes. The STOQ itself continues to exist until the next halt/load, even if it no longer contains any messages and is not in use by any process.
An operator can use the WQ (Display STOQ Count) command in MARC to display the number of messages in a STOQ. An operator can also purge messages from a STOQ with the RQ (Remove STOQ Entries) command in MARC. For details, refer to “Operator Interfaces to CRCR and STOQ” later in this section.
While a STOQ can store multiple messages, memory constraints limit the possible size of a STOQ. If a process attempts to send a message to a STOQ that is full, the process is then suspended unless it has set the No Wait flag for the send operation.
Similarly, if the STOQ or subqueue specified for a receive operation is empty, the receiving process is suspended unless it has set the No Wait flag for the receive operation.
A program can use the events STOQ_INPUT or STOQ_OUTPUT to detect when a STOQ is ready for a send or receive operation. For details, refer to “Waiting for CRCR or STOQ Events” later in this section.
A receive operation can specify a partial subqueue name. Such an operation returns the first message whose subqueue name begins with that partial subqueue name. For example, a receive operation that specifies a subqueue named OPS could receive a message from subqueues named OPS, OPSCON, OPSREP, or OPSPOD.
