DosReadQueue (OS/2 1.x)

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.

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.

Bindings

C

#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