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.