DosPeekQueue (OS/2 1.x)

This call retrieves an element from a queue without removing it from the queue.

Syntax

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

Parameters

QueueHandle (HQUEUE) - input 

Handle of the queue to read.

Request (PULONG) - output 

Address of the data to be filled in with the following information.

1 - The PID of the process that added the element to the queue.

2 - Used for event coding 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. The value of this data is understood by the client thread and by the server thread. There is no special meaning to this data and the operating system does not alter the data. ;DataLength (PUSHORT) - output:Address of the length of the received data.

DataAddress (PULONG) - output 

Address of the element retrieved from the queue.

ElementCode (PUSHORT) - input/output 

Address of the code that identifies the element to be read. This field is set to:

0 - Read the element at the beginning of the queue and return the identifier of the next element.

<> 0 - Read the element whose identifier is specified and return the identifier of the next element.

NoWait (UCHAR) - input

Action to be performed when there are no entries on the queue, shown below.

0 - Requesting thread waits

1 - 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.

SemaphoreHandle (ULONG) - input 

Handle of a semaphore to be cleared when the queue has data placed into it and NoWait=0 is specified. If NoWait=1 is specified, this parameter should be set to null.

The semaphore may be either a RAM or system semaphore. If this handle is for a RAM semaphore, that semaphore must be in a segment 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 a 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 DosPeekQueue to examine a queue element without removing it from the queue. If the queue is empty and NoWait=0 is specified, the thread waits for an element to be added to the queue. If the queue is empty and NoWait=1 is specified, the thread returns with ERROR_QUE_EMPTY.

The ElementCode parameter returns an indicator for the element being examined. To examine the first element in the queue, the queue owner issues DosPeekQueue with ElementCode set to zero. To examine the next element in the queue, the queue owner uses the value returned in ElementCode as input for the next DosPeekQueue request, and so on. By issuing successive peeks, the queue owner can select a queue element and then remove it from the queue by specifying an ElementCode value with a DosReadQueue request.

The semaphore provided by SemaphoreHandle is typically used with a DosMuxSemWait request to wait for a queue or any of several other events. If DosReadQueue is issued with NoWait=0, it clears the semaphore indicated by SemaphoreHandle as soon as the element is peeked.

The Request, DataLength and DataBuffer 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 = DosPeekQueue(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) */
PUSHORT ElementCode;     /* Indicator of element received (returned) */
UCHAR   NoWait;          /* Indicate to not wait if queue is empty */
PBYTE   ElemPriority;    /* Priority of element (returned) */
ULONG   SemaphoreHandle; /* Semaphore Handle */

USHORT  rc;              /* return code */

MASM

EXTRN  DosPeekQueue: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     ;Indicator of element received (returned)
PUSH   OTHER   NoWait          ;Indicate to not wait if queue is empty
PUSH@  BYTE    ElemPriority    ;Priority of element (returned)
PUSH   DWORD   SemaphoreHandle ;Semaphore Handle
CALL   DosPeekQueue

Returns WORD