DosReadQueue
Bindings: C, MASM
This call reads an element from a queue and removes it.
DosReadQueue (QueueHandle, Request, DataLength, DataAddress,
ElementCode, NoWait, ElemPriority, SemaphoreHandle)
QueueHandle (HQUEUE) - input
Handle of the queue to read from.
Request (PULONG) - output
Address of a data field that returns the following information.
The first word is the PID of the process that added the element to the
queue.
The second word is used for event encoding by the application. The
data in this word is the same as that furnished by the Request
parameter on the DosWriteQueue request for the corresponding queue
element.
DataLength (PUSHORT) - output
Address of the length of the data being received.
DataAddress (PULONG) - output
Address of the element being received from the queue.
ElementCode (USHORT) - input
Overrides the normal priority, FIFO-, or LIFO-read ordering. This
operand is used to identify a specific element that is to be read.
This field can be set to zero to read the first element in the queue,
or it can contain an identifier for a particular element, which was
returned to ElementCode by a DosPeekQueue request.
NoWait (UCHAR) - input
Action to be performed when no entries are found in the queue.
Value Definition
0 The requesting thread waits.
1 The requesting thread does not wait.
ElemPriority (PBYTE) - output
Address of the element's priority. This is the value that was
specified for ElemPriority by the DosWriteQueue call that added the
element to the queue. ElemPriority is a numeric value in the range of
0 to 15, with 15 being the highest priority.
SemaphoreHandle (HSEM) - input
Handle of the semaphore cleared when an element is written to the
queue and NoWait=0 is specified. If NoWait=1 is specified, this
parameter should be set to null.
The semaphore can be either a RAM or system semaphore. If the
semaphore is a RAM semaphore, it must be in a segment that is shared
between the process that owns the queue and any process that issues a
DosWriteQueue request to the queue.
If multiple threads are processing elements from the queue using
NoWait=0, the same semaphore must be provided on all DosPeekQueue or
DosReadQueue requests.
rc (USHORT) - return
Return code descriptions are:
0 NO_ERROR
330 ERROR_QUE_PROC_NOT_OWNED
333 ERROR_QUE_ELEMENT_NOT_EXIST
337 ERROR_QUE_INVALID_HANDLE
342 ERROR_QUE_EMPTY
433 ERROR_QUE_INVALID_WAIT
Remarks
A process that creates a queue with DosCreateQueue owns it. Only the
owning process and any threads it creates can issue DosReadQueue to
remove an element from the queue. If the queue is empty and NoWait = 0 is
specified, the thread waits for an element to be written to the queue. If
the queue is empty and NoWait = 1 is specified, the thread returns with
ERROR_QUE_EMPTY.
If ElementCode is set to zero, the elements in the queue are removed in
the order specified at the time of the queue's creation (FIFO, LIFO, or
priority).
ElementCode can also be set to a value returned by DosPeekQueue, which
uses ElementCode to return identifiers for successive queue elements.
The assigning of identifiers by DosPeekQueue to individual queue
elements allows the queue owner to examine a queue element with
DosPeekQueue and compare it with a queue element it has read.
The semaphore provided by SemaphoreHandle is typically used by a
DosMuxSemWait request to wait for an element to be written to a queue or
other events. If DosReadQueue is issued with NoWait=0, it clears the
semaphore indicated by SemaphoreHandle as soon as the element is read.
The Request, DataLength and DataAddress parameters contain data
understood by the thread adding the element to the queue and by the
thread that receives the queue element. There is no special meaning to
this data; applications may use these parameters for any purpose they
wish. OS/2 does not alter this data; it simply copies this data intact.
OS/2 does not validate the address of DataBuffer or the DataLength.
Created using Inf-PHP v.2 (c) 2003 Yuri Prokushev
Created using Inf-HTML v.0.9b (c) 1995 Peter Childs