DosPeekQueue
Bindings: C, MASM
This call retrieves an element from a queue without removing it from the
queue.
DosPeekQueue (QueueHandle, Request, DataLength, DataAddress,
ElementCode, NoWait, ElemPriority, SemaphoreHandle)
QueueHandle (HQUEUE) - input
Handle of the queue to read.
Request (PULONG) - output
Address of the data to be filled in with the following information.
Word Description
1 The PID of the process that added the element to the queue.
2 Used for event coding 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. The value of this data is understood by the client
thread and by the server thread. There is no special
meaning to this data and the operating system does not alter
the data.
DataLength (PUSHORT) - output
Address of the length of the received data.
DataAddress (PULONG) - output
Address of the element retrieved from the queue.
ElementCode (PUSHORT) - input/output
Address of the code that identifies the element to be read. This field
is set to:
Value Definition
0 Read the element at the beginning of the queue and return
the identifier of the next element.
<> 0 Read the element whose identifier is specified and return
the identifier of the next element.
NoWait (UCHAR) - input
Action to be performed when there are no entries on the queue, shown
below.
Value Definition
0 Requesting thread waits
1 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.
SemaphoreHandle (ULONG) - input
Handle of a semaphore to be cleared when the queue has data placed
into it and NoWait=0 is specified. If NoWait=1 is specified, this
parameter should be set to null.
The semaphore may be either a RAM or system semaphore. If this handle
is for a RAM semaphore, that semaphore must be in a segment 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 a
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 DosPeekQueue to
examine a queue element without removing it from the queue. If the queue
is empty and NoWait=0 is specified, the thread waits for an element to be
added to the queue. If the queue is empty and NoWait=1 is specified, the
thread returns with ERROR_QUE_EMPTY.
The ElementCode parameter returns an indicator for the element being
examined. To examine the first element in the queue, the queue owner
issues DosPeekQueue with ElementCode set to zero. To examine the next
element in the queue, the queue owner uses the value returned in
ElementCode as input for the next DosPeekQueue request, and so on. By
issuing successive peeks, the queue owner can select a queue element and
then remove it from the queue by specifying an ElementCode value with a
DosReadQueue request.
The semaphore provided by SemaphoreHandle is typically used with a
DosMuxSemWait request to wait for a queue or any of several other events.
If DosReadQueue is issued with NoWait=0, it clears the semaphore
indicated by SemaphoreHandle as soon as the element is peeked.
The Request, DataLength and DataBuffer 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