CA-GSS Statements and Commands › GSS Extended Functions › IO Functions › Number, String, and Variable Functions › System Information Functions › QUEUES()

QUEUES()

Use QUEUES() to add an entire stack to the bottom of any stack belonging to any IMOD.

Restriction

QUEUES() can specify a target stack external to an IMOD only when the target stack has been declared public for writing or for queuing.

Syntax

The QUEUES() function has this syntax:

QUEUES(source,[stack],[owner],,[postoption])

Arguments

The QUEUES() function takes these arguments:

source

Stack whose content is to be queued to the target stack.

Default: Current stack.

stack

Number of the stack to be referenced.

Default: If a local stack is referenced, the current stack (as set by the SWAPSTAK() function); otherwise, the value is set by the owning IMOD task using the PUBSTACK(DEFAULT) function.

owner

IMOD ID of the stack's owner (for external reference). This value can be obtained from the variable imod_id in the owning IMOD task. It is also the value returned by the SPAWN() function.

Default: Current IMOD task.

postoption

Wait option, which determines whether the owning IMOD waits for a record to appear on an external stack. Specify one of these values:

POST

Any outstanding wait is satisfied; the default.

NOPOST

An outstanding wait is not satisfied.

ONLYPOST

Any outstanding wait is satisfied, but a record is not placed on the stack.

Usage Notes

• The contents of the stack are transferred rather than copied.
• QUEUES() is preferred over QUEUE() when transferring more than one related record to an external stack. This prevents the possibility of the target IMOD processing a partial request.

Return Codes

The QUEUES() function produces these return codes:

101 - 105 ARG n MISSING OR INVALID

122 STACK NOT SPECIFIED AND NO DEFAULT

123 SPECIFIED STACK DOES NOT EXIST

125 SPECIFIED IMOD NOT FOUND

126 STACK WRITE FAILED

127 REQUESTED STACK DOES NOT EXIST

128 SPECIFIED IMOD/STACK NOT AUTHORIZED

129 SOURCE AND TARGET IDENTICAL

Example

x = queues(5)        /* Stack 5 is queued to the current stack */
x = queues(5,2)      /* Stack 5 is queued to local stack 2     */
x = queues(5,,453,,'post') /* Stack 5 is queued to IMOD 453's
                              default stack. Any outstanding 
                              wait will be marked complete.    */