DosPeekQueue (OS/2 1.x)

From EDM2
Jump to: navigation, search

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


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


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


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.




USHORT  rc = DosPeekQueue(QueueHandle, Request, DataLength, DataAddress,
                          ElementCode, NoWait, ElemPriority,

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


EXTRN  DosPeekQueue:FAR

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