7.4.55. RXQUEUE


>>-RXQUEUE(-+-"Create"-+------------+-+-)----------------------><
            |          +-,queuename-+ |
            +-"Delete",queuename------+
            +-"Get"-------------------+
            +-"Set",newqueuename------+

Creates and deletes external data queues. It also sets and queries their names.

"Create"

creates a queue with the name queuename if you specify queuename and if no queue of that name exists already. You must not use SESSION as a queuename. If you specify no queuename, then the language processor provides a name. The name of the queue is returned in either case.

The maximum length of queuename can be 1024 characters.

Many queues can exist at the same time, and most systems have sufficient resources available to support several hundred queues at a time. If a queue with the specified name exists already, a queue is still created with a name assigned by the language processor. The assigned name is then returned to you.

"Delete"

deletes the named queue. It returns 0 if successful or a nonzero number if an error occurs. Possible return values are:

0: Queue has been deleted.
5: Not a valid queue name or tried to delete queue named "SESSION".
9: Specified queue does not exist.
10: Queue is busy; wait is active.
12: A memory failure has occurred.
1002: Failure in memory manager.

"Get"

returns the name of the queue currently in use.

"Set"

sets the name of the current queue to newqueuename and returns the previously active queue name.

The first parameter determines the function. Only the first character of the first parameter is significant. The parameter can be entered in any case. The syntax for a valid queue name is the same as for a valid Rexx symbol.

The second parameter specified for Create, Set, and Delete must follow the same syntax rules as the Rexx variable names. There is no connection, however, between queue names and variable names. A program can have a variable and a queue with the same name. The actual name of the queue is the uppercase value of the name requested.

Named queues prevent different Rexx programs that are running in a single session from interfering with each other. They allow Rexx programs running in different sessions to synchronize execution and pass data. LINEIN("QUEUE:") is especially useful because the calling program stops running until another program places a line on the queue.

Example 7.69. Builtin function RXQUEUE

/* default queue                                    */
rxqueue("Get")             -> "SESSION"
/* assuming FRED does not already exist             */
rxqueue("Create", "Fred")  -> "FRED"
/* assuming SESSION had been active                 */
rxqueue("Set", "Fred")     -> "SESSION"
/* assuming FRED exists                             */
rxqueue("delete", "Fred")  -> "0"