DosReadQueue (OS/2 1.x)
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.
- 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
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.
#define INCL_DOSQUEUES USHORT rc = DosReadQueue(QueueHandle, Request, DataLength, DataAddress, ElementCode, NoWait, ElemPriority, SemaphoreHandle); HQUEUE QueueHandle; /* Queue handle */ PULONG Request; /* Request identification data (returned) */ PUSHORT DataLength; /* Length of element received (returned) */ PULONG DataAddress; /* Address of element received (returned) */ USHORT ElementCode; /* Indicate want a particular element */ UCHAR NoWait; /* Indicate to not wait if queue is empty */ PBYTE ElemPriority; /* Priority of element (returned) */ HSEM SemaphoreHandle; /* Semaphore handle */ USHORT rc; /* return code */
EXTRN DosReadQueue:FAR INCL_DOSQUEUES EQU 1 PUSH WORD QueueHandle ;Queue handle PUSH@ DWORD Request ;Request identification data (returned) PUSH@ WORD DataLength ;Length of element received (returned) PUSH@ DWORD DataAddress ;Address of element received (returned) PUSH WORD ElementCode ;Indicate want a particular element PUSH OTHER NoWait ;Indicate to not wait if queue is empty PUSH@ BYTE ElemPriority ;Priority of element (returned) PUSH DWORD SemaphoreHandle ;Semaphore handle CALL DosReadQueue Returns WORD