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.