DosReadQueue

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

  ---

  [Back: DosReadAsync]
  [Next: DosReallocHuge]