DosPeekQueue

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:
• 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.

  ---

  [Back: DosPeekNmPipe]
  [Next: DosPFSActivate]