Queue Interface

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.

Queue Interface Functions

The following sections explain the functions for creating and using named queues.

RexxCreateQueue

RexxCreateQueue creates a new (empty) queue.

retc = RexxCreateQueue(Buffer, BuffLen, RequestedName, DupFlag);

Parameters

Buffer (char *) - input

is the address of the buffer where the ASCII name of the created queue is returned.

BuffLen (size_t) - input

is the size of the buffer.

RequestedName (const char *) - input

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.

DupFlag (size_t *) - output

is the duplicate name indicator. This flag is set when the requested name already exists.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_STORAGE 1The name buffer is not large enough for the queue name.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.

Remarks

Queue names must conform to the same syntax rules as Rexx variable names. Lowercase characters in queue names are translated to uppercase.

RexxOpenQueue

RexxOpenQueue creates a new (empty) queue if a queue by the given name does not already exist. In contrast to RexxCreateQueue, RexxOpenQueue will not create a differently named queue if the indicated queue name already exists.

retc = RexxOpenQueue(RequestedName, CreatedFlag);

Parameters

RequestedName (const char *) - input

is the address of an ASCII queue name. If no queue of that name exists, a queue is created with the requested name. and the CreatedFlag will be set to TRUE. If the name already exists, this will just return a succesful return code. The maximum length for a queue name is 1024 characters.

CreateFlag (size_t *) - output

indicates whether RexxOpenQueue created the indicated queue. If zero on return, then the named queue already existed.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_STORAGE 1The name buffer is not large enough for the queue name.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.

Remarks

Queue names must conform to the same syntax rules as Rexx variable names. Lowercase characters in queue names are translated to uppercase.

RexxDeleteQueue

RexxDeleteQueue deletes a queue.

retc = RexxDeleteQueue(QueueName);

Parameters

QueueName (const char *) - input

is the address of the ASCII name of the queue to be deleted.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.
RXQUEUE_NOTREG 9The queue does not exist.
RXQUEUE_ACCESS 10The queue cannot be deleted because it is busy.

Remarks

If a queue is busy (for example, wait is active), it is not deleted.

RexxQueueExists

RexxQueueExists tests if name queue exists.

retc = RexxQueueExists(QueueName);

Parameters

QueueName (const char *) - input

is the address of the ASCII name of the queue to be queried.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.
RXQUEUE_NOTREG 9The queue does not exist.

RexxQueryQueue

RexxQueryQueue returns the number of entries remaining in the named queue.

retc = RexxQueryQueue(QueueName, Count);

Parameters

QueueName (const char *) - input

is the address of the ASCII name of the queue to be queried.

Count (size_t *) - output

is the number of entries in the queue.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.
RXQUEUE_NOTREG 9The queue does not exist.

RexxAddQueue

RexxAddQueue adds an entry to a queue.

retc = RexxAddQueue(QueueName, EntryData, AddFlag);

Parameters

QueueName (const char *) - input

is the address of the ASCII name of the queue to which data is to be added.

EntryData (PCONSTRXSTRING) - input

is the address of a CONSTRXSTRING containing the data to be added to the queue.

AddFlag (size_t) - input

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).

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.
RXQUEUE_PRIORITY 6The order flag is not equal to RXQUEUE_LIFO or RXQUEUE_FIFO.
RXQUEUE_NOTREG 9The queue does not exist.
RXQUEUE_MEMFAIL 12There is insufficient memory available to complete the request.

RexxPullFromQueue

RexxPullFromQueue removes the top entry from the queue and returns it to the caller.

retc = RexxPullFromQueue(QueueName, DataBuf, DateTime, WaitFlag);

Parameters

QueueName (const char *) - input

is the address of the ASCII name of the queue from which data is to be pulled.

DataBuf (PRXSTRING) - output

is the address of an RXSTRING for the returned value.

DateTime (REXXDATETIME *) - output

is the address of the entry's date and time stamp. If the date and time stamp is not needed, DateTime may be NULL.

WaitFlag (size_t) - input

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.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.
RXQUEUE_BADWAITFLAG 7The wait flag is not equal to RXQUEUE_WAIT or RXQUEUE_NOWAIT.
RXQUEUE_EMPTY 8Attempted to pull the item off the queue but it was empty.
RXQUEUE_NOTREG 9The queue does not exist.
RXQUEUE_MEMFAIL 12There is insufficient memory available to complete the request.

RexxClearQueue

RexxClearQueue clears all entries from a named queue.

retc = RexxClearQueue(QueueName);

Parameters

QueueName (const char *) - input

is the address of the ASCII name of the queue to be cleared.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.
RXQUEUE_NOTREG 9The queue does not exist.

RexxPullQueue (Deprecated)

RexxPullQueue removes the top entry from the queue and returns it to the caller. RexxPullQueue is deprecated in favor of its more portable replacement RexxPullFromQueue.

retc = RexxPullQueue(QueueName, DataBuf, DateTime, WaitFlag);

Parameters

QueueName (const char *) - input

is the address of the ASCII name of the queue from which data is to be pulled.

DataBuf (PRXSTRING) - output

is the address of an RXSTRING for the returned value.

DateTime (PDATETIME) - output

is the address of the entry's date and time stamp.

WaitFlag (size_t) - input

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.

Return Codes

RXQUEUE_OK 0The system queue function completed successfully.
RXQUEUE_BADQNAME 5The queue name is not valid, or you tried to create or delete a queue named SESSION.
RXQUEUE_BADWAITFLAG 7The wait flag is not equal to RXQUEUE_WAIT or RXQUEUE_NOWAIT.
RXQUEUE_EMPTY 8Attempted to pull the item off the queue but it was empty.
RXQUEUE_NOTREG 9The queue does not exist.
RXQUEUE_MEMFAIL 12There is insufficient memory available to complete the request.

Remarks

The caller is responsible for freeing the returned memory that DataBuf points to.