DosReadQueue (OS/2 1.x)

Legacy Function Warning
It is recommended to use a newer replacement for this function.
Replacement:
Remarks:	This page list the older version of the function for reference.

This call reads an element from a queue and removes it.

Syntax

DosReadQueue (QueueHandle, Request, DataLength, DataAddress, ElementCode,
              NoWait, ElemPriority, SemaphoreHandle)

Parameters

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.

Return Code

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.

Example Code

C Binding

#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 */

MASM Binding

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

Related Functions