Application programs can use the Rexx Queue Interface to establish and manipulate named queues. Named queues prevent different Rexx programs that are running in a single session from interfering with each other. Named queues also allow Rexx programs running in different sessions to synchronize execution and pass data. These queuing services are entirely separate from the Windows InterProcess Communications queues.
The following sections explain the functions for creating and using named queues.
RexxCreateQueue creates a new (empty) queue.
retc = RexxCreateQueue(Buffer, BuffLen, RequestedName, DupFlag);
is the address of the buffer where the ASCII name of the created queue is returned.
is the size of the buffer.
is the address of an ASCII queue name. If no queue of that name exists, a queue is created with the requested name. If the name already exists, a queue is created, but Rexx assigns an arbitrary name to it. In addition, the DupFlag is set. The maximum length for a queue name is 1024 characters.
When RequestedName is null, Rexx provides a name for the created queue.
In all cases, the actual queue name is passed back to the caller.
is the duplicate name indicator. This flag is set when the requested name already exists.
Queue names must conform to the same syntax rules as Rexx variable names. Lowercase characters in queue names are translated to uppercase.
The queue name must be a valid Rexx symbol. However, there is no connection between queue names and variable names. A program can have a variable and a queue with the same name.
RexxDeleteQueue deletes a queue.
retc = RexxDeleteQueue(QueueName);
is the address of the ASCII name of the queue to be deleted.
If a queue is busy (for example, wait is active), it is not deleted.
RexxQueryQueue returns the number of entries remaining in the named queue.
retc = RexxQueryQueue(QueueName, Count);
is the address of the ASCII name of the queue to be queried.
is the number of entries in the queue.
RexxAddQueue adds an entry to a queue.
retc = RexxAddQueue(QueueName, EntryData, AddFlag);
is the address of the ASCII name of the queue to which data is to be added.
is the address of an RXSTRING containing the data to be added to the queue.
is the LIFO/FIFO flag. When AddFlag is RXQUEUE_LIFO, data is added LIFO (Last In, First Out) to the queue. When AddFlag is RXQUEUE_FIFO, data is added FIFO (First In, First Out).
| RXQUEUE_OK | 0 | The system queue function completed successfully. |
| RXQUEUE_BADQNAME | 5 | The queue name is not valid, or you tried to create or delete a queue named SESSION. |
| RXQUEUE_PRIORITY | 6 | The order flag is not equal to RXQUEUE_LIFO or RXQUEUE_FIFO. |
| RXQUEUE_NOTREG | 9 | The queue does not exist. |
| RXQUEUE_MEMFAIL | 12 | There is insufficient memory available to complete the request. |
RexxPullQueue removes the top entry from the queue and returns it to the caller.
retc = RexxPullQueue(QueueName, DataBuf, DateTime, WaitFlag);
is the address of the ASCII name of the queue from which data is to be pulled.
is the address of an RXSTRING for the returned value.
is the address of the entry's date and time stamp.
is the wait flag. When WaitFlag is RXQUEUE_NOWAIT and the queue is empty, RXQUEUE_EMPTY is returned. Otherwise, when WaitFlag is RXQUEUE_WAIT, Rexx waits until a queue entry is available and returns that entry to the caller.
| RXQUEUE_OK | 0 | The system queue function completed successfully. |
| RXQUEUE_BADQNAME | 5 | The queue name is not valid, or you tried to create or delete a queue named SESSION. |
| RXQUEUE_BADWAITFLAG | 7 | The wait flag is not equal to RXQUEUE_WAIT or RXQUEUE_NOWAIT. |
| RXQUEUE_EMPTY | 8 | Attempted to pull the item off the queue but it was empty. |
| RXQUEUE_NOTREG | 9 | The queue does not exist. |
| RXQUEUE_MEMFAIL | 12 | There is insufficient memory available to complete the request. |
The caller is responsible for freeing the returned memory that DataBuf points to.